RF22

- Main Page
- Classes
- Files
- Examples

- File List

RF22Router.h
1 // RF22Router.h
2 //
3 // Author: Mike McCauley (mikem@airspayce.com)
4 // Copyright (C) 2011 Mike McCauley
5 // $Id: RF22Router.h,v 1.9 2014/04/01 05:06:44 mikem Exp mikem $
6
7 #ifndef RF22Router_h
8 #define RF22Router_h
9
10 #include <RF22ReliableDatagram.h>
11
12 // Default max number of hops we will route
13 #define RF22_DEFAULT_MAX_HOPS 30
14
15 // The default size of the routing table we keep
16 #define RF22_ROUTING_TABLE_SIZE 10
17
18 // Error codes
19 #define RF22_ROUTER_ERROR_NONE 0
20 #define RF22_ROUTER_ERROR_INVALID_LENGTH 1
21 #define RF22_ROUTER_ERROR_NO_ROUTE 2
22 #define RF22_ROUTER_ERROR_TIMEOUT 3
23 #define RF22_ROUTER_ERROR_NO_REPLY 4
24 #define RF22_ROUTER_ERROR_UNABLE_TO_DELIVER 5
25
26 // This size of RF22_ROUTER_MAX_MESSAGE_LEN is OK for Arduino Mega, but too big for
27 // Duemilanova. Size of 50 works with the sample router programs on Duemilanova.
28 #define RF22_ROUTER_MAX_MESSAGE_LEN (RF22_MAX_MESSAGE_LEN - sizeof(RF22Router::RoutedMessageHeader))
29 //#define RF22_ROUTER_MAX_MESSAGE_LEN 50
30
31 // These allow us to define a simulated network topology for testing purposes
32 // See RF22Router.cpp for details
33 //#define RF22_TEST_NETWORK 1
34 //#define RF22_TEST_NETWORK 2
35 //#define RF22_TEST_NETWORK 3
36 //#define RF22_TEST_NETWORK 4
37
38 /////////////////////////////////////////////////////////////////////
39 /// \class RF22Router RF22Router.h <RF22Router.h>
40 /// \brief RF22 subclass for sending addressed, optionally acknowledged datagrams
41 /// multi-hop routed across a network.
42 ///
43 /// Extends RF22ReliableDatagram to define addressed messages
44 /// That are reliably transmitted and routed across a network. Each message is transmitted reliably
45 /// between each hop in order to get from the source node to the destination node.
46 ///
47 /// With RF22Router, routes are hard wired. This means that each node must have programmed
48 /// in it how to reach each of the other nodes it will be trying to communicate with.
49 /// This means you must specify the next-hop node address for each of the destination nodes,
50 /// using the addRouteTo() function.
51 ///
52 /// When sendtoWait() is called with a new message to deliver, and the destination address,
53 /// RF22Router looks up the next hop node for the destination node. It then uses
54 /// RF22ReliableDatagram to (reliably) deliver the message to the next hop
55 /// (which is expected also to be running an RF22Router). If that next-hop node is not
56 /// the final destination, it will also look up the next hop for the destination node and
57 /// (reliably) deliver the message to the next hop. By this method, messages can be delivered
58 /// across a network of nodes, even if each node cannot hear all of the others in the network.
59 /// Each time a message is received for another node and retransmitted to the next hop,
60 /// the HOPS filed in teh header is incremented. If a message is received for routing to another node
61 /// which has exceed the routers max_hops, the message wioll be dropped and ignored.
62 /// This helps prevent infinite routing loops.
63 ///
64 /// RF22Router supports messages with a dest of RF22_BROADCAST_ADDRESS. Such messages are not routed,
65 /// and are broadcast (once) to all nodes within range.
66 ///
67 /// The recvfromAck() function is responsible not just for receiving and delivering
68 /// messages addressed to this node (or RF22_BROADCAST_ADDRESS), but
69 /// it is also responsible for routing other message to their next hop. This means that it is important to
70 /// call recvfromAck() or recvfromAckTimeout() frequently in your main loop. recvfromAck() will return
71 /// false if it receives a message but it is not for this node.
72 ///
73 /// RF22Router does not provide reliable end-to-end delivery, but uses reliable hop-to-hop delivery.
74 /// If a message is unable to be delivered to an end node during to a delivery failure between 2 hops,
75 /// the source node will not be told about it.
76 ///
77 /// Note: This class is most useful for networks of nodes that are essentially static
78 /// (i.e. the nodes dont move around), and for which the
79 /// routing never changes. If that is not the case for your proposed network, see RF22Mesh instead.
80 ///
81 /// \par The Routing Table
82 ///
83 /// The routing table is a local table in RF22Router that holds the information about the next hop node
84 /// address for each destination address you may want to send a message to. It is your responsibility
85 /// to make sure every node in an RF22Router network has been configured with a unique address and the
86 /// routing information so that messages are correctly routed across the network from source node to
87 /// destination node. This is usually done once in setup() by calling addRouteTo().
88 /// The hardwired routing will in general be different on each node, and will depend on the physical
89 /// topololgy of the network.
90 /// You can also use addRouteTo() to change a route and
91 /// deleteRouteTo() to delete a route at run time. Youcan also clear the entire routing table
92 ///
93 /// The Routing Table has limited capacity for entries (defined by RF22_ROUTING_TABLE_SIZE, which is 10)
94 /// if more than RF22_ROUTING_TABLE_SIZE are added, the oldest (first) one will be removed by calling
95 /// retireOldestRoute()
96 ///
97 /// \par Message Format
98 ///
99 /// RF22Router add to the lower level RF22ReliableDatagram (and even lower level RF22) class mesage formats.
100 /// In those lower level classes, the hop-to-hop message headers are in the RF22 message headers,
101 /// and are handled automcatically by tyhe RF22 hardware.
102 /// RF22Router and its subclasses add an end-to-end addressing header in the payload of the RF22 message,
103 /// and before the RF22Router application data.
104 /// - 1 octet DEST, the destination node address (ie the address of the final
105 /// destination node for this message)
106 /// - 1 octet SOURCE, the source node address (ie the address of the originating node that first sent
107 /// the message).
108 /// - 1 octet HOPS, the number of hops this message has traversed so far.
109 /// - 1 octet ID, an incrementing message ID for end-to-end message tracking for use by subclasses.
110 /// Not used by RF22Router.
111 /// - 1 octet FLAGS, a bitmask for use by subclasses. Not used by RF22Router.
112 /// - 0 or more octets DATA, the application payload data. The length of this data is implicit
113 /// in the length of the entire message.
114 ///
115 /// You should be careful to note that there are ID and FLAGS fields in the low level per-hop
116 /// message header too. These are used only for hop-to-hop, and in general will be different to
117 /// the ones at the RF22Router level.
118 ///
119 /// \par Testing
120 ///
121 /// Bench testing of such networks is notoriously difficult, especially simulating limited radio
122 /// connectivity between some nodes.
123 /// To assist testing (both during RF22 development and for your own networks)
124 /// RF22Router.cpp has the ability to
125 /// simulate a number of different small network topologies. Each simulated network supports 4 nodes with
126 /// addresses 1 to 4. It operates by pretending to not hear RF22 messages from certain other nodes.
127 /// You can enable testing with a \#define TEST_NETWORK in RF22Router.h
128 /// The sample programs rf22_mesh_* rely on this feature.
129 ///
130 /// Part of the Arduino RF22 library for operating with HopeRF RF22 compatible transceivers
131 /// (see http://www.hoperf.com)
132 class RF22Router : public RF22ReliableDatagram
133 {
134 public:
135
136 /// Defines the structure of the RF22Router message header, used to keep track of end-to-end delivery
137 /// parameters
138 typedef struct
139 {
140 uint8_t dest; ///< Destination node address
141 uint8_t source; ///< Originator node address
142 uint8_t hops; ///< Hops traversed so far
143 uint8_t id; ///< Originator sequence number
144 uint8_t flags; ///< Originator flags
145 // Data follows, Length is implicit in the overall message length
146 } RoutedMessageHeader;
147
148 /// Defines the structure of a RF22Router message
149 typedef struct
150 {
151 RoutedMessageHeader header; ///< end-to-end delivery header
152 uint8_t data[RF22_ROUTER_MAX_MESSAGE_LEN]; ///< Application payload data
153 } RoutedMessage;
154
155 /// Values for the possible states for routes
156 typedef enum
157 {
158 Invalid = 0, ///< No valid route is known
159 Discovering, ///< Discovering a route (not currently used)
160 Valid ///< Route is valid
161 } RouteState;
162
163 /// Defines an entry in the routing table
164 typedef struct
165 {
166 uint8_t dest; ///< Destination node address
167 uint8_t next_hop; ///< Send via this next hop address
168 uint8_t state; ///< State of this route, one of RouteState
169 } RoutingTableEntry;
170
171 /// Constructor.
172 /// \param[in] thisAddress The address to assign to this node. Defaults to 0
173 /// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the RF22 before
174 /// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega)
175 /// \param[in] interrupt The interrupt number to use. Default is interrupt 0 (Arduino input pin 2)
176 RF22Router(uint8_t thisAddress = 0, uint8_t slaveSelectPin = SS, uint8_t interrupt = 0);
177
178 /// Initialises this instance and the radio module connected to it.
179 /// Overrides the init() function in RF22.
180 /// Sets max_hops to the default of RF22_DEFAULT_MAX_HOPS (30)
181 boolean init();
182
183 /// Sets the max_hops to the given value
184 /// This controls the maximum number of hops allowed between source and destination nodes
185 /// Messages that are not delivered by the time their HOPS field exceeds max_hops on a
186 /// routing node will be dropped and ignored.
187 /// \param [in] max_hops The new value for max_hops
188 void setMaxHops(uint8_t max_hops);
189
190 /// Adds a route to the local routing table, or updates it if already present.
191 /// If there is not enough room the oldest (first) route will be deleted by calling retireOldestRoute().
192 /// \param [in] dest The destination node address. RF22_BROADCAST_ADDRESS is permitted.
193 /// \param [in] next_hop The address of the next hop to send messages destined for dest
194 /// \param [in] state The satte of the route. Defaults to Valid
195 void addRouteTo(uint8_t dest, uint8_t next_hop, uint8_t state = Valid);
196
197 /// Finds and returns a RoutingTableEntry for the given destination node
198 /// \param [in] dest The desired destination node address.
199 /// \return pointer to a RoutingTableEntry for dest
200 RoutingTableEntry* getRouteTo(uint8_t dest);
201
202 /// Deletes from the local routing table any route for the destination node.
203 /// \param [in] dest The destination node address
204 /// \return true if the route was present
205 boolean deleteRouteTo(uint8_t dest);
206
207 /// Deletes the oldest (first) route from the
208 /// local routing table
209 void retireOldestRoute();
210
211 /// Clears all entries from the
212 /// local routing table
213 void clearRoutingTable();
214
215 /// If RF22_HAVE_SERIAL is defined, this will print out the contents of the local
216 /// routing table using Serial
217 void printRoutingTable();
218
219 /// Sends a message to the destination node. Initialises the RF22Router message header
220 /// (the SOURCE address is set to the address of this node, HOPS to 0) and calls
221 /// route() which looks up in the routing table the next hop to deliver to and sends the
222 /// message to the next hop. Waits for an acknowledgement from the next hop
223 /// (but not from the destination node (if that is different).
224 /// \param [in] buf The application message data
225 /// \param [in] len Number of octets in the application message data. 0 is permitted
226 /// \param [in] dest The destination node address
227 /// \return The result code:
228 /// - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop
229 /// (not necessarily to the final dest address)
230 /// - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
231 /// - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop
232 /// (usually because it dod not acknowledge due to being off the air or out of range
233 uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest);
234
235 /// Similar to sendtoWait() above, but spoofs the source address.
236 /// For internal use only during routing
237 /// \param [in] buf The application message data
238 /// \param [in] len Number of octets in the application message data. 0 is permitted
239 /// \param [in] dest The destination node address
240 /// \param [in] source The (fake) originatong node address.
241 /// \return The result code:
242 /// - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop
243 /// (not necessarily to the final dest address)
244 /// - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
245 /// - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop
246 /// (usually because it dod not acknowledge due to being off the air or out of range
247 uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest, uint8_t source);
248
249 /// Starts the receiver if it is not running already.
250 /// If there is a valid message available for this node (or RF22_BROADCAST_ADDRESS),
251 /// send an acknowledgement to the last hop
252 /// address (blocking until this is complete), then copy the application message payload data
253 /// to buf and return true
254 /// else return false.
255 /// If a message is copied, *len is set to the length..
256 /// If from is not NULL, the originator SOURCE address is placed in *source.
257 /// If to is not NULL, the DEST address is placed in *dest. This might be this nodes address or
258 /// RF22_BROADCAST_ADDRESS.
259 /// This is the preferred function for getting messages addressed to this node.
260 /// If the message is not a broadcast, acknowledge to the sender before returning.
261 /// \param[in] buf Location to copy the received message
262 /// \param[in,out] len Available space in buf. Set to the actual number of octets copied.
263 /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address
264 /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address
265 /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID
266 /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS
267 /// (not just those addressed to this node).
268 /// \return true if a valid message was recvived for this node copied to buf
269 boolean recvfromAck(uint8_t* buf, uint8_t* len, uint8_t* source = NULL, uint8_t* dest = NULL, uint8_t* id = NULL, uint8_t* flags = NULL);
270
271 /// Starts the receiver if it is not running already.
272 /// Similar to recvfromAck(), this will block until either a valid message available for this node
273 /// or the timeout expires.
274 /// \param[in] buf Location to copy the received message
275 /// \param[in,out] len Available space in buf. Set to the actual number of octets copied.
276 /// \param[in] timeout Maximum time to wait in milliseconds
277 /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address
278 /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address
279 /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID
280 /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS
281 /// (not just those addressed to this node).
282 /// \return true if a valid message was copied to buf
283 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);
284
285 protected:
286
287 /// Lets sublasses peek at messages going
288 /// past before routing or local delivery.
289 /// Called by recvfromAck() immediately after it gets the message from RF22ReliableDatagram
290 /// \param [in] message Pointer to the RF22Router message that was received.
291 /// \param [in] messageLen Length of message in octets
292 virtual void peekAtMessage(RoutedMessage* message, uint8_t messageLen);
293
294 /// Finds the next-hop route and sends the message via RF22ReliableDatagram::sendtoWait().
295 /// This is virtual, which lets subclasses override or intercept the route() function.
296 /// Called by sendtoWait after the message header has been filled in.
297 /// \param [in] message Pointer to the RF22Router message to be sent.
298 /// \param [in] messageLen Length of message in octets
299 virtual uint8_t route(RoutedMessage* message, uint8_t messageLen);
300
301 /// Deletes a specific rout entry from therouting table
302 /// \param [in] index The 0 based index of the routing table entry to delete
303 void deleteRoute(uint8_t index);
304
305 /// The last end-to-end sequence number to be used
306 /// Defaults to 0
307 uint8_t _lastE2ESequenceNumber;
308
309 /// The maximum number of hops permitted in routed messages.
310 /// If a routed message would exceed this number of hops it is dropped and ignored.
311 uint8_t _max_hops;
312
313 private:
314
315 /// Temporary mesage buffer
316 static RoutedMessage _tmpMessage;
317
318 /// Local routing table
319 RoutingTableEntry _routes[RF22_ROUTING_TABLE_SIZE];
320 };
321
322 #endif
323
RF22Router::RF22Router
RF22Router(uint8_t thisAddress=0, uint8_t slaveSelectPin=SS, uint8_t interrupt=0)
Definition: RF22Router.cpp:21
RF22Router::setMaxHops
void setMaxHops(uint8_t max_hops)
Definition: RF22Router.cpp:39
RF22Router::sendtoWait
uint8_t sendtoWait(uint8_t *buf, uint8_t len, uint8_t dest)
Definition: RF22Router.cpp:155
RF22Router::route
virtual uint8_t route(RoutedMessage *message, uint8_t messageLen)
Definition: RF22Router.cpp:179
RF22Router::deleteRoute
void deleteRoute(uint8_t index)
Definition: RF22Router.cpp:98
RF22Router::retireOldestRoute
void retireOldestRoute()
Definition: RF22Router.cpp:140
RF22Router::printRoutingTable
void printRoutingTable()
Definition: RF22Router.cpp:107
RF22Router::recvfromAck
boolean recvfromAck(uint8_t *buf, uint8_t *len, uint8_t *source=NULL, uint8_t *dest=NULL, uint8_t *id=NULL, uint8_t *flags=NULL)
Definition: RF22Router.cpp:205
RF22Router::clearRoutingTable
void clearRoutingTable()
Definition: RF22Router.cpp:147
RF22Router::_lastE2ESequenceNumber
uint8_t _lastE2ESequenceNumber
Definition: RF22Router.h:307
RF22Router::RoutedMessage
Defines the structure of a RF22Router message.
Definition: RF22Router.h:149
RF22Router::peekAtMessage
virtual void peekAtMessage(RoutedMessage *message, uint8_t messageLen)
Definition: RF22Router.cpp:199
RF22Router::Valid
Route is valid.
Definition: RF22Router.h:160
RF22Router::RoutedMessage::header
RoutedMessageHeader header
end-to-end delivery header
Definition: RF22Router.h:151
RF22Router::deleteRouteTo
boolean deleteRouteTo(uint8_t dest)
Definition: RF22Router.cpp:125
RF22Router::RoutedMessageHeader::id
uint8_t id
Originator sequence number.
Definition: RF22Router.h:143
RF22Router::RoutingTableEntry::next_hop
uint8_t next_hop
Send via this next hop address.
Definition: RF22Router.h:167
RF22Router::RoutingTableEntry::state
uint8_t state
State of this route, one of RouteState.
Definition: RF22Router.h:168
RF22Router::_max_hops
uint8_t _max_hops
Definition: RF22Router.h:311
RF22Router::RoutedMessageHeader
Definition: RF22Router.h:138
RF22Router::init
boolean init()
Definition: RF22Router.cpp:30
RF22Router::recvfromAckTimeout
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)
Definition: RF22Router.cpp:292
RF22Router::RoutedMessageHeader::dest
uint8_t dest
Destination node address.
Definition: RF22Router.h:140
RF22Router::RoutedMessageHeader::source
uint8_t source
Originator node address.
Definition: RF22Router.h:141
RF22Router::RouteState
RouteState
Values for the possible states for routes.
Definition: RF22Router.h:156
RF22Router::addRouteTo
void addRouteTo(uint8_t dest, uint8_t next_hop, uint8_t state=Valid)
Definition: RF22Router.cpp:45
RF22Router::RoutingTableEntry::dest
uint8_t dest
Destination node address.
Definition: RF22Router.h:166
RF22Router::Invalid
No valid route is known.
Definition: RF22Router.h:158
RF22Router::RoutedMessageHeader::flags
uint8_t flags
Originator flags.
Definition: RF22Router.h:144
RF22ReliableDatagram
RF22 subclass for sending addressed, acknowledged, retransmitted datagrams.
Definition: RF22ReliableDatagram.h:41
RF22Router::Discovering
Discovering a route (not currently used)
Definition: RF22Router.h:159
RF22Router::RoutingTableEntry
Defines an entry in the routing table.
Definition: RF22Router.h:164
RF22Router::RoutedMessageHeader::hops
uint8_t hops
Hops traversed so far.
Definition: RF22Router.h:142
RF22Router::getRouteTo
RoutingTableEntry * getRouteTo(uint8_t dest)
Definition: RF22Router.cpp:88
RF22Router
RF22 subclass for sending addressed, optionally acknowledged datagrams multi-hop routed across a netw...
Definition: RF22Router.h:132