Configuration API¶

Address Length feature¶

setAddressLength()¶

void RF24Revamped::setAddressLength(uint8_t length)¶

Set the address length from 3 to 5 bytes

Parameters: length – The address length (in bytes) to use; this parameter is clamped to the range [3, 5].

getAddressLength()¶

uint8_t RF24Revamped::getAddressLength(void)¶

Returns: The address length (in bytes) currently configured by setAddressLength(). This number will be in range [3, 5].

Dynamic Payload Length feature¶

Note

If the Dynamic Payload Length feature is enabled for any pipe, then the Static Payload Length feature setting for that pipe(s) is not used.

Dynamic Payload Length setters¶

Unary pipe control of Dynamic Payloads¶

void RF24Revamped::setDynamicPayloads(bool enable)¶

Enable or disable dynamically sized payloads for all pipes

Parameters: enable – Enable (true) or disable (false) the dynamic payload length feature for all pipes.

Binary pipe control of Dynamic Payloads¶

void RF24Revamped::setDynamicPayloadsBin(uint8_t binary_enable)¶

Enable or disable dynamically sized payloads for all pipes using a binary integer.

Parameters: binary_enable – A binary integer to control the dynamic payload length feature for all pipes. Bit positions 0-5 represent pipes 0-5 respectively. A high bit (1) enables the feature for the corresponding pipe; a low bit (0) disables the feature for the corresponding pipe.

Individual pipe control of Dynamic Payloads¶

void RF24Revamped::setDynamicPayloads(bool enable, uint8_t pipe)¶

Enable or disable dynamically sized payloads for a specific pipe.

Parameters

enable – the configuration of the dynamic payload length feature concerning specific pipe.
pipe – the specific pipe concerning the dynamic payload length feature.

Dynamic Payload Length getters¶

Individual Pipe Representation of Dynamic Payload Length¶

bool RF24Revamped::getDynamicPayloads(uint8_t pipe = 0)¶

Get the configuration of dynamically sized payloads for a specific pipe.

Parameters: pipe – the specific pipe concerning the dynamic payload length feature. If this parameter is not specified, then the configuration about pipe 0 is returned.

Binary Representation of Dynamic Payload Length¶

uint8_t RF24Revamped::getDynamicPayloadsBin(void)¶

Get the configuration of dynamically sized payloads for all pipes as a binary representation.

Returns: A binary integer where each bit represents the dynamic payload feature configuration for a specific pipe. Bit position 0 represents pipe 0, and bit position 5 represents pipe 5. A high bit (1) enables the feature for the corresponding pipe; a low bit (0) disables the feature for the corresponding pipe. Bit position 6 and 7 will always be 0.

Static Payload Length feature¶

All pipes are configured to use the maximum default length of 32 bytes.

Note

If the Dynamic Payload Length feature is enabled for any pipe, then the Static Payload Length setting is not used for that pipe(s).

Static Payload Length setters¶

Unary pipe control of Static Payload Lengths¶

void RF24Revamped::setPayloadLength(uint8_t size)¶

Set Static Payload length to be expected for all pipes.

Parameters: size – The number of bytes to use for payload lengths handled by all pipes. This parameter is clamped to the range [1, 32].

Individual pipe control of Static Payload Length¶

void RF24Revamped::setPayloadLength(uint8_t size, uint8_t pipe)¶

Set Static Payload length to be expected for a specific pipe.

Parameters

size – The number of bytes to use for payload lengths handled by the pipe specified by the pipe parameter. This parameter is clamped to the range [1, 32].
pipe – The specific pipe to configure the length for static payloads.

getPayloadLength()¶

uint8_t RF24Revamped::getPayloadLength(uint8_t pipe = 0)¶

Get Static Payload length for a specific pipe

Parameters: pipe – the specific pipe about the configuration being fetched. If not specified, then the data returned is about pipe 0.
Returns: The payload length in bytes that a pipe is configured to use.

Auto-Ack feature¶

Auto-acknowledgement responds to every recieved payload with an empty ACK packet. These ACK packets get sent from the receiving radio back to the transmitting radio. To attach an ACK payload to a ACK packet, use writeAck().

