loramac.h

Go to the documentation of this file.

/*
 * Copyright (C) 2017 Inria
 *
 * 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.
 */
 
#pragma once
 
#include <assert.h>
#include <stdint.h>
#include <stdlib.h>
 
#include "modules.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef CONFIG_LORAMAC_DEV_EUI_DEFAULT
#define CONFIG_LORAMAC_DEV_EUI_DEFAULT          "0000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_JOIN_EUI_DEFAULT
#define CONFIG_LORAMAC_JOIN_EUI_DEFAULT          "0000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_APP_EUI_DEFAULT
#define CONFIG_LORAMAC_APP_EUI_DEFAULT          "0000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_APP_KEY_DEFAULT
#define CONFIG_LORAMAC_APP_KEY_DEFAULT          "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_NWK_KEY_DEFAULT
#define CONFIG_LORAMAC_NWK_KEY_DEFAULT          "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_APP_SKEY_DEFAULT
#define CONFIG_LORAMAC_APP_SKEY_DEFAULT         "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_NWK_SKEY_DEFAULT
#define CONFIG_LORAMAC_NWK_SKEY_DEFAULT         "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_FNWKSINT_KEY_DEFAULT
#define CONFIG_LORAMAC_FNWKSINT_KEY_DEFAULT          "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_SNWKSINT_KEY_DEFAULT
#define CONFIG_LORAMAC_SNWKSINT_KEY_DEFAULT          "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_NWKSENC_KEY_DEFAULT
#define CONFIG_LORAMAC_NWKSENC_KEY_DEFAULT          "00000000000000000000000000000000"
#endif
 
#ifndef CONFIG_LORAMAC_DEV_ADDR_DEFAULT
#define CONFIG_LORAMAC_DEV_ADDR_DEFAULT         "00000000"
#endif
 
#if !IS_ACTIVE(CONFIG_LORAMAC_REGION_EU_868) \
    && !IS_ACTIVE(CONFIG_LORAMAC_REGION_IN_865)
#define CONFIG_LORAMAC_REGION_EU_868           1
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS_A)
#define CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS     (LORAMAC_CLASS_A)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS_B)
#define CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS     (LORAMAC_CLASS_B)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS_C)
#define CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS     (LORAMAC_CLASS_C)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS
#define CONFIG_LORAMAC_DEFAULT_DEVICE_CLASS     (LORAMAC_CLASS_A)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_NETID
#define CONFIG_LORAMAC_DEFAULT_NETID            (1U)
#endif
 
#ifdef DOXYGEN
#define CONFIG_LORAMAC_DEFAULT_PRIVATE_NETWORK
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_0)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_0)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_1)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_1)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_2)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_2)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_3)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_3)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_4)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_4)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_5)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_5)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_6)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_6)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_7)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_7)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_8)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_8)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_9)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_9)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_10)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_10)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_11)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_11)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_12)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_12)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_13)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_13)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_14)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_14)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_DR_15)
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_15)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_DR
#define CONFIG_LORAMAC_DEFAULT_DR               (LORAMAC_DR_0)
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_0)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_0)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_1)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_1)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_2)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_2)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_3)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_3)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_4)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_4)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_5)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_5)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_6)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_6)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_7)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_7)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_8)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_8)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_9)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_9)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_10)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_10)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_11)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_11)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_12)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_12)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_13)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_13)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_14)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_14)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_POWER_15)
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_15)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_TX_POWER
#define CONFIG_LORAMAC_DEFAULT_TX_POWER         (LORAMAC_TX_PWR_1)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_TX_PORT
#define CONFIG_LORAMAC_DEFAULT_TX_PORT          (2U)
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_MODE_CNF)
#define CONFIG_LORAMAC_DEFAULT_TX_MODE          (LORAMAC_TX_CNF)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_TX_MODE_UNCNF)
#define CONFIG_LORAMAC_DEFAULT_TX_MODE          (LORAMAC_TX_UNCNF)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_TX_MODE
#define CONFIG_LORAMAC_DEFAULT_TX_MODE          (LORAMAC_TX_CNF)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_REDUNDANCY
#define CONFIG_LORAMAC_DEFAULT_REDUNDANCY       (0U)
#endif
 
