@callback 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.

@callback 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.

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

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 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.

@callback 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.