Pipe 0 is used for TX operations, which include sending ACK packets. If using this feature on both TX & RX nodes, then pipe 0 must have this feature enabled for the RX & TX operations. If this feature is disabled on a transmitting radio’s pipe 0, then the transmitting radio will always report that the payload was sent (even if it was not). Remember to also enable this feature for any pipe that is openly listening to a transmitting radio with this feature enabled.

Warning

If this feature is enabled for pipe 0, then the multicast parameter to send() can be used to disable this feature for an individual payload. However, if this feature is disabled for pipe 0, then the multicast parameter will have no effect.

Note

If disabling auto-acknowledgment packets on pipe 0, the Ack Payload feature is also disabled as this feature is required on pipe 0 to send ACK payloads.

Auto-Ack setters¶

Unary pipe control of AutoAck¶

void RF24Revamped::setAutoAck(bool enable)¶

Enable or disable the auto-acknowledgement feature for all pipes. This feature is enabled by default.

Parameters: enable – Enable (true) or disable (false) the auto-acknowledgment feature for all pipes

Binary pipe control of AutoAck¶

void RF24Revamped::setAutoAckBin(uint8_t binary_enable)¶

Enable or disable the auto-acknowledgement feature for a specific pipe. This feature is enabled by default for all pipes.

Parameters: binary_enable – A binary integer to control the auto-acknowledgement feature for all pipes. Bit positions 0-5 represent pipes 0-5 respectively. A high bit (1) enables the feature for the corresponding pipe; a low bit (0) disables the feature for the corresponding pipe.

Individual pipe control of AutoAck¶

void RF24Revamped::setAutoAck(bool enable, uint8_t pipe)¶

Enable or disable the auto-acknowledgement feature for a specific pipe. This feature is enabled by default for all pipes.

Parameters

enable – Enable (true) or disable (false) the auto-acknowledgment feature for the specified pipe
pipe – Which pipe to configure. This number should be in range [0, 5].

Auto-Ack getters¶

Binary Representation of Auto-Ack¶

uint8_t RF24Revamped::getAutoAckBin(void)¶

Fetch the status of the auto-ack feature for all pipes.

Returns: A binary integer where each bit represents the auto-acknowledgement feature configuration for a specific pipe. Bit position 0 represents pipe 0, and bit position 5 represents pipe 5. A high bit (1) enables the feature for the corresponding pipe; a low bit (0) disables the feature for the corresponding pipe. Bit positions 6 and 7 will always be 0.

Individual Pipe Representation of Auto-Ack¶

bool RF24Revamped::getAutoAck(uint8_t pipe = 0)¶

Fetch the status of the auto-ack feature for a specific pipe.

Parameters: pipe – The specific pipe about which data to fetch. If this parameter is not specified, then the status of the auto-ack feature about pipe 0 is returned.
Returns: If the auto-ack feature is enabled (true) or disabled (false) for the specified pipe

Auto-Retry feature¶

Important

The Auto-Retry feature requires the Auto-Ack feature enabled for pipe 0.

Hint

Disabling the auto-retry feature on a transmitter still uses the auto-ack feature (if enabled), except it will not retry to transmit if the payload was not acknowledged on the first attempt.

See also

lastTxArc()

Auto-Retry setters¶

setAutoRetry()¶

void RF24Revamped::setAutoRetry(uint16_t delay, uint8_t count)¶

Configure of the auto-retry feature.

Parameters

delay – How long to wait (in microseconds) for an acknowledgement (ACK) between each auto-retry attempt. This parameter is clamped to the range [250, 4000]. The default is 1500 us.
count – How many auto-retry attempts to make before giving up. The default and maximum is 15. Use 0 to disable the auto-retry feature.

setArd()¶

void RF24Revamped::setArd(uint16_t delay)¶

Configure the auto-retry feature’s delay (ARD).

Parameters: delay – How long to wait (in microseconds) between each auto-retry attempt. This parameter is clamped to the range [250, 4000]. The default is 1500 us.

setArc()¶

void RF24Revamped::setArc(uint8_t count)¶

Configure the auto-retry feature’s count (ARC).

Parameters: count – How many auto-retry attempts before giving up. The default and maximum is 15. Use 0 to disable the auto-retry feature all together.

Auto-Retry getters¶

getAutoRetry()¶

void RF24Revamped::getAutoRetry(uint16_t *delay, uint8_t *count)¶

Get the auto-retry feature’s configuration.

Parameters

