API documentation

Setting addresses and PAN ID of the device

group nrf_802154_addresses

Functions

void nrf_802154_pan_id_set(const uint8_t *p_pan_id)

Sets the PAN ID used by the device.

This function makes a copy of the PAN ID.

Parameters:

  • p_pan_id – [in] Pointer to the PAN ID (2 bytes, little-endian).

void nrf_802154_extended_address_set(const uint8_t *p_extended_address)

Sets the extended address of the device.

This function makes a copy of the address.

Parameters:

  • p_extended_address – [in] Pointer to the extended address (8 bytes, little-endian).

void nrf_802154_short_address_set(const uint8_t *p_short_address)

Sets the short address of the device.

This function makes a copy of the address.

Parameters:

  • p_short_address – [in] Pointer to the short address (2 bytes, little-endian).

Functions to calculate data given by the driver

group nrf_802154_data

Functions

uint8_t nrf_802154_energy_level_from_dbm_calculate(int8_t ed_dbm)

Converts energy level received during the energy detection procedure to IEEE Std. 802.15.4-2015 compliant value.

Parameters:

  • ed_dbm – Energy level in dBm

Returns:

uint8_t Energy level in units compliant to IEEE Std. 802.15.4-2015 chapter 10.2.5.

uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm)

Converts a given dBm level to a CCA energy detection threshold value.

Parameters:

  • dbm – [in] Energy level in dBm used to calculate the CCAEDTHRES value.

Returns:

Energy level value corresponding to the given dBm level that is to be written to the CCACTRL register.

uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)

Calculates the timestamp of the first symbol of the preamble in a received frame.

Deprecated:

This function is deprecated. Use nrf_802154_timestamp_end_to_phr_convert instead and adjust the code that calls this function to rely on the timestamp of the first symbol of the PHR, not the timestamp of the first symbol of the frame.

Parameters:

  • end_timestamp – [in] Timestamp of the end of the last symbol in the frame, in microseconds.

  • psdu_length – [in] Number of bytes in the frame PSDU.

Returns:

Timestamp of the beginning of the first preamble symbol of a given frame, in microseconds.

uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)

Calculates the timestamp of the MAC Header in a received frame.

Deprecated:

This function is deprecated. Use nrf_802154_timestamp_end_to_phr_convert instead and adjust the code that calls this function to rely on the timestamp of the first symbol of the PHR, not the MAC Header timestamp.

Parameters:

  • end_timestamp – [in] Timestamp of the end of the last symbol in the frame, in microseconds.

  • psdu_length – [in] Number of bytes in the frame PSDU.

Returns:

Timestamp of the MHR of a given frame, in microseconds.

uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length)

Converts the timestamp of the frame’s end to the timestamp of the start of its PHR.

This function calculates the time when the first symbol of the PHR is at the local antenna. Note that this time is equivalent to: the end of the frame’s SFD and RMARKER as defined in’ IEEE 802.15.4-2020, Section 6.9.1.

Parameters:

  • end_timestamp – [in] Timestamp of the end of the last symbol in the frame, in microseconds.

  • psdu_length – [in] Number of bytes in the frame PSDU.

Returns:

Timestamp of the start of the PHR of a given frame, in microseconds.

uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp)

Converts the timestamp of the frame’s PHR to the timestamp of the start of its SHR.

This function converts the time when the first symbol of the frame’s PHR is at the local antenna to the timestamp of the start of the frame’s SHR.

Parameters:

  • phr_timestamp – [in] Timestamp of the frame’s PHR.

Returns:

Timestamp of the start of the SHR of a given frame, in microseconds.

uint64_t nrf_802154_timestamp_phr_to_mhr_convert(uint64_t phr_timestamp)

Converts the timestamp of the frame’s PHR to the timestamp of the start of its MHR.

This function converts the time when the first symbol of the frame’s PHR is at the local antenna to the timestamp of the start of the frame’s MHR.

Parameters:

  • phr_timestamp – [in] Timestamp of the frame’s PHR.

Returns:

Timestamp of the start of the MHR of a given frame, in microseconds.

Functions to request FSM transitions and check the current state

group nrf_802154_transitions

Functions

nrf_802154_state_t nrf_802154_state_get(void)

Gets the current state of the radio.

bool nrf_802154_sleep(void)

Changes the radio state to the RADIO_STATE_SLEEP state.

The sleep state is the lowest power state. In this state, the radio cannot transmit or receive frames. It is the only state in which the driver releases the high-frequency clock and does not request timeslots from a radio arbiter.

Note

If another module requests it, the high-frequency clock may be enabled even in the radio sleep state.

Return values:

  • true – The radio changes its state to the low power mode.

  • false – The driver could not schedule changing state.

nrf_802154_sleep_error_t nrf_802154_sleep_if_idle(void)

Changes the radio state to the RADIO_STATE_SLEEP state if the radio is idle.

The sleep state is the lowest power state. In this state, the radio cannot transmit or receive frames. It is the only state in which the driver releases the high-frequency clock and does not request timeslots from a radio arbiter.

Note

If another module requests it, the high-frequency clock may be enabled even in the radio sleep state.

Return values:

  • NRF_802154_SLEEP_ERROR_NONE – The radio changes its state to the low power mode.

  • NRF_802154_SLEEP_ERROR_BUSY – The driver could not schedule changing state.

bool nrf_802154_receive(void)

Changes the radio state to RADIO_STATE_RX.

In the receive state, the radio receives frames and may automatically send ACK frames when appropriate. The received frame is reported to the higher layer by a call to nrf_802154_received.

Return values:

  • true – The radio enters the receive state.

  • false – The driver could not enter the receive state.

bool nrf_802154_receive_at(uint64_t rx_time, uint32_t timeout, uint8_t channel, uint32_t id)

Requests reception at the specified time.

This function works as a delayed version of nrf_802154_receive. It is asynchronous. It queues the delayed reception using the Radio Scheduler module. If the delayed reception cannot be performed (nrf_802154_receive_at would return false) or the requested reception timeslot is denied, nrf_802154_receive_failed is called with the NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED argument.

If the requested reception time is in the past, the function returns false and does not schedule reception.

A scheduled reception can be cancelled by a call to nrf_802154_receive_at_cancel.

Note

The identifier id must be unique. It must not have the same value as identifiers of other delayed timeslots active at the moment, so that it can be mapped unambiguously to an active delayed operation if the request is successful. In particular, none of the reserved identifiers can be used.

Parameters:

  • rx_time – [in] Absolute time used by the SL Timer, in microseconds (us).

  • timeout – [in] Reception timeout (counted from rx_time), in microseconds (us).

  • channel – [in] Radio channel on which the frame is to be received.

  • id – [in] Identifier of the scheduled reception window. If the reception has been scheduled successfully, the value of this parameter can be used in nrf_802154_receive_at_cancel to cancel it.

Return values:

  • true – The reception procedure was scheduled.

  • false – The driver could not schedule the reception procedure.

bool nrf_802154_receive_at_cancel(uint32_t id)

Cancels a delayed reception scheduled by a call to nrf_802154_receive_at.

If the receive window has been scheduled but has not started yet, this function prevents entering the receive window. If the receive window has been scheduled and has already started, the radio remains in the receive state, but a window timeout will not be reported.

Parameters:

  • id – [in] Identifier of the delayed reception window to be cancelled. If the provided value does not refer to any scheduled or active receive window, the function returns false.

Return values:

  • true – The delayed reception was scheduled and successfully cancelled.

  • false – No delayed reception was scheduled.

bool nrf_802154_transmit_raw(uint8_t *p_data, const nrf_802154_transmit_metadata_t *p_metadata)

Changes the radio state to RADIO_STATE_TX.

In the transmit state, the radio transmits a given frame. If requested, it waits for an ACK frame. Depending on NRF_802154_ACK_TIMEOUT_ENABLED, the radio driver automatically stops waiting for an ACK frame or waits indefinitely for an ACK frame. If it is configured to wait, the MAC layer is responsible for calling nrf_802154_receive or nrf_802154_sleep after the ACK timeout. The transmission result is reported to the higher layer by calls to nrf_802154_transmitted_raw or nrf_802154_transmit_failed.

* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC header and payload                                    | FCS        |
* +-----+-----------------------------------------------------------+------------+
*       |                                                                        |
*       | <---------------------------- PHR -----------------------------------> |
*

Note

If the CPU is halted or interrupted while this function is executed, nrf_802154_transmitted_raw or nrf_802154_transmit_failed can be called before this function returns a result.

Note

This function is implemented in zero-copy fashion. It passes the given buffer pointer to the RADIO peripheral.

Note

This function is available if NRF_802154_USE_RAW_API is enabled.

Parameters:

  • p_data – [in] Pointer to the array with data to transmit. The first byte must contain frame length (including FCS). The following bytes contain data. The CRC is computed automatically by the radio hardware. Therefore, the FCS field can contain any bytes.

  • p_metadata – [in] Pointer to metadata structure. Contains detailed properties of data to transmit. If NULL following metadata are used:

    Field

    Value

    frame_props

    NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT

    cca

    true

Return values:

  • true – The transmission procedure was scheduled.

  • false – The driver could not schedule the transmission procedure.

bool nrf_802154_transmit(const uint8_t *p_data, uint8_t length, const nrf_802154_transmit_metadata_t *p_metadata)

Changes the radio state to transmit.

In the transmit state, the radio transmits a given frame. If requested, it waits for an ACK frame. Depending on NRF_802154_ACK_TIMEOUT_ENABLED, the radio driver automatically stops waiting for an ACK frame or waits indefinitely for an ACK frame. If it is configured to wait, the MAC layer is responsible for calling nrf_802154_receive or nrf_802154_sleep after the ACK timeout. The transmission result is reported to the higher layer by calls to nrf_802154_transmitted or nrf_802154_transmit_failed.

*       p_data
*       v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC header and payload                                    | FCS        |
* +-----+-----------------------------------------------------------+------------+
*       |                                                           |
*       | <------------------ length -----------------------------> |
*

Note

If the CPU is halted or interrupted while this function is executed, nrf_802154_transmitted or nrf_802154_transmit_failed must be called before this function returns a result.

Note

This function copies the given buffer. It maintains an internal buffer, which is used to make a frame copy. To prevent unnecessary memory consumption and to perform zero-copy transmission, use nrf_802154_transmit_raw instead.

Note

This function is available if NRF_802154_USE_RAW_API is disabled.

Parameters:

  • p_data – [in] Pointer to the array with the payload of data to transmit. The array should exclude PHR or FCS fields of the 802.15.4 frame.

  • length – [in] Length of the given frame. This value must exclude PHR and FCS fields from the given frame (exact size of buffer pointed to by p_data).

  • p_metadata – [in] Pointer to metadata structure. Contains detailed properties of data to transmit. If NULL following metadata are used:

    Field

    Value

    frame_props

    NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT

    cca

    true

Return values:

  • true – The transmission procedure was scheduled.

  • false – The driver could not schedule the transmission procedure.

bool nrf_802154_transmit_raw_at(uint8_t *p_data, uint64_t tx_time, const nrf_802154_transmit_at_metadata_t *p_metadata)

Requests transmission at the specified time.

This function works as a delayed version of nrf_802154_transmit_raw. It is asynchronous. It queues the delayed transmission using the Radio Scheduler module and performs it at the specified time.

If the delayed transmission is successfully performed, nrf_802154_transmitted_raw is called. If the delayed transmission cannot be performed ( nrf_802154_transmit_raw would return false) or the requested transmission timeslot is denied, nrf_802154_transmit_failed with the NRF_802154_TX_ERROR_TIMESLOT_DENIED argument is called.

Additional CCA attempts can be requested by the caller through p_metadata. In that case CCA procedure is repeated back-to-back either until it returns idle channel and the transmission starts, or until 1 + p_metadata->extra_cca_attempts CCA attempts are performed. The maximum allowed number of additional CCA attempts is 254 so that the total number of CCA attempts doesn’t exceed 255.

This function is designed to transmit the first symbol of SHR at tx_time provided that the number of CCA attempts that will be performed is deterministic, which is only the case when no attempts are performed or when a single attempt is performed. Otherwise, the function assumes that tx_time points to a moment where the transmission would start if the first CCA attempt detected idle channel. If the first CCA detects busy channel and additional CCA attempts follow, the moment of transmission (first symbol of SHR) is delayed by the time taken by additional CCA attempts, which is a multiple of the duration of a single CCA attempt.

The below diagram shows an example sequence where two additional CCA attempts are performed. TT denotes turnaround time necessary to switch from CCA to Tx. tx_time points to a moment in time that occurs TT after the first CCA finishes.

*           tx_time           frame start
*              |                   |
*              |                   |
*              v                   v
* +---------+---------+---------+--+----------+-----+-------------------------+
* |   CCA   |   CCA   |   CCA   |TT|    SHR   | PHR | MAC Header and payload  |
* +---------+---------+---------+--+----------+-----+-------------------------+
*           |         |         |
*           v         v         v
*          BUSY      BUSY      IDLE
*

If the requested transmission time is in the past, the function returns false and does not schedule transmission.

A successfully scheduled transmission can be cancelled by a call to nrf_802154_transmit_at_cancel.

Note

This function is implemented in a zero-copy fashion. It passes the given buffer pointer to the RADIO peripheral.

Parameters:

  • p_data – [in] Pointer to the array with data to transmit. The first byte must contain the frame length (including FCS). The following bytes contain data. The CRC is computed automatically by the radio hardware. Therefore, the FCS field can contain any bytes.

  • tx_time – [in] Absolute time used by the SL Timer, in microseconds (us).

  • p_metadata – [in] Pointer to metadata structure. Contains detailed properties of data to transmit. If NULL following metadata are used:

    Field

    Value

    frame_props

    NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT

    cca

    true

    channel

    As returned by nrf_802154_channel_get

    tx_power

    As set with nrf_802154_tx_power_set

    extra_cca_attempts

    0

Return values:

  • true – The transmission procedure was scheduled.

  • false – The driver could not schedule the transmission procedure.

bool nrf_802154_transmit_at_cancel(void)

Cancels a delayed transmission scheduled by a call to nrf_802154_transmit_raw_at.

If a delayed transmission has been scheduled but the transmission has not been started yet, a call to this function prevents the transmission. If the transmission is ongoing, it will not be aborted.

If a delayed transmission has not been scheduled (or has already finished), this function does not change state and returns false.

Return values:

  • true – The delayed transmission was scheduled and successfully cancelled.

  • false – No delayed transmission was scheduled.

bool nrf_802154_energy_detection(uint32_t time_us)

Changes the radio state to energy detection.

In the energy detection state, the radio detects the maximum energy for a given time. The result of the detection is reported to the higher layer by nrf_802154_energy_detected.

Note

nrf_802154_energy_detected can be called before this function returns a result.

Note

Performing the energy detection procedure can take longer than requested in time_us. The procedure is performed only during the timeslots granted by a radio arbiter. It can be interrupted by other protocols using the radio hardware. If the procedure is interrupted, it is automatically continued and the sum of time periods during which the procedure is carried out is not less than the requested time_us.

Parameters:

  • time_us – [in] Duration of energy detection procedure. The given value is rounded up to multiplication of 8 symbols (128 us).

Return values:

  • true – The energy detection procedure was scheduled.

  • false – The driver could not schedule the energy detection procedure.

bool nrf_802154_cca(void)

Changes the radio state to RADIO_STATE_CCA.

In the CCA state, the radio verifies if the channel is clear. The result of the verification is reported to the higher layer by nrf_802154_cca_done.

Note

nrf_802154_cca_done can be called before this function returns a result.

Return values:

  • true – The CCA procedure was scheduled.

  • false – The driver could not schedule the CCA procedure.

bool nrf_802154_continuous_carrier(void)

Changes the radio state to continuous carrier.

Note

When the radio is emitting continuous carrier signals, it blocks all transmissions on the selected channel. This function is to be called only during radio tests. Do not use it during normal device operation.

Return values:

  • true – The continuous carrier procedure was scheduled.

  • false – The driver could not schedule the continuous carrier procedure.

bool nrf_802154_modulated_carrier(const uint8_t *p_data)

Changes the radio state to modulated carrier.

Note

When the radio is emitting modulated carrier signals, it blocks all transmissions on the selected channel. This function is to be called only during radio tests. Do not use it during normal device operation.

Parameters:

  • p_data – [in] Pointer to a buffer to modulate the carrier with. The first byte is the data length.

Return values:

  • true – The modulated carrier procedure was scheduled.

  • false – The driver could not schedule the modulated carrier procedure.

Calls to the higher layer

group nrf_802154_calls

Functions

void nrf_802154_cca_done(bool channel_free)

Notifies that the CCA procedure has finished.

Parameters:

  • channel_free – [in] Indication if the channel is free.

void nrf_802154_cca_failed(nrf_802154_cca_error_t error)

Notifies that the CCA procedure failed.

Parameters:

  • error – [in] Reason of the failure.

void nrf_802154_energy_detected(const nrf_802154_energy_detected_t *p_result)

Notifies that the energy detection procedure finished.

Parameters:

  • p_result – [in] Pointer to structure containing the result of the operation. The pointer is valid within the nrf_802154_energy_detected only.

void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error)

