David Rimer
Port of RadioHead version 1.48 to mbed. It is a little messy and only works for SPI at this time.
RH_RF69.h
- Committer:
- davidr99
- Date:
- 2015-10-15
- Revision:
- 0:ab4e012489ef
File content as of revision 0:ab4e012489ef:
// RH_RF69.h
// Author: Mike McCauley (mikem@airspayce.com)
// Copyright (C) 2014 Mike McCauley
// $Id: RH_RF69.h,v 1.29 2015/05/17 00:11:26 mikem Exp $
//
///
#ifndef RH_RF69_h
#define RH_RF69_h
#include <RHGenericSPI.h>
#include <RHSPIDriver.h>
// The crystal oscillator frequency of the RF69 module
#define RH_RF69_FXOSC 32000000.0
// The Frequency Synthesizer step = RH_RF69_FXOSC / 2^^19
#define RH_RF69_FSTEP (RH_RF69_FXOSC / 524288)
// This is the maximum number of interrupts the driver can support
// Most Arduinos can handle 2, Megas can handle more
#define RH_RF69_NUM_INTERRUPTS 3
// This is the bit in the SPI address that marks it as a write
#define RH_RF69_SPI_WRITE_MASK 0x80
// Max number of octets the RH_RF69 Rx and Tx FIFOs can hold
#define RH_RF69_FIFO_SIZE 66
// Maximum encryptable payload length the RF69 can support
#define RH_RF69_MAX_ENCRYPTABLE_PAYLOAD_LEN 64
// The length of the headers we add.
// The headers are inside the RF69's payload and are therefore encrypted if encryption is enabled
#define RH_RF69_HEADER_LEN 4
// This is the maximum message length that can be supported by this driver. Limited by
// the size of the FIFO, since we are unable to support on-the-fly filling and emptying
// of the FIFO.
// Can be pre-defined to a smaller size (to save SRAM) prior to including this header
// Here we allow for 4 bytes of address and header and payload to be included in the 64 byte encryption limit.
// the one byte payload length is not encrpyted
#ifndef RH_RF69_MAX_MESSAGE_LEN
#define RH_RF69_MAX_MESSAGE_LEN (RH_RF69_MAX_ENCRYPTABLE_PAYLOAD_LEN - RH_RF69_HEADER_LEN)
#endif
// Keep track of the mode the RF69 is in
#define RH_RF69_MODE_IDLE 0
#define RH_RF69_MODE_RX 1
#define RH_RF69_MODE_TX 2
// This is the default node address,
#define RH_RF69_DEFAULT_NODE_ADDRESS 0
// Register names
#define RH_RF69_REG_00_FIFO 0x00
#define RH_RF69_REG_01_OPMODE 0x01
#define RH_RF69_REG_02_DATAMODUL 0x02
#define RH_RF69_REG_03_BITRATEMSB 0x03
#define RH_RF69_REG_04_BITRATELSB 0x04
#define RH_RF69_REG_05_FDEVMSB 0x05
#define RH_RF69_REG_06_FDEVLSB 0x06
#define RH_RF69_REG_07_FRFMSB 0x07
#define RH_RF69_REG_08_FRFMID 0x08
#define RH_RF69_REG_09_FRFLSB 0x09
#define RH_RF69_REG_0A_OSC1 0x0a
#define RH_RF69_REG_0B_AFCCTRL 0x0b
#define RH_RF69_REG_0C_RESERVED 0x0c
#define RH_RF69_REG_0D_LISTEN1 0x0d
#define RH_RF69_REG_0E_LISTEN2 0x0e
#define RH_RF69_REG_0F_LISTEN3 0x0f
#define RH_RF69_REG_10_VERSION 0x10
#define RH_RF69_REG_11_PALEVEL 0x11
#define RH_RF69_REG_12_PARAMP 0x12
#define RH_RF69_REG_13_OCP 0x13
#define RH_RF69_REG_14_RESERVED 0x14
#define RH_RF69_REG_15_RESERVED 0x15
#define RH_RF69_REG_16_RESERVED 0x16
#define RH_RF69_REG_17_RESERVED 0x17
#define RH_RF69_REG_18_LNA 0x18
#define RH_RF69_REG_19_RXBW 0x19
#define RH_RF69_REG_1A_AFCBW 0x1a
#define RH_RF69_REG_1B_OOKPEAK 0x1b
#define RH_RF69_REG_1C_OOKAVG 0x1c
#define RH_RF69_REG_1D_OOKFIX 0x1d
#define RH_RF69_REG_1E_AFCFEI 0x1e
#define RH_RF69_REG_1F_AFCMSB 0x1f
#define RH_RF69_REG_20_AFCLSB 0x20
#define RH_RF69_REG_21_FEIMSB 0x21
#define RH_RF69_REG_22_FEILSB 0x22
#define RH_RF69_REG_23_RSSICONFIG 0x23
#define RH_RF69_REG_24_RSSIVALUE 0x24
#define RH_RF69_REG_25_DIOMAPPING1 0x25
#define RH_RF69_REG_26_DIOMAPPING2 0x26
#define RH_RF69_REG_27_IRQFLAGS1 0x27
#define RH_RF69_REG_28_IRQFLAGS2 0x28
#define RH_RF69_REG_29_RSSITHRESH 0x29
#define RH_RF69_REG_2A_RXTIMEOUT1 0x2a
#define RH_RF69_REG_2B_RXTIMEOUT2 0x2b
#define RH_RF69_REG_2C_PREAMBLEMSB 0x2c
#define RH_RF69_REG_2D_PREAMBLELSB 0x2d
#define RH_RF69_REG_2E_SYNCCONFIG 0x2e
#define RH_RF69_REG_2F_SYNCVALUE1 0x2f
// another 7 sync word bytes follow, 30 through 36 inclusive
#define RH_RF69_REG_37_PACKETCONFIG1 0x37
#define RH_RF69_REG_38_PAYLOADLENGTH 0x38
#define RH_RF69_REG_39_NODEADRS 0x39
#define RH_RF69_REG_3A_BROADCASTADRS 0x3a
#define RH_RF69_REG_3B_AUTOMODES 0x3b
#define RH_RF69_REG_3C_FIFOTHRESH 0x3c
#define RH_RF69_REG_3D_PACKETCONFIG2 0x3d
#define RH_RF69_REG_3E_AESKEY1 0x3e
// Another 15 AES key bytes follow
#define RH_RF69_REG_4E_TEMP1 0x4e
#define RH_RF69_REG_4F_TEMP2 0x4f
#define RH_RF69_REG_58_TESTLNA 0x58
#define RH_RF69_REG_5A_TESTPA1 0x5a
#define RH_RF69_REG_5C_TESTPA2 0x5c
#define RH_RF69_REG_6F_TESTDAGC 0x6f
#define RH_RF69_REG_71_TESTAFC 0x71
// These register masks etc are named wherever possible
// corresponding to the bit and field names in the RFM69 Manual
// RH_RF69_REG_01_OPMODE
#define RH_RF69_OPMODE_SEQUENCEROFF 0x80
#define RH_RF69_OPMODE_LISTENON 0x40
#define RH_RF69_OPMODE_LISTENABORT 0x20
#define RH_RF69_OPMODE_MODE 0x1c
#define RH_RF69_OPMODE_MODE_SLEEP 0x00
#define RH_RF69_OPMODE_MODE_STDBY 0x04
#define RH_RF69_OPMODE_MODE_FS 0x08
#define RH_RF69_OPMODE_MODE_TX 0x0c
#define RH_RF69_OPMODE_MODE_RX 0x10
// RH_RF69_REG_02_DATAMODUL
#define RH_RF69_DATAMODUL_DATAMODE 0x60
#define RH_RF69_DATAMODUL_DATAMODE_PACKET 0x00
#define RH_RF69_DATAMODUL_DATAMODE_CONT_WITH_SYNC 0x40
#define RH_RF69_DATAMODUL_DATAMODE_CONT_WITHOUT_SYNC 0x60
#define RH_RF69_DATAMODUL_MODULATIONTYPE 0x18
#define RH_RF69_DATAMODUL_MODULATIONTYPE_FSK 0x00
#define RH_RF69_DATAMODUL_MODULATIONTYPE_OOK 0x08
#define RH_RF69_DATAMODUL_MODULATIONSHAPING 0x03
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_FSK_NONE 0x00
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_FSK_BT1_0 0x01
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_FSK_BT0_5 0x02
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_FSK_BT0_3 0x03
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_OOK_NONE 0x00
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_OOK_BR 0x01
#define RH_RF69_DATAMODUL_MODULATIONSHAPING_OOK_2BR 0x02
// RH_RF69_REG_11_PALEVEL
#define RH_RF69_PALEVEL_PA0ON 0x80
#define RH_RF69_PALEVEL_PA1ON 0x40
#define RH_RF69_PALEVEL_PA2ON 0x20
#define RH_RF69_PALEVEL_OUTPUTPOWER 0x1f
// RH_RF69_REG_23_RSSICONFIG
#define RH_RF69_RSSICONFIG_RSSIDONE 0x02
#define RH_RF69_RSSICONFIG_RSSISTART 0x01
// RH_RF69_REG_25_DIOMAPPING1
#define RH_RF69_DIOMAPPING1_DIO0MAPPING 0xc0
#define RH_RF69_DIOMAPPING1_DIO0MAPPING_00 0x00
#define RH_RF69_DIOMAPPING1_DIO0MAPPING_01 0x40
#define RH_RF69_DIOMAPPING1_DIO0MAPPING_10 0x80
#define RH_RF69_DIOMAPPING1_DIO0MAPPING_11 0xc0
#define RH_RF69_DIOMAPPING1_DIO1MAPPING 0x30
#define RH_RF69_DIOMAPPING1_DIO1MAPPING_00 0x00
#define RH_RF69_DIOMAPPING1_DIO1MAPPING_01 0x10
#define RH_RF69_DIOMAPPING1_DIO1MAPPING_10 0x20
#define RH_RF69_DIOMAPPING1_DIO1MAPPING_11 0x30
#define RH_RF69_DIOMAPPING1_DIO2MAPPING 0x0c
#define RH_RF69_DIOMAPPING1_DIO2MAPPING_00 0x00
#define RH_RF69_DIOMAPPING1_DIO2MAPPING_01 0x04
#define RH_RF69_DIOMAPPING1_DIO2MAPPING_10 0x08
#define RH_RF69_DIOMAPPING1_DIO2MAPPING_11 0x0c
#define RH_RF69_DIOMAPPING1_DIO3MAPPING 0x03
#define RH_RF69_DIOMAPPING1_DIO3MAPPING_00 0x00
#define RH_RF69_DIOMAPPING1_DIO3MAPPING_01 0x01
#define RH_RF69_DIOMAPPING1_DIO3MAPPING_10 0x02
#define RH_RF69_DIOMAPPING1_DIO3MAPPING_11 0x03
// RH_RF69_REG_26_DIOMAPPING2
#define RH_RF69_DIOMAPPING2_DIO4MAPPING 0xc0
#define RH_RF69_DIOMAPPING2_DIO4MAPPING_00 0x00
#define RH_RF69_DIOMAPPING2_DIO4MAPPING_01 0x40
#define RH_RF69_DIOMAPPING2_DIO4MAPPING_10 0x80
#define RH_RF69_DIOMAPPING2_DIO4MAPPING_11 0xc0
#define RH_RF69_DIOMAPPING2_DIO5MAPPING 0x30
#define RH_RF69_DIOMAPPING2_DIO5MAPPING_00 0x00
#define RH_RF69_DIOMAPPING2_DIO5MAPPING_01 0x10
#define RH_RF69_DIOMAPPING2_DIO5MAPPING_10 0x20
#define RH_RF69_DIOMAPPING2_DIO5MAPPING_11 0x30
#define RH_RF69_DIOMAPPING2_CLKOUT 0x07
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_ 0x00
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_2 0x01
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_4 0x02
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_8 0x03
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_16 0x04
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_32 0x05
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_RC 0x06
#define RH_RF69_DIOMAPPING2_CLKOUT_FXOSC_OFF 0x07
// RH_RF69_REG_27_IRQFLAGS1
#define RH_RF69_IRQFLAGS1_MODEREADY 0x80
#define RH_RF69_IRQFLAGS1_RXREADY 0x40
#define RH_RF69_IRQFLAGS1_TXREADY 0x20
#define RH_RF69_IRQFLAGS1_PLLLOCK 0x10
#define RH_RF69_IRQFLAGS1_RSSI 0x08
#define RH_RF69_IRQFLAGS1_TIMEOUT 0x04
#define RH_RF69_IRQFLAGS1_AUTOMODE 0x02
#define RH_RF69_IRQFLAGS1_SYNADDRESSMATCH 0x01
// RH_RF69_REG_28_IRQFLAGS2
#define RH_RF69_IRQFLAGS2_FIFOFULL 0x80
#define RH_RF69_IRQFLAGS2_FIFONOTEMPTY 0x40
#define RH_RF69_IRQFLAGS2_FIFOLEVEL 0x20
#define RH_RF69_IRQFLAGS2_FIFOOVERRUN 0x10
#define RH_RF69_IRQFLAGS2_PACKETSENT 0x08
#define RH_RF69_IRQFLAGS2_PAYLOADREADY 0x04
#define RH_RF69_IRQFLAGS2_CRCOK 0x02
// RH_RF69_REG_2E_SYNCCONFIG
#define RH_RF69_SYNCCONFIG_SYNCON 0x80
#define RH_RF69_SYNCCONFIG_FIFOFILLCONDITION_MANUAL 0x40
#define RH_RF69_SYNCCONFIG_SYNCSIZE 0x38
#define RH_RF69_SYNCCONFIG_SYNCSIZE_1 0x00
#define RH_RF69_SYNCCONFIG_SYNCSIZE_2 0x08
#define RH_RF69_SYNCCONFIG_SYNCSIZE_3 0x10
#define RH_RF69_SYNCCONFIG_SYNCSIZE_4 0x18
#define RH_RF69_SYNCCONFIG_SYNCSIZE_5 0x20
#define RH_RF69_SYNCCONFIG_SYNCSIZE_6 0x28
#define RH_RF69_SYNCCONFIG_SYNCSIZE_7 0x30
#define RH_RF69_SYNCCONFIG_SYNCSIZE_8 0x38
#define RH_RF69_SYNCCONFIG_SYNCSIZE_SYNCTOL 0x07
// RH_RF69_REG_37_PACKETCONFIG1
#define RH_RF69_PACKETCONFIG1_PACKETFORMAT_VARIABLE 0x80
#define RH_RF69_PACKETCONFIG1_DCFREE 0x60
#define RH_RF69_PACKETCONFIG1_DCFREE_NONE 0x00
#define RH_RF69_PACKETCONFIG1_DCFREE_MANCHESTER 0x20
#define RH_RF69_PACKETCONFIG1_DCFREE_WHITENING 0x40
#define RH_RF69_PACKETCONFIG1_DCFREE_RESERVED 0x60
#define RH_RF69_PACKETCONFIG1_CRC_ON 0x10
#define RH_RF69_PACKETCONFIG1_CRCAUTOCLEAROFF 0x08
#define RH_RF69_PACKETCONFIG1_ADDRESSFILTERING 0x06
#define RH_RF69_PACKETCONFIG1_ADDRESSFILTERING_NONE 0x00
#define RH_RF69_PACKETCONFIG1_ADDRESSFILTERING_NODE 0x02
#define RH_RF69_PACKETCONFIG1_ADDRESSFILTERING_NODE_BC 0x04
#define RH_RF69_PACKETCONFIG1_ADDRESSFILTERING_RESERVED 0x06
// RH_RF69_REG_3C_FIFOTHRESH
#define RH_RF69_FIFOTHRESH_TXSTARTCONDITION_NOTEMPTY 0x80
#define RH_RF69_FIFOTHRESH_FIFOTHRESHOLD 0x7f
// RH_RF69_REG_3D_PACKETCONFIG2
#define RH_RF69_PACKETCONFIG2_INTERPACKETRXDELAY 0xf0
#define RH_RF69_PACKETCONFIG2_RESTARTRX 0x04
#define RH_RF69_PACKETCONFIG2_AUTORXRESTARTON 0x02
#define RH_RF69_PACKETCONFIG2_AESON 0x01
// RH_RF69_REG_4E_TEMP1
#define RH_RF69_TEMP1_TEMPMEASSTART 0x08
#define RH_RF69_TEMP1_TEMPMEASRUNNING 0x04
// RH_RF69_REG_5A_TESTPA1
#define RH_RF69_TESTPA1_NORMAL 0x55
#define RH_RF69_TESTPA1_BOOST 0x5d
// RH_RF69_REG_5C_TESTPA2
#define RH_RF69_TESTPA2_NORMAL 0x70
#define RH_RF69_TESTPA2_BOOST 0x7c
// RH_RF69_REG_6F_TESTDAGC
#define RH_RF69_TESTDAGC_CONTINUOUSDAGC_NORMAL 0x00
#define RH_RF69_TESTDAGC_CONTINUOUSDAGC_IMPROVED_LOWBETAON 0x20
#define RH_RF69_TESTDAGC_CONTINUOUSDAGC_IMPROVED_LOWBETAOFF 0x30
// Define this to include Serial printing in diagnostic routines
#define RH_RF69_HAVE_SERIAL
/////////////////////////////////////////////////////////////////////
/// \class RH_RF69 RH_RF69.h <RH_RF69.h>
/// \brief Driver to send and receive unaddressed, unreliable datagrams via an RF69 and compatible radio transceiver.
///
/// Works with
/// - the excellent Moteino and Moteino-USB
/// boards from LowPowerLab http://lowpowerlab.com/moteino/
/// - compatible chips and modules such as RFM69W, RFM69HW, RFM69CW, RFM69HCW (Semtech SX1231, SX1231H),
/// - RFM69 modules from http://www.hoperfusa.com such as http://www.hoperfusa.com/details.jsp?pid=145
/// - Anarduino MiniWireless -CW and -HW boards http://www.anarduino.com/miniwireless/ including
/// the marvellous high powered MinWireless-HW (with 20dBm output for excellent range)
///
/// \par Overview
///
/// This class provides basic functions for sending and receiving unaddressed,
/// unreliable datagrams of arbitrary length to 64 octets per packet.
///
/// Manager classes may use this class to implement reliable, addressed datagrams and streams,
/// mesh routers, repeaters, translators etc.
///
/// Naturally, for any 2 radios to communicate that must be configured to use the same frequency and
/// modulation scheme.
///
/// This Driver provides an object-oriented interface for sending and receiving data messages with Hope-RF
/// RF69B and compatible radio modules, such as the RFM69 module.
///
/// The Hope-RF (http://www.hoperf.com) RF69 is a low-cost ISM transceiver
/// chip. It supports FSK, GFSK, OOK over a wide range of frequencies and
/// programmable data rates. It also suports AES encryption of up to 64 octets
/// of payload It is available prepackaged on modules such as the RFM69W. And
/// such modules can be prepacked on processor boards such as the Moteino from
/// LowPowerLabs (which is what we used to develop the RH_RF69 driver)
///
/// This Driver provides functions for sending and receiving messages of up
/// to 60 octets on any frequency supported by the RF69, in a range of
/// predefined data rates and frequency deviations. Frequency can be set with
/// 61Hz precision to any frequency from 240.0MHz to 960.0MHz. Caution: most modules only support a more limited
/// range of frequencies due to antenna tuning.
///
/// Up to 2 RF69B modules can be connected to an Arduino (3 on a Mega),
/// permitting the construction of translators and frequency changers, etc.
///
/// The following modulation types are suppported with a range of modem configurations for
/// common data rates and frequency deviations:
/// - GFSK Gaussian Frequency Shift Keying
/// - FSK Frequency Shift Keying
///
/// Support for other RF69 features such as on-chip temperature measurement,
/// transmitter power control etc is also provided.
///
/// Tested on USB-Moteino with arduino-1.0.5
/// on OpenSuSE 13.1
///
/// \par Packet Format
///
/// All messages sent and received by this RH_RF69 Driver conform to this packet format:
///
/// - 4 octets PREAMBLE
/// - 2 octets SYNC 0x2d, 0xd4 (configurable, so you can use this as a network filter)
/// - 1 octet RH_RF69 payload length
/// - 4 octets HEADER: (TO, FROM, ID, FLAGS)
/// - 0 to 60 octets DATA
/// - 2 octets CRC computed with CRC16(IBM), computed on HEADER and DATA
///
/// For technical reasons, the message format is not protocol compatible with the
/// 'HopeRF Radio Transceiver Message Library for Arduino'
/// http://www.airspayce.com/mikem/arduino/HopeRF from the same author. Nor is
/// it compatible with messages sent by 'Virtual Wire'
/// http://www.airspayce.com/mikem/arduino/VirtualWire.pdf also from the same
/// author. Nor is it compatible with messages sent by 'RF22'
/// http://www.airspayce.com/mikem/arduino/RF22 also from the same author.
///
/// \par Connecting RFM-69 to Arduino
///
/// We tested with Moteino, which is an Arduino Uno compatible with the RFM69W
/// module on-board. Therefore it needs no connections other than the USB
/// programming connection and an antenna to make it work.
///
/// If you have a bare RFM69W that you want to connect to an Arduino, you
/// might use these connections (untested): CAUTION: you must use a 3.3V type
/// Arduino, otherwise you will also need voltage level shifters between the
/// Arduino and the RFM69. CAUTION, you must also ensure you connect an
/// antenna
///
/// \code
/// Arduino RFM69W
/// GND----------GND (ground in)
/// 3V3----------3.3V (3.3V in)
/// interrupt 0 pin D2-----------DIO0 (interrupt request out)
/// SS pin D10----------NSS (chip select in)
/// SCK pin D13----------SCK (SPI clock in)
/// MOSI pin D11----------MOSI (SPI Data in)
/// MISO pin D12----------MISO (SPI Data out)
/// \endcode
///
/// With these connections, you can then use the default constructor RH_RF69().
/// You can override the default settings for the SS pin and the interrupt in
/// the RH_RF69 constructor if you wish to connect the slave select SS to other
/// than the normal one for your Arduino (D10 for Diecimila, Uno etc and D53
/// for Mega) or the interrupt request to other than pin D2 (Caution,
/// different processors have different constraints as to the pins available
/// for interrupts).
///
/// If you have a Teensy 3.1 and a compatible RFM69 breakout board, you will need to
/// construct the RH_RF69 instance like this:
/// \code
/// RH_RF69 driver(15, 16);
/// \endcode
///
/// If you have a MoteinoMEGA https://lowpowerlab.com/shop/moteinomega
/// with RFM69 on board, you dont need to make any wiring connections
/// (the RFM69 module is soldered onto the MotienoMEGA), but you must initialise the RH_RF69
/// constructor like this:
/// \code
/// RH_RF69 driver(4, 2);
/// \endcode
/// Make sure you have the MoteinoMEGA core installed in your Arduino hardware folder as described in the
/// documentation for the MoteinoMEGA.
///
/// It is possible to have 2 or more radios connected to one Arduino, provided
/// each radio has its own SS and interrupt line (SCK, SDI and SDO are common
/// to all radios)
///
/// Caution: on some Arduinos such as the Mega 2560, if you set the slave
/// select pin to be other than the usual SS pin (D53 on Mega 2560), you may
/// need to set the usual SS pin to be an output to force the Arduino into SPI
/// master mode.
///
/// Caution: Power supply requirements of the RF69 module may be relevant in some circumstances:
/// RF69 modules are capable of pulling 45mA+ at full power, where Arduino's 3.3V line can
/// give 50mA. You may need to make provision for alternate power supply for
/// the RF69, especially if you wish to use full transmit power, and/or you have
/// other shields demanding power. Inadequate power for the RF69 is likely to cause symptoms such as:
/// -reset's/bootups terminate with "init failed" messages
/// -random termination of communication after 5-30 packets sent/received
/// -"fake ok" state, where initialization passes fluently, but communication doesn't happen
/// -shields hang Arduino boards, especially during the flashing
/// \par Interrupts
///
/// The RH_RF69 driver uses interrupts to react to events in the RF69 module,
/// such as the reception of a new packet, or the completion of transmission
/// of a packet. The RH_RF69 driver interrupt service routine reads status from
/// and writes data to the the RF69 module via the SPI interface. It is very
/// important therefore, that if you are using the RH_RF69 driver with another
/// SPI based deviced, that you disable interrupts while you transfer data to
/// and from that other device. Use cli() to disable interrupts and sei() to
/// reenable them.
///
/// \par Memory
///
/// The RH_RF69 driver requires non-trivial amounts of memory. The sample
/// programs above all compile to about 8kbytes each, which will fit in the
/// flash proram memory of most Arduinos. However, the RAM requirements are
/// more critical. Therefore, you should be vary sparing with RAM use in
/// programs that use the RH_RF69 driver.
///
/// It is often hard to accurately identify when you are hitting RAM limits on Arduino.
/// The symptoms can include:
/// - Mysterious crashes and restarts
/// - Changes in behaviour when seemingly unrelated changes are made (such as adding print() statements)
/// - Hanging
/// - Output from Serial.print() not appearing
///
/// \par Automatic Frequency Control (AFC)
///
/// The RF69 module is configured by the RH_RF69 driver to always use AFC.
///
/// \par Transmitter Power
///
/// You can control the transmitter power on the RF69 transceiver
/// with the RH_RF69::setTxPower() function. The argument can be any of
/// -18 to +13 (for RF69W) or -14 to 20 (for RF69HW)
/// The default is 13. Eg:
/// \code
/// driver.setTxPower(-5);
/// \endcode
///
/// We have made some actual power measurements against
/// programmed power for Moteino (with RF69W)
/// - Moteino (with RF69W), USB power
/// - 10cm RG58C/U soldered direct to RFM69 module ANT and GND
/// - bnc connecteor
/// - 12dB attenuator
/// - BNC-SMA adapter
/// - MiniKits AD8307 HF/VHF Power Head (calibrated against Rohde&Schwartz 806.2020 test set)
/// - Tektronix TDS220 scope to measure the Vout from power head
/// \code
/// Program power Measured Power
/// dBm dBm
/// -18 -17
/// -16 -16
/// -14 -14
/// -12 -12
/// -10 -9
/// -8 -7
/// -6 -4
/// -4 -3
/// -2 -2
/// 0 0.2
/// 2 3
/// 4 5
/// 6 7
/// 8 10
/// 10 13
/// 12 14
/// 13 15
/// 14 -51
/// 20 -51
/// \endcode
/// We have also made some actual power measurements against
/// programmed power for Anarduino MiniWireless with RFM69-HW
/// Anarduino MiniWireless (with RFM69-HW), USB power
/// - 10cm RG58C/U soldered direct to RFM69 module ANT and GND
/// - bnc connecteor
/// - 2x12dB attenuators
/// - BNC-SMA adapter
/// - MiniKits AD8307 HF/VHF Power Head (calibrated against Rohde&Schwartz 806.2020 test set)
/// - Tektronix TDS220 scope to measure the Vout from power head
/// \code
/// Program power Measured Power
/// dBm dBm
/// -18 no measurable output
/// 0 no measurable output
/// 13 no measurable output
/// 14 11
/// 15 12
/// 16 12.4
/// 17 14
/// 18 15
/// 19 15.8
/// 20 17
/// \endcode
/// (Caution: we dont claim laboratory accuracy for these measurements)
/// You would not expect to get anywhere near these powers to air with a simple 1/4 wavelength wire antenna.
/// Caution: although the RFM69 appears to have a PC antenna on board, you will get much better power and range even
/// with just a 1/4 wave wire antenna.
///
/// \par Performance
///
/// Some simple speed performance tests have been conducted.
/// In general packet transmission rate will be limited by the modulation scheme.
/// Also, if your code does any slow operations like Serial printing it will also limit performance.
/// We disabled any printing in the tests below.
/// We tested with RH_RF69::GFSK_Rb250Fd250, which is probably the fastest scheme available.
/// We tested with a 13 octet message length, over a very short distance of 10cm.
///
/// Transmission (no reply) tests with modulation RH_RF69::GFSK_Rb250Fd250 and a
/// 13 octet message show about 152 messages per second transmitted and received.
///
/// Transmit-and-wait-for-a-reply tests with modulation RH_RF69::GFSK_Rb250Fd250 and a
/// 13 octet message (send and receive) show about 68 round trips per second.
///
class RH_RF69 : public RHSPIDriver
{
public:
/// \brief Defines register values for a set of modem configuration registers
///
/// Defines register values for a set of modem configuration registers
/// that can be passed to setModemRegisters() if none of the choices in
/// ModemConfigChoice suit your need setModemRegisters() writes the
/// register values from this structure to the appropriate RF69 registers
/// to set the desired modulation type, data rate and deviation/bandwidth.
typedef struct
{
uint8_t reg_02; ///< Value for register RH_RF69_REG_02_DATAMODUL
uint8_t reg_03; ///< Value for register RH_RF69_REG_03_BITRATEMSB
uint8_t reg_04; ///< Value for register RH_RF69_REG_04_BITRATELSB
uint8_t reg_05; ///< Value for register RH_RF69_REG_05_FDEVMSB
uint8_t reg_06; ///< Value for register RH_RF69_REG_06_FDEVLSB
uint8_t reg_19; ///< Value for register RH_RF69_REG_19_RXBW
uint8_t reg_1a; ///< Value for register RH_RF69_REG_1A_AFCBW
uint8_t reg_37; ///< Value for register RH_RF69_REG_37_PACKETCONFIG1
} ModemConfig;
/// Choices for setModemConfig() for a selected subset of common
/// modulation types, and data rates. If you need another configuration,
/// use the register calculator. and call setModemRegisters() with your
/// desired settings.
/// These are indexes into MODEM_CONFIG_TABLE. We strongly recommend you use these symbolic
/// definitions and not their integer equivalents: its possible that new values will be
/// introduced in later versions (though we will try to avoid it).
/// CAUTION: some of these configurations do not work corectly and are marked as such.
typedef enum
{
FSK_Rb2Fd5 = 0, ///< FSK, Whitening, Rb = 2kbs, Fd = 5kHz
FSK_Rb2_4Fd4_8, ///< FSK, Whitening, Rb = 2.4kbs, Fd = 4.8kHz
FSK_Rb4_8Fd9_6, ///< FSK, Whitening, Rb = 4.8kbs, Fd = 9.6kHz
FSK_Rb9_6Fd19_2, ///< FSK, Whitening, Rb = 9.6kbs, Fd = 19.2kHz
FSK_Rb19_2Fd38_4, ///< FSK, Whitening, Rb = 19.2kbs, Fd = 38.4kHz
FSK_Rb38_4Fd76_8, ///< FSK, Whitening, Rb = 38.4kbs, Fd = 76.8kHz
FSK_Rb57_6Fd120, ///< FSK, Whitening, Rb = 57.6kbs, Fd = 120kHz
FSK_Rb125Fd125, ///< FSK, Whitening, Rb = 125kbs, Fd = 125kHz
FSK_Rb250Fd250, ///< FSK, Whitening, Rb = 250kbs, Fd = 250kHz
FSK_Rb55555Fd50, ///< FSK, Whitening, Rb = 55555kbs,Fd = 50kHz for RFM69 lib compatibility
GFSK_Rb2Fd5, ///< GFSK, Whitening, Rb = 2kbs, Fd = 5kHz
GFSK_Rb2_4Fd4_8, ///< GFSK, Whitening, Rb = 2.4kbs, Fd = 4.8kHz
GFSK_Rb4_8Fd9_6, ///< GFSK, Whitening, Rb = 4.8kbs, Fd = 9.6kHz
GFSK_Rb9_6Fd19_2, ///< GFSK, Whitening, Rb = 9.6kbs, Fd = 19.2kHz
GFSK_Rb19_2Fd38_4, ///< GFSK, Whitening, Rb = 19.2kbs, Fd = 38.4kHz
GFSK_Rb38_4Fd76_8, ///< GFSK, Whitening, Rb = 38.4kbs, Fd = 76.8kHz
GFSK_Rb57_6Fd120, ///< GFSK, Whitening, Rb = 57.6kbs, Fd = 120kHz
GFSK_Rb125Fd125, ///< GFSK, Whitening, Rb = 125kbs, Fd = 125kHz
GFSK_Rb250Fd250, ///< GFSK, Whitening, Rb = 250kbs, Fd = 250kHz
GFSK_Rb55555Fd50, ///< GFSK, Whitening, Rb = 55555kbs,Fd = 50kHz
OOK_Rb1Bw1, ///< OOK, Whitening, Rb = 1kbs, Rx Bandwidth = 1kHz.
OOK_Rb1_2Bw75, ///< OOK, Whitening, Rb = 1.2kbs, Rx Bandwidth = 75kHz.
OOK_Rb2_4Bw4_8, ///< OOK, Whitening, Rb = 2.4kbs, Rx Bandwidth = 4.8kHz.
OOK_Rb4_8Bw9_6, ///< OOK, Whitening, Rb = 4.8kbs, Rx Bandwidth = 9.6kHz.
OOK_Rb9_6Bw19_2, ///< OOK, Whitening, Rb = 9.6kbs, Rx Bandwidth = 19.2kHz.
OOK_Rb19_2Bw38_4, ///< OOK, Whitening, Rb = 19.2kbs, Rx Bandwidth = 38.4kHz.
OOK_Rb32Bw64, ///< OOK, Whitening, Rb = 32kbs, Rx Bandwidth = 64kHz.
// Test,
} ModemConfigChoice;
/// Constructor. You can have multiple instances, but each instance must have its own
/// interrupt and slave select pin. After constructing, you must call init() to initialise the interface
/// and the radio module. A maximum of 3 instances can co-exist on one processor, provided there are sufficient
/// distinct interrupt lines, one for each instance.
/// \param[in] slaveSelectPin the Arduino pin number of the output to use to select the RF69 before
/// accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, D10 for Maple)
/// \param[in] interruptPin The interrupt Pin number that is connected to the RF69 DIO0 interrupt line.
/// Defaults to pin 2.
/// Caution: You must specify an interrupt capable pin.
/// On many Arduino boards, there are limitations as to which pins may be used as interrupts.
/// On Leonardo pins 0, 1, 2 or 3. On Mega2560 pins 2, 3, 18, 19, 20, 21. On Due and Teensy, any digital pin.
/// On other Arduinos pins 2 or 3.
/// See http://arduino.cc/en/Reference/attachInterrupt for more details.
/// On Chipkit Uno32, pins 38, 2, 7, 8, 35.
/// On other boards, any digital pin may be used.
/// \param[in] spi Pointer to the SPI interface object to use.
/// Defaults to the standard Arduino hardware SPI interface
RH_RF69(PINS slaveSelectPin, PINS interruptPin, RHGenericSPI& spi = hardware_spi);
/// Initialises this instance and the radio module connected to it.
/// The following steps are taken:
/// - Initialise the slave select pin and the SPI interface library
/// - Checks the connected RF69 module can be communicated
/// - Attaches an interrupt handler
/// - Configures the RF69 module
/// - Sets the frequency to 434.0 MHz
/// - Sets the modem data rate to FSK_Rb2Fd5
/// \return true if everything was successful
bool init();
/// Reads the on-chip temperature sensor.
/// The RF69 must be in Idle mode (= RF69 Standby) to measure temperature.
/// The measurement is uncalibrated and without calibration, you can expect it to be far from
/// correct.
/// \return The measured temperature, in degrees C from -40 to 85 (uncalibrated)
int8_t temperatureRead();
/// Sets the transmitter and receiver
/// centre frequency
/// \param[in] centre Frequency in MHz. 240.0 to 960.0. Caution, RF69 comes in several
/// different frequency ranges, and setting a frequency outside that range of your radio will probably not work
/// \param[in] afcPullInRange Not used
/// \return true if the selected frquency centre is within range
bool setFrequency(float centre, float afcPullInRange = 0.05);
/// Reads and returns the current RSSI value.
/// Causes the current signal strength to be measured and returned
/// If you want to find the RSSI
/// of the last received message, use lastRssi() instead.
/// \return The current RSSI value on units of 0.5dB.
int8_t rssiRead();
/// Sets the parameters for the RF69 OPMODE.
/// This is a low level device access function, and should not normally ned to be used by user code.
/// Instead can use stModeRx(), setModeTx(), setModeIdle()
/// \param[in] mode RF69 OPMODE to set, one of RH_RF69_OPMODE_MODE_*.
void setOpMode(uint8_t mode);
/// If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running,
/// disables them.
void setModeIdle();
/// If current mode is Tx or Idle, changes it to Rx.
/// Starts the receiver in the RF69.
void setModeRx();
/// If current mode is Rx or Idle, changes it to Rx. F
/// Starts the transmitter in the RF69.
void setModeTx();
/// Sets the transmitter power output level.
/// Be a good neighbour and set the lowest power level you need.
/// Caution: legal power limits may apply in certain countries.
/// After init(), the power will be set to 13dBm.
/// \param[in] power Transmitter power level in dBm. For RF69W, valid values are from -18 to +13
/// (higher power settings disable the transmitter).
/// For RF69HW, valid values are from +14 to +20. Caution: at +20dBm, duty cycle is limited to 1% and a
/// maximum VSWR of 3:1 at the antenna port.
void setTxPower(int8_t power);
/// Sets all the registers required to configure the data modem in the RF69, including the data rate,
/// bandwidths etc. You can use this to configure the modem with custom configurations if none of the
/// canned configurations in ModemConfigChoice suit you.
/// \param[in] config A ModemConfig structure containing values for the modem configuration registers.
void setModemRegisters(const ModemConfig* config);
/// Select one of the predefined modem configurations. If you need a modem configuration not provided
/// here, use setModemRegisters() with your own ModemConfig. The default after init() is RH_RF69::GFSK_Rb250Fd250.
/// \param[in] index The configuration choice.
/// \return true if index is a valid choice.
bool setModemConfig(ModemConfigChoice index);
/// Starts the receiver and checks whether a received message is available.
/// This can be called multiple times in a timeout loop
/// \return true if a complete, valid message has been received and is able to be retrieved by
/// recv()
bool available();
/// Turns the receiver on if it not already on.
/// If there is a valid message available, copy it to buf and return true
/// else return false.
/// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
/// You should be sure to call this function frequently enough to not miss any messages
/// It is recommended that you call it in your main loop.
/// \param[in] buf Location to copy the received message
/// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
/// \return true if a valid message was copied to buf
bool recv(uint8_t* buf, uint8_t* len);
/// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
/// Then loads a message into the transmitter and starts the transmitter. Note that a message length
/// of 0 is NOT permitted.
/// \param[in] data Array of data to be sent
/// \param[in] len Number of bytes of data to send (> 0)
/// \return true if the message length was valid and it was correctly queued for transmit
bool send(const uint8_t* data, uint8_t len);
/// Sets the length of the preamble
/// in bytes.
/// Caution: this should be set to the same
/// value on all nodes in your network. Default is 4.
/// Sets the message preamble length in REG_0?_PREAMBLE?SB
/// \param[in] bytes Preamble length in bytes.
void setPreambleLength(uint16_t bytes);
/// Sets the sync words for transmit and receive
/// Caution: SyncWords should be set to the same
/// value on all nodes in your network. Nodes with different SyncWords set will never receive
/// each others messages, so different SyncWords can be used to isolate different
/// networks from each other. Default is { 0x2d, 0xd4 }.
/// \param[in] syncWords Array of sync words, 1 to 4 octets long. NULL if no sync words to be used.
/// \param[in] len Number of sync words to set, 1 to 4. 0 if no sync words to be used.
void setSyncWords(const uint8_t* syncWords = NULL, uint8_t len = 0);
/// Enables AES encryption and sets the AES encryption key, used
/// to encrypt and decrypt all messages. The default is disabled.
/// \param[in] key The key to use. Must be 16 bytes long. The same key must be installed
/// in other instances of RF69, otherwise communications will not work correctly. If key is NULL,
/// encryption is disabled.
void setEncryptionKey(uint8_t* key = NULL);
/// Returns the time in millis since the most recent preamble was received, and when the most recent
/// RSSI measurement was made.
uint32_t getLastPreambleTime();
/// The maximum message length supported by this driver
/// \return The maximum message length supported by this driver
uint8_t maxMessageLength();
/// Prints the value of a single register
/// to the Serial device if RH_HAVE_SERIAL is defined for the current platform
/// For debugging/testing only
/// \return true if successful
bool printRegister(uint8_t reg);
/// Prints the value of all the RF69 registers
/// to the Serial device if RH_HAVE_SERIAL is defined for the current platform
/// For debugging/testing only
/// \return true if successful
bool printRegisters();
/// Sets the radio operating mode for the case when the driver is idle (ie not
/// transmitting or receiving), allowing you to control the idle mode power requirements
/// at the expense of slower transitions to transmit and receive modes.
/// By default, the idle mode is RH_RF69_OPMODE_MODE_STDBY,
/// but eg setIdleMode(RH_RF69_OPMODE_MODE_SLEEP) will provide a much lower
/// idle current but slower transitions. Call this function after init().
/// \param[in] idleMode The chip operating mode to use when the driver is idle. One of RH_RF69_OPMODE_*
void setIdleMode(uint8_t idleMode);
/// Sets the radio into low-power sleep mode.
/// If successful, the transport will stay in sleep mode until woken by
/// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
/// Caution: there is a time penalty as the radio takes a finite time to wake from sleep mode.
/// \return true if sleep mode was successfully entered.
virtual bool sleep();
protected:
/// This is a low level function to handle the interrupts for one instance of RF69.
/// Called automatically by isr*()
/// Should not need to be called by user code.
void handleInterrupt();
/// Low level function to read the FIFO and put the received data into the receive buffer
/// Should not need to be called by user code.
void readFifo();
protected:
/// Low level interrupt service routine for RF69 connected to interrupt 0
static void isr0();
/// Low level interrupt service routine for RF69 connected to interrupt 1
static void isr1();
/// Low level interrupt service routine for RF69 connected to interrupt 1
static void isr2();
/// Array of instances connected to interrupts 0 and 1
static RH_RF69* _deviceForInterrupt[];
/// Index of next interrupt number to use in _deviceForInterrupt
static uint8_t _interruptCount;
#if (RH_PLATFORM == RH_PLATFORM_MBED)
/// The configured interrupt pin connected to this instance
InterruptIn _interruptPin;
#else
/// The configured interrupt pin connected to this instance
uint8_t _interruptPin;
#endif
/// The index into _deviceForInterrupt[] for this device (if an interrupt is already allocated)
/// else 0xff
uint8_t _myInterruptIndex;
/// The radio OP mode to use when mode is RHModeIdle
uint8_t _idleMode;
/// The reported device type
uint8_t _deviceType;
/// The selected output power in dBm
int8_t _power;
/// The message length in _buf
volatile uint8_t _bufLen;
/// Array of octets of teh last received message or the next to transmit message
uint8_t _buf[RH_RF69_MAX_MESSAGE_LEN];
/// True when there is a valid message in the Rx buffer
volatile bool _rxBufValid;
/// Time in millis since the last preamble was received (and the last time the RSSI was measured)
uint32_t _lastPreambleTime;
};
/// @example rf69_client.pde
/// @example rf69_server.pde
/// @example rf69_reliable_datagram_client.pde
/// @example rf69_reliable_datagram_server.pde
#endif