Configuration options for network APIs

List of available configuration options for the Network Device Driver API and the GNRC communication interface. More...

Detailed Description

List of available configuration options for the Network Device Driver API and the GNRC communication interface.

Files

file  netopt.h
 Definition of global configuration options.
 

Enumerations

enum  netopt_t {
  NETOPT_CHANNEL, NETOPT_IS_CHANNEL_CLR, NETOPT_ADDRESS, NETOPT_ADDRESS_LONG,
  NETOPT_ADDR_LEN, NETOPT_SRC_LEN, NETOPT_NID, NETOPT_HOP_LIMIT,
  NETOPT_IPV6_IID, NETOPT_IPV6_ADDR, NETOPT_IPV6_ADDR_REMOVE, NETOPT_IPV6_ADDR_FLAGS,
  NETOPT_IPV6_GROUP, NETOPT_IPV6_GROUP_LEAVE, NETOPT_IPV6_FORWARDING, NETOPT_IPV6_SND_RTR_ADV,
  NETOPT_TX_POWER, NETOPT_MAX_PACKET_SIZE, NETOPT_PRELOADING, NETOPT_PROMISCUOUSMODE,
  NETOPT_AUTOACK, NETOPT_ACK_REQ, NETOPT_RETRANS, NETOPT_PROTO,
  NETOPT_STATE, NETOPT_RAWMODE, NETOPT_RX_START_IRQ, NETOPT_RX_END_IRQ,
  NETOPT_TX_START_IRQ, NETOPT_TX_END_IRQ, NETOPT_AUTOCCA, NETOPT_CSMA,
  NETOPT_CSMA_RETRIES, NETOPT_CSMA_MAXBE, NETOPT_CSMA_MINBE, NETOPT_MAC_NO_SLEEP,
  NETOPT_IS_WIRED, NETOPT_DEVICE_TYPE, NETOPT_CHANNEL_PAGE, NETOPT_CCA_THRESHOLD,
  NETOPT_CCA_MODE, NETOPT_STATS, NETOPT_ENCRYPTION, NETOPT_ENCRYPTION_KEY,
  NETOPT_RF_TESTMODE, NETOPT_L2FILTER, NETOPT_L2FILTER_RM, NETOPT_LAST_ED_LEVEL,
  NETOPT_PREAMBLE_LENGTH, NETOPT_INTEGRITY_CHECK, NETOPT_CHANNEL_HOP, NETOPT_CHANNEL_HOP_PERIOD,
  NETOPT_SINGLE_RECEIVE, NETOPT_RX_TIMEOUT, NETOPT_TX_TIMEOUT, NETOPT_BANDWIDTH,
  NETOPT_SPREADING_FACTOR, NETOPT_CODING_RATE, NETOPT_FIXED_HEADER, NETOPT_IQ_INVERT,
  NETOPT_6LO_IPHC, NETOPT_TX_RETRIES_NEEDED, NETOPT_NUMOF
}
 Global list of configuration options available throughout the network stack, e.g. More...
 
enum  netopt_enable_t { NETOPT_DISABLE = 0, NETOPT_ENABLE = 1 }
 Binary parameter for enabling and disabling options. More...
 
enum  netopt_state_t {
  NETOPT_STATE_OFF = 0, NETOPT_STATE_SLEEP, NETOPT_STATE_IDLE, NETOPT_STATE_RX,
  NETOPT_STATE_TX, NETOPT_STATE_RESET, NETOPT_STATE_STANDBY
}
 Option parameter to be used with NETOPT_STATE to set or get the state of a network device or protocol implementation. More...
 
enum  netopt_rf_testmode_t { NETOPT_RF_TESTMODE_IDLE = 0, NETOPT_RF_TESTMODE_CRX, NETOPT_RF_TESTMODE_CTX_CW, NETOPT_RF_TESTMODE_CTX_PRBS9 }
 Option parameter to be used with NETOPT_RF_TESTMODE. More...
 

Functions

const char * netopt2str (netopt_t opt)
 Get a string ptr corresponding to opt, for debugging. More...
 

Enumeration Type Documentation

◆ netopt_enable_t

Binary parameter for enabling and disabling options.

Enumerator
NETOPT_DISABLE 

disable a given option

NETOPT_ENABLE 

enable a given option

Definition at line 460 of file netopt.h.