Notifies that the energy detection procedure failed.

Parameters:

  • error – [in] Reason of the failure.

void nrf_802154_tx_ack_started(const uint8_t *p_data)

Notifies about the start of the ACK frame transmission.

Note

If a call to this function is performed by the same CPU running core of nRF 802.15.4 Radio Driver (non serialized call to nrf_802154_tx_ack_started) the function must be very short to prevent dropping frames by the driver. If a call to this function is performed by a CPU through a serialization layer the call can be slightly delayed. The call can happen even after an ACK frame is fully transmitted. It is guaranteed that a call to nrf_802154_tx_ack_started occurs before a call to nrf_802154_received_timestamp_raw related to the same received frame.

Parameters:

  • p_data – [in] Pointer to a buffer with PHR and PSDU of the ACK frame.

void nrf_802154_received_raw(uint8_t *p_data, int8_t power, uint8_t lqi)

Notifies that a frame was received. 

* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload                                    | FCS        |
* +-----+-----------------------------------------------------------+------------+
*       |                                                                        |
*       | <---------------------------- PHR -----------------------------------> |
*

Note

Currently this callout is only available on the CPU which is running the core of the radio driver. If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead.

Note

The buffer pointed to by p_data is not modified by the radio driver (and cannot be used to receive a frame) until nrf_802154_buffer_free_raw is called.

Note

The buffer pointed to by p_data may be modified by the function handler (and other modules) until nrf_802154_buffer_free_raw is called.

Note

This callout is called by the nRF 802.15.4 Radio Driver if NRF_802154_USE_RAW_API is enabled. Default implementation of this function provided by the nRF 802.15.4 Radio Driver calls nrf_802154_received_timestamp_raw .

Parameters:

  • p_data – [in] Pointer to a buffer that contains PHR and PSDU of the received frame. The first byte in the buffer is the length of the frame (PHR). The following bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS. FCS is already verified by the hardware and may be modified by the hardware.

  • power – [in] RSSI of the received frame.

  • lqi – [in] LQI of the received frame.

void nrf_802154_received_timestamp_raw(uint8_t *p_data, int8_t power, uint8_t lqi, uint64_t time)

Notifies that a frame was received at a given time.

This function works like nrf_802154_received_raw and adds a timestamp to the parameter list.

Note

The received frame usually contains a timestamp. However, due to a race condition, the timestamp may be invalid. This erroneous situation is indicated by the NRF_802154_NO_TIMESTAMP value of the time parameter.

Parameters:

  • p_data – [in] Pointer to a buffer that contains PHR and PSDU of the received frame. The first byte in the buffer is the length of the frame (PHR). The following bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS. FCS is already verified by the hardware and may be modified by the hardware.

  • power – [in] RSSI of the received frame.

  • lqi – [in] LQI of the received frame.

  • time – [in] Timestamp taken when the last symbol of the frame was received, in microseconds (us), or NRF_802154_NO_TIMESTAMP if the timestamp is invalid.

void nrf_802154_received(uint8_t *p_data, uint8_t length, int8_t power, uint8_t lqi)

Notifies that a frame was received. 

*       p_data
*       v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload                                    | FCS        |
* +-----+-----------------------------------------------------------+------------+
*       |                                                           |
*       | <------------------ length -----------------------------> |
*

Note

The buffer pointed to by p_data is not modified by the radio driver (and cannot be used to receive a frame) until nrf_802154_buffer_free is called.

Note

The buffer pointed to by p_data can be modified by the function handler (and other modules) until nrf_802154_buffer_free is called.

Note

This callout is called by the nRF 802.15.4 Radio Driver if NRF_802154_USE_RAW_API is disabled. Default implementation of this function provided by the nRF 802.15.4 Radio Driver calls nrf_802154_received_timestamp .

Parameters:

  • p_data – [in] Pointer to a buffer that contains only the payload of the received frame (PSDU without FCS).

  • length – [in] Length of the received payload.

  • power – [in] RSSI of the received frame.

  • lqi – [in] LQI of the received frame.

void nrf_802154_received_timestamp(uint8_t *p_data, uint8_t length, int8_t power, uint8_t lqi, uint32_t time)

Notifies that a frame was received at a given time.

This function works like nrf_802154_received and adds a timestamp to the parameter list.

Note

The received frame usually contains a timestamp. However, due to a race condition, the timestamp may be invalid. This erroneous situation is indicated by the NRF_802154_NO_TIMESTAMP value of the time parameter.

Note

This callout is called by the default implementation of nrf_802154_received .

Parameters:

  • p_data – [in] Pointer to a buffer that contains only the payload of the received frame (PSDU without FCS).

  • length – [in] Length of the received payload.

  • power – [in] RSSI of the received frame.

  • lqi – [in] LQI of the received frame.

  • time – [in] Timestamp taken when the last symbol of the frame was received, in microseconds (us), or NRF_802154_NO_TIMESTAMP if the timestamp is invalid.

void nrf_802154_receive_failed(nrf_802154_rx_error_t error, uint32_t id)

Notifies that the reception of a frame failed.

Parameters:

  • error – [in] Error code that indicates the reason of the failure.

  • id – [in] Identifier of reception window the error occurred in. If the error is related to a delayed reception window requested through nrf_802154_receive_at, the value of id equals the identifier of the scheduled reception window. Otherwise, the value of id equals NRF_802154_RESERVED_IMM_RX_WINDOW_ID.

void nrf_802154_transmitted_raw(uint8_t *p_frame, const nrf_802154_transmit_done_metadata_t *p_metadata)

Notifies that a frame was transmitted.

Note

If ACK was requested for the transmitted frame, this function is called after a proper ACK is received. If ACK was not requested, this function is called just after transmission has ended.

Note

The buffer pointed to by nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack is not modified by the radio driver (and cannot be used to receive a frame) until nrf_802154_buffer_free_raw is called.

Note

The buffer pointed to by nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack may be modified by the function handler (and other modules) until nrf_802154_buffer_free_raw is called.

Note

nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the granularity of the timer driver in the platform/timer directory.

Note

This callout is called by the nRF 802.15.4 Radio Driver if NRF_802154_USE_RAW_API is enabled.

Parameters:

  • p_frame – [in] Pointer to a buffer that contains PHR and PSDU of the transmitted frame.

  • p_metadata – [in] Pointer to a metadata structure describing frame passed in p_frame.

void nrf_802154_transmitted(uint8_t *p_frame, const nrf_802154_transmit_done_metadata_t *p_metadata)

Notifies that a frame was transmitted.

Note

If ACK was requested for the transmitted frame, this function is called after a proper ACK is received. If ACK was not requested, this function is called just after transmission has ended.

Note

The buffer pointed to by nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack is not modified by the radio driver (and cannot be used to receive a frame) until nrf_802154_buffer_free is called.

Note

The buffer pointed to by nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack may be modified by the function handler (and other modules) until nrf_802154_buffer_free is called.

Note

The next higher layer must handle either nrf_802154_transmitted or nrf_802154_transmitted_raw. It should not handle both functions.

Note

nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the granularity of the timer driver in the platform/timer directory.

Note

Including a timestamp for received frames uses resources like CPU time and memory. If the timestamp is not required, use nrf_802154_received instead.

Note

This callout is called by the nRF 802.15.4 Radio Driver if NRF_802154_USE_RAW_API is disabled.

Parameters:

  • p_frame – [in] Pointer to a buffer that contains PHR and PSDU of the transmitted frame.

  • p_metadata – [in] Pointer to a metadata structure describing frame passed in p_frame.

void nrf_802154_transmit_failed(uint8_t *p_frame, nrf_802154_tx_error_t error, const nrf_802154_transmit_done_metadata_t *p_metadata)

Notifies that a frame was not transmitted due to a busy channel.

This function is called if the transmission procedure fails.

Note

Frame data values in nrf_802154_transmit_done_metadata_t::data are invalid for nrf_802154_transmit_failed callout.

Parameters:

  • p_frame – [in] Pointer to a buffer that contains PHR and PSDU of the frame that was not transmitted.

  • error – [in] Reason of the failure.

  • p_metadata – [in] Pointer to a metadata structure describing frame passed in p_frame.

void nrf_802154_tx_started(const uint8_t *p_frame)

Notifies that transmitting a frame has started.

Note

Currently this callout is only available on the CPU which is running the core of the radio driver. If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead.

Note

Usually, nrf_802154_transmitted is called shortly after this function. However, if the transmit procedure is interrupted, it might happen that nrf_802154_transmitted is not called.

Note

This function should be very short to prevent dropping frames by the driver.

Parameters:

  • p_frame – [in] Pointer to a buffer that contains PHR and PSDU of the frame being transmitted.

