RadioHead
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
RHRouter Class Reference

RHReliableDatagram subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a network. More...

#include <RHRouter.h>

Inheritance diagram for RHRouter:
RHReliableDatagram RHDatagram RHMesh

Classes

struct  RoutedMessage
 Defines the structure of a RHRouter message. More...
 
struct  RoutedMessageHeader
 Defines the structure of the RHRouter message header, used to keep track of end-to-end delivery parameters. More...
 
struct  RoutingTableEntry
 Defines an entry in the routing table. More...
 

Public Types

enum  RouteState { Invalid = 0, Discovering, Valid }
 Values for the possible states for routes. More...
 

Public Member Functions

 RHRouter (RHGenericDriver &driver, uint8_t thisAddress=0)
 
bool init ()
 
void setMaxHops (uint8_t max_hops)
 
void addRouteTo (uint8_t dest, uint8_t next_hop, uint8_t state=Valid)
 
RoutingTableEntrygetRouteTo (uint8_t dest)
 
bool deleteRouteTo (uint8_t dest)
 
void retireOldestRoute ()
 
void clearRoutingTable ()
 
void printRoutingTable ()
 
uint8_t sendtoWait (uint8_t *buf, uint8_t len, uint8_t dest, uint8_t flags=0)
 
uint8_t sendtoFromSourceWait (uint8_t *buf, uint8_t len, uint8_t dest, uint8_t source, uint8_t flags=0)
 
