Manager class for addressed, unreliable messages. More...

#include <RHDatagram.h>

Inheritance diagram for RHDatagram:

Public Member Functions
	RHDatagram (RHGenericDriver &driver, uint8_t thisAddress=0)

bool	init ()

void	setThisAddress (uint8_t thisAddress)

bool	sendto (uint8_t *buf, uint8_t len, uint8_t address)

bool	recvfrom (uint8_t buf, uint8_t len, uint8_t from=NULL, uint8_t to=NULL, uint8_t id=NULL, uint8_t flags=NULL)

bool	available ()

void	waitAvailable (uint16_t polldelay=0)

bool	waitPacketSent ()

bool	waitPacketSent (uint16_t timeout)

bool	waitAvailableTimeout (uint16_t timeout, uint16_t polldelay=0)

void	setHeaderTo (uint8_t to)

void	setHeaderFrom (uint8_t from)

void	setHeaderId (uint8_t id)

void	setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_NONE)

uint8_t	headerTo ()

uint8_t	headerFrom ()

uint8_t	headerId ()

uint8_t	headerFlags ()

uint8_t	thisAddress ()

Protected Attributes
RHGenericDriver &	_driver
	The Driver we are to use.

uint8_t	_thisAddress
	The address of this node.

Detailed Description

Manager class for addressed, unreliable messages.

Every RHDatagram node has an 8 bit address (defaults to 0). Addresses (DEST and SRC) are 8 bit integers with an address of RH_BROADCAST_ADDRESS (0xff) reserved for broadcast.

Media Access Strategy

RHDatagram and the underlying drivers always transmit as soon as sendto() is called.

Message Lengths

Not all Radio drivers supported by RadioHead can handle the same message lengths. Some radios can handle up to 255 octets, and some as few as 28. If you attempt to send a message that is too long for the underlying driver, sendTo() will return false and will not transmit the message. It is the programmers responsibility to make sure that messages passed to sendto() do not exceed the capability of the radio. You can use the *_MAX_MESSAGE_LENGTH definitions or driver->maxMessageLength() to help.

Headers

Each message sent and received by a RadioHead driver includes 4 headers:
TO The node address that the message is being sent to (broadcast RH_BROADCAST_ADDRESS (255) is permitted)
FROM The node address of the sending node
ID A message ID, distinct (over short time scales) for each message sent by a particilar node
FLAGS A bitmask of flags. The most significant 4 bits are reserved for use by RadioHead. The least significant 4 bits are reserved for applications.

Constructor & Destructor Documentation

◆ RHDatagram()

RHDatagram::RHDatagram	(	RHGenericDriver &	driver,
		uint8_t	thisAddress = `0`
	)

Constructor.

Parameters

[in]	driver	The RadioHead driver to use to transport messages.
[in]	thisAddress	The address to assign to this node. Defaults to 0

Member Function Documentation

◆ available()

bool RHDatagram::available ( )

Tests whether a new message is available from the Driver. On most drivers, this will also put the Driver into RHModeRx mode until a message is actually received bythe transport, when it will be returned to RHModeIdle. This can be called multiple times in a timeout loop.

Returns: true if a new, complete, error-free uncollected message is available to be retreived by recv()

References _driver, and RHGenericDriver::available().

Referenced by RHReliableDatagram::recvfromAck().

◆ headerFlags()

uint8_t RHDatagram::headerFlags ( )

Returns the FLAGS header of the last received message

Returns: The FLAGS header of the most recently received message.

References _driver, and RHGenericDriver::headerFlags().

Referenced by recvfrom().

◆ headerFrom()

uint8_t RHDatagram::headerFrom ( )

Returns the FROM header of the last received message

Returns: The FROM header of the most recently received message.

References _driver, and RHGenericDriver::headerFrom().

Referenced by RHMesh::doArp(), RHMesh::peekAtMessage(), recvfrom(), RHMesh::recvfromAck(), and RHMesh::route().

◆ headerId()

uint8_t RHDatagram::headerId ( )

Returns the ID header of the last received message

Returns: The ID header of the most recently received message.

References _driver, and RHGenericDriver::headerId().

Referenced by recvfrom().

◆ headerTo()

uint8_t RHDatagram::headerTo ( )

Returns the TO header of the last received message

Returns: The TO header of the most recently received message.

References _driver, and RHGenericDriver::headerTo().

Referenced by recvfrom().

◆ init()

bool RHDatagram::init ( )

Initialise this instance and the driver connected to it.

References _driver, _thisAddress, RHGenericDriver::init(), and setThisAddress().

Referenced by RHRouter::init().

◆ recvfrom()

bool RHDatagram::recvfrom	(	uint8_t *	buf,
		uint8_t *	len,
		uint8_t *	from = `NULL`,
		uint8_t *	to = `NULL`,
		uint8_t *	id = `NULL`,
		uint8_t *	flags = `NULL`
	)

Turns the receiver on if it not already on. If there is a valid message available for this node, copy it to buf and return true The SRC address is placed in *from if present and not NULL. The DEST address is placed in *to if present and not NULL. If a message is copied, *len is set to the length. You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters

[in]	buf	Location to copy the received message
[in,out]	len	Pointer to the number of octets available in buf. The number be reset to the actual number of octets copied.
[in]	from	If present and not NULL, the referenced uint8_t will be set to the FROM address
[in]	to	If present and not NULL, the referenced uint8_t will be set to the TO address
[in]	id	If present and not NULL, the referenced uint8_t will be set to the ID
[in]	flags	If present and not NULL, the referenced uint8_t will be set to the FLAGS (not just those addressed to this node).