void nrf_802154_custom_part_of_radio_init(void)

Perform some additional operations during initialization of the RADIO peripheral.

By implementing this function the higher layer can provide some additional operations to be performed at the beginning of each new timeslot. These can in particular be modifications of RADIO peripheral register values.

Driver memory management

group nrf_802154_memman

Functions

void nrf_802154_buffer_free_raw(uint8_t *p_data)

Notifies the driver that the buffer containing the received frame is not used anymore.

Note

The buffer pointed to by p_data may be modified by this function.

Note

This function can be safely called only from the main context. To free the buffer from a callback or the IRQ context, use nrf_802154_buffer_free_immediately_raw.

Note

This function is available if NRF_802154_USE_RAW_API is enabled.

Parameters:

  • p_data – [in] Pointer to the buffer containing the received data that is no longer needed by the higher layer.

bool nrf_802154_buffer_free_immediately_raw(uint8_t *p_data)

Notifies the driver that the buffer containing the received frame is not used anymore.

Note

The buffer pointed to by p_data may be modified by this function.

Note

This function can be safely called from any context. If the driver is busy processing a request called from a context with lower priority, this function returns false and the caller should free the buffer later.

Note

This function is available if NRF_802154_USE_RAW_API is enabled.

Parameters:

  • p_data – [in] Pointer to the buffer containing the received data that is no longer needed by the higher layer.

Return values:

  • true – Buffer was freed successfully.

  • false – Buffer cannot be freed right now due to ongoing operation.

void nrf_802154_buffer_free(uint8_t *p_data)

Notifies the driver that the buffer containing the received frame is not used anymore.

Note

The buffer pointed to by p_data may be modified by this function.

Note

This function can be safely called only from the main context. To free the buffer from a callback or IRQ context, use nrf_802154_buffer_free_immediately.

Note

This function is available if NRF_802154_USE_RAW_API is disabled.

Parameters:

  • p_data – [in] Pointer to the buffer containing the received data that is no longer needed by the higher layer.

bool nrf_802154_buffer_free_immediately(uint8_t *p_data)

Notifies the driver that the buffer containing the received frame is not used anymore.

Note

The buffer pointed to by p_data may be modified by this function.

Note

This function can be safely called from any context. If the driver is busy processing a request called from a context with lower priority, this function returns false and the caller should free the buffer later.

Note

This function is available if NRF_802154_USE_RAW_API is disabled.

Parameters:

  • p_data – [in] Pointer to the buffer containing the received data that is no longer needed by the higher layer.

Return values:

  • true – Buffer was freed successfully.

  • false – Buffer cannot be freed right now due to ongoing operation.

RSSI measurement function

group nrf_802154_rssi

RSSI calculations used internally in the 802.15.4 driver.

Functions

bool nrf_802154_rssi_measure_begin(void)

Begins the RSSI measurement.

The result will be available after the measurement process is finished. The result can be read by nrf_802154_rssi_last_get. Check the documentation of the RADIO peripheral to check the duration of the RSSI measurement procedure.

Note

This function is to be called in the RADIO_STATE_RX state.

Return values:

  • true – RSSI measurement successfully requested.

  • false – RSSI measurement cannot be scheduled at the moment.

int8_t nrf_802154_rssi_last_get(void)

Gets the result of the last RSSI measurement.

Returns:

RSSI measurement result, in dBm.

int8_t nrf_802154_rssi_sample_temp_corr_value_get(uint8_t rssi_sample)

Gets the RSSISAMPLE temperature correction value.

The correction value is based on the last temperature value reported by the platform.

Parameters:

  • rssi_sample – [in] Value read from the RSSISAMPLE register.

Returns:

RSSISAMPLE temperature correction value.

uint8_t nrf_802154_rssi_sample_corrected_get(uint8_t rssi_sample)

Adjusts the given RSSISAMPLE value by a temperature correction factor.

Parameters:

  • rssi_sample – [in] Value read from the RSSISAMPLE register.

Returns:

RSSISAMPLE corrected by a temperature factor.

uint8_t nrf_802154_rssi_lqi_corrected_get(uint8_t lqi)

Adjusts the reported LQI value using a temperature correction factor.

Parameters:

  • lqi – [in] Value read from the LQI byte.

Returns:

LQI byte value corrected by a temperature factor.

int16_t nrf_802154_rssi_ed_corrected_get(int16_t ed)

Adjusts the EDSAMPLE value using a temperature correction factor.

Parameters:

  • ed – [in] Value read from the EDSAMPLE register.

Returns:

EDSAMPLE value corrected by a temperature factor.

uint8_t nrf_802154_rssi_cca_ed_threshold_corrected_get(uint8_t cca_ed)

Adjusts the CCA ED threshold value using a temperature correction factor.

Parameters:

  • cca_ed – [in] Value representing the CCA ED threshold to be corrected.

Returns:

CCA ED threshold value corrected by a temperature factor.

uint8_t nrf_802154_rssi_ed_sample_convert(uint8_t ed_sample)

Convert the hardware reported energy detection value to a value compliant with the 802.15.4 specification.

Parameters:

  • ed_sample – [in] The hardware reported value

Returns:

802.15.4 compliant energy detection value.

int8_t nrf_802154_rssi_dbm_from_energy_level_calculate(uint8_t energy_level)

Converts the energy level received during the energy detection procedure to a dBm value.

Parameters:
Returns:

Result of the energy detection procedure in dBm.

int8_t nrf_802154_rssi_ed_sample_to_dbm_convert(uint8_t ed_sample)

Converts the EDSAMPLE value to a dBm value.

Note

Performs temperature correction internally.

Parameters:

  • [int] – ed_sample The hardware reported value.

Returns:

Result of the energy detection procedure in dBm.

Promiscuous mode

group nrf_802154_prom

Functions

void nrf_802154_promiscuous_set(bool enabled)

Enables or disables the promiscuous radio mode.

In the promiscuous mode, the driver notifies the higher layer that it received any frame (regardless frame type or destination address). In normal mode (not promiscuous), the higher layer is not notified about ACK frames and frames with unknown type. Also, frames with a destination address not matching the device address are ignored.

Note

The promiscuous mode is disabled by default.

Parameters:

  • enabled – [in] If the promiscuous mode is to be enabled.

bool nrf_802154_promiscuous_get(void)

Checks if the radio is in the promiscuous mode.

Return values:

  • True – Radio is in the promiscuous mode.

  • False – Radio is not in the promiscuous mode.

Auto ACK management

group nrf_802154_autoack

Functions

void nrf_802154_auto_ack_set(bool enabled)

Enables or disables the automatic acknowledgments (auto ACK).

If the auto ACK is enabled, the driver prepares and sends ACK frames automatically aTurnaroundTime (192 us) after the proper frame is received. The driver prepares an ACK frame according to the data provided by nrf_802154_ack_data_set. When the auto ACK is enabled, the driver notifies the next higher layer about the received frame after the ACK frame is transmitted. If the auto ACK is disabled, the driver does not transmit ACK frames. It notifies the next higher layer about the received frames when a frame is received. In this mode, the next higher layer is responsible for sending the ACK frame. ACK frames should be sent using nrf_802154_transmit.

Note

The auto ACK is enabled by default.

Parameters:

  • enabled – [in] If the auto ACK should be enabled.

bool nrf_802154_auto_ack_get(void)

Checks if the auto ACK is enabled.

Return values:

  • True – Auto ACK is enabled.

  • False – Auto ACK is disabled.

void nrf_802154_pan_coord_set(bool enabled)

Configures the device as the PAN coordinator.

Note

That information is used for packet filtering.

Parameters:

  • enabled – [in] The radio is configured as the PAN coordinator.

bool nrf_802154_pan_coord_get(void)

Checks if the radio is configured as the PAN coordinator.

Return values:

  • true – The radio is configured as the PAN coordinator.

  • false – The radio is not configured as the PAN coordinator.

void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_method)

Select the source matching algorithm.

When calling nrf_802154_ack_data_pending_bit_should_be_set, one of several algorithms for source address matching will be chosen. To ensure a specific algorithm is selected, call this function before nrf_802154_ack_data_pending_bit_should_be_set.

Note

This method should be called after driver initialization, but before transceiver is enabled.

Parameters:

  • match_method – [in] Source address matching method to be used.

bool nrf_802154_ack_data_set(const uint8_t *p_addr, bool extended, const void *p_data, uint16_t length, nrf_802154_ack_data_t data_type)

Adds the address of a peer node for which the provided ACK data is to be injected into generated ACKs.

Data passed to this function can be either pending bit data or Header IE data.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

  • For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD

  • For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE

  • For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

