RHDatagram subclass for sending addressed, acknowledged, retransmitted datagrams. More...

#include <RHReliableDatagram.h>

Inherited by RHRouter.

Public Member Functions
	RHReliableDatagram (RHGenericDriver &driver, uint8_t thisAddress=0)
	Constructor.
void	setTimeout (uint16_t timeout)
	Sets the minimum retransmit timeout.
void	setRetries (uint8_t retries)
	Sets the maximum number of retries.
uint8_t	retries ()
	Returns the currently configured maximum retries count.
bool	sendtoWait (uint8_t *buf, uint8_t len, uint8_t address)
	Send the message (with retries) and waits for an ack.
bool	recvfromAck (uint8_t buf, uint8_t len, uint8_t from=NULL, uint8_t to=NULL, uint8_t id=NULL, uint8_t flags=NULL)
	If there is a valid message available for this node, send an acknowledgement to the SRC address (blocking until this is complete), then copy the message to buf and return true else return false.
bool	recvfromAckTimeout (uint8_t buf, uint8_t len, uint16_t timeout, uint8_t from=NULL, uint8_t to=NULL, uint8_t id=NULL, uint8_t flags=NULL)
	Similar to recvfromAck(), this will block until either a valid message available for this node or the timeout expires.
uint32_t	retransmissions ()
	Returns the number of retransmissions we have had to send since starting or since the last call to resetRetransmissions().
void	resetRetransmissions ()
	Resets the count of the number of retransmissions to 0.
bool	init ()
	Initialise this instance and the driver connected to it.
void	setThisAddress (uint8_t thisAddress)
	Sets the address of this node.
bool	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.
bool	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.
bool	available ()
	Tests whether a new message is available from the Driver.
void	waitAvailable ()
	Starts the Driver receiver and blocks until a valid received message is available.
bool	waitPacketSent ()
	Blocks until the transmitter is no longer transmitting.
bool	waitPacketSent (uint16_t timeout)
	Blocks until the transmitter is no longer transmitting.
bool	waitAvailableTimeout (uint16_t timeout)
	Starts the Driver receiver and blocks until a received message is available or a timeout.
void	setHeaderTo (uint8_t to)
	Sets the TO header to be sent in all subsequent messages.
void	setHeaderFrom (uint8_t from)
	Sets the FROM header to be sent in all subsequent messages.
void	setHeaderId (uint8_t id)
	Sets the ID header to be sent in all subsequent messages.
void	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.
uint8_t	headerTo ()
	Returns the TO header of the last received message.
uint8_t	headerFrom ()
	Returns the FROM header of the last received message.
uint8_t	headerId ()
	Returns the ID header of the last received message.
uint8_t	headerFlags ()
	Returns the FLAGS header of the last received message.
uint8_t	thisAddress ()
	Returns the address of this node.
Protected Member Functions
void	acknowledge (uint8_t id, uint8_t from)
	Send an ACK for the message id to the given from address Blocks until the ACK has been sent.
bool	haveNewMessage ()
	Checks whether the message currently in the Rx buffer is a new message, not previously received based on the from address and the sequence.
Protected Attributes
RHGenericDriver &	_driver
	The Driver we are to use.
uint8_t	_thisAddress
	The address of this node.

Detailed Description

RHDatagram subclass for sending addressed, acknowledged, retransmitted datagrams.

Manager class that extends RHDatagram to define addressed, reliable datagrams with acknowledgement and retransmission. Based on RHDatagram, adds flags and sequence numbers. RHReliableDatagram is reliable in the sense that messages are acknowledged by the recipient, and unacknowledged messages are retransmitted until acknowledged or the retries are exhausted. When addressed messages are sent (by sendtoWait()), it will wait for an ack, and retransmit after timeout until an ack is received or retries are exhausted. When addressed messages are collected by the application (by recvfromAck()), an acknowledgement is automatically sent to the sender.

You can use RHReliableDatagram to send broadcast messages, with a TO address of RH_BROADCAST_ADDRESS, however broadcasts are not acknowledged or retransmitted and are therefore NOT actually reliable.

The retransmit timeout is randomly varied between timeout and timeout*2 to prevent collisions on all retries when 2 nodes happen to start sending at the same time .

Each new message sent by sendtoWait() has its ID incremented.

An ack consists of a message with:

TO set to the from address of the original message
FROM set to this node address
ID set to the ID of the original message
FLAGS with the RH_FLAGS_ACK bit set
1 octet of payload containing ASCII '!' (since some drivers cannot handle 0 length payloads)

Media Access Strategy

