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

#include <RF22Mesh.h>

Inheritance diagram for RF22Mesh:

Classes
struct	MeshApplicationMessage
	Signals an application layer message for the caller of RF22Mesh. More...

struct	MeshMessageHeader
	Structure of the basic RF22Mesh header. More...

struct	MeshRouteDiscoveryMessage

struct	MeshRouteFailureMessage
	Signals a route failure. More...

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

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

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

virtual boolean	doArp (uint8_t address)

virtual boolean	isPhysicalAddress (uint8_t *address, uint8_t addresslen)

Protected Member Functions inherited from RF22Router
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 ()

Additional Inherited Members
Public Types inherited from RF22Router
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...

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.

Protected Attributes inherited from RF22Router
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

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, with automatic route discovery.

Extends RF22Router to add automatic route discovery within a mesh of adjacent nodes, and route signalling.

Unlike RF22Router, RF22Mesh can be used in networks where the network topology is fluid, or unknown, or if nodes can mode around or go in or out of service. When a node wants to send a message to another node, it will automcatically discover a route to the destaintion node and use it. If the route becomes unavailable, a new route will be discovered.

Route Discovery

When a RF22Mesh mesh node is initialised, it doe not know any routes to any other nodes (see RF22Router for details on route and the routing table). When you attempt to send a message with sendtoWait, will first check to see if there is a route to the destinastion node in the routing tabl;e. If not, it wil initialite 'Route Discovery'. When a node needs to discover a route to another node, it broadcasts MeshRouteDiscoveryMessage with a message type of RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST. Any node that receives such a request checks to see if it is a request for a route to itself (in which case it makes a unicast reply to the originating node with a MeshRouteDiscoveryMessage with a message type of RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_RESPONSE) otherwise it rebroadcasts the request, after adding itself to the list of nodes visited so far by the request.

If a node receives a RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST that already has itself listed in the visited nodes, it knows it has already seen and rebroadcast this request, and threfore ignores it. This prevents broadcast storms. When a node receives a RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST it can use the list of nodes aready visited to deduce routes back towards the originating (requesting node). This also means that when the destination node of the request is reached, it (and all the previous nodes the request visited) will have a route back to the originating node. This means the unicast RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_RESPONSE reply will be routed successfully back to the original route requester.

The RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_RESPONSE sent back by the destination node contains the full list of nodes that were visited on the way to the destination. Therefore, intermediate nodes that route the reply back towards the originating node can use the node list in the reply to deduce routes to all the nodes between it and the destination node.

Therefore, RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST and RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_RESPONSE together ensure the original requester and all the intermediate nodes know how to route to the source and destination nodes and every node along the path.

Note that there is a race condition here that can effect routing on multipath routes. For example, if the route to the destination can traverse several paths, last reply from the destination will be the one used.

Route Failure

RF22Router (and therefore RF22Mesh) use reliable hop-to-hop delivery of messages using hop-to-hop acknowledgements, but not end-to-end acknowledgements. When sendtoWait() returns, you know that the message has been delivered to the next hop, but not if it is (or even if it can be) delivered to the destination node. If during the course of hop-to-hop routing of a message, one of the intermediate RF22Mesh nodes finds it cannot deliver to the next hop (say due to a lost route or no acknwledgement from the next hop), it replies to the originator with a unicast MeshRouteFailureMessage RF22_MESH_MESSAGE_TYPE_ROUTE_FAILURE message. Intermediate nodes (on the way beack to the originator) and the originating node use this message to delete the route to the destination node of the original message. This means that if a route to a destination becomes unusable (either because an intermediate node is off the air, or has moved out of range) a new route will be established the next time a message is to be sent.

Message Format

RF22Mesh uses a number of message formats layered on top of RF22Router:

MeshApplicationMessage (message type RF22_MESH_MESSAGE_TYPE_APPLICATION). Carries an application layer message for the caller of RF22Mesh
MeshRouteDiscoveryMessage (message types RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST and RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_RESPONSE). Carries Route Discovery messages (broadcast) and replies (unicast).
MeshRouteFailureMessage (message type RF22_MESH_MESSAGE_TYPE_ROUTE_FAILURE) Informs nodes of route failures.

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