For IE data, specific cases are supported, where additional data will be injected into the IE on pre-transmission:

  • CSL IE - CSL phase will be injected if IE ID is set to IE_CSL_ID

  • Thread link metrics - Link metrics will be injected if

    • IE ID is set to IE_VENDOR_ID

    • OUI is set to IE_VENDOR_THREAD_OUI

    • Thread IE subtype is set to IE_VENDOR_THREAD_ACK_PROBING_ID

For Link metrics to be injected, additional preparation is required. Each byte of injected link metrics needs to be filled with a token, indicating what type of data is to be injected pre-transmission. Supported tokens are:

  • IE_VENDOR_THREAD_RSSI_TOKEN - RSSI of the last received frame will be injected,

  • IE_VENDOR_THREAD_MARGIN_TOKEN - RSSI above sensitivity margin of the last received frame will be injected,

  • IE_VENDOR_THREAD_LQI_TOKEN - LQI of the last received frame will be injected. Additionally, tokens must be unique in given IE, all bytes prepared for link metrics must be filled with tokens and no more than two bytes must be prepared for link metrics. If any of those conditions is not met, no data will be injected into the ACK pre-transmission.

To better illustrate, if RSSI is to be inserted into ACKs for specific address, following ie data needs to be prepared:

* +------------+----------------------+---------------------------------+-----------------------------+
* | Bytes: 0-1 |          2-4         |                5                |              6              |
* +------------+----------------------+---------------------------------+-----------------------------+
* | IE header  | IE_VENDOR_THREAD_OUI | IE_VENDOR_THREAD_ACK_PROBING_ID | IE_VENDOR_THREAD_RSSI_TOKEN |
* +------------+----------------------+---------------------------------+-----------------------------+
*                                     |                                                               |
*                                     | <------------------IE Vendor-specific data------------------> |
*

When sending ACK with this data, before transmission, RSSI of the last received frame will be written into byte 6.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Parameters:

  • p_addr – [in] Array of bytes containing the address of the node (little-endian).

  • extended – [in] If the given address is an extended MAC address or a short MAC address.

  • p_data – [in] Pointer to the buffer containing data to be set.

  • length – [in] Length of p_data.

  • data_type – [in] Type of data to be set. Refer to the nrf_802154_ack_data_t type.

Return values:

  • True – Address successfully added to the list.

  • False – Not enough memory to store this address in the list.

bool nrf_802154_ack_data_clear(const uint8_t *p_addr, bool extended, nrf_802154_ack_data_t data_type)

Removes the address of a peer node for which the ACK data is set from the pending bit list.

The ACK data that was previously set for the given address is automatically removed.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

  • For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD

  • For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE

  • For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Parameters:

  • p_addr – [in] Array of bytes containing the address of the node (little-endian).

  • extended – [in] If the given address is an extended MAC address or a short MAC address.

  • data_type – [in] Type of data to be removed. Refer to the nrf_802154_ack_data_t type.

Return values:

  • True – Address removed from the list.

  • False – Address not found in the list.

void nrf_802154_ack_data_remove_all(bool extended, nrf_802154_ack_data_t data_type)

Removes all addresses of a given length from the ACK data list.

Parameters:

  • extended – [in] Indication if all extended addresses or all short addresses are to be removed from the list.

  • data_type – [in] Type of data that is to be cleared for all addresses of a given length.

void nrf_802154_auto_pending_bit_set(bool enabled)

Enables or disables setting a pending bit in automatically transmitted ACK frames.

The radio driver automatically sends ACK frames in response frames destined for this node with the ACK Request bit set. The pending bit in the ACK frame can be set or cleared regarding data in the indirect queue destined for the ACK destination.

If setting a pending bit in ACK frames is disabled, the pending bit in every ACK frame is set. If setting a pending bit in ACK frames is enabled, the radio driver checks if there is data in the indirect queue destined for the ACK destination. If there is no such data, the pending bit is cleared.

Note

Setting a pending bit in automatically transmitted ACK frames is enabled by default.

Note

Due to the ISR latency, the radio driver might not be able to verify if there is data in the indirect queue before ACK is sent. In this case, the pending bit is set.

Parameters:

  • enabled – [in] If setting a pending bit in ACK frames is enabled.

bool nrf_802154_pending_bit_for_addr_set(const uint8_t *p_addr, bool extended)

Adds the address of a peer node to the pending bit list.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

  • For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD

  • For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE

  • For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Note

This function makes a copy of the given address.

Parameters:

  • p_addr – [in] Array of bytes containing the address of the node (little-endian).

  • extended – [in] If the given address is an extended MAC address or a short MAC address.

Return values:

  • True – The address is successfully added to the list.

  • False – Not enough memory to store the address in the list.

bool nrf_802154_pending_bit_for_addr_clear(const uint8_t *p_addr, bool extended)

Removes address of a peer node from the pending bit list.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

  • For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD

  • For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE

  • For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Parameters:

  • p_addr – [in] Array of bytes containing the address of the node (little-endian).

  • extended – [in] If the given address is an extended MAC address or a short MAC address.

Return values:

  • True – The address is successfully removed from the list.

  • False – No such address in the list.

void nrf_802154_pending_bit_for_addr_reset(bool extended)

Removes all addresses of a given type from the pending bit list.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

  • For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD

  • For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE

  • For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Parameters:

  • extended – [in] If the function is to remove all extended MAC addresses or all short addresses.

CCA configuration management

group nrf_802154_cca

Functions

void nrf_802154_cca_cfg_set(const nrf_802154_cca_cfg_t *p_cca_cfg)

Configures the radio CCA mode and threshold.

Parameters:

  • p_cca_cfg – [in] Pointer to the CCA configuration structure. Only fields relevant to the selected mode are updated.

void nrf_802154_cca_cfg_get(nrf_802154_cca_cfg_t *p_cca_cfg)

Gets the current radio CCA configuration.

Parameters:

  • p_cca_cfg – [out] Pointer to the structure for the current CCA configuration.

CSMA-CA procedure

group nrf_802154_csma

Functions

bool nrf_802154_transmit_csma_ca_raw(uint8_t *p_data, const nrf_802154_transmit_csma_ca_metadata_t *p_metadata)

Performs the CSMA-CA procedure and transmits a frame in case of success.

The end of the CSMA-CA procedure is notified by nrf_802154_transmitted_raw or nrf_802154_transmit_failed.

Note

The driver may be configured to automatically time out waiting for an ACK frame depending on NRF_802154_ACK_TIMEOUT_ENABLED. If the automatic ACK timeout is disabled, the CSMA-CA procedure does not time out waiting for an ACK frame if a frame with the ACK request bit set was transmitted. The MAC layer is expected to manage the timer to time out waiting for the ACK frame. This timer can be started by nrf_802154_tx_started. When the timer expires, the MAC layer is expected to call nrf_802154_receive or nrf_802154_sleep to stop waiting for the ACK frame.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled and NRF_802154_USE_RAW_API is enabled.

Parameters:

  • p_data – [in] Pointer to the frame to transmit. See also nrf_802154_transmit_raw.

  • p_metadata – [in] Pointer to metadata structure. Contains detailed properties of data to transmit. If NULL following metadata are used:

    Field

    Value

    frame_props

    NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT

Return values:

  • true – The chain of CSMA-CA and transmission procedure was scheduled.

  • false – The driver could not schedule the procedure chain.

bool nrf_802154_csma_ca_min_be_set(uint8_t min_be)

Sets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Parameters:

  • min_be – [in] Minimum value of the backoff exponent.

Return values:

  • true – When value provided by min_be has been set successfully.

  • false – Otherwise.

uint8_t nrf_802154_csma_ca_min_be_get(void)

Gets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Returns:

Current minimum value of the backoff exponent.

bool nrf_802154_csma_ca_max_be_set(uint8_t max_be)

Sets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Parameters:

  • max_be – [in] Maximum value of the backoff exponent.

Return values:

  • true – When value provided by max_be has been set successfully.

  • false – Otherwise.

uint8_t nrf_802154_csma_ca_max_be_get(void)

Gets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Returns:

Current maximum value of the backoff exponent.

void nrf_802154_csma_ca_max_backoffs_set(uint8_t max_backoffs)

Sets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring a channel access failure.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Parameters:

  • max_backoffs – [in] Maximum number of backoffs.

uint8_t nrf_802154_csma_ca_max_backoffs_get(void)

Gets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring a channel access failure.

Note

This function is available if NRF_802154_CSMA_CA_ENABLED is enabled.

Returns:

Current maximum number of backoffs.

ACK timeout procedure

group nrf_802154_timeout

Functions

void nrf_802154_ack_timeout_set(uint32_t time)

Sets timeout for the ACK timeout feature.

A timeout is notified by nrf_802154_transmit_failed.

Note

This function is available if NRF_802154_ACK_TIMEOUT_ENABLED is enabled.

