Topics et formats de messages MQTT

Cette page répertorie les paramètres de connexion du broker MQTT, la manière dont un appareil s'authentifie, ainsi que tous les topics sur lesquels un appareil peut publier ou s'abonner, avec leur charge utile. Utilisez-la lorsque vous écrivez ou déboguez la couche MQTT de votre micrologiciel.

Deux voies prises en charge. Votre micrologiciel peut communiquer directement avec le broker via n'importe quel client MQTT 5, en suivant cette page. Il peut aussi utiliser le daemon Linux ou la bibliothèque MCU, qui implémentent ce protocole à votre place, y compris la gestion des clés, les heartbeats, les actions et les mises à jour du micrologiciel. Certains topics sont configurables par registre : lisez-les depuis le registre plutôt que de les coder en dur.

Paramètres de connexion

Connectez-vous toujours à l'hôte et au port renvoyés par le provisionnement (data.mqtt.host et data.mqtt.port), voir Devices API v3.

Les piles TLS embarquées doivent faire confiance à l'autorité de certification racine de la chaîne du broker. Inspectez la chaîne avec :

openssl s_client -showcerts -verify 5 -connect mqtts.fundamentum-iot.com:8883

Authentification

L'appareil signe un JWT avec sa clé privée, celle dont il a enregistré la clé publique lors du provisionnement. Le broker le vérifie à l'aide de cette clé publique. Aucun secret partagé ne circule sur le réseau.

Signez avec RS256. Le broker refuse la connexion si la signature est invalide, si le jeton est expiré ou si aud ne correspond pas au projet figurant dans le client ID.

Client ID

Forme longue :

projects/<project-id>/regions/<region-id>/registries/<registry-id>/devices/<serial-number>

Forme courte, pour les appareils où la longueur compte :

<project-id>.<region-id>.<registry-id>.<serial-number>

Topics

Chaque topic commence par le préfixe propre à l'appareil :

registries/<registry-id>/devices/<serial-number>/

Un appareil ne peut publier et s'abonner que sous son propre préfixe. Il n'existe pas de trafic d'appareil à appareil : vos systèmes reçoivent les données des appareils via des connecteurs.

De l'appareil vers Fundamentum

De Fundamentum vers l'appareil

Les messages sur custom_actions ne sont livrés que lorsque l'appareil est abonné. Rien n'est renvoyé vers le cloud pour ces messages.

Charges utiles

Télémétrie : events

Des octets quelconques. Fundamentum transmet la télémétrie telle quelle, vous choisissez donc votre propre format. Décodez un format propriétaire avec une fonction cloud.

États : states

Toute charge utile parvient au topic des états du registre. Lorsque vous utilisez le format JSON Fundamentum, la plateforme stocke également les états (historique et dernières valeurs) et extrait les lectures des balises :

{
  "timestamp": 1789167823,
  "states": {
    "battery_level": 87,
    "temperature": 21.4
  },
  "beacons": [
    {
      "identification": "beacon-abc123",
      "states": { "rssi": -67, "battery_level": 44 }
    }
  ]
}

Heartbeat : heartbeat

La propriété utilisateur MQTT 5 v sélectionne le format.

Sans v, ou avec v: 0, envoyez du JSON contenant le nombre de secondes écoulées depuis le démarrage :

{ "uptime": 86400 }

Avec v: 1, envoyez un message protobuf Heartbeat. Il peut aussi transporter les sous-appareils pour lesquels une passerelle s'exprime, chacun avec son numéro de série et son uptime. Voir Gateways and sub-devices.

Les schémas protobuf des heartbeats et des actions sont publiés dans le crate fundamentum-iot-mqtt-proto sur crates.io.

Commandes : commands et commands/<device-command-id>

L'appareil reçoit un tableau JSON de commandes en attente, chacune ayant la forme suivante :

{
  "device_command_id": 1,
  "command_short_name": "command-name",
  "parameters": {}
}

Exemple de mise à jour du micrologiciel :

{
  "device_command_id": 790,
  "command_short_name": "firmware-update",
  "parameters": {
    "device_id": 296,
    "command_id": 8,
    "version_id": 29,
    "target_device": { "serial_number": "<serial-number>", "id": 296 },
    "version": {
      "configuration_file_url": ["https://<download-url>"],
      "configuration": {},
      "identifier": "base-firmware-1-4-2",
      "name": "base-firmware-version",
      "id": 29
    }
  }
}

command_id et version.id sont des identifiants internes que l'appareil peut ignorer.

Signalez la progression sur commands/<device-command-id> :

{ "status": "success", "message": "firmware updated to 1.4.2" }

Voir Firmware updates (OTA).

Actions : actions et actions/<action-id>/response

Les actions sont des messages protobuf. L'appareil signale le résultat sur actions/<action-id>/response, également en protobuf. Les actions sont définies par type d'appareil et traduites pour chaque version du micrologiciel par des encodeurs. Voir Actions and custom encoders.

Configuration : config

La configuration enregistrée de l'appareil, au format JSON. Elle n'a pas de forme fixe : c'est ce que vous avez enregistré pour l'appareil, par exemple avec POST .../configuration sur la Devices API.

Étapes suivantes

• Connect over MQTTS
• Send telemetry, states and heartbeats
• Edge components