RF22Router.h

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