Circuits.UART

v1.3.0

Circuits.UART v1.3.0 Circuits.UART.Framing.Line View Source

Each message is one line. This framer appends and removes newline sequences as part of the framing. Buffering is performed internally, so users can get the complete messages under normal circumstances. Attention should be paid to the following:

  1. Lines must have a fixed max length so that a misbehaving sender can’t cause unbounded buffer expansion. When the max length is passed, a {:partial, data} is reported. The application can decide what to do with this.
  2. The separation character varies depending on the target device. Some devices require “\r\n” sequences, so be sure to specify this. Currently only one or two character separators are supported.
  3. It may be desirable to set a :rx_framer_timeout to prevent characters received in error from collecting during idle times. When the receive timer expires, {:partial, data} is reported.
  4. Line separators must be ASCII characters (0-127) or be valid UTF-8 sequences. If the device only sends ASCII, high characters (128-255) should work as well. [Note: please report if using extended characters.]

Link to this section Summary

Functions

add_framing(data, state)

Add framing to the passed in data

buffer_empty?(state)
flush(direction, state)

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

frame_timeout(state)

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(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 Functions

Link to this function add_framing(data, state) View Source

Add framing to the passed in data.

The returned frame_data will be sent out the UART.

Callback implementation for Circuits.UART.Framing.add_framing/2.

Link to this function flush(direction, state) View Source

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

Callback implementation for Circuits.UART.Framing.flush/2.

Link to this function frame_timeout(state) View Source

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.

Callback implementation for Circuits.UART.Framing.frame_timeout/1.

Link to this function init(args) View Source

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.

Callback implementation for Circuits.UART.Framing.init/1.

Link to this function remove_framing(data, state) View Source

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.

Callback implementation for Circuits.UART.Framing.remove_framing/2.