Examples:: rf22_mesh_client.pde, rf22_mesh_server1.pde, rf22_mesh_server2.pde, and rf22_mesh_server3.pde.

Constructor & Destructor Documentation

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

Member Function Documentation

boolean RF22Mesh::doArp ( uint8_t address )

protectedvirtual

Try to resolve a route for the given address. Blocks while discovering the route which may take up to 4000 msec. Virtual so subclasses can override.

Parameters

[in] address The physical addres to resolve

Returns: true if the address was resolved and added to the local routing table

References RF22Router::addRouteTo(), RF22Mesh::MeshRouteDiscoveryMessage::dest, RF22Mesh::MeshRouteDiscoveryMessage::destlen, RF22Mesh::MeshRouteDiscoveryMessage::header, RF22::headerFrom(), RF22Mesh::MeshMessageHeader::msgType, RF22Router::recvfromAck(), and RF22Router::sendtoWait().

Referenced by sendtoWait().

boolean RF22Mesh::isPhysicalAddress	(	uint8_t *	address,
		uint8_t	addresslen
	)

protectedvirtual

Tests if the given address of length addresslen is indentical to the physical addres of this node. RF22Mesh always ikmplements p[hysical addresses as the 1 octet address of the node given by _thisAddress Called by recvfromAck() to test whether a RF22_MESH_MESSAGE_TYPE_ROUTE_DISCOVERY_REQUEST is for this node. Subclasses may want to override to implemnt mode complicated or longer physical addresses

Parameters

[in]	address	Address of the pyysical addres being tested
[in]	addresslen	Lengthof the address in bytes

Returns: true if the physical address of this node is identical to address

References RF22Datagram::_thisAddress.

Referenced by recvfromAck().

void RF22Mesh::peekAtMessage	(	RoutedMessage *	message,
		uint8_t	messageLen
	)

protectedvirtual

Internal function that inspects messages being received and adjusts the routing table if necessary. 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 from RF22Router.

References RF22Datagram::_thisAddress, RF22Router::addRouteTo(), RF22Router::RoutedMessage::data, RF22Router::deleteRouteTo(), RF22Mesh::MeshRouteDiscoveryMessage::dest, RF22Mesh::MeshRouteFailureMessage::dest, RF22::headerFrom(), RF22Mesh::MeshMessageHeader::msgType, and RF22Mesh::MeshRouteDiscoveryMessage::route.

boolean RF22Mesh::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 application layer 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 and copied to buf

References RF22Router::_max_hops, RF22Datagram::_thisAddress, RF22Router::addRouteTo(), RF22Mesh::MeshApplicationMessage::data, RF22Mesh::MeshRouteDiscoveryMessage::dest, RF22Mesh::MeshRouteDiscoveryMessage::destlen, RF22Mesh::MeshRouteDiscoveryMessage::header, RF22::headerFrom(), isPhysicalAddress(), RF22Mesh::MeshMessageHeader::msgType, RF22Router::recvfromAck(), RF22Mesh::MeshRouteDiscoveryMessage::route, and RF22Router::sendtoWait().

Referenced by recvfromAckTimeout().

boolean RF22Mesh::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 application layer 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().

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

protectedvirtual

Internal function that inspects messages being received and adjusts the routing table if necessary. 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 from RF22Router.

References RF22Datagram::_thisAddress, RF22Router::addRouteTo(), RF22Router::deleteRouteTo(), RF22Mesh::MeshRouteFailureMessage::dest, RF22Router::RoutedMessageHeader::dest, RF22Mesh::MeshRouteFailureMessage::header, RF22Router::RoutedMessage::header, RF22::headerFrom(), RF22Mesh::MeshMessageHeader::msgType, RF22Router::route(), RF22Router::sendtoWait(), and RF22Router::RoutedMessageHeader::source.

Referenced by sendtoWait().

uint8_t RF22Mesh::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. If no route is known, initiates route discovery and waits for a reply. Then sends the message to the next hop Then 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 RF22Mesh::MeshApplicationMessage::data, doArp(), RF22Router::getRouteTo(), RF22Mesh::MeshApplicationMessage::header, RF22Mesh::MeshMessageHeader::msgType, route(), and RF22Router::sendtoWait().

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

RF22Mesh.h
RF22Mesh.cpp

Classes

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation