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

#include <RF22Router.h>

Inheritance diagram for RF22Router:

Classes
struct	RoutedMessage
	Defines the structure of a RF22Router message. More...

struct	RoutedMessageHeader

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 Types inherited from RF22
enum	ModemConfigChoice { UnmodulatedCarrier = 0, FSK_PN9_Rb2Fd5, FSK_Rb2Fd5, FSK_Rb2_4Fd36, FSK_Rb4_8Fd45, FSK_Rb9_6Fd45, FSK_Rb19_2Fd9_6, FSK_Rb38_4Fd19_6, FSK_Rb57_6Fd28_8, FSK_Rb125Fd125, FSK_Rb_512Fd2_5, FSK_Rb_512Fd4_5, GFSK_Rb2Fd5, GFSK_Rb2_4Fd36, GFSK_Rb4_8Fd45, GFSK_Rb9_6Fd45, GFSK_Rb19_2Fd9_6, GFSK_Rb38_4Fd19_6, GFSK_Rb57_6Fd28_8, GFSK_Rb125Fd125, OOK_Rb1_2Bw75, OOK_Rb2_4Bw335, OOK_Rb4_8Bw335, OOK_Rb9_6Bw335, OOK_Rb19_2Bw335, OOK_Rb38_4Bw335, OOK_Rb40Bw335 }

enum	CRCPolynomial { CRC_CCITT = 0, CRC_16_IBM = 1, CRC_IEC_16 = 2, CRC_Biacheva = 3 }
	Defines the available choices for CRC Types of permitted CRC polynomials, to be passed to setCRCPolynomial() They deliberately have the same numeric values as the crc[1:0] field of Register RF22_REG_30_DATA_ACCESS_CONTROL. More...

Public Member Functions
	RF22Router (uint8_t thisAddress=0, uint8_t slaveSelectPin=SS, uint8_t interrupt=0)

boolean	init ()

void	setMaxHops (uint8_t max_hops)

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

RoutingTableEntry *	getRouteTo (uint8_t dest)

boolean	deleteRouteTo (uint8_t dest)

void	retireOldestRoute ()

void	clearRoutingTable ()

void	printRoutingTable ()

uint8_t	sendtoWait (uint8_t *buf, uint8_t len, uint8_t dest)

uint8_t	sendtoWait (uint8_t *buf, uint8_t len, uint8_t dest, uint8_t source)

boolean	recvfromAck (uint8_t buf, uint8_t len, uint8_t source=NULL, uint8_t dest=NULL, uint8_t id=NULL, uint8_t flags=NULL)

boolean	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 RF22ReliableDatagram
	RF22ReliableDatagram (uint8_t thisAddress=0, uint8_t slaveSelectPin=SS, uint8_t interrupt=0)

void	setTimeout (uint16_t timeout)

void	setRetries (uint8_t retries)

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

boolean	recvfromAck (uint8_t buf, uint8_t len, uint8_t from=NULL, uint8_t to=NULL, uint8_t id=NULL, uint8_t flags=NULL)

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

uint16_t	retransmissions ()

Public Member Functions inherited from RF22Datagram
	RF22Datagram (uint8_t thisAddress=0, uint8_t slaveSelectPin=SS, uint8_t interrupt=0)

boolean	init ()

void	setThisAddress (uint8_t thisAddress)

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

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

Public Member Functions inherited from RF22
	RF22 (uint8_t slaveSelectPin=SS, uint8_t interrupt=0, GenericSPIClass *spi=&Hardware_spi)

boolean	init ()

void	reset ()

uint8_t	spiRead (uint8_t reg)

void	spiWrite (uint8_t reg, uint8_t val)

void	spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len)

void	spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len)

uint8_t	statusRead ()

uint8_t	adcRead (uint8_t adcsel=RF22_ADCSEL_INTERNAL_TEMPERATURE_SENSOR, uint8_t adcref=RF22_ADCREF_BANDGAP_VOLTAGE, uint8_t adcgain=0, uint8_t adcoffs=0)

uint8_t	temperatureRead (uint8_t tsrange=RF22_TSRANGE_M64_64C, uint8_t tvoffs=0)

uint16_t	wutRead ()

void	setWutPeriod (uint16_t wtm, uint8_t wtr=0, uint8_t wtd=0)

boolean	setFrequency (float centre, float afcPullInRange=0.05)

boolean	setFHStepSize (uint8_t fhs)

boolean	setFHChannel (uint8_t fhch)

uint8_t	rssiRead ()

uint8_t	ezmacStatusRead ()

void	setMode (uint8_t mode)

void	setModeIdle ()

void	setModeRx ()

void	setModeTx ()

uint8_t	mode ()

void	setTxPower (uint8_t power)

void	setModemRegisters (const ModemConfig *config)

boolean	setModemConfig (ModemConfigChoice index)

boolean	available ()

void	waitAvailable ()

bool	waitAvailableTimeout (uint16_t timeout)

boolean	recv (uint8_t buf, uint8_t len)

boolean	send (const uint8_t *data, uint8_t len)

void	waitPacketSent ()

bool	waitPacketSent (uint16_t timeout)

void	setPromiscuous (boolean promiscuous)

uint8_t	headerTo ()

uint8_t	headerFrom ()

uint8_t	headerId ()

uint8_t	headerFlags ()

uint8_t	lastRssi ()

void	setPreambleLength (uint8_t nibbles)

void	setSyncWords (const uint8_t *syncWords, uint8_t len)

boolean	setCRCPolynomial (CRCPolynomial polynomial)

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 RF22ReliableDatagram
void	acknowledge (uint8_t id, uint8_t from)

boolean	haveNewMessage ()

Protected Member Functions inherited from RF22
void	handleInterrupt ()

void	clearRxBuf ()

void	clearTxBuf ()

boolean	fillTxBuf (const uint8_t *data, uint8_t len)

boolean	appendTxBuf (const uint8_t *data, uint8_t len)

void	sendNextFragment ()

void	readNextFragment ()

void	resetFifos ()

void	resetRxFifo ()

void	resetTxFifo ()

virtual void	handleExternalInterrupt ()

virtual void	handleWakeupTimerInterrupt ()

void	setHeaderTo (uint8_t to)

void	setHeaderFrom (uint8_t from)

void	setHeaderId (uint8_t id)

void	setHeaderFlags (uint8_t flags)

void	startTransmit ()

void	restartTransmit ()

Protected Attributes
uint8_t	_lastE2ESequenceNumber

uint8_t	_max_hops

Protected Attributes inherited from RF22Datagram
uint8_t	_thisAddress
	The address of this node. Defaults to 0.

Protected Attributes inherited from RF22
GenericSPIClass *	_spi

volatile uint8_t	_mode

uint8_t	_idleMode

uint8_t	_slaveSelectPin

uint8_t	_interrupt

uint8_t	_deviceType

CRCPolynomial	_polynomial

volatile uint8_t	_bufLen

uint8_t	_buf [RF22_MAX_MESSAGE_LEN]

volatile boolean	_rxBufValid

volatile uint8_t	_txBufSentIndex

volatile uint16_t	_rxBad

volatile uint16_t	_rxGood

volatile uint16_t	_txGood

volatile uint8_t	_lastRssi

Additional Inherited Members
Static Public Member Functions inherited from RF22
static void	printBuffer (const char prompt, const uint8_t buf, uint8_t len)

Static Protected Member Functions inherited from RF22
static void	isr0 ()
	Low level interrupt service routine for RF22 connected to interrupt 0.

static void	isr1 ()
	Low level interrupt service routine for RF22 connected to interrupt 1.

static void	isr2 ()
	Low level interrupt service routine for RF22 connected to interrupt 1.

Static Protected Attributes inherited from RF22
static RF22 *	_RF22ForInterrupt [] = {0, 0, 0}
	Array of instances connected to interrupts 0 and 1.

Detailed Description

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

Extends RF22ReliableDatagram 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 RF22Router, 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, RF22Router looks up the next hop node for the destination node. It then uses RF22ReliableDatagram to (reliably) deliver the message to the next hop (which is expected also to be running an RF22Router). 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.

RF22Router supports messages with a dest of RF22_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 RF22_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.

RF22Router 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 RF22Mesh instead.

The Routing Table

The routing table is a local table in RF22Router 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 RF22Router 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 RF22_ROUTING_TABLE_SIZE, which is 10) if more than RF22_ROUTING_TABLE_SIZE are added, the oldest (first) one will be removed by calling retireOldestRoute()

Message Format

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

1 octet DEST, the destination node address (ie the address of the final destination node for this message)
1 octet SOURCE, the source node address (ie the address of the originating node that first sent the message).
1 octet HOPS, the number of hops this message has traversed so far.
1 octet ID, an incrementing message ID for end-to-end message tracking for use by subclasses. Not used by RF22Router.
1 octet FLAGS, a bitmask for use by subclasses. Not used by RF22Router.
0 or more octets DATA, the application payload data. The length of this data is implicit in the length of the entire message.

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 RF22Router level.

Testing

Bench testing of such networks is notoriously difficult, especially simulating limited radio connectivity between some nodes. To assist testing (both during RF22 development and for your own networks) RF22Router.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 RF22 messages from certain other nodes. You can enable testing with a #define TEST_NETWORK in RF22Router.h The sample programs rf22_mesh_* rely on this feature.

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

Examples:: rf22_router_client.pde, rf22_router_server1.pde, rf22_router_server2.pde, and rf22_router_server3.pde.

Member Enumeration Documentation

enum RF22Router::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

RF22Router::RF22Router	(	uint8_t	thisAddress = `0`,
		uint8_t	slaveSelectPin = `SS`,
		uint8_t	interrupt = `0`
	)

Constructor.

Parameters

