Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Bloques de transformación de datos

Referencia de Change, Calculate, Scale, Template, JSON, CSV, XML, Hex, Base64 y Bytes: los bloques que reestructuran, calculan y decodifican los datos de los mensajes.

Los bloques de transformación cambian el mensaje y lo envían. Sirven para renombrar claves, calcular valores, construir textos y decodificar datos brutos del dispositivo antes de Guardar telemetría. Cada uno tiene una salida out y una salida error. Ninguno guarda estado.

Change

Establece, edita, elimina o mueve propiedades del mensaje y de las variables de flujo o globales, en pasos que se ejecutan de arriba abajo.

AjusteSignificadoValores
opsLos pasoshasta 16 filas

Cada paso:

opHaceCampos
setEscribe un valor; los padres que falten se creanpath, value (cualquier tipo de valor)
changeReemplaza cada aparición de from por to en el texto; lo que no es texto no se modificapath, from, to, regex (un patrón de como máximo 64 caracteres)
deleteElimina la propiedad o variablepath
moveCopia a la ruta indicada en to y luego elimina el original.path, to
copy keysCopia cada clave de primer nivel del objeto en path cuyo nombre completo coincida con Keys matching en To objectpath, Keys matching, To object
delete keysElimina cada clave de primer nivel cuyo nombre completo coincidapath, Keys matching

Las rutas son rutas msg., flow. o global. (flow.persist:x para el almacén persistente). Los campos del motor (_…), msg.msgType y msg.originator no se pueden escribir. Errores: invalid_value con invalid_path, read_only, invalid_key, limit (almacén de variables lleno) o bad pattern; los pasos anteriores al que falla ya están aplicados.

Ejemplo: renombrar una clave del dispositivo antes de guardar: paso 1 set msg.payload.temperature a la ruta msg.payload.tmp; paso 2 delete msg.payload.tmp.

Calculate

Calcula una expresión y escribe el resultado.

AjusteSignificadoPredeterminadoValores
exprLa expresiónobligatoriohasta 512 caracteres
targetDónde va el resultadomsg.payloaduna ruta msg., flow. o global.

7 / 2 es 3.5; + une textos cuando cualquiera de los lados es texto; la aritmética con null o con cualquier texto (incluso "21.5") falla con type: convierta con number(). Errores: invalid_value, type, div_zero, steps, limit. Consulte Bloques de condición para las funciones.

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

Scale

Asigna linealmente un número de un rango a otro, en el mismo campo.

AjusteSignificadoPredeterminadoValores
propertyEl númeromsg.payloaduna ruta
in_min, in_maxEl rango de entrada0, 4095números, distintos entre sí
out_min, out_maxEl rango de salida0, 100números
modeFuera del rango de salidaclampclamp (limitar), wrap (dar la vuelta), free (dejar)
roundDecimalesninguno0 a 10

Fórmula: out_min + (value − in_min) × (out_max − out_min) / (in_max − in_min). El texto numérico y true/false (1/0) cuentan como números. Error invalid_value («not a number», o un rango de entrada vacío).

Template

Construye texto, o un valor JSON, a partir de marcadores {{ expression }}.

AjusteSignificadoPredeterminadoValores
templateEl texto{{ msg.payload }}hasta 4.096 caracteres
targetDónde va el resultadomsg.payloaduna ruta msg., flow. o global.
formattext, o json (el resultado se interpreta como JSON)texttext, json

null queda vacío; los objetos y las matrices se escriben como JSON. Para la salida JSON, ponga usted mismo entre comillas los marcadores de texto: {"temp": {{ msg.payload }}, "unit": "{{ flow.unit }}"}. El resultado tiene como máximo 64 KB de texto.

JSON

Convierte texto JSON en un valor, o un valor en texto JSON, en el mismo campo.

AjusteSignificadoPredeterminadoValores
modeauto (interpreta el texto, deja pasar el resto), parse, stringifyauto
propertyLa propiedadmsg.payloaduna ruta

