Les types de données Sparkplug B définissent précisément la façon dont chaque valeur de métrique est encodée, d'un entier signé de 8 bits à un tableau complet de lignes et de colonnes. Cette référence liste chaque code de type avec le champ Protobuf qu'il utilise, explique les propriétés de métriques et les codes qualité, et montre des exemples décodés pour que vous reconnaissiez chaque type en inspectant du trafic réel.
Pourquoi Sparkplug a ses propres types de données
JSON connaît les nombres, les chaînes et les booléens. Les systèmes industriels ont besoin de plus de précision. Un registre d'automate peut être un entier non signé de 16 bits, un compteur une valeur non signée de 64 bits, et un horodatage ne doit pas être confondu avec un nombre ordinaire. Sparkplug B attribue à chaque métrique un code datatype explicite, pour qu'une application hôte située à l'autre bout du monde interprète la valeur exactement comme l'edge node l'entendait.
Le type de données est déclaré pour chaque métrique dans les messages de birth. Les messages de données peuvent l'omettre, c'est pourquoi les consommateurs mémorisent les types issus des births, comme décrit dans notre guide du payload Sparkplug B.
Types de données scalaires Sparkplug B
| Code | Nom | Champ de valeur Protobuf | Remarques |
|---|---|---|---|
| 0 | Unknown | aucun | Valeur par défaut, ne devrait pas apparaître dans des métriques valides |
| 1 | Int8 | int_value | Signé, complément à deux dans un champ non signé |
| 2 | Int16 | int_value | Signé, complément à deux |
| 3 | Int32 | int_value | Signé, complément à deux |
| 4 | Int64 | long_value | Signé, complément à deux dans un uint64 |
| 5 | UInt8 | int_value | Non signé |
| 6 | UInt16 | int_value | Non signé |
| 7 | UInt32 | int_value | Non signé |
| 8 | UInt64 | long_value | Non signé |
| 9 | Float | float_value | IEEE 754 32 bits |
| 10 | Double | double_value | IEEE 754 64 bits |
| 11 | Boolean | boolean_value | true ou false |
| 12 | String | string_value | Texte UTF-8 |
| 13 | DateTime | long_value | Millisecondes depuis l'epoch Unix, UTC |
| 14 | Text | string_value | Texte plus long, même encodage que String |
| 15 | UUID | string_value | UUID sous forme de chaîne |
| 16 | DataSet | dataset_value | Tableau de colonnes typées et de lignes |
| 17 | Bytes | bytes_value | Données binaires brutes |
| 18 | File | bytes_value | Contenu de fichier, décrit par MetaData |
| 19 | Template | template_value | Type ou instance défini par l'utilisateur |
Les codes 20 et 21 (PropertySet et PropertySetList) servent aux valeurs de propriétés, pas aux valeurs de métriques.
Le piège des entiers signés
Le bug de décodage le plus courant dans Sparkplug consiste à lire directement les entiers signés. Comme int_value est un champ non signé de 32 bits, un Int32 valant -5 arrive sous la forme 4294967291, et un Int64 valant -1 arrive sous la forme 18446744073709551615 dans long_value. Le consommateur doit appliquer le complément à deux d'après le type déclaré. Les edge nodes doivent faire l'inverse à l'encodage. Si un tableau de bord affiche soudain une température de quatre milliards de degrés, c'est presque toujours la raison.
DateTime n'est pas un nombre
Une métrique DateTime et une métrique Int64 utilisent le même champ, mais n'ont pas le même sens. Traitez DateTime comme des millisecondes depuis l'epoch en UTC et convertissez-le pour l'affichage. N'envoyez jamais de secondes, ni d'heure locale.
Types de données tableaux
Sparkplug définit aussi des tableaux de types scalaires. Ils voyagent dans bytes_value sous forme de valeurs little-endian contiguës, un encodage que Sparkplug 3.0 décrit précisément (voir notre comparatif Sparkplug 3.0 pour les autres clarifications).
| Code | Nom | Code | Nom |
|---|---|---|---|
| 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 |
La prise en charge des tableaux varie selon les produits. Si vous dépendez des tableaux entre éditeurs, testez-les tôt avec les deux extrémités connectées au même broker.
Indicateurs de métriques
Chaque métrique peut porter des indicateurs booléens qui modifient la façon dont les consommateurs la traitent :
| Indicateur | Signification | Comportement du consommateur |
|---|---|---|
| is_null | La métrique existe mais n'a pas de valeur | Afficher null ou mauvaise qualité, ne pas substituer zéro |
| is_historical | La valeur date du passé, par exemple en store and forward | La stocker, ne pas écraser la valeur en direct |
| is_transient | La valeur ne doit pas être historisée | L'afficher, ne pas la stocker |
Les métriques ont aussi un timestamp optionnel, distinct de celui du payload. Utilisez-le pour enregistrer le moment où la valeur a été échantillonnée à la source.
Propriétés des métriques
Une métrique peut porter un PropertySet : des listes parallèles de clés et de valeurs typées. Les valeurs de propriétés utilisent les mêmes codes de type, plus PropertySet (20) et PropertySetList (21), qui permettent l'imbrication.
La propriété Quality
La seule propriété à laquelle la spécification donne une signification définie est Quality, un Int32 :
| Valeur | Signification |
|---|---|
| 192 | Bonne |
| 0 | Mauvaise |
| 500 | Périmée |
Un hôte qui reçoit une métrique avec Quality 0 doit l'afficher comme mauvaise, même si une valeur est présente. Beaucoup de plateformes edge positionnent Quality à 500 lorsqu'elles perdent le contact avec l'équipement sous-jacent tout en gardant le nœud connecté.
Autres propriétés courantes
Unités d'ingénierie, plages, descriptions et formats d'affichage sont souvent transmis sous forme de propriétés, mais leurs noms de clés relèvent des conventions de chaque plateforme, pas de la spécification. Mettez-vous d'accord sur un vocabulaire de propriétés commun à vos edge nodes, sinon votre application hôte verra le même concept sous des clés différentes.
DataSets
Un DataSet est un petit tableau typé à l'intérieur d'une seule métrique. Il comporte un nombre de colonnes, des noms de colonnes, un code de type pour chaque colonne et une liste de lignes. Chaque valeur de ligne utilise un ensemble restreint de champs : int, long, float, double, boolean ou string.
Une fois décodée, une table de paramètres de recette peut ressembler à ceci :
{
"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 }] }
]
}
}
Les DataSets sont utiles pour des lots de valeurs liées qui doivent rester ensemble. Pour des modèles d'équipements structurés, les templates conviennent généralement mieux ; voir templates et UDT Sparkplug.
Exemples décodés
Voici un fragment de birth avec plusieurs types de données et une propriété Quality, tel que vous le verriez après décodage :
[
{ "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" }
]
Remarquez l'offset Int16 : la valeur brute 4294967286 vaut -10 après complément à deux. Notez aussi que certains rendus JSON affichent les valeurs 64 bits sous forme de chaînes pour éviter une perte de précision en JavaScript.
Vérifier les types de données en pratique
Le moyen le plus rapide de vérifier les types est de lire les births décodés. ConnectMQ décode Sparkplug B dans l'explorateur de topics du portail : vous pouvez ouvrir un NBIRTH ou un DBIRTH et contrôler le type et la valeur de chaque métrique sans écrire de code. Pour des contrôles automatisés, le décodeur de notre tutoriel pour décoder Sparkplug B en Python associe les codes aux noms et gère la conversion des entiers signés.
Lorsque vous testez sur le serveur MQTT public gratuit, utilisez un group ID aléatoire et rappelez-vous que tout y est lisible par tous : il sert aux tests et aux prototypes, pas aux données de production.
Checklist des types de données pour la configuration d'un edge node
- Faites correspondre chaque type Sparkplug au type du registre source ; ne convertissez pas tout en Double.
- Utilisez des types non signés pour les compteurs qui ne deviennent jamais négatifs.
- Utilisez DateTime pour les horodatages, toujours en millisecondes UTC.
- Positionnez Quality sur les métriques dont la source peut tomber en panne indépendamment du nœud.
- Utilisez is_null plutôt que zéro lorsqu'une valeur est indisponible.
- Marquez comme historiques les données en store and forward.
- Harmonisez les noms de clés de propriétés sur tous les edge nodes.
- Testez tableaux, DataSets et templates de bout en bout avant le déploiement.
La place des types de données
Des types de données corrects permettent aux données Sparkplug d'alimenter historians, SCADA et Unified Namespace sans correctifs tag par tag. Pour des conseils d'architecture, consultez le guide de l'IoT industriel avec MQTT. N'importe quel broker MQTT conforme transporte ces payloads ; un broker MQTT managé qui les décode en plus accélère nettement la vérification.
Démarrer avec ConnectMQ
Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire. Connectez votre edge node et vérifiez le type de données, la valeur et la qualité de chaque métrique dans l'explorateur de topics de ConnectMQ.
Questions fréquentes
Combien y a-t-il de types de données Sparkplug B ?
La spécification définit des types scalaires avec les codes 1 à 19, des types de jeux de propriétés 20 et 21, et des types tableaux de 22 à 34. Le code 0 correspond à Unknown.
Pourquoi ma valeur Sparkplug négative s'affiche-t-elle comme un nombre énorme ?
Les entiers signés sont stockés dans des champs Protobuf non signés. Appliquez le complément à deux d'après le type déclaré, ou utilisez un décodeur qui le fait pour vous.
Que signifie Quality 192 dans Sparkplug ?
Cela signifie une bonne qualité. La propriété Quality utilise 192 pour bonne, 0 pour mauvaise et 500 pour périmée.
Les types de données Sparkplug sont-ils obligatoires dans les messages de données ?
Ils sont obligatoires dans les messages de birth et facultatifs dans NDATA et DDATA. Les consommateurs doivent mémoriser le type de chaque métrique à partir du birth.
