ieee802154_radio_ops Struct Reference

Radio ops struct declaration. More...

Detailed Description

Radio ops struct declaration.

Definition at line 368 of file radio.h.

#include <radio.h>

Data Fields

int(* write )(ieee802154_dev_t *dev, const iolist_t *psdu)
 Write a frame into the framebuffer. More...
 
int(* request_transmit )(ieee802154_dev_t *dev)
 Request the transmission of a preloaded frame. More...
 
int(* confirm_transmit )(ieee802154_dev_t *dev, ieee802154_tx_info_t *info)
 Confirmation function for ieee802154_radio_ops::request_transmit. More...
 
int(* len )(ieee802154_dev_t *dev)
 Get the length of the received PSDU frame. More...
 
int(* read )(ieee802154_dev_t *dev, void *buf, size_t size, ieee802154_rx_info_t *info)
 Read a frame from the internal framebuffer. More...
 
int(* off )(ieee802154_dev_t *dev)
 Turn off the device. More...
 
int(* request_on )(ieee802154_dev_t *dev)
 Request to turn on the device. More...
 
int(* confirm_on )(ieee802154_dev_t *dev)
 Confirmation function for ieee802154_radio_ops::request_on. More...
 
int(* request_set_trx_state )(ieee802154_dev_t *dev, ieee802154_trx_state_t state)
 Request a PHY state change. More...
 
int(* confirm_set_trx_state )(ieee802154_dev_t *dev)
 Confirmation function for ieee802154_radio_ops::request_set_trx_state. More...
 
int(* request_cca )(ieee802154_dev_t *dev)
 Request Stand-Alone Clear Channel Assessment. More...
 
int(* confirm_cca )(ieee802154_dev_t *dev)
 Confirmation function for ieee802154_radio_ops::request_cca. More...
 
bool(* get_cap )(ieee802154_dev_t *dev, ieee802154_rf_caps_t cap)
 Get a cap from the radio. More...
 
int(* set_cca_threshold )(ieee802154_dev_t *dev, int8_t threshold)
 Set the threshold for the Energy Detection (first mode of CCA) More...
 
int(* set_cca_mode )(ieee802154_dev_t *dev, ieee802154_cca_mode_t mode)
 Set CCA mode. More...
 
int(* config_phy )(ieee802154_dev_t *dev, const ieee802154_phy_conf_t *conf)
 Set IEEE802.15.4 PHY configuration (channel, TX power) More...
 
int(* set_hw_addr_filter )(ieee802154_dev_t *dev, const network_uint16_t *short_addr, const eui64_t *ext_addr, const uint16_t *pan_id)
 Set IEEE802.15.4 addresses in hardware address filter. More...
 
int(* set_frame_retrans )(ieee802154_dev_t *dev, uint8_t retrans)
 Set number of frame retransmissions. More...
 
int(* set_csma_params )(ieee802154_dev_t *dev, const ieee802154_csma_be_t *bd, int8_t retries)
 Set the CSMA-CA parameters. More...
 
int(* set_rx_mode )(ieee802154_dev_t *dev, ieee802154_rx_mode_t mode)
 Set the RX mode. More...
 

Field Documentation

◆ config_phy

int(* ieee802154_radio_ops::config_phy) (ieee802154_dev_t *dev, const ieee802154_phy_conf_t *conf)

Set IEEE802.15.4 PHY configuration (channel, TX power)

This function SHOULD NOT validate the PHY configurations unless it's specific to the device. The upper layer is responsible of all kind of validations. In case a configuration is not valid (e.g parameters out of range), this function should return -EINVAL

Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]confthe PHY configuration
Returns
0 on success
-EINVAL if the configuration is not valid for the device.
negative errno on error

Definition at line 645 of file radio.h.

◆ confirm_cca

int(* ieee802154_radio_ops::confirm_cca) (ieee802154_dev_t *dev)

Confirmation function for ieee802154_radio_ops::request_cca.

This function must be called to finish the CCA procedure. This function should be called on IEEE802154_RADIO_CONFIRM_CCA, If no interrupt is available, this function can be polled.

Precondition
call to ieee802154_radio_ops::request_cca was successful.
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
positive number if the channel is clear
0 if the channel is busy
-EAGAIN if the CCA procedure hasn't finished.
negative errno on error

Definition at line 585 of file radio.h.

◆ confirm_on

int(* ieee802154_radio_ops::confirm_on) (ieee802154_dev_t *dev)

Confirmation function for ieee802154_radio_ops::request_on.