#ifdef DOXYGEN
#define CONFIG_LORAMAC_DEFAULT_ADR
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_RETX
#define CONFIG_LORAMAC_DEFAULT_RETX             (5U)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_LINKCHK
#define CONFIG_LORAMAC_DEFAULT_LINKCHK          (0U)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_RX1_DELAY
#define CONFIG_LORAMAC_DEFAULT_RX1_DELAY        (1000U)
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_0)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_0)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_1)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_1)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_2)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_2)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_3)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_3)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_4)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_4)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_5)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_5)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_6)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_6)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_7)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_7)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_8)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_8)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_9)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_9)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_10)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_10)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_11)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_11)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_12)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_12)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_13)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_13)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_14)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_14)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_RX2_DR_15)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_15)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_RX2_DR
#if IS_ACTIVE(CONFIG_LORAMAC_REGION_EU_868)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_0)
#elif IS_ACTIVE(CONFIG_LORAMAC_REGION_IN_865)
#define CONFIG_LORAMAC_DEFAULT_RX2_DR           (LORAMAC_DR_2)
#endif
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_RX2_FREQ
#if IS_ACTIVE(CONFIG_LORAMAC_REGION_EU_868)
#define CONFIG_LORAMAC_DEFAULT_RX2_FREQ         (869525000UL)
#elif IS_ACTIVE(CONFIG_LORAMAC_REGION_IN_865)
#define CONFIG_LORAMAC_DEFAULT_RX2_FREQ         (866550000UL)
#endif
#endif
 
#if IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE_OTAA)
#define CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE   (LORAMAC_JOIN_OTAA)
#elif IS_ACTIVE(CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE_ABP)
#define CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE   (LORAMAC_JOIN_ABP)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE
#define CONFIG_LORAMAC_DEFAULT_JOIN_PROCEDURE   (LORAMAC_JOIN_OTAA)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_JOIN_DELAY1
#define CONFIG_LORAMAC_DEFAULT_JOIN_DELAY1      (5U)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_JOIN_DELAY2
#define CONFIG_LORAMAC_DEFAULT_JOIN_DELAY2      (6U)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_MAX_FCNT_GAP
#define CONFIG_LORAMAC_DEFAULT_MAX_FCNT_GAP     (16384U)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_SYSTEM_MAX_RX_ERROR
#define CONFIG_LORAMAC_DEFAULT_SYSTEM_MAX_RX_ERROR  (50)
#endif
 
#ifndef CONFIG_LORAMAC_DEFAULT_MIN_RX_SYMBOLS
#define CONFIG_LORAMAC_DEFAULT_MIN_RX_SYMBOLS   (12)
#endif
#ifndef LORAMAC_DEFAULT_ADR_ACK_LIMIT
#define LORAMAC_DEFAULT_ADR_ACK_LIMIT           (64U)
#endif
 
#ifndef LORAMAC_DEFAULT_ADR_ACK_DELAY
#define LORAMAC_DEFAULT_ADR_ACK_DELAY           (32U)
#endif
 
#ifndef LORAMAC_DEFAULT_ADR_TIMEOUT
#define LORAMAC_DEFAULT_ADR_TIMEOUT             (3U)
#endif
 
#define LORAMAC_DEFAULT_RX2_DELAY               (1000U + CONFIG_LORAMAC_DEFAULT_RX1_DELAY)
 
#define LORAMAC_DEVEUI_LEN                      (8U)
 
#define LORAMAC_DEVADDR_LEN                     (4U)
 
#define LORAMAC_APPEUI_LEN                      (8U)
 
#define LORAMAC_JOINEUI_LEN                     (8U)
 
#define LORAMAC_APPKEY_LEN                      (16U)
 
#define LORAMAC_NWKKEY_LEN                      (16U)
 
#define LORAMAC_APPSKEY_LEN                     (16U)
 
#define LORAMAC_NWKSKEY_LEN                     (16U)
 
#define LORAMAC_FNWKSINTKEY_LEN                 (16U)
 
#define LORAMAC_SNWKSINTKEY_LEN                 (16U)
 
#define LORAMAC_NWKSENCKEY_LEN                  (16U)
 
#define LORAMAC_JSINTKEY_LEN                  (16U)
 
#define LORAMAC_JSENCKEY_LEN                  (16U)
 
#define LORAMAC_JSINTKEY_LEN                  (16U)
 
#define LORAMAC_PORT_MIN                        (1U)
 
#define LORAMAC_PORT_MAX                        (223U)
 
