NRF24 library for Arduino

This NRF24 library has now been superceded by the RadioHead library http://www.airspayce.com/mikem/arduino/RadioHead RadioHead and its RH_NRF24 driver provides all the features supported by NRF24, and much more besides, including Reliable Datagrams, Addressing, Routing and Meshes. All the platforms that NRF24 supported are also supported by RadioHead.

This library will no longer be maintained or updated, but we will continue to publish it for the benefit of the the community, and you may continue to use it within the terms of the license. Nevertheless we recommend upgrading to RadioHead where possible.

This is the Arduino NRF24 library. It provides an object-oriented interface for sending and receiving data messages with Nordic nRF24L01 based radio modules, such as the sparkfun WRL-00691 http://www.sparkfun.com/products/691

The nRF24L01 (http://www.sparkfun.com/datasheets/Wireless/Nordic/nRF24L01P_Product_Specification_1_0.pdf) is a low-cost 2.4GHz ISM transceiver module. It supports a number of channel frequencies in the 2.4GHz band and a range of data rates.

This library provides functions for sending and receiving messages of up to 32 octets on any frequency supported by the nRF24L01, at a selected data rate.

Up to 2 nRF24L01 modules can be connected to an Arduino, permitting the construction of translators and frequency changers, etc.

This library provides classes for

- NRF24: addressed, reliable, retransmitted, acknowledged messages (using nrf24 Enhanced Shockburst)

Example Arduino programs are included to show the main modes of use.

The version of the package that this documentation refers to can be downloaded from http://www.airspayce.com/mikem/arduino/NRF24/NRF24-1.14.zip You can find the latest version at http://www.airspayce.com/mikem/arduino/NRF24

You can also find online help and disussion at http://groups.google.com/group/NRF24-arduino Please use that group for all questions and discussions on this topic. Do not contact the author directly, unless it is to discuss commercial licensing. Before asking a question or reporting a bug, please read http://www.catb.org/esr/faqs/smart-questions.html

Tested on Arduino Diecimila, Duemilanove and Mega with arduino 1.0 on OpenSuSE 12.1 with avr-libc-1.7.1-1.1, cross-avr-binutils-2.19.1-33.1 and cross-avr-gcc-4.3.3_20100125-28.1, and with arduino-0021 on the same platforms

Packet Format

All messages sent and received by this NRF24 library must conform to this packet format, as specified by the nRF24L01 product specificaiton:

- 1 octets PREAMBLE
- 4 octets ADDRESS
- 9 bits packet control field
- 0 to 32 octets PAYLOAD
- 2 octets CRC

Connecting nRF24L01 to Arduino

The physical connection between the nRF24L01 and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO), a Chip Enable pin and a Slave Select pin. If you are using the Sparkfun WRL-00691 module, it has a voltage regulator on board and can be run with 5V VCC The examples below assume the Sparkfun WRL-00691 module

Connect the nRF24L01 to most Arduino's like this (Caution, Arduino Mega has different pins for SPI, see below),

* Arduino Sparkfun WRL-00691
* 3V3 or 5V----VCC (3.3V to 7V in)
* pin D8-----------CE (chip enable in)
* SS pin D10----------CSN (chip select in)
* SCK pin D13----------SCK (SPI clock in)
* MOSI pin D11----------SDI (SPI Data in)
* MISO pin D12----------SDO (SPI data out)
* IRQ (Interrupt output, not connected)
* GND----------GND (ground in)
*

For an Arduino Leonardo (the SPI pins do not come out on the Digital pins as for normal Arduino, but only appear on the ICSP header)

* Leonardo Sparkfun WRL-00691
* 3V3 or 5V----VCC (3.3V to 7V in)
* pin D8-----------CE (chip enable in)
* SS pin D10----------CSN (chip select in)
* SCK ICSP pin 3----------SCK (SPI clock in)
* MOSI ICSP pin 4----------SDI (SPI Data in)
* MISO ICSP pin 1----------SDO (SPI data out)
* IRQ (Interrupt output, not connected)
* GND----------GND (ground in)
*

and initialise the NRF24 object like this to explicitly set the SS pin NRF24 nrf24(8, 10);

For an Arduino Mega:

* Mega Sparkfun WRL-00691
* 3V3 or 5V----VCC (3.3V to 7V in)
* pin D8-----------CE (chip enable in)
* SS pin D53----------CSN (chip select in)
* SCK pin D52----------SCK (SPI clock in)
* MOSI pin D51----------SDI (SPI Data in)
* MISO pin D50----------SDO (SPI data out)
* IRQ (Interrupt output, not connected)
* GND----------GND (ground in)
*

and you can then use the default constructor NRF24(). You can override the default settings for the CSN and CE pins in the NRF24() constructor if you wish to connect the slave select CSN to other than the normal one for your Arduino (D10 for Diecimila, Uno etc and D53 for Mega)

Caution: on some Arduinos such as the Mega 2560, if you set the slave select pin to be other than the usual SS pin (D53 on Mega 2560), you may need to set the usual SS pin to be an output to force the Arduino into SPI master mode.

Caution: this module has not been proved to work with Leonardo, at least without level shifters between the NRF24 and the Leonardo. Tests seem to indicate that such level shifters would be required with Leonardo to make it work.

It is possible to have 2 radios conected to one arduino, provided each radio has its own CSN and CE line (SCK, SDI and SDO are common to both radios)