Parameters:

  • time – [in] Timeout in microseconds (us). A default value is defined in nrf_802154_config.h.

Statistics and measurements

group nrf_802154_stats

Functions

void nrf_802154_stats_get(nrf_802154_stats_t *p_stats)

Gets current statistics.

Parameters:

  • p_stats – [out] Structure that will be filled with current stats values.

void nrf_802154_stat_counters_get(nrf_802154_stat_counters_t *p_stat_counters)

Get current statistics.

Note

This returns part of information returned by nrf_802154_stats_get

Parameters:

  • p_stat_counters – [out] Structure that will be filled with current stats counter values.

void nrf_802154_stat_counters_subtract(const nrf_802154_stat_counters_t *p_stat_counters)

Decreases current statistic counter values by the provided ones.

This function is intended to be called together with nrf_802154_stats_get to avoid missing any counted events.

Parameters:

  • p_stat_counters – [in] Current stat counter values will be decreased by values provided behind this pointer.

void nrf_802154_stat_timestamps_get(nrf_802154_stat_timestamps_t *p_stat_timestamps)

Get time stamps of events gathered by the last operation.

Parameters:

  • p_stat_timestamps – [out] Structure that will be filled with current time stamps of events.

void nrf_802154_stat_counters_reset(void)

Resets current stat counters to 0.

Note

nrf_802154_stat_counters_get and nrf_802154_stat_counters_reset may lead to missing events if an counted event occurs between these calls. Use nrf_802154_stat_counters_subtract to avoid such condition if necessary.

Inter-frame spacing feature

group nrf_802154_ifs

Functions

nrf_802154_ifs_mode_t nrf_802154_ifs_mode_get(void)

Gets IFS operation mode.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Returns:

Current IFS operation mode. Refer to nrf_802154_ifs_mode_t for details.

bool nrf_802154_ifs_mode_set(nrf_802154_ifs_mode_t mode)

Sets IFS operation mode.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Parameters:

  • mode – [in] IFS operation mode. Refer to nrf_802154_ifs_mode_t for details.

Return values:

  • true – The update of IFS operation mode was successful.

  • false – The update of IFS operation mode failed. Provided mode is unsupported

uint16_t nrf_802154_ifs_min_sifs_period_get(void)

Gets Short IFS period in microseconds.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Returns:

Current Short IFS period in microseconds.

void nrf_802154_ifs_min_sifs_period_set(uint16_t period)

Sets Short IFS period in microseconds.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Parameters:

  • period – [in] Short IFS period in microseconds.

uint16_t nrf_802154_ifs_min_lifs_period_get(void)

Gets Long IFS period in microseconds.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Returns:

Current Long IFS period in microseconds.

void nrf_802154_ifs_min_lifs_period_set(uint16_t period)

Sets Long IFS period in microseconds.

Note

This function is available if NRF_802154_IFS_ENABLED is enabled.

Parameters:

  • period – [in] Long IFS period in microseconds.

Radio driver run-time capabilities feature

group nrf_802154_capabilities

Functions

nrf_802154_capabilities_t nrf_802154_capabilities_get(void)

Gets nRF 802.15.4 Radio Driver Capabilities.

Returns:

Capabilities of the radio driver.

Radio driver MAC security feature

group nrf_802154_security

Functions

void nrf_802154_security_global_frame_counter_set(uint32_t frame_counter)

Sets nRF 802.15.4 Radio Driver Global MAC Frame Counter.

The driver automatically increments the counter in every outgoing frame which uses the Global MAC Frame Counter. This call is meant to set the initial value of the frame counter.

Parameters:

  • frame_counter – [in] Global MAC Frame Counter to set.

void nrf_802154_security_global_frame_counter_set_if_larger(uint32_t frame_counter)

Sets nRF 802.15.4 Radio Driver MAC Global Frame Counter if the value passed is larger than current.

Parameters:

  • frame_counter – [in] Frame counter to set.

nrf_802154_security_error_t nrf_802154_security_key_store(nrf_802154_key_t *p_key)

Store the 802.15.4 MAC Security Key inside the nRF 802.15.4 Radio Driver.

Note

This function is not reentrant and must be called from thread context only.

Parameters:

  • p_key – [in] Pointer to the key to store. Refer to nrf_802154_key_t for details. Storing the key copies the content of the key and key ID into the Radio Driver. This input parameter can be destroyed after the call.

Return values:

  • NRF_802154_SECURITY_ERROR_NONE – Storing of key is successful.

  • NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED – Type of the key is not supported.

  • NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED – ID mode of the key is not supported.

  • NRF_802154_SECURITY_ERROR_ALREADY_PRESENT – Failed to store the key - key of such id is already present. Remove the key first to overwrite.

  • NRF_802154_SECURITY_ERROR_STORAGE_FULL – Failed to store the key - storage full.

nrf_802154_security_error_t nrf_802154_security_key_remove(nrf_802154_key_id_t *p_id)

Remove the 802.15.4 MAC Security Key from the nRF 802.15.4 Radio Driver.

Note

This function is not reentrant and must be called from thread context only.

Parameters:

  • p_id – [in] Pointer to the ID of the key to remove.

Return values:

  • NRF_802154_SECURITY_ERROR_NONE – Removal of key is successful.

  • NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND – Failed to remove the key - no such key found.

void nrf_802154_security_key_remove_all(void)

Remove all stored 802.15.4 MAC Security Keys from the nRF 802.15.4 Radio Driver.

Note

This function is not reentrant and must be called from thread context only.

Radio driver Information Element data injection feature

group nrf_802154_ie_writer

Information element writer module.

Functions

void nrf_802154_csl_writer_period_set(uint16_t period)

Sets the value of CSL period to inject into the CSL information element.

Parameters:

  • period – [in] CSL period value.

void nrf_802154_csl_writer_anchor_time_set(uint64_t anchor_time)

Sets the anchor time based on which the next CSL window time and the CSL phase is calculated.

This function sets an anchor time based on which the times of future CSL windows are calculated. When this anchor time is used for calculations, it is assumed that it points to a time where the first bit of MAC header of the frame received from a peer happens. In other words, the anchor time should point to a time where CSL phase would be equal 0. As a result, CSL phase can always be calculated relatively to a time given by the equation anchor_time + n * csl_period where n is an integer. Note that the reasoning holds irrespectively of signedness of n so the anchor time can be either in the past or in the future.

This function should be called after calling nrf_802154_csl_writer_period_set and every time when the CSL communication desynchronizes.

If this function is not called a legacy CSL operation mode is chosen. The CSL phase is then calculated based on the time of the nearest scheduled CSL reception window and can be undefined, if no such window was scheduled.

Parameters:

  • anchor_time – [in] Anchor time in microseconds.

void nrf_802154_rx_on_when_idle_set(bool rx_on_when_idle)

Sets the RxOnWhenIdle mode value.

This function sets the RxOnWhenIdle mode value, which defaults to true. When enabled, the radio will stay in receive state during idle periods. When disabled, the radio will stay in sleep state during idle periods. The new value will only take effect after a completed operation.

Notice that the period following a failed reception is not considered idle, rather continuation of the reception state. Same goes for the finalization of a reception during a receive slot.

An idle period is started in the following situations:

  • After nrf_802154_receive starts a receive state and a frame is correctly received and passed the filtering:

    • If the received frame requests an ACK: after the ACK was properly transmitted or immediately if for some internal condition the ACK is not transmitted.

    • If the received frame does not request an ACK: immediately, unless the received frame is an spurious ACK.

  • Immediately after a frame is transmitted, when no ACK is requested.

  • After a frame is transmitted, when ACK is requested, if:

    • ACK timeout expires.

    • An invalid ACK is received (or not an ACK frame).

    • The matching ACK is received, unless the transmitted frame was a Data Request Command and the frame pending bit is set to true in the ACK.

  • After a standalone CCA is completed.

  • After a failed CCA during CSMA/CA procedure.

  • After every Energy Detection operation.

  • After a delayed reception times out.

Combining disabled RxOnWhenIdle mode and enabled promiscuous mode is unsupported. Such configuration may result in an undefined behavior.

Parameters:

  • rx_on_when_idle – [in] If RxOnWhenIdle mode should be enabled.

void nrf_802154_ie_writer_reset(void)

Resets the IE writer module to pristine state.

void nrf_802154_ie_writer_prepare(uint8_t *p_ie_header, const uint8_t *p_end_addr)

Prepares to write Information Element data to all elements recognized by the module.

Calls to this function put the IE writer module into an armed state. In the armed state the addresses of recognized Information Element values are latched. The IE writer module shall perform necessary calculations and write the results to the latched addresses during the execution of either nrf_802154_ie_writer_tx_ack_started_hook or nrf_802154_ie_writer_tx_started_hook hooks.

