Ajout et revendication d’appareils

Il existe plusieurs façons d’ajouter un appareil à votre organisation. Cette page couvre les trois que vous utilisez le plus : ajouter un appareil manuellement, laisser les appareils s’enregistrer eux-mêmes avec la clé de provisionnement du profil, et revendiquer un appareil sous licence. Pour les fichiers contenant de nombreux appareils, voir Importer des appareils en masse ; pour les capteurs LoRaWAN, voir Ajouter un appareil OTAA.

Le volet Nouvel appareil

Ouvrez Appareils et sélectionnez Nouvel appareil. Lorsque votre organisation dispose de plusieurs méthodes, le volet affiche Que ajoutez-vous ? :

Un choix n’apparaît que si son module est activé et que vous disposez de ses permissions. Choisir une autre méthode revient à la liste.

Ajouter un appareil manuellement

1. Dans le volet, choisissez Autre appareil.
2. Saisissez un Nom (unique dans votre organisation, 128 caractères maximum), un Libellé facultatif, et choisissez le Profil d’appareil (Le profil par défaut si vous n’en choisissez aucun).
3. Activez Cet appareil est une passerelle uniquement pour un appareil qui transmet des données pour d’autres appareils.
4. Sélectionnez Créer l’appareil.
5. Copiez le jeton d’accès maintenant : il n’est affiché qu’une seule fois. Sélectionnez Je l’ai enregistré une fois terminé, ou Ouvrir l’appareil.

Les paramètres d’appareils de votre organisation déterminent si un nouvel appareil reçoit immédiatement un jeton d’accès : Émettre un jeton d’accès pour les nouveaux appareils (activé par défaut ; Appareils > ⋯ > Paramètres). Si vos appareils utilisent MQTT basic ou X.509, désactivez-le : l’appareil est alors créé sans identifiant et vous en définissez un via l’API. Voir Identifiants des appareils.

Auto-provisionnement avec une clé de provisionnement

L’appareil connaît la clé de provisionnement et le secret de son profil. Au premier démarrage, il demande à Hermetry son propre identifiant, si bien que vous n’avez pas à créer chaque appareil au préalable.

Configurer le profil

1. Ouvrez le profil et son onglet Provisionnement.
2. Choisissez la Stratégie de provisionnement :

1. Enregistrez, puis sélectionnez Créer une clé dans Clés de provisionnement. Copiez le secret : « Copiez le secret maintenant. Vous ne le verrez plus. » Sélectionnez Je l’ai copié.

Le tableau des clés affiche chaque Identifiant de clé, son État (En usage, Ancienne, encore acceptée, Révoquée), Créée le, Acceptée jusqu’au et Dernière utilisation. Les boutons des clés agissent immédiatement ; ils ne font pas partie de Enregistrer les modifications.

Ce que l’appareil envoie

Connectez-vous en TLS avec le nom d’utilisateur provision et un mot de passe vide, abonnez-vous à v1/provision/res, puis publiez sur v1/provision/req :

{"deviceName": "boiler-07", "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60", "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"}

La réponse sur v1/provision/res :

{"status": "SUCCESS", "credentialsType": "ACCESS_TOKEN", "credentialsValue": "aZ3…"}

L’appareil se connecte ensuite avec son nouvel identifiant. En HTTPS, envoyez le même corps à POST /api/v1/provision sans en-tête bearer ; un refus répond également 200, avec "status": "FAILURE".

Limites : provisionnements réussis par clé et par heure (60 par défaut), 5 requêtes par nom d’appareil et par heure, et 10 requêtes par adresse source et par minute.

Remplacer ou révoquer une clé

• Remplacer la clé crée une nouvelle clé et un nouveau secret. L’ancienne clé reste acceptée pendant Jours de fonctionnement de l’ancienne clé (30 par défaut, de 0 à 365 ; 0 l’arrête immédiatement), puis elle est révoquée automatiquement. Les appareils que vous configurez à partir de maintenant ont besoin de la nouvelle clé.
• Révoquer arrête une clé immédiatement et définitivement. Vous saisissez l’identifiant de la clé et indiquez un motif (« Par exemple : le secret a été partagé par erreur. »). Les appareils déjà enregistrés continuent de fonctionner.

Revendiquer un appareil sous licence

Les routeurs, passerelles et contrôleurs sous licence sortent d’usine avec leur propre identité : un numéro de série, un certificat et un secret de revendication. Avant que vous le revendiquiez, il n’appartient à aucune organisation, et Hermetry rejette ses données.

