Send and receive unaddressed, unreliable datagrams by nRF51 and nRF52 compatible transceivers. More...

#include <RH_NRF51.h>

Inheritance diagram for RH_NRF51:

Public Types
enum	DataRate { DataRate1Mbps = 0 , DataRate2Mbps , DataRate250kbps }
	Defines convenient values for setting data rates in setRF() More...

enum	TransmitPower { TransmitPower4dBm = 0 , TransmitPower0dBm , TransmitPowerm4dBm , TransmitPowerm8dBm , TransmitPowerm12dBm , TransmitPowerm16dBm , TransmitPowerm20dBm , TransmitPowerm30dBm }
	Convenient values for setting transmitter power in setRF() More...

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

bool	init ()

bool	setChannel (uint8_t channel)

bool	setNetworkAddress (uint8_t *address, uint8_t len)

bool	setRF (DataRate data_rate, TransmitPower power)

void	setModeIdle ()

void	setModeRx ()
	Sets the radio in RX mode.

void	setModeTx ()
	Sets the radio in TX mode.

bool	send (const uint8_t *data, uint8_t len)

virtual bool	waitPacketSent ()

bool	isSending ()

bool	printRegisters ()

bool	available ()

bool	recv (uint8_t buf, uint8_t len)

void	setEncryptionKey (uint8_t *key=NULL)

uint8_t	maxMessageLength ()

float	get_temperature ()

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	validateRxBuf ()
	Examine the receive buffer to determine whether the message is for this node.

void	clearRxBuf ()
	Clear our local receive buffer.

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

Send and receive unaddressed, unreliable datagrams by nRF51 and nRF52 compatible transceivers.

Supported transceivers include:

Nordic nRF51 based 2.4GHz radio modules, such as nRF51822 and other compatible chips, such as used in RedBearLabs devices like: http://store.redbearlab.com/products/redbearlab-nrf51822 http://store.redbearlab.com/products/blenano and Sparkfun nRF52832 breakout board, with Arduino 1.6.13 and Sparkfun nRF52 boards manager 0.2.3

This base class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 254 octets per packet. Use one of the Manager classes to get addressing and acknowledgement reliability, routing, meshes etc.

The nRF51822 (https://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF51822) and nRF52832 (https://learn.sparkfun.com/tutorials/nrf52832-breakout-board-hookup-guide) is a complete SoC (system on a chip) with ARM microprocessor and 2.4 GHz radio, which supports a range of channels and transmission bit rates. Chip antenna is on-board.

This library provides functions for sending and receiving messages of up to 254 octets on any frequency supported by the nRF51822/nRF52832, at a selected data rate.

The nRF51 transceiver is configured to use Enhanced Shockburst with no acknowledgement and no retransmits. TXADDRESS and RXADDRESSES:RXADDR0 (ie pipe 0) are the logical address used. The on-air network address is set in BASE0 and PREFIX0. SHORTS is used to automatically transition the radio between Ready, Start and Disable. No interrupts are used.

Naturally, for any 2 radios to communicate that must be configured to use the same frequency and data rate, and with identical network addresses.

Example programs are included to show the main modes of use.

Packet Format

All messages sent and received by this class conform to this packet format. It is NOT compatible with the one used by RH_NRF24 and the nRF24L01 product specification, mainly because the nRF24 only supports 6 bits of message length.

1 octets PREAMBLE
3 to 5 octets NETWORK ADDRESS
1 octet S0 (not used, required if encryption used)
8 bits PAYLOAD LENGTH
1 octet S1 (not used, required if encryption used)
0 to 251 octets PAYLOAD (possibly encrypted), consisting of:
- 1 octet TO header
- 1 octet FROM header
- 1 octet ID header
- 1 octet FLAGS header
- 0 to 247 octets of user message
2 octets CRC (Algorithm x^16+x^12^x^5+1 with initial value 0xFFFF).

Example programs

Several example programs are provided.

The sample programs are designed to be built using Arduino 1.6.4 or later using the procedures outlined in http://redbearlab.com/getting-started-nrf51822/ or with Sparkfun nRF52832 breakout board, with Arduino 1.6.13 and Sparkfun nRF52 boards manager 0.2.3 using the procedures outlined in https://learn.sparkfun.com/tutorials/nrf52832-breakout-board-hookup-guide

Radio Performance

At DataRate2Mbps (2Mb/s), payload length vs airtime: 0 bytes takes about 70us, 128 bytes takes 520us, 254 bytes take 1020us. You can extrapolate linearly to slower data rates.

The RF powers claimed by the chip manufacturer have not been independently verified here.

Memory

The compiled client and server sketches are about 42k bytes on Arduino. The reliable client and server sketches compile to about 43k bytes on Arduino. Unfortunately the Arduino build environmnet does not drop unused clsses and code, so the resulting programs include all the unused classes ad code. This needs to be revisited. RAM requirements are minimal.

Member Enumeration Documentation

◆ DataRate

enum RH_NRF51::DataRate

Defines convenient values for setting data rates in setRF()

Enumerator
DataRate1Mbps	1 Mbps
DataRate2Mbps	2 Mbps
DataRate250kbps	250 kbps

◆ TransmitPower

enum RH_NRF51::TransmitPower

Convenient values for setting transmitter power in setRF()

Enumerator
TransmitPower4dBm	4 dBm
TransmitPower0dBm	0 dBm
TransmitPowerm4dBm	-4 dBm
TransmitPowerm8dBm	-8 dBm
TransmitPowerm12dBm	-12 dBm
TransmitPowerm16dBm	-16 dBm
TransmitPowerm20dBm	-20 dBm
TransmitPowerm30dBm	-30 dBm

Constructor & Destructor Documentation

◆ RH_NRF51()

RH_NRF51::RH_NRF51 ( )

Constructor. After constructing, you must call init() to initialise the interface and the radio module

Member Function Documentation

◆ available()

bool RH_NRF51::available ( )

virtual

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.

◆ get_temperature()

float RH_NRF51::get_temperature ( )

Reeads the current die temperature using the built in TEMP peripheral. Blocks while the temperature is measured, which takes about 30 microseconds.

◆ init()

bool RH_NRF51::init ( )

virtual

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

Start the processors High Frequency clock DC/DC converter and
Disable and reset the radio
Set the logical channel to 0 for transmit and receive (only pipe 0 is used)
Configure the CRC (2 octets, algorithm x^16+x^12^x^5+1 with initial value 0xffff)
Set the default network address of 0xE7E7E7E7E7
Set channel to 2
Set data rate to DataRate2Mbps
Set TX power to TransmitPower0dBm
Returns
true if everything was successful

Reimplemented from RHGenericDriver.

◆ isSending()

bool RH_NRF51::isSending ( )

Indicates if the chip is in transmit mode and there is a packet currently being transmitted

Returns: true if the chip is in transmit mode and there is a transmission in progress

◆ maxMessageLength()

uint8_t RH_NRF51::maxMessageLength ( )

virtual

The maximum message length supported by this driver

Returns: The maximum message length supported by this driver

Implements RHGenericDriver.

◆ printRegisters()

bool RH_NRF51::printRegisters ( )

Prints the value of all NRF_RADIO registers. to the Serial device if RH_HAVE_SERIAL is defined for the current platform For debugging purposes only. Caution: there are 1024 of them (many reserved and set to 0).

Returns: true on success

◆ recv()

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

virtual

Turns the receiver on if it not already on. Once a message with CRC correct is received, the receiver will be returned to Idle mode. 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.

◆ send()

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

virtual

Sends data to the address set by setTransmitAddress() Sets the radio to TX mode. Caution: when encryption is enabled, the maximum message length is reduced to 23 octets.

Parameters

[in]	data	Data bytes to send.
[in]	len	Number of data bytes to send

Returns: true on success (which does not necessarily mean the receiver got the message, only that the message was successfully transmitted). False if the message is too long or was otherwise not transmitted.

Implements RHGenericDriver.

◆ setChannel()

bool RH_NRF51::setChannel ( uint8_t channel )

Sets the transmit and receive channel number. The frequency used is (2400 + channel) MHz

Returns: true on success

◆ setEncryptionKey()

void RH_NRF51::setEncryptionKey ( uint8_t * key = NULL )

Enables AES encryption and sets the AES encryption key, used to encrypt and decrypt all messages using the on-chip AES CCM mode encryption engine. The default is disabled. In the AES configuration, the message counter and IV is always set to 0, which means the same keystream is used for every message with a given key. Caution: when encryption is enabled, the maximum message length is reduced to 23 octets.

Parameters

[in] key The key to use. Must be 16 bytes long. The same key must be installed in other instances of RH_RF51, otherwise communications will not work correctly. If key is NULL, encryption is disabled, which is the default.

◆ setModeIdle()

void RH_NRF51::setModeIdle ( )

Sets the radio in power down mode, with the configuration set to the last value from setOpMode(). Sets chip enable to LOW.

◆ setNetworkAddress()

bool RH_NRF51::setNetworkAddress	(	uint8_t *	address,
		uint8_t	len
	)

Sets the Network address. Only nodes with the same network address can communicate with each other. You can set different network addresses in different sets of nodes to isolate them from each other. Internally, this sets the nRF51 BASE0 and PREFIX0 to be the given network address. The first octet of the address is used for PREFIX0 and the rest is used for BASE0. BALEN is set to the approprtae base length. The default network address is 0xE7E7E7E7E7.

Parameters

[in]	address	The new network address. Must match the network address of any receiving node(s).
[in]	len	Number of bytes of address to set (3 to 5).

Returns: true on success, false if len is not in the range 3-5 inclusive.

◆ setRF()

bool RH_NRF51::setRF	(	DataRate	data_rate,
		TransmitPower	power
	)

Sets the data rate and transmitter power to use.

Parameters

[in]	data_rate	The data rate to use for all packets transmitted and received. One of RH_NRF51::DataRate.
[in]	power	Transmitter power. One of RH_NRF51::TransmitPower.

Returns: true on success

◆ waitPacketSent()

virtual bool RH_NRF51::waitPacketSent ( )

virtual

Blocks until the current message (if any) has been transmitted

Returns: true on success, false if the chip is not in transmit mode or other transmit failure

Reimplemented from RHGenericDriver.

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

RH_NRF51.h

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ DataRate

◆ TransmitPower

Constructor & Destructor Documentation

◆ RH_NRF51()

Member Function Documentation

◆ available()

◆ get_temperature()

◆ init()

◆ isSending()

◆ maxMessageLength()

◆ printRegisters()

◆ recv()

◆ send()

◆ setChannel()

◆ setEncryptionKey()

◆ setModeIdle()

◆ setNetworkAddress()

◆ setRF()

◆ waitPacketSent()