Enviar uplinks de ChirpStack a DeviceChain
ChirpStack v4 reenvía lo que oyen sus pasarelas mediante una integración HTTP en una aplicación: publica cada evento en la URL que le indiques, en JSON. DeviceChain recibe esas peticiones con una integración de entrada de tipo de remitente ChirpStack v4, encuentra el dispositivo por su DevEUI y guarda las lecturas como mediciones de ese dispositivo. A partir de ahí alimentan paneles, reglas de detección y alarmas como cualquier otra medición.
El tipo de remitente ChirpStack v4 lee el formato de evento propio de ChirpStack. No escribes ningún adaptador, y un decodificador nunca tiene que desenvolver el sobre de ChirpStack: la plataforma toma el DevEUI de deviceInfo.devEui, la hora de time, el objeto decodificado de object, la trama sin procesar de data y el puerto y el contador de fPort y fCnt.
Lo que queda por decidir es dónde se decodifica la trama:
| Opción A: decodifica ChirpStack | Opción B: decodifica DeviceChain | |
|---|---|---|
| Dónde vive la disposición de los bytes | Un códec JavaScript en el perfil de dispositivo de ChirpStack | Un decodificador de carga útil en el perfil de dispositivo de DeviceChain |
| Qué guarda DeviceChain | Los números y booleanos del object de ChirpStack | Lo que produce el decodificador a partir de data |
| Versiones y pruebas | Las de ChirpStack | Se publica con el perfil, con vectores de prueba guardados que deben pasar antes de poder publicarlo |
Las dos usan la misma integración y la misma configuración de ChirpStack. Los pasos son iguales hasta el paso 5, donde eliges una.
Antes de empezar
- Un servidor ChirpStack v4 con una aplicación, un perfil de dispositivo y dispositivos que ya se han unido a la red. Necesitas el DevEUI de cada dispositivo.
- Una instancia de DeviceChain que ChirpStack pueda alcanzar por HTTPS. A un ChirpStack que gestionas tú se le puede dar la CA de tu instancia; uno alojado por terceros necesita que la instancia tenga un certificado de una CA pública.
- Un miembro del inquilino con el permiso
device:write. Los pasos de consola usan la consola del inquilino; cada paso tiene también su forma en GraphQL, que se envía ahttps://<host>/api/device-management/graphqlcon un token de acceso del inquilino en la cabeceraAuthorization: Bearer(cómo obtener uno).
1. Un tipo de dispositivo para los sensores
La integración solo puede alcanzar dispositivos de los tipos de dispositivo a los que la limitas, así que empieza por un tipo de dispositivo y su perfil. Declara una métrica por cada valor que informa el sensor, con la clave que tendrá el valor decodificado: la métrica da a la lectura su unidad y su validación. Esta guía usa un sensor de sala que informa una temperatura, una humedad, la tensión de la batería en milivoltios y un contacto de puerta:
| Clave de la métrica | Tipo de datos | Unidad |
|---|---|---|
temperature | Double | Cel |
humidity | Double | % |
battery | Integer | mV |
door | Boolean |
En la consola, crea el perfil y sus métricas como se describe en Tipos y perfiles de dispositivo, crea un tipo de dispositivo que use el perfil y publica el perfil. Con GraphQL, envíalo en dos peticiones, porque una mutación puede seleccionar como máximo cinco campos raíz y con un sexto se rechaza la petición entera:
mutation {
createDeviceProfile(request: { token: "room-sensor", name: "Room sensor", category: "sensor" }) { token }
temperature: createMetricDefinition(request: { token: "room-sensor-temperature", deviceProfileToken: "room-sensor", metricKey: "temperature", name: "Temperature", dataType: "DOUBLE", unit: "Cel" }) { metricKey }
humidity: createMetricDefinition(request: { token: "room-sensor-humidity", deviceProfileToken: "room-sensor", metricKey: "humidity", name: "Humidity", dataType: "DOUBLE", unit: "%" }) { metricKey }
battery: createMetricDefinition(request: { token: "room-sensor-battery", deviceProfileToken: "room-sensor", metricKey: "battery", name: "Battery", dataType: "INT", unit: "mV" }) { metricKey }
door: createMetricDefinition(request: { token: "room-sensor-door", deviceProfileToken: "room-sensor", metricKey: "door", name: "Door", dataType: "BOOLEAN" }) { metricKey }
}
mutation {
createDeviceType(request: { token: "room-sensor", name: "Room sensor", profileToken: "room-sensor" }) { token }
}
Si eliges la opción B, añade el decodificador antes de publicar; si no, publica ahora:
mutation { publishDeviceProfile(token: "room-sensor", label: "metrics") { version } }
Una clave decodificada sin métrica se guarda igualmente, sin unidad.
2. Crea la integración
En la consola, abre Conectar → Integraciones y elige Nueva integración:
- Tipo de remitente: ChirpStack v4. No se puede cambiar después.
- Token: el nombre de la integración en la URL, como
chirpstack-eu868. No se puede cambiar después. - Tipos de dispositivo:
Room sensor. - Identificador del dispositivo: DevEUI.
- Guardar métricas del enlace: actívalo si quieres guardar junto a las lecturas de cada uplink la intensidad de señal, la relación señal-ruido y el número de pasarelas, como
lorawan.rssi,lorawan.snrylorawan.gateways.
Elige Crear integración. El diálogo Integración creada muestra el token de portador una sola vez. Cópialo ahora: solo se guarda como un resumen y no se puede volver a mostrar. Si lo pierdes, Rotar token emite uno nuevo y el anterior deja de funcionar de inmediato.
Con GraphQL, createIntegration devuelve el token en issuedToken:
mutation {
createIntegration(request: {
token: "chirpstack-eu868"
name: "ChirpStack EU868"
type: "CHIRPSTACK_V4"
enabled: true
deviceTypeTokens: ["room-sensor"]
identity: "DEV_EUI"
linkMetrics: true
}) {
integration { token type identity }
issuedToken
}
}
La dirección de la integración es:
https://<host>/api/integrations/<tenant>/<integration>
<host> es el host en el que abres la consola, <tenant> es el token de tu inquilino e <integration> es el token de la integración. La página de la integración en la consola muestra la URL completa en Conectar el remitente, con un botón de copia.
3. Añade la integración HTTP en ChirpStack
En la interfaz web de ChirpStack, abre la aplicación, ve a Integrations y añade la integración HTTP:
| Ajuste de ChirpStack | Valor |
|---|---|
| Payload encoding | JSON. DeviceChain rechaza la codificación Protobuf con 415. |
| Event endpoint URL(s) | https://<host>/api/integrations/<tenant>/<integration>, sin nada detrás. ChirpStack añade por sí mismo ?event=up (u otro nombre de evento) a cada petición. |
| Headers | Una cabecera: nombre Authorization, valor Bearer <bearer-token>. |
Guárdala. A partir de ese momento ChirpStack publica en DeviceChain cada evento de los dispositivos de la aplicación. Solo se guardan los eventos up. join, status, log y los demás eventos se responden con 204 y se ignoran, y ack y txack solo se leen cuando el operador ha activado el downlink LoRaWAN, así que puedes dejar todos los eventos activados.
El token se envía solo en la cabecera. No lo pongas en la URL, donde quedaría escrito en los registros de acceso.
4. Registra los dispositivos por DevEUI
DeviceChain encuentra el dispositivo al que se refiere un uplink mediante un alias de dispositivo que contiene su DevEUI. Crea un dispositivo del tipo del paso 1 para cada sensor, con el alias lorawan.deveui. En la consola, usa el campo Alias del formulario del dispositivo: Añadir alias, DevEUI LoRaWAN y los 16 dígitos hexadecimales. Da igual mayúsculas o minúsculas. Con GraphQL:
mutation {
createDevice(request: {
token: "room-4"
name: "Room 4"
deviceTypeToken: "room-sensor"
aliases: [{ scheme: "lorawan.deveui", value: "70B3D57ED0050004" }]
}) { token aliases { scheme value } }
}
También puedes dejar que los sensores te lo digan. Un uplink cuyo DevEUI no tiene ningún dispositivo de los tipos de la integración no se guarda, y su DevEUI aparece en la página de la integración en Dispositivos no registrados vistos. Crear un dispositivo con este alias abre el formulario del dispositivo con el DevEUI ya rellenado. Consulta Dispositivos no registrados.
5. Elige dónde se decodifica la trama
Opción A: ChirpStack decodifica con un códec
En ChirpStack, abre el perfil de dispositivo que usan tus sensores, ve a su pestaña Codec, elige funciones JavaScript como códec de carga útil y escribe una función decodeUplink. ChirpStack la ejecuta en cada uplink y envía lo que devuelve en data como el object del evento de uplink. Para el sensor de sala, cuya trama de seis bytes en el puerto 2 contiene una temperatura con signo en décimas de grado, una humedad en pasos de medio punto porcentual, la batería en milivoltios y el contacto de puerta en el bit 0 del último byte:
function decodeUplink(input) {
var b = input.bytes;
if (input.fPort !== 2 || b.length < 6) {
throw new Error("unexpected frame on port " + input.fPort);
}
var t = (b[0] << 8) | b[1];
if (t & 0x8000) t -= 0x10000;
return {
data: {
temperature: t / 10,
humidity: b[2] / 2,
battery: (b[3] << 8) | b[4],
door: (b[5] & 1) === 1
}
};
}
En el lado de DeviceChain no hay nada más que hacer: deja el perfil de dispositivo sin decodificador. DeviceChain aplana object en lecturas:
- cada número es una lectura, con su clave; un valor anidado toma como clave su ruta unida por puntos (
{"battery": {"mv": 3300}}esbattery.mv); trueyfalsese guardan como1y0;- las cadenas y
nullse omiten, así que un códec que devuelve"status": "ok"no guarda nada para ese campo.
Nombra las claves que devuelve el códec como las métricas que declaraste, o declara las métricas con las claves que devuelve el códec. Qué se guarda tiene las reglas completas.
Un uplink cuyo evento no trae object, o uno sin ningún número ni booleano, se acusa y no guarda nada. La integración lo cuenta como sin decodificar y conserva una muestra de su trama: así se ve un uplink de un perfil de dispositivo sin códec.
Si el códec de un fabricante devuelve claves o unidades distintas de las de tu perfil (temp_f en Fahrenheit, bat.mv), no tienes que cambiar el códec. Un decodificador de DeviceChain sobre la entrada Objeto decodificado puede renombrarlas y convertirlas; consulta Reformar un objeto decodificado.
Opción B: DeviceChain decodifica la trama sin procesar
Da al perfil de dispositivo un decodificador de carga útil y ChirpStack no necesita códec. Cada evento up trae la trama sin procesar en data, y la integración entrega al decodificador:
| Nombre en el decodificador | Del evento de ChirpStack |
|---|---|
frame | data, los bytes de la trama |
fPort | fPort |
fCnt | fCnt |
decoded | object, cuando ChirpStack tiene un códec |
link | La recepción más fuerte de rxInfo y el número de pasarelas, cuando Guardar métricas del enlace está activado |
En la consola, abre el borrador del perfil, ve a la pestaña Decodificador, pon la entrada en Trama binaria y añade una sección para el fPort 2 con cuatro filas. Este es el documento que guarda, y el mismo documento se puede fijar con GraphQL mediante setDeviceProfileDecoder(profileToken: "room-sensor", document: ...):
{
"kind": "CEL",
"envVersion": 1,
"input": "FRAME",
"sections": [
{
"name": "uplink",
"when": "fPort == 2",
"outputs": [
{ "key": "temperature", "expr": "double(i16be(frame, 0)) / 10.0" },
{ "key": "humidity", "expr": "double(u8(frame, 2)) / 2.0" },
{ "key": "battery", "expr": "u16be(frame, 3)" },
{ "key": "door", "expr": "bit(frame, 5, 0)" }
]
},
{ "name": "other ports", "ignore": true }
],
"vectors": [
{
"name": "room sensor",
"input": { "frameHex": "00D75A0CE401", "fPort": 2 },
"expect": { "temperature": 21.5, "humidity": 45, "battery": 3300, "door": 1 }
}
]
}
La segunda sección acepta los uplinks de cualquier otro puerto y no guarda nada para ellos; sin ella, fallarían al decodificar con no_section. El vector es una prueba guardada: la publicación lo ejecuta y la rechaza si el decodificador no produce exactamente esas lecturas.
Prueba el decodificador antes de publicar. En el panel Prueba elige Trama, pega 00D75A0CE401 y pon fPort a 2, o elige Cuerpo de webhook, selecciona la integración y pega un evento completo tal como lo publica ChirpStack. Después publica el perfil. Un decodificador recién publicado tarda hasta un minuto aproximadamente en aplicarse.
Cuando el tipo de dispositivo tiene un decodificador, es el decodificador el que decide qué se guarda. Si ChirpStack también tiene un códec, su object no se guarda; solo está disponible para el decodificador como decoded. Una decodificación que falla no guarda nada de ese uplink y queda registrada como un evento fallido con el motivo DECODE_FAILED; la pestaña Decodificador del perfil lo muestra en Estado y Fallos recientes. Rechazos del decodificador enumera los motivos.
Un decodificador de DeviceChain no es JavaScript. Es una lista de expresiones tipadas sin bucles, así que el códec JavaScript de un fabricante no se puede pegar tal cual; sus lecturas de bytes se reescriben como filas del decodificador. Decodificadores de payload y la referencia de funciones describen el lenguaje.
6. Comprueba que llegan los uplinks
Puedes probar la integración antes de configurar ChirpStack, con una petición con la misma forma que la que envía ChirpStack. Esta lleva un object decodificado (opción A) y la trama sin procesar en data (opción B), así que sirve para las dos; el deduplicationId debe ser un UUID, y uno nuevo cada vez, o el uplink se guarda una sola vez:
curl -i -X POST "https://<host>/api/integrations/<tenant>/chirpstack-eu868?event=up" \
-H "Authorization: Bearer $INTEGRATION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deduplicationId": "'"$(uuidgen)"'",
"deviceInfo": { "devEui": "70b3d57ed0050004" },
"fPort": 2,
"fCnt": 1,
"data": "ANdaDOQB",
"object": { "temperature": 21.5, "humidity": 45, "battery": 3300, "door": true }
}'
202 Accepted significa que la petición se leyó y que el token es válido; no significa que se haya guardado nada. Después mira en DeviceChain:
- La página del dispositivo muestra las lecturas:
temperature21.5,humidity45,battery3300 ydoor1. - La página de la integración muestra Token rechazado si una petición falló en la autenticación, un recuento sin decodificar de los uplinks sin nada que guardar y Dispositivos no registrados vistos con los DevEUI que no tiene ningún dispositivo del ámbito.
- Con la opción B, la pestaña Decodificador del perfil muestra cuántos uplinks se decodificaron y cuántos fallaron.
En cuanto ChirpStack empieza a enviar, los uplinks reales aparecen del mismo modo. La página del dispositivo en ChirpStack muestra los eventos up que reenvió.
Solución de problemas
| Lo que ves | Causa probable |
|---|---|
401 | El token de portador es incorrecto o se rotó, o el token del inquilino o de la integración en la URL es incorrecto. La integración muestra Token rechazado. |
403 | La integración está desactivada. Vuelve a activar Aceptando datos. |
415 | La codificación de carga útil de la integración HTTP es Protobuf. Ponla en JSON. |
400 | El cuerpo de la respuesta nombra el campo: un DevEUI que no tiene 16 dígitos hexadecimales, un deduplicationId que no es un UUID, un time de hace más de 366 días o una petición sin ?event= (una URL de endpoint que no termina donde ChirpStack puede añadirlo). |
202, pero no se guarda nada | Ningún dispositivo de los tipos de la integración tiene el DevEUI (mira Dispositivos no registrados vistos), o el uplink no tenía nada que guardar (mira el recuento sin decodificar), o, con la opción B, la decodificación falló (mira la pestaña Decodificador). |
| Las lecturas llegan sin unidad | No hay ninguna métrica declarada en el perfil para esa clave, o el perfil no se ha publicado desde que se declaró. |
| ChirpStack no consigue conectar | ChirpStack no confía en el certificado de la instancia. |
Por qué no aparecen los datos de mi dispositivo recorre el registro que guarda la plataforma de lo que rechazó, y Qué se le responde al remitente enumera todas las respuestas.
Siguientes pasos
- Convierte lecturas en alarmas: De un uplink LoRaWAN a una alarma lleva el mismo sensor hasta una regla de detección, una alarma y un comando.
- Envía comandos de vuelta a través de ChirpStack: downlink LoRaWAN.
- Entiende los duplicados y los reintentos: Duplicados y reintentos. La clave es el
deduplicationIdde ChirpStack, así que una petición reintentada se guarda una sola vez. - Protege el token: Qué puede hacer un token de integración.
Véase también
La documentación de ChirpStack para los ajustes de su lado (en inglés):
- HTTP integration: el endpoint, el parámetro de consulta
eventy la codificación JSON. - Event types: el evento
upy sus campos. - Device profiles: la pestaña Codec y las funciones de códec JavaScript.