RF24 Library: Driver for nRF24L01(+) 2.4GHz Wireless Transceiver

Moderator (dec 2015): The library mentioned here is updated on another location.
see RF24 Library: Driver for nRF24L01(+) 2.4GHz Wireless Transceiver - #267 by Avamander - Networking, Protocols, and Devices - Arduino Forum


Hi, I thought I should actually formally announce this driver library one of these days... I have been working toward building a complete driver implementation for the Nordic nRF24L01/nRF24L01+ chips. This is the lowest layer of a mesh network stack I'm working on, though it should be independently useful for any usage of these chips.

Complete documentation is here: http://maniacbug.github.com/RF24/index.html

Examples range from a simple two-node ping/pong to a complex multi-hop mesh network which should work with unlimited nodes (I've tried 6).

Suggestions are welcome.

Hey ManiacBug,

How's it going? Any updates.

Sorry got way off track here but picking it up I hope...

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

Hi maniacbug,

I've been quietly watching this thread too.

Which radio modules you are using?. and where did you buy them?.

Since he hasn't responded yet, its likely because he's been rather busy.

We've been having a fun exchange for some time now as I too am interested in enhanced RF24 support. I don't want to take the wind out of his sails, but it looks like he's added support for interrupt based I/O. I don't know if he considers it stable or not but its certainly something to which we can look forward.

Additionally, I hope he'll be merging in a number of new features and bug fixes from my tree. My tree has largely concentrated on P-variant features, which includes support for 250kbs bandwidth mode, data rate query, enhanced CRC configuration (/query) and defaults, faster SPI bus interface, per pipeline auto ACK configuration, and PA power query/configuration. I'm likely forgetting some minor others.

I expect at least one additional bug fix will follow shortly with the possibility of a second shortly after that. I have yet to fully confirm the second.

Additional debugging information has been added printDetails() and IIRC, he's also added some additional debugging details throughout.

printDetail():
STATUS=0e: RX_DR=0 TX_DS=0 MAX_RT=0 RX_P_NO=7 TX_FULL=0
RX_ADDR_P0 = 0xdeadbeefed
RX_ADDR_P1 = 0xc2c2c2c2c2
RX_ADDR_P2 = 0xc3
RX_ADDR_P3 = 0xc4
RX_ADDR_P4 = 0xc5
RX_ADDR_P5 = 0xc6
TX_ADDR = 0xe7e7e7e7e7
RX_PW_P0 = 0x20
RX_PW_P1 = 0x00
EN_AA = 0x00
EN_RXADDR = 0x03
RF_CH = 0x00
RF_SETUP = 0x0f (data rate: 1)
Hardware; isPVariant: 1
CONFIG = 0x0f (CRC enable: 1; CRC16: 1)

And just for giggles, here's the output from a modified, single bit (testCarrier() or testRPD()) scanner. The scanner also dumps received messages which is good for address/CRC quality testing, as well as a very primitive promiscuous operating mode. My version of the scanner has not been committed.

There has also been some discussion of channel spacing to better support the chips wide and narrow band modes of operation.

And if you're also interested in the Mirf library, expect a minor update in the near future.

Lastly, if you have P-variant hardware, I would very much love to hear about range testing when operating in 2Mbs, 1Mbs, and 250kbs bandwidth modes. I really hope more people take interest in the very affordable and seemingly very capable nRF24 modules.

This does sound nice, I love the size of those modules, you could put them into just about anything.

I to have been keeping an eye on this, not ready to do anything yet though.


Rob

Hi Gerg and Everyone...

I am very interested in this. I have put up a beginning How-To for these modules here:
http://arduino-info.wikispaces.com/Nrf24L01-2.4GHz-HowTo

Comments, corrections, additions appreciated...

Gerg, you said:

And if you're also interested in the Mirf library, expect a minor update in the near future.

Lastly, if you have P-variant hardware, I would very much love to hear about range testing when operating in 2Mbs, 1Mbs, and 250kbs bandwidth modes.

What do you mean by "P-Variant hardware" ?? I have some of the boards that have a nRF24L01's plus a power Amp for 100mW and receiver preamp. Here:
http://arduino-direct.com/sunshop/index.php?l=product_detail&p=190
are these what you mean??

I'm just starting to fire these up... Any suggestions on best first-up software sketch / testing appreciated..

I do have an RF background.. most was higher power (Broadcast)...

Where is the best place to download your fork?? And where's best Mirf??

Terry,

There's a page with related information at http://arduino-info.wikispaces.com/nRF24L01-Mirf-Examples.

There's also a 'general' page at http://arduino-info.wikispaces.com/Nrf24L01-2.4GHz-HowTo.

At the base of the page it mentions that the "24F Library is much more full-featured and does error checking", and the 24F Library is described at http://arduino-info.wikispaces.com/nRF24L01-RF24-Examples.

I've been using modules from mdfly.com.

Mostly these units as the workhorse of the system:

2.4Ghz Wireless nRF24L01 Transceiver Module $6.95
http://www.mdfly.com/index.php?main_page=product_info&cPath=8_52&products_id=82

And then also experimenting with these for greater range

nRF24L01 2.4GHz Transceiver Module w/ Power Amplifier $12.95
http://www.mdfly.com/index.php?main_page=product_info&cPath=8_52&products_id=394

2.4GHz Transceiver Module w/ Power Amplifier $19.95
http://www.mdfly.com/index.php?main_page=product_info&cPath=8_52&products_id=583

However, I also noticed that iTeadStudio has nRF24L01+ units for $4!

novice:
Terry,

There's a page with related information at http://arduino-info.wikispaces.com/nRF24L01-Mirf-Examples.

Heh, aren't those Terry's pages?! :slight_smile:

Hi Everyone, Sorry for the Maniacal confusion!

First, I just want to get these nRF24L01 units working well for Arduino applications and get some good examples online. I DO have a shop that sells these modules, also so that's a Disclaimer.

I am also researching Antennas. I have a RF / Amateur Radio background and have built antennas and RF hardware. There are also lots of good antennas and power amplifiers available for WiFi in this same frequency band that should work for these modules. I want to prototype longer-range solutions for Base to Mobile (say, Home to SemiAutonomous Robot or other autonomous vehicle.)
Like this Antenna: http://goo.gl/61daA or this Amplifier: http://goo.gl/Y8Tcu

I think there is great promise to these and with the serious software work by Maniacbug and others this should be workable.

I just connected two nRF24L01+ units with the pingpair example and I'm getting Timeouts so I need to check everything over.. Any debug suggestions appreciated.. I'd like to be able to write up a newbie Get Started page...

How can we organize this effort??

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

maniacbug:
I've been using modules from mdfly.com.
...
2.4GHz Transceiver Module w/ Power Amplifier $19.95
http://www.mdfly.com/index.php?main_page=product_info&cPath=8_52&products_id=583

Hey ManiacBug, have you seen these, which have both a Power Amplifier AND a Low Noise Receiver Preamplifier??
http://arduino-direct.com/sunshop/index.php?l=product_detail&p=190

Where in the World are you? I'll send you a couple of these if you'll experiment with them and let us know how they work out...

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

terryking228:
Hi Gerg and Everyone...

I am very interested in this. I have put up a beginning How-To for these modules here:
http://arduino-info.wikispaces.com/Nrf24L01-2.4GHz-HowTo

Comments, corrections, additions appreciated...

First let me say I very much appreciate the quality of your wiki docs. Your pages were one of the reasons I decided to further explore my sprinkler project; whereby the relay board is central.

terryking228:
Gerg, you said:

And if you're also interested in the Mirf library, expect a minor update in the near future.

Lastly, if you have P-variant hardware, I would very much love to hear about range testing when operating in 2Mbs, 1Mbs, and 250kbs bandwidth modes.

What do you mean by "P-Variant hardware" ?? I have some of the boards that have a nRF24L01's plus a power Amp for 100mW and receiver preamp. Here:
http://arduino-direct.com/sunshop/index.php?l=product_detail&p=190
are these what you mean??

There exists the NRF24L01 and NRF24L01P (aka NRF24L01+, and even NRF24L01P+) chips. The P-variant is the next generation. It provides for a 250Kbs data rate, better receiver sensitivity, and a couple of other features. The p-variant is fully backward compatible. IMOHO, given the extremely modest price difference (typically a $1.50 or less), the P deprecates its predecessor (non-p variant). Ive read many an account whereby simply migrating from the non-p to the p-variant provides for superior range. Add in the fact the p-variant alone allows for the 250-Kbps mode which also enables much improve sensitivity, its claimed the range improvement is profound. As I've not confirmed any of this and I'm second/third hand parroting, take it for what it is.

Maniacbug has some really nice scripts and his latest stuff even has some testing/validation stuff drive via python scripts. So do check out his source repository.

I forget where I found the mirf tree. IIRC, it was google code, github, or gitorious. The bug fix is the use of 16-bit CRC rather than 8-bit CRC. Its a literal 1-byte change in a file. Keep in mind though Maniacbug's library is much higher level and feature rich. Unless your at a space premium, I do recommend his library over that of Mirf.

terryking228:
I'm just starting to fire these up... Any suggestions on best first-up software sketch / testing appreciated..

I do have an RF background.. most was higher power (Broadcast)...

Wouldn't happen to include a background in antenna design would it? We've had some discussion on proper pcb trace antenna orientation for best reception/transmission. My own results have proved to be borderline confusing to indeterminate. Some of which conflict with Maniacbug's observations, which makes it all the more futile. Some definitive insight would be wonderful; especially if it saves me from reading some long/dry white papers. :slight_smile:

terryking228:
Where is the best place to download your fork?? And where's best Mirf??

My fork is available on github. But I did just get confirmation back from Maniacbug that he's merged it to a branch in his tree. So unless you like the bleeding edge, its probably best to clone his tree. From a testing perspective alone, in that his environment is must better suited than my own, I do recommend following his tree unless you're willing to stumble some from my own.

For something entirely different, I did manage some testing this weekend. I set up two modules. One as a dedicated transmitter and the other as a dedicated scanner (my version). My results were extremely surprising. In 2Mbs mode, I was able to scan 9-Mhz of bandwidth. In 1Mbs mode, I scanned 5-6-Mhz of bandwidth. And in 250Kbs mode, I scanned 2-3-Mhz of bandwidth. This is especially surprising given the datasheet basically claims 1+Mhz+some minor bleed, 1-Mhz+some minor bleed, and <1Mhz+some minor bleed. But then again, I've not really spent that much time reviewing documented the "bleed" from each operating mode. The short of it is, this test does wonders to suggest recommended channel spacing. Whereby, based on my testing, the channel spacing should be 9Mhz, 6Mhz, and 3Mhz, respectively. Whereas previous discussions centered on 2Mhz, 1Mhz, and 1Mhz.

EDIT: Added mirf library comment.
EDIT: Revised observed and document (that I read) RF performance.

Gerg, thanks for your good information.

I got out the big magnifier and checked the Nordic chips on the 3 products I have (Plain Nrf24L01+, with PA, and with PA+LNA) and all have a "+" character after the "24L01". So I'm happy that these are all the latest version chip..

I have built some VHF and UHF antennas, but I'm not sure about the kind of printed circuit board antennas on the $4.75 units. I think they are best suited to very short ranges where "just not worrying about antennas at all" is a good feature. Anything that needs more than 10 meters or so of range I'd be more comfortable with a "real" antenna. That means a connector and parts I have seen mean a Power Amplifier and maybe a Receiver Preamp are added.

OH: There is a plain 24L01+ with RP-SMA connector that would sell for about $10. Hmm. Maybe good for very low power sensor nodes?? Any opinions?? I do not stock that but I could...

The next step in distance would be better antennas (some plug right into the same "RP-SMA" connectors. Then there are external amplifiers, roof antennas and all that. I hope we can establish some real-world guidelines for this stuff. There are a lot of unsupported claims for distances and antenna gains and it's confusing and unrealistic. I just saw a 433 Mhz Remote lights controller on TaoBao with a handheld control, that says range is 1000M !

OK, I'm getting these units running next! Enough words, need signals....

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

gerg:
In 2Mbs mode, I was able to scan 9-Mhz of bandwidth. In 1Mbs mode, I scanned 5-Mhz of bandwidth. And in 250Kbs mode, I scanned 2-3-Mhz of bandwidth. This is especially surprising given the datasheet basically claims 2+Mhz+some minor bleed, 1+Mhz+some minor bleed, and <1Mhz+some minor bleed.

Wow, this is really good information. Spread those channels widely!

gerg:
I forget where I found the mirf tree. IIRC, it was google code, github, or gitorious. The bug fix is the use of 16-bit CRC rather than 8-bit CRC. Its a literal 1-byte change in a file. Keep in mind though Maniacbug's library is much higher level and feature rich. Unless your at a space premium, I do recommend his library over that of Mirf.

Gerg inspired me to take a closer look :slight_smile: Indeed, the simple RF24 example uses 3k more program memory and 18 bytes more RAM than the comparable Mirf example. So yes, if you're down to your last 10% of flash space, it's probably better to stick with the simpler library.

RF24/examples/pingpair:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .data             PROGBITS        00800100 001fba 0000f2 00  WA  0   0  1
  [ 2] .text             PROGBITS        00000000 000094 001f06 00  AX  0   0  2
  [ 3] .bss              NOBITS          008001f2 0020ac 0000c6 00  WA  0   0  1

Mirf/examples/ping_client:

Section Headers:
  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
  [ 1] .data             PROGBITS        00800100 00128a 000072 00  WA  0   0  1
  [ 2] .text             PROGBITS        00000000 000094 0011f6 00  AX  0   0  2
  [ 3] .bss              NOBITS          00800172 0012fc 0000b4 00  WA  0   0  1

I just connected two nRF24L01+ units with the pingpair example and I'm getting Timeouts so I need to check everything over.. Any debug suggestions appreciated.. I'd like to be able to write up a newbie Get Started page...

Are you getting ANY successful transmissions? If not, any of the RF24 examples will spew out a bunch of information right at the start. Capture that from both nodes and post it here.

Do you have the latest pull from git? Within the last month, I fixed a bug someone reported which led to many false transmission failures. Unless you have specific need for '+' feature, I recommend sticking with the 'master' branch until 'p_enable' gets more testing. (Or unless you want to help test it :))

Hey ManiacBug, have you seen these, which have both a Power Amplifier AND a Low Noise Receiver Preamplifier??
http://arduino-direct.com/sunshop/index.php?l=product_detail&p=190

Where in the World are you? I'll send you a couple of these if you'll experiment with them and let us know how they work out...

That would be pretty handy. I use the high-price units for my base station, so having LNA on there too would be handy. That said, I also use PA units as relays to reach the base station, so in practice I haven't found a situation where a PA node could not reach the base within my house.

I'm in Seattle. I'll PM you my address if you want to send a couple. Happy to try them out. I've been meaning to do some range tests. It's next on my list after testing Gerg's changes more thoroughly and merging them into the mainline.

Lately I've been doing a lot of work on atmega128rfa1, which is a different beast entirely. It runs RPL over IPv6 which is COMPLETE hotness, but the hardware is too expensive.

I'm in Seattle. I'll PM you my address if you want to send a couple. Happy to try them out. I've been meaning to do some range tests. It's next on my list after testing Gerg's changes more thoroughly and merging them into the mainline.

Please do or send to my open email.. Would be good if you and gerg had the same hardware (and Me!)

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

Hi Everyone,

OK, I'm OnTheAir (As the light-up signs used to say)... I'm running gerg's latest library and after realizing he's running serial@9600, I have data going both ways with PingPair. Yahoo! Running one UNO and one Seeeduino and plain nRF24L01 boards with built-in PCB antenna...

I get about one timeout in 10 transmissions... No difference between distances of 2cm and 3M . These are the smallest radios I've ever used.. In contrast I just unpacked a 204A from my Dad, which is an 18" high vacuum tube that was a display antique when I first saw it in 1950. Sorry, but I love these contrasts ( :roll_eyes: for old-guy stories)..

I'll do more tomorrow and fire up the boards with power amp and LNA and antennas that LOOK like antennas.

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

terryking228:
Hi Everyone,

OK, I'm OnTheAir (As the light-up signs used to say)... I'm running gerg's latest library and after realizing he's running serial@9600, I have data going both ways with PingPair. Yahoo! Running one UNO and one Seeeduino and plain nRF24L01 boards with built-in PCB antenna...

Always exciting to see bits flying through the air.

terryking228:
I get about one timeout in 10 transmissions... No difference between distances of 2cm and 3M . These are the smallest radios I've ever used..

You're not alone in your awe. Its pretty awesome what they fit in that tiny little IC.

I'm assuming the error rate is actually a false positive. There have been a number of driver issues along these lines. I think Maniacbug even mentioned he recently fixed one. I'd have to look to see if that fix is part of the branch you're using.

I hope to play some more this week and see if I can nail down some of the potential issues I've identified.

Hi,

I'm assuming the error rate is actually a false positive. There have been a number of driver issues along these lines. I think Maniacbug even mentioned he recently fixed one. I'd have to look to see if that fix is part of the branch you're using.

Looking at the two Serial outputs, a missed transmission seems to always have the PONG not sending a response (Maybe not getting a message).. Seems like any time PONG sends a response, PING gets it..

BTW it's SO nice to be able to run multiple copies of the IDE and Serial Monitor in the same desktop. Some other older IDE's could not do that and drove me crazy testing communications...

I need to sit down and read all this code!

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com

gerg:
I'm assuming the error rate is actually a false positive. There have been a number of driver issues along these lines. I think Maniacbug even mentioned he recently fixed one. I'd have to look to see if that fix is part of the branch you're using.

Right. You said you're running gerg's branch, which does not yet have the major fix that produced plenty false failures.

That said, failures are a fact of life. This is documented by Nordic. It's particularly acute at 8-bit CRC. At 16-bit CRC, 1MBps data rate, channel 100, units 12 inches apart, I almost never get any failures.

maniacbug:
... You said you're running gerg's branch, which does not yet have the major fix that produced plenty false failures.

That said, failures are a fact of life. This is documented by Nordic. It's particularly acute at 8-bit CRC. At 16-bit CRC, 1MBps data rate, channel 100, units 12 inches apart, I almost never get any failures.

Hey Maniac.. do you have a major 'Fix' that " produced plenty false failures."? Sorry, a bit confused... Does your current release have the fix?

Yes, I understand there will be fails and hope that the automatic retries can be worked out.

Maniac, send me a shipping address??

Regards, Terry King
...In The Woods In Vermont
terry@yourduino.com