API de firmware y ajustes de dispositivos

Esta página cubre dos familias de rutas: actualizaciones de firmware (OTA) y ajustes remotos de dispositivos. Cómo funcionan ambas para las personas se explica en Actualizaciones de firmware (OTA), Oleadas de despliegue de firmware y Ajustes remotos de dispositivos. Las rutas están bajo https://<your host>/tenant/<tenantId>.

Rutas de firmware

Añadir y revocar claves de firma es un permiso de Propietario, así que una clave de API no puede hacerlo.

Subir un paquete

POST /api/iot/ota/packages acepta multipart/form-data con dos partes: file (la imagen) y meta (texto JSON). El checksum se comprueba antes de guardar nada, y la firma se verifica con tus claves registradas.

curl -s -X POST "https://$HOST/tenant/$TENANT/api/iot/ota/packages" \
  -H "Authorization: Bearer $HERMETRY_KEY" \
  -F "file=@router-fw-2.5.0.bin" \
  -F 'meta={"title":"router-fw","version":"2.5.0","checksum":"<sha256 of the file>","signatureScheme":"usign-ed25519","signature":"<text of the .sig file>","profileId":"a1b2…","releaseNotes":"Fixes LTE reconnect."}'

El tamaño máximo predeterminado es 64 MiB. La respuesta es 201 { "package": {...} }.

Asignar y desplegar

{
    "packageId": "f00d…",
    "targetType": "PROFILE",
    "targetId": "a1b2…",
    "waves": [
        {
            "size": {
                "percent": 5
            },
            "soakMin": 60,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 1440
        },
        {
            "size": {
                "percent": 100
            },
            "soakMin": 0,
            "minSuccessPct": 95,
            "maxFailurePct": 2,
            "maxDurationMin": 2880
        }
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/ota/assignments' \
  -H 'Content-Type: application/json' \
  -d '{"packageId":"f00d…","targetType":"PROFILE","targetId":"a1b2…","waves":[{"size":{"percent":5},"soakMin":60,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":1440},{"size":{"percent":100},"soakMin":0,"minSuccessPct":95,"maxFailurePct":2,"maxDurationMin":2880}]}'

{
    "assignment": {
        "…": "…"
    },
    "preview": {
        "…": "…"
    },
    "result": {
        "…": "…"
    }
}

{
    "assignment": null,
    "preview": {
        "…": "…"
    }
}

{
    "message": "Only a ready package can be assigned.",
    "code": "CONFLICT"
}

El size de una oleada es { "percent": 0–100 } o { "count": 1–100000 }; la última oleada toma el resto. soakMin de 0 a 10.080, minSuccessPct y maxFailurePct de 0 a 100, maxFailures opcional, maxDurationMin de 5 a 43.200.

Estados de despliegue: RUNNING, PAUSED, COMPLETED, ABORTED. Una comprobación fallida pausa el despliegue; resume lo continúa, abort lo termina.

Estados de actualización

La actualización de un dispositivo pasa por QUEUED, INITIATED, WAITING, DOWNLOADING, DOWNLOADED, VERIFIED, UPDATING y termina en UPDATED, FAILED, TIMEOUT, ROLLED_BACK, SKIPPED o CANCELLED. Solo FAILED, TIMEOUT y ROLLED_BACK pueden reintentarse ({ "action": "retry" }), hasta el límite de intentos.

Ajustes OTA

PUT /api/iot/ota/settings/profile/{profileId} acepta otaEnabled, allowMetered, allowUnsigned, downloadTimeoutMin (de 5 a 1.440), updateTimeoutMin (de 2 a 240), maxAttempts (de 1 a 10); null vuelve al valor predeterminado. Para un dispositivo (/settings/device/{deviceId}) solo se acepta allowMetered: «Un dispositivo solo acepta el ajuste de enlace medido.»

Eventos de webhook: ota.update.* y ota.rollout.*, consulta la Referencia de eventos de webhook.

Rutas de ajustes de dispositivos

Los ajustes remotos son para dispositivos con licencia cuyo modelo publica un manifiesto de ajustes.

Lo que una escritura puede cambiar depende de la clase de cada ajuste modificado: los ajustes de operación requieren iot_device_settings.operate, los ajustes de configuración iot_device_settings.write, los ajustes peligrosos iot_device_settings.dangerous.write (solo el Propietario, nunca una clave de API) y "confirm": true.

Cambiar una sección

GET  /api/iot/devices/{deviceId}/settings/network        → ETag: "7"
PATCH /api/iot/devices/{deviceId}/settings/network
If-Match: "7"
{ "patch": { "lte": { "apn": "iot.example" } } }

• Se requiere If-Match: sin él, 428 «If-Match is required: send the rev you read.»
• Una sección cambiada desde que la leyó: 412 «The section changed since it was read; read it again.» (rev_mismatch).
• ?dryRun=true valida y lista lo que cambiaría, y no guarda nada.
• Un merge patch fusiona objetos, elimina con null y reemplaza las listas completas.
• Las escrituras están limitadas a 600 por organización y por minuto.
• Los secretos nunca se devuelven: un ajuste secreto se lee como { "set": true }.

Un dispositivo que no acepta ajustes por sección responde 409 «This device does not take settings by section.»; uno cuyo manifiesto no está aún en el catálogo, «The settings manifest of this device’s model and firmware is not in the catalog yet.»

Trabajos masivos

POST /api/iot/device-settings/jobs con la cabecera Idempotency-Key: name (hasta 80), baselineId o sections, selector (deviceIds, profileId o models), waves opcional ({ "percent": [1, 10, 100] } o { "count": [...] }, hasta 10), gates (minApplied, maxReverted como fracciones de 0 a 1), onConflict (queue o skip), offlineExpiryDays (de 1 a 90), waveTimeoutMin (de 1 a 1,440), confirm. Una Idempotency-Key repetida responde con el primer trabajo (200). ?dryRun=true responde con el plan. Rechazos: 409 too_many_jobs; 422 confirm_required, invalid_sections, no_devices, too_many_devices; 403 class_forbidden.