DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Auto-provisionnement

Avec l'auto-provisionnement, l'appareil s'enregistre lui-même dans un registre au premier démarrage, à l'aide du jeton de provisionnement du registre. Cette page vous explique comment obtenir le fichier de jeton, générer la clé de l'appareil et appeler la Devices API.

Cycle de vie de l'appareil : l'appareil s'auto-provisionne une seule fois, puis se connecte au broker MQTT

Avant de commencer

1. Télécharger le fichier de jeton du registre

Dans le Hub, ouvrez le tableau de bord du registre et sélectionnez Download Token file. Le Hub enregistre <registry-name>_token.json :

{
  "server_url": "https://devices.fundamentum-iot.com",
  "mqtt_host": "mqtts.fundamentum-iot.com",
  "mqtt_port": "8883",
  "token": "<registry-provisioning-token>",
  "project_id": 123,
  "registry_id": 456,
  "region_id": 1
}

Le bouton est désactivé tant que le registre n'a pas de secret de provisionnement.

Vous pouvez également récupérer le jeton avec un jeton OAuth autorisé à stocker des appareils dans le projet. Voir Authentification.

curl -s https://devices.fundamentum-iot.com/api/v3/registries/<registry-id>/token \
  -H "Authorization: Bearer $TOKEN"

Copiez le fichier de jeton sur l'appareil, ou intégrez ses valeurs dans votre image de micrologiciel. Traitez le token comme un secret : toute personne qui le détient peut enregistrer des appareils dans ce registre.

2. Générer la paire de clés de l'appareil

Générez la paire de clés sur l'appareil ou sur la chaîne de production. La clé privée ne doit jamais quitter l'appareil.

openssl genpkey -algorithm RSA -out rsa_private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in rsa_private.pem -pubout -out rsa_public.pem

3. Enregistrer l'appareil

Appelez POST /api/v3/provision sans en-tête Authorization. Le jeton du registre est placé dans le corps de la requête sous le nom access_token.

curl -s -X POST https://devices.fundamentum-iot.com/api/v3/provision \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": <project-id>,
    "region_id": 1,
    "registry_id": <registry-id>,
    "serial_number": "<serial-number>",
    "asset_type_id": 2,
    "access_token": "<registry-provisioning-token>",
    "algorithm": "RS256",
    "secret": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  }'
Champ Obligatoire Description
project_id, registry_id Oui Provenant du fichier de jeton.
region_id Oui Toujours 1.
serial_number Oui Unique dans le registre : lettres minuscules, chiffres, - et _.
access_token Oui La valeur token du fichier de jeton.
secret Oui La clé publique de l'appareil, au format PEM.
algorithm Non RS256 (par défaut) ou Password.
asset_type_id Non Vaut 2 par défaut (IoT Device). Il ne s'agit pas de l'identifiant du type d'appareil ; voir ci-dessous.

Pour trouver un autre asset_type_id, ouvrez la page du registre dans le Hub et notez l'Id de la ligne du tableau Device Limit. Ouvrez ensuite Device Types et lisez la colonne Asset Type ID (ati) correspondant à ce type d'appareil.

Un appel réussi renvoie 200 avec la configuration de l'appareil et le point de terminaison MQTT :

{
  "status": "success",
  "data": {
    "configuration": {},
    "mqtt": { "host": "mqtts.fundamentum-iot.com", "port": "8883" }
  }
}

4. Traiter la réponse

Statut Signification Marche à suivre
200 L'appareil est provisionné. Stockez l'hôte et le port MQTT, puis connectez-vous.
400 Un champ est invalide ; data.errors indique le path et le location. Corrigez la requête.
404 Le projet, le registre ou le type d'actif est introuvable. Vérifiez les valeurs du fichier de jeton.
409 L'appareil est déjà provisionné avec une clé différente (device already provisioned). Conservez la clé d'origine, ou reprovisionnez explicitement (étape 5).
422 La validation a échoué ; data indique le champ et la raison. Corrigez le champ indiqué dans data.

Appeler POST de nouveau avec la même clé est sans risque : votre micrologiciel peut donc l'appeler à chaque démarrage jusqu'à ce qu'il réussisse.

5. Reprovisionner explicitement

POST /api/v3/provision est l'appel sûr : il ne remplace jamais une clé déjà enregistrée. Lorsque vous effectuez volontairement une rotation de la clé, par exemple après le remplacement de l'élément sécurisé de l'appareil, appelez PUT /api/v3/provision avec le même corps. PUT écrase l'algorithme et le secret stockés.

curl -s -X PUT https://devices.fundamentum-iot.com/api/v3/provision \
  -H "Content-Type: application/json" \
  -d @provision.json

Réservez PUT à la rotation volontaire des clés et utilisez POST dans votre séquence de démarrage habituelle.

Étapes suivantes