Cuando la biblioteca no tiene un códec para su sensor, o desea una salida distinta de un códec de la biblioteca, escriba el suyo. Sus códecs son tablas en JSON, no scripts: Hermetry nunca ejecuta código de un códec. Los publica en su organización, y sus dispositivos y perfiles pueden usarlos como los códecs de la biblioteca.
Escribir códecs requiere el permiso para añadir, cambiar y eliminar sus propios códecs LoRaWAN (administradores por defecto). Cada publicación y eliminación queda registrada en auditoría.
Dos formas de empezar
Guardar una copia de un códec de la biblioteca
Ideal cuando un códec de la biblioteca se parece a lo que necesita.
- Abra Dispositivos > ⋯ > Códecs LoRaWAN y abra el códec de la biblioteca.
- Seleccione Guardar una copia.
- El editor se abre con la tabla de la biblioteca, el id
t.<id de biblioteca>(cámbielo si lo desea), el origentenanty una línea de origen que indica el códec copiado y su revisión. - Modifique la tabla, seleccione Comprobar y después Publicar.
Crear un códec nuevo
- En el panel de códecs, seleccione Nuevo códec.
- Introduzca el Id y pegue o escriba la tabla en Tabla del códec (JSON). El editor ofrece un esquema desde el que empezar.
- Seleccione Comprobar y después Publicar.
Ids
Los ids de sus códecs empiezan por t., seguidos de 2 a 62 letras minúsculas, dígitos o guiones, por ejemplo t.cold-room-probe. El id no cambia nunca después. Un id ya usado en su organización se rechaza: ya existe un códec con este id. Elija otro id.
La tabla del códec
Un códec es un documento JSON. Sus campos principales:
| Campo | Obligatorio | Significado |
|---|---|---|
id | Sí | El id del códec (t.…) |
title | Sí | Un nombre legible, de hasta 160 caracteres |
vendor | Sí | El fabricante del dispositivo, de hasta 64 caracteres |
models | No | Nombres de modelo que cubre este códec (hasta 64) |
fports | No | FPorts que decodifica (1–255, hasta 64). Omítalo para todos los puertos. |
oui | No | Códigos de fabricante: los primeros 6 dígitos hexadecimales del DevEUI, en mayúsculas (hasta 32). Los usa la elección automática. |
kind | No | layout (campos en posiciones de byte fijas) o tlv (registros de canal, tipo y datos) |
frames | Para layout | Cómo distinguir las tramas (por fport, length, min_length, un byte marcador byte o bits con máscara) y los fields de cada una |
channels, types, attributes, default | Para tlv | Las definiciones de registros |
tests | Sí, al menos uno | Vectores de prueba: fport, hex y los valores expected (hasta 200) |
Un campo en una trama layout tiene at (desplazamiento en bytes), field (clave de salida), fmt (el formato de bytes) y, opcionalmente, scale, digits, offset, unit y enum. Los formatos incluyen u8, i8, u16be, u16le, i16be, i16le, u24be, u24le, u32be, u32le, i32be, i32le, f32be, f32le, hex, ascii y split de bits de un byte.
Las claves de nivel superior desconocidas se rechazan. No se aceptan decodificadores JavaScript: este es un decodificador JavaScript. Solo se acepta el formato de tabla.
Ejemplo
Un sensor que envía, en FPort 2, la batería en mV (2 bytes), la temperatura en décimas de °C (2 bytes, con signo) y la humedad en % (1 byte):
{
"id": "t.room-sensor",
"title": "Room sensor, temperature and humidity",
"vendor": "Example maker",
"models": ["RS-1"],
"fports": [2],
"kind": "layout",
"frames": [
{
"fport": 2,
"min_length": 5,
"fields": [
{ "at": 0, "field": "battery", "fmt": "u16be", "unit": "mV" },
{ "at": 2, "field": "temperature", "fmt": "i16be", "scale": 0.1, "unit": "°C" },
{ "at": 4, "field": "humidity", "fmt": "u8", "unit": "%" }
]
}
],
"tests": [
{ "name": "normal reading", "fport": 2, "hex": "0BC4010A32",
"expect": { "battery": 3012, "temperature": 26.6, "humidity": 50 } }
]
}Los valores escalados se redondean a 2 decimales salvo que el campo defina digits.
Comprobar y publicar
Comprobar ejecuta todos los vectores de prueba y muestra cada uno como Pasa o Falla, con Qué difiere. Cuando todos pasan: Todos los vectores de prueba pasan. Al publicar, queda disponible para sus dispositivos y routers.
Publicar vuelve a ejecutar las mismas comprobaciones y rechaza el códec con No publicado: y el motivo:
| Motivo mostrado | Significado |
|---|---|
| el texto no es JSON válido. | Corrija la sintaxis JSON. |
| falta un campo o no está permitido (…). | Falta un campo obligatorio o hay un campo desconocido. |
| el id debe ser t. seguido de letras minúsculas, dígitos y guiones. | Corrija el id. |
| el códec tiene más de 40960 bytes. | Sus códecs están limitados a 40 KB. |
| las tablas no tienen el formato esperado (…). | La definición de una trama o de un campo es incorrecta. |
| un códec necesita al menos un vector de prueba. | Añada un vector de prueba. |
| fallan algunos vectores de prueba (ver abajo). | Corrija la tabla o los valores esperados. |
| una versión publicada decodificaba claves que esta ya no decodifica (…). Publíquela con un id nuevo. | Consulte las revisiones abajo. |
| otro de sus códecs ya cubre models. | Dos de sus códecs no pueden reclamar el mismo modelo. |
Las tablas se anidan como máximo 32 niveles de profundidad.
Revisiones
Cada publicación de un códec existente crea una nueva revisión. Para proteger sus flujos y paneles, una nueva revisión puede añadir claves, pero nunca eliminar ni renombrar una, ni cambiar la unidad de una clave. Si necesita quitar o renombrar claves, publique con un id nuevo y traslade sus dispositivos a él.
Revisiones en la página del códec lista cada revisión con su tamaño y número de claves.
Su códec y la biblioteca
Sus códecs se prueban antes que los de la biblioteca en la elección automática. Una copia conserva los códigos de fabricante y los FPorts del códec de la biblioteca, de modo que los dispositivos de ese fabricante en Automático pasan a su copia en cuanto la publica. Uno de sus códecs puede reclamar el mismo modelo que un códec de la biblioteca; así es como sustituye la biblioteca para sus dispositivos.
Eliminar un códec
Abra su códec y seleccione Eliminar. El códec sale de su lista; a partir de entonces, los dispositivos y perfiles que lo elegían decodifican con la elección automática. Sus revisiones se conservan, y el id nunca cambia de significado: si crea de nuevo el mismo id, debe cumplir la regla de revisiones frente a la última revisión del códec eliminado.