This is the Arduino RF22 library. It provides an object-oriented interface for sending and receiving data messages with Hope-RF RF22B based radio modules, and compatible chips and modules, including the RFM22B transceiver module such as this bare module: http://www.sparkfun.com/products/10153 and this shield: http://www.sparkfun.com/products/11018
RF22 also supports some of the features of ZigBee and XBee, (such as mesh routing and automatic route discovery), but with a much less complicated system and less expensive radios.
The Hope-RF (http://www.hoperf.com) RFM22B (http://www.hoperf.com/rf_fsk/fsk/RFM22B.htm) is a low-cost ISM transceiver module. It supports FSK, GFSK, OOK over a wide range of frequencies and programmable data rates.
This library provides functions for sending and receiving messages of up to 255 octets on any frequency supported by the RF22B, in a range of predefined data rates and frequency deviations. Frequency can be set with 312Hz precision to any frequency from 240.0MHz to 960.0MHz.
Up to 2 RF22B modules can be connected to an Arduino, permitting the construction of translators and frequency changers, etc.
This library provides classes for
The following modulation types are suppported with a range of modem configurations for common data rates and frequency deviations:
Support for other RF22B features such as on-chip temperature measurement, analog-digital converter, transmitter power control etc is also provided.
The latest version of this documentation can be downloaded from http://www.airspayce.com/mikem/arduino/RF22
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/RF22/RF22-1.33.zip You can find the latest version at http://www.airspayce.com/mikem/arduino/RF22
You can also find online help and disussion at http://groups.google.com/group/rf22-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.
Tested on Arduino Diecimila and Mega with arduino-0021 on OpenSuSE 11.1 and avr-libc-1.6.1-1.15, cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5. With HopeRF RFM22 modules that appear to have RF22B chips on board:
All messages sent and received by this RF22 library must conform to this packet format:
For technical reasons, the message format is not compatible with the 'HopeRF Radio Transceiver Message Library for Arduino' http://www.airspayce.com/mikem/arduino/HopeRF from the same author. Nor is it compatible with 'Virtual Wire' http://www.airspayce.com/mikem/arduino/VirtualWire.pdf also from the same author.
If you have the Sparkfun RFM22 Shield (https://www.sparkfun.com/products/11018) the connections described below are done for you on the shield, no changes required, just add headers and plug it in to an Arduino (but not and Arduino Mega, see below)
The physical connection between the RF22B and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO), a Slave Select pin and an interrupt pin. Note also that on the RFF22B, it is required to control the TX_ANT and X_ANT pins of the RFM22 in order to enable the antenna connection. The RF22 library is configured so that GPIO0 and GPIO1 outputs can control TX_ANT and RX_ANT input pins automatically. You must connect GPIO0 to TX_ANT and GPIO1 to RX_ANT for this automatic antenna switching to occur.
If you are using the Sparkfun RF22 shield, it will work with any 5V arduino without modification. Connect the RFM-22 module to most Arduino's like this (Caution, Arduino Mega has different pins for SPI, see below):
For an Arduino Mega:
For Chipkit Uno32. Caution: you must also ensure jumper JP4 on the Uno32 is set to RD4
and you can then use the default constructor RF22(). You can override the default settings for the SS pin and the interrupt in the RF22 constructor if you wish to connect the slave select SS to other than the normal one for your Arduino (D10 for Diecimila, Uno etc and D53 for Mega) or the interrupt request to other than pin D2 (Caution, different processors have different constraints as to the pins availbale for interrupts).
It is possible to have 2 radios connected to one arduino, provided each radio has its own SS and interrupt line (SCK, SDI and SDO are common to both radios)
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: Power supply requirements of the RF22 module may be relevant in some circumstances: RF22 modules are capable of pulling 80mA+ at full power, where Arduino's 3.3V line can give 50mA. You may need to make provision for alternate power supply for the RF22, especially if you wish to use full transmit power, and/or you have other shields demanding power. Inadequate power for the RF22 is reported to cause symptoms such as:
Caution: some RF22 breakout boards (such as the HAB-RFM22B-BOA HAB-RFM22B-BO) reportedly have the TX_ANT and RX_ANT pre-connected to GPIO0 and GPIO1 round the wrong way. You can work with this if you edit RF22.cpp and change the code that does spiWrite(RF22_REG_0B_GPIO_CONFIGURATION0, 0x12). See the comments there
Caution: If you are using a bare RF22 module without IO level shifters, you may have difficulty connecting to a 5V arduino. The RF22 module is 3.3V and its IO pins are 3.3V not 5V. Some Arduinos (Diecimila and Uno) seem to work OK with this, and some (Mega) do not always work reliably. Your Mileage May Vary. For best result, use level shifters, or use a RF22 shield or board with level shifters built in, such as the Sparkfun RFM22 shield http://www.sparkfun.com/products/11018. You could also use a 3.3V IO Arduino such as a Pro. It is recognised that it is difficult to connect the Sparkfun RFM22 shield to a Mega, since the SPI pins on the Mega are different to other Arduinos, But it is possible, by bending the SPI pins (D10, D11, D12, D13) on the shield out of the way before plugging it in to the Mega and jumpering the shield pins to the Mega like this:
The RF22 library uses interrupts to react to events in the RF22 module, such as the reception of a new packet, or the completion of transmission of a packet. The RF22 library interrupt service routine reads status from and writes data to the the RF22 module via the SPI interface. It is very important therefore, that if you are using the RF22 library with another SPI based deviced, that you disable interrupts while you transfer data to and from that other device. Use cli() to disable interrupts and sei() to reenable them.
The RF22 library requires non-trivial amounts of memory. The sample programs above all compile to about 9 to 14kbytes each, which will fit in the flash proram memory of most Arduinos. However, the RAM requirements are more critical. Most sample programs above will run on Duemilanova, but not on Diecimila. Even on Duemilanova, the RAM requirements are very close to the available memory of 2kbytes. Therefore, you should be vary sparing with RAM use in programs that use the RF22 library on Duemilanova.
It is often hard to accurately identify when you are hitting RAM limits on Arduino. The symptoms can include:
With an Arduino Mega, with 8 kbytes of SRAM, there is much more RAM headroom for your own elaborate programs. This library is reported to work with Arduino Pro Mini, but that has not been tested by me.
The Arduino UNO is now known to work with RF22.
The RF22M modules use an inexpensive crystal to control the frequency synthesizer, and therfore you can expect the transmitter and receiver frequencies to be subject to the usual inaccuracies of such crystals. The RF22 contains an AFC circuit to compensate for differences in transmitter and receiver frequencies. It does this by altering the receiver frequency during reception by up to the pull-in frequency range. This RF22 library enables the AFC and by default sets the pull-in frequency range to 0.05MHz, which should be sufficient to handle most situations. However, if you observe unexplained packet losses or failure to operate correctly all the time it may be because your modules have a wider frequency difference, and you may need to set the afcPullInRange to a differentvalue, using setFrequency();
Some simple speed performance tests have been conducted. In general packet transmission rate will be limited by the modulation scheme. Also, if your code does any slow operations like Serial printing it will also limit performance. We disabled any printing in the tests below. We tested with RF22::GFSK_Rb125Fd125, which is probably the fastest scheme available. We tested with a 13 octet message length, over a very short distance of 10cm.
Transmission (no reply) tests with modulation RF22::GFSK_Rb125Fd125 and a 13 octet message show about 330 messages per second transmitted.
Transmit-and-wait-for-a-reply tests with modulation RF22::GFSK_Rb125Fd125 and a 13 octet message (send and receive) show about 160 round trips per second.
Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.
This software is Copyright (C) 2011 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:
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
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@.firstname.lastname@example.org@m.payce.nosp@m..com for details.