PPNet

Message protocol with error correction (Reed-Solomon) and framing (COBS).

Installation

If available on Hex, add the dependency to your list in mix.exs:

def deps do
  [
    {:pp_net, "~> 0.1.4"}
  ]
end

Transport layer: COBS and Reed-Solomon

Each message is encoded in two stages before being sent on the wire:

1. Frame
   Build the frame: type (1 byte) + body (variable). There is no separate checksum field; Reed-Solomon provides integrity.

2. Reed-Solomon
   The frame is encoded with Reed-Solomon (8 parity bytes), allowing up to 4 corrupted bytes in the block to be corrected. Maximum block size is 255 bytes (typical RS limit in GF(2⁸)).

3. COBS
   The result is encoded with COBS (Consistent Overhead Byte Stuffing): the byte 0x00 is reserved as the frame delimiter, and the payload is escaped so it never contains 0x00. Frames can thus be delimited reliably in a stream.

4. Separator
   A single 0x00 byte is appended after each encoded message, marking the end of the frame.

Decoding: the receiver splits the stream on 0x00, decodes each block with COBS, applies Reed-Solomon to correct errors, then parses the frame (type + body).

Frame structure (after Reed-Solomon)

All messages share the same logical layout before COBS:

The full block (type + body) is protected by 8 Reed-Solomon parity bytes.

Message formats (body)

Types 1–4: MessagePack body

Hello (1), SingleCounter (2), Ping (3), and Event (4) use MessagePack for the body.

Type 1 — Hello

Body: MessagePack array (fields in order).

Backward compatibility: A 6-element list without datetime is still accepted; datetime will be nil.

Type 2 — SingleCounter

Body: MessagePack array.

Backward compatibility: A 4-element list without datetime is still accepted; datetime will be nil.

Type 3 — Ping

Body: MessagePack array with 11 elements in order:

Backward compatibility: A 9-element list without session_id is still accepted; session_id will be nil. A 10-element list without datetime is still accepted; datetime will be nil.

WiFi encoding: Each entry is 7 bytes: MAC address as 6 raw bytes (no colon-separated string), then RSSI as one signed byte. This keeps the payload small so the ping stays within a single frame.

Type 4 — Event

Body: MessagePack array [kind, data, datetime].

Backward compatibility: A 2-element list without datetime is still accepted; datetime will be nil.

Type 5 — Image

Body: fixed header + raw image data.

H.264 (4):data must be an Annex-B byte stream — NAL units prefixed with a 00 00 01 or 00 00 00 01 start code. pack/1 rejects other framings (e.g. AVCC/length-prefixed) with %PPNet.PackError{reason: :not_annex_b}.

Backward compatibility: The old format (id + format + data without datetime/data_size) is still accepted; datetime will be nil.

When the encoded image (or any message) exceeds the channel limit, it is sent as chunked messages (types 6 and 7).

Type 6 — ChunkedMessageHeader (chunked message header)

Used when the payload is too large for a single frame (e.g. image). The body is fixed binary.

message_module_code indicates the original message type (1=Hello, 2=SingleCounter, 3=Ping, 4=Event, 5=Image). Total header body: 11 bytes.

Type 7 — ChunkedMessageBody (fragment)

chunk_size is the length in bytes of chunk_data. Fragments are reassembled by transaction_id and ordered by chunk_index.

Backward compatibility: The old format without datetime is still accepted; datetime will be nil.

Usage

• Encode a message: PPNet.encode_message(message) returns a single binary, or a list [header_binary | chunk_binaries] when the message is chunked (e.g. large image). You can pass limit: n to force chunking when the encoded size would exceed n bytes (default 254).

• Parse a stream: PPNet.parse(binary) returns %{messages: [...], errors: [...]}. Each element of messages is either a decoded message struct (Hello, Ping, etc.) or a ChunkedMessageHeader / ChunkedMessageBody. Join all frames (e.g. from a stream) and call parse on the concatenated binary.

• Reassemble chunked payloads: when you have [%ChunkedMessageHeader{} | chunks] from parse, call PPNet.chunked_to_message([header | chunks]) to get {:ok, message} (or {:error, reason}). The result is the original message type (e.g. %Image{}, %Ping{}).

Example (chunked image):

image = %PPNet.Message.Image{data: raw_binary, format: :webp, datetime: DateTime.utc_now()}
[header_bin | chunk_bins] = PPNet.encode_message(image, limit: 200)
payload = [header_bin | chunk_bins] |> Enum.join()
%{messages: [header | body_messages], errors: []} = PPNet.parse(payload)
{:ok, ^image} = PPNet.chunked_to_message([header | body_messages])