DvG_StreamCommand
DvG_BinaryStreamCommand Class Reference

Class to manage listening to a stream, such as Serial or Wire, for incoming binary commands (or binary data packets in general) and act upon them. More...

#include <DvG_StreamCommand.h>

Public Member Functions

 DvG_BinaryStreamCommand (Stream &stream, uint8_t *buffer, uint16_t max_len, const uint8_t *EOL, uint8_t EOL_len)
 Construct a new DvG_BinaryStreamCommand object. More...
 
int8_t available (bool debug_info=false)
 Poll the stream for incoming bytes and append them one-by-one to the command buffer buffer. This method should be called repeatedly. More...
 
uint16_t getCommandLength ()
 Return the length of the command without the EOL sentinel in bytes, only when a complete command has been received. The received command can be read from the user-supplied command buffer up to this length. Otherwise, 0 is returned. More...
 
void reset ()
 TODO: descr.
 

Detailed Description

Class to manage listening to a stream, such as Serial or Wire, for incoming binary commands (or binary data packets in general) and act upon them.

We speak of a completely received 'command' once a sequence of bytes is received that matches the 'end-of-line' (EOL) sentinel. The EOL sentinel is supplied by the user and should be a single sequence of bytes of fixed length that is unique, i.e. will not appear anywhere inside of the command / data packet that it is suffixing.

The command buffer is supplied by the user and must be a fixed-size uint8_t array to store incoming bytes into.

Examples
BinaryStreamCommand.ino.

Constructor & Destructor Documentation

◆ DvG_BinaryStreamCommand()

DvG_BinaryStreamCommand::DvG_BinaryStreamCommand ( Stream &  stream,
uint8_t *  buffer,
uint16_t  max_len,
const uint8_t *  EOL,
uint8_t  EOL_len 
)

Construct a new DvG_BinaryStreamCommand object.

Parameters
streamReference to a stream to listen to, e.g. Serial, Wire, etc.
bufferReference to the command buffer: A fixed-size uint8_t array which will be managed by this class to hold a single incoming command.
max_lenArray size of buffer. Do not exceed the maximum size of 2^^16 = 65536 bytes.
EOLReference to the end-of-line sentinel: A fixed-size uint8_t array containing a unique sequence of bytes.
EOL_lenArray size of EOL. Do not exceed the maximum size of 2^^8 = 256 bytes.

Member Function Documentation

◆ available()

int8_t DvG_BinaryStreamCommand::available ( bool  debug_info = false)

Poll the stream for incoming bytes and append them one-by-one to the command buffer buffer. This method should be called repeatedly.

Parameters
debug_infoWhen true it will print debug information to stream as a tab-delimited list of all received bytes in HEX format. WARNING: Enabling this will likely interfere with downstream code listening in to the stream for I/O, so use it only for troubleshooting while developing.
Returns
1 (true) when a complete command has been received and its size is ready to be returned by getCommandLength(). Otherwise 0 (false) when no complete command has been received yet, or -1 (true!) as a special value to indicate that the command buffer was overrun and that the exceeding byte got dropped.
Examples
BinaryStreamCommand.ino.

◆ getCommandLength()

uint16_t DvG_BinaryStreamCommand::getCommandLength ( )

Return the length of the command without the EOL sentinel in bytes, only when a complete command has been received. The received command can be read from the user-supplied command buffer up to this length. Otherwise, 0 is returned.

Returns
uint16_t
Examples
BinaryStreamCommand.ino.

The documentation for this class was generated from the following files: