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

#include <RH_RF24.h>

Data Structures
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 }
	Choices for setModemConfig() for a selected subset of common modulation types, and data rates. More...
enum	CRCPolynomial
	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. More...
enum	RHMode { RHModeInitialising = 0, RHModeSleep, RHModeIdle, RHModeTx, RHModeRx }
	Defines different operating modes for the transport hardware. More...
Public Member Functions
	RH_RF24 (PINS slaveSelectPin, PINS interruptPin, PINS sdnPin, RHGenericSPI &spi=hardware_spi)
	Constructor.
bool	init ()
	Initialises this instance and the radio module connected to it.
void	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.
bool	setFrequency (float centre, float afcPullInRange=0.05)
	Sets the transmitter and receiver centre frequency.
void	setModemRegisters (const ModemConfig *config)
	Sets all the properties required to configure the data modem in the RF24, including the data rate, bandwidths etc.
bool	setModemConfig (ModemConfigChoice index)
	Select one of the predefined modem configurations.
bool	available ()
	Starts the receiver and checks whether a received message is available.
bool	recv (uint8_t buf, uint8_t len)
	Turns the receiver on if it not already on.
bool	send (const uint8_t *data, uint8_t len)
	Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
uint8_t	maxMessageLength ()
	The maximum message length supported by this driver.
void	setPreambleLength (uint16_t bytes)
	Sets the length of the preamble in bytes.
void	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.
bool	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.
void	setModeIdle ()
	If current mode is Rx or Tx changes it to Idle.
void	setModeRx ()
	If current mode is Tx or Idle, changes it to Rx.
void	setModeTx ()
	If current mode is Rx or Idle, changes it to Rx.
void	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.
bool	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.
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)
	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.
bool	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.
bool	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.
float	get_temperature ()
	Measures and returns the current Chip temperature.
float	get_battery_voltage ()
	Measures and returns the current Chip Vcc supply voltage.
float	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)
uint8_t	frr_read (uint8_t reg)
	Read one of the Fast Read Response registers.
virtual bool	sleep ()
	Sets the radio into low-power sleep mode.
uint8_t	spiRead (uint8_t reg)
	Reads a single register from the SPI device.
uint8_t	spiWrite (uint8_t reg, uint8_t val)
	Writes a single byte to the SPI device.
uint8_t	spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len)
	Reads a number of consecutive registers from the SPI device using burst read mode.
uint8_t	spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len)
	Write a number of consecutive registers using burst write mode.
virtual void	waitAvailable ()
	Starts the receiver and blocks until a valid received message is available.
virtual bool	waitPacketSent ()
	Blocks until the transmitter is no longer transmitting.
virtual bool	waitPacketSent (uint16_t timeout)
	Blocks until the transmitter is no longer transmitting.
virtual bool	waitAvailableTimeout (uint16_t timeout)
	Starts the receiver and blocks until a received message is available or a timeout.
virtual void	setThisAddress (uint8_t thisAddress)
	Sets the address of this node.
virtual void	setHeaderTo (uint8_t to)
	Sets the TO header to be sent in all subsequent messages.
virtual void	setHeaderFrom (uint8_t from)
	Sets the FROM header to be sent in all subsequent messages.
virtual void	setHeaderId (uint8_t id)
	Sets the ID header to be sent in all subsequent messages.
virtual void	setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC)
	Sets and clears bits in the FLAGS header to be sent in all subsequent messages First it clears he FLAGS according to the clear argument, then sets the flags according to the set argument.
virtual void	setPromiscuous (bool promiscuous)
	Tells the receiver to accept messages with any TO address, not just messages addressed to thisAddress or the broadcast address.
virtual uint8_t	headerTo ()
	Returns the TO header of the last received message.
virtual uint8_t	headerFrom ()
	Returns the FROM header of the last received message.
virtual uint8_t	headerId ()
	Returns the ID header of the last received message.
virtual uint8_t	headerFlags ()
	Returns the FLAGS header of the last received message.
int8_t	lastRssi ()
	Returns the most recent RSSI (Receiver Signal Strength Indicator).
RHMode	mode ()
	Returns the operating mode of the library.
void	setMode (RHMode mode)
	Sets the operating mode of the transport.
uint16_t	rxBad ()
	Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc) which were rejected and not delivered to the application.
uint16_t	rxGood ()
	Returns the count of the number of good received packets.
uint16_t	txGood ()
	Returns the count of the number of packets successfully transmitted (though not necessarily received by the destination)
Static Public Member Functions
static void	printBuffer (const char prompt, const uint8_t buf, uint8_t len)
	Prints a data buffer in HEX.
Protected Member Functions
void	handleInterrupt ()
	This is a low level function to handle the interrupts for one instance of RF24.
bool	clearRxFifo ()
	Clears the chips RX FIFO.
void	clearBuffer ()
	Clears RH_RF24's internal TX and RX buffers and counters.
void	sendNextFragment ()
	Loads the next part of the currently transmitting message into the chips TX buffer.
void	readNextFragment ()
	Copies the next part of the currenrtly received message from the chips RX FIFO to the receive buffer.
bool	writeTxFifo (uint8_t *data, uint8_t len)
	Loads data into the chips TX FIFO.
void	validateRxBuf ()
	Checks the contents of the RX buffer.
void	power_on_reset ()
	Cycles the Shutdown pin to force the cradio chip to reset.
bool	configure (const uint8_t *commands)
	Sets registers, commands and properties in the ratio according to the data in the commands array.
bool	cmd_clear_all_interrupts ()
	Clears all pending interrutps in the radio chip.
Protected Attributes
RHGenericSPI &	_spi
	Reference to the RHGenericSPI instance to use to trasnfer data with teh SPI device.
DigitalOut	_slaveSelectPin
	The pin number of the Slave Selct pin that is used to select the desired device.
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 int8_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.

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

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.

Customising

The library will work out of the box with the provided examples, over the full frequency range and with a wide range of predefined modem configurations schemes and speeds. However, you may want to change the default behaviour of this library. There are several ways you can do this:

Use the RH_RF24 API based on this documentation
Create your own ModemConfig and pass it to setModemreeegisters()
Generate a new radio_config_Si4460.h using the Silicon Labs WDS software package
Write directly to the radio registers and properties using command() and set_properties()

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();

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.

Definition at line 637 of file RH_RF24.h.

Member Enumeration Documentation

enum CRCPolynomial

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.

Definition at line 763 of file RH_RF24.h.

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

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.

Definition at line 740 of file RH_RF24.h.

enum RHMode [inherited]

Defines different operating modes for the transport hardware.

These are the different values that can be adopted by the _mode variable and returned by the mode() member function,

Enumerator:

RHModeInitialising	Transport is initialising. Initial default value until init() is called..
RHModeSleep	Transport hardware is in low power sleep mode (if supported)
RHModeIdle	Transport is idle.
RHModeTx	Transport is in the process of transmitting a message.
RHModeRx	Transport is in the process of receiving a message.

Definition at line 45 of file RHGenericDriver.h.

Constructor & Destructor Documentation

