- Main Page
- Classes
- Files

# 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.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
    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 = 10, 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 #ifdef RF22_HAVE_SERIAL
    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 #endif
    00220
    00221     /// Sends a message to the destination node. Initialises the RF22Router message header
    00222     /// (the SOURCE address is set to the address of this node, HOPS to 0) and calls
    00223     /// route() which looks up in the routing table the next hop to deliver to and sends the
    00224     /// message to the next hop. Waits for an acknowledgement from the next hop
    00225     /// (but not from the destination node (if that is different).
    00226     /// \param [in] buf The application message data
    00227     /// \param [in] len Number of octets in the application message data. 0 is permitted
    00228     /// \param [in] dest The destination node address
    00229     /// \return The result code:
    00230     ///         - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop
    00231     ///           (not necessarily to the final dest address)
    00232     ///         - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
    00233     ///         - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop
    00234     ///           (usually because it dod not acknowledge due to being off the air or out of range
    00235     uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest);
    00236
    00237     /// Similar to sendtoWait() above, but spoofs the source address.
    00238     /// For internal use only during routing
    00239     /// \param [in] buf The application message data
    00240     /// \param [in] len Number of octets in the application message data. 0 is permitted
    00241     /// \param [in] dest The destination node address
    00242     /// \param [in] source The (fake) originatong node address.
    00243     /// \return The result code:
    00244     ///         - RF22_ROUTER_ERROR_NONE Message was routed and deliverd to the next hop
    00245     ///           (not necessarily to the final dest address)
    00246     ///         - RF22_ROUTER_ERROR_NO_ROUTE There was no route for dest in the local routing table
    00247     ///         - RF22_ROUTER_ERROR_UNABLE_TO_DELIVER Noyt able to deliver to the next hop
    00248     ///           (usually because it dod not acknowledge due to being off the air or out of range
    00249     uint8_t sendtoWait(uint8_t* buf, uint8_t len, uint8_t dest, uint8_t source);
    00250
    00251     /// Starts the receiver if it is not running already.
    00252     /// If there is a valid message available for this node (or RF22_BROADCAST_ADDRESS),
    00253     /// send an acknowledgement to the last hop
    00254     /// address (blocking until this is complete), then copy the application message payload data
    00255     /// to buf and return true
    00256     /// else return false.
    00257     /// If a message is copied, *len is set to the length..
    00258     /// If from is not NULL, the originator SOURCE address is placed in *source.
    00259     /// If to is not NULL, the DEST address is placed in *dest. This might be this nodes address or
    00260     /// RF22_BROADCAST_ADDRESS.
    00261     /// This is the preferred function for getting messages addressed to this node.
    00262     /// If the message is not a broadcast, acknowledge to the sender before returning.
    00263     /// \param[in] buf Location to copy the received message
    00264     /// \param[in,out] len Available space in buf. Set to the actual number of octets copied.
    00265     /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address
    00266     /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address
    00267     /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID
    00268     /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS
    00269     /// (not just those addressed to this node).
    00270     /// \return true if a valid message was recvived for this node copied to buf
    00271     boolean recvfromAck(uint8_t* buf, uint8_t* len, uint8_t* source = NULL, uint8_t* dest = NULL, uint8_t* id = NULL, uint8_t* flags = NULL);
    00272
    00273     /// Starts the receiver if it is not running already.
    00274     /// Similar to recvfromAck(), this will block until either a valid message available for this node
    00275     /// or the timeout expires.
    00276     /// \param[in] buf Location to copy the received message
    00277     /// \param[in,out] len Available space in buf. Set to the actual number of octets copied.
    00278     /// \param[in] timeout Maximum time to wait in milliseconds
    00279     /// \param[in] source If present and not NULL, the referenced uint8_t will be set to the SOURCE address
    00280     /// \param[in] dest If present and not NULL, the referenced uint8_t will be set to the DEST address
    00281     /// \param[in] id If present and not NULL, the referenced uint8_t will be set to the ID
    00282     /// \param[in] flags If present and not NULL, the referenced uint8_t will be set to the FLAGS
    00283     /// (not just those addressed to this node).
    00284     /// \return true if a valid message was copied to buf
    00285     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);
    00286
    00287 protected:
    00288
    00289     /// Lets sublasses peek at messages going
    00290     /// past before routing or local delivery.
    00291     /// Called by recvfromAck() immediately after it gets the message from RF22ReliableDatagram
    00292     /// \param [in] message Pointer to the RF22Router message that was received.
    00293     /// \param [in] messageLen Length of message in octets
    00294     virtual void peekAtMessage(RoutedMessage* message, uint8_t messageLen);
    00295
    00296     /// Finds the next-hop route and sends the message via RF22ReliableDatagram::sendtoWait().
    00297     /// This is virtual, which lets subclasses override or intercept the route() function.
    00298     /// Called by sendtoWait after the message header has been filled in.
    00299     /// \param [in] message Pointer to the RF22Router message to be sent.
    00300     /// \param [in] messageLen Length of message in octets
    00301     virtual uint8_t route(RoutedMessage* message, uint8_t messageLen);
    00302
    00303     /// Deletes a specific rout entry from therouting table
    00304     /// \param [in] index The 0 based index of the routing table entry to delete
    00305     void deleteRoute(uint8_t index);
    00306
    00307     /// The last end-to-end sequence number to be used
    00308     /// Defaults to 0
    00309     uint8_t _lastE2ESequenceNumber;
    00310
    00311     /// The maximum number of hops permitted in routed messages.
    00312     /// If a routed message would exceed this number of hops it is dropped and ignored.
    00313     uint8_t              _max_hops;
    00314
    00315 private:
    00316
    00317     /// Temporary mesage buffer
    00318     static RoutedMessage _tmpMessage;
    00319
    00320     /// Local routing table
    00321     RoutingTableEntry    _routes[RF22_ROUTING_TABLE_SIZE];
    00322 };
    00323
    00324 #endif
    00325