Le revendiquer

1. Connectez-vous au panneau local de l’appareil et ouvrez sa page Cloud. Activez la connexion cloud si elle est désactivée ; l’appareil se connecte alors à Hermetry de lui-même.
2. Appuyez sur Ouvrir la fenêtre de revendication sur la même page. La fenêtre reste ouverte pendant 15 minutes.
3. Dans Hermetry, ouvrez Appareils > Nouvel appareil et choisissez le choix d’appareil sous licence.
4. Choisissez la façon de saisir le code :
   • Scanner le code affiché à l’écran de l’appareil : pointez la caméra de votre téléphone sur le QR code de la page Cloud et copiez le texte affiché dans le champ.
   • Saisir le numéro de série et le code : saisissez le Numéro de série (de 6 à 32 lettres, chiffres et tirets, par exemple RT420-2610-000123) et le Code de revendication (20 caractères, par exemple 7KQ2-M9XH-D4TB-6WRA-1NZC).
5. Sélectionnez Vérifier. Sur Prêt à ajouter, saisissez un Nom d’appareil (vide = le numéro de série).
6. Sélectionnez Ajouter l’appareil. « L’appareil a été ajouté. Il se connecte en quelques secondes lorsqu’il est en ligne. »

L’appareil est ajouté avec une copie du profil de son modèle et son identifiant par certificat X.509. Sa connexion redémarre au sein de votre organisation.

Lorsqu’une revendication échoue

Revendication par API

{
    "serial": "RT420-2610-000123",
    "secret": "7KQ2M9XHD4TB6WRA1NZC",
    "name": "Pump house router"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
  -H 'Content-Type: application/json' \
  -d '{"serial":"RT420-2610-000123","secret":"7KQ2M9XHD4TB6WRA1NZC","name":"Pump house router"}'

{
    "status": "claimed",
    "serial": "RT420-2610-000123",
    "deviceId": "…",
    "model": "…",
    "profileId": "…"
}

{
    "status": "claimable",
    "serial": "RT420-2610-000123",
    "model": "…",
    "type": "…",
    "hw": "…"
}

{
    "message": "The serial or claim code is not correct.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "bad_secret"
    }
}

{
    "message": "…",
    "code": "FEATURE_NOT_AVAILABLE",
    "details": {
        "reason": "device_limit"
    }
}

{
    "message": "Open the claim window on the device's Cloud page (it stays open for 15 minutes), then try again.",
    "code": "CONFLICT",
    "details": {
        "reason": "press_claim_button"
    }
}

{
    "message": "…",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "rate_limited"
    }
}

La réponse 200 avec "status": "claimable" correspond à un essai à blanc. Une revendication d’un appareil déjà possédé par votre organisation répond 200 avec "status": "claimed" et "alreadyOwned": true. Une revendication encore en cours répond {"status": "in_progress", "serial": "…"}. 409 avec not_claimable signifie que le numéro de série est inconnu, retiré ou possédé par un autre compte.

L’onglet Propriété et la libération d’un appareil

L’onglet Propriété d’un appareil revendiqué affiche son numéro de série, son modèle, son certificat (valable jusqu’au) et la date à laquelle il a été ajouté à ce compte. Un appareil créé dans votre compte plutôt que revendiqué indique Pas un appareil d’usine.

Pour transférer un appareil sous licence à un autre propriétaire, sélectionnez Libérer l’appareil dans l’onglet Propriété. La boîte de dialogue Libérer cet appareil ? explique :

• L’appareil quitte ce compte et sa connexion est fermée.
• Ses données restent dans l’historique de ce compte.
• Le prochain propriétaire doit avoir un accès physique à l’appareil pour l’ajouter.
• Une réinitialisation d’usine de l’appareil ne le libère pas : seule cette action le fait.

Saisissez le numéro de série pour confirmer et indiquez un motif facultatif. L’appareil retourne dans le pool d’usine.

Un appareil peut aussi être libéré avec le bouton Libérer sur sa propre page Cloud. Vous recevez alors un avis « Un appareil s’est libéré de votre compte ». Si personne dans votre équipe n’a fait cette action, contactez le support.

Voir aussi

• Appareils sous licence
• Sécurité de l’identité et de la revendication des appareils
• La liste des appareils et la page d’un appareil