Dispositivos
Un dispositivo es una cosa física que se conecta a DeviceChain y envía datos: un termostato, un contador, un localizador. Este capítulo trata la lista de dispositivos, las formas de añadirlos (de uno en uno, en masa o desde un archivo CSV), la exportación de la lista, la deshabilitación de un dispositivo y cada pestaña de la página de un dispositivo.
Es para los usuarios y administradores del inquilino que registran y cuidan los dispositivos. Todo dispositivo pertenece a un tipo de dispositivo, así que necesitas al menos un tipo antes de añadir un dispositivo. Los tipos de dispositivo se tratan en el capítulo siguiente.
La lista de dispositivos
Abre Dispositivos en la barra lateral y luego Dispositivos dentro de él.
La lista muestra 20 dispositivos por página. Selecciona una fila para abrir la página de ese dispositivo. Las columnas son:
- Estado: si el dispositivo está conectado ahora mismo. En línea significa que está conectado o que ha enviado datos hace poco. Desconectado significa que su conexión informó de que se fue. Fuera de línea significa simplemente que hace un tiempo que no se sabe nada de él. Un guion significa que aún no se sabe nada: el dispositivo nunca ha enviado datos, o no tienes permiso para ver su estado.
- Token: el identificador único del dispositivo en este inquilino. No se puede cambiar.
- Nombre: un nombre legible. Un dispositivo deshabilitado lleva el distintivo Deshabilitado junto a su nombre.
- Tipo: el tipo de dispositivo, con los colores y el icono que se le dieron.
- Descripción y Creado.
Cómo decide DeviceChain si un dispositivo está en línea se explica en Presencia de dispositivo.
Añadir un dispositivo
Elige Nuevo dispositivo.
- Elige el Tipo de dispositivo.
- Escribe un Token, o usa el botón junto al campo para generar uno a partir del patrón de
tokens de tu instalación. El patrón se muestra bajo el campo.
{slug}se rellena a partir del nombre que escribas. - Escribe un Nombre y, si quieres, una Descripción.
- Si el dispositivo informa a través de un servidor de red LoRaWAN u otro remitente en lugar de conectarse por sí mismo, añade sus alias.
- Elige Crear dispositivo.
Un dispositivo nuevo que se conecta por sí mismo no puede enviar nada hasta que tenga una credencial. Añádela desde su pestaña Credenciales. Un dispositivo que informa a través de una integración de entrada necesita un alias en su lugar.
Alias
Un alias es el nombre con el que otro sistema conoce al dispositivo, como su DevEUI de LoRaWAN. El campo Alias del formulario del dispositivo admite hasta 8, un valor por esquema:
- Elige Añadir alias.
- Escoge el esquema: DevEUI de LoRaWAN (16 dígitos hexadecimales), Id de dispositivo del servidor de red (el id del dispositivo en The Things Stack) o Esquema propio (un nombre tuyo y un valor).
- Escribe el valor. Un DevEUI se guarda en mayúsculas, lo escribas como lo escribas.
Un alias pertenece a un solo dispositivo del inquilino. Una integración de entrada encuentra el dispositivo al que se refiere un mensaje por su alias. Consulta Integraciones de entrada.
Crear muchos dispositivos a la vez
Creación masiva crea un lote de dispositivos del mismo tipo, numerados en secuencia.
- Tipo de dispositivo: todos los dispositivos del lote reciben este tipo.
- Cantidad: cuántos dispositivos crear, de 1 a 1000.
- Índice inicial: el primer número que se usa.
- Plantilla de token: debe incluir
{n}, o{n:0Wd}para rellenar el número con ceros hasta el ancho W.device-{n:04d}dadevice-0001,device-0002, etc. - Plantilla de nombre (opcional): puede usar
{n}o{n:0Wd}. - Plantilla de ID externo (opcional): tu propio identificador de negocio para cada
dispositivo. También puede usar
{random}para un identificador aleatorio por dispositivo. Cuando creas más de un dispositivo, debe incluir{n},{n:0Wd}o{random}para que cada uno reciba un identificador distinto.
El recuadro Vista previa muestra los primeros y el último de los tokens y nombres que recibirá el lote. Revísalo y elige Crear N dispositivos.
Importar dispositivos desde un archivo CSV
Importar crea dispositivos a partir de un archivo CSV. Úsalo para cargar una flota que ya tienes en una hoja de cálculo, o un archivo que te entregó el fabricante.
- En Credenciales, elige Ninguna para crear solo los dispositivos, o Credenciales de fábrica para crear cada dispositivo junto con la credencial que tu fábrica le asignó.
- Elige un archivo con Elegir un archivo CSV, o pega las filas y elige Usar las filas pegadas. El archivo necesita una fila de cabecera y puede tener hasta 10.000 filas y 5 MiB.
- En Asigna las columnas, comprueba qué columna de tu archivo alimenta cada campo. La columna del token debe estar asignada, y cada fila necesita un tipo de dispositivo: asigna una columna de tipo o elige un Tipo de dispositivo para todo el archivo. Con Credenciales de fábrica, también deben estar asignadas las columnas del tipo y del id de la credencial. Una vista previa muestra las primeras filas tal como se enviarán.
- Elige Comprobar el archivo. Es un ensayo: el servidor decide cada fila exactamente como lo haría la importación real, y no crea nada.
- Lee Lo que haría una importación. Cada fila tiene un resultado: Creado, Ya existe, Conflicto, No válido o Rechazado, con detalles para lo que no se crearía. Puedes filtrar las filas por resultado.
- Elige Importar N dispositivos, donde N es el número de filas que, según la comprobación, se crearían. Una barra de progreso muestra cuánto lleva. Detener tras este lote se detiene limpiamente entre lotes. Si vuelves a importar el mismo archivo, continúa donde se detuvo.
- Al terminar, el resumen dice cuántos dispositivos se crearon, cuántos ya existían y cuántos requieren atención. Descargar resultados guarda el resultado de cada fila y Descargar filas fallidas guarda solo las filas que hay que corregir. Corrígelas e importa ese archivo. Los dispositivos ya creados aparecen como existentes y no se tocan.
Con Credenciales de fábrica, el archivo contiene secretos. Se envían una sola vez, nunca se muestran ni se escriben en los resultados, y se borran de la página cuando termina la importación. El archivo en sí queda bajo tu responsabilidad.
Las columnas, los modos de credenciales y todos los resultados se describen en detalle en Importar dispositivos desde CSV.
Exportar la lista
Exportar CSV descarga todos los dispositivos de la lista en un archivo CSV. El archivo contiene el token, el nombre, el tipo, el token del tipo, la descripción y la fecha de creación de cada dispositivo, con las horas en formato ISO-8601. No incluye el estado en vivo. Las cabeceras coinciden con lo que espera Importar, así que un archivo exportado se puede volver a importar tal cual.
Mientras se exporta, el botón muestra cuántas filas lleva reunidas, junto a un botón Cancelar exportación. Un mensaje confirma cuántas filas se exportaron. Una exportación se detiene en 10.000 filas; si llega a ese límite, la consola te avisa de que el archivo contiene solo las primeras 10.000.
Deshabilitar y habilitar un dispositivo
Deshabilitar un dispositivo lo deja fuera sin eliminarlo. Úsalo para poner en cuarentena un dispositivo que se comporta mal o que puede estar comprometido, y vuelve a habilitarlo cuando esté corregido.
Abre el dispositivo y elige Deshabilitar arriba a la derecha. La consola te pide confirmación. Mientras el dispositivo está deshabilitado:
- sus eventos se descartan en lugar de almacenarse, y no se recuperan al volver a habilitarlo;
- no puede abrir una conexión nueva, y una conexión que ya tenga se cierra (si la plataforma no puede confirmarlo, la deshabilitación queda guardada y se te indica que la repitas). Cuando esa conexión termina, el dispositivo aparece como desconectado;
- los comandos nuevos que se le envían se rechazan;
- los comandos que ya estaban en cola para él quedan retenidos: ni se envían ni se cancelan.
Sus datos, credenciales y configuración se conservan. Un dispositivo deshabilitado lleva el distintivo Deshabilitado en su página y en la lista de dispositivos.
Cuando hay comandos retenidos, la pestaña Comandos del dispositivo indica cuántos, por ejemplo «2 comandos en cola retenidos mientras este dispositivo está deshabilitado». Salen, del más antiguo al más reciente, cuando habilitas el dispositivo, o caducan a su propia hora de vencimiento. Si no deben enviarse nunca, elige Cancelar todos. Un comando que ya se envió no se puede recuperar.
Para recuperar el dispositivo, elige Habilitar. Sus eventos vuelven a almacenarse y puede conectarse y recibir comandos.
La lista completa de lo que hace la deshabilitación, incluidas la configuración y las alarmas, está en Deshabilitar un dispositivo.
Qué hace la eliminación de un dispositivo
La eliminación de un dispositivo no se puede deshacer. El dispositivo, sus credenciales, alias, atributos, pertenencias a grupos y relaciones se eliminan de inmediato, y su token queda libre: puedes crear un dispositivo nuevo con el mismo token. El dispositivo nuevo no hereda ninguno de los registros del anterior:
- El estado en vivo, las últimas lecturas y la posición se eliminan. Los miembros del propietario del dispositivo nuevo no ven la última posición ni las lecturas del anterior.
- Los comandos que la plataforma aún tenía para el dispositivo anterior (en cola, retenidos o aparcados) se cancelan. Un comando creado para el dispositivo anterior nunca se envía al nuevo, ni siquiera uno ya entregado a un transporte y aún no confirmado. Los comandos que envíes al dispositivo nuevo salen con normalidad.
- Las asignaciones de actualización pendientes del dispositivo anterior terminan, y sus objetivos de despliegue se muestran como cancelados. Al dispositivo nuevo no se le ofrecen ni puede descargar sus artefactos.
- Las alarmas del dispositivo anterior se eliminan, y sus reglas de detección olvidan su estado, de modo que la primera lectura del dispositivo nuevo que cumpla una regla genera una alarma nueva. Cada alarma que seguía activa termina con un despeje que indica que se eliminó el dispositivo, así que sus notificaciones dejan de escalar.
- El historial de eventos se conserva. Los eventos que la plataforma recibió del dispositivo anterior siguen almacenados, pero dejan de aparecer bajo el cliente, el área o el activo al que pertenecía. Los eventos que envía el dispositivo nuevo aparecen con normalidad, aunque los informe con una hora anterior a la eliminación.
Los servicios se enteran de una eliminación a través del broker de mensajes. Si el broker no está disponible, la eliminación se completa igualmente y los demás servicios se ponen al día cuando vuelve. Hasta entonces, los registros del dispositivo anterior pueden seguir visibles.
También se tratan los registros que dejaron eliminaciones anteriores a esta versión. Una comprobación periódica elimina el estado en vivo de los dispositivos que ya no existen, y una asignación de actualización hecha para un dispositivo anterior con el mismo token no se ofrece al dispositivo que lo tiene ahora. Los comandos se cancelan para las eliminaciones que el broker de mensajes aún conserva cuando el servicio actualizado arranca por primera vez, lo que cubre los últimos días. Un comando en espera de una eliminación más antigua se cancela en lugar de enviarse si es anterior al dispositivo que ahora tiene su token.
Límites
- Una lectura que la plataforma aceptó antes de la eliminación pero procesó después puede recuperar brevemente el estado en vivo del dispositivo anterior. Si ningún dispositivo tiene el token, la comprobación periódica lo elimina. Si se creó un dispositivo nuevo con ese token, su primera lectura lo sustituye, y una lectura del dispositivo anterior nunca se aplica al nuevo.
- Antes de volver a enviar una notificación de una alarma, la plataforma comprueba que la alarma sigue existiendo. Si esa comprobación falla, la notificación se envía igualmente, para que una caída no silencie una alarma real. Consulta Alarmas de un dispositivo eliminado.
- Durante una actualización, mientras conviven versiones antiguas y nuevas de los servicios, una eliminación que atiende una versión antigua sigue el comportamiento anterior hasta que esa versión se sustituye. Consulta Versiones y actualizaciones.
La página del dispositivo
Selecciona un dispositivo en la lista para abrir su página. La cabecera muestra el nombre del dispositivo, su token (con un botón para copiarlo), su tipo y, si está deshabilitado, el distintivo Deshabilitado. A la derecha están Deshabilitar (o Habilitar) y Eliminar. Eliminar un dispositivo no se puede deshacer.
La página se organiza en pestañas. Puede que no las veas todas: Credenciales, Enviar datos y
Sustitución requieren permiso para modificar dispositivos, y Actualizaciones solo aparece
cuando tu instalación ejecuta el servicio de actualizaciones y tienes permiso para verlas. Alarmas
requiere alarm:read. Los miembros limitados a una parte del inquilino no ven Asignación,
Pasarela, Facetas ni Configuración.
Básico
Básico contiene el tipo, el token, el nombre y la descripción del dispositivo.
Puedes cambiar el tipo, el nombre y la descripción y elegir Guardar cambios. El token no se puede cambiar.
Asignación
Asignación vincula el dispositivo con el cliente, el área o el activo al que sirve. Organiza los datos del dispositivo, pero no decide si puede enviar datos: un dispositivo sin asignación sigue enviándolos.
Elige un Tipo de destino (Cliente, Área o Activo), selecciona el Destino y elige Asignar. Un dispositivo puede tener varias asignaciones a la vez. Desasignar quita una. Los eventos que el dispositivo ya envió conservan las asignaciones con las que se registraron.
Consulta Gestión de asignaciones de dispositivos.
Pasarela
Pasarela muestra la pasarela detrás de la que está este dispositivo y los dispositivos que están detrás de él. Con permiso para modificar dispositivos, introduce un Token del dispositivo pasarela y elige Asignar pasarela, o Mover para cambiar una pasarela existente. Quitar pasarela elimina la relación; la siguiente publicación de la antigua pasarela para este dispositivo se rechaza. Una pasarela no puede estar a su vez detrás de otra pasarela.
Facetas
Facetas contiene los valores que describen el dispositivo, como la zona o la planta en la que está. Explorar y los grupos dinámicos encuentran dispositivos por estos valores.
- Valores de faceta enumera las facetas que tu inquilino ha declarado. Escribe un valor y elige Guardar, o Limpiar para quitarlo. Cuando un valor decide la pertenencia a un grupo dinámico, la pestaña te dice de qué grupos entraría o saldría el dispositivo con el cambio.
- Otros atributos enumera todo lo demás que se guarda en el dispositivo. Puedes añadir un atributo compartido con Añadir atributo y eliminarlo. Los valores que informa el dispositivo (CLIENT) o que fija la plataforma (SERVER) se muestran solo como referencia. Los atributos compartidos son también donde viven los valores de la configuración del dispositivo.
Las facetas y Explorar tienen su propio capítulo.
Conectividad
Conectividad muestra si el dispositivo está conectado y sus lecturas más recientes.
- El distintivo dice En línea, Desconectado o Fuera de línea.
- Origen de la presencia indica cómo se sabe. Reportado por el transporte significa que la propia conexión se lo comunicó a DeviceChain. Inferido a partir de la actividad significa que DeviceChain lo dedujo de lo reciente que es el último envío del dispositivo.
- Última conexión, Última actividad y Última desconexión dan las horas.
- Últimas lecturas enumera el último valor de cada medición y cuándo llegó.
Cuando un dispositivo inferido se queda callado, la pestaña añade la nota «Sin actividad reciente»: hace un tiempo que no envía nada, algo que también puede parecer un dispositivo sano con un intervalo de envío lento.
Un dispositivo cuyo perfil declara una posición, o que ya ha informado de una, tiene además una sección Última posición conocida, con su latitud, longitud y, cuando se informan, la elevación, la precisión, la velocidad y el rumbo. El termostato de la captura no cumple ninguna de las dos condiciones, así que la sección no aparece.
Eventos
Eventos enumera los 10 eventos más recientes que envió el dispositivo.
Cada fila muestra cuándo ocurrió el evento, su tipo (por ejemplo, una medición) y el origen por el que llegó. Para un historial más largo, usa un panel.
Alarmas
Alarmas enumera las alarmas generadas en este dispositivo, 10 por página, y se actualiza cada
30 segundos. Con alarm:write, puedes reconocer aquí una alarma activa que aún no se haya reconocido.
El enlace situado sobre la tabla abre la lista de alarmas del inquilino para las demás acciones.
Comandos
Comandos es donde envías un comando a este dispositivo concreto y sigues los comandos que ya se le enviaron.
El selector Comando ofrece los comandos que declara el perfil del dispositivo. Elige uno y la consola muestra un formulario para sus parámetros.
Rellena los parámetros y elige Emitir comando. El formulario comprueba cada valor con el perfil, por ejemplo el rango permitido, antes de enviar nada. Si el perfil no declara comandos, puedes escribir cualquier nombre de comando y, opcionalmente, una carga útil.
La tabla de abajo enumera los comandos del dispositivo con su estado, como QUEUED, SENT o SUCCESSFUL, y el resultado que informó el dispositivo. Los estados se muestran en inglés, también en la consola en español. Un comando que aún no ha llegado al dispositivo (QUEUED, HELD o PARKED) tiene un botón Cancelar. Un comando ya enviado no se puede cancelar.
Qué significa cada estado se explica en Comandos, y Enviar un comando cubre cómo enviar uno y seguirlo. Para enviar un comando a muchos dispositivos a la vez, usa un lote de comandos.
Configuración
Configuración muestra los ajustes que DeviceChain guarda para que el dispositivo los aplique, y si el dispositivo ya los aplicó.
La configuración de un dispositivo es un pequeño documento construido a partir de sus atributos compartidos. Solo se incluyen las claves que declara su perfil. Cada cambio crea una nueva revisión numerada, que se envía al dispositivo.
- El distintivo de arriba dice si el dispositivo está al día. Sincronizado significa que aplicó la última revisión. Pendiente significa que hay una revisión esperando a aplicarse. Desactualizado significa que los valores cambiaron desde la última revisión. Se crea una revisión nueva la próxima vez que se escribe una clave declarada o que el dispositivo se sincroniza. Sin revisión todavía significa que aún no se creó ninguna.
- Revisión deseada es la última, y Revisión informada es la que el dispositivo dijo tener por última vez. Estado del informe es lo que hizo el dispositivo con ella: Recibida, Aplicada o Rechazada. Cuando el dispositivo rechaza una configuración, se enumeran sus motivos.
- Claves declaradas enumera las claves que declara el perfil, tomadas de su versión publicada activa. Sus valores se cambian como atributos compartidos en la pestaña Facetas.
- Atributos compartidos no declarados son atributos compartidos que el perfil no nombra. Nunca se envían al dispositivo.
- Documento deseado es el documento exacto que se envía al dispositivo.
- Historial de revisiones enumera las revisiones del dispositivo, de la más reciente a la más antigua, y quién hizo cada una.
Puedes devolver un dispositivo a una configuración anterior o darle la de otro dispositivo. En los dos casos la consola muestra primero una vista previa, y nada cambia hasta que eliges Aplicar.
Para restaurar una revisión anterior, elige Restaurar en su fila del Historial de revisiones.
Para copiar la configuración de otro dispositivo, elígelo en Copiar de otro dispositivo y elige Previsualizar cambios. La copia toma la última revisión de ese dispositivo.
La vista previa enumera cada clave con su valor Actual, el valor que tendrá Después y si queda Añadida, Cambiada o Eliminada. Al aplicar se crea una revisión nueva y se envía al dispositivo. Las revisiones anteriores no se modifican. El cambio se rechaza si el perfil de este dispositivo no declara todas las claves que lleva la configuración.
Cómo recibe un dispositivo su configuración y cómo informa de ella se describe en Restaurar o copiar una configuración.
Actualizaciones
Actualizaciones muestra la actualización remota (OTA) asignada al dispositivo y su historial de actualizaciones. Se trata en el capítulo de actualizaciones remotas.
Credenciales
Credenciales contiene lo que usa el dispositivo para demostrar quién es al conectarse.
Hay tres tipos:
- ACCESS_TOKEN: el dispositivo presenta un token. Pega el tuyo o elige Generar.
- MQTT_BASIC: el dispositivo se conecta con un usuario y una contraseña.
- X509_CERTIFICATE: el dispositivo presenta un certificado de cliente. Registras el certificado y nombras el ancla de confianza con la que debe encadenar (consulta Aprovisionamiento y anclas de confianza).
Elige el Tipo, rellena los campos y elige Agregar credencial. Un dispositivo puede tener más de una credencial. Eliminar quita una, y después el dispositivo ya no puede autenticarse con ella.
Una contraseña MQTT solo se muestra una vez: justo después de añadir la credencial, o después de elegir Establecer nueva contraseña para cambiarla. La plataforma solo guarda un resumen de un solo sentido, así que nunca puede volver a mostrar la contraseña.
Copia la contraseña, dásela al dispositivo y elige Listo. Cuando estableces una contraseña nueva, la anterior deja de funcionar en cuanto guardas.
Consulta Credenciales de dispositivo.
Enviar datos
Enviar datos construye un comando listo para ejecutar que envía la primera medición del
dispositivo: un mosquitto_pub para MQTT o un curl para HTTP. Elige el transporte, y la
credencial si el dispositivo tiene más de una, y copia el comando con el botón de copiar.
El comando usa el token y la credencial del dispositivo (para un token de acceso muestra <access-token> en lugar del token, que la consola no puede leer de nuevo: pega el que emitiste, o sustituye el token si lo perdiste), y las métricas de la versión
publicada de su perfil, con valores de ejemplo que el perfil acepta. Una métrica que solo
existe en el borrador no se usa, porque la plataforma comprueba las lecturas contra la versión
publicada. Cuando la versión publicada no tiene ninguna métrica que el ejemplo pueda usar, el
comando envía en su lugar una lectura no declarada, que se almacena siempre que su valor sea un
número. Se incluyen como máximo ocho métricas.
Los comandos están escritos para un shell POSIX como bash o zsh. En Windows, ejecútalos en WSL o
Git Bash: PowerShell y cmd.exe interpretan de otra forma las comillas y los saltos de línea, así
que el comando no enviaría lo que muestra.
La consola no puede conocer algunos valores, así que el comando deja un marcador para cada uno:
| Marcador | Sustitúyelo por |
|---|---|
<instance-id> | El id de instancia elegido al instalar la instancia. Es el espacio de nombres de Kubernetes de la instancia sin el prefijo dci-. |
<mqtt-host> | El host en el que se expone el listener MQTT. El listener usa TLS, así que guarda el certificado de la CA de la instancia como instance-ca.crt. |
<ingest-host> | El host del listener de ingesta HTTP, puerto 8081. Una instalación predeterminada no lo expone fuera del clúster, salvo el webhook de integración entrante en /api/integrations/{tenant}/{integration} de la dirección HTTPS de la instancia; consulta Tu primer dispositivo. |
<password> | La contraseña de una credencial MQTT_BASIC. Solo se muestra una vez, al establecerla. Si la has perdido, establece una nueva en la pestaña Credenciales. |
La pestaña no ofrece ningún comando cuando el comando no podría funcionar, y en su lugar indica qué corregir:
- El dispositivo está deshabilitado. Los eventos de un dispositivo deshabilitado se descartan al llegar.
- El dispositivo no tiene ninguna credencial habilitada y sin caducar. Por defecto, la plataforma exige una credencial en cada conexión y en cada evento. Añade una primero en la pestaña Credenciales.
Un dispositivo que no está asignado a nada puede enviar datos; sus eventos se almacenan.
Como Credenciales, la pestaña requiere permiso para modificar dispositivos.
Un 202 de HTTP, o un acuse de recibo MQTT, significa que el evento se recibió, no que se
almacenó. Búscalo en la pestaña Eventos.
Consulta Conectar un dispositivo.
Sustitución
Sustitución sirve para cambiar el hardware: una unidad falló y otra ocupa su lugar. El dispositivo conserva su identidad, su historial, sus alarmas, sus asignaciones y su pertenencia a grupos. Solo cambian las credenciales.
- Escribe el Motivo. Queda registrado en el historial de mantenimiento.
- Escribe el Identificador de la unidad nueva: el número de serie o el IMEI del hardware nuevo. Queda registrado en el historial. El ID externo del dispositivo no cambia.
- Elige Sustituir unidad y confirma.
Todas las credenciales que podía usar la unidad anterior se deshabilitan, y se emite una credencial nueva para la unidad nueva. La credencial nueva se muestra una sola vez, así que cópiala antes de elegir Listo. No se puede recuperar desde el historial.
La tabla de abajo enumera las sustituciones anteriores: cuándo, quién, por qué, la unidad nueva y cuántas credenciales se retiraron.