Contiki-NG
Loading...
Searching...
No Matches

Data Structures

struct  radio_driver
 The structure of a Contiki-NG radio device driver. More...
 

Macros

#define RADIO_TX_MODE_SEND_ON_CCA   (1 << 0)
 Radio TX mode control / retrieval.
 

Typedefs

typedef int radio_value_t
 Each radio has a set of parameters that designate the current configuration and state of the radio.
 
typedef enum radio_result_e radio_result_t
 Radio return values when setting or getting radio parameters.
 

Enumerations

enum  radio_param_e {
  RADIO_PARAM_POWER_MODE , RADIO_PARAM_CHANNEL , RADIO_PARAM_PAN_ID , RADIO_PARAM_16BIT_ADDR ,
  RADIO_PARAM_RX_MODE , RADIO_PARAM_TX_MODE , RADIO_PARAM_TXPOWER , RADIO_PARAM_CCA_THRESHOLD ,
  RADIO_PARAM_RSSI , RADIO_PARAM_LAST_RSSI , RADIO_PARAM_IQ_LSBS , RADIO_PARAM_LAST_LINK_QUALITY ,
  RADIO_PARAM_64BIT_ADDR , RADIO_PARAM_LAST_PACKET_TIMESTAMP , RADIO_PARAM_SHR_SEARCH , RADIO_CONST_CHANNEL_MIN ,
  RADIO_CONST_CHANNEL_MAX , RADIO_CONST_TXPOWER_MIN , RADIO_CONST_TXPOWER_MAX , RADIO_CONST_TSCH_TIMING ,
  RADIO_CONST_PHY_OVERHEAD , RADIO_CONST_BYTE_AIR_TIME , RADIO_CONST_DELAY_BEFORE_TX , RADIO_CONST_DELAY_BEFORE_RX ,
  RADIO_CONST_DELAY_BEFORE_DETECT , RADIO_CONST_MAX_PAYLOAD_LEN
}
 Radio parameters and constants. More...
 
enum  radio_power_mode_e { RADIO_POWER_MODE_OFF , RADIO_POWER_MODE_ON , RADIO_POWER_MODE_CARRIER_ON , RADIO_POWER_MODE_CARRIER_OFF }
 Radio power modes. More...
 
enum  radio_shr_search_e { RADIO_SHR_SEARCH_DIS = 0 , RADIO_SHR_SEARCH_EN = 1 }
 Possible values of the get_value() / set_value() value argument when the param argument is RADIO_PARAM_SHR_SEARCH. More...
 
enum  radio_result_e { RADIO_RESULT_OK , RADIO_RESULT_NOT_SUPPORTED , RADIO_RESULT_INVALID_VALUE , RADIO_RESULT_ERROR }
 Radio return values when setting or getting radio parameters. More...
 
enum  radio_tx_e { RADIO_TX_OK , RADIO_TX_ERR , RADIO_TX_COLLISION , RADIO_TX_NOACK }
 Radio return values for the transmit() function. More...
 

Radio RX mode

The radio reception mode controls address filtering and automatic transmission of acknowledgements in the radio (if such operations are supported by the radio).

A single parameter is used to allow setting these features simultaneously as an atomic operation.

These macros are meant to be used as the value argument of get_value() and set_value() when the param argument is RADIO_PARAM_RX_MODE.

To enable both address filter and transmissions of automatic acknowledgments:

