Actions et encodeurs personnalisés

Les actions sont vos propres opérations sur les appareils : vous définissez le temps dont un appareil dispose pour les recevoir et les exécuter, le nombre de nouvelles tentatives et leur urgence, et Fundamentum suit chacune d'elles appareil par appareil. Avec les capabilities et les encodeurs, une même action fonctionne sur tous les types d'appareils et toutes les versions de micrologiciel, même si chacun attend un format différent.

Avant de commencer

• Vous avez la CLI fun connectée, ou un jeton pour la Public API.
• Vous connaissez votre <project-id> et les identifiants des appareils cibles.
• Vos appareils reçoivent et accusent réception des actions. Le daemon Linux les transmet à votre code et renvoie les mises à jour d'état. Consultez Topics MQTT et formats de message pour les appareils sans Edge.
• Pour écrire un encodeur, vous savez comment déployer une fonction cloud.

Fonctionnement

• Un type d'action est un modèle : un name, un type numérique que vos appareils reconnaissent et les règles de livraison.
• Une action envoie une charge utile à un ou plusieurs appareils. Fundamentum crée une action d'appareil par appareil et suit son statut.
• Le type d'action peut éventuellement désigner une capability. Fundamentum recherche alors, pour le type et la version de micrologiciel de chaque appareil, l'encodeur qui traduit la charge utile, ainsi que le protocole (topic de l'appareil) sur lequel la livrer.

Une action d'appareil passe par les statuts suivants :

pending → queued → sent → waiting / ongoing → success | failure | timeout

Une action d'appareil peut aussi se terminer par cancel, et retry indique qu'elle est renvoyée. success, failure, timeout et cancel sont des statuts finaux. Chaque action d'appareil enregistre également sent_at, received_at, started_at, done_at, sa progression ainsi que ses nombres de tentatives de livraison et d'exécution. L'action elle-même est scheduled, progressing ou done, et sa progression est la moyenne de celles de ses appareils.

1. Créer un type d'action

fun api v1 action store-action-type --project-id <project-id> --body '{
  "project_id": <project-id>,
  "name": "Rotate logs",
  "type": 42,
  "delivering_timeout": 120,
  "execution_timeout": 300,
  "max_retries": 3,
  "priority": 1
}'

Fundamentum fournit également des types d'action génériques partagés par tous les projets. Listez-les avec fun api v1 action list-action-types --project-id <project-id>.

2. Envoyer une action

payload est encodé en base64. devices liste les identifiants d'appareils :

fun api v1 action store-action --project-id <project-id> --body '{
  "action_type_id": <action-type-id>,
  "devices": [101, 102, 103],
  "description": "Weekly log rotation",
  "payload": "eyJrZWVwIjogN30="
}'

Pour la planifier, ajoutez "is_scheduled": true avec activate_at, end_at ou une expression cron. Pour cibler les appareils d'un registre, utilisez store-action-by-registry avec --registry-id.

3. Suivre l'action de bout en bout

fun api v1 action get-action --project-id <project-id> --action-id <action-id>
fun api v1 action get-device-actions --project-id <project-id> --device-id <device-id>
fun api v1 action get-device-actions-by-registry --project-id <project-id> --registry-id <registry-id>

Dans le Hub, la page de l'action et l'onglet Actions de l'appareil se mettent à jour en direct à mesure que les appareils signalent leur progression.

4. Annuler ou réessayer

Les actions ne peuvent pas être supprimées, seulement annulées. Vous pouvez agir sur tous les appareils d'une action, ou sur un seul :

fun api v1 action cancel-action --project-id <project-id> --action-id <action-id>
fun api v1 action retry-device-action --project-id <project-id> --device-id <device-id> --action-id <action-id>

5. Utiliser une même action sur plusieurs types d'appareils : capabilities et encodeurs

1. Créez une capability, le nom de ce que les appareils savent faire. Les noms comptent de 1 à 64 caractères : lettres, chiffres, ., - et _, en commençant par une lettre ou un chiffre.

   fun api v1 capability store-capability --project-id <project-id> \
     --body '{"name": "device.restart", "description": "Restart the device"}'
   

2. Choisissez un protocole. Il définit le topic de l'appareil sur lequel la charge utile encodée est publiée. Les protocoles sont communs à toute la plateforme :

   fun api v1 capability get-encoder-protocols --project-id <project-id>
   

3. Déployez votre fonction d'encodeur (consultez Fonctions cloud), puis enregistrez-la comme encodeur :

   fun api v1 capability store-encoder --project-id <project-id> \
     --body '{"name": "Model B restart encoder", "protocol_id": <protocol-id>, "function_id": "<function-id>", "parameters": {}}'
   

4. Liez la capability à l'encodeur pour un type d'appareil, et éventuellement une version de micrologiciel. Un lien pour un version_id précis l'emporte sur un lien valable pour toutes les versions :

   fun api v1 capability store-capability-encoder --project-id <project-id> --capability-id <capability-id> \
     --body '{"encoder_id": <encoder-id>, "device_type_id": <device-type-id>, "version_id": <version-id>}'
   

5. Créez un type d'action avec "capability_name": "device.restart" et envoyez des actions comme à l'étape 2.

Écrire un encodeur

Votre encodeur est appelé selon deux modes :

• encode, lorsque l'action est créée, puis à chaque envoi à un appareil, nouvelles tentatives comprises. L'entrée est la charge utile de l'action. Renvoyez ce que l'appareil doit recevoir. Si votre encodeur échoue lors de la création de l'action, celle-ci est rejetée.
• decode, à chaque réponse de l'appareil. L'entrée est le payload de la réponse de l'appareil. Renvoyez-le dans le format dans lequel vous souhaitez le lire.

Le statut, le message et la progression de l'action d'appareil proviennent toujours de la réponse de l'appareil. decode ne traduit que sa charge utile ; s'il échoue, le statut s'applique quand même et l'action d'appareil enregistre l'erreur de décodage.

L'appel transporte quatre valeurs de métadonnées : Mode (encode ou decode), Capability, Action-Id et Device-Ids (séparés par des virgules). Sur un protocole groupable, un seul appel peut couvrir plusieurs appareils qui partagent le même encodeur. La fonction écrit un document JSON sur stdout, dans les deux modes :

{"status": "success", "data_type": "json", "data": {"command": "restart", "delay_s": 5}}

Utilisez "data_type": "binary" avec data en base64 pour les charges utiles binaires, ou {"status": "error", "error": "..."} pour signaler un échec. Consultez Fonctions cloud : moteur d'exécution et SDK pour lire l'entrée et les métadonnées.

Étapes suivantes

• Référence de l'API dans Swagger UI : Action, Capability
• Mises à jour du micrologiciel (OTA)
• Transferts de fichiers
• Fonctions cloud
• Public API