RHReliableDatagram and the underlying drivers always transmit as soon as sendtoWait() is called. RHReliableDatagram waits for an acknowledgement, and if one is not received after a timeout period the message is transmitted again. If no acknowledgement is received after several retries, the transmissions is deemed to have failed. No contention for media is detected. This will be recognised as "pure ALOHA". The addition of Clear Channel Assessment (CCA) is desirable and planned.

There is no message queuing or threading in RHReliableDatagram. sendtoWait() waits until an acknowledgement is received, retransmitting up to (by default) 3 retries time with a default 200ms timeout. During this transmit-acknowledge phase, any received message (other than the expected acknowledgement) will be ignored. Your sketch will be unresponsive to new messages until an acknowledgement is received or the retries are exhausted. Central server-type sketches should be very cautious about their retransmit strategy and configuration lest they hang for a long time trying to reply to clients that are unreachable.

Caution: if you have a radio network with a mixture of slow and fast processors and ReliableDatagrams, you may be affected by race conditions where the fast processor acknowledges a message before the sender is ready to process the acknowledgement. Best practice is to use the same processors (and radios) throughout your network.

Definition at line 78 of file RHReliableDatagram.h.

Constructor & Destructor Documentation

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

Definition at line 18 of file RHReliableDatagram.cpp.

Member Function Documentation

void acknowledge	(	uint8_t	id,
		uint8_t	from
	)		`[protected]`

Send an ACK for the message id to the given from address Blocks until the ACK has been sent.

Definition at line 176 of file RHReliableDatagram.cpp.

bool available ( ) [inherited]

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

Definition at line 52 of file RHDatagram.cpp.

bool haveNewMessage ( ) [protected]

Checks whether the message currently in the Rx buffer is a new message, not previously received based on the from address and the sequence.

If it is new, it is acknowledged and returns true

Returns:: true if there is a message received and it is a new message

uint8_t headerFlags ( ) [inherited]

Returns the FLAGS header of the last received message.

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

Definition at line 117 of file RHDatagram.cpp.

uint8_t headerFrom ( ) [inherited]

Returns the FROM header of the last received message.

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

Definition at line 107 of file RHDatagram.cpp.

uint8_t headerId ( ) [inherited]

Returns the ID header of the last received message.

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

Definition at line 112 of file RHDatagram.cpp.

uint8_t headerTo ( ) [inherited]

Returns the TO header of the last received message.

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

Definition at line 102 of file RHDatagram.cpp.

bool init ( ) [inherited]

Initialise this instance and the driver connected to it.

Reimplemented in RHRouter.

Definition at line 17 of file RHDatagram.cpp.

bool recvfrom	(	uint8_t *	buf,
		uint8_t *	len,
		uint8_t *	from = `NULL`,
		uint8_t *	to = `NULL`,
		uint8_t *	id = `NULL`,
		uint8_t *	flags = `NULL`
	)		`[inherited]`

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 available space in buf. Set 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

Definition at line 39 of file RHDatagram.cpp.

bool recvfromAck	(	uint8_t *	buf,
		uint8_t *	len,
		uint8_t *	from = `NULL`,
		uint8_t *	to = `NULL`,
		uint8_t *	id = `NULL`,
		uint8_t *	flags = `NULL`
	)

If there is a valid message available for this node, send an acknowledgement to the SRC address (blocking until this is complete), then copy the message to buf and return true else return false.

If a message is copied, *len is set to the length.. If from is not NULL, the SRC address is placed in *from. If to is not NULL, the DEST address is placed in *to. This is the preferred function for getting messages addressed to this node. If the message is not a broadcast, acknowledge to the sender before returning. 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	Available space in buf. Set to the actual number of octets copied.
[in]	from	If present and not NULL, the referenced uint8_t will be set to the SRC address
[in]	to	If present and not NULL, the referenced uint8_t will be set to the DEST 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

Reimplemented in RHMesh, and RHRouter.

Definition at line 114 of file RHReliableDatagram.cpp.

bool recvfromAckTimeout	(	uint8_t *	buf,
		uint8_t *	len,
		uint16_t	timeout,
		uint8_t *	from = `NULL`,
		uint8_t *	to = `NULL`,
		uint8_t *	id = `NULL`,
		uint8_t *	flags = `NULL`
	)

Similar to recvfromAck(), this will block until either a valid message available for this node or the timeout expires.

Starts the receiver automatically. 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	Available space in buf. Set to the actual number of octets copied.
[in]	timeout	Maximum time to wait in milliseconds
[in]	from	If present and not NULL, the referenced uint8_t will be set to the SRC address
[in]	to	If present and not NULL, the referenced uint8_t will be set to the DEST 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

Reimplemented in RHMesh, and RHRouter.