◆ netopt_rf_testmode_t

Option parameter to be used with NETOPT_RF_TESTMODE.

Enumerator
NETOPT_RF_TESTMODE_IDLE 

idle mode, radio off

NETOPT_RF_TESTMODE_CRX 

continuous rx mode

NETOPT_RF_TESTMODE_CTX_CW 

carrier wave continuous tx mode

NETOPT_RF_TESTMODE_CTX_PRBS9 

PRBS9 continuous tx mode.

Definition at line 492 of file netopt.h.

◆ netopt_state_t

Option parameter to be used with NETOPT_STATE to set or get the state of a network device or protocol implementation.

Enumerator
NETOPT_STATE_OFF 

powered off

NETOPT_STATE_SLEEP 

sleep mode

NETOPT_STATE_IDLE 

idle mode, the device listens to receive packets

NETOPT_STATE_RX 

receive mode, the device currently receives a packet

NETOPT_STATE_TX 

transmit mode, set: triggers transmission of a preloaded packet (see NETOPT_PRELOADING*).

The resulting state of the network device is NETOPT_STATE_IDLE get: the network device is in the process of transmitting a packet

NETOPT_STATE_RESET 

triggers a hardware reset.

The resulting state of the network device is NETOPT_STATE_IDLE

NETOPT_STATE_STANDBY 

standby mode.

The devices is awake but not listening to packets.

Definition at line 469 of file netopt.h.

◆ netopt_t

enum netopt_t

Global list of configuration options available throughout the network stack, e.g.

by netdev and netapi

Enumerator
NETOPT_CHANNEL 

get/set channel as uint16_t in host byte order

NETOPT_IS_CHANNEL_CLR 

check if channel is clear

NETOPT_ADDRESS 

get/set address in host byte order

NETOPT_ADDRESS_LONG 

get/set long address in host byte order

Examples for this include the EUI-64 in IEEE 802.15.4

NETOPT_ADDR_LEN 

get the default address length a network device expects as uint16_t in host byte order

NETOPT_SRC_LEN 

get/set the address length to choose for the network device's source address as uint16_t in host byte order

NETOPT_NID 

get/set the network ID as uint16_t in host byte order

Examples for this include the PAN ID in IEEE 802.15.4

NETOPT_HOP_LIMIT 

get/set hop limit as uint8_t

NETOPT_IPV6_IID 

get the IPv6 interface identifier of a network interface as eui64_t.

See also
RFC 4291, section 2.5.1

The generation of the interface identifier is dependent on the link-layer. Please refer to the appropriate IPv6 over <link> specification for further implementation details (such as RFC 2464 or RFC 4944).

NETOPT_IPV6_ADDR 

get IPv6 addresses of an interface as array of ipv6_addr_t or add an IPv6 address as ipv6_addr_t to an interface

When adding an IPv6 address to a GNRC interface using GNRC_NETAPI_MSG_TYPE_SET, the gnrc_netapi_opt_t::context field can be used to pass the prefix length (8 MSB) and some flags (8 LSB) according to net_gnrc_netif_ipv6_addrs_flags. The address is however always considered to be manually added. When getting the option you can pass an array of ipv6_addr_t of any length greater than 0 to the getter. The array will be filled up to to its maximum and the remaining addresses on the interface will be ignored

NETOPT_IPV6_ADDR_REMOVE 

Removes an IPv6 address as ipv6_addr_t from an interface.

NETOPT_IPV6_ADDR_FLAGS 

get the flags to the addresses returned by NETOPT_IPV6_ADDR as array of uint8_t

The information contained in the array is very specific to the interface's API. For GNRC e.g. the values are according to net_gnrc_netif_ipv6_addrs_flags.

NETOPT_IPV6_GROUP 

get IPv6 multicast groups of an interface as array of ipv6_addr_t or join an IPv6 multicast group as ipv6_addr_t on an interface

When adding an IPv6 address to a GNRC interface using GNRC_NETAPI_MSG_TYPE_SET, the gnrc_netapi_opt_t::context field can be used to pass the prefix length (8 MSB) and some flags (8 LSB) according to net_gnrc_netif_ipv6_addrs_flags. The address is however always considered to be manually added. When getting the option you can pass an array of ipv6_addr_t of any length greater than 0 to the getter. The array will be filled up to to its maximum and the remaining addresses on the interface will be ignored

