Driver to send and receive unaddressed, unreliable datagrams via an RF24 and compatible radio transceiver. More...

#include <RH_RF24.h>

Inheritance diagram for RH_RF24:

Classes
struct	CommandInfo
	Defines the commands we can interrogate in printRegisters. More...

struct	ModemConfig
	Defines property values for a set of modem configuration registers. More...

Public Types
enum	ModemConfigChoice { FSK_Rb0_5Fd1 = 0 , FSK_Rb5Fd10 , FSK_Rb50Fd100 , FSK_Rb150Fd300 , GFSK_Rb0_5Fd1 , GFSK_Rb5Fd10 , GFSK_Rb50Fd100 , GFSK_Rb150Fd300 , OOK_Rb5Bw30 , OOK_Rb10Bw40 }

enum	CRCPolynomial { CRC_NONE = 0 , CRC_ITU_T , CRC_IEC_16 , CRC_Biacheva , CRC_16_IBM , CRC_CCITT , CRC_Koopman , CRC_IEEE_802_3 , CRC_Castagnoli }
	Defines the available choices for CRC Types of permitted CRC polynomials, to be passed to setCRCPolynomial() They deliberately have the same numeric values as the CRC_POLYNOMIAL field of PKT_CRC_CONFIG.

Public Types inherited from RHGenericDriver
enum	RHMode { RHModeInitialising = 0 , RHModeSleep , RHModeIdle , RHModeTx , RHModeRx , RHModeCad }
	Defines different operating modes for the transport hardware. More...

Public Member Functions
	RH_RF24 (uint8_t slaveSelectPin=SS, uint8_t interruptPin=2, uint8_t sdnPin=9, RHGenericSPI &spi=hardware_spi)

bool	init ()

void	setIdleMode (uint8_t idleMode)

bool	setFrequency (float centre, float afcPullInRange=0.05)

void	setModemRegisters (const ModemConfig *config)

bool	setModemConfig (ModemConfigChoice index)

bool	available ()

bool	recv (uint8_t buf, uint8_t len)

bool	send (const uint8_t *data, uint8_t len)

uint8_t	maxMessageLength ()

void	setPreambleLength (uint16_t bytes)

void	setSyncWords (const uint8_t *syncWords=NULL, uint8_t len=0)

bool	setCRCPolynomial (CRCPolynomial polynomial)

void	setModeIdle ()

void	setModeRx ()

void	setModeTx ()

void	setTxPower (uint8_t power)

bool	printRegisters ()

bool	command (uint8_t cmd, const uint8_t write_buf=0, uint8_t write_len=0, uint8_t read_buf=0, uint8_t read_len=0)

bool	set_properties (uint16_t firstProperty, const uint8_t *values, uint8_t count)

bool	get_properties (uint16_t firstProperty, uint8_t *values, uint8_t count)

float	get_temperature ()

float	get_battery_voltage ()

float	get_gpio_voltage (uint8_t gpio)

uint8_t	frr_read (uint8_t reg)

virtual bool	sleep ()

uint16_t	deviceType ()

Public Member Functions inherited from RHSPIDriver
	RHSPIDriver (uint8_t slaveSelectPin=SS, RHGenericSPI &spi=hardware_spi)

bool	init ()

uint8_t	spiRead (uint8_t reg)

uint8_t	spiWrite (uint8_t reg, uint8_t val)

uint8_t	spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len)

uint8_t	spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len)

void	setSlaveSelectPin (uint8_t slaveSelectPin)

void	spiUsingInterrupt (uint8_t interruptNumber)

Public Member Functions inherited from RHGenericDriver
	RHGenericDriver ()
	Constructor.

virtual	~RHGenericDriver ()
	Generic destructor to prevent warnings when objects are dynamically allocated.

virtual bool	init ()

virtual bool	available ()=0

virtual bool	recv (uint8_t buf, uint8_t len)=0

virtual bool	send (const uint8_t *data, uint8_t len)=0

virtual uint8_t	maxMessageLength ()=0

virtual void	waitAvailable (uint16_t polldelay=0)

virtual bool	waitPacketSent ()

