# Connecteurs

> Comment votre hub joint Home Assistant, Music Assistant et d'autres services chez vous par une connexion que votre domicile ouvre, et ce qu'elle peut faire.

Source: https://docs.thalovant.com/fr/concepts/connectors/

---
Un **connecteur** est la façon dont votre hub joint un service de votre domicile : Home Assistant pour les lumières et les serrures, Music Assistant pour la musique. Un hub dans le nuage ne peut pas ouvrir de porte sur votre réseau, alors c'est votre domicile qui l'ouvre. Un petit programme ou une intégration chez vous se connecte vers le hub, attend, et fait ce que le hub demande. Rien n'est ouvert sur votre routeur.

Ce que le hub a le droit de demander est écrit une seule fois, sous la forme d'une courte liste de verbes pour chaque service : jouer, mettre en pause, régler le volume, éteindre. Le routeur du hub refuse tout ce qui n'est pas dans la liste, envoie le reste chez vous et chez personne d'autre, puis vérifie la réponse au retour. Cette page explique ces règles et où elles s'arrêtent.

## Ce Qui Existe Aujourd'hui

| Service | Comment il atteint votre domicile | Où il en est |
| --- | --- | --- |
| Home Assistant | Le [lien Home Assistant](/fr/manage/home-assistant/), une intégration que vous installez depuis HACS. | Disponible. La version 0.5.0 transmet vos phrases à Assist, porte les actions structurées et porte les demandes Music Assistant ; la musique demande la version 0.5.0 ou ultérieure. |
| Music Assistant | Le lien Home Assistant, les [médias de la maison](/fr/music-and-home/home-media/), ou un pont domestique que vous faites tourner vous-même. | Voir [Par Home Assistant](/fr/music-and-home/music-through-home-assistant/) et [Sans Home Assistant](/fr/music-and-home/music-assistant-without-home-assistant/). Le programme du pont n'est pas encore publié. |
| Jellyfin | Les [médias de la maison](/fr/music-and-home/home-media/) ou un pont domestique. | La [compétence Média](/fr/concepts/media/) peut aussi appeler directement votre serveur, sur un hub à vous. |
| Plex | Pas par un connecteur. | La compétence Média appelle directement votre serveur. La plateforme n'a pas encore de verbes pour Plex. |

Si vous utilisez Home Assistant, servez-vous de son lien : il porte les mêmes demandes Music Assistant que le pont. Si vous n'utilisez que Music Assistant ou Jellyfin, activez les médias de la maison à la voix sur un appareil, ou faites tourner le pont vous-même.

## Comment Une Demande Arrive

1. **Le hub établit qui a parlé.** Il lit son propre enregistrement de la connexion : le compte Thalovant auquel l'appareil appartient et le nom que la plateforme lui a donné. Il ne croit jamais ce qu'un appareil dit de lui-même.
2. **La compétence fait une seule demande structurée.** « Joue Adam's Song dans la cuisine » devient un service, un verbe (jouer) et ses arguments (un titre, un nom d'enceinte).
3. **Le routeur la compare aux verbes fixes du service.** Un verbe ou un argument absent de la liste est refusé et rien n'est envoyé. La compétence vous dit qu'elle n'a pas pu.
4. **Elle va à la connexion de votre compte vers ce service.** Une connexion, une seule livraison. Jamais chez un autre foyer.
5. **Votre domicile s'en charge.** Le pont interroge Music Assistant. L'intégration Home Assistant interroge Home Assistant.
6. **La réponse revient et est vérifiée de nouveau.** C'est un court code et quelques mots simples, comme un titre ou un nom d'enceinte. La compétence la dit dans la langue de la personne.

Home Assistant se distingue sur deux points. Sa demande transporte aussi les mots que vous avez dits, parce qu'Assist lit des phrases. Et sa réponse est du texte libre, que le routeur nettoie de tout balisage et coupe à une longueur qui se prononce (600 caractères, sauf réglage contraire du hub) avant que l'enceinte la dise.

## La Connexion Ne Fait Que Sortir

