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