Router

pw_hdlc: Simple, robust, and efficient serial communication

pw_hdlc::Router is an experimental asynchronous HDLC router using pw_channel.

It sends and receives HDLC packets using an external byte-oriented channel and routes the decoded packets to local datagram-oriented channels.

API

class Router

A router that multiplexes multiple datagram-oriented Channel s over a single byte-oriented Channel using HDLC framing.

Public Functions

inline Router(pw::channel::ByteReaderWriter &io_channel, ByteSpan decode_buffer)

Constructs a Router

Parameters:

• io_channel – [in] The channel on which to send and receive encoded HDLC packets.

• decode_buffer – [in] The memory to use for storing partially-decoded HDLC frames. This buffer should be at least Decoder::RequiredBufferSizeForFrameSize(frame_size) bytes in order to ensure that HDLC frames of size frame_size can be successfully decoded.

Status AddChannel(pw::channel::DatagramReaderWriter &channel, uint64_t receive_address, uint64_t send_address)

Registers a Channel tied to the provided addresses.

All incoming HDLC messages received on io_channel with HDLC address receive_address will be decoded and routed to the provided channel.

Data read from channel will be HDLC-encoded and sent to io_channel.

Note that a non-writeable channel will exert backpressure on the entire router, so channels should strive to consume or discard incoming data as quickly as possible in order to prevent starvation of other channels.

Parameters:

• receive_address – [in] Incoming HDLC messages received on the external io_channel with an address matching receive_address will be decoded and written to channel.

• send_address – [in] Data read from channel will be written to io_channel with the HDLC address send_address.

Returns:

Code	Description
OK	Channel was successfully registered.
ALREADY_EXISTS	A registration already exists for either channel, receive_address, or send_address. Channels may not be registered with multiple addresses, nor may addresses be used with multiple channels.

Status RemoveChannel(pw::channel::DatagramReaderWriter &channel, uint64_t receive_address, uint64_t send_address)

Removes a previously registered Channel tied to the provided addresses.

Returns:

Code	Description
OK	The channel was successfully deregistered.
NOT_FOUND	A registration of the channel for the provided addresses was not found.

pw::async2::Poll Pend(pw::async2::Context &cx)

Progress the router as far as possible, waking the provided cx when more progress can be made.

This will only return Ready if io_channel has been observed as closed, after which all messages have been flushed to the remaining channels and the channels have been closed.

pw::async2::Poll PendClose(pw::async2::Context &cx)

Closes all underlying channels, attempting to flush any data.

More pw_hdlc docs

Get started & guides

How to set up and use pw_hdlc

API reference

Reference details about the pw_hdlc API

Design

Design details about pw_hdlc

Code size analysis

The code size impact of pw_hdlc

RPC over HDLC example

A step-by-step example of sending RPCs over HDLC

Experimental async router

An experimental asynchronous HDLC router using pw_channel