Example programs

The following example programs are provided: -nrf24_ping_client, nrf24_pin_server. This is a matched pair. The client sends (acknowledged) 4 byte timestamp to the server which replies (acknowledged). The client measures the round-trip time and prints it. Typical RTT is 1-2 msec. These are compatible radio wise with the ping_client and ping_server programs that come with the Mirf library though the electrical connections are different -nrf24_specan. Example sketch showing how to create a primitive spectrum analyser with the NRF24 class. The nRF24L01 received power detector is only one bit, but this will show which channels have more than -64dBm present. -nrf24_audio_tx, nrf24_audio_rx. This is a matched pair. The clinet sends a stream of audio samples measured from analog input 0 to the receiver, which reconstructs them on output D6. See comments in those files for electrical requirements. The pair demonstrates the use of NRF24 in NOACK modefor improved performance (but no reliability). Can achieve 6.4kHz sample rate. Dont expect good quality audio!

Radio Performance

The performance of this radio seems to be very good. I was able to build ping client/server that was able to achieve over 800 round trips per second (at 0dBm power, 2Mbps, channel 1, 4 byte payload each way, 1 checksum byte) when the radios were next to each other. This rate could still be achieved at 15m distance, but the orientation of the radios and obstructions became critical. The human body can easily block these signals. Best response was when the chip antennas were broadside to each other.

It is possible to get even better streaming performance using NOACK mode (see the nrf24_audio_tx sample) at the cost of nop reliability. In NOACK mode, at 2Mbps, 32 byte payload, can get about 1900 packets per second: 60800 bytes of payload per second

Frequency accuracy may be debatable. For nominal frequency of 2401.000 MHz (ie channel 1), my Yaesu VR-5000 receiver indicated the center frequency for my test radios was 2401.121 MHz. Its not clear to me if the Yaesu is the source of the error, but I tend to believe it, which would make the nRF24l01 frequency out by 121kHz.

Radio operating strategy and defaults

The radio is enabled all the time, and switched between TX and RX modes depending on whether there is any data to send. Sending data sets the radio to TX mode. After data is sent, the radion automatically returns to Standby II mode. Calling waitAvailable() or waitAvailableTimeout() starts the radio in RX mode.

The radio is configured by default to Channel 2, 2Mbps, 0dBm power, 5 bytes address, payload width 1, CRC enabled 1 byte CRC, Auto-Ack mode. Enhanced shockburst is used. P1 is the receive pipe. P0 is set to the transmit address to enable autoack.

Memory

Memory usage of this program is minimal. The compiled ping client and server programs are about 4000 bytes. RAM requirements of the library are minimal.

Installation

Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.

This software is Copyright (C) 2012 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:

Donations

This library is offered under a free GPL license for those who want to use it that way. We try hard to keep it up to date, fix bugs and to provide free support. If this library has helped you save time or money, please consider donating at http://www.airspayce.com or here:

Open Source Licensing GPL V2

This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 2 when your application is distributed. See http://www.gnu.org/copyleft/gpl.html

Commercial Licensing

This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. Contact info@.nosp@m.airs.nosp@m.payce.nosp@m..com for details.

Revision History

Version
  1.0 Initial release
  1.1 Changed default value for slave slect pin in constructor to be SS, ie the normal one for the compiled Arduino (D10 for Diecimila, Uno etc and D53 for Mega). This is because some Arduinos such as Mega 2560 reportedly use the type of the SS pin to determine whether to run in slave or master mode. Therfore it is preferred that the slave select pin actually be the normal SS pin.
  1.2 Updated documentation about what happens during init, and that SPI is initialised to 8MHz (but can be set to other frequencies after calling init()
  1.3 Fixed error in title of main page
  1.4 Fixed typo in nrf24_test.pde, reported by TOM.
  1.6 Fixed an error NRF24::setRF in setting data rate to 250kbps. Reported by Shiu Kumar.
  1.7 Improvements to waitPacketSent() so if the chip is not in transmit mode, it wont wait forever. Improvements to isSending() so it returns false if the chip is not in transmit mode.
  1.8 Fixed a conflict between 2 definitions of NRF24_TX_FULL. The one in 07 STATUS is changed to NRF24_STATUS_TX_FULL. Reported by Charles-Henri Hallard. Updated author and distribution location details to airspayce.com
  1.9 Improvements to waitAvailableTimeout to make it robust on millis() rollover.
  1.10 Testing with Leonardo and update documentation to reflect special electrical connection needs on Leonardo.
  1.11 NRF24_COMMAND_W_ACK_PAYLOAD(c) is now a macro that takes a pipe number parameter. Added new function setRetry(), a convenience for setting ARD and ARC retry parameter. Can now customise the radio configuration byte with setConfiguration(). Added new examples crazyflie and crazyflie_client that use the NRF24 library to communicate with Crazyflie quadcopters and transmitters.
  1.12 NRF24::init, powerUpRx, powerUpTx will now fail if no device is connected;
  1.13 Added End Of Life notice. This library will no longer be maintained and updated: use RadioHead instead.
  1.14 Fixed problem that prevented 250kbps data rate working.

Author
  Mike McCauley (mikem.nosp@m.@air.nosp@m.spayc.nosp@m.e.co.nosp@m.m) DO NOT CONTACT THE AUTHOR DIRECTLY: USE THE LISTS