# nrf24l01

nRF24L01+ library for wireless communication.

Author | Rob Jansen, Copyright © 2019..2025, all rights reserved.
Adapted-by |
Compiler | 2.5r9

Description

    Libray for wireless transmission and reception using the nRF24L01+.

Sources

    https://infocenter.nordicsemi.com/pdf/nRF24L01P_PS_v1.0.pdf
             Partly based on the draft library of Sebastien LeLong. Completed,
             extended and adapted to enable backward compatibility with older
             nRF24XX devices. Draft library version can be found at:
             https://github.com/sirloon/jaluino/blob/master/lib/nrf24l01.jal

Notes

    The following pins must be defined by the main program before
             including this library for both software SPI and hardware SPI:
             -) alias nrf24_spi_sck_direction  -- SCK to sck of nRF24L01+
             -) alias nrf24_spi_sdi_direction  -- SDI to MISO of nRF24L01+
             -) alias nrf24_spi_sdo_direction  -- SDO to MOSI of nRF24L01+
             -) alias nrf24_ce_pin_direction   -- To ce of nRF24L01+
             -) alias nrf24_csn_pin_direction  -- To csn of nRF24L01+
             -) alias nrf24_ce_pin
             -) alias nrf24_csn_pin
             In addtion when using software SPI (see below):
             -) alias nrf24_spi_sck
             -) alias nrf24_spi_sdi
             -) alias nrf24_spi_sdo

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte NRF24_W_TX_PAYLOAD = 0xA0`
- `const byte NRF24_R_RX_PAYLOAD = 0x61`
- `const byte NRF24_OBSERVE_TX = 0x08`
- `const byte NRF24_DPL_P5 = 5`
- `const byte NRF24_ENAA_P0 = 0`
- `const byte NRF24_PRIM_RX = 0`
- `const byte NRF24_PLL_LOCK = 4`
- `const byte NRF24_MAX_PAYLOAD = 32`
- `const byte NRF24_DPL_P0 = 0`
- `const byte NRF24_RX_PW_P3 = 0x14`
- `const byte NRF24_SETUP_RETR = 0x04`
- `const byte NRF24_DPL_P1 = 1`
- `const byte NRF24_CRCO = 2`
- `const byte NRF24_AW = 0`
- `const byte NRF24_ENAA_P5 = 5`
- `const byte NRF24_CH = 0`
- `const byte NRF24_PWR_UP = 1`
- `const byte NRF24_RX_FULL = 1`
- `const byte NRF24_EN_RXADDR = 0x02`
- `const byte NRF24_ENAA_P4 = 4`
- `const byte NRF24_POWER_LEVEL_MED = 0b000_0100`
- `const byte NRF24_RX_P_NO = 1`
- `const byte NRF24_R_REGISTER = 0x00`
- `const byte NRF24_FIFO_STATUS = 0x17`
- `const byte NRF24_DYNPD = 0x1C`
- `const byte NRF24_TX_REUSE = 6`
- `const byte NRF24_RF_CH = 0x05`
- `const byte NRF24_TX_DS = 5`
- `const byte NRF24_REUSE_TX_PL = 0xE3`
- `const byte NRF24_POWER_LEVEL_MIN = 0b000_0000`
- `const byte NRF24_RF_PWR = 1`
- `const byte NRF24_NOP = 0xFF`
- `const byte NRF24_DPL_P2 = 2`
- `const byte NRF24_POWER_LEVEL_MAX = 0b000_0110`
- `const byte NRF24_ENAA_P1 = 1`
- `const byte NRF24_SETUP_AW = 0x03`
- `const byte NRF24_ERX_P3 = 3`
- `const byte NRF24_ERX_P2 = 2`
- `const byte NRF24_RX_PW_P2 = 0x13`
- `const byte NRF24_RF_DR_HIGH = 3`
- `const byte NRF24_ADDR_WIDTH_5 = 5`
- `const byte NRF24_RX_ADDR_P2 = 0x0C`
- `const byte NRF24_MASK_MAX_RT = 4`
- `var volatile byte nrf24_read_buffer[NRF24_PAYLOAD_SIZE]`
- `const byte NRF24_ACTIVATE = 0x50`
- `const byte NRF24_ERX_P1 = 1`
- `const byte NRF24_PLOS_CNT = 4`
- `const byte NRF24_CD = 0x09`
- `const byte NRF24_ERX_P5 = 5`
- `const byte NRF24_ADDR_WIDTH_4 = 4`
- `const byte NRF24_RF_DR_LOW = 5`
- `const byte NRF24_ARD = 4`
- `const byte NRF24_RX_PW_P1 = 0x12`
- `const byte NRF24_CONFIG = ((1<`
- `const byte NRF24_RX_PW_P0 = 0x11`
- `var bit _nrf24_dynamic_payload_enabled`
- `const byte NRF24_EN_AA = 0x01`
- `const byte NRF24_ADDR_WIDTH_3 = 3`
- `const byte NRF24_REGISTER_MASK = 0x1F`
- `const byte NRF24_CONT_WAVE = 7`
- `const byte NRF24_RX_DR = 6`
- `const byte NRF24_FLUSH_RX = 0xE2`
- `const byte NRF24_DATA_RATE_2MBPS = 0b0000_1000`
- `const byte NRF24_LNA_HCURR = 0`
- `const byte NRF24_RF_SETUP = 0x06`
- `const byte NRF24_CONFIG_REG = 0x00`
- `const byte NRF24_ENAA_P3 = 3`
- `const byte NRF24_FLUSH_TX = 0xE1`
- `const byte NRF24_TX_FULL = 0`
- `const byte NRF24_W_REGISTER = 0x20`
- `const byte NRF24_MASK_RX_DR = 6`
- `const byte NRF24_RX_ADDR_P0 = 0x0A`
- `const byte NRF24_POWER_LEVEL_LOW = 0b000_0010`
- `const byte NRF24_DATA_RATE_1MBPS = 0b0000_0000`
- `const byte NRF24_DATA_RATE_250KBPS = 0b0010_0000`
- `const byte NRF24_FEATURE = 0x1D`
- `const byte NRF24_RX_ADDR_P5 = 0x0F`
- `const byte NRF24_DPL_P4 = 4`
- `const byte NRF24_TX_ADDR = 0x10`
- `const byte NRF24_RX_ADDR_P4 = 0x0E`
- `const byte NRF24_EN_DPL = 2`
- `const byte NRF24_FIFO_FULL = 5`
- `const byte NRF24_MASK_TX_DS = 5`
- `const byte NRF24_DPL_P3 = 3`
- `const byte NRF24_ARC_CNT = 0`
- `const byte NRF24_ENAA_P2 = 2`
- `const byte NRF24_ERX_P4 = 4`
- `const byte NRF24_MAX_RT = 4`
- `const byte NRF24_ARC = 0`
- `const byte NRF24_TX_EMPTY = 4`
- `const byte NRF24_RX_EMPTY = 0`
- `const byte NRF24_R_RX_PL_WID = 0x60`
- `const byte NRF24_RX_PW_P4 = 0x15`
- `const byte NRF24_STATUS = 0x07`
- `const byte NRF24_ERX_P0 = 0`
- `const byte NRF24_RX_PW_P5 = 0x16`
- `const byte NRF24_RX_ADDR_P1 = 0x0B`
- `const byte NRF24_EN_CRC = 3`
- `const byte NRF24_RX_ADDR_P3 = 0x0D`

### Procedures

- `nrf24_power_down()`
- `nrf24_power_up_tx()`
- `nrf24_print_setup_retr()`
- `nrf24_print_rf_setup()`
- `nrf24_print_address_register(byte in str[], byte in reg, byte in qty)`
- `nrf24_power_up_rx()`
- `nrf24_send_data(byte in data[], byte in length)`
- `nrf24_set_auto_retransmit_delay(byte in retransmit_delay)`
- `nrf24_enable_compatibility_mode()`
- `nrf24_print_status()`
- `nrf24_disable_dynamic_payload()`
- `nrf24_init()`
- `nrf24_set_auto_retransmit_count(byte in retransmit_count)`
- `nrf24_set_power_level(byte in power_level)`
- `nrf24_enable_dynamic_payload()`
- `nrf24_set_data_rate(byte in data_rate)`
- `nrf24_print_details()`
- `nrf24_set_address_width(byte in width)`
- `nrf24_set_rf_channel(byte in channel)`
- `nrf24_set_rx_pipe(byte in pipe, byte in addr[])`
- `nrf24_print_config()`
- `nrf24_print_byte_register(byte in str[],byte in reg, byte in qty)`
- `nrf24_set_transmit_address(byte in addr[])`
- `nrf24_print_observe_tx()`
- `nrf24_print_en_aa()`

Private

- `_nrf24_flush_tx()`
- `_nrf24_write_byte_register(byte in reg, byte in value)`
- `_nrf24_write_array_register(byte in reg, byte in data[])`
- `_nrf24_flush_rx()`

### Functions

- `nrf24_tx_ok() return bit`
- `nrf24_data_available() return bit`
- `nrf24_carrier_detected() return bit`
- `nrf24_tx_ready() return bit`
- `nrf24_get_data(byte out pipe, byte in out how_long) return bit`

Private

- `_nrf24_read_byte_register(byte in reg) return byte`
- `_nrf24_get_status() return byte`
- `_nrf24_get_dynamic_payload_size() return byte`

## API details

### Global variables/contants

- `const byte NRF24_W_TX_PAYLOAD = 0xA0`

  No documentation found

- `const byte NRF24_R_RX_PAYLOAD = 0x61`

  No documentation found

- `const byte NRF24_OBSERVE_TX = 0x08`

  No documentation found

- `const byte NRF24_DPL_P5 = 5`

  No documentation found

- `const byte NRF24_ENAA_P0 = 0`

  No documentation found

- `const byte NRF24_PRIM_RX = 0`

  No documentation found

- `const byte NRF24_PLL_LOCK = 4`

  No documentation found

- `const byte NRF24_MAX_PAYLOAD = 32`

      Maximum payload size the nRF24L01+ device can handle.

- `const byte NRF24_DPL_P0 = 0`

  No documentation found

- `const byte NRF24_RX_PW_P3 = 0x14`

  No documentation found

- `const byte NRF24_SETUP_RETR = 0x04`

  No documentation found

- `const byte NRF24_DPL_P1 = 1`

  No documentation found

- `const byte NRF24_CRCO = 2`

  No documentation found

- `const byte NRF24_AW = 0`

  No documentation found

- `const byte NRF24_ENAA_P5 = 5`

  No documentation found

- `const byte NRF24_CH = 0`

  No documentation found

- `const byte NRF24_PWR_UP = 1`

  No documentation found

- `const byte NRF24_RX_FULL = 1`

  No documentation found

- `const byte NRF24_EN_RXADDR = 0x02`

  No documentation found

- `const byte NRF24_ENAA_P4 = 4`

  No documentation found

- `const byte NRF24_POWER_LEVEL_MED = 0b000_0100`

      -6dBm

- `const byte NRF24_RX_P_NO = 1`

  No documentation found

- `const byte NRF24_R_REGISTER = 0x00`

      Instruction Mnemonics.

- `const byte NRF24_FIFO_STATUS = 0x17`

  No documentation found

- `const byte NRF24_DYNPD = 0x1C`

  No documentation found

- `const byte NRF24_TX_REUSE = 6`

  No documentation found

- `const byte NRF24_RF_CH = 0x05`

  No documentation found

- `const byte NRF24_TX_DS = 5`

  No documentation found

- `const byte NRF24_REUSE_TX_PL = 0xE3`

  No documentation found

- `const byte NRF24_POWER_LEVEL_MIN = 0b000_0000`

      Power levels. Default is 0 dbM.

- `const byte NRF24_RF_PWR = 1`

  No documentation found

- `const byte NRF24_NOP = 0xFF`

  No documentation found

- `const byte NRF24_DPL_P2 = 2`

  No documentation found

- `const byte NRF24_POWER_LEVEL_MAX = 0b000_0110`

       0dBm

- `const byte NRF24_ENAA_P1 = 1`

  No documentation found

- `const byte NRF24_SETUP_AW = 0x03`

  No documentation found

- `const byte NRF24_ERX_P3 = 3`

  No documentation found

- `const byte NRF24_ERX_P2 = 2`

  No documentation found

- `const byte NRF24_RX_PW_P2 = 0x13`

  No documentation found

- `const byte NRF24_RF_DR_HIGH = 3`

  No documentation found

- `const byte NRF24_ADDR_WIDTH_5 = 5`

  No documentation found

- `const byte NRF24_RX_ADDR_P2 = 0x0C`

  No documentation found

- `const byte NRF24_MASK_MAX_RT = 4`

  No documentation found

- `var volatile byte nrf24_read_buffer[NRF24_PAYLOAD_SIZE]`

      Read buffer containing the data received from the nrf24.

- `const byte NRF24_ACTIVATE = 0x50`

  No documentation found

- `const byte NRF24_ERX_P1 = 1`

  No documentation found

- `const byte NRF24_PLOS_CNT = 4`

  No documentation found

- `const byte NRF24_CD = 0x09`

  No documentation found

- `const byte NRF24_ERX_P5 = 5`

  No documentation found

- `const byte NRF24_ADDR_WIDTH_4 = 4`

  No documentation found

- `const byte NRF24_RF_DR_LOW = 5`

  No documentation found

- `const byte NRF24_ARD = 4`

  No documentation found

- `const byte NRF24_RX_PW_P1 = 0x12`

  No documentation found

- `const byte NRF24_CONFIG = ((1<`

       Other used constants ---------------------------
      Enable CRC, 2-byte length.

- `const byte NRF24_RX_PW_P0 = 0x11`

  No documentation found

- `var bit _nrf24_dynamic_payload_enabled`

      Dynamic payload status.

- `const byte NRF24_EN_AA = 0x01`

  No documentation found

- `const byte NRF24_ADDR_WIDTH_3 = 3`

      Address width. Default is 5 bytes.

- `const byte NRF24_REGISTER_MASK = 0x1F`

  No documentation found

- `const byte NRF24_CONT_WAVE = 7`

  No documentation found

- `const byte NRF24_RX_DR = 6`

  No documentation found

- `const byte NRF24_FLUSH_RX = 0xE2`

  No documentation found

- `const byte NRF24_DATA_RATE_2MBPS = 0b0000_1000`

  No documentation found

- `const byte NRF24_LNA_HCURR = 0`

  No documentation found

- `const byte NRF24_RF_SETUP = 0x06`

  No documentation found

- `const byte NRF24_CONFIG_REG = 0x00`

      Memory Map.

- `const byte NRF24_ENAA_P3 = 3`

  No documentation found

- `const byte NRF24_FLUSH_TX = 0xE1`

  No documentation found

- `const byte NRF24_TX_FULL = 0`

  No documentation found

- `const byte NRF24_W_REGISTER = 0x20`

  No documentation found

- `const byte NRF24_MASK_RX_DR = 6`

      Bit Mnemonics.

- `const byte NRF24_RX_ADDR_P0 = 0x0A`

  No documentation found

- `const byte NRF24_POWER_LEVEL_LOW = 0b000_0010`

      -12dBm

- `const byte NRF24_DATA_RATE_1MBPS = 0b0000_0000`

  No documentation found

- `const byte NRF24_DATA_RATE_250KBPS = 0b0010_0000`

      Data rates. Default is 2 Mbits/s.

- `const byte NRF24_FEATURE = 0x1D`

  No documentation found

- `const byte NRF24_RX_ADDR_P5 = 0x0F`

  No documentation found

- `const byte NRF24_DPL_P4 = 4`

  No documentation found

- `const byte NRF24_TX_ADDR = 0x10`

  No documentation found

- `const byte NRF24_RX_ADDR_P4 = 0x0E`

  No documentation found

- `const byte NRF24_EN_DPL = 2`

  No documentation found

- `const byte NRF24_FIFO_FULL = 5`

  No documentation found

- `const byte NRF24_MASK_TX_DS = 5`

  No documentation found

- `const byte NRF24_DPL_P3 = 3`

  No documentation found

- `const byte NRF24_ARC_CNT = 0`

  No documentation found

- `const byte NRF24_ENAA_P2 = 2`

  No documentation found

- `const byte NRF24_ERX_P4 = 4`

  No documentation found

- `const byte NRF24_MAX_RT = 4`

  No documentation found

- `const byte NRF24_ARC = 0`

  No documentation found

- `const byte NRF24_TX_EMPTY = 4`

  No documentation found

- `const byte NRF24_RX_EMPTY = 0`

  No documentation found

- `const byte NRF24_R_RX_PL_WID = 0x60`

  No documentation found

- `const byte NRF24_RX_PW_P4 = 0x15`

  No documentation found

- `const byte NRF24_STATUS = 0x07`

  No documentation found

- `const byte NRF24_ERX_P0 = 0`

  No documentation found

- `const byte NRF24_RX_PW_P5 = 0x16`

  No documentation found

- `const byte NRF24_RX_ADDR_P1 = 0x0B`

  No documentation found

- `const byte NRF24_EN_CRC = 3`

  No documentation found

- `const byte NRF24_RX_ADDR_P3 = 0x0D`

  No documentation found

### Procedures

- `nrf24_power_down()`

      Power down the device. Device is powered up when a message is transmitted.

- `nrf24_power_up_tx()`

      Power up the transmitter and clear all pending RX and TX status bits.

- `nrf24_print_setup_retr()`

  No documentation found

- `nrf24_print_rf_setup()`

  No documentation found

- `nrf24_print_address_register(byte in str[], byte in reg, byte in qty)`

  No documentation found

- `nrf24_power_up_rx()`

      Power up the receiver and clear all pending RX and TX status bits.

- `nrf24_send_data(byte in data[], byte in length)`

      Sends the number of data bytes given in length from the given buffer. When
      dynamic payload is not active the procedure will fill the remaining payload
      with '00' as to always start a transmission.

- `nrf24_set_auto_retransmit_delay(byte in retransmit_delay)`

      Sets the auto re_transmit delay from 0 (250 us) to 15 (4000 us) in steps of
      250 us. Note that the delay is defined as the time between the start of a
      transmission and the start of the next transmission. This means that
      tranmitting a message with a high payload, a short delay and a low bitrate
      can cause transmission failures. A safe value is 1500 us minimum for a 32
      byte payload at 250 kbps, also see the datasheet.

- `nrf24_enable_compatibility_mode()`

      Disable the nRF24L01+ mode. Needed for backwards compatibilty when
      communicating with an nRF24L01 non-plus device. This disables auto
      acknowedge on all pipes, sets the auto retranmit delay to 250 us and sets
      the auto retransmit count to 0. The data rate is set to 1 Mbit/s

- `nrf24_print_status()`

  No documentation found

- `nrf24_disable_dynamic_payload()`

      Disable dynamic payload on all pipes.

- `nrf24_init()`

      Initializes the SPI interface to communicate with the nRF24L01+ module and
      initializes the module after which the module is powered down. The procedure
      also waits for power up time to pass and initializes the module as follows:
      ) Set CRC coding scheme to 2 bytes.
      ) Set transmit/receive address width to 5 bytes (default).
      ) Sets the module receive address to NRF24_RECEIVE_ADDR on pipe 1 including
      the payload size to NRF24_PAYLOAD_SIZE.
      ) Enable plus mode which means setting auto acknowledge on all pipes.
      ) Set the retransmit delay 750 us and the retransmit count to 5.
      ) Set RF Channel to 2 (default).
      ) Set bitrate to 2 Mbits/s (default).
      ) Set RF TX power power to 0 dBm (default).
      ) Enable dynamic payload length.

- `nrf24_set_auto_retransmit_count(byte in retransmit_count)`

      Sets the auto re-transmit count from 0 (no re-transmits) to 15 re-transmits.

- `nrf24_set_power_level(byte in power_level)`

      Set the power level of the transmitter. Use the defined power rate constants.

- `nrf24_enable_dynamic_payload()`

      Enable dynamic payload on all pipes.

- `nrf24_set_data_rate(byte in data_rate)`

      Set the data rate. Use the defined data rate constants.

- `nrf24_print_details()`

  No documentation found

- `nrf24_set_address_width(byte in width)`

      Set the address width on all pipes.

- `nrf24_set_rf_channel(byte in channel)`

      Set the RF channel, value 0 - 127 or 0 - 84 in the US.

- `nrf24_set_rx_pipe(byte in pipe, byte in addr[])`

      Sets the receiving address for a pipe number, and sets payload width as well.

- `nrf24_print_config()`

  No documentation found

- `nrf24_print_byte_register(byte in str[],byte in reg, byte in qty)`

  No documentation found

- `nrf24_set_transmit_address(byte in addr[])`

      Sets the transmitting address and pipe 0 as to enable auto acknowledge.

- `nrf24_print_observe_tx()`

  No documentation found

- `nrf24_print_en_aa()`

  No documentation found

Private

- `_nrf24_flush_tx()`

      Flush the transmit buffer.

- `_nrf24_write_byte_register(byte in reg, byte in value)`

      Write a byte into the given nRF24L01+ register.

- `_nrf24_write_array_register(byte in reg, byte in data[])`

      Write an array of data into the given nRF24L01+ register.

- `_nrf24_flush_rx()`

      Flush the receive buffer.

### Functions

- `nrf24_tx_ok() return bit`

      Returns the the status of the last transmission. If the maximum number of
      retries were used FALSE is returned indicating a tranmission failure,
      otherwise TRUE is returned indicating a succesful transmission.

- `nrf24_data_available() return bit`

      Checks if data is available for reading and returns TRUE when data is present.

- `nrf24_carrier_detected() return bit`

      Check for the presense of a carrier and return TRUE when detected.

- `nrf24_tx_ready() return bit`

      Check if the transmission status and returns TRUE when ready.

- `nrf24_get_data(byte out pipe, byte in out how_long) return bit`

      Checks if data is received, copies it to the nrf24_read_buffer[] and returns
      TRUE when data is available.

Private

- `_nrf24_read_byte_register(byte in reg) return byte`

      Reads and returns the value of the given nRF24L01+ register.

- `_nrf24_get_status() return byte`

      Return the contents of the nrf24L01+ status register.

- `_nrf24_get_dynamic_payload_size() return byte`

      Get the size of the dynamic payload, if incorrect flush the rx fifo.

## Related samples

Here are the list of samples which use this library:

16f1823 | 16f1823_nrf24l01.jal
16f1825 | 16f1825_nrf24l01.jal
16f1829 | 16f1829_nrf24l01.jal