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 possède une sortie out et une sortie error. Aucun 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, en étapes exécutées de haut en bas.
| Réglage | Signification | Valeurs |
|---|---|---|
| ops | Les étapes | jusqu’à 16 lignes |
Chaque étape :
| op | Effectue | Champs |
|---|---|---|
set | Écrit une valeur ; les parents manquants sont créés | path, value (tout type de valeur) |
change | Remplace chaque occurrence de from par to dans le texte ; les valeurs non textuelles ne sont pas modifiées | 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. | 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 (stockage de variables plein) ou bad pattern ; les étapes précédant celle en échec sont déjà appliquées.
Exemple : renommer une clé d’appareil avant l’enregistrement : étape 1 set msg.payload.temperature vers le chemin msg.payload.tmp ; étape 2 delete msg.payload.tmp.
Calculer
Évalue 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 du texte dès qu’un des deux côtés est du texte ; une opération arithmétique sur null ou sur tout texte (même "21.5") échoue avec type : convertir 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).
Échelle
Convertit un nombre linéairement 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 considérés comme des nombres. Erreur invalid_value (« not a number », ou plage d’entrée vide).
Modèle
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 du 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 plus 64 Ko de texte.
JSON
Convertit 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
Texte CSV en enregistrements, ou 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 | Décodage : la première ligne contient les noms. Encodage : é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 | Décodage : les champs de type numérique deviennent des nombres | off | on, off |
| output | Décodage : 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
Texte XML en objet, ou objet en texte XML.
| Réglage | Signification | Par défaut |
|---|---|---|
| Mode | parse, build, ou auto | |
| Propriété | 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 |
| Sélection | 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 Kio (1 à 256 Kio) |
Un document contenant <!DOCTYPE est refusé. Au plus 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, le texte qui ressemble à du hex (ou du base64) est décodé et tout le reste encodé ; les mots courts comme test ou les nombres comme 2024 sont aussi du base64 ou du hex valides, donc choisissez encode ou decode lorsque vous connaissez le sens. Le décodage hex ignore les espaces et les deux-points.
Octets
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 | Lire ou construire | 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 | Petit boutiste (little endian) | off (gros boutiste) | on, off |
| bits | Une plage de bits start:length | champ entier | ex. 0:1, 4:3 |
| scale | Décodage : × scale ; encodage : ÷ scale | 1 | un nombre |
Decode lit du texte hex (espaces et deux-points ignorés) ou un tableau de valeurs d’octets dans msg.payload et écrit { name: value }. Encode écrit du texte hex. Erreur invalid_value lorsque les données ne sont pas en hex 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’appareils
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.

