> 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.

## Visión general técnica y capacidades

{% columns %}
{% column %}
**Fuente de datos** El nodo es un punto de entrada para los datos de telemetría de dispositivos IoT y plataformas OEM en el sistema IoT Logic. Funciona como un traductor universal, recibe datos mediante los 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 del dispositivo en un formato estandarizado que puede procesarse posteriormente en su flujo.
{% endcolumn %}

{% column %}

<figure><img src="https://1900701122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2Fgit-blob-af4d64e959feca51b9e4010f02f38e78e4ed22c8%2Fiot-logic-data-source-tile.png?alt=media" alt="Data source node in the flow workspace"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Además de recibir telemetría, un **Fuente de datos** nodo también puede enriquecer un dispositivo que ya agregó a este. Un sistema externo, como una plataforma telemática independiente que no envía datos a Navixy de forma predeterminada, 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 cual. 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 conocer el funcionamiento, y [Opciones de configuración](#configuration-options) para configurarlo.

### Integración con la arquitectura de flujos

<figure><img src="https://1900701122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2Fgit-blob-2155447864f99240b12cd2f10618cb92cbff488e%2Fiot-logic-data-source-in-flow.png?alt=media" alt="Data source node included in a flow on workspace"><figcaption></figcaption></figure>

**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 de origen, cada uno con configuraciones independientes. Esta arquitectura permite:

* Adquisición inicial de datos de 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 posteriores
* Filtrado selectivo de dispositivos para incluir solo las fuentes de datos relevantes en su flujo
* Enriquecimiento del flujo para dispositivos ya conectados, usando atributos enviados desde un sistema externo por HTTP

### Capacidades del nodo

El **Nodo Fuente de datos** por sí mismo ofrece:

* **Diversidad de protocolos**: Es compatible con múltiples fabricantes de dispositivos, incluidos Teltonika, Queclink, Suntech, Jimi y otros, mediante los analizadores sintácticos y decodificadores heredados de Navixy
* **Flexibilidad de transporte**: Admite los protocolos TCP, UDP, HTTP y conexiones con brokers MQTT
* **Transformación unificada de datos**: Convierte los mensajes específicos del dispositivo a un formato estandarizado para un procesamiento coherente
* **Filtrado de dispositivos**: Ofrece capacidades de filtrado para seleccionar modelos o protocolos específicos
* **Procesamiento en tiempo real**: Gestiona flujos de datos de telemetría entrantes en tiempo real para su procesamiento inmediato
* **Enriquecimiento por push HTTP**: Combina los atributos enviados desde un sistema externo con el flujo de un dispositivo ya seleccionado en este nodo. HTTP es el único tipo de push compatible actualmente, 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** El 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. Es obligatoria y funciona exactamente igual que antes.
* **Software**: configura el enriquecimiento por push HTTP para los dispositivos que seleccionó en la pestaña Dispositivos. Es opcional y depende de esa selección.
  {% endcolumn %}

{% column width="41.666666666666664%" %}

<figure><img src="https://1900701122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2Fgit-blob-3ee99992528681bd753f09ca94f203bd655000c1%2FData_source_node_edit%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
El **Software** La pestaña depende de la **Dispositivos** pestaña. Su **Dispositivo de origen** selector solo muestra los dispositivos ya seleccionados en **Dispositivos**, y no muestra datos disponibles hasta que seleccione al menos uno allí.
{% endhint %}

Veamos qué elementos utiliza este Nodo y qué puede configurar al trabajar con él:

### Pasos de configuración

{% stepper %}
{% step %}

#### Especificar el 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 %}

#### Seleccionar fuentes

De la lista filtrada, seleccione los dispositivos que desea incluir. Solo los dispositivos registrados en su cuenta de usuario de Navixy están disponibles para su selección. Esta selección también es el requisito previo para la pestaña opcional **Software** pestaña, que solo puede asignar los 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 %}

#### Configurar el enriquecimiento por 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 por 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 notifica si alguno de los dispositivos seleccionados no coincide con los nuevos parámetros, pero no los elimina automáticamente de su selección.
{% endhint %}

### Configuración del enriquecimiento por push HTTP

