Custom Framing

Custom framing is for vendor-specific protocols that look like header, length, payload, and checksum.

AA 55 02 10 34
header len payload

The business payload is only:

10 34

LengthHeaderFrameCodec adds the header, writes length, calculates checksums, and handles split/sticky packets. Your code works with payloads.

When to Use It

Manual format	Fit
AA 55 + length + data + checksum	Good fit
7E + length + command + data + CRC	Good fit
Modbus RTU / TCP	Use Modbus instead
One command per text line	May not need framing

Minimal Request/Response

await using var app = ZeusHost.Create(builder => builder.AddVirtualChannel("bus"));

await using var session = app.CreateFrameSession(
    "bus",
    new FrameLayout([0xAA, 0x55], FrameLengthKind.UInt8, FrameChecksumKind.None));

await app.StartAsync();

var reply = await session.RequestAsync(new byte[] { 0x10, 0x34 });

Default layout is AA 55 + 1-byte length + no checksum, so this is equivalent when defaults fit:

await using var session = app.CreateFrameSession("bus");

Match the Right Response

If responses include sequence numbers or commands, pass a matcher:

var sequence = (byte)0x34;

var reply = await session.RequestAsync(
    new byte[] { 0x10, sequence },
    response => response.Length >= 2
        && response.Span[0] == 0x90
        && response.Span[1] == sequence);

Only payloads matching the predicate are returned; other frames stay available for later matching.

Send Without Waiting

await session.SendAsync(new byte[] { 0x20, 0x01 });

Use this for broadcasts, heartbeats, or commands without responses.

Options

Type	Meaning
FrameLengthKind.UInt8	1-byte length, payload up to 255 bytes
UInt16LittleEndian	2-byte little-endian length
UInt16BigEndian	2-byte big-endian length
FrameChecksumKind.None	No checksum
FrameChecksumKind.Xor8	1-byte XOR checksum
FrameChecksumKind.Sum8	1-byte sum checksum
FrameChecksumKind.Crc16Modbus	Modbus CRC16, little-endian output

Checksums cover the length field and payload, not the header.

Next: if the device is standard Modbus, use Modbus.