delay – [out] The reference variable that will store the amount of microseconds that the radio waits for an acknowledgement (ACK) packet response between auto-retry attempted transmissions.
count – [out] The reference variable that will store the maximum number of auto-retry attempts allowed.

Returns

This function returns nothing (void). All returned data is stored in the referenced variables passed as arguments.

uint16_t autoDelay;
uint8_t autoCount;
radio.getAutoRetry(&autoDelay, &autoCount);

getArc()¶

uint8_t RF24Revamped::getArc(void)¶: Get the auto-retry feature’s count (ARC) configuration.

getArd()¶

uint16_t RF24Revamped::getArd(void)¶: Get the auto-retry feature’s delay (ARD) configuration,

Ack Payload feature¶

ACK payloads are a handy way to return data back to senders without manually changing the radio modes on both units.

Important

ACK payloads are dynamically sized payloads. Thus, the ACK payload feature requires the Auto-Ack feature and the Dynamic Payload Length feature to be enabled for any pipe using ACK payloads.

See also

setAutoAck(), writeAck()

enableAckPayload()¶

void RF24Revamped::enableAckPayload(void)¶

Enable custom payloads in the acknowledge packets

Note

This function automatically enables the Dynamic Payload Length feature and the Auto-Ack feature on pipe 0 by default.

Tip

Use Dynamic Payload Length setters and Auto-Ack setters to enable dynamic payloads and auto-ack packets on any or all pipes (especially for RX nodes that use pipes other than pipe 0 to receive transmissions expecting responses with ACK payloads).

disableAckPayload()¶

void RF24Revamped::disableAckPayload(void)¶: Disable custom payloads in the ackowledge packets

Multicast feature¶

allowMulticast()¶

void RF24Revamped::allowMulticast(bool)¶

Enable dynamic ACKs (single write multicast or unicast) for chosen messages.

radio.send(&data, 32, 1); // Sends a payload with no acknowledgement requested
radio.send(&data, 32, 0); // Sends a payload using auto-retry/auto-ack features

See also

Auto-Ack setters

Note

This function must be called once before using the multicast parameter for any functions that offer it. To use multicast behavior about all outgoing payloads (using pipe 0) or incoming payloads (concerning all RX pipes), use setAutoAck().

Parameters: enable – Enables (true) or disables (false) the affect of the multicast parameter to send() or write().

isAllowMulticast()¶

bool RF24Revamped::isAllowMulticast(void)¶

Returns: If the multicast parameter to write() or send() will have any affect. This is configured using allowMulticast().

interruptConfig()¶

void RF24Revamped::interruptConfig(bool dataReady = true, bool dataSent = true, bool dataFail = true)¶

This function is used to configure what events will trigger the Interrupt Request (IRQ) pin active LOW. The following events can be configured:

”data sent”: This does not mean that the data transmitted was recieved, only that the attempt to send it was complete.
”data failed”: This means the data being sent was not recieved. This event is only triggered when the auto-ack feature is enabled.
”data received”: This means that data from a receiving payload has been loaded into the RX FIFO buffers. Remember that there are only 3 levels available in the RX FIFO buffers.

By default, all events are configured to trigger the IRQ pin active LOW. When the IRQ pin is active, use clearStatusFlags() to determine what events triggered it. Remeber that calling clearStatusFlags() also clears these events’ status, and the IRQ pin will then be reset to inactive HIGH.

The following code configures the IRQ pin to only reflect the “data received” event:

radio.interruptConfig(0, 0, 1);

Parameters

dataReady – false ignores the “data received” event, true reflects the “data received” event on the IRQ pin.
dataSent – false ignores the “data sent” event, true reflects the “data sent” event on the IRQ pin.
dataFail – false ignores the “data failed” event, true reflects the “data failed” event on the IRQ pin.

RF Data Rate¶

Data Rate enum¶

enum rf24_datarate_e¶

How fast data moves through the air. Units are in bits per second (bps).

See also

setDataRate(), getDataRate()

Values:

enumerator RF24_1MBPS¶: (0) represents 1 Mbps

enumerator RF24_2MBPS¶: (1) represents 2 Mbps

enumerator RF24_250KBPS¶: (2) represents 250 kbps

setDataRate()¶

void RF24Revamped::setDataRate(rf24_datarate_e speed)¶

Set the transmission Data Rate

Parameters

speed – Specify one of the following values (as defined by rf24_datarate_e):