virtual bool	waitPacketSent (uint16_t timeout)

virtual bool	waitAvailableTimeout (uint16_t timeout, uint16_t polldelay=0)

virtual bool	waitCAD ()

void	setCADTimeout (unsigned long cad_timeout)

virtual bool	isChannelActive ()

virtual void	setThisAddress (uint8_t thisAddress)

virtual void	setHeaderTo (uint8_t to)

virtual void	setHeaderFrom (uint8_t from)

virtual void	setHeaderId (uint8_t id)

virtual void	setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC)

virtual void	setPromiscuous (bool promiscuous)

virtual uint8_t	headerTo ()

virtual uint8_t	headerFrom ()

virtual uint8_t	headerId ()

virtual uint8_t	headerFlags ()

virtual int16_t	lastRssi ()

virtual RHMode	mode ()

virtual void	setMode (RHMode mode)
	Sets the operating mode of the transport. More...

virtual bool	sleep ()

virtual uint16_t	rxBad ()

virtual uint16_t	rxGood ()

virtual uint16_t	txGood ()

Protected Member Functions
void	handleInterrupt ()

bool	clearRxFifo ()

void	clearBuffer ()
	Clears RH_RF24's internal TX and RX buffers and counters.

void	sendNextFragment ()

void	readNextFragment ()

bool	writeTxFifo (uint8_t *data, uint8_t len)

void	validateRxBuf ()

void	power_on_reset ()
	Cycles the Shutdown pin to force the cradio chip to reset.

bool	configure (const uint8_t *commands)

bool	cmd_clear_all_interrupts ()
	Clears all pending interrutps in the radio chip.

Protected Member Functions inherited from RHSPIDriver
virtual void	beginTransaction ()

virtual void	endTransaction ()

virtual void	selectSlave ()

virtual void	deselectSlave ()

Additional Inherited Members
Static Public Member Functions inherited from RHGenericDriver
static void	printBuffer (const char prompt, const uint8_t buf, uint8_t len)

Protected Attributes inherited from RHSPIDriver
RHGenericSPI &	_spi
	Reference to the RHGenericSPI instance to use to transfer data with the SPI device.

uint8_t	_slaveSelectPin
	The pin number of the Slave Select pin that is used to select the desired device.

Protected Attributes inherited from RHGenericDriver
volatile RHMode	_mode
	The current transport operating mode.

uint8_t	_thisAddress
	This node id.

bool	_promiscuous
	Whether the transport is in promiscuous mode.

volatile uint8_t	_rxHeaderTo
	TO header in the last received mesasge.

volatile uint8_t	_rxHeaderFrom
	FROM header in the last received mesasge.

volatile uint8_t	_rxHeaderId
	ID header in the last received mesasge.

volatile uint8_t	_rxHeaderFlags
	FLAGS header in the last received mesasge.

uint8_t	_txHeaderTo
	TO header to send in all messages.

uint8_t	_txHeaderFrom
	FROM header to send in all messages.

uint8_t	_txHeaderId
	ID header to send in all messages.

uint8_t	_txHeaderFlags
	FLAGS header to send in all messages.

volatile int16_t	_lastRssi
	The value of the last received RSSI value, in some transport specific units.

volatile uint16_t	_rxBad
	Count of the number of bad messages (eg bad checksum etc) received.

volatile uint16_t	_rxGood
	Count of the number of successfully transmitted messaged.

volatile uint16_t	_txGood
	Count of the number of bad messages (correct checksum etc) received.

volatile bool	_cad
	Channel activity detected.

unsigned int	_cad_timeout
	Channel activity timeout in ms.

Detailed Description

Driver to send and receive unaddressed, unreliable datagrams via an RF24 and compatible radio transceiver.

Works with

Silicon Labs Si4460/1/2/3/4 transceiver chips
The equivalent HopeRF RF24/25/26/27 transceiver chips
HopeRF Complete modules: RFM24W/26W/27W

Overview

This class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 250 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 RF24 and compatible radio modules, such as the RFM24W module.

