net/lorawan : Update documentation

Marked as non-supported: LORAMAC_DEFAULT_ADR_ACK_LIMIT LORAMAC_DEFAULT_ADR_ACK_DELAY LORAMAC_DEFAULT_ADR_TIMEOUT
2024-12-29 04:50:03 +01:00 · 2020-11-25 19:41:32 +01:00 · 2020-11-25 19:41:32 +01:00 · 42eb6c4097
commit 42eb6c4097
parent 9600ebf536
3 changed files with 134 additions and 58 deletions
--- a/examples/lorawan/README.md
+++ b/examples/lorawan/README.md
@ -30,8 +30,9 @@ ST Nucleo-64 can be used with mbed LoRa shields: there's one based on
 [the sx1276 radio](https://os.mbed.com/components/SX1276MB1xAS/) and one based
 on the [the sx1272 radio](https://os.mbed.com/components/SX1272MB2xAS/).

-Finally, to join a LoRaWAN network using OTAA activation, edit the application
-`Makefile` and set your device information:
+Finally, to join a LoRaWAN network using OTAA activation, use `make menuconfig`
+inside the application and edit the configuration or edit the application
+`Makefile` :

    DEVEUI ?= 0000000000000000
    APPEUI ?= 0000000000000000
--- a/pkg/semtech-loramac/contrib/semtech_loramac.c
+++ b/pkg/semtech-loramac/contrib/semtech_loramac.c
@ -204,8 +204,6 @@ static size_t _write_uint32(size_t pos, uint32_t value)
    return eeprom_write(pos, array, sizeof(uint32_t));
 }

-
-
 static inline void _set_join_state(semtech_loramac_t *mac, bool joined)
 {
    DEBUG("[semtech-loramac] set join state ? %d\n", joined);
--- a/sys/include/net/loramac.h
+++ b/sys/include/net/loramac.h
@ -39,7 +39,7 @@ extern "C" {
 /**
 * @brief   Default device EUI
 *
- *          8 bytes key, required for join procedure
+ * 8 bytes key, required for join procedure
 */
 #ifndef CONFIG_LORAMAC_DEV_EUI_DEFAULT
 #define CONFIG_LORAMAC_DEV_EUI_DEFAULT          "0000000000000000"
@ -48,7 +48,7 @@ extern "C" {
 /**
 * @brief   Default application EUI
 *
- *          8 bytes key, required for join procedure
+ * 8 bytes key, required for join procedure
 */
 #ifndef CONFIG_LORAMAC_APP_EUI_DEFAULT
 #define CONFIG_LORAMAC_APP_EUI_DEFAULT          "0000000000000000"
@ -57,7 +57,7 @@ extern "C" {
 /**
 * @brief   Default application key
 *
- *          16 bytes key, required for join procedure
+ * 16 bytes key, required for join procedure
 */
 #ifndef CONFIG_LORAMAC_APP_KEY_DEFAULT
 #define CONFIG_LORAMAC_APP_KEY_DEFAULT          "00000000000000000000000000000000"
@ -66,7 +66,7 @@ extern "C" {
 /**
 * @brief   Default application session key
 *
- *          16 bytes key, only required for ABP join procedure type
+ * 16 bytes key, only required for ABP join procedure type
 */
 #ifndef CONFIG_LORAMAC_APP_SKEY_DEFAULT
 #define CONFIG_LORAMAC_APP_SKEY_DEFAULT         "00000000000000000000000000000000"
@ -75,7 +75,7 @@ extern "C" {
 /**
 * @brief   Default network session key
 *
- *          16 bytes key, only required for ABP join procedure type.
+ * 16 bytes key, only required for ABP join procedure type.
 */
 #ifndef CONFIG_LORAMAC_NWK_SKEY_DEFAULT
 #define CONFIG_LORAMAC_NWK_SKEY_DEFAULT         "00000000000000000000000000000000"
@ -87,14 +87,9 @@ extern "C" {
 #ifndef CONFIG_LORAMAC_DEV_ADDR_DEFAULT
 #define CONFIG_LORAMAC_DEV_ADDR_DEFAULT         "00000000"
 #endif
-/** @} */

 /**
- * @name    LoRaMAC default values
- * @{
- */
-/**
- * @brief Default LoRaWAN region
+ * @brief   Default LoRaWAN region
 */
 #if !IS_ACTIVE(CONFIG_LORAMAC_REGION_EU_868) \
    && !IS_ACTIVE(CONFIG_LORAMAC_REGION_IN_865)
@ -104,7 +99,14 @@ extern "C" {
 /**
 * @brief   Default device class (A, B or C)
 *
- * @note GNRC LoRaWAN only supports Class A
+ * Configure the class of device. LoRaWAN supports three classes of operation
+ * for end nodes namely Class A, B and C. All LoRaWAN devices are expected to
+ * implement Class A, whereas Class B and Class C can be considered as
+ * extensions to the specification of Class A devices.
+ *
+ * @see     [LoRaWAN Classes by TTN](https://www.thethingsnetwork.org/docs/lorawan/classes.html)
+ *
+ * @note    GNRC LoRaWAN only supports Class A
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS_A)
 #define CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS     (LORAMAC_CLASS_A)
@ -120,6 +122,11 @@ extern "C" {

 /**
 * @brief   Default NetID (only valid with ABP join procedure)
+ *
+ * NETID is used by networks for assigning network-specific addresses to their
+ * end-devices (i.e., DevAddr) so that uplink frames sent by those devices even
+ * when they are roaming outside their home network can be forwarded to their
+ * home network.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_NETID
 #define CONFIG_LORAMAC_DEFAULT_NETID            (1U)
@ -155,7 +162,13 @@ extern "C" {
 #endif

 /**
- * @brief   Default datarate
+ * @brief   Default datarate index
+ *
+ * Data rate combines two aspects, Bandwidth (BW) and Spreading Factor (SF). BW
+ * depends on the region while SF contributes to the dwell time in any given
+ * band which is limited by region. DR hence signifies difference combination on
+ * BW and SF for different regions. Refer LoRaWAN 1.0.3 Regional Parameters for
+ * more information.
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_0)
 #define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_0)
@ -196,7 +209,10 @@ extern "C" {
 #endif

 /**
- * @brief   Default MAC TX power
+ * @brief   Default MAC TX power index
+ *
+ * TXPower index indicates power levels relative to the max EIRP level of the
+ * end-device. Refer LoRaWAN 1.0.3 Regional Parameters for more information.
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_0)
 #define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_0)
@ -238,6 +254,12 @@ extern "C" {

 /**
 * @brief   Default MAC TX port (from 1 to 223)
+ *
+ * The TX port denotes the port field `FPort` in the payload and is commonly
+ * used on the destination side (Application Server) to distinguish different
+ * payload formats. For example it can be used to identify different sensor
+ * types/values from the same end-node and hence different payload formats can
+ * be assigned to the different values based on value of port.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_TX_PORT
 #define CONFIG_LORAMAC_DEFAULT_TX_PORT          (2U)
@ -245,6 +267,11 @@ extern "C" {

 /**
 * @brief   Default MAC TX mode (confirmable or unconfirmable)
+ *
+ * A confirmed uplink will expect an acknowledgment from the network server;
+ * otherwise, the message will be retransmitted by the number indicated by
+ * @ref  CONFIG_LORAMAC_DEFAULT_RETX , whereas an unconfirmed message will not
+ * expect any acknowledgment back from the network server.
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_MODE_CNF)
 #define CONFIG_LORAMAC_DEFAULT_TX_MODE          (LORAMAC_TX_CNF)
@ -257,7 +284,12 @@ extern "C" {
 #endif

 /**
- * @brief   Default adaptive datarate state
+ * @brief   Enable/disable adaptive datarate state
+ *
+ * If enabled the end node will inform the network server about the status of
+ * ADR using the ADR field in uplink data packet. The network server will then
+ * optimize the data rate and the transmission power of the end node based on
+ * the information collected from the network.
 */
 #ifdef DOXYGEN
 #define CONFIG_LORAMAC_DEFAULT_ADR
@ -265,6 +297,9 @@ extern "C" {

 /**
 * @brief   Default uplink retransmission
+ *
+ * Maximum number of retransmissions to be used for a confirmed uplink packet,
+ * if no downlink acknowledgment is received from the network.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_RETX
 #define CONFIG_LORAMAC_DEFAULT_RETX             (5U)
@ -273,7 +308,10 @@ extern "C" {
 /**
 * @brief   Default link check interval (in seconds)
 *
- *          0 means the link check process is disabled
+ * 0 means the link check process is disabled. The link check process is used by
+ * an end-device to validate its connectivity with the network. The frame has
+ * no payload. When a `LinkCheckReq` is received by the network server via one
+ * or multiple gateways, it responds with a `LinkCheckAns` MAC command.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_LINKCHK
 #define CONFIG_LORAMAC_DEFAULT_LINKCHK          (0U)
@ -281,18 +319,19 @@ extern "C" {

 /**
 * @brief   Default first RX window delay (in ms)
+ *
+ * This configuration specifies the delay in seconds to open the RX1 window
+ * after the end of uplink modulation on the end-node.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_RX1_DELAY
 #define CONFIG_LORAMAC_DEFAULT_RX1_DELAY        (1000U)
 #endif

 /**
- * @brief   Default second RX window delay (in ms)
- */
-#define LORAMAC_DEFAULT_RX2_DELAY              (1000U + CONFIG_LORAMAC_DEFAULT_RX1_DELAY)
-
-/**
- * @brief   Default second RX window datarate index
+ * @brief   Default second RX (RX2) window datarate index
+ *
+ * This may be changed only if the network server can be configured with the
+ * same datarate.
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_0)
 #define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_0)
@ -337,7 +376,7 @@ extern "C" {
 #endif

 /**
- * @brief   Default second RX window frequency (in Hz)
+ * @brief   Default second RX (RX2) window frequency (in Hz)
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_RX2_FREQ
 #if IS_ACTIVE(CONFIG_LORAMAC_REGION_EU_868)
@ -349,6 +388,13 @@ extern "C" {

 /**
 * @brief   Default LoRaMAC join procedure
+ *
+ * There are two options, Over The Air Activation (OTAA) results in device
+ * sending join request to the network whereas in the case of Activation By
+ * Personalization (ABP) the user enters the activation keys manually. OTAA is
+ * the preferred and most secure way to connect to a LoRaWAN network. For quick
+ * testing ABP is preferred as the device can transmit right away without
+ * waiting for the network to provision the keys.
 */
 #if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE_OTAA)
 #define CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE   (LORAMAC_JOIN_OTAA)
@ -362,6 +408,10 @@ extern "C" {

 /**
 * @brief   Default LoRaMAC join accept delay 1 (in seconds)
+ *
+ * Maximum wait time in end node to receive the `join-accept` message sent by
+ * the network in the first receive window. This is similar to the operation of
+ * RX1 window.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_JOIN_DELAY1
 #define CONFIG_LORAMAC_DEFAULT_JOIN_DELAY1      (5U)
@ -369,6 +419,10 @@ extern "C" {

 /**
 * @brief   Default LoRaMAC join accept delay 2
+ *
+ * Maximum wait time in end node to receive the `join-accept` message sent by
+ * the network in the second receive window. This is similar to the operation of
+ * RX2 window.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_JOIN_DELAY2
 #define CONFIG_LORAMAC_DEFAULT_JOIN_DELAY2      (6U)
@ -376,34 +430,20 @@ extern "C" {

 /**
 * @brief   Default max FCNT gap
+ *
+ * Frame counter deviation is the difference between the frame counter values
+ * transmitted by the End Node and the value stored in Network Server (NS).
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_MAX_FCNT_GAP
 #define CONFIG_LORAMAC_DEFAULT_MAX_FCNT_GAP     (16384U)
 #endif

-/**
- * @brief   Default adaptive datarate ACK limit (in s)
- */
-#ifndef LORAMAC_DEFAULT_ADR_ACK_LIMIT
-#define LORAMAC_DEFAULT_ADR_ACK_LIMIT          (64U)
-#endif
-
-/**
- * @brief   Default adaptive datarate ACK delay (in s)
- */
-#ifndef LORAMAC_DEFAULT_ADR_ACK_DELAY
-#define LORAMAC_DEFAULT_ADR_ACK_DELAY          (32U)
-#endif
-
-/**
- * @brief   Default adaptive datarate timeout
- */
-#ifndef LORAMAC_DEFAULT_ADR_TIMEOUT
-#define LORAMAC_DEFAULT_ADR_TIMEOUT            (3U)
-#endif
-
 /**
 * @brief   Default maximum system overall timing error
+ *
+ * This configuration is used to increase the RX window to account for timer
+ * drift. This may be decreased if the system clock is accurate, for eg: if the
+ * system clock is from a TCXO.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_SYSTEM_MAX_RX_ERROR
 #define CONFIG_LORAMAC_DEFAULT_SYSTEM_MAX_RX_ERROR  (50)
@ -411,12 +451,49 @@ extern "C" {

 /**
 * @brief   Default minimum RX symbols to detect a frame
+ *
+ * This configuration is used to arrive at `T_RX_late` which is used in RX
+ * window calculation. This may be increased to account for inaccuracies in
+ * system timer. Refer SX1276_settings_for_LoRaWAN_v2p2.pdf (AN1200.24)
+ * from Semtech for more information.
 */
 #ifndef CONFIG_LORAMAC_DEFAULT_MIN_RX_SYMBOLS
 #define CONFIG_LORAMAC_DEFAULT_MIN_RX_SYMBOLS   (12)
 #endif
 /** @} */

+/**
+ * @brief   Default adaptive datarate ACK limit (in s)
+ *
+ * @note This feature is not yet supported.
+ */
+#ifndef LORAMAC_DEFAULT_ADR_ACK_LIMIT
+#define LORAMAC_DEFAULT_ADR_ACK_LIMIT           (64U)
+#endif
+
+/**
+ * @brief   Default adaptive datarate ACK delay (in s)
+ *
+ * @note This feature is not yet supported.
+ */
+#ifndef LORAMAC_DEFAULT_ADR_ACK_DELAY
+#define LORAMAC_DEFAULT_ADR_ACK_DELAY           (32U)
+#endif
+
+/**
+ * @brief   Default adaptive datarate timeout
+ *
+ * @note This feature is not yet supported.
+ */
+#ifndef LORAMAC_DEFAULT_ADR_TIMEOUT
+#define LORAMAC_DEFAULT_ADR_TIMEOUT             (3U)
+#endif
+
+/**
+ * @brief   Default second RX window delay (in ms)
+ */
+#define LORAMAC_DEFAULT_RX2_DELAY               (1000U + CONFIG_LORAMAC_DEFAULT_RX1_DELAY)
+
 /**
 * @name    LoRaMAC constants
 * @{
@ -424,52 +501,52 @@ extern "C" {
 /**
 * @brief   Device EUI length in bytes
 */
-#define LORAMAC_DEVEUI_LEN             (8U)
+#define LORAMAC_DEVEUI_LEN                      (8U)

 /**
 * @brief   Device address length in bytes
 */
-#define LORAMAC_DEVADDR_LEN            (4U)
+#define LORAMAC_DEVADDR_LEN                     (4U)

 /**
 * @brief   Application EUI length in bytes
 */
-#define LORAMAC_APPEUI_LEN             (8U)
+#define LORAMAC_APPEUI_LEN                      (8U)

 /**
 * @brief   Application key length in bytes
 */
-#define LORAMAC_APPKEY_LEN             (16U)
+#define LORAMAC_APPKEY_LEN                      (16U)

 /**
 * @brief   Application session key length in bytes
 */
-#define LORAMAC_APPSKEY_LEN            (16U)
+#define LORAMAC_APPSKEY_LEN                     (16U)

 /**
 * @brief   Network session key length in bytes
 */
-#define LORAMAC_NWKSKEY_LEN            (16U)
+#define LORAMAC_NWKSKEY_LEN                     (16U)

 /**
 * @brief   Minimum port value
 */
-#define LORAMAC_PORT_MIN               (1U)
+#define LORAMAC_PORT_MIN                        (1U)

 /**
 * @brief   Maximmu port value
 */
-#define LORAMAC_PORT_MAX               (223U)
+#define LORAMAC_PORT_MAX                        (223U)

 /**
 * @brief Application Nonce length in bytes
 */
-#define LORAMAC_APP_NONCE_LEN          (3U)
+#define LORAMAC_APP_NONCE_LEN                   (3U)

 /**
 * @brief Network ID length in bytes
 */
-#define LORAMAC_NETWORK_ID_LEN         (3U)
+#define LORAMAC_NETWORK_ID_LEN                  (3U)

 /** @} */