It is expected, that the layout of the frame does not change while the IE writer is in armed state.

If this function detects a malformed header IE, the module state shall be reset to the unarmed state. There is no guarantee that all malformed header IEs will be detected, but it is guaranteed that the writer module shall never modify memory past the p_end_addr argument.

Parameters:

  • p_ie_header – [in] Address of the IE header.

  • p_end_addr – [in] First invalid address after p_ie_header.

bool nrf_802154_ie_writer_tx_setup(uint8_t *p_frame, nrf_802154_transmit_params_t *p_params, nrf_802154_transmit_failed_notification_t notify_function)

Transmission setup hook for the IE writer module.

This hook parses the frame in search of header Information Elements and arms the IE writer module. The IE writer module shall write data to recognized Information Elements during the execution of nrf_802154_ie_writer_tx_ack_started_hook and nrf_802154_ie_writer_tx_started_hook hooks.

If this function detects a malformed frame, the module state shall be reset to the unarmed state. There is no guarantee that all malformed frames will be detected.

Parameters:

  • p_frame – [in] Pointer to the buffer that contains the PHR and PSDU of the transmitted frame.

  • p_params – [in] Pointer to the transmission parameters.

  • notify_function – [in] Function to be called to notify transmission failure.

Return values:

true – Always succeeds.

void nrf_802154_ie_writer_tx_ack_started_hook(uint8_t *p_ack)

ACK TX started hook for the IE writer module.

This hook executes during the EVENT_ADDRESS radio event. If the IE writer is armed, the IEs recognized by the writer module shall be modified. If IE writer is not armed no action shall be performed.

The function writes to memory addresses that were found suitable by the call to nrf_802154_ie_writer_prepare function. No parsing of the frame pointed by the p_ack argument is performed and the argument itself is ignored due to timing requirements that this hook must not exceed.

Parameters:

  • p_ack – [in] Pointer to the buffer that contains the PHR and PSDU of the ACK frame.

bool nrf_802154_ie_writer_tx_started_hook(uint8_t *p_frame)

TX started hook for the IE writer module.

This hook executes during the EVENT_ADDRESS radio event. If the IE writer is armed, the IEs recognized by the writer module shall be modified. If IE writer is not armed no action shall be performed.

The function writes to memory addresses that were found suitable by the call to nrf_802154_ie_writer_prepare function. No parsing of the frame pointed by the p_frame argument is performed and the argument itself is ignored due to timing requirements that this hook must not exceed.

Parameters:

  • p_frame – [in] Pointer to the buffer that contains the PHR and PSDU of the transmitted frame.

Return values:

true – Always succeeds.

void nrf_802154_ie_writer_csl_period_set(uint16_t period)

Sets the value of CSL period to inject into the CSL information element.

Parameters:

  • period – [in] CSL period value.

void nrf_802154_ie_writer_csl_anchor_time_set(uint64_t anchor_time)

Sets the anchor time based on which the next CSL window time and the CSL phase is calculated.

Parameters:

  • anchor_time – [in] Anchor time value.

Radio driver configuration

group nrf_802154_config_radio

Defines

NRF_802154_CCA_MODE_DEFAULT

CCA mode used by the driver.

NRF_802154_CCA_ED_THRESHOLD_DEFAULT

Energy detection threshold used in the CCA procedure.

NRF_802154_CCA_CORR_THRESHOLD_DEFAULT

Correlator threshold used in the CCA procedure.

NRF_802154_CCA_CORR_LIMIT_DEFAULT

Correlator limit used in the CCA procedure.

NRF_802154_INTERNAL_RADIO_IRQ_HANDLING

If the driver is expected to internally handle the RADIO IRQ. If the driver is used in an OS, the RADIO IRQ can be handled by the OS and passed to the driver by nrf_802154_radio_irq_handler. In this case, the internal handling must be disabled.

NRF_802154_INTERNAL_SWI_IRQ_HANDLING

If the driver is expected to internally handle the SWI IRQ. If the driver is used in an OS, the SWI IRQ can be handled by the OS and passed to the driver by nrf_802154_swi_irq_handler. In this case, the internal handling must be disabled.

NRF_802154_IRQ_PRIORITY

Interrupt priority for RADIO peripheral. Keep the IRQ priority high (low number) to prevent losing frames due to preemption.

NRF_802154_SWI_PRIORITY

The priority of software interrupt used for requests and notifications.

NRF_802154_ECB_PRIORITY

Interrupt priority for ECB peripheral used for frame encryption.

NRF_802154_USE_RAW_API

When this flag is set, the RAW API is available for the MAC layer. It is recommended to use the RAW API because it provides more optimized functions.

Note

If the RAW API is not enabled for the MAC layer, only less optimized functions performing copy are available.

NRF_802154_PENDING_SHORT_ADDRESSES

The number of slots containing short addresses of nodes for which the pending data is stored.

NRF_802154_PENDING_EXTENDED_ADDRESSES

The number of slots containing extended addresses of nodes for which the pending data is stored.

NRF_802154_RX_BUFFERS

The number of buffers in the receive queue.

NRF_802154_MAX_DISREGARDABLE_NOTIFICATIONS

The number of slots in the driver’s notification queue intended for notifications that can be disregarded with no impact on the driver, for instance failed reception notifications.

Note

Setting this macro to 0 will cause the driver to not issue any disregardable notifications.

NRF_802154_NOTIFY_CRCERROR

With this flag set to 1, the CRC errors are notified to upper layers. This requires an interrupt handler to be used.

NRF_802154_FRAME_TIMESTAMP_ENABLED

If timestamps are to be added to the frames received. Enabling this feature enables the functions nrf_802154_received_timestamp_raw, nrf_802154_received_timestamp which add timestamps to the frames received. Enables also proper value of frame timestamp ( nrf_802154_transmit_done_metadata_t::data.transmitted.time ) passed as metadata to nrf_802154_transmitted and nrf_802154_transmitted_raw, This option also enables timestamping in stats.

NRF_802154_DELAYED_TRX_ENABLED

If the delayed transmission and the receive window features are available.

NRF_802154_TEST_MODES_ENABLED

Enables test modes. Test modes are normally disabled in end products. When NRF_802154_TEST_MODES_ENABLED is set to 1, nRF 802.15.4 Radio Driver provides additional API to enable certain test modes. Setting NRF_802154_TEST_MODES_ENABLED to 1 without using test mode API does not change any behavior of the Radio Driver.

NRF_802154_PAN_COORD_GET_ENABLED

Enables the nrf_802154_pan_coord_get function.

CSMA/CA procedure configuration

group nrf_802154_config_csma

Defines

NRF_802154_CSMA_CA_ENABLED

If CSMA-CA is to be enabled by the driver. Disabling CSMA-CA improves the driver performance.

NRF_802154_CSMA_CA_MIN_BE_DEFAULT

The default minimum value of the backoff exponent (BE) in the CSMA-CA algorithm (see IEEE 802.15.4-2015: 6.2.5.1).

Note

The minimum value of the backoff exponent may be changed from default by calling the nrf_802154_csma_ca_min_be_set function.

NRF_802154_CSMA_CA_MAX_BE_DEFAULT

The default maximum value of the backoff exponent, BE, in the CSMA-CA algorithm (see IEEE 802.15.4-2015: 6.2.5.1).

Note

The maximum value of the backoff exponent may be changed from default by calling the nrf_802154_csma_ca_max_be_set function.

NRF_802154_CSMA_CA_MAX_CSMA_BACKOFFS_DEFAULT

The default maximum number of backoffs that the CSMA-CA algorithm will attempt before declaring a channel access failure.

Note

The maximum number of backoffs may be changed from default by calling the nrf_802154_csma_ca_max_backoffs_set function.

NRF_802154_CSMA_CA_WAIT_FOR_TIMESLOT

Indicates whether the CSMA-CA algorithm waits for an available timeslot before it performs the CCA procedure.

Note

When this option is enabled, the CSMA-CA procedure can be synchronized with timeslots of other protocols. This decreases the robustness of the CSMA-CA procedure. On the other hand, enabling this function increases the performance of multi-protocol applications, especially when protocols other than 802.15.4 use much of the radio time (like the BLE scanning operation).

ACK timeout feature configuration

group nrf_802154_config_timeout

Defines

NRF_802154_ACK_TIMEOUT_ENABLED

Indicates whether the ACK timeout feature is to be enabled in the driver.

NRF_802154_ACK_TIMEOUT_DEFAULT_TIMEOUT

The default timeout in microseconds (us) for the ACK timeout feature.

NRF_802154_PRECISE_ACK_TIMEOUT_DEFAULT_TIMEOUT

