Envoi de commandes aux appareils

Une commande (aussi appelée RPC) demande à un appareil d’effectuer une action : redémarrage, commutation d’une sortie, lancement d’un test. Chaque commande est enregistrée comme une requête, et vous pouvez en suivre l’état jusqu’à ce que l’appareil réponde. Les commandes ne sont envoyées que par des sessions TLS (sauf si le profil autorise une commande en clair), jamais par les flux qui traitent la télémétrie, et chacune est vérifiée par rapport aux permissions de l’expéditeur.

Le catalogue des commandes

Chaque profil d’appareil dispose d’un onglet Commands : « Les commandes que les opérateurs peuvent envoyer aux appareils de ce profil ; chaque niveau nécessite sa propre permission. » Sa modification nécessite la permission de gérer les commandes (administrateurs).

Sélectionnez Add command et renseignez :

From a template pré-remplit le formulaire à partir d’une commande que la plateforme envoie déjà (comme une commande de carte de contrôle). Import remplace tout le catalogue par un export ({"commands": [ … ]}) ; Export affiche le catalogue au format JSON. Un profil contient jusqu’à 200 commandes.

Niveaux

Envoyer une commande

1. Ouvrez l’appareil et son onglet Commands.
2. Choisissez une commande sous Choose a command (ou Other method (raw), réservé aux propriétaires) et renseignez ses Parameters.
3. Définissez les options si besoin :

1. Sélectionnez Send. Une commande à fort impact demande Send {method}? (« Cette commande a un impact sur l’appareil (il peut redémarrer ou perdre sa session). ») et, si elle comporte une phrase, Type {phrase} to confirm.

Si l’appareil est hors ligne, l’onglet affiche : « L’appareil est hors ligne : sans « persistent », la commande échoue immédiatement. »

Les tableaux de bord, les symboles SCADA, les règles et les flux peuvent également envoyer des commandes. Une carte de contrôle n’envoie que des commandes de niveau basic. Voir Control cards.

États des commandes

Une commande longue affiche Running on the device jusqu’à l’arrivée de son résultat ; une commande expirée affiche No answer: the outcome is unknown ; une réponse arrivée après la fin affiche Answered after the end.

L’historique

L’History de l’onglet Commands liste Method, Status, Sent by (Console, API, A flow, Firmware update, An alarm action, A dashboard control), Created, Completed et Duration. Ouvrez une commande pour voir sa Request, sa Response et sa Progress, pour Cancel command tant qu’elle est en attente ou envoyée, ou pour Send again. Les paramètres secrets sont masqués.

Limites par défaut : 10 commandes par appareil et par minute, et 600 par organisation et par minute ; paramètres jusqu’à 16 Kio de JSON ; réponse jusqu’à 64 Kio. L’historique est conservé 90 jours.

Sur l’appareil

L’appareil s’abonne à v1/rpc/req/+ et reçoit :

PUBLISH v1/rpc/req/42
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}

Pour une commande à aller-retour, il répond avec le même identifiant :

PUBLISH v1/rpc/res/42
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}

Règles pour l’appareil :

• Une commande peut arriver deux fois. Mémorisez au moins les 32 derniers identifiants de requête pendant 10 minutes et n’exécutez jamais deux fois le même identifiant.
• Si la requête contient expirationTime et qu’elle est dépassée, ne l’exécutez pas ; répondez {"ok": false, "error": "expired"}.
• Si la requête est plus grande que ce que l’appareil peut traiter, ne l’exécutez pas ; répondez {"ok": false, "error": "payload_too_large"}.
• Les commandes ne sont livrées qu’après que l’appareil s’est abonné à v1/rpc/req/+ sur cette connexion.

Les appareils HTTP attendent les commandes avec GET /api/v1/rpc et répondent avec POST /api/v1/rpc/{id}. Voir Device HTTP API.

Commandes longues

PUBLISH v1/rpc/res/43
{"ok": true, "accepted": true, "job_id": "43"}

PUBLISH v1/attributes
{"rpc_result": {"job_id": "43", "method": "sys.traceroute", "ok": true, "result": {...}, "ts": 1759572042000}}

Requêtes émises par l’appareil

Un appareil peut aussi interroger le cloud : il publie sur v1/rpc/up/req/{id} avec {"method": …, "params": …} et lit la réponse sur v1/rpc/up/res/{id}. Vos flux reçoivent et traitent ces requêtes.

LoRaWAN et enfants de passerelle

• Les appareils LoRaWAN reçoivent des downlinks bruts avec la commande lora.downlink. Voir Sending downlinks.
• Les commandes vers les appareils derrière une passerelle sont en cours de développement. Voir Commands to devices behind a gateway.

Par API

{
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    },
    "timeoutMs": 10000
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"sys.ping","params":{"host":"8.8.8.8","count":3},"timeoutMs":10000}'

{
    "rpc": {
        "rpcId": "…",
        "deviceId": "…",
        "method": "sys.ping",
        "status": "SUCCESSFUL",
        "outcome": null,
        "response": {
            "ok": true,
            "result": {
                "sent": 3,
                "received": 3,
                "avg_ms": 18.2
            }
        },
        "tier": "basic",
        "highImpact": false,
        "source": "api",
        "…": "…"
    }
}

{
    "rpc": {
        "rpcId": "…",
        "deviceId": "…",
        "method": "sys.reboot",
        "status": "QUEUED",
        "…": "…"
    }
}

{
    "message": "This command needs confirm: true.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "confirm_required"
    }
}

{
    "message": "Device not found.",
    "code": "NOT_FOUND"
}

Lisez une commande avec GET /tenant/{tenantId}/api/iot/rpc/{rpcId} et annulez-la avec POST …/rpc/{rpcId}/cancel (uniquement pendant QUEUED ou SENT ; action journalisée). Le champ outcome affiche running, unknown ou late, comme décrit ci-dessus. Voir Commands API.

Les événements webhook rpc.completed et rpc.failed informent les autres systèmes du résultat. Les commandes à fort impact et les commandes brutes sont inscrites dans le journal d’audit à leur création et à leur fin.