RH_RF24	(	PINS	slaveSelectPin,
		PINS	interruptPin,
		PINS	sdnPin,
		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

Definition at line 60 of file RH_RF24.cpp.

Member Function Documentation

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

Definition at line 326 of file RH_RF24.cpp.

void clearBuffer ( ) [protected]

Clears RH_RF24's internal TX and RX buffers and counters.

Definition at line 300 of file RH_RF24.cpp.

bool clearRxFifo ( ) [protected]

Clears the chips RX FIFO.

Returns:: true if successful

Definition at line 294 of file RH_RF24.cpp.

bool cmd_clear_all_interrupts ( ) [protected]

Clears all pending interrutps in the radio chip.

Definition at line 823 of file RH_RF24.cpp.

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`
	)

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.

Definition at line 742 of file RH_RF24.cpp.

bool 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

Definition at line 792 of file RH_RF24.cpp.

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

Definition at line 884 of file RH_RF24.cpp.

float get_battery_voltage ( )

Measures and returns the current Chip Vcc supply voltage.

Returns:: The current chip Vcc supply voltage in Volts.

Definition at line 863 of file RH_RF24.cpp.

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

Definition at line 873 of file RH_RF24.cpp.

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

Definition at line 842 of file RH_RF24.cpp.

float get_temperature ( )

Measures and returns the current Chip temperature.

Returns:: The current chip temperature in degrees Centigrade

Definition at line 853 of file RH_RF24.cpp.

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

Definition at line 204 of file RH_RF24.cpp.

uint8_t headerFlags ( ) [virtual, inherited]

Returns the FLAGS header of the last received message.

Returns:: The FLAGS header

Definition at line 119 of file RHGenericDriver.cpp.

uint8_t headerFrom ( ) [virtual, inherited]

Returns the FROM header of the last received message.

Returns:: The FROM header

Definition at line 109 of file RHGenericDriver.cpp.

uint8_t headerId ( ) [virtual, inherited]

Returns the ID header of the last received message.

Returns:: The ID header

Definition at line 114 of file RHGenericDriver.cpp.

uint8_t headerTo ( ) [virtual, inherited]

Returns the TO header of the last received message.

Returns:: The TO header

Definition at line 104 of file RHGenericDriver.cpp.

bool 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 RHSPIDriver.

Definition at line 75 of file RH_RF24.cpp.

int8_t lastRssi ( ) [inherited]

Returns the most recent RSSI (Receiver Signal Strength Indicator).

Usually it is the RSSI of the last received message, which is measured when the preamble is received. If you called readRssi() more recently, it will return that more recent value.

Returns:: The most recent RSSI measurement in dBm.

Definition at line 124 of file RHGenericDriver.cpp.

uint8_t maxMessageLength ( ) [virtual]

The maximum message length supported by this driver.

Returns:: The maximum message length supported by this driver

Implements RHGenericDriver.

Definition at line 447 of file RH_RF24.cpp.

RHGenericDriver::RHMode mode ( ) [inherited]

Returns the operating mode of the library.

Returns:: the current mode, one of RF69_MODE_*

Definition at line 129 of file RHGenericDriver.cpp.

void power_on_reset ( ) [protected]

Cycles the Shutdown pin to force the cradio chip to reset.

Definition at line 809 of file RH_RF24.cpp.

void printBuffer	(	const char *	prompt,
		const uint8_t *	buf,
		uint8_t	len
	)		`[static, inherited]`

Prints a data buffer in HEX.

For diagnostic use

Parameters:

[in]	prompt	string to preface the print
[in]	buf	Location of the buffer to print
[in]	len	Length of the buffer in octets.

Definition at line 145 of file RHGenericDriver.cpp.

bool 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

Definition at line 1131 of file RH_RF24.cpp.

void readNextFragment ( ) [protected]

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

Definition at line 417 of file RH_RF24.cpp.

bool 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 available space in buf. Set to the actual number of octets copied.

Returns:: true if a valid message was copied to buf

Implements RHGenericDriver.

Definition at line 335 of file RH_RF24.cpp.

uint16_t rxBad ( ) [inherited]

Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc) which were rejected and not delivered to the application.

Caution: not all drivers can correctly report this count. Some underlying hardware only report good packets.

Returns:: The number of bad packets received.

Definition at line 165 of file RHGenericDriver.cpp.

uint16_t rxGood ( ) [inherited]

Returns the count of the number of good received packets.

Returns:: The number of good packets received.

Definition at line 170 of file RHGenericDriver.cpp.

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

Definition at line 352 of file RH_RF24.cpp.

void sendNextFragment ( ) [protected]

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

Definition at line 399 of file RH_RF24.cpp.

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

Definition at line 829 of file RH_RF24.cpp.

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

Definition at line 559 of file RH_RF24.cpp.

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

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.

Definition at line 581 of file RH_RF24.cpp.

void setHeaderFlags	(	uint8_t	set,
		uint8_t	clear = `RH_FLAGS_APPLICATION_SPECIFIC`
	)		`[virtual, inherited]`

Sets and clears bits in the FLAGS header to be sent in all subsequent messages First it clears he FLAGS according to the clear argument, then sets the flags according to the set argument.

The default for clear always clears the application specific flags.

Parameters:

[in]	set	bitmask of bits to be set. Flags are cleared with the clear mask before being set.
[in]	clear	bitmask of flags to clear. Defaults to RH_FLAGS_APPLICATION_SPECIFIC which clears the application specific flags, resultiung in new application specific flags identical to the set.

Definition at line 98 of file RHGenericDriver.cpp.

void setHeaderFrom ( uint8_t from ) [virtual, inherited]

Sets the FROM header to be sent in all subsequent messages.

Parameters:

[in] from The new FROM header value

Definition at line 88 of file RHGenericDriver.cpp.

void setHeaderId ( uint8_t id ) [virtual, inherited]

Sets the ID header to be sent in all subsequent messages.

Parameters:

[in] id The new ID header value

Definition at line 93 of file RHGenericDriver.cpp.

void setHeaderTo ( uint8_t to ) [virtual, inherited]

Sets the TO header to be sent in all subsequent messages.

Parameters:

[in] to The new TO header value

Definition at line 83 of file RHGenericDriver.cpp.

void 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

Definition at line 70 of file RH_RF24.cpp.

void setMode ( RHMode mode ) [inherited]

Sets the operating mode of the transport.

Definition at line 134 of file RHGenericDriver.cpp.

void setModeIdle ( )

If current mode is Rx or Tx changes it to Idle.

If the transmitter or receiver is running, disables them.

Definition at line 647 of file RH_RF24.cpp.

bool setModemConfig ( ModemConfigChoice index )

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.

Definition at line 540 of file RH_RF24.cpp.

void setModemRegisters ( const ModemConfig * config )

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.

Definition at line 453 of file RH_RF24.cpp.

void setModeRx ( )

If current mode is Tx or Idle, changes it to Rx.

Starts the receiver in the RF24.

Definition at line 673 of file RH_RF24.cpp.

void setModeTx ( )

If current mode is Rx or Idle, changes it to Rx.

F Starts the transmitter in the RF24.

Definition at line 694 of file RH_RF24.cpp.

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

Definition at line 552 of file RH_RF24.cpp.

void setPromiscuous ( bool promiscuous ) [virtual, inherited]

Tells the receiver to accept messages with any TO address, not just messages addressed to thisAddress or the broadcast address.

Parameters:

[in] promiscuous true if you wish to receive messages with any TO address

Reimplemented in RH_RF22.

Definition at line 73 of file RHGenericDriver.cpp.

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

Definition at line 572 of file RH_RF24.cpp.

void setThisAddress ( uint8_t thisAddress ) [virtual, inherited]

Sets the address of this node.

Defaults to 0xFF. Subclasses or the user may want to change this. This will be used to test the adddress in incoming messages. In non-promiscuous mode, only messages with a TO header the same as thisAddress or the broadcast addess (0xFF) will be accepted. In promiscuous mode, all messages will be accepted regardless of the TO header. In a conventional multinode system, all nodes will have a unique address (which you could store in EEPROM). You would normally set the header FROM address to be the same as thisAddress (though you dont have to, allowing the possibilty of address spoofing).

Parameters:

[in] thisAddress The address of this node.

Reimplemented in RH_RF22, and RH_TCP.

Definition at line 78 of file RHGenericDriver.cpp.

void 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

Definition at line 709 of file RH_RF24.cpp.

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

Definition at line 661 of file RH_RF24.cpp.

uint8_t spiBurstRead	(	uint8_t	reg,
		uint8_t *	dest,
		uint8_t	len
	)		`[inherited]`

Reads a number of consecutive registers from the SPI device using burst read mode.

Parameters:

[in]	reg	Register number of the first register
[in]	dest	Array to write the register values to. Must be at least len bytes
[in]	len	Number of bytes to read

Returns:: Some devices return a status byte during the first data transfer. This byte is returned. it may or may not be meaningfule depending on the the type of device being accessed.

Definition at line 56 of file RHSPIDriver.cpp.

uint8_t spiBurstWrite	(	uint8_t	reg,
		const uint8_t *	src,
		uint8_t	len
	)		`[inherited]`

Write a number of consecutive registers using burst write mode.

Parameters:

[in]	reg	Register number of the first register
[in]	src	Array of new register values to write. Must be at least len bytes
[in]	len	Number of bytes to write

Returns:: Some devices return a status byte during the first data transfer. This byte is returned. it may or may not be meaningfule depending on the the type of device being accessed.

Definition at line 69 of file RHSPIDriver.cpp.

uint8_t spiRead ( uint8_t reg ) [inherited]

Reads a single register from the SPI device.

Parameters:

[in] reg Register number

Returns:: The value of the register

Definition at line 32 of file RHSPIDriver.cpp.

uint8_t spiWrite	(	uint8_t	reg,
		uint8_t	val
	)		`[inherited]`

Writes a single byte to the SPI device.

Parameters:

[in]	reg	Register number
[in]	val	The value to write

Returns:: Some devices return a status byte during the first data transfer. This byte is returned. it may or may not be meaningfule depending on the the type of device being accessed.

Definition at line 44 of file RHSPIDriver.cpp.

uint16_t txGood ( ) [inherited]

Returns the count of the number of packets successfully transmitted (though not necessarily received by the destination)

Returns:: The number of packets successfully transmitted

Definition at line 175 of file RHGenericDriver.cpp.

void validateRxBuf ( ) [protected]

Checks the contents of the RX buffer.

If it contans a valid message adressed to this node sets _rxBufValid.

Definition at line 274 of file RH_RF24.cpp.

void waitAvailable ( ) [virtual, inherited]

Starts the receiver and blocks until a valid received message is available.

Reimplemented in RH_TCP.

Definition at line 33 of file RHGenericDriver.cpp.

bool waitAvailableTimeout ( uint16_t timeout ) [virtual, inherited]

Starts the receiver and blocks until a received message is available or a timeout.

Parameters:

[in] timeout Maximum time to wait in milliseconds.

Returns:: true if a message is available

Reimplemented in RH_TCP.

Definition at line 42 of file RHGenericDriver.cpp.

bool waitPacketSent ( ) [virtual, inherited]

Blocks until the transmitter is no longer transmitting.

Reimplemented in RH_NRF24, RH_NRF51, and RH_NRF905.

Definition at line 54 of file RHGenericDriver.cpp.

bool waitPacketSent ( uint16_t timeout ) [virtual, inherited]

Blocks until the transmitter is no longer transmitting.

or until the timeout occuers, whichever happens first

Parameters:

[in] timeout Maximum time to wait in milliseconds.

Returns:: true if the RF22 completed transmission within the timeout period. False if it timed out.

Definition at line 61 of file RHGenericDriver.cpp.

bool 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

Definition at line 385 of file RH_RF24.cpp.

Field Documentation

volatile int8_t _lastRssi [protected, inherited]

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

Definition at line 249 of file RHGenericDriver.h.

volatile RHMode _mode [protected, inherited]

The current transport operating mode.

Definition at line 216 of file RHGenericDriver.h.

bool _promiscuous [protected, inherited]

Whether the transport is in promiscuous mode.

Definition at line 222 of file RHGenericDriver.h.

volatile uint16_t _rxBad [protected, inherited]

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

Definition at line 252 of file RHGenericDriver.h.

volatile uint16_t _rxGood [protected, inherited]

Count of the number of successfully transmitted messaged.

Definition at line 255 of file RHGenericDriver.h.

volatile uint8_t _rxHeaderFlags [protected, inherited]

FLAGS header in the last received mesasge.

Definition at line 234 of file RHGenericDriver.h.

volatile uint8_t _rxHeaderFrom [protected, inherited]

FROM header in the last received mesasge.

Definition at line 228 of file RHGenericDriver.h.

volatile uint8_t _rxHeaderId [protected, inherited]

ID header in the last received mesasge.

Definition at line 231 of file RHGenericDriver.h.

volatile uint8_t _rxHeaderTo [protected, inherited]

TO header in the last received mesasge.

Definition at line 225 of file RHGenericDriver.h.

DigitalOut _slaveSelectPin [protected, inherited]

The pin number of the Slave Selct pin that is used to select the desired device.

Definition at line 86 of file RHSPIDriver.h.

RHGenericSPI& _spi [protected, inherited]

Reference to the RHGenericSPI instance to use to trasnfer data with teh SPI device.

Definition at line 82 of file RHSPIDriver.h.

uint8_t _thisAddress [protected, inherited]

This node id.

Definition at line 219 of file RHGenericDriver.h.

volatile uint16_t _txGood [protected, inherited]

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

Definition at line 258 of file RHGenericDriver.h.

uint8_t _txHeaderFlags [protected, inherited]

FLAGS header to send in all messages.

Definition at line 246 of file RHGenericDriver.h.

uint8_t _txHeaderFrom [protected, inherited]

FROM header to send in all messages.

Definition at line 240 of file RHGenericDriver.h.

uint8_t _txHeaderId [protected, inherited]

ID header to send in all messages.

Definition at line 243 of file RHGenericDriver.h.

uint8_t _txHeaderTo [protected, inherited]

TO header to send in all messages.

Definition at line 237 of file RHGenericDriver.h.

Type:	Library
Created:	15 Oct 2015
Imports:	194
Forks:	1
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	10

Important changes to repositories hosted on mbed.com

RH_RF24 Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

RH_RF24 Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning