> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/data-source-node.md).
# Fuente de datos
El nodo Fuente de datos es el punto de entrada de IoT Logic para la telemetría del dispositivo. Recibe datos por TCP, UDP, HTTP o MQTT, los decodifica y los pasa a los nodos posteriores. También puede enriquecer un dispositivo ya conectado
## Resumen técnico y capacidades
{% columns %}
{% column %}
**Fuente de datos** El Nodo es un punto de entrada para datos de telemetría de dispositivos IoT y plataformas OEM en el sistema IoT Logic. Funciona como un traductor universal, recibe datos mediante protocolos TCP/UDP/HTTP en interfaces de red y a través de colas MQTT, y luego decodifica los flujos de datos entrantes según el protocolo seleccionado. El nodo transforma los Mensajes de los dispositivos a un formato estandarizado que luego puede procesarse en su flujo.
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Además de recibir telemetría, un **Fuente de datos** Nodo también puede enriquecer un dispositivo que ya haya agregado a él. Un sistema externo, como una plataforma telemática independiente que no envía datos a Navixy por defecto, envía atributos adicionales al flujo del dispositivo. A veces esa plataforma externa es la propia del fabricante del dispositivo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, el **Software** La pestaña lo mantiene registrado tal como está. Enriquece continuamente el flujo del dispositivo con datos de esa otra plataforma, por lo que ambos flujos se ejecutan en paralelo. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) para ver los detalles, y [Opciones de configuración](#configuration-options) para configurarlo.
### Integración de la arquitectura del flujo
**Nodo Fuente de datos** funciona como el punto de entrada de los datos en un flujo de IoT Logic. Un solo flujo puede contener varios nodos fuente, cada uno con configuraciones independientes. Esta arquitectura permite:
* Adquisición inicial de datos desde múltiples tipos de dispositivos y formatos de protocolo
* Transformación estandarizada de datos de distintos fabricantes a formatos unificados
* Rutas de procesamiento en paralelo al conectar una Fuente de datos con varios nodos descendentes
* Filtrado selectivo de dispositivos para incluir solo fuentes de datos relevantes en su flujo
* Enriquecimiento del flujo para dispositivos ya conectados, usando atributos enviados desde un sistema externo mediante HTTP
### Capacidades del nodo
El **Nodo Fuente de datos** por sí solo ofrece:
* **Diversidad de protocolos**: Compatible con múltiples fabricantes de dispositivos, incluidos Teltonika, Queclink, Suntech, Jimi y otros, mediante analizadores y decodificadores heredados de Navixy
* **Flexibilidad de transporte**: Admite los protocolos TCP, UDP, HTTP y conexiones con broker MQTT
* **Transformación unificada de datos**: Convierte los Mensajes específicos de cada dispositivo a un formato estandarizado para un procesamiento uniforme
* **Filtrado de dispositivos**: Proporciona capacidades de filtrado para seleccionar modelos o protocolos específicos
* **Procesamiento en tiempo real**: Gestiona los flujos de datos de telemetría entrantes en tiempo real para un procesamiento inmediato
* **Enriquecimiento por push HTTP**: Fusiona los atributos enviados desde un sistema externo en el flujo de un dispositivo ya seleccionado en este nodo. HTTP es hoy el único tipo de push compatible, y la arquitectura está diseñada para admitir más en el futuro
## Opciones de configuración
{% columns %}
{% column width="58.333333333333336%" valign="middle" %}
Configurar un **Fuente de datos** Nodo determina qué dispositivos envían datos a su flujo y, opcionalmente, cómo un sistema externo puede enriquecer esos dispositivos con datos enviados.
El cuadro de diálogo de configuración está organizado en dos pestañas:
* **Dispositivos**: selecciona qué dispositivos envían telemetría al flujo. Requerido, y funciona exactamente como antes.
* **Software**: configura el enriquecimiento por push HTTP para los dispositivos que seleccionó en la pestaña Dispositivos. Opcional, y depende de esa selección.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
El **Software** la pestaña depende de la **Dispositivos** pestaña. Su **Dispositivo de origen** selector solo muestra dispositivos ya seleccionados en **Dispositivos**, y no muestra datos disponibles hasta que seleccione al menos uno allí.
{% endhint %}
Veamos qué elementos usa este nodo y qué puede configurar al trabajar con él:
### Pasos de configuración
{% stepper %}
{% step %}
#### Especificar nombre del nodo
Ingrese un nombre descriptivo para esta Fuente de datos:
* Use un nombre que le ayude a identificar el fabricante, los modelos u otra información relevante.
* Este nombre se mostrará en el diagrama de flujo para facilitar su identificación.
{% endstep %}
{% step %}
#### Seleccione las fuentes
De la lista filtrada, seleccione los dispositivos que desea incluir. Solo están disponibles para la selección los dispositivos registrados en su cuenta de usuario de Navixy. Esta selección también es el requisito previo para la opcional **Software** pestaña, que solo puede asignar dispositivos seleccionados aquí.
{% endstep %}
{% step %}
#### Guarde la configuración del nodo
Haga clic en **Aplicar cambios** para completar la creación del nodo.
{% endstep %}
{% step %}
#### Configure el enriquecimiento de push HTTP (opcional)
Cambie a la **Software** pestaña para enriquecer los dispositivos que seleccionó en Dispositivos con datos enviados desde un sistema externo. Este paso es opcional. Consulte [Configuración del enriquecimiento de push HTTP](#configuring-http-push-enrichment) para ver la configuración completa.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Si cambia la configuración del fabricante o del modelo después de seleccionar dispositivos, Navixy le notificará si alguno de los dispositivos seleccionados no coincide con los nuevos parámetros, pero no los eliminará automáticamente de su selección.
{% endhint %}
### Configuración del enriquecimiento de push HTTP
El enriquecimiento de push HTTP permite que un sistema externo agregue atributos a un dispositivo que ya está seleccionado en la **Dispositivos** pestaña de este nodo, enviando datos a una URL generada. Es opcional y requiere al menos un dispositivo seleccionado primero en [Pasos de configuración](#configuration-steps) primer lugar.
Esto es útil cuando un dispositivo ya reporta a un sistema independiente que no alimenta a Navixy de forma predeterminada, por ejemplo, una plataforma de gestión de baterías que hace seguimiento del nivel de batería del mismo vehículo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, puede mantenerlo registrado tal como está y permitir que esa otra plataforma envíe sus lecturas aquí. Un envío con `vehicle_id: "truck_12"`, `bms_battery_soc: 76`, y `bms_battery_temp: 34.2` agrega `bms_battery_soc` y `bms_battery_temp` como nuevos atributos en el dispositivo asignado, junto con su telemetría GPS nativa.
{% stepper %}
{% step %}
#### Defina el tipo de conector
Cambie a la **Software** pestaña y establezca **Tipo de conector** en **HTTP**, actualmente la única opción.
{% endstep %}
{% step %}
#### Guarde el flujo y copie la URL generada
Guarde el flujo completo, no solo este nodo. El **URL** campo solo genera un valor una vez que el flujo se guarda con **Tipo de conector** establecido. Hasta entonces, muestra un marcador de posición que le solicita guardar el flujo. Una vez que aparezca la URL, haga clic en el icono de copiar junto a ella, que solo está deshabilitado mientras el campo esté vacío.
{% endstep %}
{% step %}
#### Autentique el sistema externo
Proporcione al sistema externo una [clave API de Navixy](/docs/user/es/guide/account/api-keys.md)válida y configúrelo para enviar `Authorization: NVX ` con cada solicitud de envío, junto con la URL. Un envío sin este encabezado falla, por lo que se requieren tanto la URL como el encabezado antes de que puedan llegar los datos.
{% endstep %}
{% step %}
#### Defina la clave primaria y las asignaciones
Introduzca una **Clave primaria**: el nombre del campo que usa el sistema externo para identificar a qué dispositivo pertenece un registro enviado. Acepta hasta 64 caracteres, solo letras, dígitos y guiones bajos.
Añada una **Asignaciones** una fila por dispositivo para enriquecer. Para cada fila, seleccione el **Dispositivo de origen**, limitado a los dispositivos ya seleccionados en Dispositivos, e introduzca el **Valor de la clave** que identifica ese dispositivo en los push entrantes. Este campo almacena hasta 255 caracteres, pero el propio endpoint de push acepta solo hasta 100 caracteres por campo, así que en la práctica mantenga el valor muy por debajo de 100 caracteres.
{% hint style="warning" %}
Tanto la clave primaria como el valor de la clave aceptan solo letras, dígitos y guiones bajos, sin guiones ni otros signos de puntuación. La validación general de campos del endpoint de push es más permisiva y acepta guiones en cualquier campo sin generar error, pero un valor con guiones nunca podrá coincidir con un valor de clave almacenado, por lo que los push que usen uno se descartan silenciosamente, exactamente como si el valor no coincidiera. Si los identificadores de su sistema externo usan guiones (por ejemplo `truck-12`), tradúzcalos, por ejemplo a `truck_12`, antes de enviar.
{% endhint %}
{% endstep %}
{% step %}
#### Aplicar y guardar
Haga clic en **Aplicar cambios**, luego guarde el flujo nuevamente si configuró la pestaña Software después del guardado inicial.
{% endstep %}
{% endstepper %}
### Especificaciones del procesamiento de datos
**Nodo de fuente de datos** hereda todos los analizadores y decodificadores de Navixy, lo que proporciona compatibilidad con una amplia gama de dispositivos IoT. Cuando los datos llegan a este Nodo, pasan por el siguiente proceso:
1. La secuencia de datos entrante se recibe a través del protocolo de transporte especificado
2. Los datos se pasan al decodificador de protocolo apropiado según su configuración
3. Los Mensajes del dispositivo se transforman en un formato estandarizado que IoT Logic puede procesar
4. Los datos unificados se pasan al siguiente Nodo de su flujo
Este proceso de estandarización le permite crear flujos de procesamiento coherentes, independientemente del formato de datos original de los distintos fabricantes de dispositivos.
### Cómo se gestionan los datos enviados
Navixy compara cada envío entrante por el valor de su clave primaria con la configuración del nodo **Asignaciones**y luego fusiona los campos restantes en el flujo de datos del dispositivo asignado como atributos: nuevos si el nombre del campo es nuevo, o escritos en el historial existente de ese atributo si el nombre coincide con uno que ya existe, ya sea informado de forma nativa por el dispositivo o enviado por el conector de otro flujo. No afectan la ubicación ni otros datos de telemetría. El campo llamado en **Clave primaria**, junto con `flujo_id` y `id_del_nodo`, se usa para el enrutamiento y nunca se convierte en un atributo en sí mismo. Una solicitud puede terminar en uno de tres estados:
| Resultado | Respuesta HTTP | ¿Datos fusionados? |
| ---------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| El valor de la clave primaria coincide con un mapeo | 200, `éxito: verdadero` | Sí. Los campos restantes se fusionan como atributos: nuevos si el nombre es nuevo, historial existente si coincide con uno ya en uso |
| El valor de la clave primaria no coincide con ningún mapeo | 200, `éxito: verdadero` | No. Se descarta silenciosamente |
| Faltante o no válido `Autorización` encabezado | error 400 | No. Se rechaza antes de que Navixy verifique la clave primaria |
{% hint style="info" %}
Una respuesta 200 solo confirma que Navixy aceptó la solicitud, no que los datos se hayan fusionado. Un valor de clave primaria que no coincida se descarta silenciosamente, sin ningún error que lo señale. Si no está seguro de que un push se haya emparejado, revise los atributos del dispositivo asignado en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md) en lugar de depender de la respuesta.
{% endhint %}
{% hint style="warning" %}
El nombre de un campo enviado comparte un solo espacio de nombres con los atributos nativos propios del dispositivo y con los nombres enviados por el conector de otro flujo que enriquece el mismo dispositivo. Si el nombre coincide con uno ya en uso, ya sea nativo del dispositivo o enviado por otro flujo, el envío sobrescribe el historial existente de ese atributo en lugar de crear uno separado.
Los sensores, Reportes y Alertas leen el valor combinado como una lectura real, por lo que un nombre en conflicto puede generar datos falsos en etapas posteriores. Por ejemplo, un campo enviado llamado `nivel_de_combustible` que coincide con el atributo nativo de combustible de un dispositivo inyectaría una lectura falsa, produciendo eventos falsos de descenso de combustible o de reabastecimiento en Reportes.
Para evitar esto, anteponga prefijos a los nombres de campo enviados para que no puedan entrar en conflicto con los atributos nativos de un dispositivo o con los nombres enviados de otro flujo, por ejemplo `bms_battery_soc` en lugar de `batería_SoC`.
Campos del mensaje del sistema, como `velocidad`, `latitud`, `longitud`, `rumbo`, `satélites`, y `hdop` no se puede sobrescribir de esta manera. Los envíos solo crean o actualizan atributos, nunca telemetría a nivel de mensaje. Un campo enviado que use uno de esos nombres sigue apareciendo con ese nombre en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md), separado de la telemetría real del dispositivo.
{% endhint %}
Un atributo fusionado queda como una entrada puntual en el historial de atributos del dispositivo, no como un valor actual permanente. Si el dispositivo informa su propia telemetría con mucha más frecuencia que el sistema externo envía actualizaciones, los paquetes del propio dispositivo pueden adelantar el historial del atributo más allá del valor enviado en cuestión de segundos, aunque la fusión haya tenido éxito.
{% hint style="info" %}
Esta es una consecuencia esperada de que dos flujos de datos funcionen a velocidades diferentes, no un defecto. Haga referencia al atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre simple. `'valid'` recorre hacia atrás el historial del atributo hasta la última lectura no nula, por lo que los nodos aguas abajo obtienen el valor enviado independientemente del momento. Consulte [Valores faltantes y enrutamiento de nulos](/docs/user/es/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para ver cómo `'valid'` se compara con `'all'` en una condición de un nodo de IoT Logic.
{% endhint %}
El endpoint de envío acepta hasta 1 solicitud por segundo por clave API, con un tamaño de ráfaga de 1. Ajuste el ritmo de las solicitudes del sistema externo en consecuencia.
## Preguntas frecuentes
#### ¿Puedo usar varios nodos Fuente de datos en un flujo?
Sí, puede usar varios **nodos Fuente de datos** en un mismo espacio de trabajo. Esto es útil cuando necesita procesar datos de distintos tipos de dispositivos de diferentes maneras o desea fusionar varios flujos de datos después de transformaciones específicas.
#### ¿Qué ocurre si un dispositivo ya se usa en otro flujo?
Un dispositivo puede pertenecer a varios flujos al mismo tiempo. Si agrega un dispositivo que ya se usa en otro flujo, ambos flujos procesan sus datos simultáneamente y los resultados se fusionan para evitar la pérdida de datos. Estar asignado a otro flujo no es una restricción. Sin embargo, si los conectores de dos flujos envían el mismo nombre de atributo a ese dispositivo, no se fusionan sin conflictos. El historial de un envío sobrescribe el del otro. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) para evitar nombres en conflicto.
#### ¿Todos mis dispositivos Navixy están disponibles automáticamente en IoT Logic?
Sí, todos los dispositivos de su cuenta de usuario de Navixy pueden usarse en el procesamiento de IoT Logic. Esto incluye dispositivos GPS, plataformas OEM, dispositivos y pasarelas MQTT, y conectores MQTT/Kafka. Un dispositivo ya seleccionado en un **Fuente de datos** nodo también puede enriquecerse con atributos enviados desde un sistema externo por HTTP, a través de la **Software** pestaña.
#### ¿Cómo sé qué fabricante seleccionar para mis dispositivos?
El protocolo debe coincidir con el protocolo de comunicación usado por el fabricante de sus dispositivos. La mayoría de los dispositivos usa un protocolo asociado con su fabricante (por ejemplo, los dispositivos Teltonika usan el protocolo Teltonika). Revise la documentación de su dispositivo o consulte con su proveedor si no está seguro.
#### ¿Puedo conectar un nodo Fuente de datos a varios nodos aguas abajo?
Sí, puede conectar un **Nodo Fuente de datos** a varios nodos de procesamiento para crear rutas de procesamiento en paralelo. Esto le permite aplicar diferentes transformaciones al mismo flujo de datos. Aquí tiene un ejemplo:
#### ¿Puedo incorporar datos de un sistema que no sea un dispositivo Navixy?
Sí, a través de la **Software** pestaña, pero solo para enriquecer un dispositivo que ya agregó en la **Dispositivos** pestaña. No es una forma de crear un flujo sin dispositivos.
#### El sistema desde el que envío reporta con menos frecuencia que mi dispositivo, ¿se perderán los datos enviados?
No, pero un atributo enviado puede dejar de ser el valor actual rápidamente si el dispositivo reporta con mucha más frecuencia, ya que ambos aportes comparten el mismo historial rotativo. Haga referencia al atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre simple para obtener de forma fiable la última lectura real, sin importar el momento. Esta es una consecuencia esperada de que dos flujos funcionen a velocidades diferentes, no un defecto. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) y [Valores faltantes y enrutamiento de nulos](/docs/user/es/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para la `'valid'` vs `'all'` distinción en una condición de un nodo de IoT Logic.
#### Envié datos, pero no aparecen, ¿qué sucede?
Revise esto en orden:
1. Confirme que la solicitud incluyó un `Authorization: NVX ` encabezado válido. Un encabezado faltante o inválido genera un error HTTP 400 de forma explícita.
2. Confirme que el nombre del campo enviado coincida exactamente con la configuración del nodo y que su valor coincida con uno de los **Clave primaria** configurados **Asignaciones** exactamente, solo letras, dígitos y guiones bajos. Un valor con guiones es la causa más común: pasa la validación propia del endpoint de push sin error, pero nunca puede coincidir con un valor Key almacenado, por lo que la solicitud sigue devolviendo éxito mientras no se fusiona nada.
3. Consulte el historial del atributo en Analizador de datos, no solo su valor actual. Un dispositivo que reporta su propia telemetría a menudo puede sacar un valor fusionado de la posición actual en cuestión de segundos, aunque la fusión se haya realizado correctamente.
#### Envié un campo y las lecturas del propio dispositivo parecen incorrectas
Es probable que el nombre del campo enviado coincidiera con un atributo nativo que el dispositivo ya reporta, o con uno enviado por el conector de otro flujo, y haya sobrescrito su historial en lugar de crear un atributo independiente. Cambie el nombre del campo enviado con un prefijo distintivo y luego revise el historial del atributo en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md) para confirmar que los valores enviados y nativos ya no están mezclados.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/data-source-node.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media)
