Struct RF24

pub struct RF24<SPI, DO, DELAY> {
    pub tx_delay: u32,
    pub ce_pin: DO,
    /* private fields */
}

This struct implements the Esb* traits for the nRF24L01 transceiver.

Additionally, there are some functions implemented that are specific to the nRF24L01.

Fields

tx_delay: u32

The delay (in microseconds) in which RF24::as_tx() will wait for ACK packets to complete.

If the auto-ack feature is disabled, then this can be set as low as 0. If the auto-ack feature is enabled, then set to 100 microseconds minimum on generally faster devices (like RPi).

Since this value can be optimized per the radio’s data rate, this value is automatically adjusted when calling EsbDataRate::set_data_rate(). If setting this to a custom value be sure, to set it after changing the radio’s data rate.

If set to 0, then the concurrent outgoing ACK packet (when auto-ack is enabled) may fail to transmit when exiting RX mode with RF24::as_tx().

ce_pin: DO

The CE pin for the radio.

This really only exposed for advanced manipulation of active TX mode. It is strongly recommended to enter RX or TX mode using RF24::as_rx() and RF24::as_tx() because those methods guarantee proper radio usage.

Implementations

impl<SPI, DO, DELAY> RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

pub fn new(ce_pin: DO, spi: SPI, delay_impl: DELAY) -> RF24<SPI, DO, DELAY>

Instantiate an RF24 object for use on the specified spi bus with the given ce_pin.

The radio’s CSN pin (aka Chip Select pin) shall be defined when instantiating the SpiDevice object (passed to the spi parameter).

pub fn is_plus_variant(&self) -> bool

Is this radio a nRF24L01+ variant?

The bool that this function returns is only valid after calling init().

pub fn rpd(&mut self) -> Result<bool, Nrf24Error<SpiError, OutputPinError>>

Was the Received Power Detection (RPD) trigger?

This flag is asserted during an RX session (after a mandatory 130 microseconds duration) if a signal stronger than -64 dBm was detected.

Note that if a payload was placed in RX mode, then that means the signal used to transmit that payload was stronger than either

• -82 dBm in 2 Mbps DataRate
• -85 dBm in 1 Mbps DataRate
• -94 dBm in 250 Kbps DataRate

Sensitivity may vary based of the radio’s model and manufacturer. The information above is stated in the nRF24L01+ datasheet.

pub fn start_carrier_wave( &mut self, level: PaLevel, channel: u8, ) -> Result<(), Nrf24Error<SpiError, OutputPinError>>

Start a constant carrier wave

This functionality is meant for hardware tests (in conjunction with RF24::rpd()). Typically, this behavior is required by government agencies to enforce regional restrictions.

pub fn stop_carrier_wave( &mut self, ) -> Result<(), Nrf24Error<SpiError, OutputPinError>>

Stop the constant carrier wave started via RF24::start_carrier_wave().

This function leaves the radio in a configuration that may be undesired or unexpected because of the setup involved in RF24::start_carrier_wave(). The PaLevel and channel passed to RF24::start_carrier_wave() are still set. If RF24::is_plus_variant() returns true, the following features are all disabled:

• auto-ack
• CRC
• auto-retry

pub fn set_lna( &mut self, enable: bool, ) -> Result<(), Nrf24Error<SpiError, OutputPinError>>

Enable or disable the LNA feature.

This is enabled by default (regardless of chip variant). See PaLevel for effective behavior.

On nRF24L01+ modules with a builtin antenna, this feature is always enabled. For clone’s and module’s with a separate PA/LNA circuit (external antenna), this function may not behave exactly as expected. Consult the radio module’s manufacturer.

Trait Implementations

impl<SPI, DO, DELAY> EsbAutoAck for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn set_ack_payloads(&mut self, enable: bool) -> Result<(), Self::Error>

Enable or disable the custom ACK (acknowledgement) payloads attached to auto-ack packets.

fn get_ack_payloads(&self) -> bool

Get the current setting of the ACK payloads feature.

fn set_auto_ack(&mut self, enable: bool) -> Result<(), Self::Error>

Enable or disable the auto-ack (automatic acknowledgement) feature for all pipes.

fn set_auto_ack_pipe( &mut self, enable: bool, pipe: u8, ) -> Result<(), Self::Error>