NETOPT_IPV6_GROUP_LEAVE 

Leaves an IPv6 multicast group as ipv6_addr_t on an interface.

NETOPT_IPV6_FORWARDING 

en/disable IPv6 forwarding or read the current state

NETOPT_IPV6_SND_RTR_ADV 

en/disable sending of IPv6 router advertisements or read the current state

NETOPT_TX_POWER 

get/set the output power for radio devices in dBm as int16_t in host byte order

NETOPT_MAX_PACKET_SIZE 

get/set the maximum packet size a network module can handle as uint16_t in host byte order

NETOPT_PRELOADING 

en/disable preloading or read the current state.

Preload using gnrc_netdev_driver_t::send_data() or gnrc_netapi_send() respectively, send setting state to NETOPT_STATE_TX

NETOPT_PROMISCUOUSMODE 

en/disable promiscuous mode or read the current state

NETOPT_AUTOACK 

en/disable link layer auto ACKs or read the current state

NETOPT_ACK_REQ 

en/disable acknowledgement requests or read the current state

NETOPT_RETRANS 

get/set the maximum number of retransmissions.

NETOPT_PROTO 

get/set the protocol for the layer as type gnrc_nettype_t.

NETOPT_STATE 

get/set the state of network devices as type netopt_state_t

NETOPT_RAWMODE 

en/disable the pre-processing of data in a network device driver as type gnrc_nettype_t

NETOPT_RX_START_IRQ 

en/disable the interrupt at reception start.

It is mostly triggered after the preamble is correctly received

Note
not all transceivers may support this interrupt
NETOPT_RX_END_IRQ 

en/disable the interrupt after packet reception.

This interrupt is triggered after a complete packet is received.

Note
in case a transceiver does not support this interrupt, the event may be triggered by the driver
NETOPT_TX_START_IRQ 

en/disable the interrupt right in the beginning of transmission.

This interrupt is triggered when the transceiver starts to send out the packet.

Note
in case a transceiver does not support this interrupt, the event may be triggered by the driver
NETOPT_TX_END_IRQ 

en/disable the interrupt after packet transmission.

This interrupt is triggered when the full packet is transmitted.

Note
not all transceivers may support this interrupt
NETOPT_AUTOCCA 

Check automatically before sending if the channel is clear.

This may be a hardware feature of the given transceiver, or might be otherwise implemented in software. If the device supports CSMA this option will enable CSMA with a certain set of parameters to emulate the desired behaviour.

Note
Be sure not to set NETOPT_CSMA simultaneously.

TODO: How to get feedback?

NETOPT_CSMA 

en/disable CSMA/CA support

If the device supports CSMA in hardware, this option enables it with default parameters. For further configuration refer to the other NETOPT_CSMA_* options.

NETOPT_CSMA_RETRIES 

get/set the maximum number of CSMA retries

(uint8_t) The maximum number of backoffs the CSMA-CA algorithm will attempt before declaring a channel access failure. Named macMaxCsmaBackoffs in IEEE Std 802.15.4-2015.

802.15.4 default: 4

NETOPT_CSMA_MAXBE 

get/set the maximum backoff exponent for the CSMA-CA algorithm

(uint8_t) Named macMaxBE in IEEE Std 802.15.4-2015.

802.15.4 default: 5

NETOPT_CSMA_MINBE 

get/set the minimum backoff exponent for the CSMA-CA algorithm

(uint8_t) Named macMinBE in IEEE Std 802.15.4-2015.

802.15.4 default: 3

NETOPT_MAC_NO_SLEEP 

en/disable blocking of radio sleep when running a duty cycling MAC layer

(netopt_enable_t) Enabling this option tells the MAC layer to never put the radio to sleep. Useful in gateways and routers not running on batteries to improve responsiveness and allow battery powered nodes on the same network to sleep more often.

NETOPT_IS_WIRED 

read-only check for a wired interface.

If the interface is wireless this function will return -ENOTSUP, a positive value otherwise.

Note
Setting this option will always return -ENOTSUP.
NETOPT_DEVICE_TYPE 

get a device's "type", e.g., ethernet, 802.15.4, ...

NETOPT_CHANNEL_PAGE 

get/set the channel page as defined by IEEE 802.15.4

NETOPT_CCA_THRESHOLD 

