Los tipos de datos de Sparkplug B definen exactamente cómo se codifica el valor de cada métrica, desde un entero de 8 bits con signo hasta una tabla completa de filas y columnas. Esta referencia enumera cada código de tipo de datos con el campo Protobuf que utiliza, explica las propiedades de las métricas y los códigos de calidad, y muestra ejemplos decodificados para que reconozcas cada tipo cuando inspecciones tráfico real.
Por qué Sparkplug tiene sus propios tipos de datos
JSON tiene números, cadenas y booleanos. Los sistemas industriales necesitan más precisión. Un registro de PLC puede ser un entero sin signo de 16 bits, un contador puede ser un valor sin signo de 64 bits y una marca de tiempo no debe confundirse con un número cualquiera. Sparkplug B asigna a cada métrica un código datatype explícito para que una aplicación host al otro lado del mundo interprete el valor exactamente como pretendía el edge node.
El tipo de datos se declara para cada métrica en los mensajes de birth. Los mensajes de datos pueden omitirlo, y por eso los consumidores guardan los tipos de datos de los births, como se describe en nuestra guía del payload Sparkplug B.
Tipos de datos escalares de Sparkplug B
| Código | Nombre | Campo de valor Protobuf | Notas |
|---|---|---|---|
| 0 | Unknown | ninguno | Marcador, no debería aparecer en métricas válidas |
| 1 | Int8 | int_value | Con signo, complemento a dos en un campo sin signo |
| 2 | Int16 | int_value | Con signo, complemento a dos |
| 3 | Int32 | int_value | Con signo, complemento a dos |
| 4 | Int64 | long_value | Con signo, complemento a dos en uint64 |
| 5 | UInt8 | int_value | Sin signo |
| 6 | UInt16 | int_value | Sin signo |
| 7 | UInt32 | int_value | Sin signo |
| 8 | UInt64 | long_value | Sin signo |
| 9 | Float | float_value | IEEE 754 de 32 bits |
| 10 | Double | double_value | IEEE 754 de 64 bits |
| 11 | Boolean | boolean_value | true o false |
| 12 | String | string_value | Texto UTF-8 |
| 13 | DateTime | long_value | Milisegundos desde la época Unix, UTC |
| 14 | Text | string_value | Texto más largo, misma codificación que String |
| 15 | UUID | string_value | UUID en forma de cadena |
| 16 | DataSet | dataset_value | Tabla de columnas tipadas y filas |
| 17 | Bytes | bytes_value | Datos binarios en bruto |
| 18 | File | bytes_value | Contenido de archivo, descrito por MetaData |
| 19 | Template | template_value | Tipo o instancia definidos por el usuario |
Los códigos 20 y 21 (PropertySet y PropertySetList) se usan para valores de propiedades, no para valores de métricas.
La trampa de los enteros con signo
El fallo de decodificación más habitual en Sparkplug es leer directamente los enteros con signo. Como int_value es un campo de 32 bits sin signo, un Int32 de -5 llega como 4294967291, y un Int64 de -1 llega como 18446744073709551615 en long_value. El consumidor debe aplicar complemento a dos según el tipo de datos declarado. Los edge nodes deben hacer lo inverso al codificar. Si un dashboard muestra de repente una temperatura de cuatro mil millones de grados, esta es casi siempre la razón.
DateTime no es un número
Una métrica DateTime y una métrica Int64 usan el mismo campo, pero significan cosas distintas. Trata DateTime como milisegundos desde la época en UTC y conviértelo para mostrarlo. Nunca envíes segundos ni hora local.
Tipos de datos array
Sparkplug también define arrays de tipos escalares. Viajan en bytes_value como valores empaquetados en little-endian, una codificación que Sparkplug 3.0 detalla con precisión (consulta nuestra comparativa de Sparkplug 3.0 para ver qué más se aclaró).
| Código | Nombre | Código | Nombre |
|---|---|---|---|
| 22 | Int8Array | 29 | UInt64Array |
| 23 | Int16Array | 30 | FloatArray |
| 24 | Int32Array | 31 | DoubleArray |
| 25 | Int64Array | 32 | BooleanArray |
| 26 | UInt8Array | 33 | StringArray |
| 27 | UInt16Array | 34 | DateTimeArray |
| 28 | UInt32Array |
El soporte de arrays varía entre productos. Si dependes de arrays entre fabricantes distintos, pruébalos pronto con ambos extremos conectados al mismo broker.
Indicadores de métricas
Cada métrica puede llevar indicadores booleanos que cambian la forma en que los consumidores la tratan:
| Indicador | Significado | Comportamiento del consumidor |
|---|---|---|
| is_null | La métrica existe pero no tiene valor | Mostrar como nulo o calidad mala, no sustituir por cero |
| is_historical | El valor es del pasado, por ejemplo de store and forward | Almacenarlo, sin sobrescribir el valor en vivo |
| is_transient | El valor no debe historizarse | Mostrarlo, sin almacenarlo |
Las métricas también tienen un timestamp opcional, independiente de la marca de tiempo del payload. Úsalo para registrar cuándo se muestreó el valor en el origen.
Propiedades de las métricas
Una métrica puede llevar un PropertySet: listas paralelas de claves y valores tipados. Los valores de las propiedades usan los mismos códigos de tipo de datos más PropertySet (20) y PropertySetList (21), que permiten el anidamiento.
La propiedad Quality
La única propiedad a la que la especificación da un significado definido es Quality, de tipo Int32:
| Valor | Significado |
|---|---|
| 192 | Buena |
| 0 | Mala |
| 500 | Obsoleta (stale) |
Un host que recibe una métrica con Quality 0 debe mostrarla como mala, aunque haya un valor presente. Muchas plataformas edge asignan Quality 500 cuando pierden el contacto con el dispositivo subyacente pero mantienen el nodo conectado.
Otras propiedades habituales
Las unidades de ingeniería, los rangos, las descripciones y los formatos de visualización se transportan a menudo como propiedades, pero sus nombres de clave son convenciones de cada plataforma, no parte de la especificación. Acuerda un vocabulario de propiedades común para todos los edge nodes, o tu aplicación host verá el mismo concepto bajo claves distintas.
DataSets
Un DataSet es una pequeña tabla tipada dentro de una única métrica. Tiene un número de columnas, nombres de columna, un código de tipo de datos para cada columna y una lista de filas. Cada valor de fila usa un conjunto restringido de campos: int, long, float, double, boolean o string.
Una vez decodificada, una tabla de parámetros de receta podría tener este aspecto:
{
"name": "Recipe/Steps",
"datatype": 16,
"datasetValue": {
"numOfColumns": 3,
"columns": ["Step", "Temperature", "Duration"],
"types": [3, 9, 7],
"rows": [
{ "elements": [{ "intValue": 1 }, { "floatValue": 180.0 }, { "intValue": 600 }] },
{ "elements": [{ "intValue": 2 }, { "floatValue": 220.0 }, { "intValue": 300 }] }
]
}
}
Los DataSets son útiles para lotes de valores relacionados que deben mantenerse juntos. Para modelos de equipos estructurados, los templates suelen encajar mejor; consulta templates y UDTs de Sparkplug.
Ejemplos decodificados
Este es un fragmento de birth con varios tipos de datos y una propiedad Quality, tal como lo verías después de decodificarlo:
[
{ "name": "Pump/Running", "alias": 1, "datatype": 11, "booleanValue": true },
{ "name": "Pump/Speed", "alias": 2, "datatype": 9, "floatValue": 1475.0,
"properties": { "keys": ["Quality"], "values": [{ "type": 3, "intValue": 192 }] } },
{ "name": "Pump/StartCount", "alias": 3, "datatype": 8, "longValue": "18342" },
{ "name": "Pump/LastService", "alias": 4, "datatype": 13, "longValue": "1789000000000" },
{ "name": "Pump/Offset", "alias": 5, "datatype": 2, "intValue": 4294967286 },
{ "name": "Pump/Serial", "alias": 6, "datatype": 12, "stringValue": "P-0042" }
]
Fíjate en el offset Int16: el valor en bruto 4294967286 es -10 tras aplicar complemento a dos. Observa también que algunas representaciones JSON muestran los valores de 64 bits como cadenas para evitar la pérdida de precisión en JavaScript.
Comprobar los tipos de datos en la práctica
La forma más rápida de verificar los tipos de datos es leer births decodificados. ConnectMQ decodifica Sparkplug B en el explorador de topics del portal, de modo que puedes abrir un NBIRTH o DBIRTH y comprobar el tipo de datos y el valor de cada métrica sin escribir código. Para comprobaciones automatizadas, el decodificador de nuestro tutorial sobre cómo decodificar Sparkplug B en Python traduce los códigos a nombres y gestiona la conversión con signo.
Cuando hagas pruebas en el servidor MQTT público gratuito, usa un group ID aleatorio y recuerda que todo lo que hay allí es legible por cualquiera, así que no es apto para datos de producción.
Checklist de tipos de datos para configurar edge nodes
- Haz coincidir cada tipo Sparkplug con el tipo del registro de origen; no lo amplíes todo a Double.
- Usa tipos sin signo para contadores que nunca son negativos.
- Usa DateTime para las marcas de tiempo, siempre en milisegundos UTC.
- Asigna Quality a las métricas cuyo origen puede fallar con independencia del nodo.
- Usa is_null en lugar de cero cuando un valor no está disponible.
- Marca como históricos los datos de store and forward.
- Acuerda nombres de clave de propiedades comunes para todos los edge nodes.
- Prueba arrays, DataSets y templates de extremo a extremo antes del despliegue.
Dónde encajan los tipos de datos
Unos tipos de datos correctos son lo que permite que los datos Sparkplug alimenten historians, SCADA y un Unified Namespace sin correcciones tag a tag. Para orientación de arquitectura, consulta la guía de IoT industrial con MQTT. Cualquier broker MQTT que cumpla el estándar transporta estos payloads; un broker MQTT gestionado que además los decodifica agiliza mucho la verificación.
Empieza con ConnectMQ
Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito. Conecta tu edge node y comprueba el tipo de datos, el valor y la calidad de cada métrica en el explorador de topics de ConnectMQ.
Preguntas frecuentes
¿Cuántos tipos de datos tiene Sparkplug B?
La especificación define tipos escalares con los códigos 1 a 19, tipos de conjunto de propiedades 20 y 21, y tipos array del 22 al 34. El código 0 es Unknown.
¿Por qué mi valor negativo de Sparkplug aparece como un número enorme?
Los enteros con signo se almacenan en campos Protobuf sin signo. Aplica complemento a dos según el tipo de datos declarado o usa un decodificador que lo haga por ti.
¿Qué significa Quality 192 en Sparkplug?
Significa calidad buena. La propiedad Quality usa 192 para buena, 0 para mala y 500 para obsoleta.
¿Son obligatorios los tipos de datos de Sparkplug en los mensajes de datos?
Son obligatorios en los mensajes de birth y opcionales en NDATA y DDATA. Los consumidores deben recordar el tipo de datos de cada métrica a partir del birth.