Precondition
call to ieee802154_radio_ops::request_on was successful.
Postcondition
the transceiver state is IEEE802154_TRX_STATE_TRX_OFF During boot or in case the radio doesn't support IEEE802154_CAP_REG_RETENTION when off was called, the Physical Information Base will be undefined. Thus, take into consideration that the following functions should be called right after the radio is turned on again:
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
0 if the device is on
-EAGAIN if the device is still busy turning on
negative errno on error

Definition at line 515 of file radio.h.

◆ confirm_set_trx_state

int(* ieee802154_radio_ops::confirm_set_trx_state) (ieee802154_dev_t *dev)

Confirmation function for ieee802154_radio_ops::request_set_trx_state.

Precondition
call to ieee802154_radio_ops::request_set_trx_state was successful.
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
0 if the state transition was successful
-EAGAIN if the transition has not finished yet
negative errno on error

Definition at line 549 of file radio.h.

◆ confirm_transmit

int(* ieee802154_radio_ops::confirm_transmit) (ieee802154_dev_t *dev, ieee802154_tx_info_t *info)

Confirmation function for ieee802154_radio_ops::request_transmit.

This function must be called to finish the transmission procedure and get the transmission status. This function should be called on IEEE802154_RADIO_CONFIRM_TX_DONE. If no interrupt is available, this function can be polled.

Precondition
the device is on
call to ieee802154_radio_ops::request_transmit was successful.
Postcondition
the state is IEEE802154_TRX_STATE_TX_ON.
Parameters
[in]devIEEE802.15.4 device descriptor
[out]infothe TX information. Pass NULL if the information is not needed. If the radio supports AutoCCA, the status should indicate transmission done or channel busy. If the radio supports frame retransmissions, the status should indicate if medium was busy, no ACK was received or transmission succeeded.
Returns
0 on success
-EAGAIN if the transmission has not finished yet.
negative errno on error

Definition at line 423 of file radio.h.

◆ get_cap

bool(* ieee802154_radio_ops::get_cap) (ieee802154_dev_t *dev, ieee802154_rf_caps_t cap)

Get a cap from the radio.

Parameters
[in]devIEEE802.15.4 device descriptor
capcap to be checked
Returns
true if the radio supports the cap
false otherwise

Definition at line 596 of file radio.h.

◆ len

int(* ieee802154_radio_ops::len) (ieee802154_dev_t *dev)

Get the length of the received PSDU frame.

Precondition
the device is on
the radio already received a frame (e.g ieee802154_dev::cb with IEEE802154_RADIO_INDICATION_RX_DONE).
Postcondition
the frame buffer is still protected against new frame arrivals.
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
length of the frame

Definition at line 438 of file radio.h.

◆ off

int(* ieee802154_radio_ops::off) (ieee802154_dev_t *dev)

Turn off the device.

Parameters
[in]devIEEE802.15.4 device descriptor

When this function returns, the radio shall be off.

Postcondition
the device is off (and thus, the transceiver state is IEEE802154_TRX_STATE_TRX_OFF)
Returns
0 on success
negative errno on error

Definition at line 473 of file radio.h.

◆ read

int(* ieee802154_radio_ops::read) (ieee802154_dev_t *dev, void *buf, size_t size, ieee802154_rx_info_t *info)

Read a frame from the internal framebuffer.

This function reads the received frame from the internal framebuffer. It should try to copy the received frame into buf

Postcondition
It's not safe to call this function again before setting the transceiver state to IEEE802154_TRX_STATE_RX_ON (thus flushing the RX FIFO).
Parameters
[in]devIEEE802.15.4 device descriptor
[out]bufbuffer to write the received PSDU frame into.
[in]sizesize of buf
[in]infoinformation of the received frame (LQI, RSSI). Can be NULL if this information is not needed.
Returns
number of bytes written in buffer (0 if buf == NULL)
-ENOBUFS if the frame doesn't fit in

Definition at line 459 of file radio.h.

◆ request_cca

int(* ieee802154_radio_ops::request_cca) (ieee802154_dev_t *dev)

Request Stand-Alone Clear Channel Assessment.

Precondition
the state is IEEE802154_TRX_STATE_RX_ON
Note
ieee802154_radio_ops::confirm_cca MUST be used to finish the CCA procedure and get the channel status.
Parameters
[in]devIEEE802.15.4 device descriptor
Postcondition
the state is IEEE802154_TRX_STATE_RX_ON
Returns
0 if request was OK
-EAGAIN if the request cannot be performed immediately.
negative errno on error

Definition at line 567 of file radio.h.

◆ request_on

int(* ieee802154_radio_ops::request_on) (ieee802154_dev_t *dev)

Request to turn on the device.

