Constant definitions and helper functions for the SPI command interface of the nRF24x series of 2.4 GHz digital transceivers. Relies on the spihelper.h module.
NOTE: The functions provided by this module do NOT manipulate any SPI Slave Select pins. Application developers must ensure that the commands these functions transmit via the SPI peripheral reach the intended destination device.
NOTE: This module does not deal with the CE and IRQ pins of the nRF24x IC. Those pins must be managed by application code.
NOTE: By default, this module will use the asynchronous API of the SPI helper module (i.e. spihelper_request), unless that API has been disabled. To use the synchronous API (i.e. spihelper_exchange_bytes) regardless of whether the asynchronous API is available, define the macro NRF24X_SYNCHRONOUS.
NOTE: By default, this module uses an internal command buffer when operating in asynchronous mode (i.e. when using the asynchronous API of spihelper.h). This buffer can be disabled and left undeclared (saving NRF24X_BFR_SIZE bytes of RAM) by defining the macro NRF24X_NO_CMD_BFR. However, doing this will also disable most of the helper functions.
| nrf24x.h | Constant definitions and helper functions for the SPI command interface of the nRF24x series of 2.4 GHz digital transceivers. |
| Configuration Macros | |
| Macros | |
| NRF24X_BFR_SIZE | Size in bytes of the buffer for asynchronous SPI operations. |
| SPI Interface Constants and Helper Macros | |
| Enumerations and Macros | |
| nRF24x Command Words | See the IC product specification for information about the protocol of the SPI interface. |
| NRF24X_R_REG_CMD | Constructs an R_REGISTER command word with a specified nRF24x register address. |
| NRF24X_W_REG_CMD | Constructs a W_REGISTER command word with a specified nRF24x register address. |
| NRF24X_W_ACK_PAYLOAD_CMD | Constructs a W_ACK_PAYLOAD command word with a specified nRF24x data pipe number. |
| nRF24x Register Addresses | See the IC product specification for information about register semantics. |
| nRF24x Data Pipe Numbers | See the IC product specification for information about data pipes. |
| nRF24x CONFIG Register Bits | See the IC product specification for information about the CONFIG register. |
| nRF24x SETUP_AW Register Values | See the IC product specification for information about the SETUP_AW register. |
| NRF24X_SETUP_RETR_VAL | Constructs a SETUP_RETR register value from ARD and ARC bitfield values. |
| NRF24X_RF_CH_VAL | Constructs an RF_CH register value from an RF_CH bitfield value. |
| nRF24x RF_SETUP Register Bits | See the IC product specification for information about the RF_SETUP register. |
| nRF24x STATUS Register Bits | See the IC product specification for information about the STATUS register. |
| NRF24X_GET_RX_P_NO | Extracts the RX_P_NO bitfield value from a STATUS register value. |
| NRF24X_GET_PLOS_CNT | Extracts the PLOS_CNT bitfield value from an OBSERVE_TX register value. |
| NRF24X_GET_ARC_CNT | Extracts the ARC_CNT bitfield value from an OBSERVE_TX register value. |
| nRF24x CD/ | See the IC product specification for information about the CD/RPD register. |
| nRF24x FIFO_STATUS Register Bits | See the IC product specification for information about the FIFO_STATUS register. |
| nRF24x FEATURE Register Bits | See the IC product specification for information about the FEATURE register. |
| Command API Variables | |
| Variables | |
| nrf24x_status | Storage location for STATUS values. |
| nrf24x_command | When the NRF24X_CMD_IN API macro is used, the command word of the input command to send MUST be stored here before the macro is invoked. |
| Command API Macros and Functions | |
| Macros | |
| NRF24X_CMD_OUT | Initiates an output command to the nRF24x via an asynchronous SPI request. |
| NRF24X_CMD_IN | Initiates an input command to the nRF24x via an asynchronous SPI request. |
| Functions | |
| nrf24x_out_0 | Sends a 0-byte output command (one that consists only of a command word) to the nRF24x. |
| nrf24x_out_1 | Sends a 1-byte output command (one that consists of a command word and a single output data byte) to the nRF24x. |
| nrf24x_out_n | Sends an N-byte output command (one that consists of a command word and a specified number of output data bytes) to the nRF24x. |
| nrf24x_in_1 | Sends a 1-byte input command (one that receives a single input data byte in response) to the nRF24x. |
| nrf24x_in_n | Sends an N-byte input command (one that receives a specified number of input data bytes in response) to the nRF24x. |
| Macros | |
| NRF24X_NONE_PENDING | Special value returned by nrf24x_in_finish when no asynchronous command is pending. |
| Functions | |
| nrf24x_in_finish | Used to finish an asynchronous input command sent to the nRF24x and fetch the received input data. |
| Macros | |
| NRF24X_BFR_SIZE | Size in bytes of the buffer for asynchronous SPI operations. |
| Enumerations and Macros | |
| nRF24x Command Words | See the IC product specification for information about the protocol of the SPI interface. |
| NRF24X_R_REG_CMD | Constructs an R_REGISTER command word with a specified nRF24x register address. |
| NRF24X_W_REG_CMD | Constructs a W_REGISTER command word with a specified nRF24x register address. |
| NRF24X_W_ACK_PAYLOAD_CMD | Constructs a W_ACK_PAYLOAD command word with a specified nRF24x data pipe number. |
| nRF24x Register Addresses | See the IC product specification for information about register semantics. |
| nRF24x Data Pipe Numbers | See the IC product specification for information about data pipes. |
| nRF24x CONFIG Register Bits | See the IC product specification for information about the CONFIG register. |
| nRF24x SETUP_AW Register Values | See the IC product specification for information about the SETUP_AW register. |
| NRF24X_SETUP_RETR_VAL | Constructs a SETUP_RETR register value from ARD and ARC bitfield values. |
| NRF24X_RF_CH_VAL | Constructs an RF_CH register value from an RF_CH bitfield value. |
| nRF24x RF_SETUP Register Bits | See the IC product specification for information about the RF_SETUP register. |
| nRF24x STATUS Register Bits | See the IC product specification for information about the STATUS register. |
| NRF24X_GET_RX_P_NO | Extracts the RX_P_NO bitfield value from a STATUS register value. |
| NRF24X_GET_PLOS_CNT | Extracts the PLOS_CNT bitfield value from an OBSERVE_TX register value. |
| NRF24X_GET_ARC_CNT | Extracts the ARC_CNT bitfield value from an OBSERVE_TX register value. |
| nRF24x CD/ | See the IC product specification for information about the CD/RPD register. |
| nRF24x FIFO_STATUS Register Bits | See the IC product specification for information about the FIFO_STATUS register. |
| nRF24x FEATURE Register Bits | See the IC product specification for information about the FEATURE register. |
See the IC product specification for information about the protocol of the SPI interface.
See the IC product specification for information about register semantics.
See the IC product specification for information about the CONFIG register.
See the IC product specification for information about the STATUS register.
| Variables | |
| nrf24x_status | Storage location for STATUS values. |
| nrf24x_command | When the NRF24X_CMD_IN API macro is used, the command word of the input command to send MUST be stored here before the macro is invoked. |
extern volatile uint8_t nrf24x_command
When the NRF24X_CMD_IN API macro is used, the command word of the input command to send MUST be stored here before the macro is invoked. That is generally the only reason to touch this variable application code will have.
NOTE: Not defined in synchronous mode.
| Macros | |
| NRF24X_CMD_OUT | Initiates an output command to the nRF24x via an asynchronous SPI request. |
| NRF24X_CMD_IN | Initiates an input command to the nRF24x via an asynchronous SPI request. |
| Functions | |
| nrf24x_out_0 | Sends a 0-byte output command (one that consists only of a command word) to the nRF24x. |
| nrf24x_out_1 | Sends a 1-byte output command (one that consists of a command word and a single output data byte) to the nRF24x. |
| nrf24x_out_n | Sends an N-byte output command (one that consists of a command word and a specified number of output data bytes) to the nRF24x. |
| nrf24x_in_1 | Sends a 1-byte input command (one that receives a single input data byte in response) to the nRF24x. |
| nrf24x_in_n | Sends an N-byte input command (one that receives a specified number of input data bytes in response) to the nRF24x. |
| Macros | |
| NRF24X_NONE_PENDING | Special value returned by nrf24x_in_finish when no asynchronous command is pending. |
| Functions | |
| nrf24x_in_finish | Used to finish an asynchronous input command sent to the nRF24x and fetch the received input data. |
Initiates an output command to the nRF24x via an asynchronous SPI request. Function-like macro.
NOTE: Not defined in synchronous mode.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status.
| N | Number of output bytes to transmit, including the command word. |
| B | Pointer to the output bytes to transmit, including the command word. |
SPI_ACTIVE if and only if the SPI request was successfully started, otherwise an error code.
Initiates an input command to the nRF24x via an asynchronous SPI request. Function-like macro.
NOTE: Not defined in synchronous mode.
CAUTION: The command word of the input command to send to the nRF24x MUST be stored in nrf24x_command before this macro is invoked.
| N | Number of input bytes to receive. |
| O | Number of received bytes to discard before getting the input bytes. Note that the sequence of received bytes includes the STATUS register value that the nRF24x returns when the command word is transmitted. |
| B | Pointer to memory to copy the received input bytes into. |
SPI_ACTIVE if and only if the SPI request was successfully started, otherwise an error code.
uint8_t nrf24x_out_0( uint8_t cmd )
Sends a 0-byte output command (one that consists only of a command word) to the nRF24x.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status.
| cmd | Command word of the output command. |
A true value if and only if the SPI request was successfully performed (or started, in asynchronous mode).
uint8_t nrf24x_out_1( uint8_t cmd, uint8_t data )
Sends a 1-byte output command (one that consists of a command word and a single output data byte) to the nRF24x.
NOTE: Not defined when NRF24X_NO_CMD_BFR is defined in asynchronous mode.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status when called in synchronous mode.
| cmd | Command word of the output command. |
| data | Data byte of the output command. |
A true value if and only if the SPI request was successfully performed (or started, in asynchronous mode).
uint8_t nrf24x_out_n( uint8_t cmd, uint8_t n_out, uint8_t * bfr_out )
Sends an N-byte output command (one that consists of a command word and a specified number of output data bytes) to the nRF24x.
NOTE: Not defined when NRF24X_NO_CMD_BFR is defined in asynchronous mode.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status when called in synchronous mode.
| cmd | Command word of the output command. |
| n_out | Number of data bytes to transmit. |
| bfr_out | Pointer to the data bytes to transmit. |
A true value if and only if the SPI request was successfully performed (or started, in asynchronous mode).
uint8_t nrf24x_in_1( uint8_t cmd, uint8_t * data_p )
Sends a 1-byte input command (one that receives a single input data byte in response) to the nRF24x.
NOTE: Not defined when NRF24X_NO_CMD_BFR is defined in asynchronous mode.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status when called in synchronous mode.
| cmd | Command word of the input command. |
| data_p | Pointer to location to copy the received data byte into. Note that this argument is ignored in asynchronous mode, where the input buffer pointer is given as an argument to nrf24x_in_finish. |
A true value if and only if the SPI request was successfully performed (or started, in asynchronous mode).
uint8_t nrf24x_in_n( uint8_t cmd, uint8_t n_in, uint8_t * bfr_in )
Sends an N-byte input command (one that receives a specified number of input data bytes in response) to the nRF24x.
NOTE: Not defined when NRF24X_NO_CMD_BFR is defined in asynchronous mode.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status when called in synchronous mode.
| cmd | Command word of the input command. |
| n_in | Number of data bytes to receive. |
| bfr_in | Pointer to memory to copy received data bytes into. Note that this argument is ignored in asynchronous mode, where the input buffer pointer is given as an argument to nrf24x_in_finish. |
A true value if and only if the SPI request was successfully performed (or started, in asynchronous mode).
Special value returned by nrf24x_in_finish when no asynchronous command is pending.
CAUTION: This is equal to 255/0xff, so that value MUST NOT be used as an actual data byte count. There will generally not be any need for byte counts that large, anyway.
Constant macro.
uint8_t nrf24x_in_finish( uint8_t * bfr_in )
Used to finish an asynchronous input command sent to the nRF24x and fetch the received input data.
NOTE: Not defined if the module is in synchronous mode or NRF24X_NO_CMD_BFR is defined.
NOTE: Writes the STATUS register value returned by the nRF24x to nrf24x_status.
| bfr_in | Pointer to memory to copy received data bytes into. |
The number of data bytes received, or NRF24X_NONE_PENDING if no asynchronous command is pending.
Storage location for STATUS values.
extern volatile uint8_t nrf24x_status
When the NRF24X_CMD_IN API macro is used, the command word of the input command to send MUST be stored here before the macro is invoked.
extern volatile uint8_t nrf24x_command
Sends a 0-byte output command (one that consists only of a command word) to the nRF24x.
uint8_t nrf24x_out_0( uint8_t cmd )
Sends a 1-byte output command (one that consists of a command word and a single output data byte) to the nRF24x.
uint8_t nrf24x_out_1( uint8_t cmd, uint8_t data )
Sends an N-byte output command (one that consists of a command word and a specified number of output data bytes) to the nRF24x.
uint8_t nrf24x_out_n( uint8_t cmd, uint8_t n_out, uint8_t * bfr_out )
Sends a 1-byte input command (one that receives a single input data byte in response) to the nRF24x.
uint8_t nrf24x_in_1( uint8_t cmd, uint8_t * data_p )
Sends an N-byte input command (one that receives a specified number of input data bytes in response) to the nRF24x.
uint8_t nrf24x_in_n( uint8_t cmd, uint8_t n_in, uint8_t * bfr_in )
Used to finish an asynchronous input command sent to the nRF24x and fetch the received input data.
uint8_t nrf24x_in_finish( uint8_t * bfr_in )
Initiates an SPI request operation consisting of a transmit phase followed by a receive phase.
spi_state spihelper_request( uint8_t n_out, volatile const uint8_t * bfr_out, uint8_t n_in, uint8_t offset_in, volatile uint8_t * bfr_in )
Synchronously exchanges a single pair of bytes via the SPI peripheral.
uint8_t spihelper_exchange_bytes( uint8_t data_out )