get/set the CCA threshold for the radio transceiver

This is the value, in dBm, that the radio transceiver uses to decide if the channel is clear or not (CCA). If the current signal strength (RSSI/ED) is stronger than this CCA threshold value, the transceiver usually considers that the radio medium is busy. Otherwise, i.e. if RSSI/ED value is less than the CCA threshold value, the radio medium is supposed to be free (the possibly received weak signal is considered to be background, meaningless noise).

Most transceivers allow to set this CCA threshold value. Some research work has proven that dynamically adapting it to network environment can improve QoS, especially in WSN.

NETOPT_CCA_MODE 

CCA mode for the radio transceiver.

Get/set the CCA mode as uint8_t corresponding to the respective PHY standard.

NETOPT_STATS 

get statistics about sent and received packets and data of the device or protocol

Expects a pointer to a netstats_t struct that will be pointed to the corresponding netstats_t of the module.

NETOPT_ENCRYPTION 

en/disable encryption.

en/disable encryption

NETOPT_ENCRYPTION_KEY 

set encryption key

NETOPT_RF_TESTMODE 

Test mode for the radio, e.g.

for CE or FCC certification

Get/set the test mode as type netopt_rf_testmode_t or as uint8_t if the radio supports other vendor specific test modes.

Note
Setting this option should always return -ENOTSUP, unless it was explicitly allowed at build time, therefore it should be secured with an additional macro in the device driver. For development and certification purposes only, this test modes can disturb normal radio communications and exceed the limits, established by the regulatory authority.
NETOPT_L2FILTER 

add an address to a link layer filter list

'Getting' this option from a device will return a pointer of type l2filter_t to the first entry of a filter list. When 'Setting' this option a pointer to an link layer address as well as the length of the address are expected as parameters.

NETOPT_L2FILTER_RM 

remove an address from a link layer filter list

'Getting' this value always returns -ENOTSUP. When 'Setting' this option a pointer to an link layer address as well as the length of the address are expected as parameters. 'Setting' this option will lead to the given address being removed from the filer list.

NETOPT_LAST_ED_LEVEL 

Energy level during the last performed CCA or RX frame.

Get the last ED level available as an int8_t. The source of the measurement is unspecified and may come from the latest CCA measurement (CCA mode 1), or from the last received frame.

NETOPT_PREAMBLE_LENGTH 

Get/Set preamble length as uint16_t in host byte order.

NETOPT_INTEGRITY_CHECK 

Enable/disable integrity check (e.g CRC).

NETOPT_CHANNEL_HOP 

Enable/disable channel hopping.

NETOPT_CHANNEL_HOP_PERIOD 

Get/Set channel hopping period as uint8_t.

NETOPT_SINGLE_RECEIVE 

Enable/disable single packet reception.

If enabled, RX is turned off upon reception of a packet

NETOPT_RX_TIMEOUT 

Get/Set the reception timeout of a packet.

Values are retrieved/passed as uint32_t in host byte order.

NETOPT_TX_TIMEOUT 

Get/Set the transmission timeout of a packet.

Values are retrieved/passed as uint32_t in host byte order.

NETOPT_BANDWIDTH 

Get/Set the radio modulation bandwidth as uint8_t.

NETOPT_SPREADING_FACTOR 

Get/Set the radio spreading factor as uint8_t.

NETOPT_CODING_RATE 

Get/Set the radio coding rate as uint8_t.

NETOPT_FIXED_HEADER 

Enable/disable fixed header mode.

NETOPT_IQ_INVERT 

Enable/disable IQ inverted.

NETOPT_6LO_IPHC 

en/disable header compression according to RFC 6282 or read the current state

NETOPT_TX_RETRIES_NEEDED 

Get retry amount from missing ACKs of the last transmission.

This retrieves the number of retries needed for the last transmissions. Only retransmissions due to missing ACK packets are considered. Retries due to CCA failures are not counted.

NETOPT_NUMOF 

maximum number of options defined here.

Note
Interfaces are not meant to respond to that.

Definition at line 36 of file netopt.h.

Function Documentation

◆ netopt2str()

const char* netopt2str ( netopt_t  opt)

Get a string ptr corresponding to opt, for debugging.

Parameters
[in]optThe option to get a string representation for
Returns
ptr to string representation for given option or "unknown"