`speed` (enum value)	description
`RF24_1MBPS` (0)	for 1 Mbps
`RF24_2MBPS` (1)	for 2 Mbps
`RF24_250KBPS` (2)	for 250 kpbs

Warning

Setting RF24_250KBPS will fail for non-plus modules (when isPlusVariant() returns false).

getDataRate()¶

rf24_datarate_e RF24Revamped::getDataRate(void)¶

Fetches the currently configured transmission Data Rate

Returns: One of the values defined by rf24_datarate_e. See table in setDataRate()

RF Channel¶

setChannel()¶

void RF24Revamped::setChannel(uint8_t channel)¶

Set RF communication channel. The frequency used by a channel is calculated as:

2400 MHz + <channel number>

Meaning the default channel of 76 uses the approximate frequency of 2476 MHz.

Parameters: channel – Which RF channel to communicate on. This parameter is clamped to the range [0, 125].

getChannel()¶

uint8_t RF24Revamped::getChannel(void)¶

Get RF communication channel

Returns: The currently configured RF Channel

CRC checking¶

setCrc()¶

void RF24Revamped::setCrc(uint8_t length)¶

Set the CRC checksum length (in bytes)

Note

CRC checking cannot be disabled if auto-ack is enabled. Additionally, CRC checksum is automatically used when the auto-ack feature is enabled.

Parameters

length – Specify the CRC checksum length in bytes

`length`	description
0	to disable using CRC checksums
1	to use 8-bit checksums
2	to use 16-bit checksums

getCrc()¶

uint8_t RF24Revamped::getCrc(void)¶

Get the CRC checksum length (in bytes)

Note

CRC checksum is automatically used when the auto-ack feature is enabled.

Returns: The number of bytes used for a CRC checksum (see table in setCrc())

Power Amplifier Level¶

Power Amplifier Level enum¶

enum rf24_pa_dbm_e¶

Power Amplifier level. The units dBm (decibel-milliwatts or dB_mW) represents a logarithmic signal loss.

See also

setPaLevel(), getPaLevel()

Values:

enumerator RF24_PA_MIN¶

(0) represents:

nRF24L01	Si24R1 with `lnaEnabled` = 1	Si24R1 with `lnaEnabled` = 0
-18 dBm	-6 dBm	-12 dBm

enumerator RF24_PA_LOW¶

(1) represents:

nRF24L01	Si24R1 with `lnaEnabled` = 1	Si24R1 with `lnaEnabled` = 0
-12 dBm	0 dBm	-4 dBm

enumerator RF24_PA_HIGH¶

(2) represents:

nRF24L01	Si24R1 with `lnaEnabled` = 1	Si24R1 with `lnaEnabled` = 0
-6 dBm	3 dBm	1 dBm

enumerator RF24_PA_MAX¶

(3) represents:

nRF24L01	Si24R1 with `lnaEnabled` = 1	Si24R1 with `lnaEnabled` = 0
0 dBm	7 dBm	4 dBm

enumerator RF24_PA_ERROR¶: (4) This should not be used and remains for backward compatibility.

setPaLevel()¶

void RF24Revamped::setPaLevel(uint8_t level, bool lnaEnable = 1)¶

Set Power Amplifier (PA) level and Low Noise Amplifier (LNA) state

`level` (enum value)	nRF24L01	Si24R1 with `lnaEnabled` = 1	Si24R1 with `lnaEnabled` = 0
`RF24_PA_MIN` (0)	-18 dBm	-6 dBm	-12 dBm
`RF24_PA_LOW` (1)	-12 dBm	0 dBm	-4 dBm
`RF24_PA_HIGH` (2)	-6 dBm	3 dBm	1 dBm
`RF24_PA_MAX` (3)	0 dBm	7 dBm	4 dBm

Note

The getPaLevel() function does not care what was passed lnaEnable parameter.

Parameters

level – The desired Power Amplifier Level as defined by rf24_pa_dbm_e.
lnaEnable – Enable or Disable the LNA (Low Noise Amplifier) Gain. See table for Si24R1 modules below. lnaEnable only affects nRF24L01 modules with an LNA chip.

getPaLevel()¶

uint8_t RF24Revamped::getPaLevel(void)¶

Fetches the current Power Amplifier Level.

Returns: One of the values defined by rf24_pa_dbm_e. See tables in setPaLevel()