Errores: invalid_value «not JSON: …» o «not a string».

CSV

Convierte texto CSV en registros, o registros en texto CSV, en el mismo campo.

AjusteSignificadoPredeterminadoValores
modeauto, decode, encodeauto
propertyLa propiedadmsg.payloaduna ruta
sepSeparador de camposcomacoma, punto y coma, tabulador, barra vertical
headerDecodificar: la primera línea tiene los nombres. Codificar: escribe una línea de encabezadooffon, off
columnsNombres de columna, separados por comasvacíohasta 256 caracteres
numbersDecodificar: los campos con forma de número se convierten en númerosoffon, off
outputDecodificar: un mensaje con todos los registros (array) o uno por registro (rows)arrayarray, rows

El entrecomillado sigue RFC 4180. Error queue_full por encima de 10.000 líneas o registros.

XML

Convierte texto XML en un objeto, o un objeto en texto XML.

AjusteSignificadoPredeterminado
Modeparse, build o auto
PropertyDónde se realiza la conversiónmsg.payload
Prefijo de atributoPrefijo de las claves de atributo@
Text keyClave del texto junto a los elementos hijos#text
Arrays / array elementsQué elementos son siempre matrices
NumbersEl texto numérico se convierte en númerosoff
SelectConserva solo una ruta de elementos, p. ej. soap:Envelope/soap:Body/*/m:Price
Root, DeclarationAl construir: el nombre del elemento raíz, la línea <?xml …?>
Max bytesEntrada más grande64 KiB (de 1 a 256 KiB)

Un documento con <!DOCTYPE se rechaza. Como máximo 10.000 elementos, 64 atributos por elemento, 128 caracteres por nombre. Errores: parse_error, dtd_refused, too_large, too_deep, bad_name, no_root.

Hex y Base64

Codifica una propiedad como hexadecimal (dos dígitos en minúscula por byte) o como texto base64, o la decodifica.

AjusteSignificadoPredeterminadoValores
modeSentidoautoauto, encode, decode
propertyLa propiedadmsg.payloaduna ruta msg., flow. o global.

En auto, el texto que parece hexadecimal (o base64) se decodifica y lo demás se codifica; las palabras cortas como test o los dígitos como 2024 también son base64 o hex válidos, así que elija encode o decode cuando conozca el sentido. La decodificación hexadecimal ignora los espacios y los dos puntos.

Bytes

Lee números con nombre de datos binarios, o construye datos binarios a partir de números.

AjusteSignificadoPredeterminadoValores
modeLeer o construirdecodedecode, encode
fieldsUna fila por campovacíohasta 16 filas

Cada campo:

CampoSignificadoPredeterminadoValores
nameClave en el resultadoobligatoriouna letra o _ al principio, hasta 32 caracteres
offsetPrimer byte, desde 000 a 4.095
typeTamaño y tipou16u8, i8, u16, i16, u32, i32, f32
leLittle endian (little endian)off (big endian)on, off
bitsUn rango de bits start:lengthcampo completop. ej. 0:1, 4:3
scaleDecodificar: × scale; codificar: ÷ scale1un número

Decode lee texto hexadecimal (se ignoran los espacios y los dos puntos) o una matriz de valores de byte en msg.payload y escribe { name: value }. Encode escribe texto hexadecimal. Error invalid_value cuando los datos no son hexadecimales o un campo queda más allá de su final.

Ejemplo: una carga útil en bruto 00d7ff9c con temp (offset 0, i16, scale 0.1) y pressure (offset 2, i16) da { "temp": 21.5, "pressure": -100 }.

Decodificación de datos brutos del dispositivo

Un dispositivo que envía datos binarios llega con la única clave raw (base64 para datos binarios). Un decodificador típico en el flujo raíz, antes de Guardar telemetría:

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

Comprueba el resultado con Test antes de desplegarlo. Para los dispositivos LoRaWAN, usa en su lugar codecs; consulta Codecs overview. Para todo lo que los bloques no pueden expresar, usa The script block.