Conectar sensores

Para quién es: el integrador o el ingeniero que conecta los equipos, y el administrador que crea sus credenciales.

Antes de empezar: un Administrador crea el adaptador (Personas y acceso). El equipo que envía necesita salida a internet con TLS; nada tiene que entrar a su red.

Elija cómo entran las lecturas

Un adaptador es una vía por la que las lecturas y los nodos llegan a Nebli Environment, con su propia credencial. Hay tres tipos:

Cada adaptador se puede revocar o rotar por separado, sin afectar a los demás (Estado de la red).

Cree un adaptador

1. Vaya a Configuración › Adaptadores y elija Nuevo adaptador.
2. Elija el tipo y póngale un nombre, por ejemplo "Sensores MQTT · Ciudad".
3. Elija Crear.

Una tarjeta muestra la credencial y dónde ponerla. El secreto se muestra una sola vez y no se puede recuperar, así que cópielo antes de cerrar la tarjeta.

Lo que muestra la tarjeta depende del tipo:

El mensaje (formato v1)

Los equipos MQTT y HTTP envían el mismo mensaje JSON: un nodo, una hora del dispositivo y sus canales. El nodo es el identificador de hardware que va en el tema o en la dirección, nunca en el mensaje.

{
  "kind": "smart_pole",
  "device_time": "2026-10-11T14:05:00-05:00",
  "channels": {
    "pm25": { "value": 18.4, "unit": "µg/m³" },
    "temperature": { "value": 19.2, "unit": "°C" },
    "power_source": { "value": "mains" }
  }
}

• kind: el tipo del nodo, hoy smart_pole (poste inteligente). Solo se usa la primera vez que un nodo reporta.
• device_time: cuándo tomó el equipo las lecturas, como fecha y hora ISO 8601 con su desfase horario. Es obligatorio.
• channels: cada clave de canal con su value y su unit. Un valor es un número, o una palabra en los canales que la llevan (power_source, link).
• Un valor null o ausente significa "sin lectura", nunca cero. Ese canal se omite y el resto del mensaje se conserva.
• Un mensaje puede llevar hasta 64 canales y 16 KB.

Canales y unidades

Estos son los canales que reporta un poste inteligente, con la unidad en que Nebli Environment los guarda. Otras unidades comunes se convierten solas: °F y K para la temperatura, Pa, kPa y mbar para la presión, km/h y nudos para el viento, mV y mA, y ppb o ppm en ambos sentidos.

Qué pasa con un mensaje

• Se confirma solo cuando queda guardado. Por HTTP la respuesta es 202. Por MQTT, una publicación QoS 1 se confirma después de guardar las lecturas. Un mensaje confirmado nunca se pierde.
• Un mensaje enviado dos veces se registra una sola vez. Se puede reenviar sin riesgo tras un tiempo de espera agotado.
• Un mensaje que no se puede leer se rechaza: JSON mal formado, sin hora del dispositivo, sin ningún canal con valor, con demasiados canales o demasiado grande. Por HTTP la respuesta es 400; se cuenta contra la credencial en la página Red.
• Vuelva a intentarlo más tarde cuando HTTP responde 429 (la credencial envía demasiado rápido) o 503, o cuando MQTT cierra la conexión sin confirmar: no se guardó nada.
• Una credencial incorrecta o revocada recibe 401 por HTTP, y se rechaza al conectar por MQTT.
• Demasiados nodos en espera. Cuando su organización ya tiene el máximo de nodos sin adoptar que puede tener, se rechaza un mensaje de un identificador de hardware nuevo (409 por HTTP) hasta que se adopten o retiren algunos.
• Una credencial envía solo para sus propios nodos. Una lectura de un nodo que registró otra credencial se rechaza y se cuenta en la página Red; nunca se registra en ese nodo.
• Un canal o una unidad desconocidos, o un valor imposible, se guardan como sospechosos. Se conservan para diagnóstico y se muestran en la página Red, pero nunca abren una alerta ni alimentan un índice. Nada se descarta en silencio.

La primera lectura

La primera vez que reporta un identificador de hardware, Nebli Environment crea el nodo y lo muestra en Nodos sin adoptar en la página Red, con el adaptador que lo reportó. Un Administrador lo adopta en un sitio, y entonces aparece en el mapa y en la tabla (Estado de la red).

Gateways TALQ

Un gateway TALQ funciona en ambos sentidos. Llama a Nebli Environment para declarar sus equipos y entregar sus reportes, y Nebli Environment llama al gateway para configurar qué registra y cuándo, porque un gateway TALQ no envía nada hasta tener esa configuración. Nebli Environment pide registrar al intervalo de reporte del nodo cuando el gateway lo admite y, si no, acepta el registro propio del gateway. Ver intercambio en la página Red muestra la conversación en ambos sentidos.

Nebli Environment implementa la especificación TALQ; no tiene la certificación TALQ.

Siguientes pasos

• Estado de la red: adaptadores, nodos sin adoptar y lo que necesita atención.
• Mapa, página del nodo y tabla: cada vista y cómo exportar lo que ve.