RF22
RF22.h
1 // RF22.h
2 // Author: Mike McCauley (mikem@airspayce.com)
3 // Copyright (C) 2011 Mike McCauley
4 // $Id: RF22.h,v 1.25 2014/04/01 05:06:44 mikem Exp mikem $
5 //
6 /// \mainpage RF22 library for Arduino
7 ///
8 /// \par END OF LIFE NOTICE
9 ///
10 /// This RF22 library has now been superceded by the RadioHead
11 /// library http://www.airspayce.com/mikem/arduino/RadioHead
12 /// RadioHead and its RH_RF22 driver provides all the features supported by RF22, and much more
13 /// besides, including Reliable Datagrams, Addressing, Routing and Meshes. All the platforms that
14 /// RF22 supported are also supported by RadioHead.
15 ///
16 /// This library will no longer be maintained or updated, but we will continue to publish
17 /// it for the benefit of the the community, and you may continue to use it within the terms of
18 /// the license. Nevertheless we recommend upgrading to RadioHead where
19 /// possible.
20 ///
21 /// This is the Arduino RF22 library.
22 /// It provides an object-oriented interface for sending and receiving data messages with Hope-RF
23 /// RF22B based radio modules, and compatible chips and modules,
24 /// including the RFM22B transceiver module such as
25 /// this bare module: http://www.sparkfun.com/products/10153
26 /// and this shield: http://www.sparkfun.com/products/11018
27 ///
28 /// RF22 also supports some of the features of ZigBee and XBee,
29 /// (such as mesh routing and automatic route discovery),
30 /// but with a much less complicated system and less expensive radios.
31 ///
32 /// The Hope-RF (http://www.hoperf.com) RFM22B (http://www.hoperf.com/rf_fsk/fsk/RFM22B.htm)
33 /// is a low-cost ISM transceiver module. It supports FSK, GFSK, OOK over a wide
34 /// range of frequencies and programmable data rates.
35 /// Manual can be found at https://www.sparkfun.com/datasheets/Wireless/General/RFM22.PDF
36 ///
37 /// This library provides functions for sending and receiving messages of up to 255 octets on any
38 /// frequency supported by the RF22B, in a range of predefined data rates and frequency deviations.
39 /// Frequency can be set with 312Hz precision to any frequency from 240.0MHz to 960.0MHz.
40 ///
41 /// Up to 3 RF22B modules can be connected to an Arduino, permitting the construction of translators
42 /// and frequency changers, etc.
43 ///
44 /// This library provides classes for
45 /// - RF22: unaddressed, unreliable messages
46 /// - RF22Datagram: addressed, unreliable messages
47 /// - RF22ReliableDatagram: addressed, reliable, retransmitted, acknowledged messages.
48 /// - RF22Router: multi hop delivery from source node to destination node via 0 or more intermediate nodes
49 /// - RF22Mesh: multi hop delivery with automatic route discovery and rediscovery.
50 ///
51 /// The following modulation types are suppported with a range of modem configurations for
52 /// common data rates and frequency deviations:
53 /// - GFSK Gaussian Frequency Shift Keying
54 /// - FSK Frequency Shift Keying
55 /// - OOK On-Off Keying
56 ///
57 /// Support for other RF22B features such as on-chip temperature measurement, analog-digital
58 /// converter, transmitter power control etc is also provided.
59 ///
60 /// The latest version of this documentation can be downloaded from
61 /// http://www.airspayce.com/mikem/arduino/RF22
62 ///
63 /// Example Arduino programs are included to show the main modes of use.
64 ///
65 /// The version of the package that this documentation refers to can be downloaded
66 /// from http://www.airspayce.com/mikem/arduino/RF22/RF22-1.40.zip
67 /// You can find the latest version at http://www.airspayce.com/mikem/arduino/RF22
68 ///
69 /// You can also find online help and disussion at
70 /// http://groups.google.com/group/rf22-arduino
71 /// Please use that group for all questions and discussions on this topic.
72 /// Do not contact the author directly, unless it is to discuss commercial licensing.
73 /// Before asking a question or reporting a bug, please read http://www.catb.org/esr/faqs/smart-questions.html
74 ///
75 /// Tested on Arduino Diecimila and Mega with arduino-0021
76 /// on OpenSuSE 11.1 and avr-libc-1.6.1-1.15,
77 /// cross-avr-binutils-2.19-9.1, cross-avr-gcc-4.1.3_20080612-26.5.
78 /// With HopeRF RFM22 modules that appear to have RF22B chips on board:
79 /// - Device Type Code = 0x08 (RX/TRX)
80 /// - Version Code = 0x06
81 /// Works on Duo. Works with Sparkfun RFM22 Wireless shields.
82 /// Works with Arduino 1.0 to at least 1.0.4
83 ///
84 /// \par Packet Format
85 ///
86 /// All messages sent and received by this RF22 library must conform to this packet format:
87 ///
88 /// - 8 nibbles (4 octets) PREAMBLE
89 /// - 2 octets SYNC 0x2d, 0xd4
90 /// - 4 octets HEADER: (TO, FROM, ID, FLAGS)
91 /// - 1 octet LENGTH (0 to 255), number of octets in DATA
92 /// - 0 to 255 octets DATA
93 /// - 2 octets CRC computed with CRC16(IBM), computed on HEADER, LENGTH and DATA
94 ///
95 /// For technical reasons, the message format is not compatible with the
96 /// 'HopeRF Radio Transceiver Message Library for Arduino' http://www.airspayce.com/mikem/arduino/HopeRF from the same author. Nor is it compatible with
97 /// 'Virtual Wire' http://www.airspayce.com/mikem/arduino/VirtualWire.pdf also from the same author.
98 ///
99 /// \par Connecting RFM-22 to Arduino
100 ///
101 /// If you have the Sparkfun RFM22 Shield (https://www.sparkfun.com/products/11018)
102 /// the connections described below are done for you on the shield, no changes required,
103 /// just add headers and plug it in to an Arduino (but not and Arduino Mega, see below)
104 ///
105 /// The physical connection between the RF22B and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO),
106 /// a Slave Select pin and an interrupt pin.
107 /// 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
108 /// antenna connection. The RF22 library is configured so that GPIO0 and GPIO1 outputs can control TX_ANT and RX_ANT input pins
109 /// automatically. You must connect GPIO0 to TX_ANT and GPIO1 to RX_ANT for this automatic antenna switching to occur.
110 ///
111 /// If you are using the Sparkfun RF22 shield, it will work with any 5V arduino without modification.
112 /// Connect the RFM-22 module to most Arduino's like this (Caution, Arduino Mega has different pins for SPI,
113 /// see below):
114 /// \code
115 /// Arduino RFM-22B
116 /// GND----------GND-\ (ground in)
117 /// SDN-/ (shutdown in)
118 /// 3V3----------VCC (3.3V in)
119 /// interrupt 0 pin D2-----------NIRQ (interrupt request out)
120 /// SS pin D10----------NSEL (chip select in)
121 /// SCK pin D13----------SCK (SPI clock in)
122 /// MOSI pin D11----------SDI (SPI Data in)
123 /// MISO pin D12----------SDO (SPI data out)
124 /// /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT
125 /// \--TX_ANT (TX antenna control in)
126 /// /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT
127 /// \--RX_ANT (RX antenna control in)
128 /// \endcode
129 /// For an Arduino Mega:
130 /// \code
131 /// Mega RFM-22B
132 /// GND----------GND-\ (ground in)
133 /// SDN-/ (shutdown in)
134 /// 3V3----------VCC (3.3V in)
135 /// interrupt 0 pin D2-----------NIRQ (interrupt request out)
136 /// SS pin D53----------NSEL (chip select in)
137 /// SCK pin D52----------SCK (SPI clock in)
138 /// MOSI pin D51----------SDI (SPI Data in)
139 /// MISO pin D50----------SDO (SPI data out)
140 /// /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT
141 /// \--TX_ANT (TX antenna control in)
142 /// /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT
143 /// \--RX_ANT (RX antenna control in)
144 /// \endcode
145 /// For Chipkit Uno32. Caution: you must also ensure jumper JP4 on the Uno32 is set to RD4
146 /// \code
147 /// Arduino RFM-22B
148 /// GND----------GND-\ (ground in)
149 /// SDN-/ (shutdown in)
150 /// 3V3----------VCC (3.3V in)
151 /// interrupt 0 pin D38----------NIRQ (interrupt request out)
152 /// SS pin D10----------NSEL (chip select in)
153 /// SCK pin D13----------SCK (SPI clock in)
154 /// MOSI pin D11----------SDI (SPI Data in)
155 /// MISO pin D12----------SDO (SPI data out)
156 /// /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT
157 /// \--TX_ANT (TX antenna control in)
158 /// /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT
159 /// \--RX_ANT (RX antenna control in)
160 /// \endcode
161 ///
162 /// and you can then use the default constructor RF22().
163 /// You can override the default settings for the SS pin and the interrupt
164 /// in the RF22 constructor if you wish to connect the slave select SS to other than the normal one for your
165 /// Arduino (D10 for Diecimila, Uno etc and D53 for Mega)
166 /// or the interrupt request to other than pin D2 (Caution, different processors have different constraints as to the
167 /// pins available for interrupts).
168 ///
169 /// It is possible to have 2 radios connected to one Arduino, provided each radio has its own
170 /// SS and interrupt line (SCK, SDI and SDO are common to both radios)
171 ///
172 /// Caution: on some Arduinos such as the Mega 2560, if you set the slave select pin to be other than the usual SS
173 /// pin (D53 on Mega 2560), you may need to set the usual SS pin to be an output to force the Arduino into SPI
174 /// master mode.
175 ///
176 /// Caution: Power supply requirements of the RF22 module may be relevant in some circumstances:
177 /// RF22 modules are capable of pulling 80mA+ at full power, where Arduino's 3.3V line can
178 /// give 50mA. You may need to make provision for alternate power supply for
179 /// the RF22, especially if you wish to use full transmit power, and/or you have
180 /// other shields demanding power. Inadequate power for the RF22 is reported to cause symptoms such as:
181 /// - reset's/bootups terminate with "init failed" messages
182 /// -random termination of communication after 5-30 packets sent/received
183 /// -"fake ok" state, where initialization passes fluently, but communication doesn't happen
184 /// -shields hang Arduino boards, especially during the flashing
185 ///
186 /// Caution: some RF22 breakout boards (such as the HAB-RFM22B-BOA HAB-RFM22B-BO) reportedly
187 /// have the TX_ANT and RX_ANT pre-connected to GPIO0 and GPIO1 round the wrong way. You can work with this
188 /// if you edit RF22.cpp and change the code that does spiWrite(RF22_REG_0B_GPIO_CONFIGURATION0, 0x12).
189 /// See the comments there
190 ///
191 /// Caution: If you are using a bare RF22 module without IO level shifters, you may have difficulty connecting
192 /// to a 5V arduino. The RF22 module is 3.3V and its IO pins are 3.3V not 5V. Some Arduinos (Diecimila and
193 /// Uno) seem to work OK with this, and some (Mega) do not always work reliably. Your Mileage May Vary.
194 /// For best result, use level shifters, or use a RF22 shield or board with level shifters built in,
195 /// such as the Sparkfun RFM22 shield http://www.sparkfun.com/products/11018.
196 /// You could also use a 3.3V IO Arduino such as a Pro.
197 /// It is recognised that it is difficult to connect
198 /// the Sparkfun RFM22 shield to a Mega, since the SPI pins on the Mega are different to other Arduinos,
199 /// But it is possible, by bending the SPI pins (D10, D11, D12, D13) on the
200 /// shield out of the way before plugging it in to the Mega and jumpering the shield pins to the Mega like this:
201 /// \code
202 /// RF22 Shield Mega
203 /// D10 D53
204 /// D13 D52
205 /// D11 D51
206 /// D12 D50
207 /// \endcode
208 ///
209 /// \par Interrupts
210 ///
211 /// The RF22 library uses interrupts to react to events in the RF22 module,
212 /// such as the reception of a new packet, or the completion of transmission of a packet.
213 /// The RF22 library interrupt service routine reads status from and writes data
214 /// to the the RF22 module via the SPI interface. It is very important therefore,
215 /// that if you are using the RF22 library with another SPI based deviced, that you
216 /// disable interrupts while you transfer data to and from that other device.
217 /// Use cli() to disable interrupts and sei() to reenable them.
218 ///
219 /// \par SPI Interface
220 ///
221 /// The RF22 module uses the SPI bus to communicate with the Arduino. Arduino
222 /// IDE includes a hardware SPI class to communicate with SPI devices using
223 /// the SPI facilities built into the Atmel chips, over the standard designated
224 /// SPI pins MOSI, MISO, SCK, which are usually on Arduino pins 11, 12 and 13
225 /// respectively (or 51, 50, 52 on a Mega).
226 ///
227 /// By default, the RF22 library uses the Hardware SPI interface to
228 /// communicate with the RF22 module. However, if your RF22 SPI is connected to
229 /// the Arduino through non-standard pins, and the standard Hardware SPI
230 /// interface will not work for you, you can instead use a bit-banged Software
231 /// SPI, which can be configured to work on any Arduino digital IO pins. A
232 /// sample Software SPI class contributed by Chris Lapa is included in the
233 /// RF22 library, and example sketches showing how to use it are in
234 /// rf22_client_softwarespi and rf22_server_softwarespi. Thanks Chris!
235 ///
236 /// The advantages of the Software SPI interface are that it can be used on
237 /// any Arduino pins, not just the usual dedicated hardware pins. The
238 /// disadvantage is that it is slightly slower then hardware.
239 ///
240 /// \par Memory
241 ///
242 /// The RF22 library requires non-trivial amounts of memory. The sample programs above all compile to
243 /// about 9 to 14kbytes each, which will fit in the flash proram memory of most Arduinos. However,
244 /// the RAM requirements are more critical. Most sample programs above will run on Duemilanova,
245 /// but not on Diecimila. Even on Duemilanova, the RAM requirements are very close to the
246 /// available memory of 2kbytes. Therefore, you should be vary sparing with RAM use in programs that use
247 /// the RF22 library on Duemilanova.
248 ///
249 /// The sample RF22Router and RF22Mesh programs compile to about 14kbytes,
250 /// and require more RAM than the others.
251 /// They will not run on Duemilanova or Diecimila, but will run on Arduino Mega.
252 ///
253 /// It is often hard to accurately identify when you are hitting RAM limits on Arduino.
254 /// The symptoms can include:
255 /// - Mysterious crashes and restarts
256 /// - Changes in behaviour when seemingly unrelated changes are made (such as adding print() statements)
257 /// - Hanging
258 /// - Output from Serial.print() not appearing
259 ///
260 /// With an Arduino Mega, with 8 kbytes of SRAM, there is much more RAM headroom for
261 /// your own elaborate programs.
262 /// This library is reported to work with Arduino Pro Mini, but that has not been tested by me.
263 ///
264 /// The Arduino UNO is now known to work with RF22.
265 ///
266 /// \par Automatic Frequency Control (AFC)
267 ///
268 /// The RF22M modules use an inexpensive crystal to control the frequency synthesizer, and therfore you can expect
269 /// the transmitter and receiver frequencies to be subject to the usual inaccuracies of such crystals. The RF22
270 /// contains an AFC circuit to compensate for differences in transmitter and receiver frequencies.
271 /// It does this by altering the receiver frequency during reception by up to the pull-in frequency range.
272 /// This RF22 library enables the AFC and by default sets the pull-in frequency range to
273 /// 0.05MHz, which should be sufficient to handle most situations. However, if you observe unexplained packet losses
274 /// or failure to operate correctly all the time it may be because your modules have a wider frequency difference, and
275 /// you may need to set the afcPullInRange to a differentvalue, using setFrequency();
276 ///
277 /// \par Performance
278 ///
279 /// Some simple speed performance tests have been conducted.
280 /// In general packet transmission rate will be limited by the modulation scheme.
281 /// Also, if your code does any slow operations like Serial printing it will also limit performance.
282 /// We disabled any printing in the tests below.
283 /// We tested with RF22::GFSK_Rb125Fd125, which is probably the fastest scheme available.
284 /// We tested with a 13 octet message length, over a very short distance of 10cm.
285 ///
286 /// Transmission (no reply) tests with modulation RF22::GFSK_Rb125Fd125 and a
287 /// 13 octet message show about 330 messages per second transmitted.
288 ///
289 /// Transmit-and-wait-for-a-reply tests with modulation RF22::GFSK_Rb125Fd125 and a
290 /// 13 octet message (send and receive) show about 160 round trips per second.
291 ///
292 /// \par Installation
293 ///
294 /// Install in the usual way: unzip the distribution zip file to the libraries
295 /// sub-folder of your sketchbook.
296 ///
297 /// This software is Copyright (C) 2011 Mike McCauley. Use is subject to license
298 /// conditions. The main licensing options available are GPL V2 or Commercial:
299 ///
300 /// \par Donations
301 ///
302 /// This library is offered under a free GPL license for those who want to use it that way.
303 /// We try hard to keep it up to date, fix bugs
304 /// and to provide free support. If this library has helped you save time or money, please consider donating at
305 /// http://www.airspayce.com or here:
306 ///
307 /// \htmlonly <form action="https://www.paypal.com/cgi-bin/webscr" method="post"><input type="hidden" name="cmd" value="_donations" /> <input type="hidden" name="business" value="mikem@airspayce.com" /> <input type="hidden" name="lc" value="AU" /> <input type="hidden" name="item_name" value="Airspayce" /> <input type="hidden" name="item_number" value="RF22" /> <input type="hidden" name="currency_code" value="USD" /> <input type="hidden" name="bn" value="PP-DonationsBF:btn_donateCC_LG.gif:NonHosted" /> <input type="image" alt="PayPal — The safer, easier way to pay online." name="submit" src="https://www.paypalobjects.com/en_AU/i/btn/btn_donateCC_LG.gif" /> <img alt="" src="https://www.paypalobjects.com/en_AU/i/scr/pixel.gif" width="1" height="1" border="0" /></form> \endhtmlonly
308 ///
309 /// \par Open Source Licensing GPL V2
310 ///
311 /// This is the appropriate option if you want to share the source code of your
312 /// application with everyone you distribute it to, and you also want to give them
313 /// the right to share who uses it. If you wish to use this software under Open
314 /// Source Licensing, you must contribute all your source code to the open source
315 /// community in accordance with the GPL Version 2 when your application is
316 /// distributed. See http://www.gnu.org/copyleft/gpl.html
317 ///
318 /// \par Commercial Licensing
319 ///
320 /// This is the appropriate option if you are creating proprietary applications
321 /// and you are not prepared to distribute and share the source code of your
322 /// application. Contact info@airspayce.com for details.
323 ///
324 /// \par Revision History
325 ///
326 /// \version 1.0 Initial release
327 ///
328 /// \version 1.1 Added rf22_snoop and rf22_specan examples
329 ///
330 /// \version 1.2 Changed default modulation to FSK_Rb2_4Fd36
331 /// Some internal reorganisation.
332 /// Added RF22Router and RF22Mesh classes plus sample programs to support multi-hop and
333 /// automatic route discovery.
334 /// \version 1.3 Removed some unnecessary debug messages. Added virtual doArp and isPhysicalAddress
335 /// functions to RF22Mesh to support other physical address interpretation schemes (IPV4/IPV6?)
336 /// \version 1.4 RF22Router and RF22Mesh were inadvertently left out of the distro.
337 /// \version 1.5 Improvements contributed by Peter Mousley: Modem config table is now in flash rather than SRAM,
338 /// saving 400 bytes of SRAM. Allow a user-defined buffer size. Thanks Peter.
339 /// \version 1.6 Fixed some minor typos on doc and clarified that this code is for the RF22B. Fixed errors in the
340 /// definition of the power output constants which were incorrectly set to the values for the RF22.
341 /// Reported by Fred Slamen. If you were using a previous version of RF22, you probably were not getting the output
342 /// power you thought.
343 /// \version 1.7 Added code to initialise GPIO0 and GPIO1 so they can automatically control the TX_ANT and RX_ANT
344 /// antenna switching inputs. You must connect GPIO0 to TX_ANT and GPIO1 to RX_ANT for this automatic
345 /// antenna switching to occur. Updated doc to reflect this new connection requirement
346 /// \version 1.8 Changed the name of RF22_ENLBD in RF22_REG_06_INTERRUPT_ENABLE2 to RF22_ENLBDI because it collided
347 /// with a define of the same name in RF22_REG_07_OPERATING_MODE. RF22_REG_05_INTERRUPT_ENABLE1 enable mask
348 /// incorrectly used RF22_IFFERROR instead of RF22_ENFFERR. Reported by Steffan Woltjer.
349 /// \version 1.9 Fixed typos in RF22_REG_21_CLOCk*. Reported by Steffan Woltjer.
350 /// \version 1.10 Fixed a problem where a IFFERR during transmission could cause an infinite loop and a hang.
351 /// Reported by Raymond Gilbert.
352 /// \version 1.11 Fixed an innocuous typo in RF22::handleInterrupt. Reported by Zhentao.
353 ///
354 /// \version 1.12 Improvements to RF22::init from Guy Molinari to improve compatibility with some
355 /// Arduinos. Now reported to be working with official Mega 2560 and Uno.
356 /// Updated so compiles on Arduino 1.0.
357 ///
358 /// \version 1.13 Announce google support group
359 ///
360 /// \version 1.14 Added definitions for bits and masks in RF22_REG_1D_AFC_LOOP_GEARSHIFT_OVERRIDE
361 /// and RF22_REG_1E_AFC_TIMING_CONTROL
362 ///
363 /// \version 1.15 Small alterations to initialisation code so that SS pin is not set to output: may cause
364 /// interference with other devices connected to the Arduino. Testing with Uno: OK.
365 ///
366 /// \version 1.16 Fixed a problem that prevented building with arduino 0021
367 ///
368 /// \version 1.17 Added optional AFC pull-in frequency range argument to setFrequency().
369 /// Default AFC pull-in range set to 0.05MHz
370 ///
371 /// \version 1.18 Changed default value for slave slect pin in constructor to be SS, ie the normal one for
372 /// the compiled Arduino (D10 for Diecimila, Uno etc and D53 for Mega). This is because some Arduinos such as Mega 2560
373 /// reportedly use the type of the SS pin to determine whether to run in slave or master mode. Therfore it
374 /// is preferred that the slave select pin actually be the normal SS pin.
375 ///
376 /// \version 1.19 Added new mode() function.
377 /// Fixed a potential race condition in RF22Datagram::recvfrom which might cause corrupt from, to, id or flags
378 /// under extreme circumstances. Improvements to interrupt hygeine by adding cli()_/sei() around all
379 /// RF22 register acceses. Found that 0 length transmit packets confuses the RF22, so they are now forbidden.
380 /// Added IPGateway example, which routes UDP messages from an internet connection using an
381 /// Ethernet Shield and sends them
382 /// to a radio whose ID is based on the UDP port. Replies are sent back to the originating UDP
383 /// address and port.
384 ///
385 /// \version 1.20 _mode is now volatile.
386 /// RF22::send() now waits until any previous transmission is complete before sending.
387 /// RF22::waitPacketSent() now waits for the RF22 to not be in _mode == RF22_MODE_TX
388 /// _txPacketSent member is now redundant and removed.
389 /// Improvements to interrupt handling and blocking. Now use ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
390 /// to prevent reenabling interrupts too soon. Thanks to Roland Mieslinger for this suggestion.
391 /// Added some performance measurements to documentation.
392 ///
393 /// \version 1.21 Fixed a case where a receiver buffer overflow could occur. Reported by Joe Tuttle.
394 ///
395 /// \version 1.22 Added documentation after testing with Sparkfun RFM22 Shield DEV-11018.
396 /// Fixed incorrect link to register calculator excel file, reported by Joey Morin.
397 ///
398 /// \version 1.23 Added support for alternative SPI interfaces, with default implementation for the standard
399 /// Arduino hardware SPI interface. Contributed by Joanna Rutkowska.
400 ///
401 /// \version 1.24 Fixed a problem that could cause corrupted receive messages if a transmit interrupted
402 /// a partial receive (as was common with eg ReliableDatagram with poor reception.
403 /// Also fixed possible receive buffer overrun.
404 /// \version 1.25 More rigorous use of const, additional register defines (RF22_CRCHDRS RF22_VARPKLEN)
405 /// and two methods (setPreambleLength()
406 /// and setSyncWords())made public. Patch provided by
407 /// Matthijs Kooijman.
408 /// \version 1.26 Added Cautions about RF22 IO voltages , level shifters and Mega. Include
409 /// Doxygen documentation in distribution.
410 /// \version 1.27 Updated author and distribution location details to airspayce.com
411 /// Added example demodulated data from an actual RF22 transmission assembled
412 /// by this RF22 library
413 /// \version 1.28 Fixed a problem that prevented packets of more than 59 octets being sent properly.
414 /// This problem was introduced in a recent update.
415 /// \version 1.29 Improvements to waitAvailableTimeout to make it robust on millis() rollover. Contributed by
416 /// Mats Byggmastar.
417 /// \version 1.30 More improvements to timeouts to be robust on millis() rollover. Contributed by
418 /// Mats Byggmastar.
419 /// \version 1.31 Added new function bool waitPacketSent(uint16_t timeout) requested by Benoit Joassart
420 /// \version 1.32 Can now specify interrupt number 2 in constructor.
421 /// \version 1.33 Now also compiles for Chipkit Uno32 under mpide-0023. Beta testing only.
422 /// Operational reports and testing are welcome.
423 /// \version 1.34 Added rf22_serial_modem example which implements a transparent
424 /// serial-radio-serial connection.
425 /// \version 1.35 Added setCRCPolynomial() to permit alternative CRC polynomials to be used for comptibility with
426 /// other radio hardware.
427 /// Fixed a case where noise or certain types of runt packets
428 /// could cause the RX fifo to get confused, losing the
429 /// start point of the next message.
430 /// Added missing define for RF22_SKIP2PH option for register 30.
431 /// Added new modem config FSK_Rb_512Fd2_5 for POCSAG for Kristoff Bonne.
432 /// \version 1.36 Added new modem config FSK_Rb_512Fd4_5 for POCSAG for Kristoff Bonne.
433 /// \version 1.37 Added SoftwareSPI.h, which is bit-banged software SPI interface class contributed by
434 /// by Chris Lapa. Also examples sketches rf22_client_softwarespi.ino and rf22_server_softwarespi.ino
435 /// showing how to use it.
436 /// \version 1.38 Chris Lapa corrected some minor errors in SoftwareSPI.h. Thanks Chris.
437 /// \version 1.39 rf22_serial_modem.ino was accidentally omitted
438 /// \version 1.40 Added End Of Life notice. This library will no longer be maintained
439 /// and updated: use RadioHead instead.
440 ///
441 /// \author Mike McCauley (mikem@airspayce.com) DO NOT CONTACT THE AUTHOR DIRECTLY. USE THE LISTS
442 
443 #ifndef RF22_h
444 #define RF22_h
445 
446 #if ARDUINO >= 100
447 #include <Arduino.h>
448 #else
449 #include <wiring.h>
450 #include "pins_arduino.h"
451 #endif
452 
453 // These defs cause trouble on some versions of Arduino
454 #undef round
455 #undef double
456 
457 // This is the maximum number of interrupts the library can support
458 // Most Arduinos can handle 2, Megas can handle more
459 #define RF22_NUM_INTERRUPTS 3
460 
461 // This is the bit in the SPI address that marks it as a write
462 #define RF22_SPI_WRITE_MASK 0x80
463 
464 // This is the maximum message length that can be supported by this library. Limited by
465 // the single message length octet in the header.
466 // Yes, 255 is correct even though the FIFO size in the RF22 is only
467 // 64 octets. We use interrupts to refill the Tx FIFO during transmission and to empty the
468 // Rx FIFO during reception
469 // Can be pre-defined to a smaller size (to save SRAM) prior to including this header
470 #ifndef RF22_MAX_MESSAGE_LEN
471 //#define RF22_MAX_MESSAGE_LEN 255
472 #define RF22_MAX_MESSAGE_LEN 50
473 #endif
474 
475 // Max number of octets the RF22 Rx and Tx FIFOs can hold
476 #define RF22_FIFO_SIZE 64
477 
478 // Keep track of the mode the RF22 is in
479 #define RF22_MODE_IDLE 0
480 #define RF22_MODE_RX 1
481 #define RF22_MODE_TX 2
482 
483 // These values we set for FIFO thresholds (4, 55) are actually the same as the POR values
484 #define RF22_TXFFAEM_THRESHOLD 4
485 #define RF22_RXFFAFULL_THRESHOLD 55
486 
487 // This is the default node address,
488 #define RF22_DEFAULT_NODE_ADDRESS 0
489 
490 // This address in the TO addreess signifies a broadcast
491 #define RF22_BROADCAST_ADDRESS 0xff
492 
493 // Number of registers to be passed to setModemConfig(). Obsolete.
494 #define RF22_NUM_MODEM_CONFIG_REGS 18
495 
496 // Register names
497 #define RF22_REG_00_DEVICE_TYPE 0x00
498 #define RF22_REG_01_VERSION_CODE 0x01
499 #define RF22_REG_02_DEVICE_STATUS 0x02
500 #define RF22_REG_03_INTERRUPT_STATUS1 0x03
501 #define RF22_REG_04_INTERRUPT_STATUS2 0x04
502 #define RF22_REG_05_INTERRUPT_ENABLE1 0x05
503 #define RF22_REG_06_INTERRUPT_ENABLE2 0x06
504 #define RF22_REG_07_OPERATING_MODE1 0x07
505 #define RF22_REG_08_OPERATING_MODE2 0x08
506 #define RF22_REG_09_OSCILLATOR_LOAD_CAPACITANCE 0x09
507 #define RF22_REG_0A_UC_OUTPUT_CLOCK 0x0a
508 #define RF22_REG_0B_GPIO_CONFIGURATION0 0x0b
509 #define RF22_REG_0C_GPIO_CONFIGURATION1 0x0c
510 #define RF22_REG_0D_GPIO_CONFIGURATION2 0x0d
511 #define RF22_REG_0E_IO_PORT_CONFIGURATION 0x0e
512 #define RF22_REG_0F_ADC_CONFIGURATION 0x0f
513 #define RF22_REG_10_ADC_SENSOR_AMP_OFFSET 0x10
514 #define RF22_REG_11_ADC_VALUE 0x11
515 #define RF22_REG_12_TEMPERATURE_SENSOR_CALIBRATION 0x12
516 #define RF22_REG_13_TEMPERATURE_VALUE_OFFSET 0x13
517 #define RF22_REG_14_WAKEUP_TIMER_PERIOD1 0x14
518 #define RF22_REG_15_WAKEUP_TIMER_PERIOD2 0x15
519 #define RF22_REG_16_WAKEUP_TIMER_PERIOD3 0x16
520 #define RF22_REG_17_WAKEUP_TIMER_VALUE1 0x17
521 #define RF22_REG_18_WAKEUP_TIMER_VALUE2 0x18
522 #define RF22_REG_19_LDC_MODE_DURATION 0x19
523 #define RF22_REG_1A_LOW_BATTERY_DETECTOR_THRESHOLD 0x1a
524 #define RF22_REG_1B_BATTERY_VOLTAGE_LEVEL 0x1b
525 #define RF22_REG_1C_IF_FILTER_BANDWIDTH 0x1c
526 #define RF22_REG_1D_AFC_LOOP_GEARSHIFT_OVERRIDE 0x1d
527 #define RF22_REG_1E_AFC_TIMING_CONTROL 0x1e
528 #define RF22_REG_1F_CLOCK_RECOVERY_GEARSHIFT_OVERRIDE 0x1f
529 #define RF22_REG_20_CLOCK_RECOVERY_OVERSAMPLING_RATE 0x20
530 #define RF22_REG_21_CLOCK_RECOVERY_OFFSET2 0x21
531 #define RF22_REG_22_CLOCK_RECOVERY_OFFSET1 0x22
532 #define RF22_REG_23_CLOCK_RECOVERY_OFFSET0 0x23
533 #define RF22_REG_24_CLOCK_RECOVERY_TIMING_LOOP_GAIN1 0x24
534 #define RF22_REG_25_CLOCK_RECOVERY_TIMING_LOOP_GAIN0 0x25
535 #define RF22_REG_26_RSSI 0x26
536 #define RF22_REG_27_RSSI_THRESHOLD 0x27
537 #define RF22_REG_28_ANTENNA_DIVERSITY1 0x28
538 #define RF22_REG_29_ANTENNA_DIVERSITY2 0x29
539 #define RF22_REG_2A_AFC_LIMITER 0x2a
540 #define RF22_REG_2B_AFC_CORRECTION_READ 0x2b
541 #define RF22_REG_2C_OOK_COUNTER_VALUE_1 0x2c
542 #define RF22_REG_2D_OOK_COUNTER_VALUE_2 0x2d
543 #define RF22_REG_2E_SLICER_PEAK_HOLD 0x2e
544 #define RF22_REG_30_DATA_ACCESS_CONTROL 0x30
545 #define RF22_REG_31_EZMAC_STATUS 0x31
546 #define RF22_REG_32_HEADER_CONTROL1 0x32
547 #define RF22_REG_33_HEADER_CONTROL2 0x33
548 #define RF22_REG_34_PREAMBLE_LENGTH 0x34
549 #define RF22_REG_35_PREAMBLE_DETECTION_CONTROL1 0x35
550 #define RF22_REG_36_SYNC_WORD3 0x36
551 #define RF22_REG_37_SYNC_WORD2 0x37
552 #define RF22_REG_38_SYNC_WORD1 0x38
553 #define RF22_REG_39_SYNC_WORD0 0x39
554 #define RF22_REG_3A_TRANSMIT_HEADER3 0x3a
555 #define RF22_REG_3B_TRANSMIT_HEADER2 0x3b
556 #define RF22_REG_3C_TRANSMIT_HEADER1 0x3c
557 #define RF22_REG_3D_TRANSMIT_HEADER0 0x3d
558 #define RF22_REG_3E_PACKET_LENGTH 0x3e
559 #define RF22_REG_3F_CHECK_HEADER3 0x3f
560 #define RF22_REG_40_CHECK_HEADER2 0x40
561 #define RF22_REG_41_CHECK_HEADER1 0x41
562 #define RF22_REG_42_CHECK_HEADER0 0x42
563 #define RF22_REG_43_HEADER_ENABLE3 0x43
564 #define RF22_REG_44_HEADER_ENABLE2 0x44
565 #define RF22_REG_45_HEADER_ENABLE1 0x45
566 #define RF22_REG_46_HEADER_ENABLE0 0x46
567 #define RF22_REG_47_RECEIVED_HEADER3 0x47
568 #define RF22_REG_48_RECEIVED_HEADER2 0x48
569 #define RF22_REG_49_RECEIVED_HEADER1 0x49
570 #define RF22_REG_4A_RECEIVED_HEADER0 0x4a
571 #define RF22_REG_4B_RECEIVED_PACKET_LENGTH 0x4b
572 #define RF22_REG_50_ANALOG_TEST_BUS_SELECT 0x50
573 #define RF22_REG_51_DIGITAL_TEST_BUS_SELECT 0x51
574 #define RF22_REG_52_TX_RAMP_CONTROL 0x52
575 #define RF22_REG_53_PLL_TUNE_TIME 0x53
576 #define RF22_REG_55_CALIBRATION_CONTROL 0x55
577 #define RF22_REG_56_MODEM_TEST 0x56
578 #define RF22_REG_57_CHARGE_PUMP_TEST 0x57
579 #define RF22_REG_58_CHARGE_PUMP_CURRENT_TRIMMING 0x58
580 #define RF22_REG_59_DIVIDER_CURRENT_TRIMMING 0x59
581 #define RF22_REG_5A_VCO_CURRENT_TRIMMING 0x5a
582 #define RF22_REG_5B_VCO_CALIBRATION 0x5b
583 #define RF22_REG_5C_SYNTHESIZER_TEST 0x5c
584 #define RF22_REG_5D_BLOCK_ENABLE_OVERRIDE1 0x5d
585 #define RF22_REG_5E_BLOCK_ENABLE_OVERRIDE2 0x5e
586 #define RF22_REG_5F_BLOCK_ENABLE_OVERRIDE3 0x5f
587 #define RF22_REG_60_CHANNEL_FILTER_COEFFICIENT_ADDRESS 0x60
588 #define RF22_REG_61_CHANNEL_FILTER_COEFFICIENT_VALUE 0x61
589 #define RF22_REG_62_CRYSTAL_OSCILLATOR_POR_CONTROL 0x62
590 #define RF22_REG_63_RC_OSCILLATOR_COARSE_CALIBRATION 0x63
591 #define RF22_REG_64_RC_OSCILLATOR_FINE_CALIBRATION 0x64
592 #define RF22_REG_65_LDO_CONTROL_OVERRIDE 0x65
593 #define RF22_REG_66_LDO_LEVEL_SETTINGS 0x66
594 #define RF22_REG_67_DELTA_SIGMA_ADC_TUNING1 0x67
595 #define RF22_REG_68_DELTA_SIGMA_ADC_TUNING2 0x68
596 #define RF22_REG_69_AGC_OVERRIDE1 0x69
597 #define RF22_REG_6A_AGC_OVERRIDE2 0x6a
598 #define RF22_REG_6B_GFSK_FIR_FILTER_COEFFICIENT_ADDRESS 0x6b
599 #define RF22_REG_6C_GFSK_FIR_FILTER_COEFFICIENT_VALUE 0x6c
600 #define RF22_REG_6D_TX_POWER 0x6d
601 #define RF22_REG_6E_TX_DATA_RATE1 0x6e
602 #define RF22_REG_6F_TX_DATA_RATE0 0x6f
603 #define RF22_REG_70_MODULATION_CONTROL1 0x70
604 #define RF22_REG_71_MODULATION_CONTROL2 0x71
605 #define RF22_REG_72_FREQUENCY_DEVIATION 0x72
606 #define RF22_REG_73_FREQUENCY_OFFSET1 0x73
607 #define RF22_REG_74_FREQUENCY_OFFSET2 0x74
608 #define RF22_REG_75_FREQUENCY_BAND_SELECT 0x75
609 #define RF22_REG_76_NOMINAL_CARRIER_FREQUENCY1 0x76
610 #define RF22_REG_77_NOMINAL_CARRIER_FREQUENCY0 0x77
611 #define RF22_REG_79_FREQUENCY_HOPPING_CHANNEL_SELECT 0x79
612 #define RF22_REG_7A_FREQUENCY_HOPPING_STEP_SIZE 0x7a
613 #define RF22_REG_7C_TX_FIFO_CONTROL1 0x7c
614 #define RF22_REG_7D_TX_FIFO_CONTROL2 0x7d
615 #define RF22_REG_7E_RX_FIFO_CONTROL 0x7e
616 #define RF22_REG_7F_FIFO_ACCESS 0x7f
617 
618 // These register masks etc are named wherever possible
619 // corresponding to the bit and field names in the RF-22 Manual
620 // RF22_REG_00_DEVICE_TYPE 0x00
621 #define RF22_DEVICE_TYPE_RX_TRX 0x08
622 #define RF22_DEVICE_TYPE_TX 0x07
623 
624 // RF22_REG_02_DEVICE_STATUS 0x02
625 #define RF22_FFOVL 0x80
626 #define RF22_FFUNFL 0x40
627 #define RF22_RXFFEM 0x20
628 #define RF22_HEADERR 0x10
629 #define RF22_FREQERR 0x08
630 #define RF22_LOCKDET 0x04
631 #define RF22_CPS 0x03
632 #define RF22_CPS_IDLE 0x00
633 #define RF22_CPS_RX 0x01
634 #define RF22_CPS_TX 0x10
635 
636 // RF22_REG_03_INTERRUPT_STATUS1 0x03
637 #define RF22_IFFERROR 0x80
638 #define RF22_ITXFFAFULL 0x40
639 #define RF22_ITXFFAEM 0x20
640 #define RF22_IRXFFAFULL 0x10
641 #define RF22_IEXT 0x08
642 #define RF22_IPKSENT 0x04
643 #define RF22_IPKVALID 0x02
644 #define RF22_ICRCERROR 0x01
645 
646 // RF22_REG_04_INTERRUPT_STATUS2 0x04
647 #define RF22_ISWDET 0x80
648 #define RF22_IPREAVAL 0x40
649 #define RF22_IPREAINVAL 0x20
650 #define RF22_IRSSI 0x10
651 #define RF22_IWUT 0x08
652 #define RF22_ILBD 0x04
653 #define RF22_ICHIPRDY 0x02
654 #define RF22_IPOR 0x01
655 
656 // RF22_REG_05_INTERRUPT_ENABLE1 0x05
657 #define RF22_ENFFERR 0x80
658 #define RF22_ENTXFFAFULL 0x40
659 #define RF22_ENTXFFAEM 0x20
660 #define RF22_ENRXFFAFULL 0x10
661 #define RF22_ENEXT 0x08
662 #define RF22_ENPKSENT 0x04
663 #define RF22_ENPKVALID 0x02
664 #define RF22_ENCRCERROR 0x01
665 
666 // RF22_REG_06_INTERRUPT_ENABLE2 0x06
667 #define RF22_ENSWDET 0x80
668 #define RF22_ENPREAVAL 0x40
669 #define RF22_ENPREAINVAL 0x20
670 #define RF22_ENRSSI 0x10
671 #define RF22_ENWUT 0x08
672 #define RF22_ENLBDI 0x04
673 #define RF22_ENCHIPRDY 0x02
674 #define RF22_ENPOR 0x01
675 
676 // RF22_REG_07_OPERATING_MODE 0x07
677 #define RF22_SWRES 0x80
678 #define RF22_ENLBD 0x40
679 #define RF22_ENWT 0x20
680 #define RF22_X32KSEL 0x10
681 #define RF22_TXON 0x08
682 #define RF22_RXON 0x04
683 #define RF22_PLLON 0x02
684 #define RF22_XTON 0x01
685 
686 // RF22_REG_08_OPERATING_MODE2 0x08
687 #define RF22_ANTDIV 0xc0
688 #define RF22_RXMPK 0x10
689 #define RF22_AUTOTX 0x08
690 #define RF22_ENLDM 0x04
691 #define RF22_FFCLRRX 0x02
692 #define RF22_FFCLRTX 0x01
693 
694 // RF22_REG_0F_ADC_CONFIGURATION 0x0f
695 #define RF22_ADCSTART 0x80
696 #define RF22_ADCDONE 0x80
697 #define RF22_ADCSEL 0x70
698 #define RF22_ADCSEL_INTERNAL_TEMPERATURE_SENSOR 0x00
699 #define RF22_ADCSEL_GPIO0_SINGLE_ENDED 0x10
700 #define RF22_ADCSEL_GPIO1_SINGLE_ENDED 0x20
701 #define RF22_ADCSEL_GPIO2_SINGLE_ENDED 0x30
702 #define RF22_ADCSEL_GPIO0_GPIO1_DIFFERENTIAL 0x40
703 #define RF22_ADCSEL_GPIO1_GPIO2_DIFFERENTIAL 0x50
704 #define RF22_ADCSEL_GPIO0_GPIO2_DIFFERENTIAL 0x60
705 #define RF22_ADCSEL_GND 0x70
706 #define RF22_ADCREF 0x0c
707 #define RF22_ADCREF_BANDGAP_VOLTAGE 0x00
708 #define RF22_ADCREF_VDD_ON_3 0x08
709 #define RF22_ADCREF_VDD_ON_2 0x0c
710 #define RF22_ADCGAIN 0x03
711 
712 // RF22_REG_10_ADC_SENSOR_AMP_OFFSET 0x10
713 #define RF22_ADCOFFS 0x0f
714 
715 // RF22_REG_12_TEMPERATURE_SENSOR_CALIBRATION 0x12
716 #define RF22_TSRANGE 0xc0
717 #define RF22_TSRANGE_M64_64C 0x00
718 #define RF22_TSRANGE_M64_192C 0x40
719 #define RF22_TSRANGE_0_128C 0x80
720 #define RF22_TSRANGE_M40_216F 0xc0
721 #define RF22_ENTSOFFS 0x20
722 #define RF22_ENTSTRIM 0x10
723 #define RF22_TSTRIM 0x0f
724 
725 // RF22_REG_14_WAKEUP_TIMER_PERIOD1 0x14
726 #define RF22_WTR 0x3c
727 #define RF22_WTD 0x03
728 
729 // RF22_REG_1D_AFC_LOOP_GEARSHIFT_OVERRIDE 0x1d
730 #define RF22_AFBCD 0x80
731 #define RF22_ENAFC 0x40
732 #define RF22_AFCGEARH 0x38
733 #define RF22_AFCGEARL 0x07
734 
735 // RF22_REG_1E_AFC_TIMING_CONTROL 0x1e
736 #define RF22_SWAIT_TIMER 0xc0
737 #define RF22_SHWAIT 0x38
738 #define RF22_ANWAIT 0x07
739 
740 // RF22_REG_30_DATA_ACCESS_CONTROL 0x30
741 #define RF22_ENPACRX 0x80
742 #define RF22_MSBFRST 0x00
743 #define RF22_LSBFRST 0x40
744 #define RF22_CRCHDRS 0x00
745 #define RF22_CRCDONLY 0x20
746 #define RF22_SKIP2PH 0x10
747 #define RF22_ENPACTX 0x08
748 #define RF22_ENCRC 0x04
749 #define RF22_CRC 0x03
750 #define RF22_CRC_CCITT 0x00
751 #define RF22_CRC_CRC_16_IBM 0x01
752 #define RF22_CRC_IEC_16 0x02
753 #define RF22_CRC_BIACHEVA 0x03
754 
755 // RF22_REG_32_HEADER_CONTROL1 0x32
756 #define RF22_BCEN 0xf0
757 #define RF22_BCEN_NONE 0x00
758 #define RF22_BCEN_HEADER0 0x10
759 #define RF22_BCEN_HEADER1 0x20
760 #define RF22_BCEN_HEADER2 0x40
761 #define RF22_BCEN_HEADER3 0x80
762 #define RF22_HDCH 0x0f
763 #define RF22_HDCH_NONE 0x00
764 #define RF22_HDCH_HEADER0 0x01
765 #define RF22_HDCH_HEADER1 0x02
766 #define RF22_HDCH_HEADER2 0x04
767 #define RF22_HDCH_HEADER3 0x08
768 
769 // RF22_REG_33_HEADER_CONTROL2 0x33
770 #define RF22_HDLEN 0x70
771 #define RF22_HDLEN_0 0x00
772 #define RF22_HDLEN_1 0x10
773 #define RF22_HDLEN_2 0x20
774 #define RF22_HDLEN_3 0x30
775 #define RF22_HDLEN_4 0x40
776 #define RF22_VARPKLEN 0x00
777 #define RF22_FIXPKLEN 0x08
778 #define RF22_SYNCLEN 0x06
779 #define RF22_SYNCLEN_1 0x00
780 #define RF22_SYNCLEN_2 0x02
781 #define RF22_SYNCLEN_3 0x04
782 #define RF22_SYNCLEN_4 0x06
783 #define RF22_PREALEN8 0x01
784 
785 // RF22_REG_6D_TX_POWER 0x6d
786 #define RF22_TXPOW 0x07
787 #define RF22_TXPOW_4X31 0x08 // Not used in RFM22B
788 #define RF22_TXPOW_1DBM 0x00
789 #define RF22_TXPOW_2DBM 0x01
790 #define RF22_TXPOW_5DBM 0x02
791 #define RF22_TXPOW_8DBM 0x03
792 #define RF22_TXPOW_11DBM 0x04
793 #define RF22_TXPOW_14DBM 0x05 // +28dBm on RF23bp
794 #define RF22_TXPOW_17DBM 0x06 // +29dBm on RF23bp
795 #define RF22_TXPOW_20DBM 0x07 // +30dBm on RF23bp
796 // IN RFM23B
797 #define RF22_TXPOW_LNA_SW 0x08
798 
799 // RF22_REG_71_MODULATION_CONTROL2 0x71
800 #define RF22_TRCLK 0xc0
801 #define RF22_TRCLK_NONE 0x00
802 #define RF22_TRCLK_GPIO 0x40
803 #define RF22_TRCLK_SDO 0x80
804 #define RF22_TRCLK_NIRQ 0xc0
805 #define RF22_DTMOD 0x30
806 #define RF22_DTMOD_DIRECT_GPIO 0x00
807 #define RF22_DTMOD_DIRECT_SDI 0x10
808 #define RF22_DTMOD_FIFO 0x20
809 #define RF22_DTMOD_PN9 0x30
810 #define RF22_ENINV 0x08
811 #define RF22_FD8 0x04
812 #define RF22_MODTYP 0x30
813 #define RF22_MODTYP_UNMODULATED 0x00
814 #define RF22_MODTYP_OOK 0x01
815 #define RF22_MODTYP_FSK 0x02
816 #define RF22_MODTYP_GFSK 0x03
817 
818 
819 // RF22_REG_75_FREQUENCY_BAND_SELECT 0x75
820 #define RF22_SBSEL 0x40
821 #define RF22_HBSEL 0x20
822 #define RF22_FB 0x1f
823 
824 // Define this to include Serial printing in diagnostic routines
825 #define RF22_HAVE_SERIAL
826 
827 #include <GenericSPI.h>
828 #include <HardwareSPI.h>
829 /////////////////////////////////////////////////////////////////////
830 /// \class RF22 RF22.h <RF22.h>
831 /// \brief Send and receive unaddressed, unreliable datagrams.
832 ///
833 /// This base class provides basic functions for sending and receiving unaddressed,
834 /// unreliable datagrams of arbitrary length to 255 octets per packet.
835 ///
836 /// Subclasses may use this class to implement reliable, addressed datagrams and streams,
837 /// mesh routers, repeaters, translators etc.
838 ///
839 /// On transmission, the TO and FROM addresses default to 0x00, unless changed by a subclass.
840 /// On reception the TO addressed is checked against the node address (defaults to 0x00) or the
841 /// broadcast address (which is 0xff). The ID and FLAGS are set to 0, and not checked by this class.
842 /// This permits use of the this base RF22 class as an
843 /// unaddresed, unreliable datagram service. Subclasses are expected to change this behaviour to
844 /// add node address, ids, retransmission etc
845 ///
846 /// Naturally, for any 2 radios to communicate that must be configured to use the same frequence and
847 /// modulation scheme.
848 class RF22
849 {
850 public:
851 
852  /// \brief Defines register values for a set of modem configuration registers
853  ///
854  /// Defines register values for a set of modem configuration registers
855  /// that can be passed to setModemConfig()
856  /// if none of the choices in ModemConfigChoice suit your need
857  /// setModemConfig() writes the register values to the appropriate RF22 registers
858  /// to set the desired modulation type, data rate and deviation/bandwidth.
859  /// Suitable values for these registers can be computed using the register calculator at
860  /// http://www.hoperf.com/upload/rf/RF22B%2023B%2031B%2042B%2043B%20Register%20Settings_RevB1-v5.xls
861  typedef struct
862  {
863  uint8_t reg_1c; ///< Value for register RF22_REG_1C_IF_FILTER_BANDWIDTH
864  uint8_t reg_1f; ///< Value for register RF22_REG_1F_CLOCK_RECOVERY_GEARSHIFT_OVERRIDE
865  uint8_t reg_20; ///< Value for register RF22_REG_20_CLOCK_RECOVERY_OVERSAMPLING_RATE
866  uint8_t reg_21; ///< Value for register RF22_REG_21_CLOCK_RECOVERY_OFFSET2
867  uint8_t reg_22; ///< Value for register RF22_REG_22_CLOCK_RECOVERY_OFFSET1
868  uint8_t reg_23; ///< Value for register RF22_REG_23_CLOCK_RECOVERY_OFFSET0
869  uint8_t reg_24; ///< Value for register RF22_REG_24_CLOCK_RECOVERY_TIMING_LOOP_GAIN1
870  uint8_t reg_25; ///< Value for register RF22_REG_25_CLOCK_RECOVERY_TIMING_LOOP_GAIN0
871  uint8_t reg_2c; ///< Value for register RF22_REG_2C_OOK_COUNTER_VALUE_1
872  uint8_t reg_2d; ///< Value for register RF22_REG_2D_OOK_COUNTER_VALUE_2
873  uint8_t reg_2e; ///< Value for register RF22_REG_2E_SLICER_PEAK_HOLD
874  uint8_t reg_58; ///< Value for register RF22_REG_58_CHARGE_PUMP_CURRENT_TRIMMING
875  uint8_t reg_69; ///< Value for register RF22_REG_69_AGC_OVERRIDE1
876  uint8_t reg_6e; ///< Value for register RF22_REG_6E_TX_DATA_RATE1
877  uint8_t reg_6f; ///< Value for register RF22_REG_6F_TX_DATA_RATE0
878  uint8_t reg_70; ///< Value for register RF22_REG_70_MODULATION_CONTROL1
879  uint8_t reg_71; ///< Value for register RF22_REG_71_MODULATION_CONTROL2
880  uint8_t reg_72; ///< Value for register RF22_REG_72_FREQUENCY_DEVIATION
881  } ModemConfig;
882 
883  /// Choices for setModemConfig() for a selected subset of common modulation types,
884  /// and data rates. If you need another configuration, use the register calculator.
885  /// and call setModemRegisters() with your desired settings
886  /// These are indexes into MODEM_CONFIG_TABLE
887  typedef enum
888  {
889  UnmodulatedCarrier = 0, ///< Unmodulated carrier for testing
890  FSK_PN9_Rb2Fd5, ///< FSK, No Manchester, Rb = 2kbs, Fd = 5kHz, PN9 random modulation for testing
891 
892  FSK_Rb2Fd5, ///< FSK, No Manchester, Rb = 2kbs, Fd = 5kHz
893  FSK_Rb2_4Fd36, ///< FSK, No Manchester, Rb = 2.4kbs, Fd = 36kHz
894  FSK_Rb4_8Fd45, ///< FSK, No Manchester, Rb = 4.8kbs, Fd = 45kHz
895  FSK_Rb9_6Fd45, ///< FSK, No Manchester, Rb = 9.6kbs, Fd = 45kHz
896  FSK_Rb19_2Fd9_6, ///< FSK, No Manchester, Rb = 19.2kbs, Fd = 9.6kHz
897  FSK_Rb38_4Fd19_6, ///< FSK, No Manchester, Rb = 38.4kbs, Fd = 19.6kHz
898  FSK_Rb57_6Fd28_8, ///< FSK, No Manchester, Rb = 57.6kbs, Fd = 28.8kHz
899  FSK_Rb125Fd125, ///< FSK, No Manchester, Rb = 125kbs, Fd = 125kHz
900  FSK_Rb_512Fd2_5, ///< FSK, No Manchester, Rb = 512bs, Fd = 2.5kHz, for POCSAG compatibility
901  FSK_Rb_512Fd4_5, ///< FSK, No Manchester, Rb = 512bs, Fd = 4.5kHz, for POCSAG compatibility
902 
903  GFSK_Rb2Fd5, ///< GFSK, No Manchester, Rb = 2kbs, Fd = 5kHz
904  GFSK_Rb2_4Fd36, ///< GFSK, No Manchester, Rb = 2.4kbs, Fd = 36kHz
905  GFSK_Rb4_8Fd45, ///< GFSK, No Manchester, Rb = 4.8kbs, Fd = 45kHz
906  GFSK_Rb9_6Fd45, ///< GFSK, No Manchester, Rb = 9.6kbs, Fd = 45kHz
907  GFSK_Rb19_2Fd9_6, ///< GFSK, No Manchester, Rb = 19.2kbs, Fd = 9.6kHz
908  GFSK_Rb38_4Fd19_6, ///< GFSK, No Manchester, Rb = 38.4kbs, Fd = 19.6kHz
909  GFSK_Rb57_6Fd28_8, ///< GFSK, No Manchester, Rb = 57.6kbs, Fd = 28.8kHz
910  GFSK_Rb125Fd125, ///< GFSK, No Manchester, Rb = 125kbs, Fd = 125kHz
911 
912  OOK_Rb1_2Bw75, ///< OOK, No Manchester, Rb = 1.2kbs, Rx Bandwidth = 75kHz
913  OOK_Rb2_4Bw335, ///< OOK, No Manchester, Rb = 2.4kbs, Rx Bandwidth = 335kHz
914  OOK_Rb4_8Bw335, ///< OOK, No Manchester, Rb = 4.8kbs, Rx Bandwidth = 335kHz
915  OOK_Rb9_6Bw335, ///< OOK, No Manchester, Rb = 9.6kbs, Rx Bandwidth = 335kHz
916  OOK_Rb19_2Bw335, ///< OOK, No Manchester, Rb = 19.2kbs, Rx Bandwidth = 335kHz
917  OOK_Rb38_4Bw335, ///< OOK, No Manchester, Rb = 38.4kbs, Rx Bandwidth = 335kHz
918  OOK_Rb40Bw335 ///< OOK, No Manchester, Rb = 40kbs, Rx Bandwidth = 335kHz
920 
921  /// \brief Defines the available choices for CRC
922  /// Types of permitted CRC polynomials, to be passed to setCRCPolynomial()
923  /// They deliberately have the same numeric values as the crc[1:0] field of Register
924  /// RF22_REG_30_DATA_ACCESS_CONTROL
925  typedef enum
926  {
927  CRC_CCITT = 0, ///< CCITT
928  CRC_16_IBM = 1, ///< CRC-16 (IBM) The default used by RF22 library
929  CRC_IEC_16 = 2, ///< IEC-16
930  CRC_Biacheva = 3 ///< Biacheva
931  } CRCPolynomial;
932 
933  /// Constructor. You can have multiple instances, but each instance must have its own
934  /// interrupt and slave select pin. After constructing, you must call init() to initialise the intnerface
935  /// and the radio module
936  /// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the RF22 before
937  /// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega)
938  /// \param[in] interrupt The interrupt number to use. 0 - 2. Default is interrupt 0 (Arduino input pin 2)
939  /// \param[in] spi Pointer to the SPI interface object to use.
940  /// Defaults to the standard Arduino hardware SPI interface
941  RF22(uint8_t slaveSelectPin = SS, uint8_t interrupt = 0, GenericSPIClass *spi = &Hardware_spi);
942 
943  /// Initialises this instance and the radio module connected to it.
944  /// The following steps are taken:
945  /// - Initialise the slave select pin and the SPI interface library
946  /// - Software reset the RF22 module
947  /// - Checks the connected RF22 module is either a RF22_DEVICE_TYPE_RX_TRX or a RF22_DEVICE_TYPE_TX
948  /// - Attaches an interrupt handler
949  /// - Configures the RF22 module
950  /// - Sets the frequency to 434.0 MHz
951  /// - Sets the modem data rate to FSK_Rb2_4Fd36
952  /// \return true if everything was successful
953  boolean init();
954 
955  /// Issues a software reset to the
956  /// RF22 module. Blocks for 1ms to ensure the reset is complete.
957  void reset();
958 
959  /// Reads a single register from the RF22
960  /// \param[in] reg Register number, one of RF22_REG_*
961  /// \return The value of the register
962  uint8_t spiRead(uint8_t reg);
963 
964  /// Writes a single byte to the RF22
965  /// \param[in] reg Register number, one of RF22_REG_*
966  /// \param[in] val The value to write
967  void spiWrite(uint8_t reg, uint8_t val);
968 
969  /// Reads a number of consecutive registers from the RF22 using burst read mode
970  /// \param[in] reg Register number of the first register, one of RF22_REG_*
971  /// \param[in] dest Array to write the register values to. Must be at least len bytes
972  /// \param[in] len Number of bytes to read
973  void spiBurstRead(uint8_t reg, uint8_t* dest, uint8_t len);
974 
975  /// Write a number of consecutive registers using burst write mode
976  /// \param[in] reg Register number of the first register, one of RF22_REG_*
977  /// \param[in] src Array of new register values to write. Must be at least len bytes
978  /// \param[in] len Number of bytes to write
979  void spiBurstWrite(uint8_t reg, const uint8_t* src, uint8_t len);
980 
981  /// Reads and returns the device status register RF22_REG_02_DEVICE_STATUS
982  /// \return The value of the device status register
983  uint8_t statusRead();
984 
985  /// Reads a value from the on-chip analog-digital converter
986  /// \param[in] adcsel Selects the ADC input to measure. One of RF22_ADCSEL_*. Defaults to the
987  /// internal temperature sensor
988  /// \param[in] adcref Specifies the refernce voltage to use. One of RF22_ADCREF_*.
989  /// Defaults to the internal bandgap voltage.
990  /// \param[in] adcgain Amplifier gain selection.
991  /// \param[in] adcoffs Amplifier offseet (0 to 15).
992  /// \return The analog value. 0 to 255.
993  uint8_t adcRead(uint8_t adcsel = RF22_ADCSEL_INTERNAL_TEMPERATURE_SENSOR,
994  uint8_t adcref = RF22_ADCREF_BANDGAP_VOLTAGE,
995  uint8_t adcgain = 0,
996  uint8_t adcoffs = 0);
997 
998  /// Reads the on-chip temperature sensoer
999  /// \param[in] tsrange Specifies the temperature range to use. One of RF22_TSRANGE_*
1000  /// \param[in] tvoffs Specifies the temperature value offset. This is actually signed value
1001  /// added to the measured temperature value
1002  /// \return The measured temperature.
1003  uint8_t temperatureRead(uint8_t tsrange = RF22_TSRANGE_M64_64C, uint8_t tvoffs = 0);
1004 
1005  /// Reads the wakeup timer value in registers RF22_REG_17_WAKEUP_TIMER_VALUE1
1006  /// and RF22_REG_18_WAKEUP_TIMER_VALUE2
1007  /// \return The wakeup timer value
1008  uint16_t wutRead();
1009 
1010  /// Sets the wakeup timer period registers RF22_REG_14_WAKEUP_TIMER_PERIOD1,
1011  /// RF22_REG_15_WAKEUP_TIMER_PERIOD2 and RF22_R<EG_16_WAKEUP_TIMER_PERIOD3
1012  /// \param[in] wtm Wakeup timer mantissa value
1013  /// \param[in] wtr Wakeup timer exponent R value
1014  /// \param[in] wtd Wakeup timer exponent D value
1015  void setWutPeriod(uint16_t wtm, uint8_t wtr = 0, uint8_t wtd = 0);
1016 
1017  /// Sets the transmitter and receiver centre frequency
1018  /// \param[in] centre Frequency in MHz. 240.0 to 960.0. Caution, some versions of RF22 and derivatives
1019  /// implemented more restricted frequency ranges.
1020  /// \param[in] afcPullInRange Sets the AF Pull In Range in MHz. Defaults to 0.05MHz (50kHz).
1021  /// Range is 0.0 to 0.159375
1022  /// for frequencies 240.0 to 480MHz, and 0.0 to 0.318750MHz for frequencies 480.0 to 960MHz,
1023  /// \return true if the selected frquency centre + (fhch * fhs) is within range and the afcPullInRange
1024  /// is within range
1025  boolean setFrequency(float centre, float afcPullInRange = 0.05);
1026 
1027  /// Sets the frequency hopping step size.
1028  /// \param[in] fhs Frequency Hopping step size in 10kHz increments
1029  /// \return true if centre + (fhch * fhs) is within limits
1030  boolean setFHStepSize(uint8_t fhs);
1031 
1032  /// Sets the frequncy hopping channel. Adds fhch * fhs to centre frequency
1033  /// \param[in] fhch The channel number
1034  /// \return true if the selected frquency centre + (fhch * fhs) is within range
1035  boolean setFHChannel(uint8_t fhch);
1036 
1037  /// Reads and returns the current RSSI value from register RF22_REG_26_RSSI. If you want to find the RSSI
1038  /// of the last received message, use lastRssi() instead.
1039  /// \return The current RSSI value
1040  uint8_t rssiRead();
1041 
1042  /// Reads and returns the current EZMAC value from register RF22_REG_31_EZMAC_STATUS
1043  /// \return The current EZMAC value
1044  uint8_t ezmacStatusRead();
1045 
1046  /// Sets the parameters for the RF22 Idle mode in register RF22_REG_07_OPERATING_MODE.
1047  /// Idle mode is the mode the RF22 will be in when not transmitting or receiving. The default idle mode
1048  /// is RF22_XTON ie READY mode.
1049  /// \param[in] mode Mask of mode bits, using RF22_SWRES, RF22_ENLBD, RF22_ENWT,
1050  /// RF22_X32KSEL, RF22_PLLON, RF22_XTON.
1051  void setMode(uint8_t mode);
1052 
1053  /// If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running,
1054  /// disables them.
1055  void setModeIdle();
1056 
1057  /// If current mode is Tx or Idle, changes it to Rx.
1058  /// Starts the receiver in the RF22.
1059  void setModeRx();
1060 
1061  /// If current mode is Rx or Idle, changes it to Rx.
1062  /// Starts the transmitter in the RF22.
1063  void setModeTx();
1064 
1065  /// Returns the operating mode of the library.
1066  /// \return the current mode, one of RF22_MODE_*
1067  uint8_t mode();
1068 
1069  /// Sets the transmitter power output level in register RF22_REG_6D_TX_POWER.
1070  /// Be a good neighbour and set the lowest power level you need.
1071  /// After init(), the power will be set to RF22_TXPOW_8DBM.
1072  /// Caution: In some countries you may only select RF22_TXPOW_17DBM if you
1073  /// are also using frequency hopping.
1074  /// \param[in] power Transmitter power level, one of RF22_TXPOW_*
1075  void setTxPower(uint8_t power);
1076 
1077  /// Sets all the registered required to configure the data modem in the RF22, including the data rate,
1078  /// bandwidths etc. You cas use this to configure the modem with custom configuraitons if none of the
1079  /// canned configurations in ModemConfigChoice suit you.
1080  /// \param[in] config A ModemConfig structure containing values for the modem configuration registers.
1081  void setModemRegisters(const ModemConfig* config);
1082 
1083  /// Select one of the predefined modem configurations. If you need a modem configuration not provided
1084  /// here, use setModemRegisters() with your own ModemConfig.
1085  /// \param[in] index The configuration choice.
1086  /// \return true if index is a valid choice.
1087  boolean setModemConfig(ModemConfigChoice index);
1088 
1089  /// Starts the receiver and checks whether a received message is available.
1090  /// This can be called multiple times in a timeout loop
1091  /// \return true if a complete, valid message has been received and is able to be retrieved by
1092  /// recv()
1093  boolean available();
1094 
1095  /// Starts the receiver and blocks until a valid received
1096  /// message is available.
1097  void waitAvailable();
1098 
1099  /// Starts the receiver and blocks until a received message is available or a timeout
1100  /// \param[in] timeout Maximum time to wait in milliseconds.
1101  /// \return true if a message is available
1102  bool waitAvailableTimeout(uint16_t timeout);
1103 
1104  /// Turns the receiver on if it not already on.
1105  /// If there is a valid message available, copy it to buf and return true
1106  /// else return false.
1107  /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
1108  /// You should be sure to call this function frequently enough to not miss any messages
1109  /// It is recommended that you call it in your main loop.
1110  /// \param[in] buf Location to copy the received message
1111  /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
1112  /// \return true if a valid message was copied to buf
1113  boolean recv(uint8_t* buf, uint8_t* len);
1114 
1115  /// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
1116  /// Then loads a message into the transmitter and starts the transmitter. Note that a message length
1117  /// of 0 is NOT permitted.
1118  /// \param[in] data Array of data to be sent
1119  /// \param[in] len Number of bytes of data to send (> 0)
1120  /// \return true if the message length was valid and it was correctly queued for transmit
1121  boolean send(const uint8_t* data, uint8_t len);
1122 
1123  /// Blocks until the RF22 is not in mode RF22_MODE_TX (ie until the RF22 is not transmitting).
1124  /// This effectively waits until any previous transmit packet is finished being transmitted.
1125  void waitPacketSent();
1126 
1127  /// Blocks until the RF22 is not in mode RF22_MODE_TX (ie until the RF22 is not transmitting)
1128  /// or until the timeout occuers, whichever happens first
1129  /// \param[in] timeout Maximum time to wait in milliseconds.
1130  /// \return true if the RF22 is not transmitting any more
1131  bool waitPacketSent(uint16_t timeout);
1132 
1133  /// Tells the receiver to accept messages with any TO address, not just messages
1134  /// addressed to this node or the broadcast address
1135  /// \param[in] promiscuous true if you wish to receive messages with any TO address
1136  void setPromiscuous(boolean promiscuous);
1137 
1138  /// Returns the TO header of the last received message
1139  /// \return The TO header
1140  uint8_t headerTo();
1141 
1142  /// Returns the FROM header of the last received message
1143  /// \return The FROM header
1144  uint8_t headerFrom();
1145 
1146  /// Returns the ID header of the last received message
1147  /// \return The ID header
1148  uint8_t headerId();
1149 
1150  /// Returns the FLAGS header of the last received message
1151  /// \return The FLAGS header
1152  uint8_t headerFlags();
1153 
1154  /// Returns the RSSI (Receiver Signal Strength Indicator)
1155  /// of the last received message. This measurement is taken when
1156  /// the preamble has been received. It is a (non-linear) measure of the received signal strength.
1157  /// \return The RSSI
1158  uint8_t lastRssi();
1159 
1160  /// Prints a data buffer in HEX.
1161  /// For diagnostic use
1162  /// \param[in] prompt string to preface the print
1163  /// \param[in] buf Location of the buffer to print
1164  /// \param[in] len Length of the buffer in octets.
1165  static void printBuffer(const char* prompt, const uint8_t* buf, uint8_t len);
1166 
1167  /// Sets the length of the preamble
1168  /// in 4-bit nibbles.
1169  /// Caution: this should be set to the same
1170  /// value on all nodes in your network. Default is 8.
1171  /// Sets the message preamble length in RF22_REG_34_PREAMBLE_LENGTH
1172  /// \param[in] nibbles Preamble length in nibbles of 4 bits each.
1173  void setPreambleLength(uint8_t nibbles);
1174 
1175  /// Sets the sync words for transmit and receive in registers RF22_REG_36_SYNC_WORD3
1176  /// to RF22_REG_39_SYNC_WORD0
1177  /// Caution: SyncWords should be set to the same
1178  /// value on all nodes in your network. Nodes with different SyncWords set will never receive
1179  /// each others messages, so different SyncWords can be used to isolate different
1180  /// networks from each other. Default is { 0x2d, 0xd4 }.
1181  /// \param[in] syncWords Array of sync words, 1 to 4 octets long
1182  /// \param[in] len Number of sync words to set, 1 to 4.
1183  void setSyncWords(const uint8_t* syncWords, uint8_t len);
1184 
1185  /// Sets the CRC polynomial top be used to generare the CRC for both receive and transmit
1186  /// Must be called before init(), otherwise the default of CRC_16_IBM will be used.
1187  /// \param[in] polynomial One of RF22::CRCPolynomial choices CRC_*
1188  /// \return true if polynomial is a valid option for this radio.
1189  boolean setCRCPolynomial(CRCPolynomial polynomial);
1190 
1191 protected:
1192  /// This is a low level function to handle the interrupts for one instance of RF22.
1193  /// Called automatically by isr0() and isr1()
1194  /// Should not need to be called.
1195  void handleInterrupt();
1196 
1197  /// Clears the receiver buffer.
1198  /// Internal use only
1199  void clearRxBuf();
1200 
1201  /// Clears the transmitter buffer
1202  /// Internal use only
1203  void clearTxBuf();
1204 
1205  /// Fills the transmitter buffer with the data of a mesage to be sent
1206  /// \param[in] data Array of data bytes to be sent (1 to 255)
1207  /// \param[in] len Number of data bytes in data (> 0)
1208  /// \return true if the message length is valid
1209  boolean fillTxBuf(const uint8_t* data, uint8_t len);
1210 
1211  /// Appends the transmitter buffer with the data of a mesage to be sent
1212  /// \param[in] data Array of data bytes to be sent (0 to 255)
1213  /// \param[in] len Number of data bytes in data
1214  /// \return false if the resulting message would exceed RF22_MAX_MESSAGE_LEN, else true
1215  boolean appendTxBuf(const uint8_t* data, uint8_t len);
1216 
1217  /// Internal function to load the next fragment of
1218  /// the current message into the transmitter FIFO
1219  /// Internal use only
1220  void sendNextFragment();
1221 
1222  /// function to copy the next fragment from
1223  /// the receiver FIF) into the receiver buffer
1224  void readNextFragment();
1225 
1226  /// Clears the RF22 Rx and Tx FIFOs
1227  /// Internal use only
1228  void resetFifos();
1229 
1230  /// Clears the RF22 Rx FIFO
1231  /// Internal use only
1232  void resetRxFifo();
1233 
1234  /// Clears the RF22 Tx FIFO
1235  /// Internal use only
1236  void resetTxFifo();
1237 
1238  /// This function will be called by handleInterrupt() if an RF22 external interrupt occurs.
1239  /// This can only happen if external interrupts are enabled in the RF22
1240  /// (which they are not by default).
1241  /// Subclasses may override this function to get control when an RF22 external interrupt occurs.
1242  virtual void handleExternalInterrupt();
1243 
1244  /// This function will be called by handleInterrupt() if an RF22 wakeup timer interrupt occurs.
1245  /// This can only happen if wakeup timer interrupts are enabled in the RF22
1246  /// (which they are not by default).
1247  /// Subclasses may override this function to get control when an RF22 wakeup timer interrupt occurs.
1248  virtual void handleWakeupTimerInterrupt();
1249 
1250  /// Sets the TO header to be sent in all subsequent messages
1251  /// \param[in] to The new TO header value
1252  void setHeaderTo(uint8_t to);
1253 
1254  /// Sets the FROM header to be sent in all subsequent messages
1255  /// \param[in] from The new FROM header value
1256  void setHeaderFrom(uint8_t from);
1257 
1258  /// Sets the ID header to be sent in all subsequent messages
1259  /// \param[in] id The new ID header value
1260  void setHeaderId(uint8_t id);
1261  /// Sets the FLAGS header to be sent in all subsequent messages
1262  /// \param[in] flags The new FLAGS header value
1263  void setHeaderFlags(uint8_t flags);
1264 
1265  /// Start the transmission of the contents
1266  /// of the Tx buffer
1267  void startTransmit();
1268 
1269  /// ReStart the transmission of the contents
1270  /// of the Tx buffer after a atransmission failure
1271  void restartTransmit();
1272 
1273 protected:
1274  GenericSPIClass* _spi;
1275 
1276  /// Low level interrupt service routine for RF22 connected to interrupt 0
1277  static void isr0();
1278 
1279  /// Low level interrupt service routine for RF22 connected to interrupt 1
1280  static void isr1();
1281 
1282  /// Low level interrupt service routine for RF22 connected to interrupt 1
1283  static void isr2();
1284 
1285  /// Array of instances connected to interrupts 0 and 1
1287 
1288  volatile uint8_t _mode; // One of RF22_MODE_*
1289 
1290  uint8_t _idleMode; // The radio mode to use when mode is RF22_MODE_IDLE
1291  uint8_t _slaveSelectPin;
1292  uint8_t _interrupt;
1293  uint8_t _deviceType;
1294 
1295  // Message confiuration options
1296  CRCPolynomial _polynomial;
1297 
1298  // These volatile members may get changed in the interrupt service routine
1299  volatile uint8_t _bufLen;
1300  uint8_t _buf[RF22_MAX_MESSAGE_LEN];
1301 
1302  volatile boolean _rxBufValid;
1303 
1304  volatile uint8_t _txBufSentIndex;
1305 
1306  volatile uint16_t _rxBad;
1307  volatile uint16_t _rxGood;
1308  volatile uint16_t _txGood;
1309 
1310  volatile uint8_t _lastRssi;
1311 };
1312 
1313 /// @example rf22_client.pde
1314 /// Client side of simple client/server pair using RF22 class
1315 
1316 /// @example rf22_server.pde
1317 /// Server side of simple client/server pair using RF22 class
1318 
1319 /// @example rf22_datagram_client.pde
1320 /// Client side of simple client/server pair using RF22Datagram class
1321 
1322 /// @example rf22_datagram_server.pde
1323 /// Server side of simple client/server pair using RF22Datagram class
1324 
1325 /// @example rf22_reliable_datagram_client.pde
1326 /// Client side of simple client/server pair using RF22ReliableDatagram class
1327 
1328 /// @example rf22_reliable_datagram_server.pde
1329 /// Server side of simple client/server pair using RF22ReliableDatagram class
1330 
1331 /// @example rf22_router_client.pde
1332 /// Client side of RF22Router network chain
1333 
1334 /// @example rf22_router_server1.pde
1335 /// Server node for RF22Router network chain
1336 
1337 /// @example rf22_router_server2.pde
1338 /// Server node for RF22Router network chain
1339 
1340 /// @example rf22_router_server3.pde
1341 /// Server node for RF22Router network chain
1342 
1343 /// @example rf22_mesh_client.pde
1344 /// Client side of RF22Mesh network chain
1345 
1346 /// @example rf22_mesh_server1.pde
1347 /// Server node for RF22Mesh network chain
1348 
1349 /// @example rf22_mesh_server2.pde
1350 /// Server node for RF22Mesh network chain
1351 
1352 /// @example rf22_mesh_server3.pde
1353 /// Server node for RF22Mesh network chain
1354 
1355 /// @example rf22_test.pde
1356 /// Test suite for RF22 library
1357 
1358 /// @example rf22_snoop.pde
1359 /// Capture and print RF22 packet from the air
1360 
1361 /// @example rf22_specan.pde
1362 /// Simple spectrum analyser using the RSSI measurements of the RF22
1363 /// (see <a href="specan1.png">Sample output</a> showing a plot from 395.0MHz to 396.0MHz of a
1364 /// signal generator at 395.5MHz amplitude modulated at 100% 1kHz)
1365 ///
1366 
1367 /// @example IPGateway.pde
1368 /// Sketch to provide an IP gateway for a set of RF22 radios (Datagram, ReliableDatagram, Router or Mesh)
1369 /// Routes UDP messages from an internet connection using an Ethernet Shield and sends them
1370 /// to a radio whose ID is based on the UDP port. Replies are sent back to the originating UDP
1371 /// address and port
1372 
1373 /// @example rf22_serial_modem.ino
1374 /// Example sketch implements a bidirectional serial modem
1375 /// with the RF22ReliableDatagram class.
1376 /// It is designed to work with another instance of rf22_serial_modem.
1377 /// Pairs of arduino+radio running this program translate input Serial port data to
1378 /// radio and send it to the other side where the data is sent out on its serial port.
1379 /// So it acts like a transparent serial cable over radio.
1380 /// Pairs of radios share the same ADDRESS, and therefore you can have up to 256 such
1381 /// pairs sharing the same airspace.
1382 /// In the event of radio communications failure, it fails silently.
1383 
1384 /// @example rf22_client_softwarespi.ino
1385 /// Example sketch showing how to create a simple messageing client
1386 /// with the RF22 class using Software SPI instead of the
1387 /// usual Hardware SPI.
1388 
1389 /// @example rf22_server_softwarespi.ino
1390 /// Example sketch showing how to create a simple messageing server
1391 /// with the RF22 class. RF22 class does not provide for addressing or reliability.
1392 /// It is designed to work with the other example rf22_client
1393 
1394 /// @example SDRSharp_20130304_095231Z_433999kHz_AF.wav
1395 /// This is an audio .wav file of a typical transmission from an RF22, driven by the RF22 library.
1396 /// The RF22 was configured for the default: 434.0MHz, FSK_Rb2_4Fd36 (ie FM, 36kHz deviation, 2.4kbps)
1397 /// It was captured with a Funcube Pro+ dongle, using SDR# software. SDR# was configured
1398 /// for a centre frequency of 434.000MHZ, WFM mode with a filter bandwidth of 100kHz
1399 /// (wider than necessary to capture the 36+36 = 72kHz deviation of the signal)
1400 /// With a wav file viewer such as audacity, the modulation can clearly be seen, consisting of:
1401 /// - Preamble of 8 nibbles (16 cycles)
1402 /// - 2 Sync words 0x2d, 0xd4
1403 /// - 4 bytes TX header (all 0s, this was a broadcast)
1404 /// - 1 byte packet length
1405 /// - payload
1406 /// - 2 bytes CRC (IBM format)
1407 
1408 #endif
uint8_t reg_6f
Value for register RF22_REG_6F_TX_DATA_RATE0.
Definition: RF22.h:877
void clearRxBuf()
Definition: RF22.cpp:577
void handleInterrupt()
Definition: RF22.cpp:196
boolean setFHStepSize(uint8_t fhs)
Definition: RF22.cpp:469
FSK, No Manchester, Rb = 2.4kbs, Fd = 36kHz.
Definition: RF22.h:893
uint8_t headerTo()
Definition: RF22.cpp:799
void setHeaderTo(uint8_t to)
Definition: RF22.cpp:779
FSK, No Manchester, Rb = 4.8kbs, Fd = 45kHz.
Definition: RF22.h:894
CRCPolynomial
Defines the available choices for CRC Types of permitted CRC polynomials, to be passed to setCRCPolyn...
Definition: RF22.h:925
uint8_t statusRead()
Definition: RF22.cpp:381
uint8_t reg_70
Value for register RF22_REG_70_MODULATION_CONTROL1.
Definition: RF22.h:878
uint8_t reg_6e
Value for register RF22_REG_6E_TX_DATA_RATE1.
Definition: RF22.h:876
OOK, No Manchester, Rb = 9.6kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:915
boolean setFrequency(float centre, float afcPullInRange=0.05)
Definition: RF22.cpp:431
uint8_t temperatureRead(uint8_t tsrange=RF22_TSRANGE_M64_64C, uint8_t tvoffs=0)
Definition: RF22.cpp:403
void setHeaderFlags(uint8_t flags)
Definition: RF22.cpp:794
uint8_t reg_1f
Value for register RF22_REG_1F_CLOCK_RECOVERY_GEARSHIFT_OVERRIDE.
Definition: RF22.h:864
uint8_t lastRssi()
Definition: RF22.cpp:819
boolean fillTxBuf(const uint8_t *data, uint8_t len)
Definition: RF22.cpp:700
FSK, No Manchester, Rb = 2kbs, Fd = 5kHz, PN9 random modulation for testing.
Definition: RF22.h:890
GFSK, No Manchester, Rb = 38.4kbs, Fd = 19.6kHz.
Definition: RF22.h:908
Biacheva.
Definition: RF22.h:930
boolean recv(uint8_t *buf, uint8_t *len)
Definition: RF22.cpp:647
void sendNextFragment()
Definition: RF22.cpp:721
void setHeaderId(uint8_t id)
Definition: RF22.cpp:789
bool waitAvailableTimeout(uint16_t timeout)
Definition: RF22.cpp:602
uint8_t reg_20
Value for register RF22_REG_20_CLOCK_RECOVERY_OVERSAMPLING_RATE.
Definition: RF22.h:865
RF22(uint8_t slaveSelectPin=SS, uint8_t interrupt=0, GenericSPIClass *spi=&Hardware_spi)
Definition: RF22.cpp:69
uint8_t reg_72
Value for register RF22_REG_72_FREQUENCY_DEVIATION.
Definition: RF22.h:880
void setModemRegisters(const ModemConfig *config)
Definition: RF22.cpp:540
uint8_t reg_2e
Value for register RF22_REG_2E_SLICER_PEAK_HOLD.
Definition: RF22.h:873
uint8_t reg_58
Value for register RF22_REG_58_CHARGE_PUMP_CURRENT_TRIMMING.
Definition: RF22.h:874
void setWutPeriod(uint16_t wtm, uint8_t wtr=0, uint8_t wtd=0)
Definition: RF22.cpp:418
boolean send(const uint8_t *data, uint8_t len)
Definition: RF22.cpp:686
GFSK, No Manchester, Rb = 2kbs, Fd = 5kHz.
Definition: RF22.h:903
OOK, No Manchester, Rb = 38.4kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:917
uint8_t reg_71
Value for register RF22_REG_71_MODULATION_CONTROL2.
Definition: RF22.h:879
void setPromiscuous(boolean promiscuous)
Definition: RF22.cpp:824
boolean setFHChannel(uint8_t fhch)
Definition: RF22.cpp:477
void setSyncWords(const uint8_t *syncWords, uint8_t len)
Definition: RF22.cpp:572
void setPreambleLength(uint8_t nibbles)
Definition: RF22.cpp:566
CCITT.
Definition: RF22.h:927
void reset()
Definition: RF22.cpp:329
Unmodulated carrier for testing.
Definition: RF22.h:889
void resetTxFifo()
Definition: RF22.cpp:763
void setMode(uint8_t mode)
Definition: RF22.cpp:493
void clearTxBuf()
Definition: RF22.cpp:662
GFSK, No Manchester, Rb = 4.8kbs, Fd = 45kHz.
Definition: RF22.h:905
boolean init()
Definition: RF22.cpp:82
void spiWrite(uint8_t reg, uint8_t val)
Definition: RF22.cpp:349
uint8_t reg_2d
Value for register RF22_REG_2D_OOK_COUNTER_VALUE_2.
Definition: RF22.h:872
OOK, No Manchester, Rb = 1.2kbs, Rx Bandwidth = 75kHz.
Definition: RF22.h:912
void waitAvailable()
Definition: RF22.cpp:593
boolean appendTxBuf(const uint8_t *data, uint8_t len)
Definition: RF22.cpp:708
Base class for SPI interfaces.
Definition: GenericSPI.h:28
boolean available()
Definition: RF22.cpp:585
uint8_t reg_23
Value for register RF22_REG_23_CLOCK_RECOVERY_OFFSET0.
Definition: RF22.h:868
void setTxPower(uint8_t power)
Definition: RF22.cpp:534
void restartTransmit()
Definition: RF22.cpp:678
IEC-16.
Definition: RF22.h:929
uint8_t reg_24
Value for register RF22_REG_24_CLOCK_RECOVERY_TIMING_LOOP_GAIN1.
Definition: RF22.h:869
GFSK, No Manchester, Rb = 125kbs, Fd = 125kHz.
Definition: RF22.h:910
uint8_t reg_2c
Value for register RF22_REG_2C_OOK_COUNTER_VALUE_1.
Definition: RF22.h:871
FSK, No Manchester, Rb = 38.4kbs, Fd = 19.6kHz.
Definition: RF22.h:897
OOK, No Manchester, Rb = 19.2kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:916
OOK, No Manchester, Rb = 40kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:918
void resetRxFifo()
Definition: RF22.cpp:756
void setModeTx()
Definition: RF22.cpp:516
uint8_t ezmacStatusRead()
Definition: RF22.cpp:488
static void isr0()
Low level interrupt service routine for RF22 connected to interrupt 0.
Definition: RF22.cpp:313
void waitPacketSent()
Definition: RF22.cpp:611
GFSK, No Manchester, Rb = 2.4kbs, Fd = 36kHz.
Definition: RF22.h:904
FSK, No Manchester, Rb = 57.6kbs, Fd = 28.8kHz.
Definition: RF22.h:898
virtual void handleWakeupTimerInterrupt()
Definition: RF22.cpp:775
uint8_t rssiRead()
Definition: RF22.cpp:483
uint8_t headerFrom()
Definition: RF22.cpp:804
uint8_t reg_1c
Value for register RF22_REG_1C_IF_FILTER_BANDWIDTH.
Definition: RF22.h:863
CRC-16 (IBM) The default used by RF22 library.
Definition: RF22.h:928
GFSK, No Manchester, Rb = 19.2kbs, Fd = 9.6kHz.
Definition: RF22.h:907
OOK, No Manchester, Rb = 4.8kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:914
uint8_t reg_69
Value for register RF22_REG_69_AGC_OVERRIDE1.
Definition: RF22.h:875
FSK, No Manchester, Rb = 512bs, Fd = 4.5kHz, for POCSAG compatibility.
Definition: RF22.h:901
void spiBurstRead(uint8_t reg, uint8_t *dest, uint8_t len)
Definition: RF22.cpp:359
void resetFifos()
Definition: RF22.cpp:749
void setModeRx()
Definition: RF22.cpp:507
boolean setModemConfig(ModemConfigChoice index)
Definition: RF22.cpp:553
void startTransmit()
Definition: RF22.cpp:670
static void isr1()
Low level interrupt service routine for RF22 connected to interrupt 1.
Definition: RF22.cpp:318
OOK, No Manchester, Rb = 2.4kbs, Rx Bandwidth = 335kHz.
Definition: RF22.h:913
Send and receive unaddressed, unreliable datagrams.
Definition: RF22.h:848
Defines register values for a set of modem configuration registers.
Definition: RF22.h:861
uint8_t mode()
Definition: RF22.cpp:529
FSK, No Manchester, Rb = 512bs, Fd = 2.5kHz, for POCSAG compatibility.
Definition: RF22.h:900
uint8_t reg_22
Value for register RF22_REG_22_CLOCK_RECOVERY_OFFSET1.
Definition: RF22.h:867
FSK, No Manchester, Rb = 125kbs, Fd = 125kHz.
Definition: RF22.h:899
uint8_t spiRead(uint8_t reg)
Definition: RF22.cpp:336
FSK, No Manchester, Rb = 2kbs, Fd = 5kHz.
Definition: RF22.h:892
uint8_t headerId()
Definition: RF22.cpp:809
static RF22 * _RF22ForInterrupt[]
Array of instances connected to interrupts 0 and 1.
Definition: RF22.h:1286
virtual void handleExternalInterrupt()
Definition: RF22.cpp:770
FSK, No Manchester, Rb = 19.2kbs, Fd = 9.6kHz.
Definition: RF22.h:896
uint8_t reg_21
Value for register RF22_REG_21_CLOCK_RECOVERY_OFFSET2.
Definition: RF22.h:866
uint8_t reg_25
Value for register RF22_REG_25_CLOCK_RECOVERY_TIMING_LOOP_GAIN0.
Definition: RF22.h:870
GFSK, No Manchester, Rb = 9.6kbs, Fd = 45kHz.
Definition: RF22.h:906
static void isr2()
Low level interrupt service routine for RF22 connected to interrupt 1.
Definition: RF22.cpp:323
void setModeIdle()
Definition: RF22.cpp:498
boolean setCRCPolynomial(CRCPolynomial polynomial)
Definition: RF22.cpp:829
ModemConfigChoice
Definition: RF22.h:887
GFSK, No Manchester, Rb = 57.6kbs, Fd = 28.8kHz.
Definition: RF22.h:909
uint16_t wutRead()
Definition: RF22.cpp:410
uint8_t headerFlags()
Definition: RF22.cpp:814
uint8_t adcRead(uint8_t adcsel=RF22_ADCSEL_INTERNAL_TEMPERATURE_SENSOR, uint8_t adcref=RF22_ADCREF_BANDGAP_VOLTAGE, uint8_t adcgain=0, uint8_t adcoffs=0)
Definition: RF22.cpp:386
void spiBurstWrite(uint8_t reg, const uint8_t *src, uint8_t len)
Definition: RF22.cpp:370
void setHeaderFrom(uint8_t from)
Definition: RF22.cpp:784
void readNextFragment()
Definition: RF22.cpp:738
FSK, No Manchester, Rb = 9.6kbs, Fd = 45kHz.
Definition: RF22.h:895
static void printBuffer(const char *prompt, const uint8_t *buf, uint8_t len)
Definition: RF22.cpp:627