NETSTACK_RADIO.set_value(RADIO_PARAM_RX_MODE,
#define RADIO_RX_MODE_ADDRESS_FILTER
Enable address-based frame filtering.
Definition radio.h:451
#define RADIO_RX_MODE_AUTOACK
Enable automatic transmission of ACK frames.
Definition radio.h:456
@ RADIO_PARAM_RX_MODE
Radio receiver mode determines if the radio has address filter (RADIO_RX_MODE_ADDRESS_FILTER) and aut...
Definition radio.h:173
#define RADIO_RX_MODE_ADDRESS_FILTER   (1 << 0)
 Enable address-based frame filtering.
 
#define RADIO_RX_MODE_AUTOACK   (1 << 1)
 Enable automatic transmission of ACK frames.
 
#define RADIO_RX_MODE_POLL_MODE   (1 << 2)
 Enable/disable/get the state of radio driver poll mode operation.
 

Detailed Description

The radio API module defines a set of functions that a radio device driver must implement.

Macro Definition Documentation

◆ RADIO_RX_MODE_ADDRESS_FILTER

#define RADIO_RX_MODE_ADDRESS_FILTER   (1 << 0)

Enable address-based frame filtering.

This will typically involve filtering based on PAN ID, Short address and long address. The filtering will consider the params RADIO_PARAM_PAN_ID, RADIO_PARAM_16BIT_ADDR and RADIO_PARAM_64BIT_ADDR respectively.

Definition at line 451 of file radio.h.

◆ RADIO_TX_MODE_SEND_ON_CCA

#define RADIO_TX_MODE_SEND_ON_CCA   (1 << 0)

Radio TX mode control / retrieval.

The radio transmission mode controls whether transmissions should be done using clear channel assessment (if supported by the radio). If send-on-CCA is enabled, the radio's send function will wait for a radio-specific time window for the channel to become clear. If this does not happen, the send function will return RADIO_TX_COLLISION.

Definition at line 474 of file radio.h.

Typedef Documentation

◆ radio_value_t

typedef int radio_value_t

Each radio has a set of parameters that designate the current configuration and state of the radio.

Parameters can either have values of type radio_value_t, or, when this type is insufficient, a generic object that is specified by a memory pointer and the size of the object.

The radio_value_t type is set to an integer type that can hold most values used to configure the radio, and is therefore the most common type used for a parameter. Certain parameters require objects of a considerably larger size than radio_value_t, however, and in these cases the documentation below for the parameter will indicate this.

All radio parameters that can vary during runtime are prefixed by RADIO_PARAM_, whereas those "parameters" that are guaranteed to remain immutable are prefixed by RADIO_CONST_. Each mutable parameter has a set of valid parameter values. When attempting to set a parameter to an invalid value, the radio will return RADIO_RESULT_INVALID_VALUE.

Some radios support only a subset of the defined radio parameters. When trying to set or get such an unsupported parameter, the radio will return RADIO_RESULT_NOT_SUPPORTED.

Definition at line 88 of file radio.h.

Enumeration Type Documentation

◆ radio_param_e

Radio parameters and constants.

The fields of this enum are expected to be used as the param argument of get_value(), set_value(), get_object() and set_object().

More specifically, fields prefixed with RADIO_PARAM_ may be passed as an argument to any of those four functions. Exceptions are documented on a per-field basis. Fields prefixed with RADIO_CONST_ will only be passed as an argument to get_value() and get_object().

Enumerator
RADIO_PARAM_POWER_MODE 

When getting the value of this parameter, the radio driver should indicate whether the radio is on or not.

RADIO_POWER_MODE_ON: The radio is powered and ready to receive frames RADIO_POWER_MODE_OFF: The radio is powered off

When setting the value of this parameter, the driver should put the radio part in the corresponding state. RADIO_POWER_MODE_ON: The radio should be powered on and ready to receive frames. This is equivalent to a call to NETSTACK_RADIO.on(). RADIO_POWER_MODE_OFF: The radio should be put in the lowest power consumption state available. This is equivalent to a call to NETSTACK_RADIO.off().

RADIO_PARAM_CHANNEL 

Channel used for radio communication.

The channel depends on the communication standard used by the radio. The values can range from RADIO_CONST_CHANNEL_MIN to RADIO_CONST_CHANNEL_MAX.

When setting this parameter, the change should take effect immediately if the radio is in RADIO_POWER_MODE_ON. Otherwise the change should take effect the next time the radio turns on.

When reading this parameter, the driver should return the currently configured channel if the radio is in RADIO_POWER_MODE_ON, or the last used channel is the radio is currently in RADIO_POWER_MODE_OFF.

RADIO_PARAM_PAN_ID 

The personal area network identifier (PAN ID), which is used by the h/w frame filtering functionality of some radios.

Setting this param will typically require the radio driver to commit the PAN ID to some radio hardware register used for frame filtering.

Getting this param will typically require the radio driver to return the value currently stored in the respective hardware register.

If the hardware does not support frame filtering, there is no expectation to perform such filtering in the radio driver software. In the case of such radios, the driver can simply return RADIO_RESULT_NOT_SUPPORTED.

RADIO_PARAM_16BIT_ADDR 

The short address (16 bits) for the radio, which is used by the h/w filter.

Setting this param will typically require the radio driver to commit the value to some radio hardware register used for frame filtering.

Getting this param will typically require the radio driver to return the value currently stored in the respective hardware register.

If the hardware does not support frame filtering, there is no expectation to perform such filtering in the radio driver software. In the case of such radios, the driver can simply return RADIO_RESULT_NOT_SUPPORTED.

RADIO_PARAM_RX_MODE 

Radio receiver mode determines if the radio has address filter (RADIO_RX_MODE_ADDRESS_FILTER) and auto-ACK (RADIO_RX_MODE_AUTOACK) enabled.

This parameter is set as a bit mask.

RADIO_PARAM_TX_MODE 

Radio transmission mode determines if the radio has send on CCA (RADIO_TX_MODE_SEND_ON_CCA) enabled or not.

This parameter is set as a bit mask.

RADIO_PARAM_TXPOWER 

Transmission power in dBm.

The values can range from RADIO_CONST_TXPOWER_MIN to RADIO_CONST_TXPOWER_MAX.

Some radios restrict the available values to a subset of this range. If an unavailable TXPOWER value is requested to be set, the radio may select another TXPOWER close to the requested one. When getting the value of this parameter, the actual value used by the radio will be returned.

RADIO_PARAM_CCA_THRESHOLD 

Clear channel assessment threshold in dBm.

This threshold determines the minimum RSSI level at which the radio will assume that there is a packet in the air.

The CCA threshold must be set to a level above the noise floor of the deployment. Otherwise mechanisms such as send-on-CCA and low-power-listening duty cycling protocols may not work correctly. Hence, the default value of the system may not be optimal for any given deployment.

RADIO_PARAM_RSSI 

Received signal strength indicator in dBm.

When getting this parameter, the radio driver should return the current RSSI value as reported by the radio.

This may require turning on the radio and requesting an RSSI sample.

This parameter will only be passed as an argument to the get_value() function.

RADIO_PARAM_LAST_RSSI 

The RSSI value of the last received packet.

This parameter will only be passed as an argument to the get_value() function.

RADIO_PARAM_IQ_LSBS 

The current I/Q LSBs.

This parameter will only be passed as an argument to the get_value() function.

RADIO_PARAM_LAST_LINK_QUALITY 

Link quality indicator of the last received packet.

The value returned should be an unsigned number between 0x00 and 0xFF.

This parameter will only be passed as an argument to the get_value() function.

RADIO_PARAM_64BIT_ADDR 

Long (64 bits) address for the radio, which is used by the address filter.

The address is specified in network byte order.

Because this parameter value is larger than what fits in radio_value_t, it needs to be used with get_object()/set_object().

Setting this param will typically require the radio driver to commit the value to some radio hardware register used for frame filtering.

Getting this param will typically require the radio driver to return the value currently stored in the respective hardware register.

If the hardware does not support frame filtering, there is no expectation to perform such filtering in the radio driver software. In the case of such radios, the driver can simply return RADIO_RESULT_NOT_SUPPORTED.

RADIO_PARAM_LAST_PACKET_TIMESTAMP 

Last packet timestamp, of type rtimer_clock_t.

The timestamp corresponds to the point in time between the end of reception of the synchronisation header and the start of reception of the physical header (PHR).

+---------------+-----+---------------+---------------+-----+
| SHR | PHR | MHR | MAC Payload | MFR |
+---------------+-----+---------------+---------------+-----+
^
--- Timestamp --|

Because this parameter value may be larger than what fits in radio_value_t, it needs to be used with get_object()/set_object().

This parameter will only be passed as an argument to the get_object() function.

RADIO_PARAM_SHR_SEARCH 

For enabling and disabling the SHR search.

Setting this param to RADIO_SHR_SEARCH_DIS will disable SHR search. This means that when the radio is in receive mode it can be used to sample RSSI or to perform a clear channel assessment (CCA), but it will not receive frames.

Setting this param to RADIO_SHR_SEARCH_EN will enable SHR search. This means that when the radio is in receive mode it will receive frames as normal.

When setting this parameter, the change should take effect immediately if the radio is in RADIO_POWER_MODE_ON. Otherwise the change should take effect the next time the radio turns on.

RADIO_CONST_CHANNEL_MIN 

The lowest radio channel number.

RADIO_CONST_CHANNEL_MAX 

The highest radio channel number.

RADIO_CONST_TXPOWER_MIN 

The minimum transmission power in dBm.

RADIO_CONST_TXPOWER_MAX 

The maximum transmission power in dBm.

RADIO_CONST_PHY_OVERHEAD 

The physical layer header (PHR) + MAC layer footer (MFR) overhead in bytes.

This does not include the synchronisation header (SHR).

For example, on IEEE 802.15.4 at 2.4 GHz this will be 3 bytes: 1 byte for the frame length (PHR) + 2 bytes for the CRC (MFR)

RADIO_CONST_BYTE_AIR_TIME 

The air time of one byte in usec, e.g.

32 for IEEE 802.15.4 at 2.4 GHz

RADIO_CONST_DELAY_BEFORE_TX 

The delay in usec between a call to the radio API's transmit function and the end of SFD transmission.

RADIO_CONST_DELAY_BEFORE_RX 

The delay in usec between turning on the radio and it being actually listening (able to hear a preamble)

RADIO_CONST_DELAY_BEFORE_DETECT 

The delay in usec between the end of SFD reception for an incoming frame and the radio API starting to return receiving_packet() != 0

Definition at line 102 of file radio.h.

◆ radio_power_mode_e

Radio power modes.

Used as the value argument of get_value() / set_value() when param is RADIO_PARAM_POWER_MODE.

Enumerator
RADIO_POWER_MODE_OFF 

Radio powered off and in the lowest possible power consumption state.

RADIO_POWER_MODE_ON 

Radio powered on and able to receive frames.

RADIO_POWER_MODE_CARRIER_ON 

Radio powered on and emitting unmodulated carriers.

RADIO_POWER_MODE_CARRIER_OFF 

Radio powered on, but not emitting unmodulated carriers.

Definition at line 391 of file radio.h.

◆ radio_result_e

Radio return values when setting or getting radio parameters.

Enumerator
RADIO_RESULT_OK 

The parameter was set/read successfully.

RADIO_RESULT_NOT_SUPPORTED 

The parameter is not supported.

RADIO_RESULT_INVALID_VALUE 

The value argument was incorrect.

RADIO_RESULT_ERROR 

An error occurred when getting/setting the parameter, but the arguments were otherwise correct.

Definition at line 479 of file radio.h.

◆ radio_shr_search_e

Possible values of the get_value() / set_value() value argument when the param argument is RADIO_PARAM_SHR_SEARCH.

Enumerator
RADIO_SHR_SEARCH_DIS 

Disable SHR search or SHR search is enabled.

RADIO_SHR_SEARCH_EN 

Enable SHR search or SHR search is enabled.

Definition at line 417 of file radio.h.

◆ radio_tx_e

enum radio_tx_e

Radio return values for the transmit() function.

Enumerator
RADIO_TX_OK 

TX was successful and where an ACK was requested one was received.

RADIO_TX_ERR 

An error occurred during transmission.

This will typically signify that the transmitted frame was too long/short or that an error occurred at the radio driver level.

RADIO_TX_COLLISION 

TX failed due to a collision.

RADIO_TX_NOACK 

A unicast frame was sent OK but an ACK was not received.

Definition at line 494 of file radio.h.