Circuits.UART v1.4.1 Circuits.UART.Framing behaviour View Source

A behaviour for implementing framers for data received over a UART.

Link to this section Summary

Callbacks

Add framing to the passed in data.

This is called when the user invokes Circuits.UART.flush/2. Any partially received frames should be dropped.

If remove_framing/2 returned :in_frame and a user-specified timeout for reassembling frames has elapsed, then this function is called. Depending on the semantics of the framing, a partial frame may be returned or the incomplete frame may be dropped.

init(args)

Initialize the state of the framer based on options passed to Circuits.UART.open/3.

remove_framing(new_data, state)

Remove the framing off received data. If a partial frame is left over at the end, then :in_frame should be returned. All of the frames received should be returned in the second tuple.

Link to this section Callbacks

add_framing(data, state)

add_framing(data :: term(), state :: term()) ::
  {:ok, framed_data, new_state} | {:error, reason, new_state}
when new_state: term(), framed_data: binary(), reason: term()

Add framing to the passed in data.

The returned frame_data will be sent out the UART.

flush(direction, state)

flush(direction :: :receive | :transmit | :both, state :: term()) :: new_state
when new_state: term()

This is called when the user invokes Circuits.UART.flush/2. Any partially received frames should be dropped.

frame_timeout(state)

frame_timeout(state :: term()) :: {:ok, [term()], new_state}
when new_state: term()

init(args)

init(args :: term()) :: {:ok, state} | {:error, reason}
when state: term(), reason: term()

Initialize the state of the framer based on options passed to Circuits.UART.open/3.

This function should return the initial state for the framer or an error.

remove_framing(new_data, state)

remove_framing(new_data :: binary(), state :: term()) ::
  {:in_frame, [term()], new_state} | {:ok, [term()], new_state}
when new_state: term()

Remove the framing off received data. If a partial frame is left over at the end, then :in_frame should be returned. All of the frames received should be returned in the second tuple.

The terms returned as the second part of the tuple can be anything. They can be the binary messages without the framing, structs based on your commands, or anything else. If you have errors in the protocol, for example a bad checksum, one convention is to return an error tuple {:error, :echksum, message}. For debugging you may want to include the message and framing with the error for simpler debugging.