Bytes to Map Parser
Overview
This prefab parses a raw BYTES input into a structured MAP. It is specifically designed to work with binary data from systems that use word-based addressing, which is common in industrial datasheets for devices like PLCs, sensors, and Modbus-compatible hardware.
It allows you to copy memory addresses directly from a datasheet, and the prefab will handle the conversion to the correct byte position automatically.
How it Works
The core logic revolves around two key constants: word_size_bytes and the schema. For each field defined in the schema, the parser calculates the starting byte position using the formula:
byte_address = word_address * word_size_bytes
This allows you to think in terms of “words” or “registers” (as defined in your device’s documentation) without doing manual byte math.
Configuration
Constants
| Constant | Type | Description |
|---|---|---|
word_size_bytes | INT | Required. The size of a single ‘word’ in bytes. This is used as a multiplier for the word_address. Common values are 1 (for 8-bit registers), 2 (for 16-bit registers), or 4 (for 32-bit registers). |
schema | JSON | Required. A JSON array of objects, where each object defines a field to be parsed from the byte array. See the Schema Fields section below for details on how to structure each object. |
Schema Fields
Each object in the schema array defines one key-value pair for the output map.
| Key | Type | Required? | Description |
|---|---|---|---|
key | String | Yes | The key name for this value in the output MAP. |
word_address | Integer | Yes | The starting address of the data in “words”. This is the value you would typically copy from a technical datasheet. Can be a decimal (122) or a hex string ("0x7A"). |
type | String | Yes | The data type to parse. See the Data Types table below for all possible values. |
endian | String | Yes | The endianness (“byte order”) for multi-byte data types. Can be le (Little-Endian) or be (Big-Endian). |
length | Integer | No | Required only for STRING and BYTES types. Specifies the exact number of bytes to read for that field. |
scale | Float | No | A multiplier to apply to a numeric value after parsing. The formula is final_value = (raw_value * scale) + offset. Defaults to 1.0. |
offset | Float | No | An additive value to apply to a numeric value after parsing and scaling. The formula is final_value = (raw_value * scale) + offset. Defaults to 0.0. |
Data Types (for the type field)
| Value | Description | Size (Bytes) |
|---|---|---|
I8 | 8-bit Signed Integer | 1 |
U8 | 8-bit Unsigned Integer | 1 |
I16 | 16-bit Signed Integer | 2 |
U16 | 16-bit Unsigned Integer | 2 |
I32 | 32-bit Signed Integer | 4 |
U32 | 32-bit Unsigned Integer | 4 |
I64 | 64-bit Signed Integer | 8 |
U64 | 64-bit Unsigned Integer | 8 |
F32 | 32-bit Float | 4 |
F64 | 64-bit Float | 8 |
BOOL | Boolean (true if byte is not 0) | 1 |
STRING | UTF-8 String | length |
BYTES | Raw Byte Array | length |
Ports
- Inputs:
input:BYTES- Receives the raw byte array to be parsed. - Outputs:
output:MAP- Sends a map containing the parsed key-value data.
Example
Imagine a sensor sends a 12-byte data packet. The datasheet specifies that the memory is addressed in 16-bit words (word_size_bytes: 2).
Sample Input (BYTES):
[0x01, 0x9A, 0x00, 0x01, 0x43, 0x48, 0x00, 0x00, 0x61, 0x62, 0x63, 0x00]
Datasheet Information:
- Word Address 0: Device Status (U16)
- Word Address 2: Temperature (F32), value must be multiplied by 0.1 and then have 5 subtracted.
- Word Address 4: Device ID (String), 3 bytes long.
Configuration
word_size_bytes
2schema
[
{
"key": "device_status",
"word_address": 0,
"type": "U16",
"endian": "be"
},
{
"key": "temperature",
"word_address": 2,
"type": "F32",
"endian": "be",
"scale": 0.1,
"offset": -5.0
},
{
"key": "device_id",
"word_address": 4,
"type": "STRING",
"endian": "be",
"length": 3
}
]Resulting Output (MAP)
Based on the input bytes and the schema, the output map will be:
{
"device_status": 410,
"temperature": -2.9999999821186066,
"device_id": "abc"
}Calculation Walkthrough:
device_status: Starts atword_address0. Byte position =0 * 2 = 0. Reads 2 bytes[0x01, 0x9A]as a Big-Endian U16, which is410.temperature: Starts atword_address2. Byte position =2 * 2 = 4. Reads 4 bytes[0x43, 0x48, 0x00, 0x00]as a Big-Endian F32, which is200.0. The final value is(200.0 * 0.1) - 5.0 = 15.0.device_id: Starts atword_address4. Byte position =4 * 2 = 8. Readslengthof 3 bytes from that position:[0x61, 0x62, 0x63], which is the UTF-8 string"abc".