Blocs de transformation de données

Les blocs de transformation modifient le message et le transmettent. Ils permettent de renommer des clés, calculer des valeurs, construire des textes et décoder les données brutes des appareils avant Save telemetry. Chacun dispose d’une sortie out et d’une sortie error. Aucun d’eux ne conserve d’état.

Change

Définit, modifie, supprime ou déplace des propriétés du message ainsi que des variables de flux ou globales, dans des étapes exécutées de haut en bas.

Réglage	Signification	Valeurs
ops	Les étapes	jusqu’à 16 lignes

Chaque étape :

op	Action	Champs
set	Écrit une valeur ; les parents manquants sont créés	path, value (valeur de tout type)
change	Remplace chaque occurrence de from par to dans le texte ; les valeurs non textuelles sont laissées telles quelles	path, from, to, regex (un motif d’au plus 64 caractères)
delete	Supprime la propriété ou la variable	path
move	Copie vers le chemin indiqué dans to, puis supprime l’original. L’éditeur n’affiche pas encore le champ to; utilisez donc set et delete à la place.	path, to
copy keys	Copie chaque clé de premier niveau de l’objet situé au chemin path dont le nom complet correspond à Keys matching vers To object	path, Keys matching, To object
delete keys	Supprime chaque clé de premier niveau dont le nom complet correspond	path, Keys matching

Les chemins sont des chemins msg., flow. ou global. (flow.persist:x pour le stockage persistant). Les champs du moteur (_…), msg.msgType et msg.originator ne peuvent pas être écrits. Erreurs : invalid_value avec invalid_path, read_only, invalid_key, limit (magasin de variables plein) ou bad pattern ; les étapes précédant celle en échec sont déjà appliquées.

Exemple : renommer une clé d’un appareil avant l’enregistrement : étape 1 set msg.payload.temperature vers le chemin msg.payload.tmp ; étape 2 delete msg.payload.tmp.

Calculate

Calcule une expression et écrit le résultat.

Réglage	Signification	Par défaut	Valeurs
expr	L’expression	obligatoire	jusqu’à 512 caractères
target	Destination du résultat	msg.payload	un chemin msg., flow. ou global.

7 / 2 donne 3.5 ; + concatène des textes dès qu’un des deux côtés est un texte ; une arithmétique sur null ou sur un texte quelconque (même "21.5") échoue avec type : convertissez avec number(). Erreurs : invalid_value, type, div_zero, steps, limit. Voir Condition blocks pour les fonctions.

Exemples : round(msg.payload.temperature * 1.8 + 32, 1) ; 10 * log10(msg.payload.ratio) ; clamp(msg.payload.level, 0, 100).

Scale

Convertit linéairement un nombre d’une plage vers une autre, sur place.

Réglage	Signification	Par défaut	Valeurs
property	Le nombre	msg.payload	un chemin
in_min, in_max	La plage d’entrée	0, 4095	nombres, non égaux
out_min, out_max	La plage de sortie	0, 100	nombres
mode	Hors de la plage de sortie	clamp	clamp (limite), wrap (rebouclage), free (laisser)
round	Décimales	aucune	0 à 10

Formule : out_min + (value − in_min) × (out_max − out_min) / (in_max − in_min). Le texte numérique et true/false (1/0) sont comptés comme des nombres. Erreur invalid_value (« not a number », ou plage d’entrée vide).

Template

Construit un texte, ou une valeur JSON, à partir de marqueurs {{ expression }}.

Réglage	Signification	Par défaut	Valeurs
template	Le texte	{{ msg.payload }}	jusqu’à 4 096 caractères
target	Destination du résultat	msg.payload	un chemin msg., flow. ou global.
format	text, ou json (le résultat est analysé comme JSON)	text	text, json

null devient vide, les objets et tableaux sont écrits en JSON. Pour une sortie JSON, mettez vous-même les marqueurs de texte entre guillemets : {"temp": {{ msg.payload }}, "unit": "{{ flow.unit }}"}. Le résultat fait au maximum 64 Ko de texte.

JSON

Transforme un texte JSON en valeur, ou une valeur en texte JSON, sur place.

Réglage	Signification	Par défaut	Valeurs
mode	auto (analyse le texte, transmet le reste), parse, stringify	auto
property	La propriété	msg.payload	un chemin

Erreurs : invalid_value « not JSON: … » ou « not a string ».

CSV