Set the auto-ack feature for an individual pipe.

fn allow_ask_no_ack(&mut self, enable: bool) -> Result<(), Self::Error>

Allow the functionality of the ask_no_ack parameter in EsbRadio::send() and EsbRadio::write().

fn write_ack_payload( &mut self, pipe: u8, buf: &[u8], ) -> Result<bool, Self::Error>

Write a buf to the radio’s TX FIFO for use with automatic ACK packets.

fn set_auto_retries(&mut self, delay: u8, count: u8) -> Result<(), Self::Error>

Set the number of retry attempts and delay between retry attempts when transmitting a payload.

impl<SPI, DO, DELAY> EsbChannel for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn set_channel(&mut self, channel: u8) -> Result<(), Self::Error>

The nRF24L01 support 126 channels. The specified channel is clamped to the range [0, 125].

fn get_channel(&mut self) -> Result<u8, Self::Error>

See also RF24::set_channel().

impl<SPI, DO, DELAY> EsbCrcLength for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn get_crc_length(&mut self) -> Result<CrcLength, Self::Error>

Get the currently configured CRC (Cyclical Redundancy Checksum) length

fn set_crc_length(&mut self, crc_length: CrcLength) -> Result<(), Self::Error>

Set the radio’s CRC (Cyclical Redundancy Checksum) length

impl<SPI, DO, DELAY> EsbDataRate for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn get_data_rate(&mut self) -> Result<DataRate, Self::Error>

Get the currently configured Data Rate

fn set_data_rate(&mut self, data_rate: DataRate) -> Result<(), Self::Error>

Set the radio’s Data Rate

impl<SPI, DO, DELAY> EsbDetails for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn print_details(&mut self) -> Result<(), Self::Error>

Print details about radio’s current configuration.

impl<SPI, DO, DELAY> EsbFifo for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn flush_rx(&mut self) -> Result<(), Self::Error>

Use this to discard all 3 layers in the radio’s RX FIFO.

fn flush_tx(&mut self) -> Result<(), Self::Error>

Use this to discard all 3 layers in the radio’s TX FIFO.

fn available(&mut self) -> Result<bool, Self::Error>

Is there a payload available in the radio’s RX FIFO?

fn available_pipe(&mut self, pipe: &mut u8) -> Result<bool, Self::Error>

This is similar to EsbFifo::available() except the pipe parameter is given a mutable u8 value, and the pipe number that received the data is stored to it.

fn get_fifo_state(&mut self, about_tx: bool) -> Result<FifoState, Self::Error>

Get the state of the specified FIFO.

impl<SPI, DO, DELAY> EsbInit for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn init(&mut self) -> Result<(), Self::Error>

Initialize the radio’s hardware using the SpiDevice and OutputPin given to RF24::new().

fn with_config(&mut self, config: &RadioConfig) -> Result<(), Self::Error>

Reconfigure the radio using the given config object.

impl<SPI, DO, DELAY> EsbPaLevel for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn get_pa_level(&mut self) -> Result<PaLevel, Self::Error>

Get the currently configured Power Amplitude Level (PA Level)

fn set_pa_level(&mut self, pa_level: PaLevel) -> Result<(), Self::Error>

Set the radio’s Power Amplitude Level (PA Level)

impl<SPI, DO, DELAY> EsbPayloadLength for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn set_payload_length(&mut self, length: u8) -> Result<(), Self::Error>

Set the radio’s static payload length.

fn get_payload_length(&mut self) -> Result<u8, Self::Error>

Get the currently configured static payload length used on pipe 0

fn set_dynamic_payloads(&mut self, enable: bool) -> Result<(), Self::Error>

Set the dynamic payloads feature for all pipes.

fn get_dynamic_payloads(&self) -> bool

Get the current setting of the dynamic payloads feature.

fn get_dynamic_payload_length(&mut self) -> Result<u8, Self::Error>

Get the dynamic length of the next available payload in the RX FIFO.

impl<SPI, DO, DELAY> EsbPipe for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn close_rx_pipe(&mut self, pipe: u8) -> Result<(), Self::Error>

If the given pipe number is not in range [0, 5], then this function does nothing.