Definition at line 150 of file RHReliableDatagram.cpp.

void resetRetransmissions ( )

Resets the count of the number of retransmissions to 0.

Definition at line 171 of file RHReliableDatagram.cpp.

uint32_t retransmissions ( )

Returns the number of retransmissions we have had to send since starting or since the last call to resetRetransmissions().

Returns:: The number of retransmissions since initialisation.

Definition at line 166 of file RHReliableDatagram.cpp.

uint8_t retries ( )

Returns the currently configured maximum retries count.

Can be changed with setRetries().

Returns:: The currently configured maximum number of retries.

Definition at line 41 of file RHReliableDatagram.cpp.

bool sendto	(	uint8_t *	buf,
		uint8_t	len,
		uint8_t	address
	)		`[inherited]`

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.

Definition at line 33 of file RHDatagram.cpp.

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

Send the message (with retries) and waits for an ack.

Returns true if an acknowledgement is received. Synchronous: any message other than the desired ACK received while waiting is discarded. Blocks until an ACK is received or all retries are exhausted (ie up to retries*timeout milliseconds). If the destination address is the broadcast address RH_BROADCAST_ADDRESS (255), the message will be sent as a broadcast, but receiving nodes do not acknowledge, and sendtoWait() returns true immediately without waiting for any acknowledgements.

Parameters:

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

Returns:: true if the message was transmitted and an acknowledgement was received.

Definition at line 47 of file RHReliableDatagram.cpp.

void setHeaderFlags	(	uint8_t	set,
		uint8_t	clear = `RH_FLAGS_NONE`
	)		`[inherited]`

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

Definition at line 97 of file RHDatagram.cpp.

void setHeaderFrom ( uint8_t from ) [inherited]

Sets the FROM header to be sent in all subsequent messages.

Parameters:

[in] from The new FROM header value

Definition at line 87 of file RHDatagram.cpp.

void setHeaderId ( uint8_t id ) [inherited]

Sets the ID header to be sent in all subsequent messages.

Parameters:

[in] id The new ID header value

Definition at line 92 of file RHDatagram.cpp.

void setHeaderTo ( uint8_t to ) [inherited]

Sets the TO header to be sent in all subsequent messages.

Parameters:

[in] to The new TO header value

Definition at line 82 of file RHDatagram.cpp.

void setRetries ( uint8_t retries )

Sets the maximum number of retries.

Defaults to 3 at construction time. If set to 0, each message will only ever be sent once. sendtoWait will give up and return false if there is no ack received after all transmissions time out and the retries count is exhausted. param[in] retries The maximum number a retries.

Definition at line 35 of file RHReliableDatagram.cpp.

void setThisAddress ( uint8_t thisAddress ) [inherited]

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

Definition at line 25 of file RHDatagram.cpp.

void setTimeout ( uint16_t timeout )

Sets the minimum retransmit timeout.

If sendtoWait is waiting for an ack longer than this time (in milliseconds), it will retransmit the message. Defaults to 200ms. The timeout is measured from the end of transmission of the message. It must be at least longer than the the transmit time of the acknowledgement (preamble+6 octets) plus the latency/poll time of the receiver. For fast modulation schemes you can considerably shorten this time. The actual timeout is randomly varied between timeout and timeout*2.

Parameters:

[in] timeout The new timeout period in milliseconds

Definition at line 29 of file RHReliableDatagram.cpp.

uint8_t thisAddress ( ) [inherited]

Returns the address of this node.

Returns:: The address of this node

Definition at line 77 of file RHDatagram.cpp.

void waitAvailable ( ) [inherited]

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

Definition at line 57 of file RHDatagram.cpp.

bool waitAvailableTimeout ( uint16_t timeout ) [inherited]

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

Parameters:

[in] timeout Maximum time to wait in milliseconds.

Returns:: true if a message is available

Definition at line 72 of file RHDatagram.cpp.

bool waitPacketSent ( ) [inherited]

Blocks until the transmitter is no longer transmitting.

Definition at line 62 of file RHDatagram.cpp.

bool waitPacketSent ( uint16_t timeout ) [inherited]

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.

Definition at line 67 of file RHDatagram.cpp.

Field Documentation

RHGenericDriver& _driver [protected, inherited]

The Driver we are to use.

Definition at line 156 of file RHDatagram.h.

uint8_t _thisAddress [protected, inherited]

The address of this node.

Definition at line 159 of file RHDatagram.h.

Type:	Library
Created:	15 Oct 2015
Imports:	194
Forks:	1
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	10

Important changes to repositories hosted on mbed.com

RHReliableDatagram Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

RHReliableDatagram Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning