RF22
|
00001 // RF22Router.h 00002 // 00003 // Author: Mike McCauley (mikem@open.com.au) 00004 // Copyright (C) 2011 Mike McCauley 00005 // $Id: RF22Router.h,v 1.7 2011/02/15 01:18:03 mikem Exp $ 00006 00007 #ifndef RF22Router_h 00008 #define RF22Router_h 00009 00010 #include <RF22ReliableDatagram.h> 00011 00012 // Default max number of hops we will route 00013 #define RF22_DEFAULT_MAX_HOPS 30 00014 00015 // The default size of the routing table we keep 00016 #define RF22_ROUTING_TABLE_SIZE 10 00017 00018 // Error codes 00019 #define RF22_ROUTER_ERROR_NONE 0 00020 #define RF22_ROUTER_ERROR_INVALID_LENGTH 1 00021 #define RF22_ROUTER_ERROR_NO_ROUTE 2 00022 #define RF22_ROUTER_ERROR_TIMEOUT 3 00023 #define RF22_ROUTER_ERROR_NO_REPLY 4 00024 #define RF22_ROUTER_ERROR_UNABLE_TO_DELIVER 5 00025 00026 // This size of RF22_ROUTER_MAX_MESSAGE_LEN is OK for Arduino Mega, but too big for 00027 // Duemilanova. Size of 50 works with the sample router programs on Duemilanova. 00028 #define RF22_ROUTER_MAX_MESSAGE_LEN (RF22_MAX_MESSAGE_LEN - sizeof(RF22Router::RoutedMessageHeader)) 00029 //#define RF22_ROUTER_MAX_MESSAGE_LEN 50 00030 00031 // These allow us to define a simulated network topology for testing purposes 00032 // See RF22Router.cpp for details 00033 //#define RF22_TEST_NETWORK 1 00034 //#define RF22_TEST_NETWORK 2 00035 //#define RF22_TEST_NETWORK 3 00036 //#define RF22_TEST_NETWORK 4 00037 00038 ///////////////////////////////////////////////////////////////////// 00039 /// \class RF22Router RF22Router.h <RF22Router.h> 00040 /// \brief RF22 subclass for sending addressed, optionally acknowledged datagrams 00041 /// multi-hop routed across a network. 00042 /// 00043 /// Extends RF22ReliableDatagram to define addressed messages 00044 /// That are reliably transmitted and routed across a network. Each message is transmitted reliably 00045 /// between each hop in order to get from the source node to the destination node. 00046 /// 00047 /// With RF22Router, routes are hard wired. This means that each node must have programmed 00048 /// in it how to reach each of the other nodes it will be trying to communicate with. 00049 /// This means you must specify the next-hop node address for each of the destination nodes, 00050 /// using the addRouteTo() function. 00051 /// 00052 /// When sendtoWait() is called with a new message to deliver, and the destination address, 00053 /// RF22Router looks up the next hop node for the destination node. It then uses 00054 /// RF22ReliableDatagram to (reliably) deliver the message to the next hop 00055 /// (which is expected also to be running an RF22Router). If that next-hop node is not 00056 /// the final destination, it will also look up the next hop for the destination node and 00057 /// (reliably) deliver the message to the next hop. By this method, messages can be delivered 00058 /// across a network of nodes, even if each node cannot hear all of the others in the network. 00059 /// Each time a message is received for another node and retransmitted to the next hop, 00060 /// the HOPS filed in teh header is incremented. If a message is received for routing to another node 00061 /// which has exceed the routers max_hops, the message wioll be dropped and ignored. 00062 /// This helps prevent infinite routing loops. 00063 /// 00064 /// RF22Router supports messages with a dest of RF22_BROADCAST_ADDRESS. Such messages are not routed, 00065 /// and are broadcast (once) to all nodes within range. 00066 /// 00067 /// The recvfromAck() function is responsible not just for receiving and delivering 00068 /// messages addressed to this node (or RF22_BROADCAST_ADDRESS), but 00069 /// it is also responsible for routing other message to their next hop. This means that it is important to 00070 /// call recvfromAck() or recvfromAckTimeout() frequently in your main loop. recvfromAck() will return 00071 /// false if it receives a message but it is not for this node. 00072 /// 00073 /// RF22Router does not provide reliable end-to-end delivery, but uses reliable hop-to-hop delivery. 00074 /// If a message is unable to be delivered to an end node during to a delivery failure between 2 hops, 00075 /// the source node will not be told about it. 00076 /// 00077 /// Note: This class is most useful for networks of nodes that are essentially static 00078 /// (i.e. the nodes dont move around), and for which the 00079 /// routing never changes. If that is not the case for your proposed network, see RF22Mesh instead. 00080 /// 00081 /// \par The Routing Table 00082 /// 00083 /// The routing table is a local table in RF22Router that holds the information about the next hop node 00084 /// address for each destination address you may want to send a message to. It is your responsibility 00085 /// to make sure every node in an RF22Router network has been configured with a unique address and the 00086 /// routing information so that messages are correctly routed across the network from source node to 00087 /// destination node. This is usually done once in setup() by calling addRouteTo(). 00088 /// The hardwired routing will in general be different on each node, and will depend on the physical 00089 /// topololgy of the network. 00090 /// You can also use addRouteTo() to change a route and 00091 /// deleteRouteTo() to delete a route at run time. Youcan also clear the entire routing table 00092 /// 00093 /// The Routing Table has limited capacity for entries (defined by RF22_ROUTING_TABLE_SIZE, which is 10) 00094 /// if more than RF22_ROUTING_TABLE_SIZE are added, the oldest (first) one will be removed by calling 00095 /// retireOldestRoute() 00096 /// 00097 /// \par Message Format 00098 /// 00099 /// RF22Router add to the lower level RF22ReliableDatagram (and even lower level RF22) class mesage formats. 00100 /// In those lower level classes, the hop-to-hop message headers are in the RF22 message headers, 00101 /// and are handled automcatically by tyhe RF22 hardware. 00102 /// RF22Router and its subclasses add an end-to-end addressing header in the payload of the RF22 message, 00103 /// and before the RF22Router application data. 00104 /// - 1 octet DEST, the destination node address (ie the address of the final 00105 /// destination node for this message) 00106 /// - 1 octet SOURCE, the source node address (ie the address of the originating node that first sent 00107 /// the message). 00108 /// - 1 octet HOPS, the number of hops this message has traversed so far. 00109 /// - 1 octet ID, an incrementing message ID for end-to-end message tracking for use by subclasses. 00110 /// Not used by RF22Router. 00111 /// - 1 octet FLAGS, a bitmask for use by subclasses. Not used by RF22Router. 00112 /// - 0 or more octets DATA, the application payload data. The length of this data is implicit 00113 /// in the length of the entire message. 00114 /// 00115 /// You should be careful to note that there are ID and FLAGS fields in the low level per-hop 00116 /// message header too. These are used only for hop-to-hop, and in general will be different to 00117 /// the ones at the RF22Router level. 00118 /// 00119 /// \par Testing 00120 /// 00121 /// Bench testing of such networks is notoriously difficult, especially simulating limited radio 00122 /// connectivity between some nodes. 00123 /// To assist testing (both during RF22 development and for your own networks) 00124 /// RF22Router.cpp has the ability to 00125 /// simulate a number of different small network topologies. Each simulated network supports 4 nodes with 00126 /// addresses 1 to 4. It operates by pretending to not hear RF22 messages from certain other nodes. 00127 /// You can enable testing with a \#define TEST_NETWORK in RF22Router.h 00128 /// The sample programs rf22_mesh_* rely on this feature. 00129 /// 00130 /// Part of the Arduino RF22 library for operating with HopeRF RF22 compatible transceivers 00131 /// (see http://www.hoperf.com) 00132 class RF22Router : public RF22ReliableDatagram 00133 { 00134 public: 00135 00136 /// Defines the structure of the RF22Router message header, used to keep track of end-to-end delivery 00137 /// parameters 00138 typedef struct 00139 { 00140 uint8_t dest; ///< Destination node address 00141 uint8_t source; ///< Originator node address 00142 uint8_t hops; ///< Hops traversed so far 00143 uint8_t id; ///< Originator sequence number 00144 uint8_t flags; ///< Originator flags 00145 // Data follows, Length is implicit in the overall message length 00146 } RoutedMessageHeader; 00147 00148 /// Defines the structure of a RF22Router message 00149 typedef struct 00150 { 00151 RoutedMessageHeader header; ///< end-to-end delivery header 00152 uint8_t data[RF22_ROUTER_MAX_MESSAGE_LEN]; ///< Applicaiton payload data 00153 } RoutedMessage; 00154 00155 /// Values for the possible states for routes 00156 typedef enum 00157 { 00158 Invalid = 0, ///< No valid route is known 00159 Discovering, ///< Discovering a route (not currently used) 00160 Valid ///< Route is valid 00161 } RouteState; 00162 00163 /// Defines an entry in the routing table 00164 typedef struct 00165 { 00166 uint8_t dest; ///< Destination node address 00167 uint8_t next_hop; ///< Send via this next hop address 00168 uint8_t state; ///< State of this route, one of RouteState 00169 } RoutingTableEntry; 00170 00171 /// Constructor. 00172 /// \param[in] thisAddress The address to assign to this node. Defaults to 0 00173 /// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the RF22 before 00174 /// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega) 00175 /// \param[in] interrupt The interrupt number to use. Default is interrupt 0 (Arduino input pin 2) 00176 RF22Router(uint8_t thisAddress = 0, uint8_t slaveSelectPin = SS, uint8_t interrupt = 0); 00177 00178 /// Initialises this instance and the radio module connected to it. 00179 /// Overrides the init() function in RF22. 00180 /// Sets max_hops to the default of RF22_DEFAULT_MAX_HOPS (30) 00181 boolean init(); 00182 00183 /// Sets the max_hops to the given value 00184 /// This controls the maximum number of hops allowed between source and destination nodes 00185 /// Messages that are not delivered by the time their HOPS field exceeds max_hops on a 00186 /// routing node will be dropped and ignored. 00187 /// \param [in] max_hops The new value for max_hops 00188 void setMaxHops(uint8_t max_hops); 00189 00190 /// Adds a route to the local routing table, or updates it if already present. 00191 /// If there is not enough room the oldest (first) route will be deleted by calling retireOldestRoute(). 00192 /// \param [in] dest The destination node address. RF22_BROADCAST_ADDRESS is permitted. 00193 /// \param [in] next_hop The address of the next hop to send messages destined for dest 00194 /// \param [in] state The satte of the route. Defaults to Valid 00195 void addRouteTo(uint8_t dest, uint8_t next_hop, uint8_t state = Valid); 00196 00197 /// Finds and returns a RoutingTableEntry for the given destination node 00198 /// \param [in] dest The desired destination node address. 00199 /// \return pointer to a RoutingTableEntry for dest 00200 RoutingTableEntry* getRouteTo(uint8_t dest); 00201 00202 /// Deletes from the local routing table any route for the destination node. 00203 /// \param [in] dest The destination node address 00204 /// \return true if the route was present 00205 boolean deleteRouteTo(uint8_t dest); 00206 00207 /// Deletes the oldest (first) route from the 00208 /// local routing table 00209 void retireOldestRoute(); 00210 00211 /// Clears all entries from the 00212 /// local routing table 00213 void clearRoutingTable(); 00214 00215 /// If RF22_HAVE_SERIAL is defined, this will print out the contents of the local 00216 /// routing table using Serial 00217 void printRoutingTable(); 00218 00219 /// Sends a message to the destination node. Initialises the RF22Router message header 00220 /// (the SOURCE address is set to the address of this node, HOPS to 0) and calls 00221 /// route() which looks up in the routing table the next hop to deliver to and sends the 00222 /// message to the next hop. Waits for an acknowledgement from the next hop 00223 /// (but not from the destination node (if that is different). 00224 /// \param [in] buf The application message data 00225 /// \param [in] len Number of octets in the application message data. 0 is permitted 00226 /// \param [in] dest The destination node address 00227 /// \return The result code: 00228 /// - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop 00229 /// (not necessarily to the final dest address) 00230 /// - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table 00231 /// - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop 00232 /// (usually because it dod not acknowledge due to being off the air or out of range 00233 uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest); 00234 00235 /// Similar to sendtoWait() above, but spoofs the source address. 00236 /// For internal use only during routing 00237 /// \param [in] buf The application message data 00238 /// \param [in] len Number of octets in the application message data. 0 is permitted 00239 /// \param [in] dest The destination node address 00240 /// \param [in] source The (fake) originatong node address. 00241 /// \return The result code: 00242 /// - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop 00243 /// (not necessarily to the final dest address) 00244 /// - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table 00245 /// - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop 00246 /// (usually because it dod not acknowledge due to being off the air or out of range 00247 uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest, uint8_t source); 00248 00249 /// Starts the receiver if it is not running already. 00250 /// If there is a valid message available for this node (or RF22_BROADCAST_ADDRESS), 00251 /// send an acknowledgement to the last hop 00252 /// address (blocking until this is complete), then copy the application message payload data 00253 /// to buf and return true 00254 /// else return false. 00255 /// If a message is copied, *len is set to the length.. 00256 /// If from is not NULL, the originator SOURCE address is placed in *source. 00257 /// If to is not NULL, the DEST address is placed in *dest. This might be this nodes address or 00258 /// RF22_BROADCAST_ADDRESS. 00259 /// This is the preferred function for getting messages addressed to this node. 00260 /// If the message is not a broadcast, acknowledge to the sender before returning. 00261 /// \param[in] buf Location to copy the received message 00262 /// \param[in,out] len Available space in buf. Set to the actual number of octets copied. 00263 /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address 00264 /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address 00265 /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID 00266 /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS 00267 /// (not just those addressed to this node). 00268 /// \return true if a valid message was recvived for this node copied to buf 00269 boolean recvfromAck(uint8_t* buf, uint8_t* len, uint8_t* source = NULL, uint8_t* dest = NULL, uint8_t* id = NULL, uint8_t* flags = NULL); 00270 00271 /// Starts the receiver if it is not running already. 00272 /// Similar to recvfromAck(), this will block until either a valid message available for this node 00273 /// or the timeout expires. 00274 /// \param[in] buf Location to copy the received message 00275 /// \param[in,out] len Available space in buf. Set to the actual number of octets copied. 00276 /// \param[in] timeout Maximum time to wait in milliseconds 00277 /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address 00278 /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address 00279 /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID 00280 /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS 00281 /// (not just those addressed to this node). 00282 /// \return true if a valid message was copied to buf 00283 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); 00284 00285 protected: 00286 00287 /// Lets sublasses peek at messages going 00288 /// past before routing or local delivery. 00289 /// Called by recvfromAck() immediately after it gets the message from RF22ReliableDatagram 00290 /// \param [in] message Pointer to the RF22Router message that was received. 00291 /// \param [in] messageLen Length of message in octets 00292 virtual void peekAtMessage(RoutedMessage* message, uint8_t messageLen); 00293 00294 /// Finds the next-hop route and sends the message via RF22ReliableDatagram::sendtoWait(). 00295 /// This is virtual, which lets subclasses override or intercept the route() function. 00296 /// Called by sendtoWait after the message header has been filled in. 00297 /// \param [in] message Pointer to the RF22Router message to be sent. 00298 /// \param [in] messageLen Length of message in octets 00299 virtual uint8_t route(RoutedMessage* message, uint8_t messageLen); 00300 00301 /// Deletes a specific rout entry from therouting table 00302 /// \param [in] index The 0 based index of the routing table entry to delete 00303 void deleteRoute(uint8_t index); 00304 00305 /// The last end-to-end sequence number to be used 00306 /// Defaults to 0 00307 uint8_t _lastE2ESequenceNumber; 00308 00309 /// The maximum number of hops permitted in routed messages. 00310 /// If a routed message would exceed this number of hops it is dropped and ignored. 00311 uint8_t _max_hops; 00312 00313 private: 00314 00315 /// Temporary mesage buffer 00316 static RoutedMessage _tmpMessage; 00317 00318 /// Local routing table 00319 RoutingTableEntry _routes[RF22_ROUTING_TABLE_SIZE]; 00320 }; 00321 00322 #endif 00323