Akash Vibhute / RF24Network

Maniacbug's RF24 arduino library ported to mbed. Tested, it works for Nucleo F411

Dependents:   RF24Network_Send RF24Network_Receive maple_chotobot_rf_motores Thesis_Verzender ... more

RF24Network.h@5:b1110d26a900, 2016-04-21 (annotated)

Committer:
akashvibhute
Date:
Thu Apr 21 04:10:31 2016 +0000
Revision:
5:b1110d26a900
Parent:
4:75c5aa56411f 
Library re-ported with all the latest and greatest stuff from Manicbug; Synced with TMRh20's RF24 library on Apr/18/2015 from https://github.com/TMRh20

Who changed what in which revision?

UserRevisionLine numberNew contents of line
akashvibhute 0:c3db0798d9aa 1 /*
akashvibhute 0:c3db0798d9aa 2 Copyright (C) 2011 James Coliz, Jr. <maniacbug@ymail.com>
akashvibhute 0:c3db0798d9aa 3
akashvibhute 0:c3db0798d9aa 4 This program is free software; you can redistribute it and/or
akashvibhute 0:c3db0798d9aa 5 modify it under the terms of the GNU General Public License
akashvibhute 0:c3db0798d9aa 6 version 2 as published by the Free Software Foundation.
akashvibhute 0:c3db0798d9aa 7 */
akashvibhute 4:75c5aa56411f 8
akashvibhute 3:dfc8da7ac18c 9 /*
akashvibhute 4:75c5aa56411f 10 * Mbed support added by Akash Vibhute <akash.roboticist@gmail.com>
akashvibhute 4:75c5aa56411f 11 * Porting completed on Nov/05/2015
akashvibhute 4:75c5aa56411f 12 *
akashvibhute 4:75c5aa56411f 13 * Updated 1: Synced with TMRh20's RF24 library on Nov/04/2015 from https://github.com/TMRh20
akashvibhute 4:75c5aa56411f 14 * Updated 2: Synced with TMRh20's RF24 library on Apr/18/2015 from https://github.com/TMRh20
akashvibhute 4:75c5aa56411f 15 *
akashvibhute 4:75c5aa56411f 16 */
akashvibhute 4:75c5aa56411f 17
akashvibhute 5:b1110d26a900 18
akashvibhute 0:c3db0798d9aa 19 #ifndef __RF24NETWORK_H__
akashvibhute 0:c3db0798d9aa 20 #define __RF24NETWORK_H__
akashvibhute 0:c3db0798d9aa 21
akashvibhute 0:c3db0798d9aa 22 /**
akashvibhute 0:c3db0798d9aa 23 * @file RF24Network.h
akashvibhute 0:c3db0798d9aa 24 *
akashvibhute 0:c3db0798d9aa 25 * Class declaration for RF24Network
akashvibhute 0:c3db0798d9aa 26 */
akashvibhute 4:75c5aa56411f 27
akashvibhute 4:75c5aa56411f 28 #include "mbed.h"
akashvibhute 0:c3db0798d9aa 29 #include <stddef.h>
akashvibhute 0:c3db0798d9aa 30 #include <stdint.h>
akashvibhute 4:75c5aa56411f 31 //#include <stdio.h>
akashvibhute 4:75c5aa56411f 32 //#include <string.h>
akashvibhute 2:a5f8e04bd02b 33 #include "RF24Network_config.h"
akashvibhute 2:a5f8e04bd02b 34
akashvibhute 4:75c5aa56411f 35
akashvibhute 4:75c5aa56411f 36
akashvibhute 4:75c5aa56411f 37 /**
akashvibhute 4:75c5aa56411f 38
akashvibhute 4:75c5aa56411f 39 */
akashvibhute 4:75c5aa56411f 40
akashvibhute 2:a5f8e04bd02b 41 /* Header types range */
akashvibhute 2:a5f8e04bd02b 42 #define MIN_USER_DEFINED_HEADER_TYPE 0
akashvibhute 2:a5f8e04bd02b 43 #define MAX_USER_DEFINED_HEADER_TYPE 127
akashvibhute 2:a5f8e04bd02b 44
akashvibhute 4:75c5aa56411f 45 /**
akashvibhute 2:a5f8e04bd02b 46
akashvibhute 2:a5f8e04bd02b 47 */
akashvibhute 4:75c5aa56411f 48
akashvibhute 2:a5f8e04bd02b 49 // ACK Response Types
akashvibhute 2:a5f8e04bd02b 50 /**
akashvibhute 2:a5f8e04bd02b 51 * **Reserved network message types**
akashvibhute 2:a5f8e04bd02b 52 *
akashvibhute 2:a5f8e04bd02b 53 * The network will determine whether to automatically acknowledge payloads based on their general type <br>
akashvibhute 4:75c5aa56411f 54 *
akashvibhute 2:a5f8e04bd02b 55 * **User types** (1-127) 1-64 will NOT be acknowledged <br>
akashvibhute 2:a5f8e04bd02b 56 * **System types** (128-255) 192 through 255 will NOT be acknowledged<br>
akashvibhute 2:a5f8e04bd02b 57 *
akashvibhute 2:a5f8e04bd02b 58 * @defgroup DEFINED_TYPES Reserved System Message Types
akashvibhute 2:a5f8e04bd02b 59 *
akashvibhute 2:a5f8e04bd02b 60 * System types can also contain message data.
akashvibhute 2:a5f8e04bd02b 61 *
akashvibhute 2:a5f8e04bd02b 62 * @{
akashvibhute 2:a5f8e04bd02b 63 */
akashvibhute 2:a5f8e04bd02b 64
akashvibhute 2:a5f8e04bd02b 65 /**
akashvibhute 2:a5f8e04bd02b 66 * A NETWORK_ADDR_RESPONSE type is utilized to manually route custom messages containing a single RF24Network address
akashvibhute 4:75c5aa56411f 67 *
akashvibhute 2:a5f8e04bd02b 68 * Used by RF24Mesh
akashvibhute 4:75c5aa56411f 69 *
akashvibhute 2:a5f8e04bd02b 70 * 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
akashvibhute 2:a5f8e04bd02b 71 * on to the proper recipient. <br>
akashvibhute 2:a5f8e04bd02b 72 * This allows nodes to forward multicast messages to the master node, receive a response, and forward it back to the requester.
akashvibhute 2:a5f8e04bd02b 73 */
akashvibhute 4:75c5aa56411f 74 #define NETWORK_ADDR_RESPONSE 128
akashvibhute 2:a5f8e04bd02b 75 //#define NETWORK_ADDR_CONFIRM 129
akashvibhute 2:a5f8e04bd02b 76
akashvibhute 2:a5f8e04bd02b 77 /**
akashvibhute 4:75c5aa56411f 78 * 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
akashvibhute 2:a5f8e04bd02b 79 * payload was successful. The time it takes to successfully send a NETWORK_PING is the round-trip-time.
akashvibhute 2:a5f8e04bd02b 80 */
akashvibhute 2:a5f8e04bd02b 81 #define NETWORK_PING 130
akashvibhute 2:a5f8e04bd02b 82
akashvibhute 2:a5f8e04bd02b 83 /**
akashvibhute 4:75c5aa56411f 84 * 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
akashvibhute 2:a5f8e04bd02b 85 * as TCP/IP frames, while still being able to utilize standard RF24Network messages etc.
akashvibhute 2:a5f8e04bd02b 86 *
akashvibhute 2:a5f8e04bd02b 87 * **Linux**
akashvibhute 4:75c5aa56411f 88 * Linux devices (defined RF24_LINUX) will buffer all data types in the user cache.
akashvibhute 2:a5f8e04bd02b 89 *
akashvibhute 2:a5f8e04bd02b 90 * **Arduino/AVR/Etc:** Data transmitted with the type set to EXTERNAL_DATA_TYPE will not be loaded into the user cache. <br>
akashvibhute 2:a5f8e04bd02b 91 * 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() :
akashvibhute 2:a5f8e04bd02b 92 * @code
akashvibhute 2:a5f8e04bd02b 93 * uint8_t return_type = network.update();
akashvibhute 2:a5f8e04bd02b 94 * if(return_type == EXTERNAL_DATA_TYPE){
akashvibhute 4:75c5aa56411f 95 * uint16_t size = network.frag_ptr->message_size;
akashvibhute 2:a5f8e04bd02b 96 * memcpy(&myDataBuffer,network.frag_ptr->message_buffer,network.frag_ptr->message_size);
akashvibhute 4:75c5aa56411f 97 * }
akashvibhute 2:a5f8e04bd02b 98 * @endcode
akashvibhute 2:a5f8e04bd02b 99 */
akashvibhute 2:a5f8e04bd02b 100 #define EXTERNAL_DATA_TYPE 131
akashvibhute 2:a5f8e04bd02b 101
akashvibhute 2:a5f8e04bd02b 102 /**
akashvibhute 2:a5f8e04bd02b 103 * Messages of this type designate the first of two or more message fragments, and will be re-assembled automatically.
akashvibhute 2:a5f8e04bd02b 104 */
akashvibhute 2:a5f8e04bd02b 105 #define NETWORK_FIRST_FRAGMENT 148
akashvibhute 2:a5f8e04bd02b 106
akashvibhute 2:a5f8e04bd02b 107 /**
akashvibhute 2:a5f8e04bd02b 108 * Messages of this type indicate a fragmented payload with two or more message fragments.
akashvibhute 2:a5f8e04bd02b 109 */
akashvibhute 2:a5f8e04bd02b 110 #define NETWORK_MORE_FRAGMENTS 149
akashvibhute 2:a5f8e04bd02b 111
akashvibhute 2:a5f8e04bd02b 112 /**
akashvibhute 2:a5f8e04bd02b 113 * Messages of this type indicate the last fragment in a sequence of message fragments.
akashvibhute 2:a5f8e04bd02b 114 * Messages of this type do not receive a NETWORK_ACK
akashvibhute 2:a5f8e04bd02b 115 */
akashvibhute 4:75c5aa56411f 116 #define NETWORK_LAST_FRAGMENT 150
akashvibhute 2:a5f8e04bd02b 117 //#define NETWORK_LAST_FRAGMENT 201
akashvibhute 2:a5f8e04bd02b 118
akashvibhute 2:a5f8e04bd02b 119 // NO ACK Response Types
akashvibhute 2:a5f8e04bd02b 120 //#define NETWORK_ACK_REQUEST 192
akashvibhute 2:a5f8e04bd02b 121
akashvibhute 2:a5f8e04bd02b 122 /**
akashvibhute 2:a5f8e04bd02b 123 * Messages of this type are used internally, to signal the sender that a transmission has been completed.
akashvibhute 2:a5f8e04bd02b 124 * RF24Network does not directly have a built-in transport layer protocol, so message delivery is not 100% guaranteed.<br>
akashvibhute 2:a5f8e04bd02b 125 * Messages can be lost via corrupted dynamic payloads, or a NETWORK_ACK can fail, while the message was actually successful.
akashvibhute 4:75c5aa56411f 126 *
akashvibhute 2:a5f8e04bd02b 127 * NETWORK_ACK messages can be utilized as a traffic/flow control mechanism, since transmitting nodes will be forced to wait until
akashvibhute 4:75c5aa56411f 128 * the payload is transmitted across the network and acknowledged, before sending additional data.
akashvibhute 2:a5f8e04bd02b 129 *
akashvibhute 2:a5f8e04bd02b 130 * 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>
akashvibhute 2:a5f8e04bd02b 131 * User messages utilizing a 'type' with a decimal value of 64 or less will not be acknowledged across the network via NETWORK_ACK messages.
akashvibhute 2:a5f8e04bd02b 132 */
akashvibhute 2:a5f8e04bd02b 133 #define NETWORK_ACK 193
akashvibhute 2:a5f8e04bd02b 134
akashvibhute 2:a5f8e04bd02b 135 /**
akashvibhute 2:a5f8e04bd02b 136 * Used by RF24Mesh
akashvibhute 2:a5f8e04bd02b 137 *
akashvibhute 2:a5f8e04bd02b 138 * Messages of this type are used with multi-casting , to find active/available nodes.
akashvibhute 2:a5f8e04bd02b 139 * Any node receiving a NETWORK_POLL sent to a multicast address will respond directly to the sender with a blank message, indicating the
akashvibhute 2:a5f8e04bd02b 140 * address of the available node via the header.
akashvibhute 4:75c5aa56411f 141 */
akashvibhute 2:a5f8e04bd02b 142 #define NETWORK_POLL 194
akashvibhute 2:a5f8e04bd02b 143
akashvibhute 2:a5f8e04bd02b 144 /**
akashvibhute 2:a5f8e04bd02b 145 * Used by RF24Mesh
akashvibhute 2:a5f8e04bd02b 146 *
akashvibhute 2:a5f8e04bd02b 147 * Messages of this type are used to request information from the master node, generally via a unicast (direct) write.
akashvibhute 2:a5f8e04bd02b 148 * Any (non-master) node receiving a message of this type will manually forward it to the master node using an normal network write.
akashvibhute 2:a5f8e04bd02b 149 */
akashvibhute 2:a5f8e04bd02b 150 #define NETWORK_REQ_ADDRESS 195
akashvibhute 2:a5f8e04bd02b 151 //#define NETWORK_ADDR_LOOKUP 196
akashvibhute 2:a5f8e04bd02b 152 //#define NETWORK_ADDR_RELEASE 197
akashvibhute 2:a5f8e04bd02b 153 /** @} */
akashvibhute 2:a5f8e04bd02b 154
akashvibhute 2:a5f8e04bd02b 155 #define NETWORK_MORE_FRAGMENTS_NACK 200
akashvibhute 2:a5f8e04bd02b 156
akashvibhute 4:75c5aa56411f 157
akashvibhute 2:a5f8e04bd02b 158 /** Internal defines for handling written payloads */
akashvibhute 2:a5f8e04bd02b 159 #define TX_NORMAL 0
akashvibhute 2:a5f8e04bd02b 160 #define TX_ROUTED 1
akashvibhute 2:a5f8e04bd02b 161 #define USER_TX_TO_PHYSICAL_ADDRESS 2 //no network ACK
akashvibhute 2:a5f8e04bd02b 162 #define USER_TX_TO_LOGICAL_ADDRESS 3 // network ACK
akashvibhute 2:a5f8e04bd02b 163 #define USER_TX_MULTICAST 4
akashvibhute 2:a5f8e04bd02b 164
akashvibhute 2:a5f8e04bd02b 165 #define MAX_FRAME_SIZE 32 //Size of individual radio frames
akashvibhute 2:a5f8e04bd02b 166 #define FRAME_HEADER_SIZE 10 //Size of RF24Network frames - data
akashvibhute 2:a5f8e04bd02b 167
akashvibhute 2:a5f8e04bd02b 168 #define USE_CURRENT_CHANNEL 255 // Use current radio channel when setting up the network
akashvibhute 2:a5f8e04bd02b 169
akashvibhute 2:a5f8e04bd02b 170 /** Internal defines for handling internal payloads - prevents reading additional data from the radio
akashvibhute 2:a5f8e04bd02b 171 * when buffers are full */
akashvibhute 4:75c5aa56411f 172 #define FLAG_HOLD_INCOMING 1
akashvibhute 4:75c5aa56411f 173 /** FLAG_BYPASS_HOLDS is mainly for use with RF24Mesh as follows:
akashvibhute 4:75c5aa56411f 174 * a: Ensure no data in radio buffers, else exit
akashvibhute 4:75c5aa56411f 175 * b: Address is changed to multicast address for renewal
akashvibhute 4:75c5aa56411f 176 * c: Holds Cleared (bypass flag is set)
akashvibhute 4:75c5aa56411f 177 * d: Address renewal takes place and is set
akashvibhute 4:75c5aa56411f 178 * e: Holds Enabled (bypass flag off)
akashvibhute 4:75c5aa56411f 179 */
akashvibhute 4:75c5aa56411f 180 #define FLAG_BYPASS_HOLDS 2
akashvibhute 4:75c5aa56411f 181
akashvibhute 4:75c5aa56411f 182 #define FLAG_FAST_FRAG 4
akashvibhute 4:75c5aa56411f 183
akashvibhute 4:75c5aa56411f 184 #define FLAG_NO_POLL 8
akashvibhute 0:c3db0798d9aa 185
akashvibhute 0:c3db0798d9aa 186 class RF24;
akashvibhute 0:c3db0798d9aa 187
akashvibhute 0:c3db0798d9aa 188 /**
akashvibhute 0:c3db0798d9aa 189 * Header which is sent with each message
akashvibhute 0:c3db0798d9aa 190 *
akashvibhute 0:c3db0798d9aa 191 * The frame put over the air consists of this header and a message
akashvibhute 2:a5f8e04bd02b 192 *
akashvibhute 2:a5f8e04bd02b 193 * Headers are addressed to the appropriate node, and the network forwards them on to their final destination.
akashvibhute 0:c3db0798d9aa 194 */
akashvibhute 4:75c5aa56411f 195 struct RF24NetworkHeader
akashvibhute 4:75c5aa56411f 196 {
akashvibhute 4:75c5aa56411f 197 uint16_t from_node; /**< Logical address where the message was generated */
akashvibhute 4:75c5aa56411f 198 uint16_t to_node; /**< Logical address where the message is going */
akashvibhute 4:75c5aa56411f 199 uint16_t id; /**< Sequential message ID, incremented every time a new frame is constructed */
akashvibhute 4:75c5aa56411f 200 /**
akashvibhute 4:75c5aa56411f 201 * Message Types:
akashvibhute 4:75c5aa56411f 202 * User message types 1 through 64 will NOT be acknowledged by the network, while message types 65 through 127 will receive a network ACK.
akashvibhute 4:75c5aa56411f 203 * System message types 192 through 255 will NOT be acknowledged by the network. Message types 128 through 192 will receive a network ACK. <br>
akashvibhute 4:75c5aa56411f 204 * <br><br>
akashvibhute 4:75c5aa56411f 205 */
akashvibhute 4:75c5aa56411f 206 unsigned char type; /**< <b>Type of the packet. </b> 0-127 are user-defined types, 128-255 are reserved for system */
akashvibhute 4:75c5aa56411f 207
akashvibhute 4:75c5aa56411f 208 /**
akashvibhute 4:75c5aa56411f 209 * During fragmentation, it carries the fragment_id, and on the last fragment
akashvibhute 4:75c5aa56411f 210 * it carries the header_type.<br>
akashvibhute 4:75c5aa56411f 211 */
akashvibhute 4:75c5aa56411f 212 unsigned char reserved; /**< *Reserved for system use* */
akashvibhute 0:c3db0798d9aa 213
akashvibhute 4:75c5aa56411f 214 static uint16_t next_id; /**< The message ID of the next message to be sent (unused)*/
akashvibhute 0:c3db0798d9aa 215
akashvibhute 4:75c5aa56411f 216 /**
akashvibhute 4:75c5aa56411f 217 * Default constructor
akashvibhute 4:75c5aa56411f 218 *
akashvibhute 2:a5f8e04bd02b 219
akashvibhute 4:75c5aa56411f 220 * Simply constructs a blank header
akashvibhute 4:75c5aa56411f 221 */
akashvibhute 4:75c5aa56411f 222 RF24NetworkHeader() {}
akashvibhute 0:c3db0798d9aa 223
akashvibhute 4:75c5aa56411f 224 /**
akashvibhute 4:75c5aa56411f 225 * Send constructor
akashvibhute 4:75c5aa56411f 226 *
akashvibhute 4:75c5aa56411f 227 * @note Now supports automatic fragmentation for very long messages, which can be sent as usual if fragmentation is enabled.
akashvibhute 4:75c5aa56411f 228 *
akashvibhute 4:75c5aa56411f 229 * Fragmentation is enabled by default for all devices except ATTiny <br>
akashvibhute 4:75c5aa56411f 230 * Configure fragmentation and max payload size in RF24Network_config.h
akashvibhute 4:75c5aa56411f 231 *
akashvibhute 4:75c5aa56411f 232 * Use this constructor to create a header and then send a message
akashvibhute 4:75c5aa56411f 233 *
akashvibhute 4:75c5aa56411f 234 * @code
akashvibhute 4:75c5aa56411f 235 * uint16_t recipient_address = 011;
akashvibhute 4:75c5aa56411f 236 *
akashvibhute 4:75c5aa56411f 237 * RF24NetworkHeader header(recipient_address,'t');
akashvibhute 4:75c5aa56411f 238 *
akashvibhute 4:75c5aa56411f 239 * network.write(header,&message,sizeof(message));
akashvibhute 4:75c5aa56411f 240 * @endcode
akashvibhute 4:75c5aa56411f 241 *
akashvibhute 4:75c5aa56411f 242 * @param _to The Octal format, logical node address where the message is going
akashvibhute 4:75c5aa56411f 243 * @param _type The type of message which follows. Only 0-127 are allowed for
akashvibhute 4:75c5aa56411f 244 * user messages. Types 1-64 will not receive a network acknowledgement.
akashvibhute 4:75c5aa56411f 245 */
akashvibhute 0:c3db0798d9aa 246
akashvibhute 4:75c5aa56411f 247 RF24NetworkHeader(uint16_t _to, unsigned char _type = 0): to_node(_to), id(next_id++), type(_type) {}
akashvibhute 4:75c5aa56411f 248 /**
akashvibhute 4:75c5aa56411f 249 * Create debugging string
akashvibhute 4:75c5aa56411f 250 *
akashvibhute 4:75c5aa56411f 251 * Useful for debugging. Dumps all members into a single string, using
akashvibhute 4:75c5aa56411f 252 * internal static memory. This memory will get overridden next time
akashvibhute 4:75c5aa56411f 253 * you call the method.
akashvibhute 4:75c5aa56411f 254 *
akashvibhute 4:75c5aa56411f 255 * @return String representation of this object
akashvibhute 4:75c5aa56411f 256 */
akashvibhute 4:75c5aa56411f 257 const char* toString(void) const;
akashvibhute 0:c3db0798d9aa 258 };
akashvibhute 0:c3db0798d9aa 259
akashvibhute 2:a5f8e04bd02b 260
akashvibhute 0:c3db0798d9aa 261 /**
akashvibhute 2:a5f8e04bd02b 262 * Frame structure for internal message handling, and for use by external applications
akashvibhute 2:a5f8e04bd02b 263 *
akashvibhute 2:a5f8e04bd02b 264 * The actual frame put over the air consists of a header (8-bytes) and a message payload (Up to 24-bytes)<br>
akashvibhute 2:a5f8e04bd02b 265 * When data is received, it is stored using the RF24NetworkFrame structure, which includes:
akashvibhute 4:75c5aa56411f 266 * 1. The header
akashvibhute 4:75c5aa56411f 267 * 2. The size of the included message
akashvibhute 2:a5f8e04bd02b 268 * 3. The 'message' or data being received
akashvibhute 4:75c5aa56411f 269 *
akashvibhute 2:a5f8e04bd02b 270 *
akashvibhute 2:a5f8e04bd02b 271 */
akashvibhute 2:a5f8e04bd02b 272
akashvibhute 2:a5f8e04bd02b 273
akashvibhute 4:75c5aa56411f 274 struct RF24NetworkFrame
akashvibhute 4:75c5aa56411f 275 {
akashvibhute 4:75c5aa56411f 276 RF24NetworkHeader header; /**< Header which is sent with each message */
akashvibhute 4:75c5aa56411f 277 uint16_t message_size; /**< The size in bytes of the payload length */
akashvibhute 4:75c5aa56411f 278
akashvibhute 4:75c5aa56411f 279 /**
akashvibhute 4:75c5aa56411f 280 * On Arduino, the message buffer is just a pointer, and can be pointed to any memory location.
akashvibhute 4:75c5aa56411f 281 * On Linux the message buffer is a standard byte array, equal in size to the defined MAX_PAYLOAD_SIZE
akashvibhute 4:75c5aa56411f 282 */
akashvibhute 4:75c5aa56411f 283
akashvibhute 4:75c5aa56411f 284
akashvibhute 4:75c5aa56411f 285
akashvibhute 4:75c5aa56411f 286 uint8_t *message_buffer; //< Pointer to the buffer storing the actual message
akashvibhute 2:a5f8e04bd02b 287
akashvibhute 4:75c5aa56411f 288 /**
akashvibhute 4:75c5aa56411f 289 * Default constructor
akashvibhute 4:75c5aa56411f 290 *
akashvibhute 4:75c5aa56411f 291 * Simply constructs a blank frame. Frames are generally used internally. See RF24NetworkHeader.
akashvibhute 4:75c5aa56411f 292 */
akashvibhute 4:75c5aa56411f 293 //RF24NetworkFrame() {}
akashvibhute 4:75c5aa56411f 294
akashvibhute 4:75c5aa56411f 295 RF24NetworkFrame() {}
akashvibhute 4:75c5aa56411f 296 /**
akashvibhute 4:75c5aa56411f 297 * Constructor - create a network frame with data
akashvibhute 4:75c5aa56411f 298 * Frames are constructed and handled differently on Arduino/AVR and Linux devices (defined RF24_LINUX)
akashvibhute 4:75c5aa56411f 299 *
akashvibhute 4:75c5aa56411f 300 * <br>
akashvibhute 4:75c5aa56411f 301 * **Linux:**
akashvibhute 4:75c5aa56411f 302 * @param _header The RF24Network header to be stored in the frame
akashvibhute 4:75c5aa56411f 303 * @param _message The 'message' or data.
akashvibhute 4:75c5aa56411f 304 * @param _len The size of the 'message' or data.
akashvibhute 4:75c5aa56411f 305 *
akashvibhute 4:75c5aa56411f 306 * <br>
akashvibhute 4:75c5aa56411f 307 * **Arduino/AVR/Etc.**
akashvibhute 4:75c5aa56411f 308 * @see RF24Network.frag_ptr
akashvibhute 4:75c5aa56411f 309 * @param _header The RF24Network header to be stored in the frame
akashvibhute 4:75c5aa56411f 310 * @param _message_size The size of the 'message' or data
akashvibhute 4:75c5aa56411f 311 *
akashvibhute 4:75c5aa56411f 312 *
akashvibhute 4:75c5aa56411f 313 * Frames are used internally and by external systems. See RF24NetworkHeader.
akashvibhute 4:75c5aa56411f 314 */
akashvibhute 4:75c5aa56411f 315
akashvibhute 4:75c5aa56411f 316 RF24NetworkFrame(RF24NetworkHeader &_header, uint16_t _message_size):
akashvibhute 4:75c5aa56411f 317 header(_header), message_size(_message_size){
akashvibhute 4:75c5aa56411f 318 }
akashvibhute 2:a5f8e04bd02b 319
akashvibhute 3:dfc8da7ac18c 320
akashvibhute 2:a5f8e04bd02b 321
akashvibhute 4:75c5aa56411f 322 /**
akashvibhute 4:75c5aa56411f 323 * Create debugging string
akashvibhute 4:75c5aa56411f 324 *
akashvibhute 4:75c5aa56411f 325 * Useful for debugging. Dumps all members into a single string, using
akashvibhute 4:75c5aa56411f 326 * internal static memory. This memory will get overridden next time
akashvibhute 4:75c5aa56411f 327 * you call the method.
akashvibhute 4:75c5aa56411f 328 *
akashvibhute 4:75c5aa56411f 329 * @return String representation of this object
akashvibhute 4:75c5aa56411f 330 */
akashvibhute 4:75c5aa56411f 331 const char* toString(void) const;
akashvibhute 2:a5f8e04bd02b 332
akashvibhute 2:a5f8e04bd02b 333 };
akashvibhute 2:a5f8e04bd02b 334
akashvibhute 4:75c5aa56411f 335
akashvibhute 2:a5f8e04bd02b 336
akashvibhute 2:a5f8e04bd02b 337 /**
akashvibhute 2:a5f8e04bd02b 338 * 2014-2015 - Optimized Network Layer for RF24 Radios
akashvibhute 0:c3db0798d9aa 339 *
akashvibhute 0:c3db0798d9aa 340 * This class implements an OSI Network Layer using nRF24L01(+) radios driven
akashvibhute 0:c3db0798d9aa 341 * by RF24 library.
akashvibhute 0:c3db0798d9aa 342 */
akashvibhute 0:c3db0798d9aa 343
akashvibhute 0:c3db0798d9aa 344 class RF24Network
akashvibhute 0:c3db0798d9aa 345 {
akashvibhute 4:75c5aa56411f 346
akashvibhute 4:75c5aa56411f 347 /**@}*/
akashvibhute 4:75c5aa56411f 348 /**
akashvibhute 4:75c5aa56411f 349 * @name Primary Interface
akashvibhute 4:75c5aa56411f 350 *
akashvibhute 4:75c5aa56411f 351 * These are the main methods you need to operate the network
akashvibhute 4:75c5aa56411f 352 */
akashvibhute 4:75c5aa56411f 353 /**@{*/
akashvibhute 4:75c5aa56411f 354
akashvibhute 0:c3db0798d9aa 355 public:
akashvibhute 4:75c5aa56411f 356 /**
akashvibhute 4:75c5aa56411f 357 * Construct the network
akashvibhute 4:75c5aa56411f 358 *
akashvibhute 4:75c5aa56411f 359 * @param _radio The underlying radio driver instance
akashvibhute 4:75c5aa56411f 360 *
akashvibhute 4:75c5aa56411f 361 */
akashvibhute 2:a5f8e04bd02b 362
akashvibhute 4:75c5aa56411f 363 RF24Network( RF24& _radio );
akashvibhute 0:c3db0798d9aa 364
akashvibhute 4:75c5aa56411f 365 /**
akashvibhute 4:75c5aa56411f 366 * Bring up the network using the current radio frequency/channel.
akashvibhute 4:75c5aa56411f 367 * Calling begin brings up the network, and configures the address, which designates the location of the node within RF24Network topology.
akashvibhute 4:75c5aa56411f 368 * @note Node addresses are specified in Octal format, see <a href=Addressing.html>RF24Network Addressing</a> for more information.
akashvibhute 4:75c5aa56411f 369 * @warning Be sure to 'begin' the radio first.
akashvibhute 4:75c5aa56411f 370 *
akashvibhute 4:75c5aa56411f 371 * **Example 1:** Begin on current radio channel with address 0 (master node)
akashvibhute 4:75c5aa56411f 372 * @code
akashvibhute 4:75c5aa56411f 373 * network.begin(00);
akashvibhute 4:75c5aa56411f 374 * @endcode
akashvibhute 4:75c5aa56411f 375 * **Example 2:** Begin with address 01 (child of master)
akashvibhute 4:75c5aa56411f 376 * @code
akashvibhute 4:75c5aa56411f 377 * network.begin(01);
akashvibhute 4:75c5aa56411f 378 * @endcode
akashvibhute 4:75c5aa56411f 379 * **Example 3:** Begin with address 011 (child of 01, grandchild of master)
akashvibhute 4:75c5aa56411f 380 * @code
akashvibhute 4:75c5aa56411f 381 * network.begin(011);
akashvibhute 4:75c5aa56411f 382 * @endcode
akashvibhute 4:75c5aa56411f 383 *
akashvibhute 4:75c5aa56411f 384 * @see begin(uint8_t _channel, uint16_t _node_address )
akashvibhute 4:75c5aa56411f 385 * @param _node_address The logical address of this node
akashvibhute 4:75c5aa56411f 386 *
akashvibhute 4:75c5aa56411f 387 */
akashvibhute 4:75c5aa56411f 388
akashvibhute 4:75c5aa56411f 389 inline void begin(uint16_t _node_address){
akashvibhute 4:75c5aa56411f 390 begin(USE_CURRENT_CHANNEL,_node_address);
akashvibhute 4:75c5aa56411f 391 }
akashvibhute 2:a5f8e04bd02b 392
akashvibhute 4:75c5aa56411f 393 /**
akashvibhute 4:75c5aa56411f 394 * Main layer loop
akashvibhute 4:75c5aa56411f 395 *
akashvibhute 4:75c5aa56411f 396 * This function must be called regularly to keep the layer going. This is where payloads are
akashvibhute 4:75c5aa56411f 397 * re-routed, received, and all the action happens.
akashvibhute 4:75c5aa56411f 398 *
akashvibhute 4:75c5aa56411f 399 * @see
akashvibhute 4:75c5aa56411f 400 *
akashvibhute 4:75c5aa56411f 401 * @return Returns the type of the last received payload.
akashvibhute 4:75c5aa56411f 402 */
akashvibhute 4:75c5aa56411f 403 uint8_t update(void);
akashvibhute 4:75c5aa56411f 404
akashvibhute 4:75c5aa56411f 405 /**
akashvibhute 4:75c5aa56411f 406 * Test whether there is a message available for this node
akashvibhute 4:75c5aa56411f 407 *
akashvibhute 4:75c5aa56411f 408 * @return Whether there is a message available for this node
akashvibhute 4:75c5aa56411f 409 */
akashvibhute 4:75c5aa56411f 410 bool available(void);
akashvibhute 4:75c5aa56411f 411
akashvibhute 4:75c5aa56411f 412 /**
akashvibhute 4:75c5aa56411f 413 * Read the next available header
akashvibhute 4:75c5aa56411f 414 *
akashvibhute 4:75c5aa56411f 415 * Reads the next available header without advancing to the next
akashvibhute 4:75c5aa56411f 416 * incoming message. Useful for doing a switch on the message type
akashvibhute 4:75c5aa56411f 417 *
akashvibhute 4:75c5aa56411f 418 * If there is no message available, the header is not touched
akashvibhute 4:75c5aa56411f 419 *
akashvibhute 4:75c5aa56411f 420 * @param[out] header The header (envelope) of the next message
akashvibhute 4:75c5aa56411f 421 */
akashvibhute 4:75c5aa56411f 422 uint16_t peek(RF24NetworkHeader& header);
akashvibhute 0:c3db0798d9aa 423
akashvibhute 4:75c5aa56411f 424 /**
akashvibhute 4:75c5aa56411f 425 * Read a message
akashvibhute 4:75c5aa56411f 426 *
akashvibhute 4:75c5aa56411f 427 * @code
akashvibhute 4:75c5aa56411f 428 * while ( network.available() ) {
akashvibhute 4:75c5aa56411f 429 * RF24NetworkHeader header;
akashvibhute 4:75c5aa56411f 430 * uint32_t time;
akashvibhute 4:75c5aa56411f 431 * network.peek(header);
akashvibhute 4:75c5aa56411f 432 * if(header.type == 'T'){
akashvibhute 4:75c5aa56411f 433 * network.read(header,&time,sizeof(time));
akashvibhute 4:75c5aa56411f 434 * Serial.print("Got time: ");
akashvibhute 4:75c5aa56411f 435 * Serial.println(time);
akashvibhute 4:75c5aa56411f 436 * }
akashvibhute 4:75c5aa56411f 437 * }
akashvibhute 4:75c5aa56411f 438 * @endcode
akashvibhute 4:75c5aa56411f 439 * @param[out] header The header (envelope) of this message
akashvibhute 4:75c5aa56411f 440 * @param[out] message Pointer to memory where the message should be placed
akashvibhute 4:75c5aa56411f 441 * @param maxlen The largest message size which can be held in @p message
akashvibhute 4:75c5aa56411f 442 * @return The total number of bytes copied into @p message
akashvibhute 4:75c5aa56411f 443 */
akashvibhute 4:75c5aa56411f 444 uint16_t read(RF24NetworkHeader& header, void* message, uint16_t maxlen);
akashvibhute 3:dfc8da7ac18c 445
akashvibhute 4:75c5aa56411f 446 /**
akashvibhute 4:75c5aa56411f 447 * Send a message
akashvibhute 4:75c5aa56411f 448 *
akashvibhute 4:75c5aa56411f 449 * @note RF24Network now supports fragmentation for very long messages, send as normal. Fragmentation
akashvibhute 4:75c5aa56411f 450 * may need to be enabled or configured by editing the RF24Network_config.h file. Default max payload size is 120 bytes.
akashvibhute 4:75c5aa56411f 451 *
akashvibhute 4:75c5aa56411f 452 * @code
akashvibhute 4:75c5aa56411f 453 * uint32_t time = millis();
akashvibhute 4:75c5aa56411f 454 * uint16_t to = 00; // Send to master
akashvibhute 4:75c5aa56411f 455 * RF24NetworkHeader header(to, 'T'); // Send header type 'T'
akashvibhute 4:75c5aa56411f 456 * network.write(header,&time,sizeof(time));
akashvibhute 4:75c5aa56411f 457 * @endcode
akashvibhute 4:75c5aa56411f 458 * @param[in,out] header The header (envelope) of this message. The critical
akashvibhute 4:75c5aa56411f 459 * thing to fill in is the @p to_node field so we know where to send the
akashvibhute 4:75c5aa56411f 460 * message. It is then updated with the details of the actual header sent.
akashvibhute 4:75c5aa56411f 461 * @param message Pointer to memory where the message is located
akashvibhute 4:75c5aa56411f 462 * @param len The size of the message
akashvibhute 4:75c5aa56411f 463 * @return Whether the message was successfully received
akashvibhute 4:75c5aa56411f 464 */
akashvibhute 4:75c5aa56411f 465 bool write(RF24NetworkHeader& header,const void* message, uint16_t len);
akashvibhute 2:a5f8e04bd02b 466
akashvibhute 4:75c5aa56411f 467 /**@}*/
akashvibhute 4:75c5aa56411f 468 /**
akashvibhute 4:75c5aa56411f 469 * @name Advanced Configuration
akashvibhute 4:75c5aa56411f 470 *
akashvibhute 4:75c5aa56411f 471 * For advanced configuration of the network
akashvibhute 4:75c5aa56411f 472 */
akashvibhute 4:75c5aa56411f 473 /**@{*/
akashvibhute 4:75c5aa56411f 474
akashvibhute 0:c3db0798d9aa 475
akashvibhute 4:75c5aa56411f 476 /**
akashvibhute 4:75c5aa56411f 477 * Construct the network in dual head mode using two radio modules.
akashvibhute 4:75c5aa56411f 478 * @note Not working on RPi. Radios will share MISO, MOSI and SCK pins, but require separate CE,CS pins.
akashvibhute 4:75c5aa56411f 479 * @code
akashvibhute 4:75c5aa56411f 480 * RF24 radio(7,8);
akashvibhute 4:75c5aa56411f 481 * RF24 radio1(4,5);
akashvibhute 4:75c5aa56411f 482 * RF24Network(radio.radio1);
akashvibhute 4:75c5aa56411f 483 * @endcode
akashvibhute 4:75c5aa56411f 484 * @param _radio The underlying radio driver instance
akashvibhute 4:75c5aa56411f 485 * @param _radio1 The second underlying radio driver instance
akashvibhute 4:75c5aa56411f 486 */
akashvibhute 4:75c5aa56411f 487
akashvibhute 4:75c5aa56411f 488 RF24Network( RF24& _radio, RF24& _radio1);
akashvibhute 4:75c5aa56411f 489
akashvibhute 4:75c5aa56411f 490 /**
akashvibhute 4:75c5aa56411f 491 * By default, multicast addresses are divided into levels.
akashvibhute 4:75c5aa56411f 492 *
akashvibhute 4:75c5aa56411f 493 * Nodes 1-5 share a multicast address, nodes n1-n5 share a multicast address, and nodes n11-n55 share a multicast address.<br>
akashvibhute 4:75c5aa56411f 494 *
akashvibhute 4:75c5aa56411f 495 * This option is used to override the defaults, and create custom multicast groups that all share a single
akashvibhute 4:75c5aa56411f 496 * address. <br>
akashvibhute 4:75c5aa56411f 497 * The level should be specified in decimal format 1-6 <br>
akashvibhute 4:75c5aa56411f 498 * @see multicastRelay
akashvibhute 4:75c5aa56411f 499 * @param level Levels 1 to 6 are available. All nodes at the same level will receive the same
akashvibhute 4:75c5aa56411f 500 * messages if in range. Messages will be routed in order of level, low to high by default, with the
akashvibhute 4:75c5aa56411f 501 * master node (00) at multicast Level 0
akashvibhute 4:75c5aa56411f 502 */
akashvibhute 4:75c5aa56411f 503
akashvibhute 4:75c5aa56411f 504 void multicastLevel(uint8_t level);
akashvibhute 4:75c5aa56411f 505
akashvibhute 4:75c5aa56411f 506 /**
akashvibhute 4:75c5aa56411f 507 * Enabling this will allow this node to automatically forward received multicast frames to the next highest
akashvibhute 4:75c5aa56411f 508 * multicast level. Duplicate frames are filtered out, so multiple forwarding nodes at the same level should
akashvibhute 4:75c5aa56411f 509 * not interfere. Forwarded payloads will also be received.
akashvibhute 4:75c5aa56411f 510 * @see multicastLevel
akashvibhute 4:75c5aa56411f 511 */
akashvibhute 4:75c5aa56411f 512
akashvibhute 4:75c5aa56411f 513 bool multicastRelay;
akashvibhute 4:75c5aa56411f 514
akashvibhute 4:75c5aa56411f 515 /**
akashvibhute 4:75c5aa56411f 516 * Set up the watchdog timer for sleep mode using the number 0 through 10 to represent the following time periods:<br>
akashvibhute 4:75c5aa56411f 517 * wdt_16ms = 0, wdt_32ms, wdt_64ms, wdt_128ms, wdt_250ms, wdt_500ms, wdt_1s, wdt_2s, wdt_4s, wdt_8s
akashvibhute 4:75c5aa56411f 518 * @code
akashvibhute 4:75c5aa56411f 519 * setup_watchdog(7); // Sets the WDT to trigger every second
akashvibhute 4:75c5aa56411f 520 * @endcode
akashvibhute 4:75c5aa56411f 521 * @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.
akashvibhute 4:75c5aa56411f 522 */
akashvibhute 4:75c5aa56411f 523 void setup_watchdog(uint8_t prescalar);
akashvibhute 2:a5f8e04bd02b 524
akashvibhute 3:dfc8da7ac18c 525 /**
akashvibhute 4:75c5aa56411f 526 * @note: This value is automatically assigned based on the node address
akashvibhute 4:75c5aa56411f 527 * to reduce errors and increase throughput of the network.
akashvibhute 4:75c5aa56411f 528 *
akashvibhute 4:75c5aa56411f 529 * Sets the timeout period for individual payloads in milliseconds at staggered intervals.
akashvibhute 4:75c5aa56411f 530 * Payloads will be retried automatically until success or timeout
akashvibhute 4:75c5aa56411f 531 * Set to 0 to use the normal auto retry period defined by radio.setRetries()
akashvibhute 4:75c5aa56411f 532 *
akashvibhute 4:75c5aa56411f 533 */
akashvibhute 2:a5f8e04bd02b 534
akashvibhute 4:75c5aa56411f 535 uint32_t txTimeout; /**< Network timeout value */
akashvibhute 4:75c5aa56411f 536
akashvibhute 4:75c5aa56411f 537 /**
akashvibhute 4:75c5aa56411f 538 * This only affects payloads that are routed by one or more nodes.
akashvibhute 4:75c5aa56411f 539 * This specifies how long to wait for an ack from across the network.
akashvibhute 4:75c5aa56411f 540 * Radios sending directly to their parent or children nodes do not
akashvibhute 4:75c5aa56411f 541 * utilize this value.
akashvibhute 4:75c5aa56411f 542 */
akashvibhute 4:75c5aa56411f 543
akashvibhute 4:75c5aa56411f 544 uint16_t routeTimeout; /**< Timeout for routed payloads */
akashvibhute 4:75c5aa56411f 545
akashvibhute 4:75c5aa56411f 546
akashvibhute 4:75c5aa56411f 547 /**@}*/
akashvibhute 4:75c5aa56411f 548 /**
akashvibhute 4:75c5aa56411f 549 * @name Advanced Operation
akashvibhute 4:75c5aa56411f 550 *
akashvibhute 4:75c5aa56411f 551 * For advanced operation of the network
akashvibhute 4:75c5aa56411f 552 */
akashvibhute 4:75c5aa56411f 553 /**@{*/
akashvibhute 2:a5f8e04bd02b 554
akashvibhute 4:75c5aa56411f 555 /**
akashvibhute 4:75c5aa56411f 556 * Return the number of failures and successes for all transmitted payloads, routed or sent directly
akashvibhute 4:75c5aa56411f 557 * @note This needs to be enabled via #define ENABLE_NETWORK_STATS in RF24Network_config.h
akashvibhute 4:75c5aa56411f 558 *
akashvibhute 4:75c5aa56411f 559 * @code
akashvibhute 4:75c5aa56411f 560 * bool fails, success;
akashvibhute 4:75c5aa56411f 561 * network.failures(&fails,&success);
akashvibhute 4:75c5aa56411f 562 * @endcode
akashvibhute 4:75c5aa56411f 563 *
akashvibhute 4:75c5aa56411f 564 */
akashvibhute 4:75c5aa56411f 565 void failures(uint32_t *_fails, uint32_t *_ok);
akashvibhute 4:75c5aa56411f 566
akashvibhute 4:75c5aa56411f 567 #if defined (RF24NetworkMulticast)
akashvibhute 4:75c5aa56411f 568
akashvibhute 4:75c5aa56411f 569 /**
akashvibhute 4:75c5aa56411f 570 * Send a multicast message to multiple nodes at once
akashvibhute 4:75c5aa56411f 571 * Allows messages to be rapidly broadcast through the network
akashvibhute 4:75c5aa56411f 572 *
akashvibhute 4:75c5aa56411f 573 * Multicasting is arranged in levels, with all nodes on the same level listening to the same address
akashvibhute 4:75c5aa56411f 574 * Levels are assigned by network level ie: nodes 01-05: Level 1, nodes 011-055: Level 2
akashvibhute 4:75c5aa56411f 575 * @see multicastLevel
akashvibhute 4:75c5aa56411f 576 * @see multicastRelay
akashvibhute 4:75c5aa56411f 577 * @param message Pointer to memory where the message is located
akashvibhute 4:75c5aa56411f 578 * @param len The size of the message
akashvibhute 4:75c5aa56411f 579 * @param level Multicast level to broadcast to
akashvibhute 4:75c5aa56411f 580 * @return Whether the message was successfully sent
akashvibhute 4:75c5aa56411f 581 */
akashvibhute 4:75c5aa56411f 582
akashvibhute 4:75c5aa56411f 583 bool multicast(RF24NetworkHeader& header,const void* message, uint16_t len, uint8_t level);
akashvibhute 4:75c5aa56411f 584
akashvibhute 4:75c5aa56411f 585
akashvibhute 4:75c5aa56411f 586 #endif
akashvibhute 4:75c5aa56411f 587
akashvibhute 4:75c5aa56411f 588 /**
akashvibhute 4:75c5aa56411f 589 * Writes a direct (unicast) payload. This allows routing or sending messages outside of the usual routing paths.
akashvibhute 4:75c5aa56411f 590 * The same as write, but a physical address is specified as the last option.
akashvibhute 4:75c5aa56411f 591 * The payload will be written to the physical address, and routed as necessary by the recipient
akashvibhute 4:75c5aa56411f 592 */
akashvibhute 4:75c5aa56411f 593 bool write(RF24NetworkHeader& header,const void* message, uint16_t len, uint16_t writeDirect);
akashvibhute 3:dfc8da7ac18c 594
akashvibhute 4:75c5aa56411f 595 /**
akashvibhute 4:75c5aa56411f 596 * Sleep this node - For AVR devices only
akashvibhute 4:75c5aa56411f 597 * @note NEW - Nodes can now be slept while the radio is not actively transmitting. This must be manually enabled by uncommenting
akashvibhute 4:75c5aa56411f 598 * the #define ENABLE_SLEEP_MODE in RF24Network_config.h
akashvibhute 4:75c5aa56411f 599 * @note Setting the interruptPin to 255 will disable interrupt wake-ups
akashvibhute 4:75c5aa56411f 600 * @note The watchdog timer should be configured in setup() if using sleep mode.
akashvibhute 4:75c5aa56411f 601 * This function will sleep the node, with the radio still active in receive mode.
akashvibhute 4:75c5aa56411f 602 *
akashvibhute 4:75c5aa56411f 603 * The node can be awoken in two ways, both of which can be enabled simultaneously:
akashvibhute 4:75c5aa56411f 604 * 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.
akashvibhute 4:75c5aa56411f 605 * 2. The watchdog timer waking the MCU after a designated period of time, can also be used instead of delays to control transmission intervals.
akashvibhute 4:75c5aa56411f 606 * @code
akashvibhute 4:75c5aa56411f 607 * if(!network.available()){ network.sleepNode(1,0); } //Sleeps the node for 1 second or a payload is received
akashvibhute 4:75c5aa56411f 608 *
akashvibhute 4:75c5aa56411f 609 * Other options:
akashvibhute 4:75c5aa56411f 610 * network.sleepNode(0,0); // Sleep this node for the designated time period, or a payload is received.
akashvibhute 4:75c5aa56411f 611 * network.sleepNode(1,255); // Sleep this node for 1 cycle. Do not wake up until then, even if a payload is received ( no interrupt )
akashvibhute 4:75c5aa56411f 612 * @endcode
akashvibhute 4:75c5aa56411f 613 * @see setup_watchdog()
akashvibhute 4:75c5aa56411f 614 * @param cycles: The node will sleep in cycles of 1s. Using 2 will sleep 2 WDT cycles, 3 sleeps 3WDT cycles...
akashvibhute 4:75c5aa56411f 615 * @param interruptPin: The interrupt number to use (0,1) for pins two and three on Uno,Nano. More available on Mega etc.
akashvibhute 4:75c5aa56411f 616 * @return True if sleepNode completed normally, after the specified number of cycles. False if sleep was interrupted
akashvibhute 4:75c5aa56411f 617 */
akashvibhute 4:75c5aa56411f 618 bool sleepNode( unsigned int cycles, int interruptPin );
akashvibhute 3:dfc8da7ac18c 619
akashvibhute 3:dfc8da7ac18c 620
akashvibhute 4:75c5aa56411f 621 /**
akashvibhute 4:75c5aa56411f 622 * This node's parent address
akashvibhute 4:75c5aa56411f 623 *
akashvibhute 4:75c5aa56411f 624 * @return This node's parent address, or -1 if this is the base
akashvibhute 4:75c5aa56411f 625 */
akashvibhute 4:75c5aa56411f 626 uint16_t parent() const;
akashvibhute 4:75c5aa56411f 627
akashvibhute 4:75c5aa56411f 628 /**
akashvibhute 4:75c5aa56411f 629 * Provided a node address and a pipe number, will return the RF24Network address of that child pipe for that node
akashvibhute 4:75c5aa56411f 630 */
akashvibhute 4:75c5aa56411f 631 uint16_t addressOfPipe( uint16_t node,uint8_t pipeNo );
akashvibhute 4:75c5aa56411f 632
akashvibhute 4:75c5aa56411f 633 /**
akashvibhute 4:75c5aa56411f 634 * @note Addresses are specified in octal: 011, 034
akashvibhute 4:75c5aa56411f 635 * @return True if a supplied address is valid
akashvibhute 4:75c5aa56411f 636 */
akashvibhute 4:75c5aa56411f 637 bool is_valid_address( uint16_t node );
akashvibhute 2:a5f8e04bd02b 638
akashvibhute 4:75c5aa56411f 639 /**@}*/
akashvibhute 4:75c5aa56411f 640 /**
akashvibhute 4:75c5aa56411f 641 * @name Deprecated
akashvibhute 4:75c5aa56411f 642 *
akashvibhute 4:75c5aa56411f 643 * Maintained for backwards compatibility
akashvibhute 4:75c5aa56411f 644 */
akashvibhute 4:75c5aa56411f 645 /**@{*/
akashvibhute 4:75c5aa56411f 646
akashvibhute 4:75c5aa56411f 647 /**
akashvibhute 4:75c5aa56411f 648 * Bring up the network on a specific radio frequency/channel.
akashvibhute 4:75c5aa56411f 649 * @note Use radio.setChannel() to configure the radio channel
akashvibhute 4:75c5aa56411f 650 *
akashvibhute 4:75c5aa56411f 651 * **Example 1:** Begin on channel 90 with address 0 (master node)
akashvibhute 4:75c5aa56411f 652 * @code
akashvibhute 4:75c5aa56411f 653 * network.begin(90,0);
akashvibhute 4:75c5aa56411f 654 * @endcode
akashvibhute 4:75c5aa56411f 655 * **Example 2:** Begin on channel 90 with address 01 (child of master)
akashvibhute 4:75c5aa56411f 656 * @code
akashvibhute 4:75c5aa56411f 657 * network.begin(90,01);
akashvibhute 4:75c5aa56411f 658 * @endcode
akashvibhute 4:75c5aa56411f 659 * **Example 3:** Begin on channel 90 with address 011 (child of 01, grandchild of master)
akashvibhute 4:75c5aa56411f 660 * @code
akashvibhute 4:75c5aa56411f 661 * network.begin(90,011);
akashvibhute 4:75c5aa56411f 662 * @endcode
akashvibhute 4:75c5aa56411f 663 *
akashvibhute 4:75c5aa56411f 664 * @param _channel The RF channel to operate on
akashvibhute 4:75c5aa56411f 665 * @param _node_address The logical address of this node
akashvibhute 4:75c5aa56411f 666 *
akashvibhute 4:75c5aa56411f 667 */
akashvibhute 4:75c5aa56411f 668 void begin(uint8_t _channel, uint16_t _node_address );
akashvibhute 4:75c5aa56411f 669
akashvibhute 4:75c5aa56411f 670 /**@}*/
akashvibhute 4:75c5aa56411f 671 /**
akashvibhute 4:75c5aa56411f 672 * @name External Applications/Systems
akashvibhute 4:75c5aa56411f 673 *
akashvibhute 4:75c5aa56411f 674 * Interface for External Applications and Systems ( RF24Mesh, RF24Ethernet )
akashvibhute 4:75c5aa56411f 675 */
akashvibhute 4:75c5aa56411f 676 /**@{*/
akashvibhute 4:75c5aa56411f 677
akashvibhute 4:75c5aa56411f 678 /** The raw system frame buffer of received data. */
akashvibhute 4:75c5aa56411f 679
akashvibhute 4:75c5aa56411f 680 uint8_t frame_buffer[MAX_FRAME_SIZE];
akashvibhute 2:a5f8e04bd02b 681
akashvibhute 4:75c5aa56411f 682 /**
akashvibhute 4:75c5aa56411f 683 * **Linux** <br>
akashvibhute 4:75c5aa56411f 684 * Data with a header type of EXTERNAL_DATA_TYPE will be loaded into a separate queue.
akashvibhute 4:75c5aa56411f 685 * The data can be accessed as follows:
akashvibhute 4:75c5aa56411f 686 * @code
akashvibhute 4:75c5aa56411f 687 * RF24NetworkFrame f;
akashvibhute 4:75c5aa56411f 688 * while(network.external_queue.size() > 0){
akashvibhute 4:75c5aa56411f 689 * f = network.external_queue.front();
akashvibhute 4:75c5aa56411f 690 * uint16_t dataSize = f.message_size;
akashvibhute 4:75c5aa56411f 691 * //read the frame message buffer
akashvibhute 4:75c5aa56411f 692 * memcpy(&myBuffer,&f.message_buffer,dataSize);
akashvibhute 4:75c5aa56411f 693 * network.external_queue.pop();
akashvibhute 4:75c5aa56411f 694 * }
akashvibhute 4:75c5aa56411f 695 * @endcode
akashvibhute 4:75c5aa56411f 696 */
akashvibhute 4:75c5aa56411f 697
akashvibhute 4:75c5aa56411f 698
akashvibhute 4:75c5aa56411f 699
akashvibhute 4:75c5aa56411f 700
akashvibhute 4:75c5aa56411f 701 #if !defined ( DISABLE_FRAGMENTATION )
akashvibhute 4:75c5aa56411f 702 /**
akashvibhute 4:75c5aa56411f 703 * **ARDUINO** <br>
akashvibhute 4:75c5aa56411f 704 * The frag_ptr is only used with Arduino (not RPi/Linux) and is mainly used for external data systems like RF24Ethernet. When
akashvibhute 4:75c5aa56411f 705 * an EXTERNAL_DATA payload type is received, and returned from network.update(), the frag_ptr will always point to the starting
akashvibhute 4:75c5aa56411f 706 * memory location of the received frame. <br>This is used by external data systems (RF24Ethernet) to immediately copy the received
akashvibhute 4:75c5aa56411f 707 * data to a buffer, without using the user-cache.
akashvibhute 4:75c5aa56411f 708 *
akashvibhute 4:75c5aa56411f 709 * @see RF24NetworkFrame
akashvibhute 4:75c5aa56411f 710 *
akashvibhute 4:75c5aa56411f 711 * @code
akashvibhute 4:75c5aa56411f 712 * uint8_t return_type = network.update();
akashvibhute 4:75c5aa56411f 713 * if(return_type == EXTERNAL_DATA_TYPE){
akashvibhute 4:75c5aa56411f 714 * uint16_t size = network.frag_ptr->message_size;
akashvibhute 4:75c5aa56411f 715 * memcpy(&myDataBuffer,network.frag_ptr->message_buffer,network.frag_ptr->message_size);
akashvibhute 4:75c5aa56411f 716 * }
akashvibhute 4:75c5aa56411f 717 * @endcode
akashvibhute 4:75c5aa56411f 718 * Linux devices (defined as RF24_LINUX) currently cache all payload types, and do not utilize frag_ptr.
akashvibhute 4:75c5aa56411f 719 */
akashvibhute 4:75c5aa56411f 720 RF24NetworkFrame* frag_ptr;
akashvibhute 4:75c5aa56411f 721 #endif
akashvibhute 0:c3db0798d9aa 722
akashvibhute 4:75c5aa56411f 723 /**
akashvibhute 4:75c5aa56411f 724 * Variable to determine whether update() will return after the radio buffers have been emptied (DEFAULT), or
akashvibhute 4:75c5aa56411f 725 * whether to return immediately when (most) system types are received.
akashvibhute 4:75c5aa56411f 726 *
akashvibhute 4:75c5aa56411f 727 * As an example, this is used with RF24Mesh to catch and handle system messages without loading them into the user cache.
akashvibhute 4:75c5aa56411f 728 *
akashvibhute 4:75c5aa56411f 729 * The following reserved/system message types are handled automatically, and not returned.
akashvibhute 4:75c5aa56411f 730 *
akashvibhute 4:75c5aa56411f 731 * | System Message Types <br> (Not Returned) |
akashvibhute 4:75c5aa56411f 732 * |-----------------------|
akashvibhute 4:75c5aa56411f 733 * | NETWORK_ADDR_RESPONSE |
akashvibhute 4:75c5aa56411f 734 * | NETWORK_ACK |
akashvibhute 4:75c5aa56411f 735 * | NETWORK_PING |
akashvibhute 4:75c5aa56411f 736 * | NETWORK_POLL <br>(With multicast enabled) |
akashvibhute 4:75c5aa56411f 737 * | NETWORK_REQ_ADDRESS |
akashvibhute 4:75c5aa56411f 738 *
akashvibhute 4:75c5aa56411f 739 */
akashvibhute 4:75c5aa56411f 740 bool returnSysMsgs;
akashvibhute 3:dfc8da7ac18c 741
akashvibhute 4:75c5aa56411f 742 /**
akashvibhute 4:75c5aa56411f 743 * Network Flags allow control of data flow
akashvibhute 4:75c5aa56411f 744 *
akashvibhute 4:75c5aa56411f 745 * 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>
akashvibhute 4:75c5aa56411f 746 * 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>
akashvibhute 4:75c5aa56411f 747 *
akashvibhute 4:75c5aa56411f 748 * | FLAGS | Value | Description |
akashvibhute 4:75c5aa56411f 749 * |-------|-------|-------------|
akashvibhute 4:75c5aa56411f 750 * |FLAG_HOLD_INCOMING| 1(bit_1) | INTERNAL: Set automatically when a fragmented payload will exceed the available cache |
akashvibhute 4:75c5aa56411f 751 * |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|
akashvibhute 4:75c5aa56411f 752 * |FLAG_FAST_FRAG| 4(bit_3) | INTERNAL: Replaces the fastFragTransfer variable, and allows for faster transfers between directly connected nodes. |
akashvibhute 4:75c5aa56411f 753 * |FLAG_NO_POLL| 8(bit_4) | EXTERNAL/USER: Disables NETWORK_POLL responses on a node-by-node basis. |
akashvibhute 4:75c5aa56411f 754 *
akashvibhute 4:75c5aa56411f 755 */
akashvibhute 4:75c5aa56411f 756 uint8_t networkFlags;
akashvibhute 4:75c5aa56411f 757
akashvibhute 4:75c5aa56411f 758 private:
akashvibhute 3:dfc8da7ac18c 759
akashvibhute 4:75c5aa56411f 760 uint32_t txTime;
akashvibhute 4:75c5aa56411f 761 Timer mainTimer;
akashvibhute 4:75c5aa56411f 762
akashvibhute 4:75c5aa56411f 763 bool write(uint16_t, uint8_t directTo);
akashvibhute 4:75c5aa56411f 764 bool write_to_pipe( uint16_t node, uint8_t pipe, bool multicast );
akashvibhute 4:75c5aa56411f 765 uint8_t enqueue(RF24NetworkHeader *header);
akashvibhute 3:dfc8da7ac18c 766
akashvibhute 4:75c5aa56411f 767 bool is_direct_child( uint16_t node );
akashvibhute 4:75c5aa56411f 768 bool is_descendant( uint16_t node );
akashvibhute 4:75c5aa56411f 769
akashvibhute 4:75c5aa56411f 770 uint16_t direct_child_route_to( uint16_t node );
akashvibhute 4:75c5aa56411f 771 //uint8_t pipe_to_descendant( uint16_t node );
akashvibhute 4:75c5aa56411f 772 void setup_address(void);
akashvibhute 4:75c5aa56411f 773 bool _write(RF24NetworkHeader& header,const void* message, uint16_t len, uint16_t writeDirect);
akashvibhute 4:75c5aa56411f 774
akashvibhute 4:75c5aa56411f 775 struct logicalToPhysicalStruct{
akashvibhute 4:75c5aa56411f 776 uint16_t send_node;
akashvibhute 4:75c5aa56411f 777 uint8_t send_pipe;
akashvibhute 4:75c5aa56411f 778 bool multicast;
akashvibhute 4:75c5aa56411f 779 };
akashvibhute 4:75c5aa56411f 780
akashvibhute 4:75c5aa56411f 781 bool logicalToPhysicalAddress(logicalToPhysicalStruct *conversionInfo);
akashvibhute 4:75c5aa56411f 782
akashvibhute 4:75c5aa56411f 783
akashvibhute 4:75c5aa56411f 784 RF24& radio; /**< Underlying radio driver, provides link/physical layers */
akashvibhute 3:dfc8da7ac18c 785 #if defined (DUAL_HEAD_RADIO)
akashvibhute 4:75c5aa56411f 786 RF24& radio1;
akashvibhute 3:dfc8da7ac18c 787 #endif
akashvibhute 4:75c5aa56411f 788 #if defined (RF24NetworkMulticast)
akashvibhute 4:75c5aa56411f 789 uint8_t multicast_level;
akashvibhute 3:dfc8da7ac18c 790 #endif
akashvibhute 4:75c5aa56411f 791 uint16_t node_address; /**< Logical node address of this unit, 1 .. UINT_MAX */
akashvibhute 4:75c5aa56411f 792 //const static int frame_size = 32; /**< How large is each frame over the air */
akashvibhute 4:75c5aa56411f 793 uint8_t frame_size;
akashvibhute 4:75c5aa56411f 794 const static unsigned int max_frame_payload_size = MAX_FRAME_SIZE-sizeof(RF24NetworkHeader);
akashvibhute 3:dfc8da7ac18c 795
akashvibhute 4:75c5aa56411f 796
akashvibhute 4:75c5aa56411f 797 #if !defined (NUM_USER_PAYLOADS)
akashvibhute 4:75c5aa56411f 798 #define NUM_USER_PAYLOADS 5
akashvibhute 4:75c5aa56411f 799 #endif
akashvibhute 4:75c5aa56411f 800
akashvibhute 4:75c5aa56411f 801 #if defined (DISABLE_USER_PAYLOADS)
akashvibhute 4:75c5aa56411f 802 uint8_t frame_queue[1]; /**< Space for a small set of frames that need to be delivered to the app layer */
akashvibhute 4:75c5aa56411f 803 #else
akashvibhute 4:75c5aa56411f 804 uint8_t frame_queue[MAIN_BUFFER_SIZE]; /**< Space for a small set of frames that need to be delivered to the app layer */
akashvibhute 4:75c5aa56411f 805 #endif
akashvibhute 4:75c5aa56411f 806
akashvibhute 4:75c5aa56411f 807 uint8_t* next_frame; /**< Pointer into the @p frame_queue where we should place the next received frame */
akashvibhute 4:75c5aa56411f 808
akashvibhute 4:75c5aa56411f 809 #if !defined ( DISABLE_FRAGMENTATION )
akashvibhute 4:75c5aa56411f 810 RF24NetworkFrame frag_queue;
akashvibhute 4:75c5aa56411f 811 uint8_t frag_queue_message_buffer[MAX_PAYLOAD_SIZE]; //frame size + 1
akashvibhute 4:75c5aa56411f 812 #endif
akashvibhute 0:c3db0798d9aa 813
akashvibhute 4:75c5aa56411f 814
akashvibhute 4:75c5aa56411f 815 //uint8_t frag_queue[MAX_PAYLOAD_SIZE + 11];
akashvibhute 4:75c5aa56411f 816 //RF24NetworkFrame frag_queue;
akashvibhute 4:75c5aa56411f 817
akashvibhute 4:75c5aa56411f 818 uint16_t parent_node; /**< Our parent's node address */
akashvibhute 4:75c5aa56411f 819 uint8_t parent_pipe; /**< The pipe our parent uses to listen to us */
akashvibhute 4:75c5aa56411f 820 uint16_t node_mask; /**< The bits which contain signfificant node address information */
akashvibhute 4:75c5aa56411f 821
akashvibhute 4:75c5aa56411f 822 #if defined ENABLE_NETWORK_STATS
akashvibhute 4:75c5aa56411f 823 static uint32_t nFails;
akashvibhute 4:75c5aa56411f 824 static uint32_t nOK;
akashvibhute 4:75c5aa56411f 825 #endif
akashvibhute 4:75c5aa56411f 826
akashvibhute 2:a5f8e04bd02b 827 public:
akashvibhute 2:a5f8e04bd02b 828
akashvibhute 4:75c5aa56411f 829
akashvibhute 2:a5f8e04bd02b 830
akashvibhute 0:c3db0798d9aa 831 };
akashvibhute 0:c3db0798d9aa 832
akashvibhute 0:c3db0798d9aa 833 /**
akashvibhute 2:a5f8e04bd02b 834 * @example helloworld_tx.ino
akashvibhute 0:c3db0798d9aa 835 *
akashvibhute 0:c3db0798d9aa 836 * Simplest possible example of using RF24Network. Put this sketch
akashvibhute 0:c3db0798d9aa 837 * on one node, and helloworld_rx.pde on the other. Tx will send
akashvibhute 0:c3db0798d9aa 838 * Rx a nice message every 2 seconds which rx will print out for us.
akashvibhute 0:c3db0798d9aa 839 */
akashvibhute 0:c3db0798d9aa 840
akashvibhute 0:c3db0798d9aa 841 /**
akashvibhute 2:a5f8e04bd02b 842 * @example helloworld_rx.ino
akashvibhute 0:c3db0798d9aa 843 *
akashvibhute 0:c3db0798d9aa 844 * Simplest possible example of using RF24Network. Put this sketch
akashvibhute 0:c3db0798d9aa 845 * on one node, and helloworld_tx.pde on the other. Tx will send
akashvibhute 0:c3db0798d9aa 846 * Rx a nice message every 2 seconds which rx will print out for us.
akashvibhute 0:c3db0798d9aa 847 */
akashvibhute 0:c3db0798d9aa 848
akashvibhute 0:c3db0798d9aa 849 /**
akashvibhute 2:a5f8e04bd02b 850 * @example Network_Ping.ino
akashvibhute 0:c3db0798d9aa 851 *
akashvibhute 2:a5f8e04bd02b 852 * Example to give users an understanding of addressing and topology in the mesh network
akashvibhute 0:c3db0798d9aa 853 * Using this sketch, each node will send a ping to the base every
akashvibhute 0:c3db0798d9aa 854 * few seconds. The RF24Network library will route the message across
akashvibhute 0:c3db0798d9aa 855 * the mesh to the correct node.
akashvibhute 2:a5f8e04bd02b 856 *
akashvibhute 2:a5f8e04bd02b 857 */
akashvibhute 2:a5f8e04bd02b 858
akashvibhute 2:a5f8e04bd02b 859 /**
akashvibhute 2:a5f8e04bd02b 860 * @example Network_Ping_Sleep.ino
akashvibhute 2:a5f8e04bd02b 861 *
akashvibhute 2:a5f8e04bd02b 862 * Example: This is almost exactly the same as the Network_Ping example, but with use
akashvibhute 2:a5f8e04bd02b 863 * of the integrated sleep mode.
akashvibhute 2:a5f8e04bd02b 864 *
akashvibhute 2:a5f8e04bd02b 865 * This example demonstrates how nodes on the network utilize sleep mode to conserve power. For example,
akashvibhute 2:a5f8e04bd02b 866 * the radio itself will draw about 13.5mA in receive mode. In sleep mode, it will use as little as 22ua (.000022mA)
akashvibhute 2:a5f8e04bd02b 867 * of power when not actively transmitting or receiving data. In addition, the Arduino is powered down as well,
akashvibhute 2:a5f8e04bd02b 868 * dropping network power consumption dramatically compared to previous capabilities. <br>
akashvibhute 2:a5f8e04bd02b 869 * Note: Sleeping nodes generate traffic that will wake other nodes up. This may be mitigated with further modifications. Sleep
akashvibhute 2:a5f8e04bd02b 870 * payloads are currently always routed to the master node, which will wake up intermediary nodes. Routing nodes can be configured
akashvibhute 2:a5f8e04bd02b 871 * to go back to sleep immediately.
akashvibhute 2:a5f8e04bd02b 872 * The displayed millis() count will give an indication of how much a node has been sleeping compared to the others, as millis() will
akashvibhute 2:a5f8e04bd02b 873 * not increment while a node sleeps.
akashvibhute 2:a5f8e04bd02b 874 *<br>
akashvibhute 2:a5f8e04bd02b 875 * - Using this sketch, each node will send a ping to every other node in the network every few seconds.<br>
akashvibhute 2:a5f8e04bd02b 876 * - The RF24Network library will route the message across the mesh to the correct node.<br>
akashvibhute 2:a5f8e04bd02b 877 *
akashvibhute 0:c3db0798d9aa 878 */
akashvibhute 0:c3db0798d9aa 879
akashvibhute 0:c3db0798d9aa 880 /**
akashvibhute 0:c3db0798d9aa 881 * @example sensornet.pde
akashvibhute 0:c3db0798d9aa 882 *
akashvibhute 0:c3db0798d9aa 883 * Example of a sensor network.
akashvibhute 0:c3db0798d9aa 884 * This sketch demonstrates how to use the RF24Network library to
akashvibhute 0:c3db0798d9aa 885 * manage a set of low-power sensor nodes which mostly sleep but
akashvibhute 0:c3db0798d9aa 886 * awake regularly to send readings to the base.
akashvibhute 0:c3db0798d9aa 887 */
akashvibhute 0:c3db0798d9aa 888 /**
akashvibhute 0:c3db0798d9aa 889 * @mainpage Network Layer for RF24 Radios
akashvibhute 0:c3db0798d9aa 890 *
akashvibhute 0:c3db0798d9aa 891 * This class implements an <a href="http://en.wikipedia.org/wiki/Network_layer">OSI Network Layer</a> using nRF24L01(+) radios driven
akashvibhute 2:a5f8e04bd02b 892 * by the newly optimized <a href="http://tmrh20.github.com/RF24/">RF24</a> library fork.
akashvibhute 0:c3db0798d9aa 893 *
akashvibhute 0:c3db0798d9aa 894 * @section Purpose Purpose/Goal
akashvibhute 0:c3db0798d9aa 895 *
akashvibhute 2:a5f8e04bd02b 896 * Original: Create an alternative to ZigBee radios for Arduino communication.
akashvibhute 4:75c5aa56411f 897 *
akashvibhute 2:a5f8e04bd02b 898 * New: Enhance the current functionality for maximum efficiency, reliability, and speed
akashvibhute 0:c3db0798d9aa 899 *
akashvibhute 2:a5f8e04bd02b 900 * Xbees are excellent little radios, backed up by a mature and robust standard
akashvibhute 0:c3db0798d9aa 901 * protocol stack. They are also expensive.
akashvibhute 0:c3db0798d9aa 902 *
akashvibhute 2:a5f8e04bd02b 903 * For many Arduino uses, they seem like overkill. So I am working to improve the current
akashvibhute 2:a5f8e04bd02b 904 * standard for nRF24L01 radios. The best RF24 modules are available for less than
akashvibhute 0:c3db0798d9aa 905 * $6 from many sources. With the RF24Network layer, I hope to cover many
akashvibhute 0:c3db0798d9aa 906 * common communication scenarios.
akashvibhute 0:c3db0798d9aa 907 *
akashvibhute 0:c3db0798d9aa 908 * Please see the @ref Zigbee page for a comparison against the ZigBee protocols
akashvibhute 0:c3db0798d9aa 909 *
akashvibhute 0:c3db0798d9aa 910 * @section Features Features
akashvibhute 0:c3db0798d9aa 911 *
akashvibhute 4:75c5aa56411f 912 * <b>Whats new? </b><br>
akashvibhute 2:a5f8e04bd02b 913 * @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
akashvibhute 2:a5f8e04bd02b 914 * @li New functionality: (Dec 8) Support for fragmented multicast payloads on both RPi and Arduino
akashvibhute 4:75c5aa56411f 915 * @li New functionality: (Nov 24) Fragmentation & reassembly supported on both RPi and Arduino
akashvibhute 2:a5f8e04bd02b 916 * @li Note: structure of network frames is changed, these are only used by external applications like RF24Ethernet and RF24toTUN, and for fragmentation
akashvibhute 2:a5f8e04bd02b 917 * @li New functionality: User message types 1 through 64 will not receive a network ack
akashvibhute 2:a5f8e04bd02b 918 *
akashvibhute 0:c3db0798d9aa 919 * The layer provides:
akashvibhute 2:a5f8e04bd02b 920 * @li <b>New</b> (2014): Network ACKs: Efficient acknowledgement of network-wide transmissions, via dynamic radio acks and network protocol acks.
akashvibhute 2:a5f8e04bd02b 921 * @li <b>New</b> (2014): Updated addressing standard for optimal radio transmission.
akashvibhute 2:a5f8e04bd02b 922 * @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.
akashvibhute 2:a5f8e04bd02b 923 * @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.
akashvibhute 2:a5f8e04bd02b 924 * @li <b>New</b> (2014): Built in sleep mode using interrupts. (Still under development. (Enable via RF24Network_config.h))
akashvibhute 2:a5f8e04bd02b 925 * @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.
akashvibhute 0:c3db0798d9aa 926 * @li Host Addressing. Each node has a logical address on the local network.
akashvibhute 0:c3db0798d9aa 927 * @li Message Forwarding. Messages can be sent from one node to any other, and
akashvibhute 0:c3db0798d9aa 928 * this layer will get them there no matter how many hops it takes.
akashvibhute 0:c3db0798d9aa 929 * @li Ad-hoc Joining. A node can join a network without any changes to any
akashvibhute 0:c3db0798d9aa 930 * existing nodes.
akashvibhute 0:c3db0798d9aa 931 *
akashvibhute 2:a5f8e04bd02b 932 * The layer does not provide:
akashvibhute 2:a5f8e04bd02b 933 * @li Dynamic address assignment. (See RF24Mesh)
akashvibhute 2:a5f8e04bd02b 934 * @li Layer 4 protocols (TCP/IP - See RF24Ethernet and RF24toTUN)
akashvibhute 0:c3db0798d9aa 935 *
akashvibhute 0:c3db0798d9aa 936 * @section More How to learn more
akashvibhute 0:c3db0798d9aa 937 *
akashvibhute 0:c3db0798d9aa 938 * @li <a href="classRF24Network.html">RF24Network Class Documentation</a>
akashvibhute 2:a5f8e04bd02b 939 * @li <a href="AdvancedConfig.html"> Advanced Configuration Options</a>
akashvibhute 2:a5f8e04bd02b 940 * @li <a href="Addressing.html"> Addressing format</a>
akashvibhute 2:a5f8e04bd02b 941 * @li <a href="Tuning.html"> Topology and Overview</a>
akashvibhute 2:a5f8e04bd02b 942 * @li <a href="https://github.com/TMRh20/RF24Network/archive/Development.zip">Download Current Development Package</a>
akashvibhute 2:a5f8e04bd02b 943 * @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>.
akashvibhute 0:c3db0798d9aa 944 *
akashvibhute 4:75c5aa56411f 945 * <b> Additional Information & Add-ons </b>
akashvibhute 2:a5f8e04bd02b 946 * @li <a href="https://github.com/TMRh20/RF24Mesh">RF24Mesh: Dynamic Mesh Layer for RF24Network Dev</a>
akashvibhute 2:a5f8e04bd02b 947 * @li <a href="https://github.com/TMRh20/RF24Ethernet">RF24Ethernet: TCP/IP over RF24Network</a>
akashvibhute 2:a5f8e04bd02b 948 * @li <a href="http://tmrh20.blogspot.com/2014/03/high-speed-data-transfers-and-wireless.html">My Blog: RF24 Optimization Overview</a>
akashvibhute 2:a5f8e04bd02b 949 * @li <a href="http://tmrh20.blogspot.com/2014/03/arduino-radiointercomwireless-audio.html">My Blog: RF24 Wireless Audio</a>
akashvibhute 2:a5f8e04bd02b 950 * @li <a href="http://maniacbug.github.com/RF24/">RF24: Original Author</a>
akashvibhute 0:c3db0798d9aa 951 * @section Topology Topology for Mesh Networks using nRF24L01(+)
akashvibhute 0:c3db0798d9aa 952 *
akashvibhute 0:c3db0798d9aa 953 * This network layer takes advantage of the fundamental capability of the nRF24L01(+) radio to
akashvibhute 2:a5f8e04bd02b 954 * listen actively to up to 6 other radios at once. The network is arranged in a
akashvibhute 0:c3db0798d9aa 955 * <a href="http://en.wikipedia.org/wiki/Network_Topology#Tree">Tree Topology</a>, where
akashvibhute 0:c3db0798d9aa 956 * one node is the base, and all other nodes are children either of that node, or of another.
akashvibhute 0:c3db0798d9aa 957 * Unlike a true mesh network, multiple nodes are not connected together, so there is only one
akashvibhute 0:c3db0798d9aa 958 * path to any given node.
akashvibhute 0:c3db0798d9aa 959 *
akashvibhute 2:a5f8e04bd02b 960 * @section Octal Octal Addressing and Topology
akashvibhute 0:c3db0798d9aa 961 *
akashvibhute 0:c3db0798d9aa 962 * Each node must be assigned an 15-bit address by the administrator. This address exactly
akashvibhute 0:c3db0798d9aa 963 * describes the position of the node within the tree. The address is an octal number. Each
akashvibhute 0:c3db0798d9aa 964 * digit in the address represents a position in the tree further from the base.
akashvibhute 0:c3db0798d9aa 965 *
akashvibhute 0:c3db0798d9aa 966 * @li Node 00 is the base node.
akashvibhute 0:c3db0798d9aa 967 * @li Nodes 01-05 are nodes whose parent is the base.
akashvibhute 0:c3db0798d9aa 968 * @li Node 021 is the second child of node 01.
akashvibhute 0:c3db0798d9aa 969 * @li Node 0321 is the third child of node 021, an so on.
akashvibhute 0:c3db0798d9aa 970 * @li The largest node address is 05555, so 3,125 nodes are allowed on a single channel.
akashvibhute 2:a5f8e04bd02b 971 * An example topology is shown below, with 5 nodes in direct communication with the master node,
akashvibhute 2:a5f8e04bd02b 972 * and multiple leaf nodes spread out at a distance, using intermediate nodes to reach other nodes.
akashvibhute 2:a5f8e04bd02b 973 *
akashvibhute 2:a5f8e04bd02b 974 *| | | 00 | | | 00 | | | | Master Node (00) |
akashvibhute 2:a5f8e04bd02b 975 *|---|----|----|----|----|----|----|----|----|-----------------------------------------------------|
akashvibhute 2:a5f8e04bd02b 976 *| | | 01 | | | 04 | | | | 1st level children of master (00) |
akashvibhute 2:a5f8e04bd02b 977 *| | 011| | 021| | |014 | | | 2nd level children of master. Children of 1st level.|
akashvibhute 2:a5f8e04bd02b 978 *|111| | | 121| 221| | | 114| | 3rd level children of master. Children of 2nd level.|
akashvibhute 2:a5f8e04bd02b 979 *| | | | |1221| |1114|2114|3114| 4th level children of master. Children of 3rd level.|
akashvibhute 0:c3db0798d9aa 980 *
akashvibhute 0:c3db0798d9aa 981 * @section Routing How routing is handled
akashvibhute 0:c3db0798d9aa 982 *
akashvibhute 0:c3db0798d9aa 983 * When sending a message using RF24Network::write(), you fill in the header with the logical
akashvibhute 0:c3db0798d9aa 984 * node address. The network layer figures out the right path to find that node, and sends
akashvibhute 0:c3db0798d9aa 985 * it through the system until it gets to the right place. This works even if the two nodes
akashvibhute 0:c3db0798d9aa 986 * are far separated, as it will send the message down to the base node, and then back out
akashvibhute 0:c3db0798d9aa 987 * to the final destination.
akashvibhute 0:c3db0798d9aa 988 *
akashvibhute 0:c3db0798d9aa 989 * All of this work is handled by the RF24Network::update() method, so be sure to call it
akashvibhute 0:c3db0798d9aa 990 * regularly or your network will miss packets.
akashvibhute 0:c3db0798d9aa 991 *
akashvibhute 0:c3db0798d9aa 992 * @section Startup Starting up a node
akashvibhute 0:c3db0798d9aa 993 *
akashvibhute 0:c3db0798d9aa 994 * When a node starts up, it only has to contact its parent to establish communication.
akashvibhute 0:c3db0798d9aa 995 * No direct connection to the Base node is needed. This is useful in situations where
akashvibhute 0:c3db0798d9aa 996 * relay nodes are being used to bridge the distance to the base, so leaf nodes are out
akashvibhute 0:c3db0798d9aa 997 * of range of the base.
akashvibhute 0:c3db0798d9aa 998 *
akashvibhute 2:a5f8e04bd02b 999 * @section Directionality Directionality
akashvibhute 0:c3db0798d9aa 1000 *
akashvibhute 0:c3db0798d9aa 1001 * By default all nodes are always listening, so messages will quickly reach
akashvibhute 2:a5f8e04bd02b 1002 * their destination.
akashvibhute 2:a5f8e04bd02b 1003 *
akashvibhute 2:a5f8e04bd02b 1004 * You may choose to sleep any nodes on the network if using interrupts. This is useful in a
akashvibhute 2:a5f8e04bd02b 1005 * case where the nodes are operating on batteries and need to sleep. This greatly decreases
akashvibhute 2:a5f8e04bd02b 1006 * the power requirements for a sensor network. The leaf nodes can sleep most of the time,
akashvibhute 2:a5f8e04bd02b 1007 * and wake every few minutes to send in a reading. Routing nodes can be triggered to wake up
akashvibhute 2:a5f8e04bd02b 1008 * whenever a payload is received See sleepNode() in the class documentation, and RFNetwork_config.h
akashvibhute 2:a5f8e04bd02b 1009 * to enable sleep mode.
akashvibhute 2:a5f8e04bd02b 1010 *
akashvibhute 2:a5f8e04bd02b 1011 *
akashvibhute 2:a5f8e04bd02b 1012 * @page Addressing Addressing Format: Understanding Addressing and Topology
akashvibhute 2:a5f8e04bd02b 1013 * An overview of addressing in RF24Network
akashvibhute 2:a5f8e04bd02b 1014 *
akashvibhute 2:a5f8e04bd02b 1015 * @section Overview Overview
akashvibhute 2:a5f8e04bd02b 1016 * The nrf24 radio modules typically use a 40-bit address format, requiring 5-bytes of storage space per address, and allowing a wide
akashvibhute 4:75c5aa56411f 1017 * array of addresses to be utilized. In addition, the radios are limited to direct communication with 6 other nodes while using the
akashvibhute 4:75c5aa56411f 1018 * Enhanced-Shock-Burst (ESB) functionality of the radios.
akashvibhute 2:a5f8e04bd02b 1019 *
akashvibhute 2:a5f8e04bd02b 1020 * RF24Network uses a simple method of data compression to store the addresses using only 2 bytes, in a format designed to represent the
akashvibhute 2:a5f8e04bd02b 1021 * network topology in an intuitive way.
akashvibhute 2:a5f8e04bd02b 1022 * See the <a href="Tuning.html"> Topology and Overview</a> page for more info regarding topology.
akashvibhute 2:a5f8e04bd02b 1023 *
akashvibhute 2:a5f8e04bd02b 1024 * @section Octal_Binary Decimal, Octal and Binary formats
akashvibhute 4:75c5aa56411f 1025 *
akashvibhute 2:a5f8e04bd02b 1026 * Say we want to designate a logical address to a node, using a tree topology as defined by the manufacturer.
akashvibhute 4:75c5aa56411f 1027 * In the simplest format, we could assign the first node the address of 1, the second 2 and so on.
akashvibhute 2:a5f8e04bd02b 1028 * 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>
akashvibhute 2:a5f8e04bd02b 1029 * In this case the children of node 1 could simply be designated as 11,21,31,41, and 51<br>
akashvibhute 4:75c5aa56411f 1030 * Children of node 2 could be designated as 12,22,32,42, and 52
akashvibhute 4:75c5aa56411f 1031 *
akashvibhute 2:a5f8e04bd02b 1032 * The above example is exactly how RF24Network manages the addresses, but they are represented in Octal format.
akashvibhute 4:75c5aa56411f 1033 *
akashvibhute 4:75c5aa56411f 1034 * <b>Decimal, Octal and Binary</b>
akashvibhute 4:75c5aa56411f 1035 * <table>
akashvibhute 2:a5f8e04bd02b 1036 * <tr bgcolor="#a3b4d7" >
akashvibhute 2:a5f8e04bd02b 1037 * <td> Decimal </td> <td> Binary </td><td> Decimal </td> <td> Binary </td><td> Decimal </td> <td> Binary </td>
akashvibhute 2:a5f8e04bd02b 1038 * </tr><tr>
akashvibhute 2:a5f8e04bd02b 1039 * <td> 1 </td> <td> 00000001 </td><td> 11 </td> <td> 00001011 </td><td> 111 </td> <td> 01101111 </td>
akashvibhute 2:a5f8e04bd02b 1040 * </tr><tr bgcolor="#a3b4d7" >
akashvibhute 2:a5f8e04bd02b 1041 * <td> Octal </td> <td> Binary </td><td> Octal </td> <td> Binary </td><td> Octal </td> <td> Binary </td>
akashvibhute 2:a5f8e04bd02b 1042 * </tr><tr>
akashvibhute 2:a5f8e04bd02b 1043 * <td> 1 </td> <td> 00000001 </td><td> 011 </td> <td> 00001001 </td><td> 0111 </td> <td> 1001001 </td>
akashvibhute 2:a5f8e04bd02b 1044 * </tr>
akashvibhute 2:a5f8e04bd02b 1045 * </table>
akashvibhute 2:a5f8e04bd02b 1046 *
akashvibhute 4:75c5aa56411f 1047 *
akashvibhute 4:75c5aa56411f 1048 * 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.
akashvibhute 4:75c5aa56411f 1049 * This allows a very simple method of managing addresses via masking and bit shifting.
akashvibhute 4:75c5aa56411f 1050 *
akashvibhute 2:a5f8e04bd02b 1051 * @section DisplayAddresses Displaying Addresses
akashvibhute 2:a5f8e04bd02b 1052 *
akashvibhute 2:a5f8e04bd02b 1053 * When using Arduino devices, octal addresses can be printed in the following manner:
akashvibhute 2:a5f8e04bd02b 1054 * @code
akashvibhute 4:75c5aa56411f 1055 * uint16_t address = 0111;
akashvibhute 2:a5f8e04bd02b 1056 * Serial.println(address,OCT);
akashvibhute 2:a5f8e04bd02b 1057 * @endcode
akashvibhute 2:a5f8e04bd02b 1058 *
akashvibhute 2:a5f8e04bd02b 1059 * Printf can also be used, if enabled, or if using linux/RPi
akashvibhute 2:a5f8e04bd02b 1060 * @code
akashvibhute 2:a5f8e04bd02b 1061 * uint16_t address = 0111;
akashvibhute 2:a5f8e04bd02b 1062 * printf("0%o\n",address);
akashvibhute 2:a5f8e04bd02b 1063 * @endcode
akashvibhute 2:a5f8e04bd02b 1064 *
akashvibhute 2:a5f8e04bd02b 1065 * See http://www.cplusplus.com/doc/hex/ for more information<br>
akashvibhute 4:75c5aa56411f 1066 * See the <a href="Tuning.html"> Topology and Overview</a> page for more info regarding topology.
akashvibhute 2:a5f8e04bd02b 1067 *
akashvibhute 2:a5f8e04bd02b 1068 * @page AdvancedConfig Advanced Configuration
akashvibhute 2:a5f8e04bd02b 1069 *
akashvibhute 2:a5f8e04bd02b 1070 * RF24Network offers many features, some of which can be configured by editing the RF24Network_config.h file
akashvibhute 2:a5f8e04bd02b 1071 *
akashvibhute 2:a5f8e04bd02b 1072 * | Configuration Option | Description |
akashvibhute 2:a5f8e04bd02b 1073 * |----------------------|-------------|
akashvibhute 2:a5f8e04bd02b 1074 * |<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 |
akashvibhute 2:a5f8e04bd02b 1075 * | <b> #define DISABLE_FRAGMENTATION </b> | Fragmentation is enabled by default, and uses an additional 144 bytes of memory. |
akashvibhute 2:a5f8e04bd02b 1076 * | <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) |
akashvibhute 2:a5f8e04bd02b 1077 * | <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 |
akashvibhute 2:a5f8e04bd02b 1078 * | <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) |
akashvibhute 2:a5f8e04bd02b 1079 * | <b> #define ENABLE_SLEEP_MODE </b> | Uncomment this option to enable sleep mode for AVR devices. (ATTiny,Uno, etc) |
akashvibhute 2:a5f8e04bd02b 1080 * | <b> #define DUAL_HEAD_RADIO </b> | Uncomment this option to enable use of dual radios |
akashvibhute 2:a5f8e04bd02b 1081 * | **#define ENABLE_NETWORK_STATS** | Enable counting of all successful or failed transmissions, routed or sent directly |
akashvibhute 2:a5f8e04bd02b 1082 *
akashvibhute 2:a5f8e04bd02b 1083 ** @page Tuning Performance and Data Loss: Tuning the Network
akashvibhute 2:a5f8e04bd02b 1084 * Tips and examples for tuning the network and general operation.
akashvibhute 2:a5f8e04bd02b 1085 *
akashvibhute 2:a5f8e04bd02b 1086 * <img src="tmrh20/topologyImage.jpg" alt="Topology" height="75%" width="75%">
akashvibhute 2:a5f8e04bd02b 1087 *
akashvibhute 2:a5f8e04bd02b 1088 * @section General Understanding Radio Communication and Topology
akashvibhute 2:a5f8e04bd02b 1089 * When a transmission takes place from one radio module to another, the receiving radio will communicate
akashvibhute 2:a5f8e04bd02b 1090 * back to the sender with an acknowledgement (ACK) packet, to indicate success. If the sender does not
akashvibhute 4:75c5aa56411f 1091 * receive an ACK, the radio automatically engages in a series of timed retries, at set intervals. The
akashvibhute 4:75c5aa56411f 1092 * radios use techniques like addressing and numbering of payloads to manage this, but it is all done
akashvibhute 2:a5f8e04bd02b 1093 * automatically by the nrf chip, out of sight from the user.
akashvibhute 2:a5f8e04bd02b 1094 *
akashvibhute 2:a5f8e04bd02b 1095 * When working over a radio network, some of these automated techniques can actually hinder data transmission to a degree.
akashvibhute 4:75c5aa56411f 1096 * Retrying failed payloads over and over on a radio network can hinder communication for nearby nodes, or
akashvibhute 2:a5f8e04bd02b 1097 * reduce throughput and errors on routing nodes.
akashvibhute 2:a5f8e04bd02b 1098 *
akashvibhute 2:a5f8e04bd02b 1099 * Radios in this network are linked by <b>addresses</b> assigned to <b>pipes</b>. Each radio can listen
akashvibhute 2:a5f8e04bd02b 1100 * to 6 addresses on 6 pipes, therefore each radio has a parent pipe and 5 child pipes, which are used
akashvibhute 2:a5f8e04bd02b 1101 * to form a tree structure. Nodes communicate directly with their parent and children nodes. Any other
akashvibhute 2:a5f8e04bd02b 1102 * traffic to or from a node must be routed through the network.
akashvibhute 2:a5f8e04bd02b 1103 *
akashvibhute 2:a5f8e04bd02b 1104 * @section Topology Topology of RF24Network
akashvibhute 2:a5f8e04bd02b 1105 *
akashvibhute 2:a5f8e04bd02b 1106 * Anybody who is familiar at all with IP networking should be able to easily understand RF24Network topology. The
akashvibhute 2:a5f8e04bd02b 1107 * master node can be seen as the gateway, with up to 4 directly connected nodes. Each of those nodes creates a
akashvibhute 2:a5f8e04bd02b 1108 * subnet below it, with up to 4 additional child nodes. The numbering scheme can also be related to IP addresses,
akashvibhute 2:a5f8e04bd02b 1109 * for purposes of understanding the topology via subnetting. Nodes can have 5 children if multicast is disabled.
akashvibhute 2:a5f8e04bd02b 1110 *
akashvibhute 4:75c5aa56411f 1111 * Expressing RF24Network addresses in IP format:
akashvibhute 2:a5f8e04bd02b 1112 *
akashvibhute 4:75c5aa56411f 1113 * As an example, we could designate the master node in theory, as Address 10.10.10.10 <br>
akashvibhute 4:75c5aa56411f 1114 * 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>
akashvibhute 4:75c5aa56411f 1115 * 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>
akashvibhute 4:75c5aa56411f 1116 *
akashvibhute 2:a5f8e04bd02b 1117 * In RF24Network, the master is just 00 <br>
akashvibhute 2:a5f8e04bd02b 1118 * Children of master are 01,02,03,04,05 <br>
akashvibhute 2:a5f8e04bd02b 1119 * Children of 01 are 011,021,031,041,051 <br>
akashvibhute 4:75c5aa56411f 1120 *
akashvibhute 2:a5f8e04bd02b 1121 * @section Network Routing
akashvibhute 2:a5f8e04bd02b 1122 *
akashvibhute 2:a5f8e04bd02b 1123 * Routing of traffic is handled invisibly to the user, by the network layer. If the network addresses are
akashvibhute 2:a5f8e04bd02b 1124 * assigned in accordance with the physical layout of the network, nodes will route traffic automatically
akashvibhute 2:a5f8e04bd02b 1125 * as required. Users simply constuct a header containing the appropriate destination address, and the network
akashvibhute 2:a5f8e04bd02b 1126 * will forward it through to the correct node. Individual nodes only route individual fragments, so if using
akashvibhute 2:a5f8e04bd02b 1127 * fragmentation, routing nodes do not need it enabled, unless sending or receiving fragmented payloads themselves.
akashvibhute 2:a5f8e04bd02b 1128 *
akashvibhute 2:a5f8e04bd02b 1129 * If routing data between parent and child nodes (marked by direct links on the topology image above) the network
akashvibhute 2:a5f8e04bd02b 1130 * uses built-in acknowledgement and retry functions of the chip to prevent data loss. When payloads are sent to
akashvibhute 2:a5f8e04bd02b 1131 * other nodes, they need to be routed. Routing is managed using a combination of built in ACK requests, and
akashvibhute 2:a5f8e04bd02b 1132 * software driven network ACKs. This allows all routing nodes to forward data very quickly, with only the final
akashvibhute 2:a5f8e04bd02b 1133 * routing node confirming delivery and sending back an
akashvibhute 2:a5f8e04bd02b 1134 * acknowledgement.
akashvibhute 2:a5f8e04bd02b 1135 *
akashvibhute 2:a5f8e04bd02b 1136 * Example: Node 00 sends to node 01. The nodes will use the built in auto-retry and auto-ack functions.<br>
akashvibhute 2:a5f8e04bd02b 1137 * Example: Node 00 sends to node 011. Node 00 will send to node 01 as before. Node 01 will forward the message to
akashvibhute 2:a5f8e04bd02b 1138 * 011. If delivery was successful, node 01 will also forward a message back to node 00, indicating success.
akashvibhute 2:a5f8e04bd02b 1139 *
akashvibhute 2:a5f8e04bd02b 1140 * Old Functionality: Node 00 sends to node 011 using auto-ack. Node 00 first sends to 01, 01 acknowledges.
akashvibhute 2:a5f8e04bd02b 1141 * Node 01 forwards the payload to 011 using auto-ack. If the payload fails between 01 and 011, node 00 has
akashvibhute 4:75c5aa56411f 1142 * no way of knowing.
akashvibhute 4:75c5aa56411f 1143 *
akashvibhute 2:a5f8e04bd02b 1144 * @note When retrying failed payloads that have been routed, there is a chance of duplicate payloads if the network-ack
akashvibhute 2:a5f8e04bd02b 1145 * is not successful. In this case, it is left up to the user to manage retries and filtering of duplicate payloads.
akashvibhute 2:a5f8e04bd02b 1146 *
akashvibhute 2:a5f8e04bd02b 1147 * Acknowledgements can and should be managed by the application or user. If requesting a response from another node,
akashvibhute 2:a5f8e04bd02b 1148 * an acknowledgement is not required, so a user defined type of 0-64 should be used, to prevent the network from
akashvibhute 2:a5f8e04bd02b 1149 * responding with an acknowledgement. If not requesting a response, and wanting to know if the payload was successful
akashvibhute 2:a5f8e04bd02b 1150 * or not, users can utilize header types 65-127.
akashvibhute 4:75c5aa56411f 1151 *
akashvibhute 2:a5f8e04bd02b 1152 * @section TuningOverview Tuning Overview
akashvibhute 2:a5f8e04bd02b 1153 * The RF24 radio modules are generally only capable of either sending or receiving data at any given
akashvibhute 2:a5f8e04bd02b 1154 * time, but have built-in auto-retry mechanisms to prevent the loss of data. These values are adjusted
akashvibhute 2:a5f8e04bd02b 1155 * automatically by the library on startup, but can be further adjusted to reduce data loss, and
akashvibhute 2:a5f8e04bd02b 1156 * thus increase throughput of the network. This page is intended to provide a general overview of its
akashvibhute 2:a5f8e04bd02b 1157 * operation within the context of the network library, and provide guidance for adjusting these values.
akashvibhute 2:a5f8e04bd02b 1158 *
akashvibhute 2:a5f8e04bd02b 1159 * @section RetryTiming Auto-Retry Timing
akashvibhute 2:a5f8e04bd02b 1160 *
akashvibhute 2:a5f8e04bd02b 1161 * The core radio library provides the functionality of adjusting the internal auto-retry interval of the
akashvibhute 2:a5f8e04bd02b 1162 * radio modules. In the network configuration, the radios can be set to automatically retry failed
akashvibhute 2:a5f8e04bd02b 1163 * transmissions at intervals ranging anywhere from 500us (.5ms) up to 4000us (4ms). When operating any
akashvibhute 2:a5f8e04bd02b 1164 * number of radios larger than two, it is important to stagger the assigned intervals, to prevent the
akashvibhute 2:a5f8e04bd02b 1165 * radios from interfering with each other at the radio frequency (RF) layer.
akashvibhute 2:a5f8e04bd02b 1166 *
akashvibhute 2:a5f8e04bd02b 1167 * The library should provide fairly good working values, as it simply staggers the assigned values within
akashvibhute 2:a5f8e04bd02b 1168 * groups of radios in direct communication. This value can be set manually by calling radio.setRetries(X,15);
akashvibhute 2:a5f8e04bd02b 1169 * and adjusting the value of X from 1 to 15 (steps of 250us).
akashvibhute 2:a5f8e04bd02b 1170 *
akashvibhute 2:a5f8e04bd02b 1171 * @section AutoRetry Auto-Retry Count and Extended Timeouts
akashvibhute 2:a5f8e04bd02b 1172 *
akashvibhute 2:a5f8e04bd02b 1173 * The core radio library also provides the ability to adjust the internal auto-retry count of the radio
akashvibhute 2:a5f8e04bd02b 1174 * modules. The default setting is 15 automatic retries per payload, and can be extended by configuring
akashvibhute 2:a5f8e04bd02b 1175 * the network.txTimeout variable. This default retry count should generally be left at 15, as per the
akashvibhute 2:a5f8e04bd02b 1176 * example in the above section. An interval/retry setting of (15,15) will provide 15 retrys at intervals of
akashvibhute 2:a5f8e04bd02b 1177 * 4ms, taking up to 60ms per payload. The library now provides staggered timeout periods by default, but
akashvibhute 2:a5f8e04bd02b 1178 * they can also be adjusted on a per-node basis.
akashvibhute 0:c3db0798d9aa 1179 *
akashvibhute 2:a5f8e04bd02b 1180 * The txTimeout variable is used to extend the retry count to a defined duration in milliseconds. See the
akashvibhute 2:a5f8e04bd02b 1181 * network.txTimeout variable. Timeout periods of extended duration (500+) will generally not help when payloads
akashvibhute 2:a5f8e04bd02b 1182 * are failing due to data collisions, it will only extend the duration of the errors. Extended duration timeouts
akashvibhute 2:a5f8e04bd02b 1183 * should generally only be configured on leaf nodes that do not receive data, or on a dual-headed node.
akashvibhute 2:a5f8e04bd02b 1184 *
akashvibhute 2:a5f8e04bd02b 1185 * @section Examples
akashvibhute 2:a5f8e04bd02b 1186 *
akashvibhute 2:a5f8e04bd02b 1187 * <b>Example 1:</b> Network with master node and three leaf nodes that send data to the master node. None of the leaf
akashvibhute 2:a5f8e04bd02b 1188 * nodes need to receive data.
akashvibhute 2:a5f8e04bd02b 1189 *
akashvibhute 2:a5f8e04bd02b 1190 * a: Master node uses default configuration<br>
akashvibhute 2:a5f8e04bd02b 1191 * b: Leaf nodes can be configured with extended timeout periods to ensure reception by the master.<br>
akashvibhute 2:a5f8e04bd02b 1192 * c:
akashvibhute 2:a5f8e04bd02b 1193 * @code
akashvibhute 2:a5f8e04bd02b 1194 * Leaf 01: network.txTimeout = 500; Leaf 02: network.txTimeout = 573; Leaf 03: network.txTimeout = 653;
akashvibhute 2:a5f8e04bd02b 1195 * @endcode
akashvibhute 2:a5f8e04bd02b 1196 * This configuration will provide a reduction in errors, as the timeouts have been extended, and are staggered
akashvibhute 2:a5f8e04bd02b 1197 * between devices.
akashvibhute 2:a5f8e04bd02b 1198 *
akashvibhute 2:a5f8e04bd02b 1199 *
akashvibhute 2:a5f8e04bd02b 1200 * <b>Example 2:</b> Network with master node and three leaf nodes that send data to the master node. The second leaf
akashvibhute 2:a5f8e04bd02b 1201 * node needs to receive configuration data from the master at set intervals of 1 second, and send data back to the
akashvibhute 2:a5f8e04bd02b 1202 * master node. The other leaf nodes will send basic sensor information every few seconds, and a few dropped payloads
akashvibhute 2:a5f8e04bd02b 1203 * will not affect the operation greatly.
akashvibhute 2:a5f8e04bd02b 1204 *
akashvibhute 2:a5f8e04bd02b 1205 * a: Master node configured with extended timeouts of .5 seconds, and increased retry delay:
akashvibhute 2:a5f8e04bd02b 1206 * @code
akashvibhute 4:75c5aa56411f 1207 * radio.setRetries(11,15);
akashvibhute 4:75c5aa56411f 1208 * network.txTimeout = 500;
akashvibhute 4:75c5aa56411f 1209 * @endcode
akashvibhute 2:a5f8e04bd02b 1210 * b: Second leaf node configured with a similar timeout period and retry delay:
akashvibhute 2:a5f8e04bd02b 1211 * @code
akashvibhute 4:75c5aa56411f 1212 * radio.setRetries(8,15);
akashvibhute 4:75c5aa56411f 1213 * network.txTimeout = 553;
akashvibhute 2:a5f8e04bd02b 1214 * @endcode
akashvibhute 2:a5f8e04bd02b 1215 * c: First and third leaf nodes configured with default timeout periods or slightly increased timout periods.
akashvibhute 2:a5f8e04bd02b 1216 *
akashvibhute 2:a5f8e04bd02b 1217 * @section DualHead Dual Headed Operation
akashvibhute 2:a5f8e04bd02b 1218 *
akashvibhute 2:a5f8e04bd02b 1219 * The library now supports a dual radio configuration to further enhance network performance, while reducing errors on
akashvibhute 2:a5f8e04bd02b 1220 * busy networks. Master nodes or relay nodes with a large number of child nodes can benefit somewhat from a dual headed
akashvibhute 2:a5f8e04bd02b 1221 * configuration, since one radio is used for receiving, and the other entirely for transmission.
akashvibhute 2:a5f8e04bd02b 1222 *
akashvibhute 2:a5f8e04bd02b 1223 * To configure a dual headed node:
akashvibhute 2:a5f8e04bd02b 1224 * 1. Edit the RF24Network_config.h file, and uncomment #define DUAL_HEAD_RADIO
akashvibhute 2:a5f8e04bd02b 1225 * 2. Connect another radio, using the same MOSI, MISO, and SCK lines.
akashvibhute 2:a5f8e04bd02b 1226 * 3. Choose another two pins to use for CE and CS on the second radio. Connect them.
akashvibhute 2:a5f8e04bd02b 1227 * 4. Setup the radio and network like so:
akashvibhute 2:a5f8e04bd02b 1228 *
akashvibhute 2:a5f8e04bd02b 1229 * @code
akashvibhute 4:75c5aa56411f 1230 * RF24 radio(7,8); // Using CE (7) and CS (8) for first radio
akashvibhute 4:75c5aa56411f 1231 * RF24 radio1(4,5); // Using CE (4) and CS (5) for second radio
akashvibhute 4:75c5aa56411f 1232 * RF24Network network(radio,radio1); // Set up the network using both radios
akashvibhute 2:a5f8e04bd02b 1233 *
akashvibhute 2:a5f8e04bd02b 1234 * Then in setup(), call radio.begin(); and radio1.begin(); before network.begin();
akashvibhute 2:a5f8e04bd02b 1235 * @endcode
akashvibhute 2:a5f8e04bd02b 1236 *
akashvibhute 2:a5f8e04bd02b 1237 * 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.
akashvibhute 2:a5f8e04bd02b 1238 * 6. Re-comment the #define in the config file as required if configuring other single-headed radios.
akashvibhute 2:a5f8e04bd02b 1239 *
akashvibhute 2:a5f8e04bd02b 1240 *
akashvibhute 2:a5f8e04bd02b 1241 * Any node can be configured in dual-head mode.
akashvibhute 2:a5f8e04bd02b 1242 *
akashvibhute 2:a5f8e04bd02b 1243 *
akashvibhute 2:a5f8e04bd02b 1244 *
akashvibhute 0:c3db0798d9aa 1245 *
akashvibhute 0:c3db0798d9aa 1246 * @page Zigbee Comparison to ZigBee
akashvibhute 0:c3db0798d9aa 1247 *
akashvibhute 0:c3db0798d9aa 1248 * This network layer is influenced by the design of ZigBee, but does not implement it
akashvibhute 2:a5f8e04bd02b 1249 * directly.
akashvibhute 0:c3db0798d9aa 1250 *
akashvibhute 0:c3db0798d9aa 1251 * @section Advantage Which is better?
akashvibhute 0:c3db0798d9aa 1252 *
akashvibhute 0:c3db0798d9aa 1253 * ZigBee is a much more robust, feature-rich set of protocols, with many different vendors
akashvibhute 0:c3db0798d9aa 1254 * providing compatible chips.
akashvibhute 0:c3db0798d9aa 1255 *
akashvibhute 0:c3db0798d9aa 1256 * RF24Network is cheap. While ZigBee radios are well over $20, nRF24L01 modules can be found
akashvibhute 2:a5f8e04bd02b 1257 * for under $2. My personal favorite is
akashvibhute 0:c3db0798d9aa 1258 * <a href="http://www.mdfly.com/index.php?main_page=product_info&products_id=82">MDFly RF-IS2401</a>.
akashvibhute 0:c3db0798d9aa 1259 *
akashvibhute 0:c3db0798d9aa 1260 * @section Contrast Similiarities & Differences
akashvibhute 0:c3db0798d9aa 1261 *
akashvibhute 0:c3db0798d9aa 1262 * Here are some comparisons between RF24Network and ZigBee.
akashvibhute 0:c3db0798d9aa 1263 *
akashvibhute 0:c3db0798d9aa 1264 * @li Both networks support Star and Tree topologies. Only Zigbee supports a true mesh.
akashvibhute 2:a5f8e04bd02b 1265 * @li In ZigBee networks, only leaf nodes can sleep
akashvibhute 2:a5f8e04bd02b 1266 * @li ZigBee nodes are configured using AT commands, or a separate Windows application.
akashvibhute 0:c3db0798d9aa 1267 * RF24 nodes are configured by recompiliing the firmware or writing to EEPROM.
akashvibhute 0:c3db0798d9aa 1268 *
akashvibhute 0:c3db0798d9aa 1269 * @section NodeNames Node Naming
akashvibhute 0:c3db0798d9aa 1270 *
akashvibhute 0:c3db0798d9aa 1271 * @li Leaf node: A node at the outer edge of the network with no children. ZigBee calls it
akashvibhute 0:c3db0798d9aa 1272 * an End Device node.
akashvibhute 0:c3db0798d9aa 1273 * @li Relay node: A node which has both parents and children, and relays messages from one
akashvibhute 0:c3db0798d9aa 1274 * to the other. ZigBee calls it a Router.
akashvibhute 0:c3db0798d9aa 1275 * @li Base node. The top of the tree node with no parents, only children. Typically this node
akashvibhute 0:c3db0798d9aa 1276 * will bridge to another kind of network like Ethernet. ZigBee calls it a Co-ordinator node.
akashvibhute 2:a5f8e04bd02b 1277 *
akashvibhute 4:75c5aa56411f 1278 *
akashvibhute 2:a5f8e04bd02b 1279 *
akashvibhute 2:a5f8e04bd02b 1280 *
akashvibhute 0:c3db0798d9aa 1281 */
akashvibhute 0:c3db0798d9aa 1282
akashvibhute 0:c3db0798d9aa 1283 #endif // __RF24NETWORK_H__
akashvibhute 2:a5f8e04bd02b 1284
akashvibhute 4:75c5aa56411f 1285
akashvibhute 4:75c5aa56411f 1286