Serial / Ethernet Reader

Overview

This prefab reads raw data from a Serial (UART) port / Ethernet channel and emits it downstream as BYTES packets. Because the incoming data arrives as a continuous stream with no built-in message boundaries, the prefab provides four packet reading modes that define where one packet ends and the next begins:

• LISTEN — collect everything, flush after a fixed number of bytes.
• FIXED — packets start with a magic word and have a fixed payload size.
• DYNAMIC — packets start with a magic word and carry their own length field.
• END — packets are delimited by a start magic word and an end magic word.

How it Works

The reader runs in cycles. Each cycle it reads bytes from the Serial (UART) port / Ethernet channel, assembles them into a packet according to the selected mode, and sends the completed packet on the output port. If a packet cannot be completed within timeout(ms), the cycle ends: in LISTEN mode any bytes collected so far are flushed as a packet, while in the other modes the partial packet is discarded and the reader resynchronizes on the next magic word.

If the optional trigger input is connected, the reader waits for a message on it before starting each cycle. This lets you gate reading behind another node (for example, read one packet only after a command has been written to the device). If trigger is not connected, the reader runs continuously.

A single packet can be at most 256 KiB (262,144 bytes). Anything larger is discarded with a warning.

FIXED, DYNAMIC, and END all frame packets around a magic word, so those constants are grouped into a single Magic Word section in the node’s configuration panel: start (the byte sequence marking the start of every packet) is shown for FIXED, DYNAMIC, and END, while end (the byte sequence marking the end of every packet) is shown for END only.

Modes

Each mode below includes a public example workflow. To try one in your own company, click Copy JSON to Clipboard in the top-left corner of the embedded workflow, then paste it under Blueprints > Import.

LISTEN

Passively collects every byte that arrives on the Serial (UART) port / Ethernet channel. A packet is emitted once max(bytes) bytes have been collected, or when timeout(ms) elapses — in which case whatever has been collected so far (if anything) is flushed as a packet. This is the mode to use when the device’s protocol has no framing, or when you just want to observe the raw stream.

Constants

Example

The example below collects raw data and uploads it to the cloud every 1,000 ms or whenever 1,024 bytes have accumulated. It also shows a second variant gated by a trigger input, which reads only once per Cloud Trigger signal.

FIXED

For protocols where every packet is the same size. The reader scans the stream for start, then reads exactly payload(bytes) more bytes.

Emitted packet: start + payload(bytes) bytes.

Constants

Example

The example below scans for the magic word 0xAA 0xBB, then reads a 5-byte payload and uploads the combined frame to the cloud. The read cycle is gated behind a trigger input, so one packet is read per incoming trigger signal rather than continuously. If the magic word is not found within the timeout, the data is dropped.

DYNAMIC

For length-prefixed protocols, where each packet declares its own payload size in a header field. The reader:

1. Scans the stream for start.
2. Buffers offset bytes (the gap between the magic word and the length field, if any). These bytes are not interpreted — they’re just carried through to the output.
3. Reads a length(bytes)-wide integer, decoded according to endian:
   • big — the first byte read is the most significant byte (standard network byte order).
   • little — the first byte read is the least significant byte.
4. Adds adjustment to the decoded value, and reads that many payload bytes.

Emitted packet: start + offset gap bytes + length field + payload. The header bytes are all included in the output, so downstream nodes (like Bytes to Value) see the full frame.

If the adjusted length is 0, the packet is emitted with just the header. If it is negative, or the total packet would exceed 256 KiB, the packet is discarded with a warning and the reader resynchronizes on the next magic word.

Constants

Worked example. Suppose start: 0xAA 0xBB, offset: 1, length(bytes): 2, endian: big, adjustment: 2, and the following bytes arrive on the wire:

AA BB 00 01 2C 11 22 33 ...

• AA BB matches start.
• 00 is the 1 offset byte — buffered as-is, not interpreted.
• 01 2C is the 2-byte length field. Decoded as big-endian, the first byte (01) is most significant, giving 0x012C = 300.
• adjustment of 2 is added: 300 + 2 = 302 payload bytes to read.
• The reader then reads the next 302 bytes (starting from 11 22 33 ...) and emits AA BB 00 01 2C + those 302 bytes as one packet.

Had endian been little instead, the same 01 2C field would decode with 01 as the least significant byte: 0x2C01 = 11265, giving a very different (and in most protocols, wrong) payload length — so it’s important that endian matches the byte order the device actually sends.

Example

The example below scans for the magic word 0xAA 0xBB, buffers a 1-byte offset, decodes a 2-byte big-endian length field (length(bytes): 2), adds an adjustment of 2, and uploads the full frame to the cloud. As with the FIXED example, the read cycle is gated behind a trigger input, so one packet is read per trigger signal.

END

For protocols that terminate packets with a marker (for example, ASCII protocols ending in \r\n). The reader scans for start, then collects everything up to and including end.

Emitted packet: start + body + end.

Constants

Example

The example below scans for the start magic word 0xAA 0xBB, accumulates every byte until the end magic word 0xCC 0xDD appears, and uploads the full frame to the cloud. This example is likewise gated behind a trigger input, so one packet is captured per trigger signal.

Ports

• Inputs: trigger(optional):ANY - Optional. When connected, the reader waits for a message here before starting each read cycle. The message content is ignored — any data type works.
• Outputs: output:BYTES - Sends one message per completed packet.

Peripherals

• serial / ethernet - The Serial (UART) port or Ethernet channel to read from. The node itself only picks the channel; the bus’s own parameters (baud rate, data bits, IP address, connect port, etc.) are set once per channel in the Blueprint Editor’s Global Peripheral Configuration panel — see UART / Serial or Ethernet there for the exact fields.

The channel here is the UART channel defined on the device itself: 0 is UART Channel 0 and 1 is UART Channel 1, as configured in Hardware settings. Ethernet has only channel 0, and has no pins to assign — it runs over the onboard W5500 module. If the UART channel you pick has no pins assigned in Hardware settings, the reader starts but never receives any bytes.