Netopt - Configuration options for network APIs¶
List of available configuration options for the Netdev - Network Device Driver API and the GNRC communication interface.
-
enum
netopt_t
¶ - NETOPT_CHANNEL
- (uint16_t) channel number
- NETOPT_IS_CHANNEL_CLR
(
netopt.h::netopt_enable_t
) check whether the network medium is clearGetting this option can be used to trigger a manual clear channel assessment (CCA) on some wireless devices.
- NETOPT_ADDRESS
(byte array, see below) link layer address in network byte order
Device type Length Meaning IEEE 802.15.4 2 device short address Ethernet 6 device MAC address nrfmin 2 device short address CC110x 1 device address - NETOPT_ADDRESS_LONG
(byte array, see below) long link layer address in network byte order
Device type Length Meaning IEEE 802.15.4 8 device long address (EUI-64), eui64_t nrfmin 8 device long address (based on short address) BLE 8 device long address (EUI-64), eui64_t - NETOPT_ADDR_LEN
- (uint16_t) get the default address length a network device expects
- NETOPT_SRC_LEN
- (uint16_t) address length to use for the link layer source address
- NETOPT_NID
(uint16_t) network ID
Examples for this include the PAN ID in IEEE 802.15.4
- NETOPT_HOP_LIMIT
- (uint8_t) hop limit
- NETOPT_IPV6_IID
(eui64_t) get the IPv6 interface identifier of a network interface
See also
<link>
specification for further implementation details (such as RFC 2464 or RFC 4944).- NETOPT_IPV6_ADDR
(ipv6_addr_t[]) 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
netapi.h::GNRC_NETAPI_MSG_TYPE_SET
, thenetapi.h::gnrc_netapi_opt_t::context
field can be used to pass the prefix length (8 MSB) and some flags (8 LSB) according to . 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
- (ipv6_addr_t) Removes an IPv6 address from an interface
- NETOPT_IPV6_ADDR_FLAGS
(array of uint8_t) get the flags to the addresses returned by netopt.h::netopt_t::NETOPT_IPV6_ADDR as array
The information contained in the array is very specific to the interface’s API. For GNRC e.g. the values are according to .
- NETOPT_IPV6_GROUP
(ipv6_addr_t) 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
netapi.h::GNRC_NETAPI_MSG_TYPE_SET
, thenetapi.h::gnrc_netapi_opt_t::context
field can be used to pass the prefix length (8 MSB) and some flags (8 LSB) according to . 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
- (ipv6_addr_t) Leave an IPv6 multicast group on an interface
- NETOPT_IPV6_FORWARDING
- (
netopt.h::netopt_enable_t
) IPv6 forwarding state - NETOPT_IPV6_SND_RTR_ADV
- (
netopt.h::netopt_enable_t
) sending of IPv6 router advertisements - NETOPT_TX_POWER
- (int16_t) transmit power for radio devices in dBm
- NETOPT_MAX_PACKET_SIZE
- (uint16_t) maximum packet size a network module can handle
- NETOPT_PRELOADING
(
netopt.h::netopt_enable_t
) frame preloadingPreload frame data using gnrc_netdev_driver_t::send_data() or
netapi.h::gnrc_netapi_send()
, trigger sending by setting state to netopt.h::netopt_state_t::NETOPT_STATE_TX- NETOPT_PROMISCUOUSMODE
- (
netopt.h::netopt_enable_t
) promiscuous mode - NETOPT_AUTOACK
- (
netopt.h::netopt_enable_t
) automatic link layer ACKs - NETOPT_ACK_PENDING
(
netopt.h::netopt_enable_t
) frame pending bit of ACKsFor IEEE 802.15.4, this bit is copied into the frame pending subfield of the ACK if it is the response to a data request MAC command frame.
- NETOPT_ACK_REQ
(
netopt.h::netopt_enable_t
) acknowledgement request on outgoing framesFor IEEE 802.15.4, this bit is copied into the ACK req subfield of the frame control field.
- NETOPT_RETRANS
- (uint8_t) maximum number of retransmissions
- NETOPT_PROTO
- (
nettype.h::gnrc_nettype_t
) the protocol for the layer - NETOPT_STATE
- (
netopt.h::netopt_state_t
) state of network device - NETOPT_RAWMODE
- (
netopt.h::netopt_enable_t
) when enabled, bypass protocol processing of incoming frames - NETOPT_RX_START_IRQ
(
netopt.h::netopt_enable_t
) trigger interrupt at reception startIt is mostly triggered after the preamble is correctly received
Note
not all transceivers may support this interrupt
- NETOPT_RX_END_IRQ
(
netopt.h::netopt_enable_t
) trigger interrupt after frame receptionThis interrupt is triggered after a complete frame is received.
Note
in case a transceiver does not support this interrupt, the event may be triggered by the driver
- NETOPT_TX_START_IRQ
(
netopt.h::netopt_enable_t
) trigger interrupt at transmission startThis interrupt is triggered when the transceiver starts to send out the frame.
Note
in case a transceiver does not support this interrupt, the event may be triggered by the driver
- NETOPT_TX_END_IRQ
(
netopt.h::netopt_enable_t
) trigger interrupt after frame transmissionThis interrupt is triggered when the full frame has been transmitted.
Note
not all transceivers may support this interrupt
- NETOPT_AUTOCCA
(
netopt.h::netopt_enable_t
) perform channel clear assessment before transmittingThis 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.
How to get feedback?
- NETOPT_LINK_CONNECTED
(
netopt.h::netopt_enable_t
) Phy link status.Returns NETOPT_ENABLE when the the link of the interface is up, NETOPT_DISABLE when the link is down. If the interface is wireless or doesn’t support link status detection this function will return -ENOTSUP.
Note
Setting this option will always return -ENOTSUP.
- NETOPT_CSMA
(
netopt.h::netopt_enable_t
) CSMA/CA supportIf 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
(uint8_t) maximum number of CSMA retries
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.
IEEE 802.15.4 default: 4
- NETOPT_CSMA_MAXBE
(uint8_t) maximum backoff exponent for the CSMA-CA algorithm
Named macMaxBE in IEEE Std 802.15.4-2015.
IEEE 802.15.4 default: 5
- NETOPT_CSMA_MINBE
(uint8_t) minimum backoff exponent for the CSMA-CA algorithm
Named macMinBE in IEEE Std 802.15.4-2015.
IEEE 802.15.4 default: 3
- NETOPT_MAC_NO_SLEEP
(
netopt.h::netopt_enable_t
) block transceiver sleepEnabling 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
(
netopt.h::netopt_enable_t
) read-only check for a wired interface.This option will return -ENOTSUP for wireless interfaces.
Note
Setting this option will always return -ENOTSUP.
- NETOPT_DEVICE_TYPE
(uint16_t) device type
e.g. NETDEV_TYPE_ETHERNET, NETDEV_TYPE_IEEE802154, etc.
- NETOPT_CHANNEL_PAGE
- (uint8_t) channel page as defined by IEEE 802.15.4
- NETOPT_CCA_THRESHOLD
(int8_t) CCA threshold for the radio transceiver
This is the value, in dBm, that the radio transceiver uses to decide whether 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
(uint8_t) CCA mode for the radio transceiver
Get/set the CCA mode corresponding to the respective PHY standard.
- NETOPT_STATS
(netstats_t*) 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
- (
netopt.h::netopt_enable_t
) link layer encryption. - NETOPT_ENCRYPTION_KEY
(byte array) set encryption key
The required byte array size is dependent on encryption algorithm and device.
- NETOPT_RF_TESTMODE
(
netopt.h::netopt_rf_testmode_t
) Test mode for the radio, e.g.for CE or FCC certification
Get/set the test mode as type
netopt.h::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.
- NETOPT_L2FILTER
(l2filter_t) 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
(l2filter_t) 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
(int8_t) 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
- (uint16_t) preamble length
- NETOPT_INTEGRITY_CHECK
- (
netopt.h::netopt_enable_t
) frame integrity check (e.g CRC) - NETOPT_CHANNEL_FREQUENCY
(uint32_t) channel center frequency
For example, with LoRa, this corresponds to the center frequency of each channel (867300000, etc) for a given frequency band (868, 915, etc).
- NETOPT_CHANNEL_HOP
- (
netopt.h::netopt_enable_t
) channel hopping - NETOPT_CHANNEL_HOP_PERIOD
- (uint8_t) channel hopping period
- NETOPT_SINGLE_RECEIVE
(
netopt.h::netopt_enable_t
) single frame receptionIf enabled, RX is turned off upon reception of a frame
- NETOPT_RX_TIMEOUT
(uint32_t) reception timeout of a frame
in what time unit?
- NETOPT_TX_TIMEOUT
(uint32_t) transmission timeout of a frame
in what time unit?
- NETOPT_BANDWIDTH
- (uint8_t) radio modulation bandwidth
- NETOPT_SPREADING_FACTOR
- (uint8_t) radio spreading factor
- NETOPT_CODING_RATE
- (uint8_t) radio coding rate
- NETOPT_FIXED_HEADER
- (
netopt.h::netopt_enable_t
) fixed header mode - NETOPT_IQ_INVERT
- (
netopt.h::netopt_enable_t
) IQ inverted - NETOPT_6LO_IPHC
(
netopt.h::netopt_enable_t
) header compressionSee also
- NETOPT_TX_RETRIES_NEEDED
(uint8_t) retry amount from missing ACKs of the last transmission
This retrieves the number of retries needed for the last transmission. Only retransmissions due to missing ACK frames are considered, retries due to CCA failures are not counted.
- NETOPT_BLE_CTX
(netdev_ble_ctx_t) set BLE radio context (channel, CRC, AA)
- NETOPT_CHECKSUM
(
netopt.h::netopt_enable_t
) enable hardware checksummingIf enabled, enable hardware checksumming of incoming frames.
- NETOPT_PHY_BUSY
(
netopt.h::netopt_enable_t
) enable busy modeWhen set, the PHY will enter busy mode, in which it will not accept incoming frames until unset.
- NETOPT_NUMOF
maximum number of options defined here.
Note
Interfaces are not meant to respond to this option
-
enum
netopt_enable_t
¶ - NETOPT_DISABLE
= 0
- disable a given option
- NETOPT_ENABLE
= 1
- enable a given option
- NETOPT_DISABLE
-
enum
netopt_state_t
¶ - NETOPT_STATE_OFF
= 0
- 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.h::netopt_t::NETOPT_PRELOADING*).
The resulting state of the network device is netopt.h::netopt_state_t::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.h::netopt_state_t::NETOPT_STATE_IDLE
- NETOPT_STATE_STANDBY
standby mode.
The devices is awake but not listening to packets.
- NETOPT_STATE_OFF
-
enum
netopt_rf_testmode_t
¶ - NETOPT_RF_TESTMODE_IDLE
= 0
- 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.
- NETOPT_RF_TESTMODE_IDLE
-
const char *
netopt2str
(netopt.h::netopt_t
opt)¶ Get a string ptr corresponding to opt, for debugging.
Parameters
opt: The option to get a string representation for Return values
- ptr to string representation for given option or “unknown”