fn open_rx_pipe(&mut self, pipe: u8, address: &[u8]) -> Result<(), Self::Error>

Open a specified pipe for receiving data when radio is in RX mode.

fn set_address_length(&mut self, length: u8) -> Result<(), Self::Error>

Set the address length (applies to all pipes).

fn get_address_length(&mut self) -> Result<u8, Self::Error>

Get the currently configured address length (applied to all pipes).

impl<SPI, DO, DELAY> EsbPower for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn power_down(&mut self) -> Result<(), Self::Error>

After calling EsbRadio::as_rx(), a non-PA/LNA radio will consume about 13.5mA at PaLevel::MAX. During active transmission (including RX role when transmitting an auto-ACK packet), a non-PA/LNA radio will consume about 11.5mA. In power standby mode (when not receiving nor transmitting), a non-PA/LNA radio will consume about 26uA (.026mA). In full power down mode (a sleep state), the radio will consume approximately 900nA (.0009mA).

fn is_powered(&self) -> bool

Is the radio powered up?

fn power_up(&mut self, delay: Option<u32>) -> Result<(), Self::Error>

Power up the radio.

impl<SPI, DO, DELAY> EsbRadio for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn send(&mut self, buf: &[u8], ask_no_ack: bool) -> Result<bool, Self::Error>

See EsbRadio::send() for implementation-agnostic detail.

This function calls RF24::flush_tx() upon entry, but it does not deactivate the radio’s CE pin upon exit.

fn write( &mut self, buf: &[u8], ask_no_ack: bool, start_tx: bool, ) -> Result<bool, Self::Error>

See EsbRadio::write() for implementation-agnostic detail. Remember, the nRF24L01’s active TX mode is activated by the nRF24L01’s CE pin.

To transmit a payload the radio’s CE pin must be active for at least 10 microseconds. The caller is required to ensure the CE pin has been active for at least 10 microseconds when using this function, thus non-blocking behavior.

fn read(&mut self, buf: &mut [u8], len: Option<u8>) -> Result<u8, Self::Error>

See EsbRadio::read() for implementation-agnostic detail.

Remember that each call to RF24::read() fetches data from the RX FIFO beginning with the first byte from the first available payload. A payload is not removed from the RX FIFO until it’s entire length (or more) is fetched.

• If len is less than the available payload’s length, then the payload remains in the RX FIFO.
• If len is greater than the first of multiple available payloads, then the data saved to the buf parameter’s object will be supplemented with data from the next available payload.
• If len is greater than the last available payload’s length, then the last byte in the payload is used as padding for the data saved to the buf parameter’s object. The nRF24L01 will repeatedly use the last byte from the last payload even when RF24::read() is called with an empty RX FIFO.

fn as_rx(&mut self) -> Result<(), Self::Error>

Put the radio into active RX mode.

fn as_tx(&mut self, tx_address: Option<&[u8]>) -> Result<(), Self::Error>

Put the radio into inactive TX mode.

fn is_rx(&self) -> bool

Is the radio in RX mode?

fn resend(&mut self) -> Result<bool, Self::Error>

Similar to EsbRadio::send() but specifically for failed transmissions.

fn rewrite(&mut self) -> Result<(), Self::Error>

Similar to EsbRadio::write() but specifically for failed transmissions.

fn get_last_arc(&mut self) -> Result<u8, Self::Error>

Get the Auto-Retry Count (ARC) about the previous transmission.

impl<SPI, DO, DELAY> EsbStatus for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

fn set_status_flags(&mut self, flags: StatusFlags) -> Result<(), Self::Error>

Configure which status flags trigger the radio’s IRQ pin.

fn clear_status_flags(&mut self, flags: StatusFlags) -> Result<(), Self::Error>

Clear the radio’s IRQ status flags

fn update(&mut self) -> Result<(), Self::Error>

Refresh the internal cache of status byte (which is also saved from every SPI transaction).

fn get_status_flags(&self, flags: &mut StatusFlags)

Get the StatusFlags state that was cached from the latest SPI transaction.

impl<SPI, DO, DELAY> RadioErrorType for RF24<SPI, DO, DELAY>

where SPI: SpiDevice, DO: OutputPin, DELAY: DelayNs,

type Error = Nrf24Error<ErrorKind, ErrorKind>