#define LORAMAC_APP_NONCE_LEN                   (3U)
 
#define LORAMAC_JOIN_NONCE_LEN                  (3U)
 
#define LORAMAC_NETWORK_ID_LEN                  (3U)
 
#if defined(REGION_AU915) || defined(REGION_CN470) || defined(REGION_US915) || defined(REGION_US915_HYBRID) || defined(REGION_AS923)
#define LORAMAC_CHANNELS_MASK_LEN                     (6U)
#else
#define LORAMAC_CHANNELS_MASK_LEN                     (1U)
#endif
 
typedef enum {
    LORAMAC_CLASS_A,                   
    LORAMAC_CLASS_B,                   
    LORAMAC_CLASS_C,                   
} loramac_class_t;
 
typedef enum {
    LORAMAC_JOIN_OTAA,                 
    LORAMAC_JOIN_ABP,                  
} loramac_join_mode_t;
 
typedef enum {
    LORAMAC_TX_CNF,                    
    LORAMAC_TX_UNCNF,                  
} loramac_tx_mode_t;
 
typedef enum {
    LORAMAC_DR_0 = 0,
    LORAMAC_DR_1,
    LORAMAC_DR_2,
    LORAMAC_DR_3,
    LORAMAC_DR_4,
    LORAMAC_DR_5,
    LORAMAC_DR_6,
    LORAMAC_DR_7,
    LORAMAC_DR_8,
    LORAMAC_DR_9,
    LORAMAC_DR_10,
    LORAMAC_DR_11,
    LORAMAC_DR_12,
    LORAMAC_DR_13,
    LORAMAC_DR_14,
    LORAMAC_DR_15,
} loramac_dr_idx_t;
 
typedef enum {
    LORAMAC_TX_PWR_0 = 0,
    LORAMAC_TX_PWR_1,
    LORAMAC_TX_PWR_2,
    LORAMAC_TX_PWR_3,
    LORAMAC_TX_PWR_4,
    LORAMAC_TX_PWR_5,
    LORAMAC_TX_PWR_6,
    LORAMAC_TX_PWR_7,
    LORAMAC_TX_PWR_8,
    LORAMAC_TX_PWR_9,
    LORAMAC_TX_PWR_10,
    LORAMAC_TX_PWR_11,
    LORAMAC_TX_PWR_12,
    LORAMAC_TX_PWR_13,
    LORAMAC_TX_PWR_14,
    LORAMAC_TX_PWR_15,
} loramac_tx_pwr_idx_t;
 typedef struct {
    uint32_t freq;                     
    uint8_t index;                     
    uint8_t bw;                        
    uint8_t dr_min;                    
    uint8_t dr_max;                    
    uint8_t dcycle;                    
} loramac_channel_t;
 
static inline uint32_t lora_time_on_air(size_t pkt_len, loramac_dr_idx_t dr, uint8_t cr)
{
    assert(dr <= LORAMAC_DR_6);
    const uint8_t _K[6][4] = {
        { 0, 1, 5, 5 }, /* DR0 */
        { 0, 1, 4, 5 }, /* DR1 */
        { 1, 5, 5, 5 }, /* DR2 */
        { 1, 4, 5, 4 }, /* DR3 */
        { 1, 3, 4, 4 }, /* DR4 */
        { 1, 2, 4, 3 }  /* DR5 */
        };
 
    uint32_t t_sym = 1 << (15 - dr);
    uint32_t t_preamble = (t_sym << 3) + (t_sym << 2) + (t_sym >> 2);
 
    uint8_t index = (dr < LORAMAC_DR_6) ? dr : LORAMAC_DR_5;
    uint8_t n0 = _K[index][0];
    uint32_t nb_symbols;
 
    uint8_t offset = _K[index][1];
 
    if (pkt_len < offset) {
        nb_symbols = 8 + n0 * (cr + 4);
    }
    else {
        uint8_t c1 = _K[index][2];
        uint8_t c2 = _K[index][3];
        uint8_t pos = (pkt_len - offset) % (c1 + c2);
        uint8_t cycle = (pkt_len - offset) / (c1 + c2);
        nb_symbols = 8 + (n0 + 2 * cycle + 1 + (pos > (c1 - 1))) * (cr + 4);
    }
 
    uint32_t t_payload = t_sym * nb_symbols;
 
    return t_preamble + t_payload;
}
 
#ifdef __cplusplus
}
#endif