Le pont ou l'intégration ouvre la connexion vers le hub et la garde ouverte. Il n'y a aucun port à rediriger, aucun tunnel et aucune adresse publique.

Une connexion de connecteur n'est pas un appareil. Elle ne peut envoyer qu'une chose, la réponse à une demande, et le hub refuse tout le reste : pas de phrases, pas d'audio, pas de demandes de sa part. Personne d'autre ne peut non plus envoyer de messages de connecteur, de sorte qu'un appareil ne peut rien demander à votre Home Assistant. La seule exception est un appareil à vous sur lequel les [médias de la maison](/fr/music-and-home/home-media/) sont activés : il répond pour votre foyer sur la connexion qu'il a déjà, seulement pour Music Assistant et Jellyfin, et seulement à une demande que le hub lui a envoyée. Cette connexion n'a pas d'identifiant MQTT et ne compte pas dans les connexions de votre forfait. Seul le compte qui la possède peut la créer et télécharger son fichier d'identité. Un hub pour enfants ne peut pas accueillir de connexion de pont domestique.

## Ce Que Vérifie Le Routeur

- **Votre foyer seulement.** Le routeur trouve le compte propriétaire de l'appareil qui a parlé et choisit la connexion de ce compte la plus récemment connectée pour le service. Une réponse ne compte qu'une fois, de cette connexion, dans les temps. Une demande n'est jamais diffusée à plusieurs.
- **Un ensemble fixe de verbes.** Chaque service a une liste fermée, et chaque verbe a des arguments de types et de tailles définis. Il n'y a ni adresse brute ni commande libre. La musique est un nom cherché dans votre bibliothèque.
- **Les noms sont des mots.** Un nom dans une demande ne peut pas contenir `<`, `>` ni `://`. Un titre qui contient `<3` est refusé comme demande, puis nettoyé quand il revient dans une réponse.
- **Les réponses sont reconstruites.** Pour Music Assistant, le service répond par un code d'une liste fermée, et votre compétence dit sa propre phrase. Un service ne peut pas mettre ses mots, ni aucun balisage, dans vos enceintes.
- **Les inconnus ne peuvent rien demander.** Un pont d'aperçu ou de messagerie sur un hub public est partagé par des gens qui ne sont pas titulaires du compte : il ne peut joindre le domicile de personne. Un type de connexion que le routeur ne connaît pas non plus.
- **Des plafonds.** Chaque foyer a quelques demandes en cours et un plafond par minute pour chaque catégorie de demande : modifier quelque chose, lire quelque chose, et les demandes sensibles décrites plus bas. Chaque service a aussi un plafond pour l'ensemble du hub. Une demande qui dépasse le plafond est refusée comme occupée. Les chiffres sont dans la spécification du connecteur et peuvent changer.

## Ce Qui Reste Chez Vous

Chaque demande transporte le service, le verbe et ses arguments, la langue, ainsi que le numéro et le nom de l'appareil qui a parlé. Home Assistant reçoit aussi les mots que vous avez dits.

Une demande ne transporte ni audio, ni détails de votre compte, ni votre position, ni rien d'autre de ce que vous avez dit au hub, ni, pour Music Assistant, la phrase elle-même.

Les jetons des services restent chez vous. Le pont garde votre jeton Music Assistant dans un fichier sur son propre ordinateur et refuse de démarrer si d'autres personnes peuvent lire ce fichier. Home Assistant garde ses propres identifiants. Votre bibliothèque, les messages d'erreur du service et ses adresses ne retournent jamais au hub : la réponse est un code et quelques mots.

La voie directe est différente. Si vous saisissez l'adresse et le jeton du serveur dans la compétence Music Assistant, ou dans la compétence Médias, le jeton est stocké comme secret de la compétence sur le hub. Préférez le pont ou le lien Home Assistant quand le hub n'est pas sur votre réseau.

Le hub voit bien chaque demande et sa réponse, puisque c'est lui qui les prononce. Sur un hub auto-hébergé, c'est votre machine.

## Actions Sensibles

