 |
Contiki-NG
|
|
Contiki-NG
|
The radio API module defines a set of functions that a radio device driver must implement. More...
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. | |
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,
@ 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. | |
The radio API module defines a set of functions that a radio device driver must implement.
| #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.
Referenced by tsch_tx_slot().
| #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.
Referenced by send_ack_if_needed().
| 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.
| enum 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. |
| enum radio_power_mode_e |
Radio power modes.
Used as the value argument of get_value() / set_value() when param is RADIO_PARAM_POWER_MODE.
| enum 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. |
| enum 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. |
| enum radio_tx_e |
Radio return values for the transmit() function.
1.17.0