The Hope-RF (http://www.hoperf.com) RF24 family is a low-cost ISM transceiver chip. It supports FSK, GFSK, OOK over a wide range of frequencies and programmable data rates. HopeRF also sell these chips on modules which includes a crystal and antenna coupling circuits: RFM24W, RFM26W and RFM27W

This Driver provides functions for sending and receiving messages of up to 250 octets on any frequency supported by the RF24, in a range of predefined data rates and frequency deviations. Frequency can be set to any frequency from 142.0MHz to 1050.0MHz. Caution: most modules only support a more limited range of frequencies due to antenna tuning.

Up to 2 RFM24 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:

OOK On-Off Keying
GFSK Gaussian Frequency Shift Keying
FSK Frequency Shift Keying

Support for other RF24 features such as on-chip temperature measurement, transmitter power control etc is also provided.

RH_RF24 uses interrupts to detect and handle events in the radio chip. The RF24 family has TX and RX FIFOs of 64 bytes, but through the use of interrupt, the RH_RF24 driver can send longer messages by filling or emptying the FIFOs on-the-fly.

Tested on Anarduino Mini http://www.anarduino.com/mini/ with arduino-1.0.5 on OpenSuSE 13.1. Also on Anarduino Mini with arduino-1.8.1 on Kubuntu 16.04

Packet Format

All messages sent and received by this RH_RF24 Driver conform to this packet format:

4 octets PREAMBLE (configurable)
2 octets SYNC 0x2d, 0xd4 (configurable, so you can use this as a network filter)
Field containing 1 octet of message length and 2 octet CRC protecting this field
Field 2 containing at least 4 octets, and 2 octet CRC protecting this field:
- 4 octets HEADER: (TO, FROM, ID, FLAGS)
- 0 to 250 octets DATA
- 2 octets CRC, computed on HEADER and DATA

Connecting RFM-24 to Arduino

For RFM24/RFM26 and Teensy 3.1 or Anarduino Mini

                Teensy      RFM-24/RFM26
                GND----------GND (ground in)
                3V3----------VCC   (3.3V in)
interrupt 2 pin D2-----------NIRQ  (interrupt request out)
         SS pin D10----------NSEL  (chip select in)
        SCK pin D13----------SCK   (SPI clock in)
       MOSI pin D11----------SDI   (SPI Data in)
       MISO pin D12----------SDO   (SPI data out)
                D9-----------SDN   (shutdown in)
                          /--GPIO0 (GPIO0 out to control transmitter antenna TX_ANT)
                          \--TX_ANT (TX antenna control in) RFM22B only
                          /--GPIO1 (GPIO1 out to control receiver antenna RX_ANT)
                          \--RX_ANT (RX antenna control in) RFM22B only

Caution: tying the radio SDN pin to ground (though it might appear from the data sheets to make sense) does not always produce a reliable radio startup. So this driver controls the SDN pin directly. Note: the GPIO0-TX_ANT and GPIO1-RX_ANT connections are not required for the 11dBm RFM24W, which has no antenna switch.

If you have an Arduino Zero, you should note that you cannot use Pin 2 for the interrupt line (Pin 2 is for the NMI only), instead you can use any other pin (we use Pin 3) and initialise RH_RF69 like this:

// Slave Select is pin 10, interrupt is Pin 3

RH_RF24 driver(10, 3);

RH_RF24

Driver to send and receive unaddressed, unreliable datagrams via an RF24 and compatible radio transce...

Definition: RH_RF24.h:686

Customising and configuring

The RH_RF24 module uses a radio configuration header file to configure the basic radio operation frequency and modulation scheme. The radio configuration header file must be generated with the Silicon Labs Wireless Development Suite (WDS) program and #included by RH_RF24.cpp

The library will work out of the box and without further configuring with these parameters:

Si4464 or equvalent
30MHz Crytstal
434MHz base frequncy band
2GFSK modulation
5kbps data rate
10kHz deviation using the radio configuration header file RF24configs/radio_config_Si4464_30_434_2GFSK_5_10.h which is included in RadioHead.

In order to use different frequency bands or modulation schemes, you must generate a new radio configuration header file with WDS, or select one of a small set of prebuilt headers from the RF24configs folder (see README in that folder for details of the filename format).

To generate a new header file:

Install Silicon Labs Wireless Development Suite (WDS) 3.2.11.0 or later (Windows only, we were not able to get it to run under Wine on Linux)
Run WDS
Menu->Start Simulation
Select radio chip type Si4464, press Select Radio
Select Radio Configuration Application, press Select Application
Click on Standard Packet Tx
On the Frequency and Power tab, Select the Frequency, crystal frequency etc. The PA power level is irrelevant, since power is set programatically
On the RF parameters tab, select the modulation type and rates
Press Generate Source, Save custom radio configuration header file
Enter a new unique file name in the RF24configs folder in RadioHead
Edit RH_RF24.cpp to use this new header file
Recompile RH_RF24

RSSI

The RSSI (Received Signal Strength Indicator) is measured and latched after the message sync bytes are received. The latched RSSI is available from the lastRssi() member functionafter the complete message is received. Although lastRssi() supposedly returns a signed integer, in the case of this radio it actually returns an unsigned 8 bit integer (uint8_t) and you will have to cast the return value to use it:

uint8_t lastRssi = (uint8_t)rf24.lastRssi();

RHGenericDriver::lastRssi

virtual int16_t lastRssi()

Definition: RHGenericDriver.cpp:160

The units of RSSI are arbitrary and relative, with larger unsigned numbers indicating a stronger signal. Values up to 255 are seen with radios in close proximity to each other. Lower limit of receivable strength is about 70.

Transmitter Power

You can control the transmitter power on the RF24/25/26/27 transceiver with the RH_RF24::setTxPower() function. The argument can be any of 0x00 to 0x4f (for RFM24/Si4460) or 0x00 to 0x7f (for others) 0x00 will yield no measurable power. For other settings there is a non-linear correlation with actual RF power output (see below) The default is 0x10. Eg:

driver.setTxPower(0x10);

We have made some actual power measurements against programmed power

Anarduino Mini with RFM24-433 and RFM26-433 at Vcc = 3.3V, in CW mode, 434MHz
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)
Digitech QM-1460 digital multimeter
Program power Measured Power dBm

