Functions to request FSM transitions and check current state

Functions
nrf_802154_state_t	nrf_802154_state_get (void)
	Get current state of the radio.
bool	nrf_802154_sleep (void)
	Change radio state to sleep. More...
nrf_802154_sleep_error_t	nrf_802154_sleep_if_idle (void)
	Change radio state to sleep if radio is idle. More...
bool	nrf_802154_receive (void)
	Change radio state to receive. More...
bool	nrf_802154_receive_at (uint32_t t0, uint32_t dt, uint32_t timeout, uint8_t channel)
	Request reception at specified time. More...
bool	nrf_802154_transmit (const uint8_t *p_data, uint8_t length, bool cca)
	Change 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)
	Request transmission at specified time. More...
bool	nrf_802154_energy_detection (uint32_t time_us)
	Change radio state to energy detection. More...
bool	nrf_802154_cca (void)
	Change radio state to CCA. More...
bool	nrf_802154_continuous_carrier (void)
	Change radio state to continuous carrier. More...

Detailed Description

Function Documentation

bool nrf_802154_cca

(

void

)

Change radio state to CCA.

Note

nrf_802154_cca_done may be called before this function returns a result.

In 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	If the CCA procedure was scheduled.
false	If the driver could not schedule the CCA procedure.

bool nrf_802154_continuous_carrier

(

void

)

Change radio state to continuous carrier.

Note

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

This function works correctly only with a single-PHY arbiter. It should not be used with any other arbiter.

Return values

true	If the continuous carrier procedure was scheduled.
false	If the driver could not schedule the continuous carrier procedure.

bool nrf_802154_energy_detection

(

uint32_t

time_us

)

Change radio state to energy detection.

In 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 may be called before this function returns a result.

Performing the energy detection procedure make take longer time than requested in time_us. The procedure is performed only during timeslots granted by a radio arbiter. It may 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 8s (128 us).

Return values

true	If the energy detection procedure was scheduled.
false	If the driver could not schedule the energy detection procedure.

bool nrf_802154_receive

(

void

)

Change radio state to receive.

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

Return values

true	If the radio enters receive state.
false	If the driver could not enter receive state.

bool nrf_802154_receive_at	(	uint32_t	t0,
		uint32_t	dt,
		uint32_t	timeout,
		uint8_t	channel
	)

Request reception at specified time.

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

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

Parameters

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

Return values

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

bool nrf_802154_sleep

(

void

)

Change radio state to sleep.

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 radio sleep state.

Return values

true	If the radio changes its state to low power mode.
false	If the driver could not schedule changing state.

nrf_802154_sleep_error_t nrf_802154_sleep_if_idle

(

void

)

Change radio state to sleep if radio is idle.

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 radio sleep state.

Return values

NRF_802154_SLEEP_ERROR_NONE	If the radio changes its state to low power mode.
NRF_802154_SLEEP_ERROR_BUSY	If the driver could not schedule changing state.

bool nrf_802154_transmit	(	const uint8_t *	p_data,
		uint8_t	length,
		bool	cca
	)

Change 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 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 array containing 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 shall exclude PHR and FCS fields from the given frame (exact size of buffer pointed to by p_data).
[in]	cca	If the driver should perform a CCA procedure before transmission.

Return values

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

bool nrf_802154_transmit_raw_at	(	const uint8_t *	p_data,
		bool	cca,
		uint32_t	t0,
		uint32_t	dt,
		uint8_t	channel
	)

Request transmission at specified time.

Note

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

This function works as delayed version of the nrf_802154_transmit_raw. It is not blocking, but queues delayed transmission using Radio Scheduler module. If delayed transmission cannot be performed (the nrf_802154_transmit_raw would return false) or requested transmission timeslot is denied, the nrf_802154_transmit_failed with the NRF_802154_TX_ERROR_TIMESLOT_DENIED argument is called.

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

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

Parameters

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

Return values

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