Connecter votre premier appareil

Cette page connecte un appareil qui se connecte avec un jeton d’accès. Cela prend environ cinq minutes. Vous pouvez utiliser l’appareil réel, ou un ordinateur doté d’un client MQTT ou de curl qui le remplace. Pour les capteurs LoRaWAN, suivez plutôt Connecter votre premier capteur LoRaWAN ; pour les appareils sous licence, consultez Ajouter et revendiquer des appareils.

De quoi avez-vous besoin

• Le rôle Admin ou Owner (autorisation de créer des appareils et de gérer leurs identifiants).
• Un client MQTT 3.1.1 avec TLS, ou curl. Les exemples utilisent mosquitto_pub, le client que la page de l’appareil affiche également.
• Accès sortant au port TCP 8883 (MQTT sur TLS) ou 443 (HTTPS).

1. Ajouter l’appareil

1. Ouvrez Devices dans le menu IoT.
2. Sélectionnez New device. Le panneau demande What are you adding? lorsque plusieurs options sont proposées ; choisissez Other device (« Any other device: give it a name and a profile, and it gets an access token. »).
3. Remplissez le formulaire :

Champ	Quoi saisir
Name	Un nom unique dans votre organisation, par exemple boiler-07. Obligatoire, jusqu’à 128 caractères.
Label	Texte libre facultatif, par exemple Boiler room, north.
Device profile	Conservez The default profile pour l’instant. Vous pourrez changer le profil de l’appareil plus tard.
This device is a gateway	Laissez désactivé. Activez-le uniquement pour un appareil qui transmet les données d’autres appareils.

1. Sélectionnez Create device.

Le panneau affiche New secret: Copy it now: it is shown once and cannot be read back. avec le Access token de l’appareil, et une carte Connection details qui contient déjà le jeton dans ses lignes d’exemple.

Si aucun jeton n’apparaît, votre organisation a désactivé Issue an access token for new devices (Devices > ⋯ > Settings). L’appareil est alors créé sans identifiant ; voir Device credentials.

2. Lire les détails de connexion

La carte Connection details répertorie :

Élément	Signification
MQTT broker	L’hôte et le port auxquels l’appareil se connecte.
Security	TLS (mqtts): the server certificate is a public one, ou MQTT simple lorsque le profil l’autorise.
Login	Username = the access token, password empty, any client ID
Telemetry topic et Attributes topic	Où l’appareil publie.
Commands (subscribe)	Où l’appareil écoute les commandes.
HTTPS telemetry et Header	L’adresse et l’en-tête pour les appareils qui utilisent HTTPS à la place.
Example message (JSON), Send it with mosquitto_pub, Send it with curl	Lignes que vous pouvez copier et exécuter.

Plus tard, les administrateurs retrouvent la même carte dans l’onglet Credentials de l’appareil (avec un espace réservé à la place du jeton).

3. Envoyer un message via MQTT

Connectez-vous avec le jeton comme nom d’utilisateur et un mot de passe vide, puis publiez un objet JSON sur v1/telemetry avec QoS 1 :

mosquitto_pub -h <broker host> -p 8883 \
  --capath /etc/ssl/certs \
  -u "<ACCESS_TOKEN>" \
  -i boiler-07 \
  -q 1 \
  -t v1/telemetry \
  -m '{"temperature": 21.5, "humidity": 40}'

• Utilisez le nom d’hôte affiché sur la carte. TLS nécessite le nom, pas une adresse IP.
• L’identifiant client peut comporter de 1 à 64 caractères parmi A–Z a–z 0–9 . _ : -.
• Hermetry stocke chaque clé comme une série distincte et horodate les valeurs avec l’heure de leur réception.

3b. Ou envoyer via HTTPS

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Une réponse 200 avec un corps vide signifie que le message a été accepté. Voir Device HTTP API.

4. Vérifier son arrivée

1. Ouvrez Devices et sélectionnez le nom de l’appareil.
2. La colonne Connection et l’en-tête de l’appareil affichent Online tant qu’une session MQTT est ouverte (selon la règle Live connection du profil par défaut). Un appareil HTTP seul sous cette règle n’apparaît jamais en ligne ; voir Connection status and activity.
3. Ouvrez l’onglet Telemetry. Le tableau Latest values répertorie temperature et humidity avec leur heure.
4. Cochez une clé numérique et utilisez Chart pour voir son évolution sur la période allant de Last hour à Last 7 days.

Envoyez quelques messages supplémentaires avec d’autres valeurs pour voir le graphique évoluer.

Si rien n’arrive

Symptôme	Cause probable
Le client affiche « bad username or password » (CONNACK 4).	Le jeton est erroné ou il a été renouvelé.
Le client affiche « not authorised » (CONNACK 5).	L’appareil est désactivé, ou le profil n’autorise pas ce type de connexion ou ce réseau, ou exige TLS. La raison est inscrite dans l’onglet Log de l’appareil.
La connexion sur le port 1883 est refusée.	Le profil exige TLS. Utilisez le port 8883.
La négociation TLS échoue.	Vous vous êtes connecté par adresse IP, ou votre client n’a pas de bundle CA. Utilisez le nom d’hôte et le magasin CA du système.
HTTP répond 401.	L’en-tête Authorization: Bearer est absent ou le jeton est erroné.
L’appareil apparaît en ligne mais aucune valeur ne s’affiche.	La charge utile n’est pas un objet JSON, ou une clé ne respecte pas les règles de nommage (par exemple elle commence par _ ou fw_). Voir MQTT topics and payload reference.

D’autres causes sont listées dans A device does not connect et Data does not arrive.

Ce que vous avez fait

• Vous avez créé un appareil sur le profil par défaut, qui exige TLS et accepte les jetons d’accès.
• L’appareil s’est connecté avec son jeton et a publié des données de télémétrie.
• Chaque message compte dans le quota mensuel de messages de votre organisation. Voir Message quota and usage.

Étape suivante

Créer votre premier tableau de bord.