A template class enabling packet-based Serial communication. More...

#include <PacketSerial.h>

Public Types
typedef void(*	PacketHandlerFunction) (const uint8_t *buffer, size_t size)
	A typedef describing the packet handler method. More...

typedef void(*	PacketHandlerFunctionWithSender) (const void sender, const uint8_t buffer, size_t size)
	A typedef describing the packet handler method. More...

Public Member Functions
	PacketSerial_ ()
	Construct a default PacketSerial_ device.

	~PacketSerial_ ()
	Destroy the PacketSerial_ device.

void	begin (unsigned long speed)
	Begin a default serial connection with the given speed. More...

void	begin (unsigned long speed, size_t port) __attribute__((deprecated))
	Deprecated. Use setStream() to configure a non-default port. More...

void	begin (Stream *stream) __attribute__((deprecated))
	Deprecated. Use setStream() to configure a non-default port. More...

void	setStream (Stream *stream)
	Attach PacketSerial to an existing Arduino `Stream`. More...

Stream *	getStream ()
	Get a pointer to the current stream. More...

const Stream *	getStream () const
	Get a pointer to the current stream. More...

void	update ()
	The update function services the serial connection. More...

void	send (const uint8_t *buffer, size_t size) const
	Set a packet of data. More...

void	setPacketHandler (PacketHandlerFunction onPacketFunction)
	Set the function that will receive decoded packets. More...

void	setPacketHandler (PacketHandlerFunctionWithSender onPacketFunctionWithSender)
	Set the function that will receive decoded packets. More...

bool	overflow () const
	Check to see if the receive buffer overflowed. More...

Detailed Description

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>
class PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >

A template class enabling packet-based Serial communication.

Typically one of the typedefined versions are used, for example, COBSPacketSerial or SLIPPacketSerial.

The template parameters allow the user to define their own packet encoder / decoder, custom packet marker and receive buffer size.

Template Parameters

EncoderType	The static packet encoder class name.
PacketMarker	The byte value used to mark the packet boundary.
BufferSize	The number of bytes allocated for the receive buffer.

Member Typedef Documentation

◆ PacketHandlerFunction

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

typedef void(* PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::PacketHandlerFunction) (const uint8_t *buffer, size_t size)

A typedef describing the packet handler method.

The packet handler method usually has the form:

void onPacketReceived(const uint8_t* buffer, size_t size);

where buffer is a pointer to the incoming buffer array, and size is the number of bytes in the incoming buffer.

◆ PacketHandlerFunctionWithSender

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

typedef void(* PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::PacketHandlerFunctionWithSender) (const void *sender, const uint8_t *buffer, size_t size)

A typedef describing the packet handler method.

The packet handler method usually has the form:

void onPacketReceived(void* sender, const uint8_t* buffer, size_t size);

where sender is a pointer to the PacketSerial_ instance that recieved the buffer, buffer is a pointer to the incoming buffer array, and size is the number of bytes in the incoming buffer.

Member Function Documentation

◆ begin() [1/3]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::begin ( unsigned long speed )

inline

Begin a default serial connection with the given speed.

The default Serial port Serial and default config SERIAL_8N1 will be used. For example:

PacketSerial myPacketSerial;

void setup()
{
    myPacketSerial.begin(9600);
}

This is a convenience method. For more complex Serial port configurations, use the setStream() function to set an arbitrary Arduino Stream.

Parameters

speed The serial data transmission speed in bits / second (baud).

See also: https://www.arduino.cc/en/Serial/Begin

◆ begin() [2/3]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::begin	(	unsigned long	speed,
		size_t	port
	)

inline

Deprecated. Use setStream() to configure a non-default port.

Parameters

speed	The serial data transmission speed in bits / second (baud).
port	The Serial port number (e.g. 0 is Serial, 1 is Serial1).

Deprecated:: Use setStream() to configure a non-default port.

◆ begin() [3/3]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::begin ( Stream * stream )

inline

Deprecated. Use setStream() to configure a non-default port.

Parameters

stream A pointer to an Arduino Stream.

Deprecated:: Use setStream() to configure a non-default port.

◆ getStream() [1/2]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

Stream* PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::getStream ( )

inline

Get a pointer to the current stream.

Warning: Reading from or writing to the stream managed by PacketSerial_ may break the packet-serial protocol if not done so with care. Access to the stream is allowed because PacketSerial_ never takes ownership of the stream and thus does not have exclusive access to the stream anyway.

Returns: a non-const pointer to the stream, or nullptr if unset.

◆ getStream() [2/2]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

const Stream* PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::getStream ( ) const

inline

Get a pointer to the current stream.