Note
ieee802154_radio_ops::confirm_on MUST be used to finish the procedure.
Precondition
the init function of the radio succeeded.
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
0 on success
negative errno on error

Definition at line 488 of file radio.h.

◆ request_set_trx_state

int(* ieee802154_radio_ops::request_set_trx_state) (ieee802154_dev_t *dev, ieee802154_trx_state_t state)

Request a PHY state change.

Note
ieee802154_radio_ops::confirm_set_trx_state MUST be used to finish the state transition. Also, setting the state to IEEE802154_TRX_STATE_RX_ON flushes the RX FIFO.
Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]statethe new state
Returns
0 on success
-EBUSY if the transceiver is busy
negative number on error

Definition at line 533 of file radio.h.

◆ request_transmit

int(* ieee802154_radio_ops::request_transmit) (ieee802154_dev_t *dev)

Request the transmission of a preloaded frame.

ieee802154_radio_ops::confirm_transmit MUST be used to finish the transmission.

Precondition
the PHY state is IEEE802154_TRX_STATE_TX_ON and the frame is already in the framebuffer.
Parameters
[in]devIEEE802.15.4 device descriptor
Returns
0 on success
negative errno on error

Definition at line 397 of file radio.h.

◆ set_cca_mode

int(* ieee802154_radio_ops::set_cca_mode) (ieee802154_dev_t *dev, ieee802154_cca_mode_t mode)

Set CCA mode.

All radios MUST at least implement the first CCA mode (ED Threshold).

Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]modethe CCA mode
Returns
0 on success
-ENOTSUP if the mode is not supported
negative errno on error

Definition at line 625 of file radio.h.

◆ set_cca_threshold

int(* ieee802154_radio_ops::set_cca_threshold) (ieee802154_dev_t *dev, int8_t threshold)

Set the threshold for the Energy Detection (first mode of CCA)

Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]thresholdthe threshold in dBm.
Returns
0 on success
negative errno on error

Definition at line 609 of file radio.h.

◆ set_csma_params

int(* ieee802154_radio_ops::set_csma_params) (ieee802154_dev_t *dev, const ieee802154_csma_be_t *bd, int8_t retries)

Set the CSMA-CA parameters.

Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]bdparameters of the exponential backoff. If NULL, the parameters are not altered.
[in]retriesnumber of CSMA-CA retries. If retries < 0, retransmissions with CSMA-CA MUST be disabled. If retries == 0, the ieee802154_radio_ops::request_transmit function is equivalent to CCA send.
Returns
0 on success
-EINVAL if the settings are not supported.
negative errno on error

Definition at line 701 of file radio.h.

◆ set_frame_retrans

int(* ieee802154_radio_ops::set_frame_retrans) (ieee802154_dev_t *dev, uint8_t retrans)

Set number of frame retransmissions.

Precondition
the device is on
Note
this function pointer can be NULL if the device doesn't support frame retransmissions
Parameters
[in]devIEEE802.15.4 device descriptor
[in]retransthe number of retransmissions attempts.
Returns
0 on success
negative errno on error

Definition at line 681 of file radio.h.

◆ set_hw_addr_filter

int(* ieee802154_radio_ops::set_hw_addr_filter) (ieee802154_dev_t *dev, const network_uint16_t *short_addr, const eui64_t *ext_addr, const uint16_t *pan_id)

Set IEEE802.15.4 addresses in hardware address filter.

Precondition
the device is on
Parameters
[in]devIEEE802.15.4 device descriptor
[in]short_addrthe IEEE802.15.4 short address. If NULL, the short address is not altered..
[in]ext_addrthe IEEE802.15.4 extended address (Network Byte Order). If NULL, the extended address is not altered.
[in]pan_idthe IEEE802.15.4 PAN ID. If NULL, the PAN ID is not altered.
Returns
0 on success
negative errno on error

Definition at line 662 of file radio.h.

◆ set_rx_mode

int(* ieee802154_radio_ops::set_rx_mode) (ieee802154_dev_t *dev, ieee802154_rx_mode_t mode)

Set the RX mode.

Parameters
[in]devIEEE802.15.4 device descriptor
[in]modeRX mode
Returns
0 on success
negative errno on error

Definition at line 713 of file radio.h.

◆ write

int(* ieee802154_radio_ops::write) (ieee802154_dev_t *dev, const iolist_t *psdu)

Write a frame into the framebuffer.

This function shouldn't do any checks, so the frame MUST be valid. The previous content of the framebuffer is replaced by psdu.

Parameters
[in]devIEEE802.15.4 device descriptor
[in]psduPSDU frame to be sent
Returns
0 on success
negative errno on error

Definition at line 381 of file radio.h.


The documentation for this struct was generated from the following file: