RadioHead
Public Types | Public Member Functions | Protected Member Functions | List of all members
RH_NRF51 Class Reference

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

#include <RH_NRF51.h>

Inheritance diagram for RH_NRF51:
RHGenericDriver

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 void waitAvailable ()
 
virtual bool waitPacketSent (uint16_t timeout)
 
virtual bool waitAvailableTimeout (uint16_t timeout)
 
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 ()
 
int16_t lastRssi ()
 
RHMode mode ()
 
void setMode (RHMode mode)
 Sets the operating mode of the transport.
 
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:

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.

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

Defines convenient values for setting data rates in setRF()

Enumerator
DataRate1Mbps 

1 Mbps

DataRate2Mbps 

2 Mbps

DataRate250kbps 

250 kbps

◆ 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]bufLocation to copy the received message
[in,out]lenPointer 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.

◆ 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]dataData bytes to send.
[in]lenNumber 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]keyThe 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]addressThe new network address. Must match the network address of any receiving node(s).
[in]lenNumber 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_rateThe data rate to use for all packets transmitted and received. One of RH_NRF51::DataRate.
[in]powerTransmitter 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: