Programar una flota
Una campaña envía comandos a los dispositivos de un grupo de entidades según un calendario y conserva un registro de cada dispositivo al que lo intentó. El alumbrado público es el caso para el que se construyó: atenuar cada luminaria en su propio ocaso, restaurarla en su propio amanecer, omitir los días festivos y saber a la mañana siguiente qué luminarias no obedecieron y por qué.
Una campaña tiene tres partes:
- un disparador que indica cuándo se activa: una expresión cron, un calendario de fechas o el sol;
- uno o más pasos, cada uno un comando con una carga útil opcional y un retraso opcional tras el disparador;
- un objetivo, un grupo de entidades de dispositivos.
Cada vez que se activa el disparador, la plataforma planifica un ciclo. Un ciclo contiene un elemento por dispositivo y por paso, y el elemento es la unidad de seguimiento y de reintento. Internamente, cada grupo de elementos vencidos se convierte en un lote de comandos ordinario, de modo que cada dispositivo se valida contra su contrato de capacidades, se retiene hasta su ventana de mantenimiento, se sigue a lo largo del ciclo de vida del comando y caduca según su tiempo de vida, igual que cualquier otro comando. Lee primero esas dos guías; esta solo cubre lo que añade la programación.
Las campañas viven en el punto de acceso command-delivery,
https://<your-host>/api/command-delivery/graphql. Crear, activar o desactivar y eliminar una
campaña, y reintentar sus fallos, requiere command:write. Leer requiere command:read. Toda
operación requiere además device:read, porque una campaña nombra un grupo y su seguimiento lista
los dispositivos del grupo. Un miembro limitado a una parte del tenant no puede usar campañas.
Crear una campaña SOLAR, leer sus elementos (campaignElements) o ciclos (campaignCycles) y reintentar sus fallos (retryCampaignFailed) ahora requiere además location:installed:read (o location:read). Las horas por dispositivo de un calendario solar revelan la posición instalada de cada dispositivo; incluso los recuentos de un ciclo pueden revelar resultados derivados de la posición en un grupo de un solo dispositivo. Las campañas CRON y CALENDAR no cambian. Añade esta autoridad a cualquier rol que gestione campañas solares.
Crear una campaña
mutation {
createCampaign(request: {
token: "dusk-dim"
name: "Dim at dusk"
trigger: "{\"kind\":\"SOLAR\",\"zone\":\"Europe/Berlin\",\"event\":\"SUNSET\",\"offsetMinutes\":-15}"
steps: [
{ type: "COMMAND", name: "setLevel", payload: "{\"level\":40}" }
{ type: "COMMAND", name: "setLevel", payload: "{\"level\":20}", delaySeconds: 21600 }
]
groupToken: "city-streetlights"
}) {
campaign { token enabled plannedThrough lastError }
rejection { code reason }
}
}
Una definición que no puede aceptarse vuelve como rejection, no como error. Los códigos son
CAMPAIGN_TRIGGER_INVALID, CAMPAIGN_STEPS_INVALID, CAMPAIGN_STEP_UNSUPPORTED,
CAMPAIGN_TARGET_INVALID, CAMPAIGN_FIELD_INVALID, TOKEN_IN_USE y los códigos de carga útil y de
nombre de comando con los que se rechaza un comando individual.
| Campo | Significado |
|---|---|
token | Único dentro del tenant. |
name | Opcional, como máximo 128 caracteres. |
trigger | Un documento JSON, descrito más abajo. |
steps | De uno a diez pasos. Un paso es COMMAND con un name, una payload JSON opcional y delaySeconds de 0 a 86400 tras el disparador. |
groupToken | El grupo de entidades objetivo, como máximo 128 caracteres. Un grupo dinámico puede seleccionar los dispositivos de un área. |
maxLatenessSeconds | Cuánto puede retrasarse todavía el envío de un comando planificado, de 1 a 86400. Por defecto 900. |
expiresInSeconds | El tiempo de vida de cada comando, de 1 a 604800, contado desde que se crea. Por defecto 3600. Es cuánto puede esperar un comando a un dispositivo inalcanzable o a una ventana de mantenimiento, así que puede durar más que maxLatenessSeconds, que limita cuándo envía el planificador, no cuándo recibe un dispositivo. Defínelo corto si una entrega tardía es peor que ninguna. |
enabled | Si empieza activa. Por defecto true. |
Una campaña nueva no envía nada que venciera antes de crearse. Un plan solar empieza en la medianoche
local anterior para que un punto de luz muy al oeste reciba igualmente su tarde, y lo que en ese
intervalo ya ha pasado se registra como SKIPPED con el motivo PREDATES_CAMPAIGN, nunca se envía.
Cambiar una campaña
Esta versión no tiene operación de actualización. Para cambiar el disparador, los pasos, el objetivo o los límites de una campaña, elimínala y vuelve a crearla; el token queda libre en cuanto se elimina la campaña anterior. Como la nueva campaña no envía nada que venciera antes de crearse, recrearla poco después del anochecer no vuelve a atenuar las luces.
El tipo de paso ARTIFACT forma parte del vocabulario pero esta versión no lo ejecuta; se rechaza
con CAMPAIGN_STEP_UNSUPPORTED en lugar de ignorarse. Para desplegar una actualización según un
calendario, usa un despliegue gradual.
Disparadores
Todo disparador necesita una zona horaria IANA en zone. Una zona vacía, o Local, se rechaza: un
calendario que siguiera al host se movería cuando se mueva el pod.
Cron
{"kind":"CRON","zone":"America/New_York","cron":"30 18 * * *"}
Cinco campos: minuto, hora, día del mes, mes y día de la semana. Cada uno admite *, un número,
a-b, */n, a-b/n y listas separadas por comas. El día de la semana va de 0 a 7, con 0 y 7 como
domingo. Cuando ambos campos de día están restringidos, un día coincide si lo hace cualquiera de
los dos. Se rechazan los nombres, ?, L y @daily.
Calendario
{"kind":"CALENDAR","zone":"Europe/London","dates":["2026-12-24","2026-12-31"],"times":["07:00","17:30"]}
Se activa a cada hora en cada fecha indicada, en la zona.
Solar
{"kind":"SOLAR","zone":"Europe/Berlin","event":"SUNSET","offsetMinutes":-15}
Se activa en SUNSET o SUNRISE más offsetMinutes (negativo es antes), calculado por separado
para cada dispositivo a partir de su propia ubicación instalada. El mismo disparador se activa por
tanto en un instante distinto para cada luminaria, y las luces de una ciudad se atenúan en una ola
que sigue al sol.
La ubicación instalada es la posición instalada del dispositivo, registrada con la mutación
setInstalledPosition o con las columnas de posición instalada de una importación de flota:
mutation {
setInstalledPosition(family: DEVICE, token: "lamp-0001",
position: { latitude: 52.52, longitude: 13.40, source: SURVEY }) { latitude longitude }
}
Defínela al poner en servicio la luminaria. Deliberadamente no es la última posición notificada: una luminaria no se mueve, y una cuyo receptor falla no debe atenuarse en un ocaso equivocado. El cálculo es preciso a unos dos minutos entre aproximadamente 60 grados norte y sur.
Un evento solar no involucra ninguna zona horaria, porque el sol no la conoce. Aquí la zona solo indica a qué calendario civil pertenecen el día y los festivos.
Dos tipos de dispositivo se registran como omitidos en lugar de adivinarse:
- un dispositivo sin posición instalada se omite como
NO_SITE; - un dispositivo donde el sol no sale o no se pone ese día (dentro de los círculos polares) se omite
como
POLAR_DAYoPOLAR_NIGHT.
Si la campaña tiene un disparador solar y no pueden leerse en absoluto las ubicaciones de los
dispositivos, la planificación falla y el motivo se muestra en lastError de la campaña; no se
envía nada.
Festivos
Cualquier disparador puede llevar holidays, una lista de fechas locales en la zona en las que no se
activa:
{"kind":"SOLAR","zone":"Europe/Berlin","event":"SUNSET","holidays":["2026-12-24","2026-12-25"]}
Un festivo suprime una activación. Nunca la traslada a otro día.
Horario de verano
Una hora de cron o de calendario es hora de reloj en la zona. En los dos días al año en que eso es ambiguo:
- una hora dentro del salto de primavera se activa en el instante en que el reloj salta, una vez;
- una hora que ocurre dos veces en la hora del retroceso otoñal se activa solo en su primera ocurrencia.
Ventanas de mantenimiento
Una campaña no tiene una ventana propia. Cada comando que crea pasa por la misma puerta que cualquier
otro comando: un comando disruptivo a un dispositivo cuyo tipo tiene una
ventana de mantenimiento se retiene hasta que la ventana se abre, y se
rechaza de inmediato si la ventana se abre solo después de que el comando caducaría. Un comando
retenido cuenta como waiting en los recuentos del ciclo. Define expiresInSeconds lo bastante
largo para cubrir la espera que quieras permitir.
Qué ocurre si hay retraso o caída
El planificador se ejecuta cada 15 segundos en cada réplica, sin líder, y un dispositivo recibe el comando una sola vez sin importar cuántas réplicas estén en marcha o reiniciándose: la reclamación de cada elemento es una comparación y asignación en la base de datos, y el lote que crea lleva un token derivado de sus elementos, de modo que una réplica que termina el trabajo de otra caída repite el lote en lugar de duplicarlo.
Nunca se envía un comando pasado su límite de retraso. Un elemento que vence y no se reclama
dentro de maxLatenessSeconds (una caída, o la campaña estaba desactivada) se marca SKIPPED con
el motivo MISSED. Un comando de atenuación enviado a medianoche es peor que ninguno, así que una
campaña nunca se pone al día.
Tampoco envía un atraso acumulado. Cuando varias activaciones del mismo paso vencen a la vez para el
mismo dispositivo (una campaña horaria con un límite de retraso largo, tras una caída), solo se envía
la más reciente y las anteriores se registran como SKIPPED con el motivo SUPERSEDED. Un
dispositivo recibe un comando, no uno por cada hora perdida.
Desactivar una campaña detiene la planificación y el envío. Volver a activarla empieza desde ese
momento: lo que venció mientras estaba desactivada se registra como SKIPPED con el motivo
DISABLED, no se envía. Eliminarla cancela todo lo planificado y aún no enviado, como SKIPPED con
el motivo CANCELLED; los comandos ya creados no se tocan, y un elemento cuyo comando se estaba
enviando cuando se eliminó la campaña se registra a partir de ese comando, no como cancelado.
El tope de comandos sin entregar del tenant sigue aplicándose. Si una flota
muy grande vence en el mismo instante, los dispositivos que superan el tope se registran como
REFUSED con HELD_CEILING_EXCEEDED y pueden reintentarse.
Seguir un ciclo
query {
campaignCycles(campaignToken: "dusk-dim", limit: 3) {
key day resolved
counts { pending dispatched refused skipped succeeded inFlight waiting failed unknown }
}
}
counts responde a la pregunta de la mañana siguiente. Los primeros cinco números cuentan elementos
según el estado de la campaña: pending, claimed, dispatched, refused, skipped. El resto
cuenta los comandos detrás de los elementos enviados: succeeded, inFlight (de los cuales
waiting por una ventana), failed (terminaron sin éxito y es seguro reenviarlos) y unknown
(pueden haber actuado ya).
Para ver los dispositivos, recorre los elementos, opcionalmente por estado:
query {
campaignElements(campaignToken: "dusk-dim", cycleKey: "d2026-06-21", status: "SKIPPED", limit: 200) {
id deviceToken step dueAt status reason commandStatus commandOutcome
}
}
Pasa el último id como afterId para la página siguiente.
Reintentar lo fallido
mutation {
retryCampaignFailed(campaignToken: "dusk-dim", cycleKey: "d2026-06-21", includeUnknown: false) {
batches retried held
}
}
Esto entrega los elementos sin éxito del ciclo al reintento de lotes de la
plataforma, de modo que se aplican sus salvaguardas: a un dispositivo cuyo comando sigue en curso, o
que ya tuvo éxito, nunca se le envía una segunda copia, y a uno cuyo resultado es desconocido solo se
le envía si pasas includeUnknown: true, tras confirmar que actuar dos veces es inocuo. También se
reintentan los elementos que el lote rechazó. held cuenta los elementos que se dejan intactos
porque reenviar no es seguro.
Un elemento se reintenta una vez. Si el propio reintento falla, reintenta ese lote desde la API de lotes.
Límites
- Un ciclo planifica como máximo 100 000 dispositivos.
- Los dispositivos de un ciclo son los miembros del grupo en el momento en que se planifica el ciclo,
hasta 36 horas antes de que se active. Cuando el ciclo vence por primera vez se vuelve a leer el
grupo, y un dispositivo que lo haya abandonado desde entonces se registra como
SKIPPEDcon el motivoNOT_IN_GROUPen lugar de recibir el comando. Si en ese momento no se puede leer el grupo, el ciclo no se envía hasta que se pueda (y quedaMISSEDsi tarda más que el límite de retraso). Un dispositivo añadido al grupo después de planificarse el ciclo no se añade a él; se incorpora al siguiente ciclo que se planifique. - Los ciclos terminados y sus elementos se conservan durante 30 días.
- Un objetivo es un grupo de entidades. No se admite apuntar directamente a un área; usa un grupo dinámico que seleccione los dispositivos del área.
- Un paso es un comando. Esta versión no ejecuta pasos de actualización.