Send and receive addressed datagrams by nRF51 compatible transceivers. More...

#include <RH_NRF51.h>

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...
enum	RHMode { RHModeInitialising = 0, RHModeSleep, RHModeIdle, RHModeTx, RHModeRx }
	Defines different operating modes for the transport hardware. More...
Public Member Functions
	RH_NRF51 ()
	Constructor.
bool	init ()
	Initialises this instance and the radio module connected to it.
bool	setChannel (uint8_t channel)
	Sets the transmit and receive channel number.
bool	setNetworkAddress (uint8_t *address, uint8_t len)
	Sets the Network address.
bool	setRF (DataRate data_rate, TransmitPower power)
	Sets the data rate and transmitter power to use.
void	setModeIdle ()
	Sets the radio in power down mode, with the configuration set to the last value from setOpMode().
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)
	Sends data to the address set by setTransmitAddress() Sets the radio to TX mode.
virtual bool	waitPacketSent ()
	Blocks until the current message (if any) has been transmitted.
bool	isSending ()
	Indicates if the chip is in transmit mode and there is a packet currently being transmitted.
bool	printRegisters ()
	Prints the value of all NRF_RADIO registers.
bool	available ()
	Checks whether a received message is available.
bool	recv (uint8_t buf, uint8_t len)
	Turns the receiver on if it not already on.
uint8_t	maxMessageLength ()
	The maximum message length supported by this driver.
virtual void	waitAvailable ()
	Starts the receiver and blocks until a valid received message is available.
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.
virtual bool	sleep ()
	Sets the transport hardware into low-power sleep mode (if supported).
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	validateRxBuf ()
	Examine the receive buffer to determine whether the message is for this node.
void	clearRxBuf ()
	Clear our local receive buffer.
Protected Attributes
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

Send and receive addressed datagrams by nRF51 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

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) 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, 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 suports 6 bits of message length.

1 octets PREAMBLE
3 to 5 octets NETWORK ADDRESS
8 bits PAYLOAD LENGTH
0 to 254 octets PAYLOAD, consisting of:
- 1 octet TO header
- 1 octet FROM header
- 1 octet ID header
- 1 octet FLAGS header
- 0 to 250 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/

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.

Definition at line 95 of file RH_NRF51.h.

Member Enumeration Documentation

enum DataRate

Defines convenient values for setting data rates in setRF()

Enumerator:

DataRate1Mbps	1 Mbps
DataRate2Mbps	2 Mbps
DataRate250kbps	250 kbps

Definition at line 100 of file RH_NRF51.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.

enum 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

Definition at line 108 of file RH_NRF51.h.

Constructor & Destructor Documentation

RH_NRF51 ( )

Constructor.

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

Definition at line 12 of file RH_NRF51.cpp.

Member Function Documentation

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

Definition at line 241 of file RH_NRF51.cpp.

void clearRxBuf ( ) [protected]

Clear our local receive buffer.

Definition at line 264 of file RH_NRF51.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:

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.

Definition at line 17 of file RH_NRF51.cpp.

bool 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

Definition at line 200 of file RH_NRF51.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 286 of file RH_NRF51.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 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 ( )

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

Definition at line 205 of file RH_NRF51.cpp.

bool 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 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 270 of file RH_NRF51.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]`

Sends data to the address set by setTransmitAddress() Sets the radio to TX mode.

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

Implements RHGenericDriver.

Definition at line 165 of file RH_NRF51.cpp.

bool setChannel ( uint8_t channel )

Sets the transmit and receive channel number.

The frequency used is (2400 + channel) MHz

Returns:: true on success

Definition at line 65 of file RH_NRF51.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 setMode ( RHMode mode ) [inherited]

Sets the operating mode of the transport.

Definition at line 134 of file RHGenericDriver.cpp.

void setModeIdle ( )

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

Sets chip enable to LOW.

Definition at line 130 of file RH_NRF51.cpp.

void setModeRx ( )

Sets the radio in RX mode.

Definition at line 139 of file RH_NRF51.cpp.

void setModeTx ( )

Sets the radio in TX mode.

Definition at line 152 of file RH_NRF51.cpp.

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

Definition at line 71 of file RH_NRF51.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.

bool 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

Definition at line 90 of file RH_NRF51.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.

bool sleep ( ) [virtual, inherited]

Sets the transport hardware into low-power sleep mode (if supported).

May be overridden by specific drivers to initialte 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)

Returns:: true if sleep mode is supported by transport hardware and the RadioHead driver, and if sleep mode was successfully entered. If sleep mode is not suported, return false.

Reimplemented in RH_NRF24, RH_RF22, RH_RF24, RH_RF69, and RH_RF95.

Definition at line 139 of file RHGenericDriver.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]

Examine the receive buffer to determine whether the message is for this node.

Definition at line 223 of file RH_NRF51.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 ( 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 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.

Definition at line 184 of file RH_NRF51.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.

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_NRF51 Class Reference

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_NRF51 Class Reference

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