David Rimer / RadioHead-148

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Embed: (wiki syntax)

« Back to documentation index

RHDatagram Class Reference
Public Member Functions | Protected Attributes

RHDatagram Class Reference

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

#include <RHDatagram.h>

Inherited by RHReliableDatagram.

Public Member Functions

 RHDatagram (RHGenericDriver &driver, uint8_t thisAddress=0)
 Constructor.
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 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.

Definition at line 45 of file RHDatagram.h.

Constructor & Destructor Documentation

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

Definition at line 8 of file RHDatagram.cpp.

Member Function Documentation

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

Definition at line 52 of file RHDatagram.cpp.

uint8_t headerFlags (  )

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

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

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

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

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 
)

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

Definition at line 39 of file RHDatagram.cpp.

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.

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.

Definition at line 33 of file RHDatagram.cpp.

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.

Parameters:
[in]setbitmask of bits to be set
[in]clearbitmask of flags to clear

Definition at line 97 of file RHDatagram.cpp.

void setHeaderFrom ( uint8_t  from )

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

Parameters:
[in]fromThe new FROM header value

Definition at line 87 of file RHDatagram.cpp.

void setHeaderId ( uint8_t  id )

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

Parameters:
[in]idThe new ID header value

Definition at line 92 of file RHDatagram.cpp.

void setHeaderTo ( uint8_t  to )

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

Parameters:
[in]toThe new TO header value

Definition at line 82 of file RHDatagram.cpp.

void 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

Definition at line 25 of file RHDatagram.cpp.

uint8_t thisAddress (  )

Returns the address of this node.

Returns:
The address of this node

Definition at line 77 of file RHDatagram.cpp.

void waitAvailable (  )

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 )

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

Parameters:
[in]timeoutMaximum time to wait in milliseconds.
Returns:
true if a message is available

Definition at line 72 of file RHDatagram.cpp.

bool waitPacketSent (  )

Blocks until the transmitter is no longer transmitting.

Definition at line 62 of file RHDatagram.cpp.

bool 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.

Definition at line 67 of file RHDatagram.cpp.

Field Documentation

RHGenericDriver& _driver [protected]

The Driver we are to use.

Definition at line 156 of file RHDatagram.h.

uint8_t _thisAddress [protected]

The address of this node.

Definition at line 159 of file RHDatagram.h.

Generated on Tue Jul 12 2022 18:05:56 by  doxygen 1.7.2