HEX RFM24 RFM26

0x00 not measurable not measurable

0x01 -20.4 -20.6

0x0f 2.4 4.8

0x1f 9.4 11.0

0x2f 11.2 14.2

0x3f 11.6 16.4

0x4f 11.6 18.0

0x5f 18.6

0x6f 19.0

0x7f 19.2

Caution: the actual radiated power output will depend heavily on the power supply voltage and the antenna.

Member Enumeration Documentation

◆ ModemConfigChoice

enum RH_RF24::ModemConfigChoice

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 values will be changed in later versions (though we will try to avoid it). Contributions of new complete and tested ModemConfigs ready to add to this list will be readily accepted. OBSOLETE: no need ever to use this now

Enumerator
FSK_Rb0_5Fd1	FSK Rb = 0.5kbs, Fd = 1kHz.
FSK_Rb5Fd10	FSK Rb = 5kbs, Fd = 10kHz.
FSK_Rb50Fd100	FSK Rb = 50kbs, Fd = 100kHz.
FSK_Rb150Fd300	FSK Rb = 50kbs, Fd = 100kHz.
GFSK_Rb0_5Fd1	GFSK Rb = 0.5kbs, Fd = 1kHz.
GFSK_Rb5Fd10	GFSK Rb = 5kbs, Fd = 10kHz.
GFSK_Rb50Fd100	GFSK Rb = 50kbs, Fd = 100kHz.
GFSK_Rb150Fd300	GFSK Rb = 150kbs, Fd = 300kHz.
OOK_Rb5Bw30	OOK Rb = 5kbs, Bw = 30kHz.
OOK_Rb10Bw40	OOK Rb = 10kbs, Bw = 40kHz.

Constructor & Destructor Documentation

◆ RH_RF24()

RH_RF24::RH_RF24	(	uint8_t	slaveSelectPin = `SS`,
		uint8_t	interruptPin = `2`,
		uint8_t	sdnPin = `9`,
		RHGenericSPI &	spi = `hardware_spi`
	)

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.

Parameters

[in]	slaveSelectPin	the Arduino pin number of the output to use to select the RF24 before accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, D10 for Maple)
[in]	interruptPin	The interrupt Pin number that is connected to the RF24 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.
[in]	sdnPin	The pin number connected to SDN on the radio. Defaults to pin 9. Connecting SDN directly to ground does not aloways provide reliable radio startup.
[in]	spi	Pointer to the SPI interface object to use. Defaults to the standard Arduino hardware SPI interface

Member Function Documentation

◆ available()

bool RH_RF24::available ( )

virtual

Starts the receiver and checks whether a received message is available. This can be called multiple times in a timeout loop

Returns: true if a complete, valid message has been received and is able to be retrieved by recv()

Implements RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::RHModeTx, and setModeRx().

Referenced by recv().

◆ clearRxFifo()

bool RH_RF24::clearRxFifo ( )

protected

Clears the chips RX FIFO

Returns: true if successful

References command().

Referenced by handleInterrupt(), and readNextFragment().

◆ command()

bool RH_RF24::command	(	uint8_t	cmd,
		const uint8_t *	write_buf = `0`,
		uint8_t	write_len = `0`,
		uint8_t *	read_buf = `0`,
		uint8_t	read_len = `0`
	)

Send a string of command bytes to the chip and get a string of reply bytes Different RFM24 commands take different numbers of command bytes and send back different numbers of reply bytes. See the Si446x documentaiton for more details. Both command bytes and reply bytes are optional

Parameters

[in]	cmd	The command number. One of RH_RF24_CMD_*
[in]	write_buf	Pointer to write_len bytes of command input bytes to send. If there are none, set to NULL.
[in]	write_len	The number of bytes to send from write_buf. If there are none, set to 0
[out]	read_buf	Pointer to read_len bytes of storage where the reply stream from the comand will be written. If none are required, set to NULL
[in]	read_len	The number of bytes to read from the reply stream. If none required, set to 0.

Returns: true if the command succeeeded.

References RHSPIDriver::_slaveSelectPin, RHSPIDriver::_spi, RHGenericSPI::beginTransaction(), RHGenericSPI::endTransaction(), and RHGenericSPI::transfer().

Referenced by clearRxFifo(), cmd_clear_all_interrupts(), configure(), get_battery_voltage(), get_gpio_voltage(), get_properties(), get_temperature(), handleInterrupt(), init(), printRegisters(), readNextFragment(), sendNextFragment(), set_properties(), setModeIdle(), setModeRx(), setModeTx(), and sleep().

◆ configure()

bool RH_RF24::configure ( const uint8_t * commands )

protected

Sets registers, commands and properties in the ratio according to the data in the commands array

Parameters

[in] commands Array of data containing radio commands in the format provided by radio_config_Si4460.h

Returns: true if successful

References command().

Referenced by init().

◆ deviceType()

uint16_t RH_RF24::deviceType ( )

inline

Return the integer value of the device type as read from the device in from RH_RF24_CMD_PART_INFO. One of 0x4460, 0x4461, 0x4462 or 0x4463, depending on the type of device actually connected.

Returns: The integer device type

◆ frr_read()

uint8_t RH_RF24::frr_read ( uint8_t reg )

Read one of the Fast Read Response registers. The Fast Read Response register must be previously configured with the matching RH_RF24_PROPERTY_FRR_CTL_?_MODE property to select what chip property will be available in that register.

Parameters

[in] reg The index of the FRR register to read. 0 means FRR A, 1 means B etc.

Returns: the value read from the specified Fast Read Response register.

References RHSPIDriver::_slaveSelectPin, RHSPIDriver::_spi, RHGenericSPI::beginTransaction(), RHGenericSPI::endTransaction(), and RHGenericSPI::transfer().

◆ get_battery_voltage()

float RH_RF24::get_battery_voltage ( )

Measures and returns the current Chip Vcc supply voltage.

Returns: The current chip Vcc supply voltage in Volts.

References command().

◆ get_gpio_voltage()

float RH_RF24::get_gpio_voltage ( uint8_t gpio )

Measures and returns the current voltage applied to a GPIO pin (which has previously been configured as a voltage input)

Parameters

