NRF24
Public Types | Public Member Functions | List of all members
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

Defines convenient values for setting data rates in setRF()

Enumerator
NRF24DataRate1Mbps 

1 Mbps

NRF24DataRate2Mbps 

2 Mbps

NRF24DataRate250kbps 

250 kbps

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]chipEnablePinthe Arduino pin to use to enable the chip for4 transmit/receive
[in]chipSelectPinthe 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]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
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]dataData bytes to send.
[in]lenNumber of data bytes to set in teh TX buffer. The actual size of the transmitted data payload is set by setPayloadSize
[in]noackOptional 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]configurationThe 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]sizeSize 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]pipeThe index of the pipe to set, from 0 to 5
[in]addressThe new address for receiving. Must match the transmit address of the transmitting node
[in]lenNumber 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]delayThe number of 250 microsecond intervals to wait for an ACK.
[in]countThe 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_rateThe data rate to use for all packets transmitted and received. One of NRF24DataRate
[in]powerTransmitter 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]addressThe new address for receiving. Must match the setTransmitAddress of the transmitting node.
[in]lenNumber 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]addressThe new address for transmitting. Must match the setThisAddress of the receiving node.
[in]lenNumber 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]commandCommand number of NRF24_COMMAND_*
[in]destArray to write the bytes returned by the command to. Must be at least len bytes
[in]lenNumber 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]regRegister number of the first register, one of NRF24_REG_*
[in]destArray to write the register values to. Must be at least len bytes
[in]lenNumber 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]commandCommand number of the first register, one of NRF24_COMMAND_*
[in]srcArray of bytes to write. Must be at least len bytes
[in]lenNumber 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]regRegister number of the first register, one of NRF24_REG_*
[in]srcArray of new register values to write. Must be at least len bytes
[in]lenNumber 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]commandthe 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]commandCommand 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]regRegister 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]commandCommand number, one of NRF24_COMMAND_*
[in]valThe 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]regRegister number, one of NRF24_REG_*
[in]valThe 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]timeoutMaximum 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: