RadioHead
Public Member Functions | Protected Attributes | List of all members
RHDatagram Class Reference

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

#include <RHDatagram.h>

Inheritance diagram for RHDatagram:
RHReliableDatagram RHRouter RHMesh

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]driverThe RadioHead driver to use to transport messages.
[in]thisAddressThe 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]bufLocation to copy the received message
[in,out]lenPointer to the number of octets available in buf. The number be reset to the actual number of octets copied.
[in]fromIf present and not NULL, the referenced uint8_t will be set to the FROM address
[in]toIf present and not NULL, the referenced uint8_t will be set to the TO address
[in]idIf present and not NULL, the referenced uint8_t will be set to the ID
[in]flagsIf 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]bufPointer to the binary message to send
[in]lenNumber of octets to send (> 0)
[in]addressThe 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]setbitmask of bits to be set
[in]clearbitmask 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]fromThe 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]idThe 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]toThe 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]thisAddressThe 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]polldelayTime 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]timeoutMaximum time to wait in milliseconds.
[in]polldelayTime 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]timeoutMaximum 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: