Envío de comandos a dispositivos

Un comando (también llamado RPC) pide a un dispositivo que haga algo: reiniciarse, conmutar una salida, ejecutar una prueba. Cada comando se guarda como una solicitud, y puede seguirse hasta que el dispositivo responda. Los comandos solo se envían a través de sesiones TLS (salvo que el perfil permita un comando en claro), nunca por los flujos que procesan telemetría, y cada uno se comprueba frente a los permisos del remitente.

El catálogo de comandos

Cada perfil de dispositivo tiene una pestaña Commands: «Los comandos que los operadores pueden enviar a los dispositivos de este perfil; cada nivel necesita su propio permiso.» Editarla requiere el permiso para gestionar comandos (administradores).

Seleccione Add command y complete:

From a template inicia el formulario a partir de un comando que la plataforma ya envía (como un control de placa). Import sustituye todo el catálogo por una exportación ({"commands": [ … ]}); Export muestra el catálogo en JSON. Un perfil admite hasta 200 comandos.

Niveles

Enviar un comando

1. Abra el dispositivo y su pestaña Commands.
2. Elija un comando en Choose a command (o Other method (raw), solo propietarios) y complete sus Parameters.
3. Configure las opciones si es necesario:

1. Seleccione Send. Un comando de alto impacto pregunta Send {method}? («Este comando tiene impacto en el dispositivo (puede reiniciarlo o perder su sesión).») y, si tiene frase, Type {phrase} to confirm.

Si el dispositivo está desconectado, la pestaña avisa: «El dispositivo está desconectado: sin «persistent» el comando falla de inmediato.»

Los paneles, los símbolos SCADA, las reglas y los flujos también pueden enviar comandos. Un control de placa envía solo comandos de nivel básico. Consulte Control cards.

Estados del comando

Un comando de larga duración muestra Running on the device hasta que llega su resultado; un comando que caducó muestra No answer: the outcome is unknown; una respuesta posterior al final muestra Answered after the end.

El historial

El History de la pestaña Commands lista Method, Status, Sent by (Console, API, A flow, Firmware update, An alarm action, A dashboard control), Created, Completed y Duration. Abra un comando para ver su Request, Response y Progress, para Cancel command mientras esté en cola o enviado, o para Send again. Los parámetros secretos aparecen enmascarados.

Límites por defecto: 10 comandos por dispositivo y minuto, y 600 por organización y minuto; parámetros de hasta 16 KiB de JSON; una respuesta de hasta 64 KiB. El historial se conserva durante 90 días.

En el dispositivo

El dispositivo se suscribe a v1/rpc/req/+ y recibe:

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

Para un comando de dos sentidos responde con el mismo id:

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

Reglas para el dispositivo:

• Un comando puede llegar dos veces. Recuerde al menos los últimos 32 ids de solicitud durante 10 minutos y nunca ejecute dos veces el mismo id.
• Si la solicitud incluye expirationTime y ya ha pasado, no la ejecute; responda {"ok": false, "error": "expired"}.
• Si una solicitud es mayor de lo que el dispositivo puede aceptar, no la ejecute; responda {"ok": false, "error": "payload_too_large"}.
• Los comandos solo se entregan después de que el dispositivo se haya suscrito a v1/rpc/req/+ en esta conexión.

Los dispositivos HTTP esperan comandos con GET /api/v1/rpc y responden con POST /api/v1/rpc/{id}. Consulte Device HTTP API.

Comandos de larga duración

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}}

Solicitudes desde el dispositivo

Un dispositivo también puede pedir algo a la nube: publique en v1/rpc/up/req/{id} con {"method": …, "params": …} y lea la respuesta en v1/rpc/up/res/{id}. Sus flujos reciben y responden estas solicitudes.

LoRaWAN y dispositivos hijos de pasarela

• Los dispositivos LoRaWAN reciben downlinks sin procesar con el comando lora.downlink. Consulte Sending downlinks.
• Los comandos a dispositivos detrás de una pasarela están en desarrollo. Consulte Commands to devices behind a gateway.

Por 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"
}

Lee un comando con GET /tenant/{tenantId}/api/iot/rpc/{rpcId} y cancélalo con POST …/rpc/{rpcId}/cancel (solo mientras esté QUEUED o SENT; queda auditado). El campo outcome muestra running, unknown o late tal como se describe arriba. Consulta Commands API.

Los eventos de webhook rpc.completed y rpc.failed informan a otros sistemas del resultado. Los comandos de alto impacto y los comandos raw se escriben en el registro de auditoría al crearse y al terminar.