Actualizaciones OTA

Las actualizaciones OTA (over-the-air) envían nuevo firmware o software a una flota sin tocar el hardware. CORE-M modela esto en dos partes: un OTA package (el artefacto verificado y sus metadatos) y un rollout (la campaña escalonada que lo entrega a un conjunto de dispositivos). La entrega viaja sobre RPC persistente, de modo que una actualización llega a un dispositivo cuando se conecta a continuación, y el dispositivo reporta el resultado de vuelta.

Esto es un how-to para operadores. Subirás un paquete, iniciarás un rollout de canary, lo vigilarás y revertirás si sale mal.

OTA packages

Un paquete es el artefacto más los metadatos que CORE-M necesita para verificarlo, decidir la compatibilidad y presentarlo a los dispositivos.

Campo	Significado
version	Versión semántica del build, p. ej. 2.0.0.
artifact_uri	Dónde reside el binario.
sha256	Checksum declarado del artefacto. Verificado antes de que el paquete sea utilizable.
signature	Firma criptográfica del artefacto.
size_bytes	Tamaño del artefacto, para que los dispositivos puedan planificar la descarga.
compatibility	A qué tipos de dispositivo / hardware puede dirigirse el build.
release_notes	Resumen de cambios legible por humanos.
type	fw (firmware) o sw (software).

Verificación de checksum y firma

Cuando subes un paquete, CORE-M descarga el artefacto y verifica su checksum contra el sha256 declarado antes de que el paquete quede disponible para cualquier rollout. Si el checksum calculado no coincide, el paquete se rechaza con INVALID_ARGUMENT y nunca se asigna a ningún sitio. Los dispositivos verifican de forma independiente la firma y el checksum tras la descarga, así que una transferencia corrupta se detecta en ambos extremos.

curl -X POST https://api.kronoxdata.com/api/v1/ota/packages \
  -H "Authorization: Bearer <tenant-admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fw",
    "version": "2.0.0",
    "artifact_uri": "s3://ota-artifacts/temp-sensor/fw-2.0.0.bin",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "signature": "MEUCIQD...",
    "size_bytes": 524288,
    "compatibility": { "device_type": "temp-sensor", "min_version": "1.0.0" },
    "release_notes": "Fix sensor drift above 60C; reduce idle current."
  }'

{
  "package_id": "pkg_2a0f",
  "status": "available",
  "checksum_verified": true
}

Precaución

Un paquete cuyo checksum no verifica se rechaza de plano — no puedes dirigirlo desde un rollout. Si la subida falla con INVALID_ARGUMENT, vuelve a hacer el hash de tu artefacto y confirma que el sha256 que declaraste coincide con los bytes en artifact_uri.

Rollouts

Un rollout entrega un paquete a un conjunto objetivo de dispositivos, en etapas, con controles de seguridad. Diriges a un device profile, empiezas con un pequeño porcentaje de canary, y dejas que CORE-M expanda el rollout solo si el canary está sano.

La máquina de estados del rollout

stateDiagram-v2
  [*] --> active : iniciar (canary %)
  active --> paused : pausa del operador
  active --> paused : umbral de fallo superado\n(auto, alerta)
  paused --> active : reanudar
  active --> rolling_back : rollback del operador
  paused --> rolling_back : rollback del operador
  active --> completed : todos los dispositivos objetivo con éxito
  rolling_back --> completed : rollback terminado
  completed --> [*]

Por dispositivo, cada objetivo rastrea su propio estado: scheduled → (comando de actualización enviado) → successful o failure, expuesto como registros de Device RPC.

Crear un rollout

1. Inicia el rollout. Dirígelo a un profile, apunta al paquete verificado y establece un pequeño porcentaje de canary y un umbral de fallo. Solo la porción del canary recibe el comando primero.

   curl -X POST https://api.kronoxdata.com/api/v1/ota/rollouts \
     -H "Authorization: Bearer <tenant-admin-jwt>" \
     -H "Content-Type: application/json" \
     -d '{
       "package_id": "pkg_2a0f",
       "target_profile_id": "prof_temp_v2",
       "canary_percent": 5,
       "failure_threshold_percent": 10,
       "rollback_package_id": "pkg_19b3"
     }'

   {
     "rollout_id": "rol_4c7e",
     "status": "active",
     "canary_percent": 5,
     "scheduled_count": 12
   }

   Solo el 5% de los dispositivos elegibles se programa inicialmente; el resto espera. Se publica el evento profile.ota.rollout.started.{tenant}.{rollout_id}.

