Functions to request FSM transitions and check current state

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. More...
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. More...
bool	nrf_802154_receive (void)
	Changes the radio state to RADIO_STATE_RX. More...
bool	nrf_802154_receive_at (uint32_t t0, uint32_t dt, uint32_t timeout, uint8_t channel)
	Requests reception at the specified time. More...
bool	nrf_802154_receive_at_cancel (void)
	Cancels a delayed reception scheduled by a call to nrf_802154_receive_at. More...
bool	nrf_802154_transmit (const uint8_t *p_data, uint8_t length, bool cca)
	Changes the radio state to transmit. More...
bool	nrf_802154_transmit_raw_at (const uint8_t *p_data, bool cca, uint32_t t0, uint32_t dt, uint8_t channel)
	Requests transmission at the specified time. More...
bool	nrf_802154_transmit_at_cancel (void)
	Cancels a delayed transmission scheduled by a call to nrf_802154_transmit_raw_at. More...
bool	nrf_802154_energy_detection (uint32_t time_us)
	Changes the radio state to energy detection. More...
bool	nrf_802154_cca (void)
	Changes the radio state to RADIO_STATE_CCA. More...
bool	nrf_802154_continuous_carrier (void)
	Changes the radio state to continuous carrier. More...

Detailed Description

Function Documentation

bool nrf_802154_cca

(

void

)

Changes the radio state to RADIO_STATE_CCA.

Note

nrf_802154_cca_done can be called before this function returns a result.

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.

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_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.

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

[in]

time_us

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_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	(	uint32_t	t0,
		uint32_t	dt,
		uint32_t	timeout,
		uint8_t	channel
	)

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_drv_radio802154_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.

Parameters

[in]	t0	Base of delay time - absolute time used by the Timer Scheduler, in microseconds (us).
[in]	dt	Delta of delay time from t0, in microseconds (us).
[in]	timeout	Reception timeout (counted from t0 + dt), in microseconds (us).
[in]	channel	Radio channel on which the frame is to be received.

Return values

true	The reception procedure was scheduled.
false	The driver could not schedule the reception procedure.

bool nrf_802154_receive_at_cancel

(

void

)

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.

Return values

true	The delayed reception was scheduled and successfully cancelled.
false	No delayed reception was scheduled.

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_transmit	(	const uint8_t *	p_data,
		uint8_t	length,
		bool	cca
	)

Changes the radio state to transmit.

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.

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.

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 -----------------------------> |
* 

Parameters

[in]	p_data	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.
[in]	length	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).
[in]	cca	If the driver is to perform a CCA procedure before transmission.

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_transmit_raw_at	(	const uint8_t *	p_data,
		bool	cca,
		uint32_t	t0,
		uint32_t	dt,
		uint8_t	channel
	)

Requests transmission at the specified time.

Note

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

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 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.

This function is designed to transmit the first symbol of SHR at the given time.

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.

Parameters

[in]	p_data	Pointer to the array with data to transmit. The first byte must contain the frame length (including PHR and FCS). The following bytes contain data. The CRC is computed automatically by the radio hardware. Therefore, the FCS field can contain any bytes.
[in]	cca	If the driver is to perform a CCA procedure before transmission.
[in]	t0	Base of delay time - absolute time used by the Timer Scheduler, in microseconds (us).
[in]	dt	Delta of delay time from t0, in microseconds (us).
[in]	channel	Radio channel on which the frame is to be transmitted.

Return values

true	The transmission procedure was scheduled.
false	The driver could not schedule the transmission procedure.