Warning: Reading from or writing to the stream managed by PacketSerial_ may break the packet-serial protocol if not done so with care. Access to the stream is allowed because PacketSerial_ never takes ownership of the stream and thus does not have exclusive access to the stream anyway.

Returns: a const pointer to the stream, or nullptr if unset.

◆ overflow()

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

bool PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::overflow ( ) const

inline

Check to see if the receive buffer overflowed.

This must be called often, directly after the update() function.

void loop()
{
    // Other program code.
    myPacketSerial.update();

    // Check for a receive buffer overflow.
    if (myPacketSerial.overflow())
    {
        // Send an alert via a pin (e.g. make an overflow LED) or return a
        // user-defined packet to the sender.
        //
        // Ultimately you may need to just increase your recieve buffer via the
        // template parameters.
    }
}

The state is reset every time a new packet marker is received NOT when overflow() method is called.

Returns: true if the receive buffer overflowed.

◆ send()

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::send	(	const uint8_t *	buffer,
		size_t	size
	)		const

inline

Set a packet of data.

This function will encode and send an arbitrary packet of data. After sending, it will send the specified PacketMarker defined in the template parameters.

// Make an array.
uint8_t myPacket[2] = { 255, 10 };

// Send the array.
myPacketSerial.send(myPacket, 2);

Parameters

buffer	A pointer to a data buffer.
size	The number of bytes in the data buffer.

◆ setPacketHandler() [1/2]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::setPacketHandler ( PacketHandlerFunction onPacketFunction )

inline

Set the function that will receive decoded packets.

This function will be called when data is read from the serial stream connection and a packet is decoded. The decoded packet will be passed to the packet handler. The packet handler must have the form:

The packet handler method usually has the form:

void onPacketReceived(const uint8_t* buffer, size_t size);

The packet handler would then be registered like this:

myPacketSerial.setPacketHandler(&onPacketReceived);

Setting a packet handler will remove all other packet handlers.

Parameters

onPacketFunction A pointer to the packet handler function.

◆ setPacketHandler() [2/2]

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::setPacketHandler ( PacketHandlerFunctionWithSender onPacketFunctionWithSender )

inline

Set the function that will receive decoded packets.

This function will be called when data is read from the serial stream connection and a packet is decoded. The decoded packet will be passed to the packet handler. The packet handler must have the form:

The packet handler method usually has the form:

void onPacketReceived(const void* sender, const uint8_t* buffer, size_t size);

To determine the sender, compare the pointer to the known possible PacketSerial senders.

void onPacketReceived(void* sender, const uint8_t* buffer, size_t size)
{
    if (sender == &myPacketSerial)
    {
        // Do something with the packet from myPacketSerial.
    }
    else if (sender == &myOtherPacketSerial)
    {
        // Do something with the packet from myOtherPacketSerial.
    }
}

The packet handler would then be registered like this:

myPacketSerial.setPacketHandler(&onPacketReceived);

Setting a packet handler will remove all other packet handlers.

Parameters

onPacketFunctionWithSender A pointer to the packet handler function.

◆ setStream()

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::setStream ( Stream * stream )

inline

Attach PacketSerial to an existing Arduino Stream.

This Stream could be a standard Serial Stream with a non-default configuration such as:

PacketSerial myPacketSerial;

void setup()
{
    Serial.begin(300, SERIAL_7N1);
    myPacketSerial.setStream(&Serial);
}

Or it might be a SoftwareSerial Stream such as:

PacketSerial myPacketSerial;
SoftwareSerial mySoftwareSerial(10, 11);

void setup()
{
    mySoftwareSerial.begin(38400);
    myPacketSerial.setStream(&mySoftwareSerial);
}

Any class that implements the Stream interface should work, which includes some network objects.

Parameters

stream A pointer to an Arduino Stream.

◆ update()

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>

void PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >::update ( )

inline

The update function services the serial connection.

This must be called often, ideally once per loop(), e.g.:

void loop()
{
    // Other program code.

    myPacketSerial.update();
}

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

/home/travis/build/bakercp/PacketSerial/src/PacketSerial.h

Public Types

Public Member Functions

Detailed Description

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256> class PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >

Member Typedef Documentation

◆ PacketHandlerFunction

◆ PacketHandlerFunctionWithSender

Member Function Documentation

◆ begin() [1/3]

◆ begin() [2/3]

◆ begin() [3/3]

◆ getStream() [1/2]

◆ getStream() [2/2]

◆ overflow()

◆ send()

◆ setPacketHandler() [1/2]

◆ setPacketHandler() [2/2]

◆ setStream()

◆ update()

template<typename EncoderType, uint8_t PacketMarker = 0, size_t ReceiveBufferSize = 256>
class PacketSerial_< EncoderType, PacketMarker, ReceiveBufferSize >