[in] gpio The GPIO pin to read. 0 to 3.

Returns: The current pin voltage in Volts.

References command().

◆ get_properties()

bool RH_RF24::get_properties	(	uint16_t	firstProperty,
		uint8_t *	values,
		uint8_t	count
	)

Get one or more chip properties using the RH_RF24_CMD_GET_PROPERTY command. See the Si446x API Description AN625 for details on what properties are available. param[in] firstProperty The property number of the first property to get. The first value in the values array will be set with this property, and any subsequent values will be set from the following properties. One of RH_RF24_PROPERTY_* param[out] values Array of 0 or more values to receive the firstProperty and subsequent proerties param[in] count The number of values in the values array

Returns: true if the command succeeeded.

References command().

Referenced by printRegisters().

◆ get_temperature()

float RH_RF24::get_temperature ( )

Measures and returns the current Chip temperature.

Returns: The current chip temperature in degrees Centigrade

References command().

◆ handleInterrupt()

void RH_RF24::handleInterrupt ( )

protected

This is a low level function to handle the interrupts for one instance of RF24. Called automatically by isr*() Should not need to be called by user code.

References RHGenericDriver::_lastRssi, RHGenericDriver::_mode, RHGenericDriver::_rxBad, RHGenericDriver::_txGood, clearBuffer(), clearRxFifo(), command(), readNextFragment(), RHGenericDriver::RHModeIdle, sendNextFragment(), and validateRxBuf().

◆ init()

bool RH_RF24::init ( )

virtual

Initialises this instance and the radio module connected to it. The following steps are taken:

Initialise the slave select and shutdown pins and the SPI interface library
Checks the connected RF24 module can be communicated
Attaches an interrupt handler
Configures the RF24 module
Sets the frequency to 434.0 MHz
Sets the modem data rate to GFSK_Rb5Fd10
Sets the tranmitter power level to 16 (about 2.4dBm on RFM4)
Returns
true if everything was successful

Reimplemented from RHGenericDriver.

References cmd_clear_all_interrupts(), command(), configure(), RHSPIDriver::init(), power_on_reset(), set_properties(), setCRCPolynomial(), setPreambleLength(), setSyncWords(), setTxPower(), and RHSPIDriver::spiUsingInterrupt().

◆ maxMessageLength()

uint8_t RH_RF24::maxMessageLength ( )

virtual

The maximum message length supported by this driver

Returns: The maximum message length supported by this driver

Implements RHGenericDriver.

◆ printRegisters()

bool RH_RF24::printRegisters ( )

Dump the values of available command replies and properties to the Serial device if RH_HAVE_SERIAL is defined for the current platform Not all commands have valid replies, therefore they are not all printed. Caution: the list is very long

References RH_RF24::CommandInfo::cmd, command(), get_properties(), and RH_RF24::CommandInfo::replyLen.

◆ readNextFragment()

void RH_RF24::readNextFragment ( )

protected

Copies the next part of the currenrtly received message from the chips RX FIFO to the receive buffer

References RHGenericDriver::_rxBad, RHSPIDriver::_slaveSelectPin, RHSPIDriver::_spi, RHGenericSPI::beginTransaction(), clearBuffer(), clearRxFifo(), command(), RHGenericSPI::endTransaction(), setModeIdle(), and RHGenericSPI::transfer().

Referenced by handleInterrupt().

◆ recv()

bool RH_RF24::recv	(	uint8_t *	buf,
		uint8_t *	len
	)

virtual

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.

Parameters

[in]	buf	Location to copy the received message
[in,out]	len	Pointer to the number of octets available in buf. The number be reset to the actual number of octets copied.

Returns: true if a valid message was copied to buf

Implements RHGenericDriver.

References available(), and clearBuffer().

◆ send()

bool RH_RF24::send	(	const uint8_t *	data,
		uint8_t	len
	)

virtual

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.

Parameters

[in]	data	Array of data to be sent
[in]	len	Number of bytes of data to send (> 0)

Returns: true if the message length was valid and it was correctly queued for transmit

Implements RHGenericDriver.