Transforme un texte CSV en enregistrements, ou des enregistrements en texte CSV, sur place.

Réglage	Signification	Par défaut	Valeurs
mode	auto, decode, encode	auto
property	La propriété	msg.payload	un chemin
sep	Séparateur de champs	virgule	virgule, point-virgule, tabulation, barre verticale
header	Decode : la première ligne contient les noms. Encode : écrit une ligne d’en-tête	off	on, off
columns	Noms de colonnes, séparés par des virgules	vide	jusqu’à 256 caractères
numbers	Decode : les champs de type numérique deviennent des nombres	off	on, off
output	Decode : un message avec tous les enregistrements (array) ou un message par enregistrement (rows)	array	array, rows

Les guillemets suivent la RFC 4180. Erreur queue_full au-delà de 10 000 lignes ou enregistrements.

XML

Transforme un texte XML en objet, ou un objet en texte XML.

Réglage	Signification	Par défaut
Mode	parse, build, ou auto
Property	Où la conversion a lieu	msg.payload
Préfixe d’attribut	Préfixe des clés d’attributs	@
Clé de texte	Clé du texte à côté des éléments enfants	#text
Tableaux / éléments de tableau	Éléments toujours traités comme des tableaux
Nombres	Le texte numérique devient des nombres	off
Select	Ne conserve qu’un chemin d’élément, par ex. soap:Envelope/soap:Body/*/m:Price
Root, Declaration	Construction : le nom de l’élément racine, la ligne <?xml …?>
Max bytes	Entrée la plus grande	64 KiB (1 à 256 KiB)

Un document contenant <!DOCTYPE est refusé. Au maximum 10 000 éléments, 64 attributs par élément, 128 caractères par nom. Erreurs : parse_error, dtd_refused, too_large, too_deep, bad_name, no_root.

Hex et Base64

Encode une propriété en hexadécimal (deux chiffres minuscules par octet) ou en texte base64, ou la décode.

Réglage	Signification	Par défaut	Valeurs
mode	Sens	auto	auto, encode, decode
property	La propriété	msg.payload	un chemin msg., flow. ou global.

En auto, un texte ressemblant à de l’hexadécimal (ou du base64) est décodé et le reste encodé ; des mots courts comme test ou des chiffres comme 2024 sont aussi du base64 ou de l’hexadécimal valides, donc choisissez encode ou decode lorsque vous connaissez le sens. Le décodage hexadécimal ignore les espaces et les deux-points.

Bytes

Lit des nombres nommés dans des données binaires, ou construit des données binaires à partir de nombres.

Réglage	Signification	Par défaut	Valeurs
mode	Lecture ou construction	decode	decode, encode
fields	Une ligne par champ	vide	jusqu’à 16 lignes

Chaque champ :

Champ	Signification	Par défaut	Valeurs
name	Clé dans le résultat	obligatoire	une lettre ou _ en premier, jusqu’à 32 caractères
offset	Premier octet, à partir de 0	0	0 à 4 095
type	Taille et nature	u16	u8, i8, u16, i16, u32, i32, f32
le	Little endian (poids faible d’abord)	off (big endian)	on, off
bits	Une plage de bits start:length	champ entier	par ex. 0:1, 4:3
scale	Decode : × scale ; encode : ÷ scale	1	un nombre

Decode lit du texte hexadécimal (espaces et deux-points ignorés) ou un tableau de valeurs d’octets dans msg.payload et écrit { name: value }. Encode écrit du texte hexadécimal. Erreur invalid_value lorsque les données ne sont pas en hexadécimal ou qu’un champ dépasse leur fin.

Exemple : une charge utile brute 00d7ff9c avec temp (offset 0, i16, scale 0.1) et pressure (offset 2, i16) donne { "temp": 21.5, "pressure": -100 }.

Décodage des données brutes d’un appareil

Un appareil qui envoie des données binaires arrive avec la clé unique raw (base64 pour le binaire). Un décodeur type dans le flux racine, avant Save telemetry :

Switch (msg.payload.raw nempty) → Change: set msg.payload to the path msg.payload.raw
  → Base64 (decode) → Hex (encode) → Bytes (decode fields) → Save telemetry

Vérifiez le résultat avec Test avant de déployer. Pour les appareils LoRaWAN, utilisez plutôt des codecs ; voir Codecs overview. Pour tout ce que les blocs ne peuvent pas exprimer, utilisez The script block.