Returns: true if a valid message was copied to buf

References _driver, headerFlags(), headerFrom(), headerId(), headerTo(), and RHGenericDriver::recv().

Referenced by RHReliableDatagram::recvfromAck(), and RHReliableDatagram::sendtoWait().

◆ sendto()

bool RHDatagram::sendto	(	uint8_t *	buf,
		uint8_t	len,
		uint8_t	address
	)

Sends a message to the node(s) with the given address RH_BROADCAST_ADDRESS is a valid address which will cause the message to be accepted by all RHDatagram nodes within range.

Parameters

[in]	buf	Pointer to the binary message to send
[in]	len	Number of octets to send (> 0)
[in]	address	The address to send the message to.

Returns: true if the message not too loing fot eh driver, and the message was transmitted.

References _driver, RHGenericDriver::send(), and setHeaderTo().

Referenced by RHReliableDatagram::acknowledge(), and RHReliableDatagram::sendtoWait().

◆ setHeaderFlags()

void RHDatagram::setHeaderFlags	(	uint8_t	set,
		uint8_t	clear = `RH_FLAGS_NONE`
	)

Sets and clears bits in the FLAGS header to be sent in all subsequent messages

Parameters

[in]	set	bitmask of bits to be set
[in]	clear	bitmask of flags to clear

References _driver, and RHGenericDriver::setHeaderFlags().

Referenced by RHReliableDatagram::acknowledge(), and RHReliableDatagram::sendtoWait().

◆ setHeaderFrom()

void RHDatagram::setHeaderFrom ( uint8_t from )

Sets the FROM header to be sent in all subsequent messages

Parameters

[in] from The new FROM header value

References _driver, and RHGenericDriver::setHeaderFrom().

Referenced by setThisAddress().

◆ setHeaderId()

void RHDatagram::setHeaderId ( uint8_t id )

Sets the ID header to be sent in all subsequent messages

Parameters

[in] id The new ID header value

References _driver, and RHGenericDriver::setHeaderId().

Referenced by RHReliableDatagram::acknowledge(), and RHReliableDatagram::sendtoWait().

◆ setHeaderTo()

void RHDatagram::setHeaderTo ( uint8_t to )

Sets the TO header to be sent in all subsequent messages

Parameters

[in] to The new TO header value

References _driver, and RHGenericDriver::setHeaderTo().

Referenced by sendto().

◆ setThisAddress()

void RHDatagram::setThisAddress ( uint8_t thisAddress )

Sets the address of this node. Defaults to 0. This will be used to set the FROM address of all messages sent by this node. In a conventional multinode system, all nodes will have a unique address (which you could store in EEPROM).

Parameters

[in] thisAddress The address of this node

References _driver, _thisAddress, setHeaderFrom(), RHGenericDriver::setThisAddress(), and thisAddress().

Referenced by init().

◆ thisAddress()

uint8_t RHDatagram::thisAddress ( )

Returns the address of this node.

Returns: The address of this node

References _thisAddress.

Referenced by setThisAddress().

◆ waitAvailable()

void RHDatagram::waitAvailable ( uint16_t polldelay = 0 )

Starts the Driver receiver and blocks until a valid received message is available.

Parameters

[in] polldelay Time between polling available() in milliseconds. This can be useful in multitaking environment like Linux to prevent waitAvailableTimeout using all the CPU while polling for receiver activity

References _driver, and RHGenericDriver::waitAvailable().

◆ waitAvailableTimeout()

bool RHDatagram::waitAvailableTimeout	(	uint16_t	timeout,
		uint16_t	polldelay = `0`
	)

Starts the Driver receiver and blocks until a received message is available or a timeout

Parameters

[in]	timeout	Maximum time to wait in milliseconds.
[in]	polldelay	Time between polling available() in milliseconds. This can be useful in multitaking environment like Linux to prevent waitAvailableTimeout using all the CPU while polling for receiver activity

Returns: true if a message is available

References _driver, and RHGenericDriver::waitAvailableTimeout().

Referenced by RHMesh::doArp(), RHReliableDatagram::recvfromAckTimeout(), RHMesh::recvfromAckTimeout(), RHRouter::recvfromAckTimeout(), and RHReliableDatagram::sendtoWait().

◆ waitPacketSent() [1/2]

bool RHDatagram::waitPacketSent ( )

Blocks until the transmitter is no longer transmitting.

References _driver, and RHGenericDriver::waitPacketSent().

Referenced by RHReliableDatagram::acknowledge(), and RHReliableDatagram::sendtoWait().

◆ waitPacketSent() [2/2]

bool RHDatagram::waitPacketSent ( uint16_t timeout )

Blocks until the transmitter is no longer transmitting. or until the timeout occuers, whichever happens first

Parameters

[in] timeout Maximum time to wait in milliseconds.

Returns: true if the radio completed transmission within the timeout period. False if it timed out.

References _driver, and RHGenericDriver::waitPacketSent().

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

RHDatagram.h
RHDatagram.cpp

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RHDatagram()

Member Function Documentation

◆ available()

◆ headerFlags()

◆ headerFrom()

◆ headerId()

◆ headerTo()

◆ init()

◆ recvfrom()

◆ sendto()

◆ setHeaderFlags()

◆ setHeaderFrom()

◆ setHeaderId()

◆ setHeaderTo()

◆ setThisAddress()

◆ thisAddress()

◆ waitAvailable()

◆ waitAvailableTimeout()

◆ waitPacketSent() [1/2]

◆ waitPacketSent() [2/2]