El enriquecimiento por push HTTP permite que un sistema externo agregue atributos a un dispositivo ya seleccionado en la **Dispositivos** pestaña, enviando datos a una URL generada. Es opcional y requiere al menos un dispositivo seleccionado en [Pasos de configuración](#configuration-steps) primero.

Esto es útil cuando un dispositivo ya reporta a un sistema independiente que no envía datos a Navixy de forma predeterminada, por ejemplo una plataforma de gestión de baterías que realiza el 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 cual y hacer que esa otra plataforma envíe aquí sus lecturas. 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 mapeado, junto con su telemetría GPS nativa.

{% stepper %}
{% step %}

#### Establecer el tipo de conector

Cambie a la **Software** pestaña y establezca **Tipo de conector** a **HTTP**, actualmente la única opción.
{% endstep %}

{% step %}

#### Guarde el flujo y copie la URL generada

Guarde todo el flujo, no solo este nodo. El **URL** el campo solo genera un valor una vez que el flujo se guarda con **Tipo de conector** configurado. Hasta entonces, muestra un marcador de posición que le pide guardar el flujo. Una vez que aparezca la URL, haga clic en el ícono de copiar junto a ella, deshabilitado solo mientras el campo esté vacío.
{% endstep %}

{% step %}

#### Autentique el sistema externo

Proporcione al sistema externo una clave de API válida de [clave de API de Navixy](https://navixy.com/docs/user/es/guide/account/api-keys.md), y configúrelo para enviar `Authorization: NVX <api_key>` con cada solicitud push, junto con la URL. Un push sin este encabezado falla, por lo que tanto la URL como el encabezado son obligatorios antes de que puedan recibirse los datos.
{% endstep %}

{% step %}

#### Defina la clave primaria y las asignaciones

Ingrese un **Clave primaria**: el nombre del campo que el sistema externo usa para identificar a qué dispositivo pertenece un registro enviado. Acepta hasta 64 caracteres, solo letras, dígitos y guiones bajos.

Añadir uno **Mapeos** una fila por dispositivo para enriquecer. Para cada fila, seleccione el **Dispositivo de origen**, limitado a los dispositivos ya seleccionados en Dispositivos, e ingrese el **Valor de clave** que identifica a ese dispositivo en los envíos entrantes. Este campo almacena hasta 255 caracteres, pero el propio endpoint de push solo acepta hasta 100 caracteres por campo, así que en la práctica mantenga el valor muy por debajo de 100 caracteres.

{% hint style="warning" %}
Tanto Primary key como Key value admiten solo letras, dígitos y guiones bajos; no admiten guiones ni otra puntuación. La validación general de campos del endpoint de push es más permisiva y acepta guiones en cualquier campo sin dar error, pero un valor con guiones nunca puede coincidir con un Valor de clave almacenado, por lo que los pushes que usen uno se descartan silenciosamente exactamente igual que si el valor no coincidiera. Si los identificadores de su sistema externo usan guiones (por ejemplo `camión-12`), tradúzcalos, por ejemplo a `truck_12`, antes de presionar.
{% 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 %}

### Detalles del procesamiento de datos

**El nodo 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. El flujo de datos entrante se recibe a través del protocolo de transporte especificado
2. Los datos se pasan al decodificador de protocolo correspondiente 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 original de los datos de distintos fabricantes de dispositivos.

### Cómo se gestionan los datos enviados

Navixy compara cada push entrante por el valor de su clave primaria con el valor configurado del Nodo **Mapeos**, 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 que el dispositivo los reporte de forma nativa o que los envíe el conector de otro flujo. No afectan la ubicación ni otras métricas de telemetría. El campo denominado en **Clave primaria**, junto con `flujo_id` y `nodo_id`, se utiliza para el enrutamiento y nunca se convierte en un atributo por sí mismo. Una solicitud puede terminar en uno de tres estados:

| Resultado                                                  | Respuesta HTTP     | ¿Se fusionaron los datos?                                                                                                            |
| ---------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| El valor de la clave primaria coincide con un mapeo        | 200, `éxito: true` | 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: true` | No. Se descarta silenciosamente                                                                                                      |
| Faltante o no válido `Authorization` 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 fusionaron. Un valor de clave primaria que no coincida se descarta silenciosamente, sin ningún error que lo indique. Si no está seguro de que un envío haya coincidido, revise los atributos del dispositivo asociado en [Analizador de datos](https://navixy.com/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md) en lugar de confiar en la respuesta.
{% endhint %}

{% hint style="warning" %}
Un nombre de campo enviado comparte un solo espacio de nombres con los atributos nativos del propio 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 fusionado como una lectura real, así que un nombre en conflicto puede producir datos falsos aguas abajo. Por ejemplo, un campo enviado llamado `nivel_de_combustible` que coincida con el atributo nativo de combustible de un dispositivo inyectaría una lectura falsa, produciendo eventos falsos de caída de combustible o repostaje en los reportes.

Para evitar esto, anteponga un prefijo a los nombres de los campos enviados para que no puedan chocar con los atributos nativos del dispositivo ni con los nombres enviados por otro flujo, por ejemplo `bms_battery_soc` en lugar de `battery_soc`.

Los campos de mensajes del sistema, como `speed`, `latitud`, `longitud`, `heading`, `satélites`, y `hdop` no pueden sobrescribirse 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](https://navixy.com/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 en un momento específico en el historial de atributos del dispositivo, no como un valor actual persistente. Si el dispositivo reporta 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 segundos, aunque la fusión se haya realizado correctamente.

{% hint style="info" %}
Esta es una consecuencia esperada de que dos flujos de datos funcionen a distintas velocidades, no un defecto. Consulte el atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre a secas. `'válido'` recorre hacia atrás el historial del atributo hasta la última lectura no nula, de modo que los nodos aguas abajo reciban el valor enviado sin importar el momento. Consulte [Valores faltantes y enrutamiento nulo](https://navixy.com/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 `'válido'` se compara con `'todos'` en una condición de un nodo de lógica.
{% endhint %}

El endpoint de envío acepta hasta 1 solicitud por segundo por clave de 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 solo 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 consecuencias. 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 de 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 del nodo **Software** pestaña.

#### ¿Cómo sé qué fabricante debo seleccionar para mis dispositivos?

El protocolo debe coincidir con el protocolo de comunicación usado por el fabricante de su dispositivo. La mayoría de los dispositivos usan 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 paralelas. Esto le permite aplicar diferentes transformaciones al mismo flujo de datos. Aquí tiene un ejemplo:

<figure><img src="https://1900701122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F446mKak1zDrGv70ahuYZ%2Fuploads%2Fgit-blob-a6ac4747b6916ec883c48e98e40391c555552988%2Fiot-logic-data-source-multi-output.png?alt=media" alt="Example showing the Data source node in context with multiple outbound connections and outputs"><figcaption></figcaption></figure>

#### ¿Puedo incorporar datos de un sistema que no sea un dispositivo de Navixy?

Sí, a través de la **Software** pestaña, pero solo para enriquecer un dispositivo que ya haya agregado 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 ambas fuentes comparten el mismo historial deslizante. Consulte el atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre literal para obtener de forma confiable la última lectura real, independientemente del momento. Esta es una consecuencia esperada de que dos flujos se ejecuten a diferentes velocidades, no un defecto. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) y [Valores faltantes y enrutamiento nulo](https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para la `'válido'` vs `'todos'` distinción en una condición de Nodo lógico.

#### Envié datos, pero no aparecen. ¿Qué está mal?

Revise estos en orden:

1. Confirme que la solicitud incluyó un `Authorization: NVX <api_key>` encabezado. Un encabezado faltante o inválido falla de forma explícita con un error HTTP 400.
2. Confirme que el nombre del campo enviado coincida con el **Clave primaria** ajuste del Nodo exactamente, y que su valor coincida con uno de los configurados **Mapeos** exactamente, solo letras, dígitos y guiones bajos. Un valor con guion es la causa más común: supera la validación propia del endpoint de envío sin error, pero nunca puede coincidir con un valor Key almacenado, por lo que la solicitud sigue devolviendo éxito aunque nada se combine.
3. Revise 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 del registro actual en cuestión de segundos, aunque la combinación haya tenido éxito.

#### Envié un campo y las lecturas propias del dispositivo se ven 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 que haya sobrescrito su historial en lugar de crear un atributo independiente. Cambie el nombre del campo enviado con un prefijo distinto, luego revise el historial del atributo en [Analizador de datos](https://navixy.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/data-source-node.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