References RHGenericDriver::_txHeaderFlags, RHGenericDriver::_txHeaderFrom, RHGenericDriver::_txHeaderId, RHGenericDriver::_txHeaderTo, sendNextFragment(), set_properties(), setModeIdle(), setModeTx(), RHGenericDriver::waitCAD(), and RHGenericDriver::waitPacketSent().

◆ sendNextFragment()

void RH_RF24::sendNextFragment ( )

protected

Loads the next part of the currently transmitting message into the chips TX buffer

References command(), and writeTxFifo().

Referenced by handleInterrupt(), and send().

◆ set_properties()

bool RH_RF24::set_properties	(	uint16_t	firstProperty,
		const uint8_t *	values,
		uint8_t	count
	)

Set one or more chip properties using the RH_RF24_CMD_SET_PROPERTY command. See the Si446x API Description AN625 for details on what properties are available. param[in] firstProperty The property number of the first property to set. The first value in the values array will be used to set this property, and any subsequent values will be used to set the following properties. One of RH_RF24_PROPERTY_* param[in] values Array of 0 or more values to write the firstProperty and subsequent proerties param[in] count The number of values in the values array

Returns: true if the command succeeeded.

References command().

Referenced by init(), send(), setCRCPolynomial(), setFrequency(), setModeRx(), setPreambleLength(), setSyncWords(), and setTxPower().

◆ setCRCPolynomial()

bool RH_RF24::setCRCPolynomial ( CRCPolynomial polynomial )

Sets the CRC polynomial to be used to generate the CRC for both receive and transmit otherwise the default of CRC_16_IBM will be used.

Parameters

[in] polynomial One of RH_RF24::CRCPolynomial choices CRC_*

Returns: true if polynomial is a valid option for this radio.

References set_properties().

Referenced by init().

◆ setFrequency()

bool RH_RF24::setFrequency	(	float	centre,
		float	afcPullInRange = `0.05`
	)

Sets the transmitter and receiver centre frequency. Valid frequency ranges for RFM24/Si4460, Si4461, RFM25/Si4463 are: 142MHz to 175Mhz, 284MHz to 350MHz, 425MHz to 525MHz, 850MHz to 1050MHz. Valid frequency ranges for RFM26/Si4464 are: 119MHz to 960MHz. Caution: RFM modules are designed with antenna coupling components to suit a limited band of frequencies (marked underneath the module). It is possible to set frequencies in other bands, but you may only get little or no power radiated. Caution, you can only use this function to change frequency within the frequency band configured by the radio configuration header file. To use a frequency in a different band, you must recompile with the appropriate radio configuration header file. Setting a frequency in anotehr band will have unpredicatble results.

Parameters

[in]	centre	Frequency in MHz.
[in]	afcPullInRange	Not used

Returns: true if the selected frequency is within a valid range for the connected radio and if setting the new frequency succeeded.

References set_properties().

◆ setIdleMode()

void RH_RF24::setIdleMode ( uint8_t idleMode )

Sets the chip mode that will be used when the RH_RF24 driver is idle (ie not transmitting or receiving) You can use this to control the power level consumed while idle, at the cost of slower transition to tranmit or receive states

Parameters

[in] idleMode The chip state to use when idle. Sensible choices might be RH_RF24_DEVICE_STATE_SLEEP or RH_RF24_DEVICE_STATE_READY

◆ setModeIdle()

void RH_RF24::setModeIdle ( )

If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running, disables them.

References RHGenericDriver::_mode, command(), and RHGenericDriver::RHModeIdle.

Referenced by readNextFragment(), and send().

◆ setModemConfig()

bool RH_RF24::setModemConfig ( ModemConfigChoice index )

OBSOLETE, do not use. To get different modulation schemes, you must generate a new radio config file as described in this documentation. 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_RF24::GFSK_Rb5Fd10.

Parameters

[in] index The configuration choice.

Returns: true if index is a valid choice.

◆ setModemRegisters()

void RH_RF24::setModemRegisters ( const ModemConfig * config )

OBSOLETE, do not use. To get different modulation schemes, you must generate a new radio config file as described in this documentation. Sets all the properties required to configure the data modem in the RF24, 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.

Parameters

