RF24Network.h

00001 /*
00002  Copyright (C) 2011 James Coliz, Jr. <maniacbug@ymail.com>
00003 
00004  This program is free software; you can redistribute it and/or
00005  modify it under the terms of the GNU General Public License
00006  version 2 as published by the Free Software Foundation.
00007  */
00008 
00009 /*
00010 * Mbed support added by Akash Vibhute <akash.roboticist@gmail.com>
00011 * Porting completed on Nov/05/2015
00012 *
00013 * Updated with TMRh20's RF24 library on Nov/04/2015 from https://github.com/TMRh20
00014 *
00015 */
00016 
00017 #ifndef __RF24NETWORK_H__
00018 #define __RF24NETWORK_H__
00019 
00020 /**
00021  * @file RF24Network.h
00022  *
00023  * Class declaration for RF24Network
00024  */
00025 #define min(a,b) (a<b?a:b)
00026 #include <stddef.h>
00027 #include <stdint.h>
00028 #include "RF24Network_config.h"
00029 
00030 /* Header types range */
00031 #define MIN_USER_DEFINED_HEADER_TYPE 0
00032 #define MAX_USER_DEFINED_HEADER_TYPE 127
00033 
00034 /**
00035 
00036  */
00037 
00038 // ACK Response Types
00039 /**
00040  * **Reserved network message types**
00041  *
00042  * The network will determine whether to automatically acknowledge payloads based on their general type <br>
00043  *
00044  * **User types** (1-127) 1-64 will NOT be acknowledged <br>
00045  * **System types** (128-255) 192 through 255 will NOT be acknowledged<br>
00046  *
00047  * @defgroup DEFINED_TYPES Reserved System Message Types
00048  *
00049  * System types can also contain message data.
00050  *
00051  * @{
00052  */
00053 
00054 /**
00055 * A NETWORK_ADDR_RESPONSE type is utilized to manually route custom messages containing a single RF24Network address
00056 *
00057 * Used by RF24Mesh
00058 *
00059 * If a node receives a message of this type that is directly addressed to it, it will read the included message, and forward the payload
00060 * on to the proper recipient. <br>
00061 * This allows nodes to forward multicast messages to the master node, receive a response, and forward it back to the requester.
00062 */
00063 #define NETWORK_ADDR_RESPONSE 128
00064 //#define NETWORK_ADDR_CONFIRM 129
00065 
00066 /**
00067 * Messages of type NETWORK_PING will be dropped automatically by the recipient. A NETWORK_ACK or automatic radio-ack will indicate to the sender whether the
00068 * payload was successful. The time it takes to successfully send a NETWORK_PING is the round-trip-time.
00069 */
00070 #define NETWORK_PING 130
00071 
00072 /**
00073  * External data types are used to define messages that will be passed to an external data system. This allows RF24Network to route and pass any type of data, such
00074  * as TCP/IP frames, while still being able to utilize standard RF24Network messages etc.
00075  *
00076  * **Linux**
00077  * Linux devices (defined RF24_LINUX) will buffer all data types in the user cache.
00078  *
00079  * **Arduino/AVR/Etc:** Data transmitted with the type set to EXTERNAL_DATA_TYPE will not be loaded into the user cache. <br>
00080  * External systems can extract external data using the following process, while internal data types are cached in the user buffer, and accessed using network.read() :
00081  * @code
00082  * uint8_t return_type = network.update();
00083  * if(return_type == EXTERNAL_DATA_TYPE){
00084  *     uint16_t size = network.frag_ptr->message_size;
00085  *     memcpy(&myDataBuffer,network.frag_ptr->message_buffer,network.frag_ptr->message_size);
00086  * }
00087  * @endcode
00088  */
00089 #define EXTERNAL_DATA_TYPE 131
00090 
00091 /**
00092  * Messages of this type designate the first of two or more message fragments, and will be re-assembled automatically.
00093  */
00094 #define NETWORK_FIRST_FRAGMENT 148
00095 
00096 /**
00097  * Messages of this type indicate a fragmented payload with two or more message fragments.
00098  */
00099 #define NETWORK_MORE_FRAGMENTS 149
00100 
00101 /**
00102  * Messages of this type indicate the last fragment in a sequence of message fragments.
00103  * Messages of this type do not receive a NETWORK_ACK
00104  */
00105 #define NETWORK_LAST_FRAGMENT 150
00106 //#define NETWORK_LAST_FRAGMENT 201
00107 
00108 // NO ACK Response Types
00109 //#define NETWORK_ACK_REQUEST 192
00110 
00111 /**
00112  * Messages of this type are used internally, to signal the sender that a transmission has been completed.
00113  * RF24Network does not directly have a built-in transport layer protocol, so message delivery is not 100% guaranteed.<br>
00114  * Messages can be lost via corrupted dynamic payloads, or a NETWORK_ACK can fail, while the message was actually successful.
00115  *
00116  * NETWORK_ACK messages can be utilized as a traffic/flow control mechanism, since transmitting nodes will be forced to wait until
00117  * the payload is transmitted across the network and acknowledged, before sending additional data.
00118  *
00119  * In the event that the transmitting device will be waiting for a direct response, manually sent by the recipient, a NETWORK_ACK is not required. <br>
00120  * User messages utilizing a 'type' with a decimal value of 64 or less will not be acknowledged across the network via NETWORK_ACK messages.
00121  */
00122 #define NETWORK_ACK 193
00123 
00124 /**
00125  * Used by RF24Mesh
00126  *
00127  * Messages of this type are used with multi-casting , to find active/available nodes.
00128  * Any node receiving a NETWORK_POLL sent to a multicast address will respond directly to the sender with a blank message, indicating the
00129  * address of the available node via the header.
00130  */
00131 #define NETWORK_POLL 194
00132 
00133 /**
00134  * Used by RF24Mesh
00135  *
00136  * Messages of this type are used to request information from the master node, generally via a unicast (direct) write.
00137  * Any (non-master) node receiving a message of this type will manually forward it to the master node using an normal network write.
00138  */
00139 #define NETWORK_REQ_ADDRESS 195
00140 //#define NETWORK_ADDR_LOOKUP 196
00141 //#define NETWORK_ADDR_RELEASE 197
00142 /** @} */
00143 
00144 #define NETWORK_MORE_FRAGMENTS_NACK 200
00145 
00146 /** Internal defines for handling written payloads */
00147 #define TX_NORMAL 0
00148 #define TX_ROUTED 1
00149 #define USER_TX_TO_PHYSICAL_ADDRESS 2  //no network ACK
00150 #define USER_TX_TO_LOGICAL_ADDRESS 3   // network ACK
00151 #define USER_TX_MULTICAST 4
00152 
00153 #define MAX_FRAME_SIZE 32   //Size of individual radio frames
00154 #define FRAME_HEADER_SIZE 10 //Size of RF24Network frames - data
00155 
00156 #define USE_CURRENT_CHANNEL 255 // Use current radio channel when setting up the network
00157 
00158 /** Internal defines for handling internal payloads - prevents reading additional data from the radio
00159  * when buffers are full */
00160 #define FLAG_HOLD_INCOMING 1
00161 /** FLAG_BYPASS_HOLDS is mainly for use with RF24Mesh as follows:
00162  * a: Ensure no data in radio buffers, else exit
00163  * b: Address is changed to multicast address for renewal
00164  * c: Holds Cleared (bypass flag is set)
00165  * d: Address renewal takes place and is set
00166  * e: Holds Enabled (bypass flag off)
00167  */
00168 #define FLAG_BYPASS_HOLDS 2
00169 
00170 #define FLAG_FAST_FRAG 4
00171 
00172 class RF24;
00173 
00174 /**
00175  * Header which is sent with each message
00176  *
00177  * The frame put over the air consists of this header and a message
00178  *
00179  * Headers are addressed to the appropriate node, and the network forwards them on to their final destination.
00180  */
00181 struct RF24NetworkHeader {
00182     uint16_t from_node; /**< Logical address where the message was generated */
00183     uint16_t to_node; /**< Logical address where the message is going */
00184     uint16_t id; /**< Sequential message ID, incremented every time a new frame is constructed */
00185     /**
00186      * Message Types:
00187      * User message types 1 through 64 will NOT be acknowledged by the network, while message types 65 through 127 will receive a network ACK.
00188      * System message types 192 through 255 will NOT be acknowledged by the network. Message types 128 through 192 will receive a network ACK. <br>
00189      * <br><br>
00190      */
00191     unsigned char type; /**< <b>Type of the packet. </b> 0-127 are user-defined types, 128-255 are reserved for system */
00192 
00193     /**
00194     * During fragmentation, it carries the fragment_id, and on the last fragment
00195     * it carries the header_type.<br>
00196     */
00197     unsigned char reserved; /**< *Reserved for system use* */
00198 
00199     static uint16_t next_id; /**< The message ID of the next message to be sent (unused)*/
00200 
00201     /**
00202      * Default constructor
00203      *
00204 
00205      * Simply constructs a blank header
00206      */
00207     RF24NetworkHeader() {}
00208 
00209     /**
00210      * Send constructor
00211      *
00212      * @note Now supports automatic fragmentation for very long messages, which can be sent as usual if fragmentation is enabled.
00213      *
00214      * Fragmentation is enabled by default for all devices except ATTiny <br>
00215      * Configure fragmentation and max payload size in RF24Network_config.h
00216      *
00217      * Use this constructor to create a header and then send a message
00218      *
00219      * @code
00220      *  uint16_t recipient_address = 011;
00221      *
00222      *  RF24NetworkHeader header(recipient_address,'t');
00223      *
00224      *  network.write(header,&message,sizeof(message));
00225      * @endcode
00226      *
00227      * @param _to The Octal format, logical node address where the message is going
00228      * @param _type The type of message which follows.  Only 0-127 are allowed for
00229      * user messages. Types 1-64 will not receive a network acknowledgement.
00230      */
00231 
00232     RF24NetworkHeader(uint16_t _to, unsigned char _type = 0): to_node(_to), id(next_id++), type(_type) {}
00233     /**
00234      * Create debugging string
00235      *
00236      * Useful for debugging.  Dumps all members into a single string, using
00237      * internal static memory.  This memory will get overridden next time
00238      * you call the method.
00239      *
00240      * @return String representation of this object
00241      */
00242     const char* toString(void) const;
00243 };
00244 
00245 
00246 /**
00247  * Frame structure for internal message handling, and for use by external applications
00248  *
00249  * The actual frame put over the air consists of a header (8-bytes) and a message payload (Up to 24-bytes)<br>
00250  * When data is received, it is stored using the RF24NetworkFrame structure, which includes:
00251  * 1. The header
00252  * 2. The size of the included message
00253  * 3. The 'message' or data being received
00254  *
00255  *
00256  */
00257 
00258 struct RF24NetworkFrame {
00259     RF24NetworkHeader header; /**< Header which is sent with each message */
00260     uint16_t message_size; /**< The size in bytes of the payload length */
00261 
00262     /**
00263     * On Arduino, the message buffer is just a pointer, and can be pointed to any memory location.
00264     * On Linux the message buffer is a standard byte array, equal in size to the defined MAX_PAYLOAD_SIZE
00265     */
00266 
00267     uint8_t *message_buffer; //< Pointer to the buffer storing the actual message
00268 
00269     /**
00270      * Default constructor
00271      *
00272      * Simply constructs a blank frame. Frames are generally used internally. See RF24NetworkHeader.
00273      */
00274     //RF24NetworkFrame() {}
00275 
00276     RF24NetworkFrame() {}
00277     /**
00278      * Constructor - create a network frame with data
00279      * Frames are constructed and handled differently on Arduino/AVR and Linux devices (defined RF24_LINUX)
00280      *
00281      * <br>
00282      * **Linux:**
00283      * @param _header The RF24Network header to be stored in the frame
00284      * @param _message The 'message' or data.
00285      * @param _len The size of the 'message' or data.
00286      *
00287      * <br>
00288      * **Arduino/AVR/Etc.**
00289      * @see RF24Network.frag_ptr
00290      * @param _header The RF24Network header to be stored in the frame
00291      * @param _message_size The size of the 'message' or data
00292      *
00293      *
00294      * Frames are used internally and by external systems. See RF24NetworkHeader.
00295      */
00296 
00297 
00298     RF24NetworkFrame(RF24NetworkHeader &_header, uint16_t _message_size):
00299         header(_header), message_size(_message_size) {
00300     }
00301 
00302     /**
00303      * Create debugging string
00304      *
00305      * Useful for debugging.  Dumps all members into a single string, using
00306      * internal static memory.  This memory will get overridden next time
00307      * you call the method.
00308      *
00309      * @return String representation of this object
00310      */
00311     const char* toString(void) const;
00312 
00313 };
00314 
00315 
00316 
00317 /**
00318  * 2014-2015 - Optimized Network Layer for RF24 Radios
00319  *
00320  * This class implements an OSI Network Layer using nRF24L01(+) radios driven
00321  * by RF24 library.
00322  */
00323 
00324 class RF24Network
00325 {
00326 private:
00327     Timer rf24netTimer;
00328     /**@}*/
00329     /**
00330      * @name Primary Interface
00331      *
00332      *  These are the main methods you need to operate the network
00333      */
00334     /**@{*/
00335 public:
00336     /**
00337      * Construct the network
00338      *
00339      * @param _radio The underlying radio driver instance
00340      *
00341      */
00342 
00343     RF24Network( RF24& _radio );
00344 
00345     /**
00346      * Bring up the network using the current radio frequency/channel.
00347      * Calling begin brings up the network, and configures the address, which designates the location of the node within RF24Network topology.
00348      * @note Node addresses are specified in Octal format, see <a href=Addressing.html>RF24Network Addressing</a> for more information.
00349      * @warning Be sure to 'begin' the radio first.
00350      *
00351      * **Example 1:** Begin on current radio channel with address 0 (master node)
00352      * @code
00353      * network.begin(00);
00354      * @endcode
00355      * **Example 2:** Begin with address 01 (child of master)
00356      * @code
00357      * network.begin(01);
00358      * @endcode
00359      * **Example 3:** Begin with address 011 (child of 01, grandchild of master)
00360      * @code
00361      * network.begin(011);
00362      * @endcode
00363      *
00364      * @see begin(uint8_t _channel, uint16_t _node_address )
00365      * @param _node_address The logical address of this node
00366      *
00367      */
00368 
00369     inline void begin(uint16_t _node_address) {
00370         begin(USE_CURRENT_CHANNEL,_node_address);
00371     }
00372 
00373     /**
00374      * Main layer loop
00375      *
00376      * This function must be called regularly to keep the layer going.  This is where payloads are
00377      * re-routed, received, and all the action happens.
00378      *
00379      * @see
00380      *
00381      * @return Returns the type of the last received payload.
00382      */
00383     uint8_t update(void);
00384 
00385     /**
00386      * Test whether there is a message available for this node
00387      *
00388      * @return Whether there is a message available for this node
00389      */
00390     bool available(void);
00391 
00392     /**
00393      * Read the next available header
00394      *
00395      * Reads the next available header without advancing to the next
00396      * incoming message.  Useful for doing a switch on the message type
00397      *
00398      * If there is no message available, the header is not touched
00399      *
00400      * @param[out] header The header (envelope) of the next message
00401      */
00402     uint16_t peek(RF24NetworkHeader& header);
00403 
00404     /**
00405      * Read a message
00406      *
00407      * @code
00408      * while ( network.available() )  {
00409      *   RF24NetworkHeader header;
00410      *   uint32_t time;
00411      *   network.peek(header);
00412      *   if(header.type == 'T'){
00413      *     network.read(header,&time,sizeof(time));
00414      *     Serial.print("Got time: ");
00415      *     Serial.println(time);
00416      *   }
00417      * }
00418      * @endcode
00419      * @param[out] header The header (envelope) of this message
00420      * @param[out] message Pointer to memory where the message should be placed
00421      * @param maxlen The largest message size which can be held in @p message
00422      * @return The total number of bytes copied into @p message
00423      */
00424     uint16_t read(RF24NetworkHeader& header, void* message, uint16_t maxlen);
00425 
00426     /**
00427      * Send a message
00428      *
00429      * @note RF24Network now supports fragmentation for very long messages, send as normal. Fragmentation
00430      * may need to be enabled or configured by editing the RF24Network_config.h file. Default max payload size is 120 bytes.
00431      *
00432      * @code
00433      * uint32_t time = millis();
00434      * uint16_t to = 00; // Send to master
00435      * RF24NetworkHeader header(to, 'T'); // Send header type 'T'
00436      * network.write(header,&time,sizeof(time));
00437      * @endcode
00438      * @param[in,out] header The header (envelope) of this message.  The critical
00439      * thing to fill in is the @p to_node field so we know where to send the
00440      * message.  It is then updated with the details of the actual header sent.
00441      * @param message Pointer to memory where the message is located
00442      * @param len The size of the message
00443      * @return Whether the message was successfully received
00444      */
00445     bool write(RF24NetworkHeader& header,const void* message, uint16_t len);
00446 
00447     /**@}*/
00448     /**
00449      * @name Advanced Configuration
00450      *
00451      *  For advanced configuration of the network
00452      */
00453     /**@{*/
00454 
00455 
00456     /**
00457     * Construct the network in dual head mode using two radio modules.
00458     * @note Not working on RPi. Radios will share MISO, MOSI and SCK pins, but require separate CE,CS pins.
00459     * @code
00460     *    RF24 radio(7,8);
00461     *    RF24 radio1(4,5);
00462     *    RF24Network(radio.radio1);
00463     * @endcode
00464     * @param _radio The underlying radio driver instance
00465     * @param _radio1 The second underlying radio driver instance
00466     */
00467 
00468     RF24Network( RF24& _radio, RF24& _radio1);
00469 
00470     /**
00471     * By default, multicast addresses are divided into levels.
00472     *
00473     * Nodes 1-5 share a multicast address, nodes n1-n5 share a multicast address, and nodes n11-n55 share a multicast address.<br>
00474     *
00475     * This option is used to override the defaults, and create custom multicast groups that all share a single
00476     * address. <br>
00477     * The level should be specified in decimal format 1-6 <br>
00478     * @see multicastRelay
00479     * @param level Levels 1 to 6 are available. All nodes at the same level will receive the same
00480     * messages if in range. Messages will be routed in order of level, low to high by default, with the
00481     * master node (00) at multicast Level 0
00482     */
00483 
00484     void multicastLevel(uint8_t level);
00485 
00486     /**
00487     * Enabling this will allow this node to automatically forward received multicast frames to the next highest
00488     * multicast level. Duplicate frames are filtered out, so multiple forwarding nodes at the same level should
00489     * not interfere. Forwarded payloads will also be received.
00490     * @see multicastLevel
00491     */
00492 
00493     bool multicastRelay;
00494 
00495     /**
00496       * Set up the watchdog timer for sleep mode using the number 0 through 10 to represent the following time periods:<br>
00497       * wdt_16ms = 0, wdt_32ms, wdt_64ms, wdt_128ms, wdt_250ms, wdt_500ms, wdt_1s, wdt_2s, wdt_4s, wdt_8s
00498       * @code
00499       *    setup_watchdog(7);   // Sets the WDT to trigger every second
00500       * @endcode
00501       * @param prescalar The WDT prescaler to define how often the node will wake up. When defining sleep mode cycles, this time period is 1 cycle.
00502       */
00503     void setup_watchdog(uint8_t prescalar);
00504 
00505     /**
00506     * @note: This value is automatically assigned based on the node address
00507     * to reduce errors and increase throughput of the network.
00508     *
00509     * Sets the timeout period for individual payloads in milliseconds at staggered intervals.
00510     * Payloads will be retried automatically until success or timeout
00511     * Set to 0 to use the normal auto retry period defined by radio.setRetries()
00512     *
00513     */
00514 
00515     uint32_t txTimeout; /**< Network timeout value */
00516 
00517     /**
00518      * This only affects payloads that are routed by one or more nodes.
00519      * This specifies how long to wait for an ack from across the network.
00520      * Radios sending directly to their parent or children nodes do not
00521      * utilize this value.
00522      */
00523 
00524     uint16_t routeTimeout; /**< Timeout for routed payloads */
00525 
00526 
00527     /**@}*/
00528     /**
00529      * @name Advanced Operation
00530      *
00531      *  For advanced operation of the network
00532      */
00533     /**@{*/
00534 
00535     /**
00536      * Return the number of failures and successes for all transmitted payloads, routed or sent directly
00537      * @note This needs to be enabled via #define ENABLE_NETWORK_STATS in RF24Network_config.h
00538      *
00539      *   @code
00540      * bool fails, success;
00541      * network.failures(&fails,&success);
00542      * @endcode
00543      *
00544      */
00545     void failures(uint32_t *_fails, uint32_t *_ok);
00546 
00547 #if defined (RF24NetworkMulticast)
00548 
00549     /**
00550      * Send a multicast message to multiple nodes at once
00551      * Allows messages to be rapidly broadcast through the network
00552      *
00553      * Multicasting is arranged in levels, with all nodes on the same level listening to the same address
00554      * Levels are assigned by network level ie: nodes 01-05: Level 1, nodes 011-055: Level 2
00555      * @see multicastLevel
00556      * @see multicastRelay
00557      * @param message Pointer to memory where the message is located
00558      * @param len The size of the message
00559      * @param level Multicast level to broadcast to
00560      * @return Whether the message was successfully sent
00561      */
00562 
00563     bool multicast(RF24NetworkHeader& header,const void* message, uint16_t len, uint8_t level);
00564 
00565 
00566 #endif
00567 
00568     /**
00569     * Writes a direct (unicast) payload. This allows routing or sending messages outside of the usual routing paths.
00570     * The same as write, but a physical address is specified as the last option.
00571     * The payload will be written to the physical address, and routed as necessary by the recipient
00572     */
00573     bool write(RF24NetworkHeader& header,const void* message, uint16_t len, uint16_t writeDirect);
00574 
00575     /**
00576     * Sleep this node - For AVR devices only
00577     * @note NEW - Nodes can now be slept while the radio is not actively transmitting. This must be manually enabled by uncommenting
00578     * the #define ENABLE_SLEEP_MODE in RF24Network_config.h
00579     * @note Setting the interruptPin to 255 will disable interrupt wake-ups
00580     * @note The watchdog timer should be configured in setup() if using sleep mode.
00581     * This function will sleep the node, with the radio still active in receive mode.
00582     *
00583     * The node can be awoken in two ways, both of which can be enabled simultaneously:
00584     * 1. An interrupt - usually triggered by the radio receiving a payload. Must use pin 2 (interrupt 0) or 3 (interrupt 1) on Uno, Nano, etc.
00585     * 2. The watchdog timer waking the MCU after a designated period of time, can also be used instead of delays to control transmission intervals.
00586     * @code
00587     * if(!network.available()){ network.sleepNode(1,0); }  //Sleeps the node for 1 second or a payload is received
00588     *
00589     * Other options:
00590     * network.sleepNode(0,0);         // Sleep this node for the designated time period, or a payload is received.
00591     * network.sleepNode(1,255);       // Sleep this node for 1 cycle. Do not wake up until then, even if a payload is received ( no interrupt )
00592     * @endcode
00593     * @see setup_watchdog()
00594     * @param cycles: The node will sleep in cycles of 1s. Using 2 will sleep 2 WDT cycles, 3 sleeps 3WDT cycles...
00595     * @param interruptPin: The interrupt number to use (0,1) for pins two and three on Uno,Nano. More available on Mega etc.
00596     * @return True if sleepNode completed normally, after the specified number of cycles. False if sleep was interrupted
00597     */
00598     bool sleepNode( unsigned int cycles, int interruptPin );
00599 
00600 
00601     /**
00602      * This node's parent address
00603      *
00604      * @return This node's parent address, or -1 if this is the base
00605      */
00606     int16_t parent() const;
00607 
00608     /**
00609     * Provided a node address and a pipe number, will return the RF24Network address of that child pipe for that node
00610     */
00611     uint16_t addressOfPipe( uint16_t node,uint8_t pipeNo );
00612 
00613     /**
00614      * @note Addresses are specified in octal: 011, 034
00615      * @return True if a supplied address is valid
00616      */
00617     bool is_valid_address ( uint16_t node );
00618 
00619     /**@}*/
00620     /**
00621      * @name Deprecated
00622      *
00623      *  Maintained for backwards compatibility
00624      */
00625     /**@{*/
00626 
00627     /**
00628      * Bring up the network on a specific radio frequency/channel.
00629      * @note Use radio.setChannel() to configure the radio channel
00630      *
00631      * **Example 1:** Begin on channel 90 with address 0 (master node)
00632      * @code
00633      * network.begin(90,0);
00634      * @endcode
00635      * **Example 2:** Begin on channel 90 with address 01 (child of master)
00636      * @code
00637      * network.begin(90,01);
00638      * @endcode
00639      * **Example 3:** Begin on channel 90 with address 011 (child of 01, grandchild of master)
00640      * @code
00641      * network.begin(90,011);
00642      * @endcode
00643      *
00644      * @param _channel The RF channel to operate on
00645      * @param _node_address The logical address of this node
00646      *
00647      */
00648     void begin(uint8_t _channel, uint16_t _node_address );
00649 
00650     /**@}*/
00651     /**
00652      * @name External Applications/Systems
00653      *
00654      *  Interface for External Applications and Systems ( RF24Mesh, RF24Ethernet )
00655      */
00656     /**@{*/
00657 
00658     /** The raw system frame buffer of received data. */
00659 
00660     uint8_t frame_buffer[MAX_FRAME_SIZE];
00661 
00662     /**
00663      * **Linux** <br>
00664      * Data with a header type of EXTERNAL_DATA_TYPE will be loaded into a separate queue.
00665      * The data can be accessed as follows:
00666      * @code
00667      * RF24NetworkFrame f;
00668      * while(network.external_queue.size() > 0){
00669      *   f = network.external_queue.front();
00670      *   uint16_t dataSize = f.message_size;
00671      *   //read the frame message buffer
00672      *   memcpy(&myBuffer,&f.message_buffer,dataSize);
00673      *   network.external_queue.pop();
00674      * }
00675      * @endcode
00676      */
00677 
00678 
00679 #if !defined ( DISABLE_FRAGMENTATION )
00680     /**
00681     * **ARDUINO** <br>
00682     * The frag_ptr is only used with Arduino (not RPi/Linux) and is mainly used for external data systems like RF24Ethernet. When
00683     * an EXTERNAL_DATA payload type is received, and returned from network.update(), the frag_ptr will always point to the starting
00684     * memory location of the received frame. <br>This is used by external data systems (RF24Ethernet) to immediately copy the received
00685     * data to a buffer, without using the user-cache.
00686     *
00687     * @see RF24NetworkFrame
00688     *
00689     * @code
00690     * uint8_t return_type = network.update();
00691     * if(return_type == EXTERNAL_DATA_TYPE){
00692     *     uint16_t size = network.frag_ptr->message_size;
00693     *     memcpy(&myDataBuffer,network.frag_ptr->message_buffer,network.frag_ptr->message_size);
00694     * }
00695     * @endcode
00696     * Linux devices (defined as RF24_LINUX) currently cache all payload types, and do not utilize frag_ptr.
00697     */
00698     RF24NetworkFrame* frag_ptr;
00699 #endif
00700 
00701     /**
00702     * Variable to determine whether update() will return after the radio buffers have been emptied (DEFAULT), or
00703     * whether to return immediately when (most) system types are received.
00704     *
00705     * As an example, this is used with RF24Mesh to catch and handle system messages without loading them into the user cache.
00706     *
00707     * The following reserved/system message types are handled automatically, and not returned.
00708     *
00709     * | System Message Types <br> (Not Returned) |
00710     * |-----------------------|
00711     * | NETWORK_ADDR_RESPONSE |
00712     * | NETWORK_ACK           |
00713     * | NETWORK_PING          |
00714     * | NETWORK_POLL <br>(With multicast enabled) |
00715     * | NETWORK_REQ_ADDRESS   |
00716     *
00717     */
00718     bool returnSysMsgs;
00719 
00720     /**
00721     * Network Flags allow control of data flow
00722     *
00723     * Incoming Blocking: If the network user-cache is full, lets radio cache fill up. Radio ACKs are not sent when radio internal cache is full.<br>
00724     * This behaviour may seem to result in more failed sends, but the payloads would have otherwise been dropped due to the cache being full.<br>
00725     *
00726     * | FLAGS | Value | Description |
00727     * |-------|-------|-------------|
00728     * |FLAG_HOLD_INCOMING| 1(bit_1) | INTERNAL: Set automatically when a fragmented payload will exceed the available cache |
00729     * |FLAG_BYPASS_HOLDS| 2(bit_2) | EXTERNAL: Can be used to prevent holds from blocking. Note: Holds are disabled & re-enabled by RF24Mesh when renewing addresses. This will cause data loss if incoming data exceeds the available cache space|
00730     * |FLAG_FAST_FRAG| 4(bit_3) | INTERNAL: Replaces the fastFragTransfer variable, and allows for faster transfers between directly connected nodes. |
00731     *
00732     */
00733     uint8_t networkFlags;
00734 
00735 private:
00736 
00737     uint32_t txTime;
00738 
00739     bool write(uint16_t, uint8_t directTo);
00740     bool write_to_pipe( uint16_t node, uint8_t pipe, bool multicast );
00741     uint8_t enqueue(RF24NetworkHeader *header);
00742 
00743     bool is_direct_child( uint16_t node );
00744     bool is_descendant( uint16_t node );
00745 
00746     uint16_t direct_child_route_to( uint16_t node );
00747     //uint8_t pipe_to_descendant( uint16_t node );
00748     void setup_address(void);
00749     bool _write(RF24NetworkHeader& header,const void* message, uint16_t len, uint16_t writeDirect);
00750 
00751     struct logicalToPhysicalStruct {
00752         uint16_t send_node;
00753         uint8_t send_pipe;
00754         bool multicast;
00755     };
00756 
00757     bool logicalToPhysicalAddress(logicalToPhysicalStruct *conversionInfo);
00758 
00759 
00760     RF24& radio; /**< Underlying radio driver, provides link/physical layers */
00761 #if defined (DUAL_HEAD_RADIO)
00762     RF24& radio1;
00763 #endif
00764 #if defined (RF24NetworkMulticast)
00765     uint8_t multicast_level;
00766 #endif
00767     uint16_t node_address; /**< Logical node address of this unit, 1 .. UINT_MAX */
00768     //const static int frame_size = 32; /**< How large is each frame over the air */
00769     uint8_t frame_size;
00770     const static unsigned int max_frame_payload_size = MAX_FRAME_SIZE-sizeof(RF24NetworkHeader);
00771 
00772 
00773 #if !defined (NUM_USER_PAYLOADS)
00774 #define NUM_USER_PAYLOADS 5
00775 #endif
00776 
00777 #if defined (DISABLE_USER_PAYLOADS)
00778     uint8_t frame_queue[1]; /**< Space for a small set of frames that need to be delivered to the app layer */
00779 #else
00780     uint8_t frame_queue[MAIN_BUFFER_SIZE]; /**< Space for a small set of frames that need to be delivered to the app layer */
00781 #endif
00782 
00783     uint8_t* next_frame; /**< Pointer into the @p frame_queue where we should place the next received frame */
00784 
00785 #if !defined ( DISABLE_FRAGMENTATION )
00786     RF24NetworkFrame frag_queue;
00787     uint8_t frag_queue_message_buffer[MAX_PAYLOAD_SIZE]; //frame size + 1
00788 #endif
00789 
00790     //uint8_t frag_queue[MAX_PAYLOAD_SIZE + 11];
00791     //RF24NetworkFrame frag_queue;
00792 
00793     uint16_t parent_node; /**< Our parent's node address */
00794     uint8_t parent_pipe; /**< The pipe our parent uses to listen to us */
00795     uint16_t node_mask; /**< The bits which contain signfificant node address information */
00796 
00797 #if defined ENABLE_NETWORK_STATS
00798     static uint32_t nFails;
00799     static uint32_t nOK;
00800 #endif
00801 
00802 public:
00803 
00804 
00805 
00806 };
00807 
00808 /**
00809  * @example helloworld_tx.ino
00810  *
00811  * Simplest possible example of using RF24Network.  Put this sketch
00812  * on one node, and helloworld_rx.pde on the other.  Tx will send
00813  * Rx a nice message every 2 seconds which rx will print out for us.
00814  */
00815 
00816 /**
00817  * @example helloworld_rx.ino
00818  *
00819  * Simplest possible example of using RF24Network.  Put this sketch
00820  * on one node, and helloworld_tx.pde on the other.  Tx will send
00821  * Rx a nice message every 2 seconds which rx will print out for us.
00822  */
00823 
00824 /**
00825  * @example Network_Ping.ino
00826  *
00827  * Example to give users an understanding of addressing and topology in the mesh network
00828  * Using this sketch, each node will send a ping to the base every
00829  * few seconds.  The RF24Network library will route the message across
00830  * the mesh to the correct node.
00831  *
00832  */
00833 
00834 /**
00835  * @example Network_Ping_Sleep.ino
00836  *
00837  * Example: This is almost exactly the same as the Network_Ping example, but with use
00838  * of the integrated sleep mode.
00839  *
00840  * This example demonstrates how nodes on the network utilize sleep mode to conserve power. For example,
00841  * the radio itself will draw about 13.5mA in receive mode. In sleep mode, it will use as little as 22ua (.000022mA)
00842  * of power when not actively transmitting or receiving data. In addition, the Arduino is powered down as well,
00843  * dropping network power consumption dramatically compared to previous capabilities. <br>
00844  * Note: Sleeping nodes generate traffic that will wake other nodes up. This may be mitigated with further modifications. Sleep
00845  * payloads are currently always routed to the master node, which will wake up intermediary nodes. Routing nodes can be configured
00846  * to go back to sleep immediately.
00847  * The displayed millis() count will give an indication of how much a node has been sleeping compared to the others, as millis() will
00848  * not increment while a node sleeps.
00849  *<br>
00850  * - Using this sketch, each node will send a ping to every other node in the network every few seconds.<br>
00851  * - The RF24Network library will route the message across the mesh to the correct node.<br>
00852  *
00853  */
00854 
00855 /**
00856  * @example sensornet.pde
00857  *
00858  * Example of a sensor network.
00859  * This sketch demonstrates how to use the RF24Network library to
00860  * manage a set of low-power sensor nodes which mostly sleep but
00861  * awake regularly to send readings to the base.
00862  */
00863 /**
00864  * @mainpage Network Layer for RF24 Radios
00865  *
00866  * This class implements an <a href="http://en.wikipedia.org/wiki/Network_layer">OSI Network Layer</a> using nRF24L01(+) radios driven
00867  * by the newly optimized <a href="http://tmrh20.github.com/RF24/">RF24</a> library fork.
00868  *
00869  * @section Purpose Purpose/Goal
00870  *
00871  * Original: Create an alternative to ZigBee radios for Arduino communication.
00872  *
00873  * New: Enhance the current functionality for maximum efficiency, reliability, and speed
00874  *
00875  * Xbees are excellent little radios, backed up by a mature and robust standard
00876  * protocol stack.  They are also expensive.
00877  *
00878  * For many Arduino uses, they seem like overkill.  So I am working to improve the current
00879  * standard for nRF24L01 radios.  The best RF24 modules are available for less than
00880  * $6 from many sources.  With the RF24Network layer, I hope to cover many
00881  * common communication scenarios.
00882  *
00883  * Please see the @ref Zigbee page for a comparison against the ZigBee protocols
00884  *
00885  * @section Features Features
00886  *
00887  * <b>Whats new? </b><br>
00888  *  @li New: (Dec 8) Merge of RPi and Arduino code. Finally moving closer to a stable release.  Report issues at https://github.com/TMRh20/RF24Network/issues
00889  *  @li New functionality: (Dec 8) Support for fragmented multicast payloads on both RPi and Arduino
00890  *  @li New functionality: (Nov 24) Fragmentation & reassembly supported on both RPi and Arduino
00891  *  @li Note: structure of network frames is changed, these are only used by external applications like RF24Ethernet and RF24toTUN, and for fragmentation
00892  *  @li New functionality: User message types 1 through 64 will not receive a network ack
00893  *
00894  * The layer provides:
00895  * @li <b>New</b> (2014): Network ACKs: Efficient acknowledgement of network-wide transmissions, via dynamic radio acks and network protocol acks.
00896  * @li <b>New</b> (2014): Updated addressing standard for optimal radio transmission.
00897  * @li <b>New</b> (2014): Extended timeouts and staggered timeout intervals. The new txTimeout variable allows fully automated extended timeout periods via auto-retry/auto-reUse of payloads.
00898  * @li <b>New</b> (2014): Optimization to the core library provides improvements to reliability, speed and efficiency. See https://tmrh20.github.io/RF24 for more info.
00899  * @li <b>New</b> (2014): Built in sleep mode using interrupts. (Still under development. (Enable via RF24Network_config.h))
00900   * @li <b>New</b> (2014): Dual headed operation: The use of dual radios for busy routing nodes or the master node enhances throughput and decreases errors. See the <a href="Tuning.html">Tuning</a> section.
00901  * @li Host Addressing.  Each node has a logical address on the local network.
00902  * @li Message Forwarding.  Messages can be sent from one node to any other, and
00903  * this layer will get them there no matter how many hops it takes.
00904  * @li Ad-hoc Joining.  A node can join a network without any changes to any
00905  * existing nodes.
00906  *
00907  * The layer does not provide:
00908  * @li Dynamic address assignment. (See RF24Mesh)
00909  * @li Layer 4 protocols (TCP/IP - See RF24Ethernet and RF24toTUN)
00910  *
00911  * @section More How to learn more
00912  *
00913  * @li <a href="classRF24Network.html">RF24Network Class Documentation</a>
00914  * @li <a href="AdvancedConfig.html"> Advanced Configuration Options</a>
00915  * @li <a href="Addressing.html"> Addressing format</a>
00916  * @li <a href="Tuning.html"> Topology and Overview</a>
00917  * @li <a href="https://github.com/TMRh20/RF24Network/archive/Development.zip">Download Current Development Package</a>
00918  * @li <a href="examples.html">Examples Page</a>.  Start with <a href="helloworld_rx_8ino-example.html">helloworld_rx</a> and <a href="helloworld_tx_8ino-example.html">helloworld_tx</a>.
00919  *
00920  * <b> Additional Information & Add-ons </b>
00921  * @li <a href="https://github.com/TMRh20/RF24Mesh">RF24Mesh: Dynamic Mesh Layer for RF24Network Dev</a>
00922  * @li <a href="https://github.com/TMRh20/RF24Ethernet">RF24Ethernet: TCP/IP over RF24Network</a>
00923  * @li <a href="http://tmrh20.blogspot.com/2014/03/high-speed-data-transfers-and-wireless.html">My Blog: RF24 Optimization Overview</a>
00924  * @li <a href="http://tmrh20.blogspot.com/2014/03/arduino-radiointercomwireless-audio.html">My Blog: RF24 Wireless Audio</a>
00925  * @li <a href="http://maniacbug.github.com/RF24/">RF24: Original Author</a>
00926  * @section Topology Topology for Mesh Networks using nRF24L01(+)
00927  *
00928  * This network layer takes advantage of the fundamental capability of the nRF24L01(+) radio to
00929  * listen actively to up to 6 other radios at once.  The network is arranged in a
00930  * <a href="http://en.wikipedia.org/wiki/Network_Topology#Tree">Tree Topology</a>, where
00931  * one node is the base, and all other nodes are children either of that node, or of another.
00932  * Unlike a true mesh network, multiple nodes are not connected together, so there is only one
00933  * path to any given node.
00934  *
00935  * @section Octal Octal Addressing and Topology
00936  *
00937  * Each node must be assigned an 15-bit address by the administrator.  This address exactly
00938  * describes the position of the node within the tree.  The address is an octal number.  Each
00939  * digit in the address represents a position in the tree further from the base.
00940  *
00941  * @li Node 00 is the base node.
00942  * @li Nodes 01-05 are nodes whose parent is the base.
00943  * @li Node 021 is the second child of node 01.
00944  * @li Node 0321 is the third child of node 021, an so on.
00945  * @li The largest node address is 05555, so 3,125 nodes are allowed on a single channel.
00946  * An example topology is shown below, with 5 nodes in direct communication with the master node,
00947  * and multiple leaf nodes spread out at a distance, using intermediate nodes to reach other nodes.
00948  *
00949  *|   |    | 00 |    |    | 00 |    |    |    | Master Node (00)                                    |
00950  *|---|----|----|----|----|----|----|----|----|-----------------------------------------------------|
00951  *|   |    | 01 |    |    | 04 |    |    |    | 1st level children of master (00)                   |
00952  *|   | 011|    | 021|    |    |014 |    |    | 2nd level children of master. Children of 1st level.|
00953  *|111|    |    | 121| 221|    |    | 114|    | 3rd level children of master. Children of 2nd level.|
00954  *|   |    |    |    |1221|    |1114|2114|3114| 4th level children of master. Children of 3rd level.|
00955  *
00956  * @section Routing How routing is handled
00957  *
00958  * When sending a message using RF24Network::write(), you fill in the header with the logical
00959  * node address.  The network layer figures out the right path to find that node, and sends
00960  * it through the system until it gets to the right place.  This works even if the two nodes
00961  * are far separated, as it will send the message down to the base node, and then back out
00962  * to the final destination.
00963  *
00964  * All of this work is handled by the RF24Network::update() method, so be sure to call it
00965  * regularly or your network will miss packets.
00966  *
00967  * @section Startup Starting up a node
00968  *
00969  * When a node starts up, it only has to contact its parent to establish communication.
00970  * No direct connection to the Base node is needed.  This is useful in situations where
00971  * relay nodes are being used to bridge the distance to the base, so leaf nodes are out
00972  * of range of the base.
00973  *
00974  * @section Directionality Directionality
00975  *
00976  * By default all nodes are always listening, so messages will quickly reach
00977  * their destination.
00978  *
00979  * You may choose to sleep any nodes on the network if using interrupts. This is useful in a
00980  * case where the nodes are operating on batteries and need to sleep. This greatly decreases
00981  * the power requirements for a sensor network. The leaf nodes can sleep most of the time,
00982  * and wake every few minutes to send in a reading. Routing nodes can be triggered to wake up
00983  * whenever a payload is received See sleepNode() in the class documentation, and RFNetwork_config.h
00984  * to enable sleep mode.
00985  *
00986  *
00987  * @page Addressing Addressing Format: Understanding Addressing and Topology
00988  * An overview of addressing in RF24Network
00989  *
00990  * @section Overview Overview
00991  * The nrf24 radio modules typically use a 40-bit address format, requiring 5-bytes of storage space per address, and allowing a wide
00992  * array of addresses to be utilized. In addition, the radios are limited to direct communication with 6 other nodes while using the
00993  * Enhanced-Shock-Burst (ESB) functionality of the radios.
00994  *
00995  * RF24Network uses a simple method of data compression to store the addresses using only 2 bytes, in a format designed to represent the
00996  * network topology in an intuitive way.
00997  * See the <a href="Tuning.html"> Topology and Overview</a> page for more info regarding topology.
00998  *
00999  * @section Octal_Binary Decimal, Octal and Binary formats
01000  *
01001  * Say we want to designate a logical address to a node, using a tree topology as defined by the manufacturer.
01002  * In the simplest format, we could assign the first node the address of 1, the second 2 and so on.
01003  * Since a single node can only connect to 6 other nodes (1 parent and 5 children) subnets need to be created if using more than 6 nodes.<br>
01004  * In this case the children of node 1 could simply be designated as 11,21,31,41, and 51<br>
01005  * Children of node 2 could be designated as 12,22,32,42, and 52
01006  *
01007  * The above example is exactly how RF24Network manages the addresses, but they are represented in Octal format.
01008  *
01009  * <b>Decimal, Octal and Binary</b>
01010  * <table>
01011  * <tr bgcolor="#a3b4d7" >
01012  * <td> Decimal </td> <td> Binary </td><td> Decimal </td> <td> Binary </td><td> Decimal </td> <td> Binary </td>
01013  * </tr><tr>
01014  * <td> 1 </td> <td> 00000001 </td><td> 11 </td> <td> 00001011 </td><td> 111 </td> <td> 01101111 </td>
01015  * </tr><tr bgcolor="#a3b4d7" >
01016  * <td> Octal </td> <td> Binary </td><td> Octal </td> <td> Binary </td><td> Octal </td> <td> Binary </td>
01017  * </tr><tr>
01018  * <td> 1 </td> <td> 00000001 </td><td> 011 </td> <td> 00001001 </td><td> 0111 </td> <td> 1001001 </td>
01019  * </tr>
01020  * </table>
01021  *
01022  *
01023  * Since the numbers 0-7 can be represented in exactly three bits, each digit is represented by exactly 3 bits when viewed in octal format.
01024  * This allows a very simple method of managing addresses via masking and bit shifting.
01025  *
01026  * @section DisplayAddresses Displaying Addresses
01027  *
01028  * When using Arduino devices, octal addresses can be printed in the following manner:
01029  * @code
01030  * uint16_t address = 0111;
01031  * Serial.println(address,OCT);
01032  * @endcode
01033  *
01034  * Printf can also be used, if enabled, or if using linux/RPi
01035  * @code
01036  * uint16_t address = 0111;
01037  * printf("0%o\n",address);
01038  * @endcode
01039  *
01040  * See http://www.cplusplus.com/doc/hex/ for more information<br>
01041  * See the <a href="Tuning.html"> Topology and Overview</a> page for more info regarding topology.
01042  *
01043  * @page AdvancedConfig Advanced Configuration
01044  *
01045  * RF24Network offers many features, some of which can be configured by editing the RF24Network_config.h file
01046  *
01047  * | Configuration Option | Description |
01048  * |----------------------|-------------|
01049  * |<b> #define RF24NetworkMulticast </b> | This option allows nodes to send and receive multicast payloads. Nodes with multicast enabled can also be configured to relay multicast payloads on to further multicast levels. See multicastRelay |
01050  * | <b> #define DISABLE_FRAGMENTATION </b> | Fragmentation is enabled by default, and uses an additional 144 bytes of memory. |
01051  * | <b> #define MAX_PAYLOAD_SIZE 144 </b> | The maximum size of payloads defaults to 144 bytes. If used with RF24toTUN and two Raspberry Pi, set this to 1514 (TAP) or 1500 (TUN) |
01052  * | <b> #define NUM_USER_PAYLOADS 5 </b> | This is the number of 24-byte payloads the network layer will cache for the user. If using fragmentation, this number * 24 must be larger than MAX_PAYLOAD_SIZE |
01053  * | <b> #define DISABLE_USER_PAYLOADS </b> | This option will disable user-caching of payloads entirely. Use with RF24Ethernet to reduce memory usage. (TCP/IP is an external data type, and not cached) |
01054  * | <b> #define ENABLE_SLEEP_MODE </b> | Uncomment this option to enable sleep mode for AVR devices. (ATTiny,Uno, etc) |
01055  * | <b> #define DUAL_HEAD_RADIO </b> | Uncomment this option to enable use of dual radios |
01056  * | **#define ENABLE_NETWORK_STATS** | Enable counting of all successful or failed transmissions, routed or sent directly |
01057  *
01058  ** @page Tuning Performance and Data Loss: Tuning the Network
01059  * Tips and examples for tuning the network and general operation.
01060  *
01061  *  <img src="tmrh20/topologyImage.jpg" alt="Topology" height="75%" width="75%">
01062  *
01063  * @section General Understanding Radio Communication and Topology
01064  * When a transmission takes place from one radio module to another, the receiving radio will communicate
01065  * back to the sender with an acknowledgement (ACK) packet, to indicate success. If the sender does not
01066  * receive an ACK, the radio automatically engages in a series of timed retries, at set intervals. The
01067  * radios use techniques like addressing and numbering of payloads to manage this, but it is all done
01068  * automatically by the nrf chip, out of sight from the user.
01069  *
01070  * When working over a radio network, some of these automated techniques can actually hinder data transmission to a degree.
01071  * Retrying failed payloads over and over on a radio network can hinder communication for nearby nodes, or
01072  * reduce throughput and errors on routing nodes.
01073  *
01074  * Radios in this network are linked by <b>addresses</b> assigned to <b>pipes</b>. Each radio can listen
01075  * to 6 addresses on 6 pipes, therefore each radio has a parent pipe and 5 child pipes, which are used
01076  * to form a tree structure. Nodes communicate directly with their parent and children nodes. Any other
01077  * traffic to or from a node must be routed through the network.
01078  *
01079  * @section Topology Topology of RF24Network
01080  *
01081  * Anybody who is familiar at all with IP networking should be able to easily understand RF24Network topology. The
01082  * master node can be seen as the gateway, with up to 4 directly connected nodes. Each of those nodes creates a
01083  * subnet below it, with up to 4 additional child nodes. The numbering scheme can also be related to IP addresses,
01084  * for purposes of understanding the topology via subnetting. Nodes can have 5 children if multicast is disabled.
01085  *
01086  * Expressing RF24Network addresses in IP format:
01087  *
01088  * As an example, we could designate the master node in theory, as Address 10.10.10.10 <br>
01089  * The children nodes of the master would be 10.10.10.1, 10.10.10.2, 10.10.10.3, 10.10.10.4 and 10.10.10.5 <br>
01090  * The children nodes of 10.10.10.1 would be 10.10.1.1, 10.10.2.1, 10.10.3.1, 10.10.4.1 and 10.10.5.1 <br>
01091  *
01092  * In RF24Network, the master is just 00  <br>
01093  * Children of master are 01,02,03,04,05  <br>
01094  * Children of 01 are 011,021,031,041,051  <br>
01095  *
01096  * @section Network Routing
01097  *
01098  * Routing of traffic is handled invisibly to the user, by the network layer. If the network addresses are
01099  * assigned in accordance with the physical layout of the network, nodes will route traffic automatically
01100  * as required. Users simply constuct a header containing the appropriate destination address, and the network
01101  * will forward it through to the correct node. Individual nodes only route individual fragments, so if using
01102  * fragmentation, routing nodes do not need it enabled, unless sending or receiving fragmented payloads themselves.
01103  *
01104  * If routing data between parent and child nodes (marked by direct links on the topology image above) the network
01105  * uses built-in acknowledgement and retry functions of the chip to prevent data loss. When payloads are sent to
01106  * other nodes, they need to be routed. Routing is managed using a combination of built in ACK requests, and
01107  * software driven network ACKs. This allows all routing nodes to forward data very quickly, with only the final
01108  * routing node confirming delivery and sending back an
01109  * acknowledgement.
01110  *
01111  * Example: Node 00 sends to node 01. The nodes will use the built in auto-retry and auto-ack functions.<br>
01112  * Example: Node 00 sends to node 011. Node 00 will send to node 01 as before. Node 01 will forward the message to
01113  * 011. If delivery was successful, node 01 will also forward a message back to node 00, indicating success.
01114  *
01115  * Old Functionality: Node 00 sends to node 011 using auto-ack. Node 00 first sends to 01, 01 acknowledges.
01116  * Node 01 forwards the payload to 011 using auto-ack. If the payload fails between 01 and 011, node 00 has
01117  * no way of knowing.
01118  *
01119  * @note When retrying failed payloads that have been routed, there is a chance of duplicate payloads if the network-ack
01120  * is not successful. In this case, it is left up to the user to manage retries and filtering of duplicate payloads.
01121  *
01122  * Acknowledgements can and should be managed by the application or user. If requesting a response from another node,
01123  * an acknowledgement is not required, so a user defined type of 0-64 should be used, to prevent the network from
01124  * responding with an acknowledgement. If not requesting a response, and wanting to know if the payload was successful
01125  * or not, users can utilize header types 65-127.
01126  *
01127  * @section TuningOverview Tuning Overview
01128  * The RF24 radio modules are generally only capable of either sending or receiving data at any given
01129  * time, but have built-in auto-retry mechanisms to prevent the loss of data. These values are adjusted
01130  * automatically by the library on startup, but can be further adjusted to reduce data loss, and
01131  * thus increase throughput of the network. This page is intended to provide a general overview of its
01132  * operation within the context of the network library, and provide guidance for adjusting these values.
01133  *
01134  * @section RetryTiming Auto-Retry Timing
01135  *
01136  * The core radio library provides the functionality of adjusting the internal auto-retry interval of the
01137  * radio modules. In the network configuration, the radios can be set to automatically retry failed
01138  * transmissions at intervals ranging anywhere from 500us (.5ms) up to 4000us (4ms). When operating any
01139  * number of radios larger than two, it is important to stagger the assigned intervals, to prevent the
01140  * radios from interfering with each other at the radio frequency (RF) layer.
01141  *
01142  * The library should provide fairly good working values, as it simply staggers the assigned values within
01143  * groups of radios in direct communication. This value can be set manually by calling radio.setRetries(X,15);
01144  * and adjusting the value of X from 1 to 15 (steps of 250us).
01145  *
01146  * @section AutoRetry Auto-Retry Count and Extended Timeouts
01147  *
01148  * The core radio library also provides the ability to adjust the internal auto-retry count of the radio
01149  * modules. The default setting is 15 automatic retries per payload, and can be extended by configuring
01150  * the network.txTimeout variable. This default retry count should generally be left at 15, as per the
01151  * example in the above section. An interval/retry setting of (15,15) will provide 15 retrys at intervals of
01152  * 4ms, taking up to 60ms per payload. The library now provides staggered timeout periods by default, but
01153  * they can also be adjusted on a per-node basis.
01154  *
01155  * The txTimeout variable is used to extend the retry count to a defined duration in milliseconds. See the
01156  * network.txTimeout variable. Timeout periods of extended duration (500+) will generally not help when payloads
01157  * are failing due to data collisions, it will only extend the duration of the errors. Extended duration timeouts
01158  * should generally only be configured on leaf nodes that do not receive data, or on a dual-headed node.
01159  *
01160  * @section Examples
01161  *
01162  * <b>Example 1:</b> Network with master node and three leaf nodes that send data to the master node. None of the leaf
01163  * nodes need to receive data.
01164  *
01165  * a: Master node uses default configuration<br>
01166  * b: Leaf nodes can be configured with extended timeout periods to ensure reception by the master.<br>
01167  * c:
01168  * @code
01169  * Leaf 01: network.txTimeout = 500;   Leaf 02: network.txTimeout = 573;  Leaf 03: network.txTimeout = 653;
01170  * @endcode
01171  * This configuration will provide a reduction in errors, as the timeouts have been extended, and are staggered
01172  * between devices.
01173  *
01174  *
01175  * <b>Example 2:</b> Network with master node and three leaf nodes that send data to the master node. The second leaf
01176  * node needs to receive configuration data from the master at set intervals of 1 second, and send data back to the
01177  * master node. The other leaf nodes will send basic sensor information every few seconds, and a few dropped payloads
01178  * will not affect the operation greatly.
01179  *
01180  * a: Master node configured with extended timeouts of .5 seconds, and increased retry delay:
01181  *   @code
01182  *      radio.setRetries(11,15);
01183  *      network.txTimeout = 500;
01184  *   @endcode
01185  * b: Second leaf node configured with a similar timeout period and retry delay:
01186  * @code
01187  *      radio.setRetries(8,15);
01188  *      network.txTimeout = 553;
01189  * @endcode
01190  * c: First and third leaf nodes configured with default timeout periods or slightly increased timout periods.
01191  *
01192  * @section DualHead Dual Headed Operation
01193  *
01194  * The library now supports a dual radio configuration to further enhance network performance, while reducing errors on
01195  * busy networks. Master nodes or relay nodes with a large number of child nodes can benefit somewhat from a dual headed
01196  * configuration, since one radio is used for receiving, and the other entirely for transmission.
01197  *
01198  * To configure a dual headed node:
01199  * 1. Edit the RF24Network_config.h file, and uncomment #define DUAL_HEAD_RADIO
01200  * 2. Connect another radio, using the same MOSI, MISO, and SCK lines.
01201  * 3. Choose another two pins to use for CE and CS on the second radio. Connect them.
01202  * 4. Setup the radio and network like so:
01203  *
01204  * @code
01205  *  RF24 radio(7,8);            // Using CE (7) and CS (8) for first radio
01206  *  RF24 radio1(4,5);           // Using CE (4) and CS (5) for second radio
01207  *  RF24Network network(radio,radio1);  // Set up the network using both radios
01208  *
01209  *  Then in setup(), call radio.begin(); and radio1.begin(); before network.begin();
01210  * @endcode
01211  *
01212  * 5. Upload to MCU. The node will now use the first radio to receive data, and radio1 to transmit, preventing data loss on a busy network.
01213  * 6. Re-comment the #define in the config file as required if configuring other single-headed radios.
01214  *
01215  *
01216  * Any node can be configured in dual-head mode.
01217  *
01218  *
01219  *
01220  *
01221  * @page Zigbee Comparison to ZigBee
01222  *
01223  * This network layer is influenced by the design of ZigBee, but does not implement it
01224  * directly.
01225  *
01226  * @section Advantage Which is better?
01227  *
01228  * ZigBee is a much more robust, feature-rich set of protocols, with many different vendors
01229  * providing compatible chips.
01230  *
01231  * RF24Network is cheap.  While ZigBee radios are well over $20, nRF24L01 modules can be found
01232  * for under $2.  My personal favorite is
01233  * <a href="http://www.mdfly.com/index.php?main_page=product_info&products_id=82">MDFly RF-IS2401</a>.
01234  *
01235  * @section Contrast Similiarities & Differences
01236  *
01237  * Here are some comparisons between RF24Network and ZigBee.
01238  *
01239  * @li Both networks support Star and Tree topologies.  Only Zigbee supports a true mesh.
01240  * @li In ZigBee networks, only leaf nodes can sleep
01241  * @li ZigBee nodes are configured using AT commands, or a separate Windows application.
01242  * RF24 nodes are configured by recompiliing the firmware or writing to EEPROM.
01243  *
01244  * @section NodeNames Node Naming
01245  *
01246  * @li Leaf node: A node at the outer edge of the network with no children.  ZigBee calls it
01247  * an End Device node.
01248  * @li Relay node: A node which has both parents and children, and relays messages from one
01249  * to the other.  ZigBee calls it a Router.
01250  * @li Base node.  The top of the tree node with no parents, only children.  Typically this node
01251  * will bridge to another kind of network like Ethernet.  ZigBee calls it a Co-ordinator node.
01252  *
01253  *
01254  *
01255  *
01256  */
01257 
01258 #endif // __RF24NETWORK_H__
01259