Detailed Description

lbuild module: modm:communication:amnb

The AMNB (Asynchronous Multi-Node Bus) is a RPC communication system over a shared half-duplex UART bus. It is intended as a low-cost replacement for higher level protocols like CAN or Ethernet, which are not available in every device unlike UART.

A node can provide two communication services, each with an 8-bit ID:

• publish/subscribe: sent to everyone and received by anyone.
• request/response: sent to one node which then sends a response.

Messages support up to 28 bytes of in-place data, and up to 8kB of heap data and are protected with 8-bit and 16-bit CCIT CRC sums. The receiving node can refuse to allocate any data, which will discard messages with >28B payload, or define a dynamic allocation threshold (for example <=1kB) above which the message will also be refused. This allows devices with very little RAM resources to share the same bus and same protocol as larger devices.

Nodes are identified with a unique 8-bit address. The protocol does not define a central node, so any node can initiate communication as arbitration is provided via a CSMA/CD mechanism, with the retransmission count and backoff time controlled by the service ID, with higher IDs having higher priority.

Data serialization is done by copying their memory representation and are described as C/C++ types which must be available for both the sender and receiver, for example, in the form of shared header files. The types must be trivially constructable, since no constructor (or destructor) is called.

Electrical Configuration

The protocol requires an open-drain + pullup config on the UART TX pin and an input + pullup config on the RX pin. Additionally, a loopback from TX to RX is required so that collisions can be detected.

There are three bus configurations:

>

1. Some UART peripherals have a built-in half-duplex mode, where the TX/RX pins are connected internally. The bus is just one pin now with an external pullup or if you use internal pullups with a slow baudrate, zero external components.

   ┌────────┐ ┌────────┐ ┌────────┐

   │ Node │ │ Node │ │ Node │

   │ TxRx │ │ TxRx │ │ TxRx │

   └───┬────┘ └───┬────┘ └───┬────┘

   └───────────┴───────────┘

2. Alternately you can connect all TX pins and RX pins together in two separate lines and use a diode from RX ->- TX to create the loopback with internal or external pullups:

   ┌────────┐ ┌────────┐ ┌────────┐

   │ Node │ │ Node │ │ Node │

   │ Tx Rx │ │ Tx Rx │ │ Tx Rx │

   └─┬───┬──┘ └─┬───┬──┘ └─┬───┬──┘

   │ └───────┼───┴───────┼───┘

   └───────────┴───────────┘─◄─┘ <- diode

3. And lastly you can use a differential transceiver with automatic direction control (like a CAN transceiver) to connect nodes that are further away. Note that you can still connect local nodes before the transceiver (but without the diode now):

   ┌────────┐ ┌────────┐ ┌────────┐

   │ Node │ │ Node │ │ Node │

   │ Tx Rx │ │ Tx Rx │ │ Tx Rx │

   └─┬───┬──┘ └─┬───┬──┘ ┌────────┐ ┌────────┐ └─┬───┬──┘

   │ └───────┼───┴─────┤ Trans- ╞═╦═╦═╦═╡ Trans- ├────┼───┘

   └───────────┴─────────┤ ceiver ╞═╩═╩═╩═╡ ceiver ├────┘

   └────────┘ └────────┘

Note that small glitches on the bus can be interpreted as a UART start condition and will trigger a byte reception. In order to recognize this, the UART must be configured as 8 data bits and 1 even parity bit (9E1)!

Subscription and Response Handlers

A list of the types modm::amnb::Listener and modm::amnb::Action store the callbacks for the IDs you want to subscribe to. The callbacks store a closure up to size MODM_AMNB_HANDLER_STORAGE, which can be overwritten to increase storage. The argument type is deduced from the callback's signature and it must match the message size otherwise the message is discarded.

Warning

Data lifetime ends after callback The received message is deallocated immediately after all callback have been executed. You must therefore copy any data you want to keep inside the callback.

All listeners are given the sender ID as first argument and return nothing. The second argument is optional and may be a type passed as const reference or a const data buffer:

Actions don't know the sender, and are passed either nothing, a const argument reference or a const data buffer. They can return a modm::amnb::Response with an optional return type, or a modm::amnb::ErrorResponse with an optional user error type. Not returning anything still sends an implicit (good) Response.

Publish and Request Node

The node class manages the whole stack via its update() function which must be called in the main loop continuously.

To broadcast, the node.broadcast(id, args) function places the message in the transmit queue, the size of which you can control. It returns false if the queue is full.

Requests node.request<ReturnType=void>(id, args) must be made from within a fiber, since they can take some time. The response is a modm::amnb::Result object, which contains the result, system error and user error.

Note that if a request returns a user error type, you must define it as node.request<ReturnType, UserErrorType>(id, args) and then explicitly check for it via response.hasUserError(). Note that the request itself may fail at a system level, for example sending a request with a payload too large for the receiver will return with a modm::amnb::Error::RequestAllocationFailed error.

Warning

Result lifetime only valid until node.update() The result is only valid until the next call to node.update(), therefore you must copy the result into your own storage!

Do not use requests in the main function! node.update() must be called during requests to service the protocol and node.request(...) won't call it, creating a deadlock!

Wire Format

There are three message formats:

>
1. Messages without payload
2. Messages with payloads up to 28B
3. Messages with payloads up to 8kB

The header contains these common fields:

• SYNC: Synchronization sequence
• CRC8: checksum for the header
• ADDR: Node address (sender or receiver)
• COMMAND: Command code (listener/action ID)
• TYPE: Message type (upper 3 bits)

Note that there are two sync bytes prefixed to every messages, since the UART hardware in most devices does not signal when it is receiving, therefore collision avoidance it not possible for the first byte, only collision detection and only after the first byte has been sent. The second byte acts as a "detection buffer" in case another node starts sending during the first byte.

Messages with <=28B data:

• CRC8: checksum for the header and data
• TYPE/LENGTH: Message type (upper 3 bits) and length (lower 5 bits) <= 28

Messages with <8kB data:

• `TYPE`: lower 5 bits >28
• LENGTH: >28 and <8k
• CRC16: checksum for the data
• DATA: Up to 8kB payload (nodes may support much less though!)

Module Options

modm:communication:amnb:with_heap: Allow large messages to allocate on the heap.

Generated with: yes in [yes, no]

Enumeration Type Documentation