RadioHead
RH_RF95.h
1 // RH_RF95.h
2 //
3 // Definitions for HopeRF LoRa radios per:
4 // http://www.hoperf.com/upload/rf/RFM95_96_97_98W.pdf
5 // http://www.hoperf.cn/upload/rfchip/RF96_97_98.pdf
6 //
7 // Author: Mike McCauley (mikem@airspayce.com)
8 // Copyright (C) 2014 Mike McCauley
9 // $Id: RH_RF95.h,v 1.21 2017/11/06 00:04:08 mikem Exp mikem $
10 //
11 
12 #ifndef RH_RF95_h
13 #define RH_RF95_h
14 
15 #include <RHSPIDriver.h>
16 
17 // This is the maximum number of interrupts the driver can support
18 // Most Arduinos can handle 2, Megas can handle more
19 #define RH_RF95_NUM_INTERRUPTS 3
20 
21 // Max number of octets the LORA Rx/Tx FIFO can hold
22 #define RH_RF95_FIFO_SIZE 255
23 
24 // This is the maximum number of bytes that can be carried by the LORA.
25 // We use some for headers, keeping fewer for RadioHead messages
26 #define RH_RF95_MAX_PAYLOAD_LEN RH_RF95_FIFO_SIZE
27 
28 // The length of the headers we add.
29 // The headers are inside the LORA's payload
30 #define RH_RF95_HEADER_LEN 4
31 
32 // This is the maximum message length that can be supported by this driver.
33 // Can be pre-defined to a smaller size (to save SRAM) prior to including this header
34 // Here we allow for 1 byte message length, 4 bytes headers, user data and 2 bytes of FCS
35 #ifndef RH_RF95_MAX_MESSAGE_LEN
36  #define RH_RF95_MAX_MESSAGE_LEN (RH_RF95_MAX_PAYLOAD_LEN - RH_RF95_HEADER_LEN)
37 #endif
38 
39 // The crystal oscillator frequency of the module
40 #define RH_RF95_FXOSC 32000000.0
41 
42 // The Frequency Synthesizer step = RH_RF95_FXOSC / 2^^19
43 #define RH_RF95_FSTEP (RH_RF95_FXOSC / 524288)
44 
45 
46 // Register names (LoRa Mode, from table 85)
47 #define RH_RF95_REG_00_FIFO 0x00
48 #define RH_RF95_REG_01_OP_MODE 0x01
49 #define RH_RF95_REG_02_RESERVED 0x02
50 #define RH_RF95_REG_03_RESERVED 0x03
51 #define RH_RF95_REG_04_RESERVED 0x04
52 #define RH_RF95_REG_05_RESERVED 0x05
53 #define RH_RF95_REG_06_FRF_MSB 0x06
54 #define RH_RF95_REG_07_FRF_MID 0x07
55 #define RH_RF95_REG_08_FRF_LSB 0x08
56 #define RH_RF95_REG_09_PA_CONFIG 0x09
57 #define RH_RF95_REG_0A_PA_RAMP 0x0a
58 #define RH_RF95_REG_0B_OCP 0x0b
59 #define RH_RF95_REG_0C_LNA 0x0c
60 #define RH_RF95_REG_0D_FIFO_ADDR_PTR 0x0d
61 #define RH_RF95_REG_0E_FIFO_TX_BASE_ADDR 0x0e
62 #define RH_RF95_REG_0F_FIFO_RX_BASE_ADDR 0x0f
63 #define RH_RF95_REG_10_FIFO_RX_CURRENT_ADDR 0x10
64 #define RH_RF95_REG_11_IRQ_FLAGS_MASK 0x11
65 #define RH_RF95_REG_12_IRQ_FLAGS 0x12
66 #define RH_RF95_REG_13_RX_NB_BYTES 0x13
67 #define RH_RF95_REG_14_RX_HEADER_CNT_VALUE_MSB 0x14
68 #define RH_RF95_REG_15_RX_HEADER_CNT_VALUE_LSB 0x15
69 #define RH_RF95_REG_16_RX_PACKET_CNT_VALUE_MSB 0x16
70 #define RH_RF95_REG_17_RX_PACKET_CNT_VALUE_LSB 0x17
71 #define RH_RF95_REG_18_MODEM_STAT 0x18
72 #define RH_RF95_REG_19_PKT_SNR_VALUE 0x19
73 #define RH_RF95_REG_1A_PKT_RSSI_VALUE 0x1a
74 #define RH_RF95_REG_1B_RSSI_VALUE 0x1b
75 #define RH_RF95_REG_1C_HOP_CHANNEL 0x1c
76 #define RH_RF95_REG_1D_MODEM_CONFIG1 0x1d
77 #define RH_RF95_REG_1E_MODEM_CONFIG2 0x1e
78 #define RH_RF95_REG_1F_SYMB_TIMEOUT_LSB 0x1f
79 #define RH_RF95_REG_20_PREAMBLE_MSB 0x20
80 #define RH_RF95_REG_21_PREAMBLE_LSB 0x21
81 #define RH_RF95_REG_22_PAYLOAD_LENGTH 0x22
82 #define RH_RF95_REG_23_MAX_PAYLOAD_LENGTH 0x23
83 #define RH_RF95_REG_24_HOP_PERIOD 0x24
84 #define RH_RF95_REG_25_FIFO_RX_BYTE_ADDR 0x25
85 #define RH_RF95_REG_26_MODEM_CONFIG3 0x26
86 
87 #define RH_RF95_REG_27_PPM_CORRECTION 0x27
88 #define RH_RF95_REG_28_FEI_MSB 0x28
89 #define RH_RF95_REG_29_FEI_MID 0x29
90 #define RH_RF95_REG_2A_FEI_LSB 0x2a
91 #define RH_RF95_REG_2C_RSSI_WIDEBAND 0x2c
92 #define RH_RF95_REG_31_DETECT_OPTIMIZ 0x31
93 #define RH_RF95_REG_33_INVERT_IQ 0x33
94 #define RH_RF95_REG_37_DETECTION_THRESHOLD 0x37
95 #define RH_RF95_REG_39_SYNC_WORD 0x39
96 
97 #define RH_RF95_REG_40_DIO_MAPPING1 0x40
98 #define RH_RF95_REG_41_DIO_MAPPING2 0x41
99 #define RH_RF95_REG_42_VERSION 0x42
100 
101 #define RH_RF95_REG_4B_TCXO 0x4b
102 #define RH_RF95_REG_4D_PA_DAC 0x4d
103 #define RH_RF95_REG_5B_FORMER_TEMP 0x5b
104 #define RH_RF95_REG_61_AGC_REF 0x61
105 #define RH_RF95_REG_62_AGC_THRESH1 0x62
106 #define RH_RF95_REG_63_AGC_THRESH2 0x63
107 #define RH_RF95_REG_64_AGC_THRESH3 0x64
108 
109 // RH_RF95_REG_01_OP_MODE 0x01
110 #define RH_RF95_LONG_RANGE_MODE 0x80
111 #define RH_RF95_ACCESS_SHARED_REG 0x40
112 #define RH_RF95_LOW_FREQUENCY_MODE 0x08
113 #define RH_RF95_MODE 0x07
114 #define RH_RF95_MODE_SLEEP 0x00
115 #define RH_RF95_MODE_STDBY 0x01
116 #define RH_RF95_MODE_FSTX 0x02
117 #define RH_RF95_MODE_TX 0x03
118 #define RH_RF95_MODE_FSRX 0x04
119 #define RH_RF95_MODE_RXCONTINUOUS 0x05
120 #define RH_RF95_MODE_RXSINGLE 0x06
121 #define RH_RF95_MODE_CAD 0x07
122 
123 // RH_RF95_REG_09_PA_CONFIG 0x09
124 #define RH_RF95_PA_SELECT 0x80
125 #define RH_RF95_MAX_POWER 0x70
126 #define RH_RF95_OUTPUT_POWER 0x0f
127 
128 // RH_RF95_REG_0A_PA_RAMP 0x0a
129 #define RH_RF95_LOW_PN_TX_PLL_OFF 0x10
130 #define RH_RF95_PA_RAMP 0x0f
131 #define RH_RF95_PA_RAMP_3_4MS 0x00
132 #define RH_RF95_PA_RAMP_2MS 0x01
133 #define RH_RF95_PA_RAMP_1MS 0x02
134 #define RH_RF95_PA_RAMP_500US 0x03
135 #define RH_RF95_PA_RAMP_250US 0x0
136 #define RH_RF95_PA_RAMP_125US 0x05
137 #define RH_RF95_PA_RAMP_100US 0x06
138 #define RH_RF95_PA_RAMP_62US 0x07
139 #define RH_RF95_PA_RAMP_50US 0x08
140 #define RH_RF95_PA_RAMP_40US 0x09
141 #define RH_RF95_PA_RAMP_31US 0x0a
142 #define RH_RF95_PA_RAMP_25US 0x0b
143 #define RH_RF95_PA_RAMP_20US 0x0c
144 #define RH_RF95_PA_RAMP_15US 0x0d
145 #define RH_RF95_PA_RAMP_12US 0x0e
146 #define RH_RF95_PA_RAMP_10US 0x0f
147 
148 // RH_RF95_REG_0B_OCP 0x0b
149 #define RH_RF95_OCP_ON 0x20
150 #define RH_RF95_OCP_TRIM 0x1f
151 
152 // RH_RF95_REG_0C_LNA 0x0c
153 #define RH_RF95_LNA_GAIN 0xe0
154 #define RH_RF95_LNA_GAIN_G1 0x20
155 #define RH_RF95_LNA_GAIN_G2 0x40
156 #define RH_RF95_LNA_GAIN_G3 0x60
157 #define RH_RF95_LNA_GAIN_G4 0x80
158 #define RH_RF95_LNA_GAIN_G5 0xa0
159 #define RH_RF95_LNA_GAIN_G6 0xc0
160 #define RH_RF95_LNA_BOOST_LF 0x18
161 #define RH_RF95_LNA_BOOST_LF_DEFAULT 0x00
162 #define RH_RF95_LNA_BOOST_HF 0x03
163 #define RH_RF95_LNA_BOOST_HF_DEFAULT 0x00
164 #define RH_RF95_LNA_BOOST_HF_150PC 0x11
165 
166 // RH_RF95_REG_11_IRQ_FLAGS_MASK 0x11
167 #define RH_RF95_RX_TIMEOUT_MASK 0x80
168 #define RH_RF95_RX_DONE_MASK 0x40
169 #define RH_RF95_PAYLOAD_CRC_ERROR_MASK 0x20
170 #define RH_RF95_VALID_HEADER_MASK 0x10
171 #define RH_RF95_TX_DONE_MASK 0x08
172 #define RH_RF95_CAD_DONE_MASK 0x04
173 #define RH_RF95_FHSS_CHANGE_CHANNEL_MASK 0x02
174 #define RH_RF95_CAD_DETECTED_MASK 0x01
175 
176 // RH_RF95_REG_12_IRQ_FLAGS 0x12
177 #define RH_RF95_RX_TIMEOUT 0x80
178 #define RH_RF95_RX_DONE 0x40
179 #define RH_RF95_PAYLOAD_CRC_ERROR 0x20
180 #define RH_RF95_VALID_HEADER 0x10
181 #define RH_RF95_TX_DONE 0x08
182 #define RH_RF95_CAD_DONE 0x04
183 #define RH_RF95_FHSS_CHANGE_CHANNEL 0x02
184 #define RH_RF95_CAD_DETECTED 0x01
185 
186 // RH_RF95_REG_18_MODEM_STAT 0x18
187 #define RH_RF95_RX_CODING_RATE 0xe0
188 #define RH_RF95_MODEM_STATUS_CLEAR 0x10
189 #define RH_RF95_MODEM_STATUS_HEADER_INFO_VALID 0x08
190 #define RH_RF95_MODEM_STATUS_RX_ONGOING 0x04
191 #define RH_RF95_MODEM_STATUS_SIGNAL_SYNCHRONIZED 0x02
192 #define RH_RF95_MODEM_STATUS_SIGNAL_DETECTED 0x01
193 
194 // RH_RF95_REG_1C_HOP_CHANNEL 0x1c
195 #define RH_RF95_PLL_TIMEOUT 0x80
196 #define RH_RF95_RX_PAYLOAD_CRC_IS_ON 0x40
197 #define RH_RF95_FHSS_PRESENT_CHANNEL 0x3f
198 
199 // RH_RF95_REG_1D_MODEM_CONFIG1 0x1d
200 #define RH_RF95_BW 0xf0
201 
202 #define RH_RF95_BW_7_8KHZ 0x00
203 #define RH_RF95_BW_10_4KHZ 0x10
204 #define RH_RF95_BW_15_6KHZ 0x20
205 #define RH_RF95_BW_20_8KHZ 0x30
206 #define RH_RF95_BW_31_25KHZ 0x40
207 #define RH_RF95_BW_41_7KHZ 0x50
208 #define RH_RF95_BW_62_5KHZ 0x60
209 #define RH_RF95_BW_125KHZ 0x70
210 #define RH_RF95_BW_250KHZ 0x80
211 #define RH_RF95_BW_500KHZ 0x90
212 #define RH_RF95_CODING_RATE 0x0e
213 #define RH_RF95_CODING_RATE_4_5 0x02
214 #define RH_RF95_CODING_RATE_4_6 0x04
215 #define RH_RF95_CODING_RATE_4_7 0x06
216 #define RH_RF95_CODING_RATE_4_8 0x08
217 #define RH_RF95_IMPLICIT_HEADER_MODE_ON 0x01
218 
219 // RH_RF95_REG_1E_MODEM_CONFIG2 0x1e
220 #define RH_RF95_SPREADING_FACTOR 0xf0
221 #define RH_RF95_SPREADING_FACTOR_64CPS 0x60
222 #define RH_RF95_SPREADING_FACTOR_128CPS 0x70
223 #define RH_RF95_SPREADING_FACTOR_256CPS 0x80
224 #define RH_RF95_SPREADING_FACTOR_512CPS 0x90
225 #define RH_RF95_SPREADING_FACTOR_1024CPS 0xa0
226 #define RH_RF95_SPREADING_FACTOR_2048CPS 0xb0
227 #define RH_RF95_SPREADING_FACTOR_4096CPS 0xc0
228 #define RH_RF95_TX_CONTINUOUS_MOE 0x08
229 
230 #define RH_RF95_PAYLOAD_CRC_ON 0x04
231 #define RH_RF95_SYM_TIMEOUT_MSB 0x03
232 
233 // RH_RF95_REG_4B_TCXO 0x4b
234 #define RH_RF95_TCXO_TCXO_INPUT_ON 0x10
235 
236 // RH_RF95_REG_4D_PA_DAC 0x4d
237 #define RH_RF95_PA_DAC_DISABLE 0x04
238 #define RH_RF95_PA_DAC_ENABLE 0x07
239 
240 /////////////////////////////////////////////////////////////////////
241 /// \class RH_RF95 RH_RF95.h <RH_RF95.h>
242 /// \brief Driver to send and receive unaddressed, unreliable datagrams via a LoRa
243 /// capable radio transceiver.
244 ///
245 /// For Semtech SX1276/77/78/79 and HopeRF RF95/96/97/98 and other similar LoRa capable radios.
246 /// Based on http://www.hoperf.com/upload/rf/RFM95_96_97_98W.pdf
247 /// and http://www.hoperf.cn/upload/rfchip/RF96_97_98.pdf
248 /// and http://www.semtech.com/images/datasheet/LoraDesignGuide_STD.pdf
249 /// and http://www.semtech.com/images/datasheet/sx1276.pdf
250 /// and http://www.semtech.com/images/datasheet/sx1276_77_78_79.pdf
251 /// FSK/GFSK/OOK modes are not (yet) supported.
252 ///
253 /// Works with
254 /// - the excellent MiniWirelessLoRa from Anarduino http://www.anarduino.com/miniwireless
255 /// - The excellent Modtronix inAir4 http://modtronix.com/inair4.html
256 /// and inAir9 modules http://modtronix.com/inair9.html.
257 /// - the excellent Rocket Scream Mini Ultra Pro with the RFM95W
258 /// http://www.rocketscream.com/blog/product/mini-ultra-pro-with-radio/
259 /// - Lora1276 module from NiceRF http://www.nicerf.com/product_view.aspx?id=99
260 /// - Adafruit Feather M0 with RFM95
261 /// - The very fine Talk2 Whisper Node LoRa boards https://wisen.com.au/store/products/whisper-node-lora
262 /// an Arduino compatible board, which include an on-board RFM95/96 LoRa Radio (Semtech SX1276), external antenna,
263 /// run on 2xAAA batteries and support low power operations. RF95 examples work without modification.
264 /// Use Arduino Board Manager to install the Talk2 code support. Upload the code with an FTDI adapter set to 5V.
265 /// - heltec / TTGO ESP32 LoRa OLED https://www.aliexpress.com/item/Internet-Development-Board-SX1278-ESP32-WIFI-chip-0-96-inch-OLED-Bluetooth-WIFI-Lora-Kit-32/32824535649.html
266 ///
267 /// \par Overview
268 ///
269 /// This class provides basic functions for sending and receiving unaddressed,
270 /// unreliable datagrams of arbitrary length to 251 octets per packet.
271 ///
272 /// Manager classes may use this class to implement reliable, addressed datagrams and streams,
273 /// mesh routers, repeaters, translators etc.
274 ///
275 /// Naturally, for any 2 radios to communicate that must be configured to use the same frequency and
276 /// modulation scheme.
277 ///
278 /// This Driver provides an object-oriented interface for sending and receiving data messages with Hope-RF
279 /// RFM95/96/97/98(W), Semtech SX1276/77/78/79 and compatible radio modules in LoRa mode.
280 ///
281 /// The Hope-RF (http://www.hoperf.com) RFM95/96/97/98(W) and Semtech SX1276/77/78/79 is a low-cost ISM transceiver
282 /// chip. It supports FSK, GFSK, OOK over a wide range of frequencies and
283 /// programmable data rates, and it also supports the proprietary LoRA (Long Range) mode, which
284 /// is the only mode supported in this RadioHead driver.
285 ///
286 /// This Driver provides functions for sending and receiving messages of up
287 /// to 251 octets on any frequency supported by the radio, in a range of
288 /// predefined Bandwidths, Spreading Factors and Coding Rates. Frequency can be set with
289 /// 61Hz precision to any frequency from 240.0MHz to 960.0MHz. Caution: most modules only support a more limited
290 /// range of frequencies due to antenna tuning.
291 ///
292 /// Up to 2 modules can be connected to an Arduino (3 on a Mega),
293 /// permitting the construction of translators and frequency changers, etc.
294 ///
295 /// Support for other features such as transmitter power control etc is
296 /// also provided.
297 ///
298 /// Tested on MinWirelessLoRa with arduino-1.0.5
299 /// on OpenSuSE 13.1.
300 /// Also tested with Teensy3.1, Modtronix inAir4 and Arduino 1.6.5 on OpenSuSE 13.1
301 ///
302 /// \par Packet Format
303 ///
304 /// All messages sent and received by this RH_RF95 Driver conform to this packet format:
305 ///
306 /// - LoRa mode:
307 /// - 8 symbol PREAMBLE
308 /// - Explicit header with header CRC (handled internally by the radio)
309 /// - 4 octets HEADER: (TO, FROM, ID, FLAGS)
310 /// - 0 to 251 octets DATA
311 /// - CRC (handled internally by the radio)
312 ///
313 /// \par Connecting RFM95/96/97/98 and Semtech SX1276/77/78/79 to Arduino
314 ///
315 /// We tested with Anarduino MiniWirelessLoRA, which is an Arduino Duemilanove compatible with a RFM96W
316 /// module on-board. Therefore it needs no connections other than the USB
317 /// programming connection and an antenna to make it work.
318 ///
319 /// If you have a bare RFM95/96/97/98 that you want to connect to an Arduino, you
320 /// might use these connections (untested): CAUTION: you must use a 3.3V type
321 /// Arduino, otherwise you will also need voltage level shifters between the
322 /// Arduino and the RFM95. CAUTION, you must also ensure you connect an
323 /// antenna.
324 ///
325 /// \code
326 /// Arduino RFM95/96/97/98
327 /// GND----------GND (ground in)
328 /// 3V3----------3.3V (3.3V in)
329 /// interrupt 0 pin D2-----------DIO0 (interrupt request out)
330 /// SS pin D10----------NSS (CS chip select in)
331 /// SCK pin D13----------SCK (SPI clock in)
332 /// MOSI pin D11----------MOSI (SPI Data in)
333 /// MISO pin D12----------MISO (SPI Data out)
334 /// \endcode
335 /// With these connections, you can then use the default constructor RH_RF95().
336 /// You can override the default settings for the SS pin and the interrupt in
337 /// the RH_RF95 constructor if you wish to connect the slave select SS to other
338 /// than the normal one for your Arduino (D10 for Diecimila, Uno etc and D53
339 /// for Mega) or the interrupt request to other than pin D2 (Caution,
340 /// different processors have different constraints as to the pins available
341 /// for interrupts).
342 ///
343 /// You can connect a Modtronix inAir4 or inAir9 directly to a 3.3V part such as a Teensy 3.1 like
344 /// this (tested).
345 /// \code
346 /// Teensy inAir4 inAir9
347 /// GND----------0V (ground in)
348 /// 3V3----------3.3V (3.3V in)
349 /// interrupt 0 pin D2-----------D0 (interrupt request out)
350 /// SS pin D10----------CS (CS chip select in)
351 /// SCK pin D13----------CK (SPI clock in)
352 /// MOSI pin D11----------SI (SPI Data in)
353 /// MISO pin D12----------SO (SPI Data out)
354 /// \endcode
355 /// With these connections, you can then use the default constructor RH_RF95().
356 /// you must also set the transmitter power with useRFO:
357 /// driver.setTxPower(13, true);
358 ///
359 /// Note that if you are using Modtronix inAir4 or inAir9,or any other module which uses the
360 /// transmitter RFO pins and not the PA_BOOST pins
361 /// that you must configure the power transmitter power for -1 to 14 dBm and with useRFO true.
362 /// Failure to do that will result in extremely low transmit powers.
363 ///
364 /// If you have an Arduino M0 Pro from arduino.org,
365 /// you should note that you cannot use Pin 2 for the interrupt line
366 /// (Pin 2 is for the NMI only). The same comments apply to Pin 4 on Arduino Zero from arduino.cc.
367 /// Instead you can use any other pin (we use Pin 3) and initialise RH_RF69 like this:
368 /// \code
369 /// // Slave Select is pin 10, interrupt is Pin 3
370 /// RH_RF95 driver(10, 3);
371 /// \endcode
372 ///
373 /// If you have a Rocket Scream Mini Ultra Pro with the RFM95W:
374 /// - Ensure you have Arduino SAMD board support 1.6.5 or later in Arduino IDE 1.6.8 or later.
375 /// - The radio SS is hardwired to pin D5 and the DIO0 interrupt to pin D2,
376 /// so you need to initialise the radio like this:
377 /// \code
378 /// RH_RF95 driver(5, 2);
379 /// \endcode
380 /// - The name of the serial port on that board is 'SerialUSB', not 'Serial', so this may be helpful at the top of our
381 /// sample sketches:
382 /// \code
383 /// #define Serial SerialUSB
384 /// \endcode
385 /// - You also need this in setup before radio initialisation
386 /// \code
387 /// // Ensure serial flash is not interfering with radio communication on SPI bus
388 /// pinMode(4, OUTPUT);
389 /// digitalWrite(4, HIGH);
390 /// \endcode
391 /// - and if you have a 915MHz part, you need this after driver/manager intitalisation:
392 /// \code
393 /// rf95.setFrequency(915.0);
394 /// \endcode
395 /// which adds up to modifying sample sketches something like:
396 /// \code
397 /// #include <SPI.h>
398 /// #include <RH_RF95.h>
399 /// RH_RF95 rf95(5, 2); // Rocket Scream Mini Ultra Pro with the RFM95W
400 /// #define Serial SerialUSB
401 ///
402 /// void setup()
403 /// {
404 /// // Ensure serial flash is not interfering with radio communication on SPI bus
405 /// pinMode(4, OUTPUT);
406 /// digitalWrite(4, HIGH);
407 ///
408 /// Serial.begin(9600);
409 /// while (!Serial) ; // Wait for serial port to be available
410 /// if (!rf95.init())
411 /// Serial.println("init failed");
412 /// rf95.setFrequency(915.0);
413 /// }
414 /// ...
415 /// \endcode
416 ///
417 /// For Adafruit Feather M0 with RFM95, construct the driver like this:
418 /// \code
419 /// RH_RF95 rf95(8, 3);
420 /// \endcode
421 ///
422 /// If you have a talk2 Whisper Node LoRa board with on-board RF95 radio,
423 /// the example rf95_* sketches work without modification. Initialise the radio like
424 /// with the default constructor:
425 /// \code
426 /// RH_RF95 driver;
427 /// \endcode
428 ///
429 /// It is possible to have 2 or more radios connected to one Arduino, provided
430 /// each radio has its own SS and interrupt line (SCK, SDI and SDO are common
431 /// to all radios)
432 ///
433 /// Caution: on some Arduinos such as the Mega 2560, if you set the slave
434 /// select pin to be other than the usual SS pin (D53 on Mega 2560), you may
435 /// need to set the usual SS pin to be an output to force the Arduino into SPI
436 /// master mode.
437 ///
438 /// Caution: Power supply requirements of the RFM module may be relevant in some circumstances:
439 /// RFM95/96/97/98 modules are capable of pulling 120mA+ at full power, where Arduino's 3.3V line can
440 /// give 50mA. You may need to make provision for alternate power supply for
441 /// the RFM module, especially if you wish to use full transmit power, and/or you have
442 /// other shields demanding power. Inadequate power for the RFM is likely to cause symptoms such as:
443 /// - reset's/bootups terminate with "init failed" messages
444 /// - random termination of communication after 5-30 packets sent/received
445 /// - "fake ok" state, where initialization passes fluently, but communication doesn't happen
446 /// - shields hang Arduino boards, especially during the flashing
447 ///
448 /// \par Interrupts
449 ///
450 /// The RH_RF95 driver uses interrupts to react to events in the RFM module,
451 /// such as the reception of a new packet, or the completion of transmission
452 /// of a packet. The RH_RF95 driver interrupt service routine reads status from
453 /// and writes data to the the RFM module via the SPI interface. It is very
454 /// important therefore, that if you are using the RH_RF95 driver with another
455 /// SPI based deviced, that you disable interrupts while you transfer data to
456 /// and from that other device. Use cli() to disable interrupts and sei() to
457 /// reenable them.
458 ///
459 /// \par Memory
460 ///
461 /// The RH_RF95 driver requires non-trivial amounts of memory. The sample
462 /// programs all compile to about 8kbytes each, which will fit in the
463 /// flash proram memory of most Arduinos. However, the RAM requirements are
464 /// more critical. Therefore, you should be vary sparing with RAM use in
465 /// programs that use the RH_RF95 driver.
466 ///
467 /// It is often hard to accurately identify when you are hitting RAM limits on Arduino.
468 /// The symptoms can include:
469 /// - Mysterious crashes and restarts
470 /// - Changes in behaviour when seemingly unrelated changes are made (such as adding print() statements)
471 /// - Hanging
472 /// - Output from Serial.print() not appearing
473 ///
474 /// \par Range
475 ///
476 /// We have made some simple range tests under the following conditions:
477 /// - rf95_client base station connected to a VHF discone antenna at 8m height above ground
478 /// - rf95_server mobile connected to 17.3cm 1/4 wavelength antenna at 1m height, no ground plane.
479 /// - Both configured for 13dBm, 434MHz, Bw = 125 kHz, Cr = 4/8, Sf = 4096chips/symbol, CRC on. Slow+long range
480 /// - Minimum reported RSSI seen for successful comms was about -91
481 /// - Range over flat ground through heavy trees and vegetation approx 2km.
482 /// - At 20dBm (100mW) otherwise identical conditions approx 3km.
483 /// - At 20dBm, along salt water flat sandy beach, 3.2km.
484 ///
485 /// It should be noted that at this data rate, a 12 octet message takes 2 seconds to transmit.
486 ///
487 /// At 20dBm (100mW) with Bw = 125 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on.
488 /// (Default medium range) in the conditions described above.
489 /// - Range over flat ground through heavy trees and vegetation approx 2km.
490 ///
491 /// Caution: the performance of this radio, especially with narrow bandwidths is strongly dependent on the
492 /// accuracy and stability of the chip clock. HopeRF and Semtech do not appear to
493 /// recommend bandwidths of less than 62.5 kHz
494 /// unless you have the optional Temperature Compensated Crystal Oscillator (TCXO) installed and
495 /// enabled on your radio module. See the refernece manual for more data.
496 /// Also https://lowpowerlab.com/forum/rf-range-antennas-rfm69-library/lora-library-experiences-range/15/
497 /// and http://www.semtech.com/images/datasheet/an120014-xo-guidance-lora-modulation.pdf
498 ///
499 /// \par Transmitter Power
500 ///
501 /// You can control the transmitter power on the RF transceiver
502 /// with the RH_RF95::setTxPower() function. The argument can be any of
503 /// +5 to +23 (for modules that use PA_BOOST)
504 /// -1 to +14 (for modules that use RFO transmitter pin)
505 /// The default is 13. Eg:
506 /// \code
507 /// driver.setTxPower(10); // use PA_BOOST transmitter pin
508 /// driver.setTxPower(10, true); // use PA_RFO pin transmitter pin
509 /// \endcode
510 ///
511 /// We have made some actual power measurements against
512 /// programmed power for Anarduino MiniWirelessLoRa (which has RFM96W-433Mhz installed)
513 /// - MiniWirelessLoRa RFM96W-433Mhz, USB power
514 /// - 30cm RG316 soldered direct to RFM96W module ANT and GND
515 /// - SMA connector
516 /// - 12db attenuator
517 /// - SMA connector
518 /// - MiniKits AD8307 HF/VHF Power Head (calibrated against Rohde&Schwartz 806.2020 test set)
519 /// - Tektronix TDS220 scope to measure the Vout from power head
520 /// \code
521 /// Program power Measured Power
522 /// dBm dBm
523 /// 5 5
524 /// 7 7
525 /// 9 8
526 /// 11 11
527 /// 13 13
528 /// 15 15
529 /// 17 16
530 /// 19 18
531 /// 20 20
532 /// 21 21
533 /// 22 22
534 /// 23 23
535 /// \endcode
536 ///
537 /// We have also measured the actual power output from a Modtronix inAir4 http://modtronix.com/inair4.html
538 /// connected to a Teensy 3.1:
539 /// Teensy 3.1 this is a 3.3V part, connected directly to:
540 /// Modtronix inAir4 with SMA antenna connector, connected as above:
541 /// 10cm SMA-SMA cable
542 /// - MiniKits AD8307 HF/VHF Power Head (calibrated against Rohde&Schwartz 806.2020 test set)
543 /// - Tektronix TDS220 scope to measure the Vout from power head
544 /// \code
545 /// Program power Measured Power
546 /// dBm dBm
547 /// -1 0
548 /// 1 2
549 /// 3 4
550 /// 5 7
551 /// 7 10
552 /// 9 13
553 /// 11 14.2
554 /// 13 15
555 /// 14 16
556 /// \endcode
557 /// (Caution: we dont claim laboratory accuracy for these power measurements)
558 /// You would not expect to get anywhere near these powers to air with a simple 1/4 wavelength wire antenna.
559 class RH_RF95 : public RHSPIDriver
560 {
561 public:
562  /// \brief Defines register values for a set of modem configuration registers
563  ///
564  /// Defines register values for a set of modem configuration registers
565  /// that can be passed to setModemRegisters() if none of the choices in
566  /// ModemConfigChoice suit your need setModemRegisters() writes the
567  /// register values from this structure to the appropriate registers
568  /// to set the desired spreading factor, coding rate and bandwidth
569  typedef struct
570  {
571  uint8_t reg_1d; ///< Value for register RH_RF95_REG_1D_MODEM_CONFIG1
572  uint8_t reg_1e; ///< Value for register RH_RF95_REG_1E_MODEM_CONFIG2
573  uint8_t reg_26; ///< Value for register RH_RF95_REG_26_MODEM_CONFIG3
574  } ModemConfig;
575 
576  /// Choices for setModemConfig() for a selected subset of common
577  /// data rates. If you need another configuration,
578  /// determine the necessary settings and call setModemRegisters() with your
579  /// desired settings. It might be helpful to use the LoRa calculator mentioned in
580  /// http://www.semtech.com/images/datasheet/LoraDesignGuide_STD.pdf
581  /// These are indexes into MODEM_CONFIG_TABLE. We strongly recommend you use these symbolic
582  /// definitions and not their integer equivalents: its possible that new values will be
583  /// introduced in later versions (though we will try to avoid it).
584  /// Caution: if you are using slow packet rates and long packets with RHReliableDatagram or subclasses
585  /// you may need to change the RHReliableDatagram timeout for reliable operations.
586  /// Caution: for some slow rates nad with ReliableDatagrams youi may need to increase the reply timeout
587  /// with manager.setTimeout() to
588  /// deal with the long transmission times.
589  typedef enum
590  {
591  Bw125Cr45Sf128 = 0, ///< Bw = 125 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Default medium range
592  Bw500Cr45Sf128, ///< Bw = 500 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Fast+short range
593  Bw31_25Cr48Sf512, ///< Bw = 31.25 kHz, Cr = 4/8, Sf = 512chips/symbol, CRC on. Slow+long range
594  Bw125Cr48Sf4096, ///< Bw = 125 kHz, Cr = 4/8, Sf = 4096chips/symbol, CRC on. Slow+long range
596 
597  /// Constructor. You can have multiple instances, but each instance must have its own
598  /// interrupt and slave select pin. After constructing, you must call init() to initialise the interface
599  /// and the radio module. A maximum of 3 instances can co-exist on one processor, provided there are sufficient
600  /// distinct interrupt lines, one for each instance.
601  /// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the RH_RF22 before
602  /// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, D10 for Maple)
603  /// \param[in] interruptPin The interrupt Pin number that is connected to the RFM DIO0 interrupt line.
604  /// Defaults to pin 2, as required by Anarduino MinWirelessLoRa module.
605  /// Caution: You must specify an interrupt capable pin.
606  /// On many Arduino boards, there are limitations as to which pins may be used as interrupts.
607  /// On Leonardo pins 0, 1, 2 or 3. On Mega2560 pins 2, 3, 18, 19, 20, 21. On Due and Teensy, any digital pin.
608  /// On Arduino Zero from arduino.cc, any digital pin other than 4.
609  /// On Arduino M0 Pro from arduino.org, any digital pin other than 2.
610  /// On other Arduinos pins 2 or 3.
611  /// See http://arduino.cc/en/Reference/attachInterrupt for more details.
612  /// On Chipkit Uno32, pins 38, 2, 7, 8, 35.
613  /// On other boards, any digital pin may be used.
614  /// \param[in] spi Pointer to the SPI interface object to use.
615  /// Defaults to the standard Arduino hardware SPI interface
616  RH_RF95(uint8_t slaveSelectPin = SS, uint8_t interruptPin = 2, RHGenericSPI& spi = hardware_spi);
617 
618  /// Initialise the Driver transport hardware and software.
619  /// Make sure the Driver is properly configured before calling init().
620  /// \return true if initialisation succeeded.
621  virtual bool init();
622 
623  /// Prints the value of all chip registers
624  /// to the Serial device if RH_HAVE_SERIAL is defined for the current platform
625  /// For debugging purposes only.
626  /// \return true on success
627  bool printRegisters();
628 
629  /// Sets all the registered required to configure the data modem in the RF95/96/97/98, including the bandwidth,
630  /// spreading factor etc. You can use this to configure the modem with custom configurations if none of the
631  /// canned configurations in ModemConfigChoice suit you.
632  /// \param[in] config A ModemConfig structure containing values for the modem configuration registers.
633  void setModemRegisters(const ModemConfig* config);
634 
635  /// Select one of the predefined modem configurations. If you need a modem configuration not provided
636  /// here, use setModemRegisters() with your own ModemConfig.
637  /// Caution: the slowest protocols may require a radio module with TCXO temperature controlled oscillator
638  /// for reliable operation.
639  /// \param[in] index The configuration choice.
640  /// \return true if index is a valid choice.
641  bool setModemConfig(ModemConfigChoice index);
642 
643  /// Tests whether a new message is available
644  /// from the Driver.
645  /// On most drivers, this will also put the Driver into RHModeRx mode until
646  /// a message is actually received by the transport, when it wil be returned to RHModeIdle.
647  /// This can be called multiple times in a timeout loop
648  /// \return true if a new, complete, error-free uncollected message is available to be retreived by recv()
649  virtual bool available();
650 
651  /// Turns the receiver on if it not already on.
652  /// If there is a valid message available, copy it to buf and return true
653  /// else return false.
654  /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
655  /// You should be sure to call this function frequently enough to not miss any messages
656  /// It is recommended that you call it in your main loop.
657  /// \param[in] buf Location to copy the received message
658  /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
659  /// \return true if a valid message was copied to buf
660  virtual bool recv(uint8_t* buf, uint8_t* len);
661 
662  /// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
663  /// Then optionally waits for Channel Activity Detection (CAD)
664  /// to show the channnel is clear (if the radio supports CAD) by calling waitCAD().
665  /// Then loads a message into the transmitter and starts the transmitter. Note that a message length
666  /// of 0 is permitted.
667  /// \param[in] data Array of data to be sent
668  /// \param[in] len Number of bytes of data to send
669  /// specify the maximum time in ms to wait. If 0 (the default) do not wait for CAD before transmitting.
670  /// \return true if the message length was valid and it was correctly queued for transmit. Return false
671  /// if CAD was requested and the CAD timeout timed out before clear channel was detected.
672  virtual bool send(const uint8_t* data, uint8_t len);
673 
674  /// Sets the length of the preamble
675  /// in bytes.
676  /// Caution: this should be set to the same
677  /// value on all nodes in your network. Default is 8.
678  /// Sets the message preamble length in RH_RF95_REG_??_PREAMBLE_?SB
679  /// \param[in] bytes Preamble length in bytes.
680  void setPreambleLength(uint16_t bytes);
681 
682  /// Returns the maximum message length
683  /// available in this Driver.
684  /// \return The maximum legal message length
685  virtual uint8_t maxMessageLength();
686 
687  /// Sets the transmitter and receiver
688  /// centre frequency.
689  /// \param[in] centre Frequency in MHz. 137.0 to 1020.0. Caution: RFM95/96/97/98 comes in several
690  /// different frequency ranges, and setting a frequency outside that range of your radio will probably not work
691  /// \return true if the selected frquency centre is within range
692  bool setFrequency(float centre);
693 
694  /// If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running,
695  /// disables them.
696  void setModeIdle();
697 
698  /// If current mode is Tx or Idle, changes it to Rx.
699  /// Starts the receiver in the RF95/96/97/98.
700  void setModeRx();
701 
702  /// If current mode is Rx or Idle, changes it to Rx. F
703  /// Starts the transmitter in the RF95/96/97/98.
704  void setModeTx();
705 
706  /// Sets the transmitter power output level, and configures the transmitter pin.
707  /// Be a good neighbour and set the lowest power level you need.
708  /// Some SX1276/77/78/79 and compatible modules (such as RFM95/96/97/98)
709  /// use the PA_BOOST transmitter pin for high power output (and optionally the PA_DAC)
710  /// while some (such as the Modtronix inAir4 and inAir9)
711  /// use the RFO transmitter pin for lower power but higher efficiency.
712  /// You must set the appropriate power level and useRFO argument for your module.
713  /// Check with your module manufacturer which transmtter pin is used on your module
714  /// to ensure you are setting useRFO correctly.
715  /// Failure to do so will result in very low
716  /// transmitter power output.
717  /// Caution: legal power limits may apply in certain countries.
718  /// After init(), the power will be set to 13dBm, with useRFO false (ie PA_BOOST enabled).
719  /// \param[in] power Transmitter power level in dBm. For RFM95/96/97/98 LORA with useRFO false,
720  /// valid values are from +5 to +23.
721  /// For Modtronix inAir4 and inAir9 with useRFO true (ie RFO pins in use),
722  /// valid values are from -1 to 14.
723  /// \param[in] useRFO If true, enables the use of the RFO transmitter pins instead of
724  /// the PA_BOOST pin (false). Choose the correct setting for your module.
725  void setTxPower(int8_t power, bool useRFO = false);
726 
727  /// Sets the radio into low-power sleep mode.
728  /// If successful, the transport will stay in sleep mode until woken by
729  /// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
730  /// Caution: there is a time penalty as the radio takes a finite time to wake from sleep mode.
731  /// \return true if sleep mode was successfully entered.
732  virtual bool sleep();
733 
734  // Bent G Christensen (bentor@gmail.com), 08/15/2016
735  /// Use the radio's Channel Activity Detect (CAD) function to detect channel activity.
736  /// Sets the RF95 radio into CAD mode and waits until CAD detection is complete.
737  /// To be used in a listen-before-talk mechanism (Collision Avoidance)
738  /// with a reasonable time backoff algorithm.
739  /// This is called automatically by waitCAD().
740  /// \return true if channel is in use.
741  virtual bool isChannelActive();
742 
743  /// Enable TCXO mode
744  /// Call this immediately after init(), to force your radio to use an external
745  /// frequency source, such as a Temperature Compensated Crystal Oscillator (TCXO), if available.
746  /// See the comments in the main documentation about the sensitivity of this radio to
747  /// clock frequency especially when using narrow bandwidths.
748  /// Leaves the module in sleep mode.
749  /// Caution, this function has not been tested by us.
750  /// Caution, the TCXO model radios are not low power when in sleep (consuming
751  /// about ~600 uA, reported by Phang Moh Lim.<br>
752  void enableTCXO();
753 
754  /// Returns the last measured frequency error.
755  /// The LoRa receiver estimates the frequency offset between the receiver centre frequency
756  /// and that of the received LoRa signal. This function returns the estimates offset (in Hz)
757  /// of the last received message. Caution: this measurement is not absolute, but is measured
758  /// relative to the local receiver's oscillator.
759  /// Apparent errors may be due to the transmitter, the receiver or both.
760  /// \return The estimated centre frequency offset in Hz of the last received message.
761  /// If the modem bandwidth selector in
762  /// register RH_RF95_REG_1D_MODEM_CONFIG1 is invalid, returns 0.
763  int frequencyError();
764 
765  /// Returns the Signal-to-noise ratio (SNR) of the last received message, as measured
766  /// by the receiver.
767  /// \return SNR of the last received message in dB
768  int lastSNR();
769 
770 protected:
771  /// This is a low level function to handle the interrupts for one instance of RH_RF95.
772  /// Called automatically by isr*()
773  /// Should not need to be called by user code.
774  void handleInterrupt();
775 
776  /// Examine the revceive buffer to determine whether the message is for this node
777  void validateRxBuf();
778 
779  /// Clear our local receive buffer
780  void clearRxBuf();
781 
782 private:
783  /// Low level interrupt service routine for device connected to interrupt 0
784  static void isr0();
785 
786  /// Low level interrupt service routine for device connected to interrupt 1
787  static void isr1();
788 
789  /// Low level interrupt service routine for device connected to interrupt 1
790  static void isr2();
791 
792  /// Array of instances connected to interrupts 0 and 1
793  static RH_RF95* _deviceForInterrupt[];
794 
795  /// Index of next interrupt number to use in _deviceForInterrupt
796  static uint8_t _interruptCount;
797 
798  /// The configured interrupt pin connected to this instance
799  uint8_t _interruptPin;
800 
801  /// The index into _deviceForInterrupt[] for this device (if an interrupt is already allocated)
802  /// else 0xff
803  uint8_t _myInterruptIndex;
804 
805  /// Number of octets in the buffer
806  volatile uint8_t _bufLen;
807 
808  /// The receiver/transmitter buffer
809  uint8_t _buf[RH_RF95_MAX_PAYLOAD_LEN];
810 
811  /// True when there is a valid message in the buffer
812  volatile bool _rxBufValid;
813 
814  // True if we are using the HF port (779.0 MHz and above)
815  bool _usingHFport;
816 
817  // Last measured SNR, dB
818  int8_t _lastSNR;
819 };
820 
821 /// @example rf95_client.pde
822 /// @example rf95_server.pde
823 /// @example rf95_encrypted_client.pde
824 /// @example rf95_encrypted_server.pde
825 /// @example rf95_reliable_datagram_client.pde
826 /// @example rf95_reliable_datagram_server.pde
827 
828 #endif
829 
void handleInterrupt()
Definition: RH_RF95.cpp:124
virtual bool recv(uint8_t *buf, uint8_t *len)
Definition: RH_RF95.cpp:236
virtual bool available()
Definition: RH_RF95.cpp:220
Base class for SPI interfaces.
Definition: RHGenericSPI.h:30
void validateRxBuf()
Examine the revceive buffer to determine whether the message is for this node.
Definition: RH_RF95.cpp:202
uint8_t reg_1d
Value for register RH_RF95_REG_1D_MODEM_CONFIG1.
Definition: RH_RF95.h:571
int frequencyError()
Definition: RH_RF95.cpp:449
int lastSNR()
Definition: RH_RF95.cpp:476
ModemConfigChoice
Definition: RH_RF95.h:589
RH_RF95(uint8_t slaveSelectPin=SS, uint8_t interruptPin=2, RHGenericSPI &spi=hardware_spi)
Definition: RH_RF95.cpp:26
void setModeIdle()
Definition: RH_RF95.cpp:313
bool setFrequency(float centre)
Definition: RH_RF95.cpp:301
Bw = 125 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Default medium range.
Definition: RH_RF95.h:591
void setPreambleLength(uint16_t bytes)
Definition: RH_RF95.cpp:416
virtual bool init()
Definition: RH_RF95.cpp:35
Defines register values for a set of modem configuration registers.
Definition: RH_RF95.h:569
Driver to send and receive unaddressed, unreliable datagrams via a LoRa capable radio transceiver...
Definition: RH_RF95.h:559
void clearRxBuf()
Clear our local receive buffer.
Definition: RH_RF95.cpp:228
virtual bool send(const uint8_t *data, uint8_t len)
Definition: RH_RF95.cpp:253
virtual bool isChannelActive()
Definition: RH_RF95.cpp:422
Bw = 31.25 kHz, Cr = 4/8, Sf = 512chips/symbol, CRC on. Slow+long range.
Definition: RH_RF95.h:593
Bw = 125 kHz, Cr = 4/8, Sf = 4096chips/symbol, CRC on. Slow+long range.
Definition: RH_RF95.h:594
void enableTCXO()
Definition: RH_RF95.cpp:438
uint8_t reg_26
Value for register RH_RF95_REG_26_MODEM_CONFIG3.
Definition: RH_RF95.h:573
void setModeTx()
Definition: RH_RF95.cpp:342
virtual uint8_t maxMessageLength()
Definition: RH_RF95.cpp:296
uint8_t reg_1e
Value for register RH_RF95_REG_1E_MODEM_CONFIG2.
Definition: RH_RF95.h:572
Bw = 500 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Fast+short range.
Definition: RH_RF95.h:592
void setModeRx()
Definition: RH_RF95.cpp:332
bool setModemConfig(ModemConfigChoice index)
Definition: RH_RF95.cpp:404
Base class for RadioHead drivers that use the SPI bus to communicate with its transport hardware...
Definition: RHSPIDriver.h:38
void setTxPower(int8_t power, bool useRFO=false)
Definition: RH_RF95.cpp:352
bool printRegisters()
Definition: RH_RF95.cpp:280
void setModemRegisters(const ModemConfig *config)
Definition: RH_RF95.cpp:395
virtual bool sleep()
Definition: RH_RF95.cpp:322