The default timeout in microseconds (us) for the precise ACK timeout feature.

NRF_802154_MAX_ACK_IE_SIZE

The maximum supported size of the 802.15.4-2015 IE header and content fields in an Enh-Ack.

Transmission start notification feature configuration

group nrf_802154_config_transmission

Information Elements configuration

group nrf_802154_ie

Defines

NRF_802154_IE_WRITER_ENABLED

Enables the Information Element writer module. The module parses frames being transmitted for known Information Element IDs. If such elements are found, the writer module shall fill the elements with appropriate data.

NRF_802154_CARRIER_FUNCTIONS_ENABLED

Enables functions used for test purposes: nrf_802154_continuous_carrier and nrf_802154_modulated_carrier

Interrupt Handlers

group nrf_802154_irq

Functions

void nrf_802154_radio_irq_handler(void)

Handles the interrupt request from the RADIO peripheral.

This function is intended for use in an operating system environment, where the OS handles IRQ and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes radio IRQ to the driver.

Note

If NRF_802154_INTERNAL_RADIO_IRQ_HANDLING is enabled, the driver internally handles the RADIO IRQ, and this function must not be called.

void nrf_802154_swi_irq_handler(void)

Handles the interrupt request from the RADIO peripheral.

This function is intended for use in an operating system environment, where the OS handles IRQ and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes radio IRQ to the driver.

Note

If NRF_802154_INTERNAL_SWI_IRQ_HANDLING is enabled, the driver internally handles the SWI IRQ, and this function must not be called.

Other functions

group nrf_802154

Defines

NRF_802154_NO_TIMESTAMP

Timestamp value indicating that the timestamp is inaccurate.

NRF_802154_RESERVED_INVALID_ID

Invalid delayed timeslot identifier.

NRF_802154_RESERVED_IMM_RX_WINDOW_ID

Reception window identifier reserved for immediate reception.

NRF_802154_RESERVED_DRX_ID_UPPER_BOUND

Upper bound for delayed reception window identifiers used by the application.

All integers ranging from 0 to NRF_802154_RESERVED_DRX_ID_UPPER_BOUND (inclusive) can be used by the application as identifiers of delayed reception windows.

NRF_802154_MAX_PENDING_NOTIFICATIONS

Maximum number of simultaneously pending notifications the driver can issue.

This parameter allows to determine the correct size for structures that process notifications issued by the driver. It accumulates the maximum number of simultaneously pending notifications that can result from successfully received frames, disregardable notifications, all supported delayed operations and the latest requested immediate operation.

Functions

void nrf_802154_init(void)

Initializes the 802.15.4 driver.

This function initializes the RADIO peripheral in the RADIO_STATE_SLEEP state.

Note

This function is to be called once, before any other functions from this module. Only the functions setting the configuration can be called before this call.

void nrf_802154_deinit(void)

Deinitializes the 802.15.4 driver.

This function deinitializes the RADIO peripheral and resets it to the default state.

void nrf_802154_channel_set(uint8_t channel)

Sets the channel on which the radio is to operate.

Parameters:

  • channel – [in] Channel number (11-26).

uint8_t nrf_802154_channel_get(void)

Gets the channel on which the radio operates.

Returns:

Channel number (11-26).

void nrf_802154_tx_power_set(int8_t power)

Sets the transmit power.

Note

The driver recalculates the requested value to the nearest value accepted by the hardware. The calculation result is rounded up.

Parameters:

  • power – [in] Transmit power in dBm.

int8_t nrf_802154_tx_power_get(void)

Gets the currently set transmit power.

Returns:

Currently used real total transmit power, in dBm.

bool nrf_802154_antenna_diversity_rx_mode_set(nrf_802154_sl_ant_div_mode_t mode)

Sets the antenna diversity rx mode.

Note

This function should not be called while reception or transmission are currently ongoing.

Parameters:

  • mode – [in] Antenna diversity rx mode to be set.

Return values:

  • true – Antenna diversity rx mode set successfully.

  • false – Invalid mode passed as argument.

nrf_802154_sl_ant_div_mode_t nrf_802154_antenna_diversity_rx_mode_get(void)

Gets current antenna diversity rx mode.

Returns:

Current antenna diversity mode for rx.

bool nrf_802154_antenna_diversity_tx_mode_set(nrf_802154_sl_ant_div_mode_t mode)

Sets the antenna diversity tx mode.

Note

This function should not be called while reception or transmission are currently ongoing.

Note

NRF_802154_SL_ANT_DIV_MODE_AUTO is not supported for transmission.

Parameters:

  • mode – [in] Antenna diversity tx mode to be set.

Return values:

  • true – Antenna diversity tx mode set successfully.

  • false – Invalid mode passed as argument.

nrf_802154_sl_ant_div_mode_t nrf_802154_antenna_diversity_tx_mode_get(void)

Gets current antenna diversity tx mode.

Returns:

Current antenna diversity mode for tx.

bool nrf_802154_antenna_diversity_rx_antenna_set(nrf_802154_sl_ant_div_antenna_t antenna)

Manually selects the antenna to be used for rx.

For antenna to be switched, antenna diversity rx mode needs to be NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, antenna will be only switched after NRF_802154_SL_ANT_DIV_MODE_MANUAL is set.

Parameters:

  • antenna – [in] Antenna to be used.

Return values:

  • true – Antenna set successfully.

  • false – Invalid antenna passed as argument.

nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_rx_antenna_get(void)

Gets antenna currently used for rx.

Note

The antenna read by this function is currently used rx antenna only if antenna diversity rx mode is set to NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, currently used antenna may be different.

Returns:

Currently used antenna.

bool nrf_802154_antenna_diversity_tx_antenna_set(nrf_802154_sl_ant_div_antenna_t antenna)

Manually selects the antenna to be used for tx.

For antenna to be switched, antenna diversity tx mode needs to be NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, antenna will be only switched after NRF_802154_SL_ANT_DIV_MODE_MANUAL is set.

Parameters:

  • antenna – [in] Antenna to be used.

Return values:

  • true – Antenna set successfully.

  • false – Invalid antenna passed as argument.

nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_tx_antenna_get(void)

Gets antenna currently used for tx.

Note

The antenna read by this function is currently used tx antenna only if antenna diversity tx mode is set to NRF_802154_SL_ANT_DIV_MODE_MANUAL. Otherwise, currently used antenna may be different.

Returns:

Currently used antenna.

nrf_802154_sl_ant_div_antenna_t nrf_802154_antenna_diversity_last_rx_best_antenna_get(void)

Gets which antenna was selected as best for the last reception.

Note

In three cases NRF_802154_SL_ANT_DIV_ANTENNA_NONE may be returned:

  • No frame was received yet.

  • Last frame was received with antenna diversity auto mode disabled.

  • RSSI measurements didn’t have enough time to finish during last frame reception and it is unspecified which antenna was selected.

Returns:

Antenna selected during last successful reception in automatic mode.

void nrf_802154_antenna_diversity_config_set(const nrf_802154_sl_ant_div_cfg_t *p_cfg)

Sets antenna diversity configuration.

Note

If antenna diversity feature is to be used, this function must be called before nrf_802154_antenna_diversity_init.

Note

This function must be called only once.

Parameters:

  • p_cfg – [in] Pointer to antenna diversity interface configuration.

bool nrf_802154_antenna_diversity_config_get(nrf_802154_sl_ant_div_cfg_t *p_cfg)

Gets the antenna diversity interface configuration.

Parameters:

  • p_cfg – [out] Antenna diversity interface configuration.

Return values:

  • true – The configuration was retrieved successfully.

  • false – The configuration could not be retrieved.

bool nrf_802154_antenna_diversity_init(void)

Initializes antenna diversity module.

This function should be called before starting radio operations, but at any time after driver initialization. In order for it to succeed, antenna diversity interface configuration must be provided before it’s called with nrf_802154_antenna_diversity_config_set. Example usage:

nrf_802154_init();

nrf_802154_sl_ant_div_cfg_t cfg =
{
    // Set the configuration parameters accordingly
};

nrf_802154_antenna_config_set(&cfg);
nrf_802154_antenna_diversity_init();

// At any later time
nrf_802154_receive();
Return values:

  • true – Initialization was successful.

  • false – Initialization could not be performed due to unconfigured interface.

void nrf_802154_antenna_diversity_timer_irq_handler(void)

Handles TIMER IRQ of the antenna diversity interface.

This function should be called when the timer instance provided to the antenna diversity interface reports an interrupt.

uint64_t nrf_802154_time_get(void)

Gets the current time.

The time returned by this function is to be used to calculate timing parameters for nrf_802154_transmit_raw_at and nrf_802154_receive_at functions.

Returns:

Current time in microseconds.