2. Las actualizaciones se entregan vía RPC persistente. CORE-M emite un comando ota_start (una RPC persistente) a cada dispositivo programado. Como es persistente, un dispositivo que está offline lo recibe al reconectar. El dispositivo descarga el artefacto (reanudable, por chunks), verifica firma y checksum, lo aplica, y se reinicia.

3. Los dispositivos reportan resultados. Cada dispositivo reporta de vuelta su firmware_version y success/failure. En caso de éxito su estado de rollout pasa a successful, su campo de firmware del dispositivo se actualiza a la nueva versión, y los contadores de éxito del rollout avanzan.

   {
     "device_id": "dev_8f3a",
     "rollout_id": "rol_4c7e",
     "firmware_version": "2.0.0",
     "status": "success"
   }

4. Vigila el canary, luego expande. Si el canary se mantiene sano, avanza el rollout al resto de la flota (reanudar / subir el canary). Si no, el umbral de fallo interviene — ver abajo.

Pausar, reanudar, revertir

Pausa / auto-pausa

Puedes pausar un rollout en cualquier momento, y CORE-M lo pausa automáticamente si los fallos cruzan el umbral. Con failure_threshold_percent=10, una vez que el 11% de los dispositivos del canary reporta fallo el monitor del rollout lo cambia a paused, no programa más dispositivos, y publica el evento de alerta profile.ota.rollout.paused.{tenant}.{rollout_id}.

curl -X POST https://api.kronoxdata.com/api/v1/ota/rollouts/rol_4c7e/pause \
  -H "Authorization: Bearer <tenant-admin-jwt>"

Reanudar

Una vez que has diagnosticado una pausa (o simplemente quieres continuar una retención manual), reanuda. La programación retoma desde donde se detuvo.

curl -X POST https://api.kronoxdata.com/api/v1/ota/rollouts/rol_4c7e/resume \
  -H "Authorization: Bearer <tenant-admin-jwt>"

Rollback

Cuando el nuevo build es malo, revierte al rollback_package_id configurado. CORE-M envía comandos de rollback a los dispositivos afectados, pone el rollout en rolling_back, y rastrea cada comando a través de registros de Device RPC — así obtienes la misma visibilidad por dispositivo a la baja que a la alza.

curl -X POST https://api.kronoxdata.com/api/v1/ota/rollouts/rol_4c7e/rollback \
  -H "Authorization: Bearer <tenant-admin-jwt>"

Consejo

Establece siempre un canary_percent bajo (1–5%) y un failure_threshold_percent sensato para firmware. El canary más la auto-pausa son tu red de seguridad: un build malo se detiene a sí mismo tras un puñado de dispositivos en lugar de inutilizar la flota. Configura un rollback_package_id por adelantado para que el rollback sea una llamada, no una carrera.

Cómo descargan los dispositivos el artefacto

Un dispositivo bajo un rollout se entera de su paquete asignado y descarga los bytes él mismo:

• GET /api/v1/devices/{device_id}/ota devuelve los metadatos del paquete (package_id, type, version, size_bytes, checksum) para el dispositivo autenticado — la asignación a nivel de dispositivo prevalece sobre la de nivel de profile.
• GET /api/v1/devices/{device_id}/ota/chunk transmite el artefacto como rangos de bytes (limitados a 64 KiB por chunk), en cualquier orden, para que las descargas sean reanudables sobre enlaces inestables. Un dispositivo solo puede obtener su propio paquete asignado; cualquier otro package_id devuelve PermissionDenied.

El dispositivo verifica el checksum (y la firma) una vez que llega el último chunk (complete: true) antes de aplicar la actualización.

A dónde ir después

Relacionado

• Device RPC — RPC persistente, el mecanismo de entrega detrás de OTA.
• Device profiles — el objetivo del rollout y la política OTA que hereda un dispositivo.
• Rotación de credenciales — mantén sanas las credenciales del dispositivo a lo largo de las generaciones de firmware.