bool recvfromAck (uint8_t *buf, uint8_t *len, uint8_t *source=NULL, uint8_t *dest=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
 
bool recvfromAckTimeout (uint8_t *buf, uint8_t *len, uint16_t timeout, uint8_t *source=NULL, uint8_t *dest=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
 
- Public Member Functions inherited from RHReliableDatagram
 RHReliableDatagram (RHGenericDriver &driver, uint8_t thisAddress=0)
 
void setTimeout (uint16_t timeout)
 
void setRetries (uint8_t retries)
 
uint8_t retries ()
 
bool sendtoWait (uint8_t *buf, uint8_t len, uint8_t address)
 
bool recvfromAck (uint8_t *buf, uint8_t *len, uint8_t *from=NULL, uint8_t *to=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
 
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)
 
uint32_t retransmissions ()
 
void resetRetransmissions ()
 
- Public Member Functions inherited from RHDatagram
 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 ()
 
bool waitPacketSent ()
 
bool waitPacketSent (uint16_t timeout)
 
bool waitAvailableTimeout (uint16_t timeout)
 
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 Member Functions

virtual void peekAtMessage (RoutedMessage *message, uint8_t messageLen)
 
virtual uint8_t route (RoutedMessage *message, uint8_t messageLen)
 
void deleteRoute (uint8_t index)
 
- Protected Member Functions inherited from RHReliableDatagram
void acknowledge (uint8_t id, uint8_t from)
 
bool haveNewMessage ()
 

Protected Attributes

uint8_t _lastE2ESequenceNumber
 
uint8_t _max_hops
 
- Protected Attributes inherited from RHDatagram
RHGenericDriver_driver
 The Driver we are to use.
 
uint8_t _thisAddress
 The address of this node.
 

Detailed Description

RHReliableDatagram subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a network.

Manager class that extends RHReliableDatagram to define addressed messages That are reliably transmitted and routed across a network. Each message is transmitted reliably between each hop in order to get from the source node to the destination node.

With RHRouter, routes are hard wired. This means that each node must have programmed in it how to reach each of the other nodes it will be trying to communicate with. This means you must specify the next-hop node address for each of the destination nodes, using the addRouteTo() function.

When sendtoWait() is called with a new message to deliver, and the destination address, RHRouter looks up the next hop node for the destination node. It then uses RHReliableDatagram to (reliably) deliver the message to the next hop (which is expected also to be running an RHRouter). If that next-hop node is not the final destination, it will also look up the next hop for the destination node and (reliably) deliver the message to the next hop. By this method, messages can be delivered across a network of nodes, even if each node cannot hear all of the others in the network. Each time a message is received for another node and retransmitted to the next hop, the HOPS filed in teh header is incremented. If a message is received for routing to another node which has exceed the routers max_hops, the message wioll be dropped and ignored. This helps prevent infinite routing loops.

RHRouter supports messages with a dest of RH_BROADCAST_ADDRESS. Such messages are not routed, and are broadcast (once) to all nodes within range.

The recvfromAck() function is responsible not just for receiving and delivering messages addressed to this node (or RH_BROADCAST_ADDRESS), but it is also responsible for routing other message to their next hop. This means that it is important to call recvfromAck() or recvfromAckTimeout() frequently in your main loop. recvfromAck() will return false if it receives a message but it is not for this node.

RHRouter does not provide reliable end-to-end delivery, but uses reliable hop-to-hop delivery. If a message is unable to be delivered to an end node during to a delivery failure between 2 hops, the source node will not be told about it.

Note: This class is most useful for networks of nodes that are essentially static (i.e. the nodes dont move around), and for which the routing never changes. If that is not the case for your proposed network, see RHMesh instead.

The Routing Table

The routing table is a local table in RHRouter that holds the information about the next hop node address for each destination address you may want to send a message to. It is your responsibility to make sure every node in an RHRouter network has been configured with a unique address and the routing information so that messages are correctly routed across the network from source node to destination node. This is usually done once in setup() by calling addRouteTo(). The hardwired routing will in general be different on each node, and will depend on the physical topololgy of the network. You can also use addRouteTo() to change a route and deleteRouteTo() to delete a route at run time. Youcan also clear the entire routing table

The Routing Table has limited capacity for entries (defined by RH_ROUTING_TABLE_SIZE, which is 10) if more than RH_ROUTING_TABLE_SIZE are added, the oldest (first) one will be removed by calling retireOldestRoute()

Message Format

RHRouter add to the lower level RHReliableDatagram (and even lower level RH) class message formats. In those lower level classes, the hop-to-hop message headers are in the RH message headers, and are handled automcatically by tyhe RH hardware. RHRouter and its subclasses add an end-to-end addressing header in the payload of the RH message, and before the RHRouter application data.

You should be careful to note that there are ID and FLAGS fields in the low level per-hop message header too. These are used only for hop-to-hop, and in general will be different to the ones at the RHRouter level.

Testing

Bench testing of such networks is notoriously difficult, especially simulating limited radio connectivity between some nodes. To assist testing (both during RH development and for your own networks) RHRouter.cpp has the ability to simulate a number of different small network topologies. Each simulated network supports 4 nodes with addresses 1 to 4. It operates by pretending to not hear RH messages from certain other nodes. You can enable testing with a #define TEST_NETWORK in RHRouter.h The sample programs rf22_mesh_* rely on this feature.

Part of the Arduino RH library for operating with HopeRF RH compatible transceivers (see http://www.hoperf.com)

Member Enumeration Documentation

◆ RouteState

Values for the possible states for routes.

Enumerator
Invalid 

No valid route is known.

Discovering 

Discovering a route (not currently used)

Valid 

Route is valid.

Constructor & Destructor Documentation

◆ RHRouter()

RHRouter::RHRouter ( 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

References _max_hops, and clearRoutingTable().

Member Function Documentation

◆ addRouteTo()

void RHRouter::addRouteTo ( uint8_t  dest,
uint8_t  next_hop,
uint8_t  state = Valid 
)

Adds a route to the local routing table, or updates it if already present. If there is not enough room the oldest (first) route will be deleted by calling retireOldestRoute().

Parameters
[in]destThe destination node address. RH_BROADCAST_ADDRESS is permitted.
[in]next_hopThe address of the next hop to send messages destined for dest
[in]stateThe satte of the route. Defaults to Valid

References RHRouter::RoutingTableEntry::dest, Invalid, RHRouter::RoutingTableEntry::next_hop, retireOldestRoute(), and RHRouter::RoutingTableEntry::state.

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

◆ clearRoutingTable()

void RHRouter::clearRoutingTable ( )

Clears all entries from the local routing table

References Invalid.

Referenced by RHRouter().

◆ deleteRoute()

void RHRouter::deleteRoute ( uint8_t  index)
protected

Deletes a specific rout entry from therouting table

Parameters
[in]indexThe 0 based index of the routing table entry to delete

References Invalid, and RHRouter::RoutingTableEntry::state.

Referenced by deleteRouteTo(), and retireOldestRoute().

◆ deleteRouteTo()

bool RHRouter::deleteRouteTo ( uint8_t  dest)

Deletes from the local routing table any route for the destination node.

Parameters
[in]destThe destination node address
Returns
true if the route was present

References deleteRoute().

Referenced by RHMesh::peekAtMessage(), and RHMesh::route().

◆ getRouteTo()

RHRouter::RoutingTableEntry * RHRouter::getRouteTo ( uint8_t  dest)

Finds and returns a RoutingTableEntry for the given destination node

Parameters
[in]destThe desired destination node address.
Returns
pointer to a RoutingTableEntry for dest

References Invalid.

Referenced by route(), and RHMesh::sendtoWait().

◆ init()

bool RHRouter::init ( )

Initialises this instance and the radio module connected to it. Overrides the init() function in RH. Sets max_hops to the default of RH_DEFAULT_MAX_HOPS (30)

References _max_hops, and RHDatagram::init().

◆ peekAtMessage()

void RHRouter::peekAtMessage ( RoutedMessage message,
uint8_t  messageLen 
)
protectedvirtual

Lets sublasses peek at messages going past before routing or local delivery. Called by recvfromAck() immediately after it gets the message from RHReliableDatagram

Parameters
[in]messagePointer to the RHRouter message that was received.
[in]messageLenLength of message in octets

Reimplemented in RHMesh.

Referenced by recvfromAck().

◆ printRoutingTable()

void RHRouter::printRoutingTable ( )

If RH_HAVE_SERIAL is defined, this will print out the contents of the local routing table using Serial

◆ recvfromAck()

bool RHRouter::recvfromAck ( uint8_t *  buf,
uint8_t *  len,
uint8_t *  source = NULL,
uint8_t *  dest = NULL,
uint8_t *  id = NULL,
uint8_t *  flags = NULL 
)

Starts the receiver if it is not running already. If there is a valid message available for this node (or RH_BROADCAST_ADDRESS), send an acknowledgement to the last hop address (blocking until this is complete), then copy the application message payload data 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 originator SOURCE address is placed in *source. If to is not NULL, the DEST address is placed in *dest. This might be this nodes address or RH_BROADCAST_ADDRESS. 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.

Parameters
[in]bufLocation to copy the received message
[in,out]lenAvailable space in buf. Set to the actual number of octets copied.
[in]sourceIf present and not NULL, the referenced uint8_t will be set to the SOURCE address
[in]destIf present and not NULL, the referenced uint8_t will be set to the DEST 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 recvived for this node copied to buf

References _max_hops, RHDatagram::_thisAddress, peekAtMessage(), RHReliableDatagram::recvfromAck(), and route().

Referenced by RHMesh::doArp(), RHMesh::recvfromAck(), and recvfromAckTimeout().

◆ recvfromAckTimeout()

bool RHRouter::recvfromAckTimeout ( uint8_t *  buf,
uint8_t *  len,
uint16_t  timeout,
uint8_t *  source = NULL,
uint8_t *  dest = NULL,
uint8_t *  id = NULL,
uint8_t *  flags = NULL 
)

Starts the receiver if it is not running already. Similar to recvfromAck(), this will block until either a valid message available for this node or the timeout expires.

Parameters
[in]bufLocation to copy the received message
[in,out]lenAvailable space in buf. Set to the actual number of octets copied.
[in]timeoutMaximum time to wait in milliseconds
[in]sourceIf present and not NULL, the referenced uint8_t will be set to the SOURCE address
[in]destIf present and not NULL, the referenced uint8_t will be set to the DEST 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 recvfromAck(), and RHDatagram::waitAvailableTimeout().

◆ retireOldestRoute()

void RHRouter::retireOldestRoute ( )

Deletes the oldest (first) route from the local routing table

References deleteRoute().

Referenced by addRouteTo().

◆ route()

uint8_t RHRouter::route ( RoutedMessage message,
uint8_t  messageLen 
)
protectedvirtual

Finds the next-hop route and sends the message via RHReliableDatagram::sendtoWait(). This is virtual, which lets subclasses override or intercept the route() function. Called by sendtoWait after the message header has been filled in.

Parameters
[in]messagePointer to the RHRouter message to be sent.
[in]messageLenLength of message in octets

Reimplemented in RHMesh.

References RHRouter::RoutedMessageHeader::dest, getRouteTo(), RHRouter::RoutedMessage::header, RHRouter::RoutingTableEntry::next_hop, and RHReliableDatagram::sendtoWait().

Referenced by recvfromAck(), RHMesh::route(), and sendtoFromSourceWait().

◆ sendtoFromSourceWait()

uint8_t RHRouter::sendtoFromSourceWait ( uint8_t *  buf,
uint8_t  len,
uint8_t  dest,
uint8_t  source,
uint8_t  flags = 0 
)

Similar to sendtoWait() above, but spoofs the source address. For internal use only during routing

Parameters
[in]bufThe application message data.
[in]lenNumber of octets in the application message data. 0 is permitted.
[in]destThe destination node address.
[in]sourceThe (fake) originating node address.
[in]flagsOptional flags for use by subclasses or application layer, delivered end-to-end to the dest address. The receiver can recover the flags with recvFromAck().
Returns
The result code:
  • RH_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop (not necessarily to the final dest address)
  • RH_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
  • RH_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop (usually because it dod not acknowledge due to being off the air or out of range

References RHDatagram::_driver, _lastE2ESequenceNumber, RHRouter::RoutedMessage::data, RHRouter::RoutedMessageHeader::dest, RHRouter::RoutedMessageHeader::flags, RHRouter::RoutedMessage::header, RHRouter::RoutedMessageHeader::hops, RHRouter::RoutedMessageHeader::id, RHGenericDriver::maxMessageLength(), route(), and RHRouter::RoutedMessageHeader::source.

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

◆ sendtoWait()

uint8_t RHRouter::sendtoWait ( uint8_t *  buf,
uint8_t  len,
uint8_t  dest,
uint8_t  flags = 0 
)

Sends a message to the destination node. Initialises the RHRouter message header (the SOURCE address is set to the address of this node, HOPS to 0) and calls route() which looks up in the routing table the next hop to deliver to and sends the message to the next hop. Waits for an acknowledgement from the next hop (but not from the destination node (if that is different).

Parameters
[in]bufThe application message data
[in]lenNumber of octets in the application message data. 0 is permitted
[in]destThe destination node address
[in]flagsOptional flags for use by subclasses or application layer, delivered end-to-end to the dest address. The receiver can recover the flags with recvFromAck().
Returns
The result code:
  • RH_ROUTER_ERROR_NONE Message was routed and delivered to the next hop (not necessarily to the final dest address)
  • RH_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
  • RH_ROUTER_ERROR_UNABLE_TO_DELIVER Not able to deliver to the next hop (usually because it dod not acknowledge due to being off the air or out of range

References RHDatagram::_thisAddress, and sendtoFromSourceWait().

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

◆ setMaxHops()

void RHRouter::setMaxHops ( uint8_t  max_hops)

Sets the max_hops to the given value This controls the maximum number of hops allowed between source and destination nodes Messages that are not delivered by the time their HOPS field exceeds max_hops on a routing node will be dropped and ignored.

Parameters
[in]max_hopsThe new value for max_hops

References _max_hops.

Member Data Documentation

◆ _lastE2ESequenceNumber

uint8_t RHRouter::_lastE2ESequenceNumber
protected

The last end-to-end sequence number to be used Defaults to 0

Referenced by sendtoFromSourceWait().

◆ _max_hops

uint8_t RHRouter::_max_hops
protected

The maximum number of hops permitted in routed messages. If a routed message would exceed this number of hops it is dropped and ignored.

Referenced by init(), RHMesh::recvfromAck(), recvfromAck(), RHRouter(), and setMaxHops().


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