[in] config A ModemConfig structure containing values for the modem configuration registers.

◆ setModeRx()

void RH_RF24::setModeRx ( )

If current mode is Tx or Idle, changes it to Rx. Starts the receiver in the RF24.

References RHGenericDriver::_mode, command(), RHGenericDriver::RHModeRx, and set_properties().

Referenced by available().

◆ setModeTx()

void RH_RF24::setModeTx ( )

If current mode is Rx or Idle, changes it to Rx. F Starts the transmitter in the RF24.

References RHGenericDriver::_mode, command(), and RHGenericDriver::RHModeTx.

Referenced by send().

◆ setPreambleLength()

void RH_RF24::setPreambleLength ( uint16_t bytes )

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.

Parameters

[in] bytes Preamble length in bytes.

References set_properties().

Referenced by init().

◆ setSyncWords()

void RH_RF24::setSyncWords	(	const uint8_t *	syncWords = `NULL`,
		uint8_t	len = `0`
	)

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 }.

Parameters

[in]	syncWords	Array of sync words, 1 to 4 octets long. NULL if no sync words to be used.
[in]	len	Number of sync words to set, 1 to 4. 0 if no sync words to be used.

References set_properties().

Referenced by init().

◆ setTxPower()

void RH_RF24::setTxPower ( uint8_t power )

Sets the transmitter power output level register PA_PWR_LVL The power argument to this function has a non-linear correlation with the actual RF power output. See the transmitter power table above for some examples. Also the Si446x Data Sheet section 5.4.2 may be helpful. 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 0x10.

Parameters

[in] power Transmitter power level. For RFM24/Si4460, valid values are 0x00 to 0x4f. For others, 0x00 to 0x7f

References set_properties().

Referenced by init().

◆ sleep()

bool RH_RF24::sleep ( )

virtual

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 finte time to wake from sleep mode.

Returns: true if sleep mode was successfully entered.

Reimplemented from RHGenericDriver.

References RHGenericDriver::_mode, command(), and RHGenericDriver::RHModeSleep.

◆ validateRxBuf()

void RH_RF24::validateRxBuf ( )

protected

Checks the contents of the RX buffer. If it contans a valid message adressed to this node sets _rxBufValid.

References RHGenericDriver::_promiscuous, RHGenericDriver::_rxGood, RHGenericDriver::_rxHeaderFlags, RHGenericDriver::_rxHeaderFrom, RHGenericDriver::_rxHeaderId, RHGenericDriver::_rxHeaderTo, and RHGenericDriver::_thisAddress.

Referenced by handleInterrupt().

◆ writeTxFifo()

bool RH_RF24::writeTxFifo	(	uint8_t *	data,
		uint8_t	len
	)

protected

Loads data into the chips TX FIFO

Parameters

[in]	data	Array of data bytes to be loaded
[in]	len	Number of bytes in data to be loaded

Returns: true if successful

References RHSPIDriver::_slaveSelectPin, RHSPIDriver::_spi, RHGenericSPI::beginTransaction(), RHGenericSPI::endTransaction(), and RHGenericSPI::transfer().

Referenced by sendNextFragment().

The documentation for this class was generated from the following files:

RH_RF24.h
RH_RF24.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ModemConfigChoice

Constructor & Destructor Documentation

◆ RH_RF24()

Member Function Documentation

◆ available()

◆ clearRxFifo()

◆ command()

◆ configure()

◆ deviceType()

◆ frr_read()

◆ get_battery_voltage()

◆ get_gpio_voltage()

◆ get_properties()

◆ get_temperature()

◆ handleInterrupt()

◆ init()

◆ maxMessageLength()

◆ printRegisters()

◆ readNextFragment()

◆ recv()

◆ send()

◆ sendNextFragment()

◆ set_properties()

◆ setCRCPolynomial()

◆ setFrequency()

◆ setIdleMode()

◆ setModeIdle()

◆ setModemConfig()

◆ setModemRegisters()

◆ setModeRx()

◆ setModeTx()

◆ setPreambleLength()

◆ setSyncWords()

◆ setTxPower()

◆ sleep()

◆ validateRxBuf()

◆ writeTxFifo()