[in]	thisAddress	The address to assign to this node. Defaults to 0
[in]	slaveSelectPin	the Arduino pin number of the output to use to select the RF22 before accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega)
[in]	interrupt	The interrupt number to use. Default is interrupt 0 (Arduino input pin 2)

References _max_hops, and clearRoutingTable().

Member Function Documentation

void RF22Router::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]	dest	The destination node address. RF22_BROADCAST_ADDRESS is permitted.
[in]	next_hop	The address of the next hop to send messages destined for dest
[in]	state	The satte of the route. Defaults to Valid

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

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

void RF22Router::clearRoutingTable ( )

Clears all entries from the local routing table

References Invalid.

Referenced by RF22Router().

void RF22Router::deleteRoute ( uint8_t index )

protected

Deletes a specific rout entry from therouting table

Parameters

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

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

Referenced by deleteRouteTo(), and retireOldestRoute().

boolean RF22Router::deleteRouteTo ( uint8_t dest )

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

Parameters

[in] dest The destination node address

Returns: true if the route was present

References deleteRoute().

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

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

Finds and returns a RoutingTableEntry for the given destination node

Parameters

[in] dest The desired destination node address.

Returns: pointer to a RoutingTableEntry for dest

References Invalid.

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

boolean RF22Router::init ( )

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

References _max_hops, and RF22Datagram::init().

void RF22Router::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 RF22ReliableDatagram

Parameters

[in]	message	Pointer to the RF22Router message that was received.
[in]	messageLen	Length of message in octets

Reimplemented in RF22Mesh.

Referenced by recvfromAck().

void RF22Router::printRoutingTable ( )

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

boolean RF22Router::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 RF22_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 RF22_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]	buf	Location to copy the received message
[in,out]	len	Available space in buf. Set to the actual number of octets copied.
[in]	source	If present and not NULL, the referenced uint8_t will be set to the SOURCE address
[in]	dest	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 recvived for this node copied to buf

References _max_hops, RF22Datagram::_thisAddress, RF22Router::RoutedMessage::data, RF22Router::RoutedMessageHeader::dest, RF22Router::RoutedMessageHeader::flags, RF22Router::RoutedMessage::header, RF22Router::RoutedMessageHeader::hops, RF22Router::RoutedMessageHeader::id, peekAtMessage(), RF22ReliableDatagram::recvfromAck(), route(), and RF22Router::RoutedMessageHeader::source.

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

boolean RF22Router::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]	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]	source	If present and not NULL, the referenced uint8_t will be set to the SOURCE address
[in]	dest	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

References recvfromAck().

void RF22Router::retireOldestRoute ( )

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

References deleteRoute().

Referenced by addRouteTo().

uint8_t RF22Router::route	(	RoutedMessage *	message,
		uint8_t	messageLen
	)

protectedvirtual

Finds the next-hop route and sends the message via RF22ReliableDatagram::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]	message	Pointer to the RF22Router message to be sent.
[in]	messageLen	Length of message in octets

Reimplemented in RF22Mesh.

References RF22Router::RoutedMessageHeader::dest, getRouteTo(), RF22Router::RoutedMessage::header, RF22Router::RoutingTableEntry::next_hop, and RF22ReliableDatagram::sendtoWait().

Referenced by recvfromAck(), RF22Mesh::route(), and sendtoWait().

uint8_t RF22Router::sendtoWait	(	uint8_t *	buf,
		uint8_t	len,
		uint8_t	dest
	)

Sends a message to the destination node. Initialises the RF22Router 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]	buf	The application message data
[in]	len	Number of octets in the application message data. 0 is permitted
[in]	dest	The destination node address

Returns

The result code:

RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop (not necessarily to the final dest address)
RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
RF22_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 RF22Datagram::_thisAddress.

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

uint8_t RF22Router::sendtoWait	(	uint8_t *	buf,
		uint8_t	len,
		uint8_t	dest,
		uint8_t	source
	)

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

Parameters

[in]	buf	The application message data
[in]	len	Number of octets in the application message data. 0 is permitted
[in]	dest	The destination node address
[in]	source	The (fake) originatong node address.

Returns

The result code:

RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop (not necessarily to the final dest address)
RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
RF22_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 _lastE2ESequenceNumber, RF22Router::RoutedMessage::data, RF22Router::RoutedMessageHeader::dest, RF22Router::RoutedMessageHeader::flags, RF22Router::RoutedMessage::header, RF22Router::RoutedMessageHeader::hops, RF22Router::RoutedMessageHeader::id, route(), and RF22Router::RoutedMessageHeader::source.

void RF22Router::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_hops The new value for max_hops

References _max_hops.

Member Data Documentation

uint8_t RF22Router::_lastE2ESequenceNumber

protected

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

Referenced by sendtoWait().

uint8_t RF22Router::_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(), RF22Mesh::recvfromAck(), recvfromAck(), RF22Router(), and setMaxHops().

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

RF22Router.h
RF22Router.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation