NRF24 Class Reference

Send and receive addressed, reliable, acknowledged datagrams by nRF24L01. More...

`#include <NRF24.h>`

## Public Types

enum | NRF24DataRate { NRF24DataRate1Mbps = 0, NRF24DataRate2Mbps, NRF24DataRate250kbps }
| Defines convenient values for setting data rates in setRF() More...
enum | NRF24TransmitPower { NRF24TransmitPowerm18dBm = 0, NRF24TransmitPowerm12dBm, NRF24TransmitPowerm6dBm, NRF24TransmitPower0dBm }
| Convenient values for setting transmitter power in setRF() These are designed to agree with the values for RF_PWR To be passed to setRF();. More...

## Public Member Functions

| NRF24 (uint8_t chipEnablePin=8, uint8_t chipSelectPin=SS)
boolean | init ()
uint8_t | spiCommand (uint8_t command)
uint8_t | spiRead (uint8_t command)
uint8_t | spiWrite (uint8_t command, uint8_t val)
void | spiBurstRead (uint8_t command, uint8_t *dest, uint8_t len)
uint8_t | spiBurstWrite (uint8_t command, uint8_t *src, uint8_t len)
uint8_t | spiReadRegister (uint8_t reg)
uint8_t | spiWriteRegister (uint8_t reg, uint8_t val)
void | spiBurstReadRegister (uint8_t reg, uint8_t *dest, uint8_t len)
uint8_t | spiBurstWriteRegister (uint8_t reg, uint8_t *src, uint8_t len)
uint8_t | statusRead ()
uint8_t | flushTx ()
uint8_t | flushRx ()
boolean | setChannel (uint8_t channel)
boolean | setConfiguration (uint8_t configuration)
boolean | setPipeAddress (uint8_t pipe, uint8_t *address, uint8_t len)
boolean | setRetry (uint8_t delay, uint8_t count=3)
boolean | setThisAddress (uint8_t *address, uint8_t len)
boolean | setTransmitAddress (uint8_t *address, uint8_t len)
boolean | setPayloadSize (uint8_t size)
boolean | setRF (uint8_t data_rate, uint8_t power)
boolean | powerDown ()
boolean | powerUpRx ()
boolean | powerUpTx ()
boolean | send (uint8_t *data, uint8_t len, boolean noack=false)
boolean | waitPacketSent ()
boolean | isSending ()
boolean | printRegisters ()
boolean | available ()
void | waitAvailable ()
bool | waitAvailableTimeout (uint16_t timeout)
boolean | recv (uint8_t *buf, uint8_t *len)

## Detailed Description

Send and receive addressed, reliable, acknowledged datagrams by nRF24L01.

This base class provides basic functions for sending and receiving addressed, reliable, automatically acknowledged and retransmitted datagrams via nRF24L01 of arbitrary length to 32 octets per packet. Sender and receiver must each know the addreesses of the other, so arbitrary meshes and stars are not possible at this level. Directed replies (ie replies sent back to the original sender) are not possible (the address of the sender is not carried in the message). See subclasses for support for this.

Subclasses may use this class to implement streams, mesh routers, repeaters, translators etc.

On transmission, the addresses of this node defaults to 0x0000000000, unless changed by a subclass.

The radio is configured to use Enhanced Shockburst with retransmits. TX_ADDR and RX_ADDR_P0 are set to the transmit address (ie the address of the destination for the next message RX_ADDR_P1 is set to the address of this node RX_ADDR_P2 is set to RX_ADDR_P1 with the LSbyte set to 0xff, for use as a broadcast address

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

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_rx.pde, nrf24_audio_tx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, nrf24_specan.pde, and nrf24_test.pde.

## Member Enumeration Documentation

enum NRF24::NRF24DataRate

Defines convenient values for setting data rates in setRF()

Enumerator
NRF24DataRate1Mbps | 1 Mbps
NRF24DataRate2Mbps | 2 Mbps
NRF24DataRate250kbps | 250 kbps

enum NRF24::NRF24TransmitPower

Convenient values for setting transmitter power in setRF() These are designed to agree with the values for RF_PWR To be passed to setRF();.

Enumerator
NRF24TransmitPowerm18dBm | -18 dBm
NRF24TransmitPowerm12dBm | -12 dBm
NRF24TransmitPowerm6dBm | -6 dBm
NRF24TransmitPower0dBm | 0 dBm

## Constructor & Destructor Documentation

NRF24::NRF24 | ( | uint8_t | chipEnablePin = `8`,
|  | uint8_t | chipSelectPin = `SS`
| ) |  |

Constructor. You can have multiple instances, but each instance must have its own chip enable and slave select pin. After constructing, you must call init() to initialise the interface and the radio module

Parameters

  [in] | chipEnablePin | the Arduino pin to use to enable the chip for4 transmit/receive
  [in] | chipSelectPin | the Arduino pin number of the output to use to select the NRF24 before accessing it

## Member Function Documentation

boolean NRF24::available | ( |  | ) |

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

References flushRx(), spiRead(), and spiReadRegister().

Referenced by recv(), waitAvailable(), and waitAvailableTimeout().

uint8_t NRF24::flushRx | ( |  | ) |

Flush the RX FIFOs

Returns
  the value of the device status register

References spiCommand().

Referenced by available(), and init().

uint8_t NRF24::flushTx | ( |  | ) |

Flush the TX FIFOs

Returns
  the value of the device status register

References spiCommand().

Referenced by init(), and waitPacketSent().

boolean NRF24::init | ( |  | ) |

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

- Set the chip enable and chip select pins to output LOW, HIGH respectively.
- Initialise the SPI output pins
- Initialise the SPI interface library to 8MHz (Hint, if you want to lower the SPI frequency (perhaps where you have other SPI shields, low voltages etc), call SPI.setClockDivider() after init()). -Flush the receiver and transmitter buffers
- Set the radio to receive with powerUpRx();
  Returns
    true if everything was successful

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_rx.pde, nrf24_audio_tx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, nrf24_specan.pde, and nrf24_test.pde.

References flushRx(), flushTx(), powerDown(), powerUpRx(), and spiWriteRegister().

boolean NRF24::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

References spiReadRegister(), and statusRead().

boolean NRF24::powerDown | ( |  | ) |

Sets the radio in power down mode. Sets chip enable to LOW.

Returns
  true on success

Examples:
  nrf24_test.pde.

References spiWriteRegister().

Referenced by init().

boolean NRF24::powerUpRx | ( |  | ) |

Sets the radio in RX mode. Sets chip enable to HIGH to enable the chip in RX mode.

Returns
  true on success

Examples:
  nrf24_audio_rx.pde, and nrf24_specan.pde.

References spiWriteRegister().

Referenced by init(), waitAvailable(), and waitAvailableTimeout().

boolean NRF24::powerUpTx | ( |  | ) |

Sets the radio in TX mode. Pulses the chip enable LOW then HIGH to enable the chip in TX mode.

Returns
  true on success

Examples:
  nrf24_test.pde.

References spiWriteRegister().

Referenced by send().

boolean NRF24::printRegisters | ( |  | ) |

Prints the value of all chip registers for debugging purposes

Returns
  true on success

References spiReadRegister().

boolean NRF24::recv | ( | uint8_t * | buf,
|  | uint8_t * | len
| ) |  |

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

Examples:
  crazyflie.ino, nrf24_audio_rx.pde, nrf24_ping_client.pde, and nrf24_ping_server.pde.

References available(), spiBurstRead(), spiRead(), and spiWriteRegister().

boolean NRF24::send | ( | uint8_t * | data,
|  | uint8_t | len,
|  | boolean | noack = `false`
| ) |  |

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 set in teh TX buffer. The actual size of the transmitted data payload is set by setPayloadSize
  [in] | noack | Optional parameter if true sends the message NOACK mode. Requires that the NOACK feature be enabled with spiWriteRegister(NRF24_REG_1D_FEATURE, NRF24_EN_DYN_ACK);

Returns
  true on success

Examples:
  crazyflie_client.ino, nrf24_audio_tx.pde, nrf24_ping_client.pde, and nrf24_ping_server.pde.

References powerUpTx(), and spiBurstWrite().

boolean NRF24::setChannel | ( | uint8_t | channel | ) |

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

Returns
  true on success

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_rx.pde, nrf24_audio_tx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, nrf24_specan.pde, and nrf24_test.pde.

References spiWriteRegister().

boolean NRF24::setConfiguration | ( | uint8_t | configuration | ) |

Sets the chip configuration that will be used to set the NRF24 NRF24_REG_00_CONFIG register. This allows you to change some chip configuration for compatibility with libraries other than this one. You should not normally need to call this. Defaults to NRF24_EN_CRC, which is the standard configuraiton for this library.

Parameters

  [in] | configuration | The chip configuration to be used.

Returns
  true on success

Examples:
  crazyflie.ino, and crazyflie_client.ino.

boolean NRF24::setPayloadSize | ( | uint8_t | size | ) |

Sets the number of bytes transmitted in each payload

Parameters

  [in] | size | Size of the transmitted payload in bytes

Returns
  true on success

Examples:
  nrf24_audio_rx.pde, nrf24_audio_tx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, and nrf24_test.pde.

References spiWriteRegister().

boolean NRF24::setPipeAddress | ( | uint8_t | pipe,
|  | uint8_t * | address,
|  | uint8_t | len
| ) |  |

Sets the first len bytes of the address for the given NRF24 receiver pipe This is an internal function and is not normally used by appications, but can be used for specialised applications.

Parameters

  [in] | pipe | The index of the pipe to set, from 0 to 5
  [in] | address | The new address for receiving. Must match the transmit address of the transmitting node
  [in] | len | Number of bytes of receive address to set.

Returns
  true on success

Examples:
  crazyflie.ino.

References spiBurstWriteRegister().

Referenced by setThisAddress().

boolean NRF24::setRetry | ( | uint8_t | delay,
|  | uint8_t | count = `3`
| ) |  |

Set the Auto Retransmit Delay and Auto Retransmit Count for Auto retransmission (ART). See section 7.4.2 in the NRF24 documentation It may be very important to set an appropriate delay and count for your application, especially with 250kbps (i.e. slow) data rate. The defaults are OK for faster data rates. If the delay is too short, the symptoms wil be unreliable transmission, or tranmsission failures

Parameters

  [in] | delay | The number of 250 microsecond intervals to wait for an ACK.
  [in] | count | The number of retries to us.

Returns
  true on success

Examples:
  crazyflie.ino, and crazyflie_client.ino.

References spiWriteRegister().

boolean NRF24::setRF | ( | uint8_t | data_rate,
|  | uint8_t | power
| ) |  |

Sets the data rate and tranmitter power to use

Parameters

  [in] | data_rate | The data rate to use for all packets transmitted and received. One of NRF24DataRate
  [in] | power | Transmitter power. One of NRF24TransmitPower.

Returns
  true on success

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_rx.pde, nrf24_audio_tx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, nrf24_specan.pde, and nrf24_test.pde.

References NRF24DataRate250kbps, NRF24DataRate2Mbps, and spiWriteRegister().

boolean NRF24::setThisAddress | ( | uint8_t * | address,
|  | uint8_t | len
| ) |  |

Sets the first len bytes of the address of this node Normally len is the same length as setAddressLength, but can be smaller in order to set the least significant bytes of the address

Parameters

  [in] | address | The new address for receiving. Must match the setTransmitAddress of the transmitting node.
  [in] | len | Number of bytes of receive address to set.

Returns
  true on success

Examples:
  nrf24_audio_rx.pde, nrf24_ping_client.pde, nrf24_ping_server.pde, and nrf24_test.pde.

References setPipeAddress().

boolean NRF24::setTransmitAddress | ( | uint8_t * | address,
|  | uint8_t | len
| ) |  |

Sets the next transmit address

Parameters

  [in] | address | The new address for transmitting. Must match the setThisAddress of the receiving node.
  [in] | len | Number of bytes of receive address to set.

Returns
  true on success

Examples:
  crazyflie_client.ino, nrf24_audio_tx.pde, nrf24_ping_client.pde, and nrf24_ping_server.pde.

References spiBurstWriteRegister().

void NRF24::spiBurstRead | ( | uint8_t | command,
|  | uint8_t * | dest,
|  | uint8_t | len
| ) |  |

Reads a number of consecutive bytes from a command using burst read mode

Parameters

  [in] | command | Command number of NRF24_COMMAND_*
  [in] | dest | Array to write the bytes returned by the command to. Must be at least len bytes
  [in] | len | Number of bytes to read

Returns
  the value of the device status register

Referenced by recv(), and spiBurstReadRegister().

void NRF24::spiBurstReadRegister | ( | uint8_t | reg,
|  | uint8_t * | dest,
|  | uint8_t | len
| ) |  |

Reads a number of consecutive registers from the NRF24 using burst read mode

Parameters

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

Returns
  the value of the device status register

References spiBurstRead().

uint8_t NRF24::spiBurstWrite | ( | uint8_t | command,
|  | uint8_t * | src,
|  | uint8_t | len
| ) |  |

Write a number of consecutive bytes to a command using burst write mode

Parameters

  [in] | command | Command number of the first register, one of NRF24_COMMAND_*
  [in] | src | Array of bytes to write. Must be at least len bytes
  [in] | len | Number of bytes to write

Returns
  the value of the device status register

Examples:
  crazyflie.ino.

Referenced by send(), and spiBurstWriteRegister().

uint8_t NRF24::spiBurstWriteRegister | ( | uint8_t | reg,
|  | uint8_t * | src,
|  | uint8_t | len
| ) |  |

Write a number of consecutive registers using burst write mode

Parameters

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

Returns
  the value of the device status register

References spiBurstWrite().

Referenced by setPipeAddress(), and setTransmitAddress().

uint8_t NRF24::spiCommand | ( | uint8_t | command | ) |

Execute an SPI command that requires neither reading or writing

Parameters

  [in] | command | the SPI command to execute, one of NRF24_COMMAND_*

Returns
  the value of the device status register

Referenced by flushRx(), and flushTx().

uint8_t NRF24::spiRead | ( | uint8_t | command | ) |

Reads a single command byte from the NRF24

Parameters

  [in] | command | Command number, one of NRF24_COMMAND_*

Returns
  the single byte returned by the command

Referenced by available(), recv(), and spiReadRegister().

uint8_t NRF24::spiReadRegister | ( | uint8_t | reg | ) |

Reads a single register from the NRF24

Parameters

  [in] | reg | Register number, one of NRF24_REG_*

Returns
  The value of the register

Examples:
  nrf24_specan.pde.

References spiRead().

Referenced by available(), isSending(), printRegisters(), statusRead(), and waitPacketSent().

uint8_t NRF24::spiWrite | ( | uint8_t | command,
|  | uint8_t | val
| ) |  |

Writes a single command byte to the NRF24

Parameters

  [in] | command | Command number, one of NRF24_COMMAND_*
  [in] | val | The value to write

Returns
  the value of the device status register

Referenced by spiWriteRegister().

uint8_t NRF24::spiWriteRegister | ( | uint8_t | reg,
|  | uint8_t | val
| ) |  |

Writes a single byte to the NRF24, and at the ame time reads the current STATUS register

Parameters

  [in] | reg | Register number, one of NRF24_REG_*
  [in] | val | The value to write

Returns
  the current STATUS (read while the command is sent)

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_tx.pde, and nrf24_test.pde.

References spiWrite().

Referenced by init(), powerDown(), powerUpRx(), powerUpTx(), recv(), setChannel(), setPayloadSize(), setRetry(), setRF(), and waitPacketSent().

uint8_t NRF24::statusRead | ( |  | ) |

Reads and returns the device status register NRF24_REG_02_DEVICE_STATUS

Returns
  The value of the device status register

References spiReadRegister().

Referenced by isSending(), and waitPacketSent().

void NRF24::waitAvailable | ( |  | ) |

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

Examples:
  crazyflie.ino, nrf24_audio_rx.pde, and nrf24_ping_server.pde.

References available(), and powerUpRx().

bool NRF24::waitAvailableTimeout | ( | uint16_t | timeout | ) |

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

Examples:
  nrf24_ping_client.pde.

References available(), and powerUpRx().

boolean NRF24::waitPacketSent | ( |  | ) |

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

Returns
  true on success, false if the Max retries were exceeded, or if the chip is not in transmit mode.

Examples:
  crazyflie.ino, crazyflie_client.ino, nrf24_audio_tx.pde, nrf24_ping_client.pde, and nrf24_ping_server.pde.

References flushTx(), spiReadRegister(), spiWriteRegister(), and statusRead().

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

- NRF24.h
- NRF24.cpp