Esta página es para administradores e integradores que cambian la configuración de dispositivos desde Hermetry, a mano o a través de la API, en un dispositivo o en muchos. Explica las reglas que hay detrás de la pestaña Settings y cómo usarlas con seguridad. Cómo abrir la pestaña, crear líneas base e iniciar trabajos se explica en Remote device settings; las rutas están en Firmware and device settings API.
Valores deseados y valores reportados
Para cada sección de configuración de un dispositivo, Hermetry mantiene dos documentos:
- Deseado: lo que Hermetry pidió por última vez que ejecute el dispositivo, con un número de revisión que aumenta con cada cambio.
- Reportado: lo que el dispositivo dice que ejecuta, con la revisión que aplicó.
Cada cambio envía la sección completa al dispositivo, no solo las claves que cambiaron. El dispositivo aplica una sección solo cuando su revisión es superior a la última que aplicó. Una sección que esperó demasiado al dispositivo se retira; entonces el dispositivo conserva la configuración que tiene.
| Estado en la pestaña Settings | Significado |
|---|---|
| En camino | Enviado, o esperando a que el dispositivo se conecte |
| El dispositivo lo está probando | El dispositivo ejecuta el cambio en modo de prueba y lo deshace por sí mismo si no puede volver a alcanzar la nube |
| Aplicado | El dispositivo ejecuta el cambio |
| Deshecho por el dispositivo | El dispositivo lo probó y volvió atrás |
| Rechazado por el dispositivo | El dispositivo no lo aceptó |
| El dispositivo estaba sin conexión | El cambio esperó demasiado (7 días para un único cambio) y se retiró |
| Revisar tras la actualización | Una actualización de firmware cambió la descripción de la sección; una persona debe revisarla y guardar |
| Cambiado en el dispositivo | Desviación: el dispositivo ejecuta otros valores de los que pidió Hermetry (véase abajo) |
| No cambiado desde aquí | Hermetry nunca estableció esta sección; solo muestra lo que informa el dispositivo |
Cómo se construye un cambio
Hay dos formas de escribir una sección, y tratan de forma distinta lo que se omite.
| Forma | Usada por | Lo que se envía |
|---|---|---|
| Sección completa | La pestaña Settings, PUT | Cada valor de la sección. Lo que se omite no forma parte de la nueva sección. |
| Parche de fusión | PATCH, líneas base, trabajos de configuración | Solo lo que cambia, como parche de fusión JSON (RFC 7386) |
Un parche de fusión sigue exactamente estas reglas:
- Los objetos se fusionan clave a clave. Una clave que no nombras conserva su valor.
nullelimina la clave.- Cualquier otro valor reemplaza por completo al anterior. Una lista siempre se reemplaza completa: para cambiar una entrada de una lista, envía la lista completa.
El parche se aplica sobre el último documento deseado de la sección, no sobre lo que reporta el dispositivo. Solo cuando Hermetry nunca ha establecido la sección un parche parte de los valores reportados; si el dispositivo tampoco ha reportado todavía la sección, la escritura se rechaza (section_not_reported).
Buenas prácticas:
- Incluye en una línea base solo lo que quieres cambiar. Todo lo demás se mantiene como está en cada dispositivo.
- No pongas nunca
nullen una línea base salvo que la clave deba desaparecer de todos los dispositivos del trabajo. - Mantén fuera de las líneas base las listas específicas de cada dispositivo (por ejemplo, listas de direcciones que difieren por sede): la lista de la línea base reemplaza la lista de cada dispositivo.
- Los ajustes que la descripción marca como modificables solo en el dispositivo se mantienen según el informe del dispositivo. Un cambio en ellos se rechaza (
remote_forbidden). - Usa
?dryRun=true(o Check en un trabajo) para ver qué ajustes toca un cambio y si necesita confirmación, antes de que se envíe nada.
Revisiones y If-Match
Al leer una sección, se devuelve su revisión deseada como cabecera ETag, con la forma W/"7". Cada escritura debe devolver esa revisión en If-Match; "7" y 7 también se aceptan.
| Respuesta | Significado |
|---|---|
428 if_match_required | La escritura no tenía If-Match |
412 rev_mismatch | Alguien cambió la sección después de que la leyeras |
Ante un 412, vuelve a leer la sección, reconstruye tu cambio sobre el nuevo documento y escribe de nuevo. No copies la nueva revisión en la cabecera y reenvíes el documento antiguo: eso sobrescribe el cambio de la otra persona. La pestaña Settings hace la misma comprobación (“Alguien más ha cambiado estos ajustes desde que los abriste. Vuelve a cargarlos para ver la última versión.”).
Desviación
Una sección tiene desviación cuando el dispositivo aplicó un cambio de Hermetry y después informa de valores distintos, normalmente porque alguien lo cambió en el propio dispositivo. La pestaña muestra “Cambiado en el dispositivo” y qué difiere. Hermetry no corrige la desviación por sí mismo. Tú eliges:
| Acción | Efecto |
|---|---|
| Enviar los nuestros de nuevo | Envía de nuevo los valores deseados de Hermetry como una nueva revisión |
| Conservar los del dispositivo | Guarda los valores actuales del dispositivo como nuevos valores deseados |
Resuelve la desviación antes de cambiar de otra forma una sección desviada. Un parche de fusión, y por tanto un trabajo de configuración, parte del último documento deseado, así que también devuelve los valores de Hermetry para los ajustes desviados.
Decide quién es responsable de cada ajuste. Si los técnicos en sitio deben poder cambiar algo, mantenlo fuera de las líneas base y de los trabajos.
Secretos
- Los ajustes secretos (contraseñas, claves) nunca se muestran ni se devuelven. Se leen como
{ "set": true }. - Un secreto nuevo llega al dispositivo como referencia de un solo uso. El dispositivo obtiene el valor una vez mediante una petición firmada; una referencia que no se obtiene caduca a los 30 días. Un dispositivo cuyo firmware no puede obtener referencias no recibe ningún secreto: el cambio se rechaza (
secret_ref_unsupported). - Para conservar el secreto actual del dispositivo, deja el campo sin cambios (en la API,
{ "$keep": true }). - Las líneas base no pueden contener secretos (
secret_not_allowed). Establécelos en cada dispositivo. secret_pending: un cambio anterior lleva un secreto que el dispositivo todavía no ha obtenido. Espera, o introduce el secreto de nuevo.secrets_need_rewriteal pulsar Enviar de nuevo: el cambio lleva secretos que el dispositivo ya no puede obtener. Introdúcelos de nuevo y guarda.
Trabajos de configuración
Un trabajo aplica una línea base, o un solo cambio, a muchos dispositivos por oleadas. Buenas prácticas:
- Selecciona por modelo y firmware que hayas probado. El paso Check muestra los dispositivos por modelo y firmware, y las secciones que un modelo no tiene.
- Mantén las oleadas. Por defecto son 1 %, luego 10 % y después el resto. La primera oleada es una muestra aleatoria fija y representativa de los dispositivos seleccionados.
- Entiende el filtro. Una oleada se supera cuando, entre los dispositivos que respondieron, al menos el 95 % aplicó el cambio y como máximo el 1 % lo deshizo (los valores por defecto). Los dispositivos que rechazaron cuentan entre los que respondieron, así que bajan el porcentaje de aplicados. Los dispositivos aún sin conexión no cuentan. Una oleada se evalúa cuando todos sus dispositivos han respondido, o 30 minutos después de empezar (por defecto), con los dispositivos que hayan respondido hasta entonces; los demás continúan en segundo plano. Una oleada superada inicia la siguiente de inmediato, sin tiempo de espera. Una oleada en la que ningún dispositivo respondió pausa el trabajo.
- Elige qué ocurre ante un conflicto. Solo puede haber un cambio en curso a la vez en la sección de un dispositivo. Un trabajo espera el cambio de otro trabajo (y omite el dispositivo tras 24 horas) u omite el dispositivo de inmediato. Un cambio que una persona haga mientras el trabajo espera prevalece.
- Define cuánto esperar a los dispositivos sin conexión: 7 días por defecto, de 1 a 90.
- Recuerda que cancelar no deshace los cambios. Los dispositivos ya cambiados conservan su nueva configuración.
Un trabajo escribe con los permisos que tenía su creador, y un trabajo que cambia ajustes peligrosos debe confirmarse al crearse. Como máximo 5 trabajos se ejecutan o esperan en pausa a la vez, un trabajo abarca hasta 5.000 dispositivos y envía cambios a un máximo de 200 dispositivos por minuto.
Actualizaciones de firmware y firmware antiguo
- Después de una actualización de firmware, Hermetry convierte los valores deseados almacenados a la descripción de ajustes del nuevo firmware. Lo que no puede convertir de forma segura se marca como «Check after update». La sección permanece en ese estado hasta que una persona la guarda; los informes del dispositivo no la cierran, y un trabajo considera rechazado a ese dispositivo.
- Ventana de soporte: las escrituras de ajustes se detienen 24 meses después de la fecha de publicación del firmware del dispositivo, según consta en su descripción de ajustes. Los ajustes siguen siendo legibles («Read only: update the firmware to change settings»). Una escritura responde
409firmware_too_oldcon la fecha en que terminó la ventana. - Un trabajo no excluye de antemano a estos dispositivos. Se rechazan cuando llega su turno y cuentan contra la puerta de la oleada. Actualice primero su firmware o exclúyalos de la selección.
Frecuencia de cambios
Los cambios individuales desde la pestaña Settings y la API, incluido Send again, están limitados a 600 por minuto por organización; por encima de eso, 429 write_rate_limited. Las escrituras propias de un trabajo a sus dispositivos no cuentan para este límite.

