RIOT/sys/net/gnrc/link_layer/lwmac/Kconfig

# Copyright (c) 2020 Freie Universitaet Berlin
#
# This file is subject to the terms and conditions of the GNU Lesser
# General Public License v2.1. See the file LICENSE in the top level
# directory for more details.
#
menuconfig KCONFIG_USEMODULE_GNRC_LWMAC
    bool "Configure GNRC LWMAC"
    depends on USEMODULE_GNRC_LWMAC
    help
        Configure the GNRC LWMAC using Kconfig.

if KCONFIG_USEMODULE_GNRC_LWMAC

config GNRC_LWMAC_WAKEUP_INTERVAL_US
    int "Time between consecutive wake-ups in microseconds"
    default 200000
    help
        Configure 'CONFIG_GNRC_LWMAC_WAKEUP_INTERVAL_US', time between
        consecutive wake-ups in microseconds. This configuration governs power
        consumption, latency and throughput! In LWMAC, devices adopt duty-cycle
        scheme to conserve power. That is, time is divided into repeated cycles
        (or, superframes), and in each cycle, a node only wakes up for a period
        of time for receiving potential incoming packets for itself. This
        configuration defines the wake-up interval, or, in other words, defines
        the cycle duration used in LWMAC. If the wake-up interval is short,
        nodes will wake up more frequently, which also increases the chances
        for receiving packets from neighbors (i.e., leads to higher throughput,
        but also results in higher power consumption. In LWMAC, by default, we
        regard the wake-up period as the beginning of a cycle.

config GNRC_LWMAC_TIME_BETWEEN_WR_US
    int "Timeout to send the next WR in microseconds"
    default 5000
    help
        Configure 'CONFIG_GNRC_LWMAC_WAKEUP_INTERVAL_US', timeout to send the
        next WR in case no WA has been received during that time in
        microseconds.In LWMAC, when a sender initiates a transmission to a
        receiver, it starts with sending a stream of repeated WR packets with
        'CONFIG_GNRC_LWMAC_TIME_BETWEEN_WR_US' interval between two
        consecutive WRs. After sending one WR (preamble) packet, the sender
        turns to the listen mode to receive the potential incoming WA
        (preamble-ACK) packet with a timeout of
        'CONFIG_GNRC_LWMAC_TIME_BETWEEN_WR_US'. If no WA is received during
        'CONFIG_GNRC_LWMAC_TIME_BETWEEN_WR_US', the sender starts sending
        the next WR. It is referenced to the beginning of both WRs, but due to
        internal overhead, the exact spacing is slightly higher. The minimum
        possible value depends on the time it takes to completely send a WR
        with the given hardware (including processor) and data rate.

config GNRC_LWMAC_WR_PREPARATION_US
    int "WR preparation overhead time in microseconds"
    default 3000
    help
        Configure 'CONFIG_GNRC_LWMAC_WR_PREPARATION_US', WR preparation overhead
        before it can be sent (higher with debugging output).In LWMAC, when a
        sender wants to send a data packet to the receiver, it starts sending
        the WR stream a little bit earlier (advance) to the beginning edge of
        destination's wake-up phase over time. The idea is not to miss the
        wake-up period of the receiver, otherwise will lead to a long WR
        procedure.

config GNRC_LWMAC_DATA_DELAY_US
    int "Time to wait after a WA in microseconds"
    default 10000
    help
        Configure 'CONFIG_GNRC_LWMAC_DATA_DELAY_US', time to wait after a WA
        for data to arrive in microseconds. When a node in LWMAC gets a WR
        during its wake-up period, it immediately replies a WA packet to the
        sender for acknowledging the sender's transmission request. After
        sending the WA, the receiver waits for the data packet from the sender,
        with a timeout of 'CONFIG_GNRC_LWMAC_DATA_DELAY_US' duration. In case
        no data will be received in this period, the receiver regards
        reception failed and go back to normal listen mode. However, in case the
        receiver receives other unintended packets, like WR/WA packets from
        other neighbor communication pairs, the receiver resets this timeout
        and continues to wait for the data packet, with the consideration that
        the sender's data transmission might be delayed due to other ongoing
        transmissions (the data packet is transmitted with CSMA/CA). This data
        timeout is long enough to catch the beginning of the packet if the
        transceiver supports 'NETDEV_EVENT_RX_STARTED' event (this can be
        important for big packets).

config GNRC_LWMAC_DATA_CSMA_RETRIES
    int "Number of CSMA retries for DATA packet after WR->WA success"
    default 3
    help
        Configure 'CONFIG_GNRC_LWMAC_DATA_CSMA_RETRIES', number of CSMA retries
        for DATA packet after WR->WA was successful. After receiving the WA
        packet 'gnrc_lwmac_frame_wa_t' from the receiver, the sender starts
        sending the data packet using CSMA/CA. This configuration defines how
        many CSMA retries a sender will be allowed to execute for sending its
        data, before the data is successfully sent (gets data ACK from the
        receiver).

config GNRC_LWMAC_MAX_DATA_TX_RETRIES
    int "MAX number of TX retries for DATA packet"
    default 3
    help
        Configure 'CONFIG_GNRC_LWMAC_MAX_DATA_TX_RETRIES', the maximum number
        of TX transmission retries for DATA packet in case of no response from
        the receiver.  When a data packet is scheduled for transmission, i.e.,
        pushed into TX for sending, LWMAC defines a maximum of
        'CONFIG_GNRC_LWMAC_MAX_DATA_TX_RETRIES' retries for transmission of the
        packet. That is, in case of transmission failure in TX due to no WA
        from the receiver, the sender will not drop the packet, but keeps it
        and retries to send the data packet in the following cycles, until the
        sender reaches the maximum retries limit defined here. Then, the packet
        will be dropped.

config GNRC_LWMAC_MAX_RX_EXTENSION_NUM
    int "MAX number of bad listen period extensions"
    default 3
    help
        Configure 'CONFIG_GNRC_LWMAC_MAX_RX_EXTENSION_NUM', the maximum
        number of bad listen period extensions a node can tolerate. In LWMAC,
        to allow burst transmissions, when in the wake-up period and by
        default, a node will extend its wake-up period to another
        'GNRC_LWMAC_WAKEUP_DURATION_US' after each packet reception (except for
        broadcast packet). However, in some cases, a receiver may overhear other
        unintended packets, e.g., WR or WA packets for other nodes, these are
        called bad extensions for the receiver. If a receiver reaches the
        maximum bad listen extension limit defined here, it goes to sleep mode
        with the consideration that the channel is currently unavailable/busy.

config GNRC_LWMAC_BROADCAST_CSMA_RETRIES
    int "Number of CSMA retries for broadcast packet"
    default 3
    help
        Configure 'CONFIG_GNRC_LWMAC_BROADCAST_CSMA_RETRIES',the number of CSMA
        retries for broadcast packet. Currently, each broadcast packet is sent
        with CSMA/CA for collision avoidance. **Too many CSMA retries may lead
        to running out of destinations wake-up period**.

config GNRC_LWMAC_TIMEOUT_COUNT
    int "MAX number of number of parallel timeouts"
    default 3
    help
        Configure 'CONFIG_GNRC_LWMAC_TIMEOUT_COUNT', the default value for the
        maximum number of parallel timeouts in LWMAC.
config GNRC_LWMAC_RADIO_REINIT_THRESHOLD
    int "Maximum preamble attempts before re-initialize radio"
    default 10
    help
        Configure 'CONFIG_GNRC_LWMAC_RADIO_REINIT_THRESHOLD', the maximum preamble
        attempts before re-initialize radio. After a long period of run time, a radio
        may be in wrong condition which needs to be re-calibrated. This is indicated
        by having a series of continuous preamble failure (no WA) in LWMAC. In case
        we have @ref GNRC_LWMAC_RADIO_REINI_THRESHOLD number of preamble failure,
        then we re-initialize the radio, trying to re-calibrate the radio for bringing
        it back to normal condition.

endif # KCONFIG_USEMODULE_GNRC_LWMAC