RH_NRF24.h

00001 // RH_NRF24.h
00002 // Author: Mike McCauley
00003 // Copyright (C) 2012 Mike McCauley
00004 // $Id: RH_NRF24.h,v 1.16 2015/08/13 02:45:47 mikem Exp $
00005 //
00006 
00007 #ifndef RH_NRF24_h
00008 #define RH_NRF24_h
00009 
00010 #include <RHGenericSPI.h>
00011 #include <RHNRFSPIDriver.h>
00012 
00013 // This is the maximum number of bytes that can be carried by the nRF24.
00014 // We use some for headers, keeping fewer for RadioHead messages
00015 #define RH_NRF24_MAX_PAYLOAD_LEN 32
00016 
00017 // The length of the headers we add.
00018 // The headers are inside the nRF24 payload
00019 #define RH_NRF24_HEADER_LEN 4
00020 
00021 // This is the maximum RadioHead user message length that can be supported by this library. Limited by
00022 // the supported message lengths in the nRF24
00023 #define RH_NRF24_MAX_MESSAGE_LEN (RH_NRF24_MAX_PAYLOAD_LEN-RH_NRF24_HEADER_LEN)
00024 
00025 // SPI Command names
00026 #define RH_NRF24_COMMAND_R_REGISTER                        0x00
00027 #define RH_NRF24_COMMAND_W_REGISTER                        0x20
00028 #define RH_NRF24_COMMAND_ACTIVATE                          0x50 // only on RFM73 ?
00029 #define RH_NRF24_COMMAND_R_RX_PAYLOAD                      0x61
00030 #define RH_NRF24_COMMAND_W_TX_PAYLOAD                      0xa0
00031 #define RH_NRF24_COMMAND_FLUSH_TX                          0xe1
00032 #define RH_NRF24_COMMAND_FLUSH_RX                          0xe2
00033 #define RH_NRF24_COMMAND_REUSE_TX_PL                       0xe3
00034 #define RH_NRF24_COMMAND_R_RX_PL_WID                       0x60
00035 #define RH_NRF24_COMMAND_W_ACK_PAYLOAD(pipe)               (0xa8|(pipe&0x7))
00036 #define RH_NRF24_COMMAND_W_TX_PAYLOAD_NOACK                0xb0
00037 #define RH_NRF24_COMMAND_NOP                               0xff
00038 
00039 // Register names
00040 #define RH_NRF24_REGISTER_MASK                             0x1f
00041 #define RH_NRF24_REG_00_CONFIG                             0x00
00042 #define RH_NRF24_REG_01_EN_AA                              0x01
00043 #define RH_NRF24_REG_02_EN_RXADDR                          0x02
00044 #define RH_NRF24_REG_03_SETUP_AW                           0x03
00045 #define RH_NRF24_REG_04_SETUP_RETR                         0x04
00046 #define RH_NRF24_REG_05_RF_CH                              0x05
00047 #define RH_NRF24_REG_06_RF_SETUP                           0x06
00048 #define RH_NRF24_REG_07_STATUS                             0x07
00049 #define RH_NRF24_REG_08_OBSERVE_TX                         0x08
00050 #define RH_NRF24_REG_09_RPD                                0x09
00051 #define RH_NRF24_REG_0A_RX_ADDR_P0                         0x0a
00052 #define RH_NRF24_REG_0B_RX_ADDR_P1                         0x0b
00053 #define RH_NRF24_REG_0C_RX_ADDR_P2                         0x0c
00054 #define RH_NRF24_REG_0D_RX_ADDR_P3                         0x0d
00055 #define RH_NRF24_REG_0E_RX_ADDR_P4                         0x0e
00056 #define RH_NRF24_REG_0F_RX_ADDR_P5                         0x0f
00057 #define RH_NRF24_REG_10_TX_ADDR                            0x10
00058 #define RH_NRF24_REG_11_RX_PW_P0                           0x11
00059 #define RH_NRF24_REG_12_RX_PW_P1                           0x12
00060 #define RH_NRF24_REG_13_RX_PW_P2                           0x13
00061 #define RH_NRF24_REG_14_RX_PW_P3                           0x14
00062 #define RH_NRF24_REG_15_RX_PW_P4                           0x15
00063 #define RH_NRF24_REG_16_RX_PW_P5                           0x16
00064 #define RH_NRF24_REG_17_FIFO_STATUS                        0x17
00065 #define RH_NRF24_REG_1C_DYNPD                              0x1c
00066 #define RH_NRF24_REG_1D_FEATURE                            0x1d
00067 
00068 // These register masks etc are named wherever possible
00069 // corresponding to the bit and field names in the nRF24L01 Product Specification
00070 // #define RH_NRF24_REG_00_CONFIG                             0x00
00071 #define RH_NRF24_MASK_RX_DR                                0x40
00072 #define RH_NRF24_MASK_TX_DS                                0x20
00073 #define RH_NRF24_MASK_MAX_RT                               0x10
00074 #define RH_NRF24_EN_CRC                                    0x08
00075 #define RH_NRF24_CRCO                                      0x04
00076 #define RH_NRF24_PWR_UP                                    0x02
00077 #define RH_NRF24_PRIM_RX                                   0x01
00078 
00079 // #define RH_NRF24_REG_01_EN_AA                              0x01
00080 #define RH_NRF24_ENAA_P5                                   0x20
00081 #define RH_NRF24_ENAA_P4                                   0x10
00082 #define RH_NRF24_ENAA_P3                                   0x08
00083 #define RH_NRF24_ENAA_P2                                   0x04
00084 #define RH_NRF24_ENAA_P1                                   0x02
00085 #define RH_NRF24_ENAA_P0                                   0x01
00086 
00087 // #define RH_NRF24_REG_02_EN_RXADDR                          0x02
00088 #define RH_NRF24_ERX_P5                                    0x20
00089 #define RH_NRF24_ERX_P4                                    0x10
00090 #define RH_NRF24_ERX_P3                                    0x08
00091 #define RH_NRF24_ERX_P2                                    0x04
00092 #define RH_NRF24_ERX_P1                                    0x02
00093 #define RH_NRF24_ERX_P0                                    0x01
00094 
00095 // #define RH_NRF24_REG_03_SETUP_AW                           0x03
00096 #define RH_NRF24_AW_3_BYTES                                0x01
00097 #define RH_NRF24_AW_4_BYTES                                0x02
00098 #define RH_NRF24_AW_5_BYTES                                0x03
00099 
00100 // #define RH_NRF24_REG_04_SETUP_RETR                         0x04
00101 #define RH_NRF24_ARD                                       0xf0
00102 #define RH_NRF24_ARC                                       0x0f
00103 
00104 // #define RH_NRF24_REG_05_RF_CH                              0x05
00105 #define RH_NRF24_RF_CH                                     0x7f
00106 
00107 // #define RH_NRF24_REG_06_RF_SETUP                           0x06
00108 #define RH_NRF24_CONT_WAVE                                 0x80
00109 #define RH_NRF24_RF_DR_LOW                                 0x20
00110 #define RH_NRF24_PLL_LOCK                                  0x10
00111 #define RH_NRF24_RF_DR_HIGH                                0x08
00112 #define RH_NRF24_PWR                                       0x06
00113 #define RH_NRF24_PWR_m18dBm                                0x00
00114 #define RH_NRF24_PWR_m12dBm                                0x02
00115 #define RH_NRF24_PWR_m6dBm                                 0x04
00116 #define RH_NRF24_PWR_0dBm                                  0x06
00117 #define RH_NRF24_LNA_HCURR                                 0x01
00118 
00119 // #define RH_NRF24_REG_07_STATUS                             0x07
00120 #define RH_NRF24_RX_DR                                     0x40
00121 #define RH_NRF24_TX_DS                                     0x20
00122 #define RH_NRF24_MAX_RT                                    0x10
00123 #define RH_NRF24_RX_P_NO                                   0x0e
00124 #define RH_NRF24_STATUS_TX_FULL                            0x01
00125 
00126 // #define RH_NRF24_REG_08_OBSERVE_TX                         0x08
00127 #define RH_NRF24_PLOS_CNT                                  0xf0
00128 #define RH_NRF24_ARC_CNT                                   0x0f
00129 
00130 // #define RH_NRF24_REG_09_RPD                                0x09
00131 #define RH_NRF24_RPD                                       0x01
00132 
00133 // #define RH_NRF24_REG_17_FIFO_STATUS                        0x17
00134 #define RH_NRF24_TX_REUSE                                  0x40
00135 #define RH_NRF24_TX_FULL                                   0x20
00136 #define RH_NRF24_TX_EMPTY                                  0x10
00137 #define RH_NRF24_RX_FULL                                   0x02
00138 #define RH_NRF24_RX_EMPTY                                  0x01
00139 
00140 // #define RH_NRF24_REG_1C_DYNPD                              0x1c
00141 #define RH_NRF24_DPL_ALL                                   0x3f
00142 #define RH_NRF24_DPL_P5                                    0x20
00143 #define RH_NRF24_DPL_P4                                    0x10
00144 #define RH_NRF24_DPL_P3                                    0x08
00145 #define RH_NRF24_DPL_P2                                    0x04
00146 #define RH_NRF24_DPL_P1                                    0x02
00147 #define RH_NRF24_DPL_P0                                    0x01
00148 
00149 // #define RH_NRF24_REG_1D_FEATURE                            0x1d
00150 #define RH_NRF24_EN_DPL                                    0x04
00151 #define RH_NRF24_EN_ACK_PAY                                0x02
00152 #define RH_NRF24_EN_DYN_ACK                                0x01
00153 
00154 
00155 /////////////////////////////////////////////////////////////////////
00156 /// \class RH_NRF24 RH_NRF24.h <RH_NRF24.h>
00157 /// \brief Send and receive addressed, reliable, acknowledged datagrams by nRF24L01 and compatible transceivers.
00158 ///
00159 /// Supported transceivers include:
00160 /// - Nordic nRF24 based 2.4GHz radio modules, such as nRF24L01 http://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01
00161 /// and other compatible transceivers. 
00162 /// - nRF24L01p with PA and LNA modules that produce a higher power output similar to this one: 
00163 /// http://www.elecfreaks.com/wiki/index.php?title=2.4G_Wireless_nRF24L01p_with_PA_and_LNA
00164 /// - Sparkfun WRL-00691 module with nRF24L01 https://www.sparkfun.com/products/691 
00165 /// or WRL-00705 https://www.sparkfun.com/products/705 etc.
00166 /// - Hope-RF RFM73 http://www.hoperf.com/rf/2.4g_module/RFM73.htm and 
00167 /// http://www.anarduino.com/details.jsp?pid=121
00168 /// and compatible devices (such as BK2423). nRF24L01 and RFM73 can interoperate
00169 /// with each other.
00170 ///
00171 /// This base class provides basic functions for sending and receiving unaddressed, unreliable datagrams
00172 /// of arbitrary length to 28 octets per packet. Use one of the Manager classes to get addressing and 
00173 /// acknowledgement reliability, routing, meshes etc.
00174 ///
00175 /// The nRF24L01 (http://www.sparkfun.com/datasheets/Wireless/Nordic/nRF24L01P_Product_Specification_1_0.pdf)
00176 /// is a low-cost 2.4GHz ISM transceiver module. It supports a number of channel frequencies in the 2.4GHz band
00177 /// and a range of data rates.
00178 ///
00179 /// This library provides functions for sending and receiving messages of up to 28 octets on any 
00180 /// frequency supported by the nRF24L01, at a selected data rate.
00181 ///
00182 /// Several nRF24L01 modules can be connected to an Arduino, permitting the construction of translators
00183 /// and frequency changers, etc.
00184 ///
00185 /// The nRF24 transceiver is configured to use Enhanced Shockburst with no acknowledgement and no retransmits.
00186 /// TX_ADDR and RX_ADDR_P0 are set to the network address. If you need the low level auto-acknowledgement
00187 /// feature supported by this chip, you can use our original NRF24 library 
00188 /// at http://www.airspayce.com/mikem/arduino/NRF24
00189 ///
00190 /// Naturally, for any 2 radios to communicate that must be configured to use the same frequency and 
00191 /// data rate, and with identical network addresses.
00192 ///
00193 /// Example Arduino programs are included to show the main modes of use.
00194 ///
00195 /// \par Packet Format
00196 ///
00197 /// All messages sent and received by this class conform to this packet format, as specified by 
00198 /// the nRF24L01 product specification:
00199 ///
00200 /// - 1 octets PREAMBLE
00201 /// - 3 to 5 octets NETWORK ADDRESS
00202 /// - 9 bits packet control field
00203 /// - 0 to 32 octets PAYLOAD, consisting of:
00204 ///   - 1 octet TO header
00205 ///   - 1 octet FROM header
00206 ///   - 1 octet ID header
00207 ///   - 1 octet FLAGS header
00208 ///   - 0 to 28 octets of user message
00209 /// - 2 octets CRC 
00210 ///
00211 /// \par Connecting nRF24L01 to Arduino
00212 ///
00213 /// The electrical connection between the nRF24L01 and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO), 
00214 /// a Chip Enable pin and a Slave Select pin.
00215 /// If you are using the Sparkfun WRL-00691 module, it has a voltage regulator on board and 
00216 /// can be should with 5V VCC if possible.
00217 /// The examples below assume the Sparkfun WRL-00691 module
00218 ///
00219 /// Connect the nRF24L01 to most Arduino's like this (Caution, Arduino Mega has different pins for SPI, 
00220 /// see below). Use these same connections for Teensy 3.1 (use 3.3V not 5V Vcc).
00221 /// \code
00222 ///                 Arduino      Sparkfun WRL-00691
00223 ///                 5V-----------VCC   (3.3V to 7V in)
00224 ///             pin D8-----------CE    (chip enable in)
00225 ///          SS pin D10----------CSN   (chip select in)
00226 ///         SCK pin D13----------SCK   (SPI clock in)
00227 ///        MOSI pin D11----------SDI   (SPI Data in)
00228 ///        MISO pin D12----------SDO   (SPI data out)
00229 ///                              IRQ   (Interrupt output, not connected)
00230 ///                 GND----------GND   (ground in)
00231 /// \endcode
00232 ///
00233 /// For an Arduino Leonardo (the SPI pins do not come out on the Digital pins as for normal Arduino, but only
00234 /// appear on the ICSP header)
00235 /// \code
00236 ///                Leonardo      Sparkfun WRL-00691
00237 ///                 5V-----------VCC   (3.3V to 7V in)
00238 ///             pin D8-----------CE    (chip enable in)
00239 ///          SS pin D10----------CSN   (chip select in)
00240 ///      SCK ICSP pin 3----------SCK   (SPI clock in)
00241 ///     MOSI ICSP pin 4----------SDI   (SPI Data in)
00242 ///     MISO ICSP pin 1----------SDO   (SPI data out)
00243 ///                              IRQ   (Interrupt output, not connected)
00244 ///                 GND----------GND   (ground in)
00245 /// \endcode
00246 /// and initialise the NRF24 object like this to explicitly set the SS pin
00247 /// NRF24 nrf24(8, 10);
00248 ///
00249 /// For an Arduino Mega:
00250 /// \code
00251 ///                 Mega         Sparkfun WRL-00691
00252 ///                 5V-----------VCC   (3.3V to 7V in)
00253 ///             pin D8-----------CE    (chip enable in)
00254 ///          SS pin D53----------CSN   (chip select in)
00255 ///         SCK pin D52----------SCK   (SPI clock in)
00256 ///        MOSI pin D51----------SDI   (SPI Data in)
00257 ///        MISO pin D50----------SDO   (SPI data out)
00258 ///                              IRQ   (Interrupt output, not connected)
00259 ///                 GND----------GND   (ground in)
00260 /// \endcode
00261 /// and you can then use the constructor RH_NRF24(8, 53). 
00262 ///
00263 /// For an Itead Studio IBoard Pro http://imall.iteadstudio.com/iboard-pro.html, connected by hardware SPI to the 
00264 /// ITDB02 Parallel LCD Module Interface pins:
00265 /// \code
00266 ///  IBoard Signal=ITDB02 pin          Sparkfun WRL-00691
00267 ///        3.3V      37-----------VCC  (3.3V to 7V in)
00268 ///         D2       28-----------CE   (chip enable in)
00269 ///         D29      27----------CSN   (chip select in)
00270 ///         SCK D52  32----------SCK   (SPI clock in)
00271 ///        MOSI D51  34----------SDI   (SPI Data in)
00272 ///        MISO D50  30----------SDO   (SPI data out)
00273 ///                              IRQ   (Interrupt output, not connected)
00274 ///        GND       39----------GND   (ground in)
00275 /// \endcode
00276 /// And initialise like this:
00277 /// \code
00278 /// RH_NRF24 nrf24(2, 29);
00279 /// \endcode
00280 ///
00281 /// For an Itead Studio IBoard Pro http://imall.iteadstudio.com/iboard-pro.html, connected by software SPI to the 
00282 /// nRF24L01+ Module Interface pins. CAUTION: performance of software SPI is very slow and is not
00283 /// compatible with other modules running hardware SPI.
00284 /// \code
00285 ///  IBoard Signal=Module pin          Sparkfun WRL-00691
00286 ///        3.3V      2----------VCC   (3.3V to 7V in)
00287 ///         D12      3-----------CE   (chip enable in)
00288 ///         D29      4----------CSN   (chip select in)
00289 ///         D9       5----------SCK   (SPI clock in)
00290 ///         D8       6----------SDI   (SPI Data in)
00291 ///         D7       7----------SDO   (SPI data out)
00292 ///                              IRQ   (Interrupt output, not connected)
00293 ///        GND       1----------GND   (ground in)
00294 /// \endcode
00295 /// And initialise like this:
00296 /// \code
00297 /// #include <SPI.h>
00298 /// #include <RH_NRF24.h>
00299 /// #include <RHSoftwareSPI.h>
00300 /// Singleton instance of the radio driver
00301 /// RHSoftwareSPI spi;
00302 /// RH_NRF24 nrf24(12, 11, spi);
00303 /// void setup() {
00304 ///     spi.setPins(7, 8, 9);
00305 ///     ....
00306 /// \endcode
00307 ///
00308 ///
00309 /// For Raspberry Pi with Sparkfun WRL-00691 
00310 /// \code
00311 ///     Raspberry Pi P1 pin          Sparkfun WRL-00691
00312 ///             5V      2-----------VCC   (3.3V to 7V in)
00313 ///         GPIO25      22-----------CE   (chip enable in)
00314 ///         GPIO8       24----------CSN   (chip select in)
00315 ///         GPIO11      23----------SCK   (SPI clock in)
00316 ///         GPIO10      19----------SDI   (SPI Data in)
00317 ///         GPIO9       21----------SDO   (SPI data out)
00318 ///                                 IRQ   (Interrupt output, not connected)
00319 ///            GND       6----------GND   (ground in)
00320 /// \endcode
00321 /// and initialise like this:
00322 /// \code
00323 ///  RH_NRF24 nrf24(RPI_V2_GPIO_P1_22, RPI_V2_GPIO_P1_24);
00324 /// \endcode
00325 /// See the example program and Makefile in examples/raspi. Requires bcm2835 library to be previously installed.
00326 /// \code
00327 /// cd examples/raspi
00328 /// make
00329 /// sudo ./RasPiRH
00330 /// \endcode
00331 /// \code
00332 ///
00333 /// You can override the default settings for the CSN and CE pins 
00334 /// in the NRF24() constructor if you wish to connect the slave select CSN to other than the normal one for your 
00335 /// Arduino (D10 for Diecimila, Uno etc and D53 for Mega)
00336 ///
00337 /// Caution: on some Arduinos such as the Mega 2560, if you set the slave select pin to be other than the usual SS 
00338 /// pin (D53 on  Mega 2560), you may need to set the usual SS pin to be an output to force the Arduino into SPI 
00339 /// master mode.
00340 ///
00341 /// Caution: this module has not been proved to work with Leonardo, at least without level 
00342 /// shifters between the nRF24 and the Leonardo. Tests seem to indicate that such level shifters would be required
00343 /// with Leonardo to make it work.
00344 ///
00345 /// It is possible to have 2 radios conected to one arduino, provided each radio has its own 
00346 /// CSN and CE line (SCK, SDI and SDO are common to both radios)
00347 ///
00348 /// \par SPI Interface
00349 ///
00350 /// You can interface to nRF24L01 with with hardware or software SPI. Use of software SPI with the RHSoftwareSPI 
00351 /// class depends on a fast enough processor and digitalOut() functions to achieve a high enough SPI bus frequency.
00352 /// If you observe reliable behaviour with the default hardware SPI RHHardwareSPI, but unreliable behaviour 
00353 /// with Software SPI RHSoftwareSPI, it may be due to slow CPU performance.
00354 ///
00355 /// Initialisation example with hardware SPI
00356 /// \code
00357 /// #include <RH_NRF24.h>
00358 /// RH_NRF24 driver;
00359 /// RHReliableDatagram manager(driver, CLIENT_ADDRESS);
00360 /// \endcode
00361 ///
00362 /// Initialisation example with software SPI
00363 /// \code
00364 /// #include <RH_NRF24.h>
00365 /// #include <RHSoftwareSPI.h>
00366 /// RHSoftwareSPI spi;
00367 /// RH_NRF24 driver(8, 10, spi);
00368 /// RHReliableDatagram manager(driver, CLIENT_ADDRESS);
00369 /// \endcode
00370 ///
00371 /// \par Example programs
00372 ///
00373 /// Several example programs are provided.
00374 ///
00375 /// \par Radio Performance
00376 ///
00377 /// Frequency accuracy may be debatable. For nominal frequency of 2401.000 MHz (ie channel 1), 
00378 /// my Yaesu VR-5000 receiver indicated the center frequency for my test radios
00379 /// was 2401.121 MHz. Its not clear to me if the Yaesu
00380 /// is the source of the error, but I tend to believe it, which would make the nRF24l01 frequency out by 121kHz.
00381 ///
00382 /// The measured power output for a nRF24L01p with PA and LNA set to 0dBm output is about 18dBm.
00383 /// 
00384 /// \par Radio operating strategy and defaults
00385 ///
00386 /// The radio is enabled all the time, and switched between TX and RX modes depending on 
00387 /// whether there is any data to send. Sending data sets the radio to TX mode.
00388 /// After data is sent, the radio automatically returns to Standby II mode. Calling waitAvailable() or
00389 /// waitAvailableTimeout() starts the radio in RX mode.
00390 ///
00391 /// The radio is configured by default to Channel 2, 2Mbps, 0dBm power, 5 bytes address, payload width 1, CRC enabled
00392 /// 2 byte CRC, No Auto-Ack mode. Enhanced shockburst is used. 
00393 /// TX and P0 are set to the Network address. Node addresses and decoding are handled with the RH_NRF24 module.
00394 ///
00395 /// \par Memory
00396 ///
00397 /// Memory usage of this class is minimal. The compiled client and server sketches are about 6000 bytes on Arduino. 
00398 /// The reliable client and server sketches compile to about 8500 bytes on Arduino.
00399 /// RAM requirements are minimal.
00400 ///
00401 class RH_NRF24 : public RHNRFSPIDriver
00402 {
00403 public:
00404 
00405     /// \brief Defines convenient values for setting data rates in setRF()
00406     typedef enum
00407     {
00408     DataRate1Mbps = 0,   ///< 1 Mbps
00409     DataRate2Mbps,       ///< 2 Mbps
00410     DataRate250kbps      ///< 250 kbps
00411     } DataRate;
00412 
00413     /// \brief Convenient values for setting transmitter power in setRF()
00414     /// These are designed to agree with the values for RF_PWR in RH_NRF24_REG_06_RF_SETUP
00415     /// To be passed to setRF();
00416     typedef enum
00417     {
00418     // Add 20dBm for nRF24L01p with PA and LNA modules
00419     TransmitPowerm18dBm = 0,        ///< On nRF24, -18 dBm
00420     TransmitPowerm12dBm,            ///< On nRF24, -12 dBm
00421     TransmitPowerm6dBm,             ///< On nRF24, -6 dBm
00422     TransmitPower0dBm,              ///< On nRF24, 0 dBm
00423     // Sigh, different power levels for the same bit patterns on RFM73:
00424     // On RFM73P-S, there is a Tx power amp, so expect higher power levels, up to 20dBm. Alas
00425     // there is no clear documentation on the power for different settings :-(
00426     RFM73TransmitPowerm10dBm = 0,   ///< On RFM73, -10 dBm
00427     RFM73TransmitPowerm5dBm,        ///< On RFM73, -5 dBm
00428     RFM73TransmitPowerm0dBm,        ///< On RFM73, 0 dBm
00429     RFM73TransmitPower5dBm          ///< On RFM73, 5 dBm. 20dBm on RFM73P-S2 ?
00430 
00431     } TransmitPower;
00432 
00433     /// Constructor. You can have multiple instances, but each instance must have its own
00434     /// chip enable and slave select pin. 
00435     /// After constructing, you must call init() to initialise the interface
00436     /// and the radio module
00437     /// \param[in] chipEnablePin the Arduino pin to use to enable the chip for transmit/receive
00438     /// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the NRF24 before
00439     /// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, 
00440     /// D10 for Maple)
00441     /// \param[in] spi Pointer to the SPI interface object to use. 
00442     ///                Defaults to the standard Arduino hardware SPI interface
00443     RH_NRF24(PINS chipEnablePin, PINS slaveSelectPin, RHGenericSPI& spi = hardware_spi);
00444   
00445     /// Initialises this instance and the radio module connected to it.
00446     /// The following steps are taken:g
00447     /// - Set the chip enable and chip select pins to output LOW, HIGH respectively.
00448     /// - Initialise the SPI output pins
00449     /// - Initialise the SPI interface library to 8MHz (Hint, if you want to lower
00450     /// the SPI frequency (perhaps where you have other SPI shields, low voltages etc), 
00451     /// call SPI.setClockDivider() after init()).
00452     /// -Flush the receiver and transmitter buffers
00453     /// - Set the radio to receive with powerUpRx();
00454     /// \return  true if everything was successful
00455     bool        init();
00456 
00457     /// Reads a single register from the NRF24
00458     /// \param[in] reg Register number, one of NRF24_REG_*
00459     /// \return The value of the register
00460     uint8_t        spiReadRegister(uint8_t reg);
00461 
00462     /// Writes a single byte to the NRF24, and at the ame time reads the current STATUS register
00463     /// \param[in] reg Register number, one of NRF24_REG_*
00464     /// \param[in] val The value to write
00465     /// \return the current STATUS (read while the command is sent)
00466     uint8_t        spiWriteRegister(uint8_t reg, uint8_t val);
00467 
00468     /// Reads a number of consecutive registers from the NRF24 using burst read mode
00469     /// \param[in] reg Register number of the first register, one of NRF24_REG_*
00470     /// \param[in] dest Array to write the register values to. Must be at least len bytes
00471     /// \param[in] len Number of bytes to read
00472     /// \return the current STATUS (read while the command is sent)
00473     uint8_t           spiBurstReadRegister(uint8_t reg, uint8_t* dest, uint8_t len);
00474 
00475     /// Write a number of consecutive registers using burst write mode
00476     /// \param[in] reg Register number of the first register, one of NRF24_REG_*
00477     /// \param[in] src Array of new register values to write. Must be at least len bytes
00478     /// \param[in] len Number of bytes to write
00479     /// \return the current STATUS (read while the command is sent)
00480     uint8_t        spiBurstWriteRegister(uint8_t reg, uint8_t* src, uint8_t len);
00481 
00482     /// Reads and returns the device status register NRF24_REG_02_DEVICE_STATUS
00483     /// \return The value of the device status register
00484     uint8_t        statusRead();
00485   
00486     /// Sets the transmit and receive channel number.
00487     /// The frequency used is (2400 + channel) MHz
00488     /// \return true on success
00489     bool setChannel(uint8_t channel);
00490 
00491     /// Sets the chip configuration that will be used to set
00492     /// the NRF24 NRF24_REG_00_CONFIG register when in Idle mode. This allows you to change some
00493     /// chip configuration for compatibility with libraries other than this one.
00494     /// You should not normally need to call this.
00495     /// Defaults to NRF24_EN_CRC| RH_NRF24_CRCO, which is the standard configuration for this library 
00496     /// (2 byte CRC enabled).
00497     /// \param[in] mode The chip configuration to be used whe in Idle mode.
00498     /// \return true on success
00499     bool setOpMode(uint8_t mode);
00500 
00501     /// Sets the Network address.
00502     /// Only nodes with the same network address can communicate with each other. You 
00503     /// can set different network addresses in different sets of nodes to isolate them from each other.
00504     /// Internally, this sets the nRF24 TX_ADDR and RX_ADDR_P0 to be the given network address.
00505     /// The default network address is 0xE7E7E7E7E7
00506     /// \param[in] address The new network address. Must match the network address of any receiving node(s).
00507     /// \param[in] len Number of bytes of address to set (3 to 5).
00508     /// \return true on success, false if len is not in the range 3-5 inclusive.
00509     bool setNetworkAddress(uint8_t* address, uint8_t len);
00510 
00511     /// Sets the data rate and transmitter power to use. Note that the nRF24 and the RFM73 have different
00512     /// available power levels, and for convenience, 2 different sets of values are available in the 
00513     /// RH_NRF24::TransmitPower enum. The ones with the RFM73 only have meaning on the RFM73 and compatible
00514     /// devces. The others are for the nRF24.
00515     /// \param [in] data_rate The data rate to use for all packets transmitted and received. One of RH_NRF24::DataRate.
00516     /// \param [in] power Transmitter power. One of RH_NRF24::TransmitPower.
00517     /// \return true on success
00518     bool setRF(DataRate data_rate, TransmitPower power);
00519 
00520     /// Sets the radio in power down mode, with the configuration set to the
00521     /// last value from setOpMode().
00522     /// Sets chip enable to LOW.
00523     void setModeIdle();
00524 
00525     /// Sets the radio in RX mode.
00526     /// Sets chip enable to HIGH to enable the chip in RX mode.
00527     void setModeRx();
00528 
00529     /// Sets the radio in TX mode.
00530     /// Pulses the chip enable LOW then HIGH to enable the chip in TX mode.
00531     void setModeTx();
00532 
00533     /// Sends data to the address set by setTransmitAddress()
00534     /// Sets the radio to TX mode
00535     /// \param [in] data Data bytes to send.
00536     /// \param [in] len Number of data bytes to send
00537     /// \return true on success (which does not necessarily mean the receiver got the message, only that the message was
00538     /// successfully transmitted).
00539     bool send(const uint8_t* data, uint8_t len);
00540 
00541     /// Blocks until the current message (if any) 
00542     /// has been transmitted
00543     /// \return true on success, false if the chip is not in transmit mode or other transmit failure
00544     virtual bool waitPacketSent();
00545 
00546     /// Indicates if the chip is in transmit mode and 
00547     /// there is a packet currently being transmitted
00548     /// \return true if the chip is in transmit mode and there is a transmission in progress
00549     bool isSending();
00550 
00551     /// Prints the value of all chip registers
00552     /// to the Serial device if RH_HAVE_SERIAL is defined for the current platform
00553     /// For debugging purposes only.
00554     /// \return true on success
00555     bool printRegisters();
00556 
00557     /// Checks whether a received message is available.
00558     /// This can be called multiple times in a timeout loop
00559     /// \return true if a complete, valid message has been received and is able to be retrieved by
00560     /// recv()
00561     bool        available();
00562 
00563     /// Turns the receiver on if it not already on.
00564     /// If there is a valid message available, copy it to buf and return true
00565     /// else return false.
00566     /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
00567     /// You should be sure to call this function frequently enough to not miss any messages
00568     /// It is recommended that you call it in your main loop.
00569     /// \param[in] buf Location to copy the received message
00570     /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
00571     /// \return true if a valid message was copied to buf
00572     bool        recv(uint8_t* buf, uint8_t* len);
00573 
00574     /// The maximum message length supported by this driver
00575     /// \return The maximum message length supported by this driver
00576     uint8_t maxMessageLength();
00577 
00578     /// Sets the radio into Power Down mode.
00579     /// If successful, the radio will stay in Power Down mode until woken by 
00580     /// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
00581     /// Caution: there is a time penalty as the radio takes a finite time to wake from sleep mode.
00582     /// \return true if sleep mode was successfully entered.
00583     virtual bool    sleep();
00584 
00585 protected:
00586     /// Flush the TX FIFOs
00587     /// \return the value of the device status register
00588     uint8_t flushTx();
00589 
00590     /// Flush the RX FIFOs
00591     /// \return the value of the device status register
00592     uint8_t flushRx();
00593 
00594     /// Examine the receive buffer to determine whether the message is for this node
00595     void validateRxBuf();
00596 
00597     /// Clear our local receive buffer
00598     void clearRxBuf();
00599 
00600 private:
00601     /// This idle mode chip configuration
00602     uint8_t             _configuration;
00603 
00604     /// the number of the chip enable pin
00605     uint8_t             _chipEnablePin;
00606 
00607     /// Number of octets in the buffer
00608     uint8_t             _bufLen;
00609     
00610     /// The receiver/transmitter buffer
00611     uint8_t             _buf[RH_NRF24_MAX_PAYLOAD_LEN];
00612 
00613     /// True when there is a valid message in the buffer
00614     bool                _rxBufValid;
00615 };
00616 
00617 /// @example nrf24_client.pde
00618 /// @example nrf24_server.pde
00619 /// @example nrf24_reliable_datagram_client.pde
00620 /// @example nrf24_reliable_datagram_server.pde
00621 /// @example RasPiRH.cpp
00622 
00623 #endif