Verrouiller, déverrouiller, armer et désarmer sont des actions sensibles. Le routeur leur donne leur propre plafond par minute, plus bas.

L'intégration Home Assistant est plus stricte. Avec **Autoriser serrures, alarmes, portes de garage, portails, vannes et sirènes** désactivé, ce qui est le réglage par défaut, elle n'exécute pas ces actions comme actions structurées. La phrase va à Assist sous forme de mots, et les règles d'exposition propres à Home Assistant décident. Une fois l'option activée, une action sensible n'est exécutée que si :

- l'entité est exposée à Assist ;
- l'action désigne exactement une entité. « Déverrouille la cuisine » ne déverrouille pas toutes les serrures de la cuisine, et « éteins toutes les automatisations » ne désactive pas vos automatisations.

Pour désarmer un panneau d'alarme à la voix, l'intégration a besoin du code d'alarme. Elle le garde dans ses propres options, le hub ne l'envoie jamais, et les diagnostics de l'intégration le masquent.

L'intégration traite aussi les sirènes, les vannes et les ouvrants de type garage, portail, porte et fenêtre comme sensibles. Le plafond distinct du routeur ne couvre que verrouiller, déverrouiller, armer et désarmer.

## Quels Appareils Peuvent Utiliser Une Compétence

Une compétence vit dans le runtime de votre hub avec un seul jeu de réglages pour tous ceux qui parlent à ce hub. Sur un hub public, cela inclut des inconnus : les règles diffèrent donc selon le chemin.

- **Lien Home Assistant et pont domestique.** Chaque foyer joint son propre lien et celui de personne d'autre : ce sont les chemins d'un hub que d'autres utilisent. Un appareil qui n'est pas à vous n'atteint jamais votre domicile.
- **Adresse du serveur dans les réglages de la compétence** (le chemin par adresse du serveur de Music Assistant, et la compétence Média). Une adresse et un jeton servent tous les appareils du hub. Un hub public refuse ces réglages, et un hub qui les a ne peut pas devenir public. Seuls les appareils de **Appareils autorisés** peuvent les utiliser, et une liste vide ne laisse entrer personne.

Une compétence apprend qui parle par l'estampille du routeur sur la phrase, jamais par le texte de la connexion elle-même. Sans estampille, elle refuse. Un appareil non autorisé n'obtient rien, pas même une erreur : la compétence rend la phrase, en silence, pour que d'autres compétences y répondent, et ne contacte jamais votre serveur. Un appareil est listé par le nom que la console affiche (`client-…`) ou par son identifiant.

## Là Où Ça S'arrête

- Un connecteur peut dire une chose fausse. La spécification limite ce qu'un service peut dire, pas si c'est vrai. Un pont qui annonce « lecture en cours » alors que rien ne joue est un pont défaillant. Il ne peut toucher que son propre foyer.
- Les compétences que vous ajoutez sont crues sur parole. Toute compétence de l'environnement d'exécution de votre hub peut demander un verbe au routeur au nom de l'appareil qui a parlé. Le routeur ne vérifie pas encore quelle compétence a demandé.
- Sur le chemin par adresse du serveur, la compétence appelle l'adresse que vous lui donnez depuis l'environnement d'exécution de votre hub. Ce que cet environnement peut atteindre dans le réseau de Thalovant est limité par sa politique réseau, pas par la compétence. Les deux compétences refusent les adresses de lien-local et de métadonnées ainsi que les noms de cluster.
- Tous les hubs ne peuvent pas accueillir un pont ou les médias de la maison. Un hub pour enfants refuse un pont domestique, comme un hub qui monte en charge ou qui n'a pas de routeur.

## Pour Aller Plus Loin

- [Lier Home Assistant](/fr/manage/home-assistant/) couvre l'intégration, ce que la compétence Maison atteint et l'installation depuis HACS.
- [Music Assistant](/fr/concepts/music-assistant/) couvre ce que vous pouvez dire et les chemins vers votre serveur.
- [Médias](/fr/concepts/media/) couvre Jellyfin et Plex.
- [Connexions](/fr/concepts/clients/) explique les connexions et leurs états.
