lorawan_types.h

Go to the documentation of this file.

/**
 * @file lorawan_types.h
 *
 * @brief Contains data structures required by LoRaWANBase class.
 *
 *  \code
 *   ______                              _
 *  / _____)             _              | |
 * ( (____  _____ ____ _| |_ _____  ____| |__
 *  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
 *  _____) ) ____| | | || |_| ____( (___| | | |
 * (______/|_____)_|_|_| \__)_____)\____)_| |_|
 *   (C)2013 Semtech
 *  ___ _____ _   ___ _  _____ ___  ___  ___ ___
 * / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
 * \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
 * embedded.connectivity.solutions===============
 *
 * \endcode
 *
 *
 * License: Revised BSD License, see LICENSE.TXT file include in the project
 *
 * Maintainer: Miguel Luis ( Semtech ), Gregory Cristian ( Semtech ) and Daniel Jaeckle ( STACKFORCE )
 *
 * Copyright (c) 2017, Arm Limited and affiliates.
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */
 
#ifndef MBED_LORAWAN_TYPES_H_
#define MBED_LORAWAN_TYPES_H_
 
#include "platform/Callback.h"
 
/**
 * A mask for the network ID.
 */
#define LORAWAN_NETWORK_ID_MASK                     (uint32_t) 0xFE000000
 
/**
 * Option Flags for send(), receive() APIs
 *
 * Special Notes for UPLINK:
 *  i)  All of the flags are mutually exclusive.
 *  ii) MSG_MULTICAST_FLAG cannot be used.
 */
#define MSG_UNCONFIRMED_FLAG                  0x01
#define MSG_CONFIRMED_FLAG                    0x02
#define MSG_MULTICAST_FLAG                    0x04
#define MSG_PROPRIETARY_FLAG                  0x08
 
/**
 * LoRaWAN device classes definition.
 *
 * LoRaWAN Specification V1.0.2, chapter 2.1.
 */
typedef enum {
    /**
     * LoRaWAN device class A.
     *
     * LoRaWAN Specification V1.0.2, chapter 3.
     */
    CLASS_A,
    /**
     * LoRaWAN device class B.
     *
     * LoRaWAN Specification V1.0.2, chapter 8.
     */
    CLASS_B,
    /**
     * LoRaWAN device class C.
     *
     * LoRaWAN Specification V1.0.2, chapter 17.
     */
    CLASS_C,
} device_class_t;
 
/**
 * lorawan_status_t contains status codes in
 * response to stack operations
 */
typedef enum lorawan_status {
    LORAWAN_STATUS_OK = 0,                         /**< Service started successfully */
    LORAWAN_STATUS_BUSY = -1000,                   /**< Service not started - LoRaMAC is busy */
    LORAWAN_STATUS_WOULD_BLOCK = -1001,            /**< LoRaMAC cannot send at the moment or have nothing to read */
    LORAWAN_STATUS_SERVICE_UNKNOWN = -1002,        /**< Service unknown */
    LORAWAN_STATUS_PARAMETER_INVALID = -1003,      /**< Service not started - invalid parameter */
    LORAWAN_STATUS_FREQUENCY_INVALID = -1004,      /**< Service not started - invalid frequency */
    LORAWAN_STATUS_DATARATE_INVALID = -1005,       /**< Service not started - invalid datarate */
    LORAWAN_STATUS_FREQ_AND_DR_INVALID = -1006,    /**< Service not started - invalid frequency and datarate */
    LORAWAN_STATUS_NO_NETWORK_JOINED = -1009,      /**< Service not started - the device is not in a LoRaWAN */
    LORAWAN_STATUS_LENGTH_ERROR = -1010,           /**< Service not started - payload lenght error */
    LORAWAN_STATUS_DEVICE_OFF = -1011,             /**< Service not started - the device is switched off */
    LORAWAN_STATUS_NOT_INITIALIZED = -1012,        /**< Service not started - stack not initialized */
    LORAWAN_STATUS_UNSUPPORTED = -1013,            /**< Service not supported */
    LORAWAN_STATUS_CRYPTO_FAIL = -1014,            /**< Service not started - crypto failure */
    LORAWAN_STATUS_PORT_INVALID = -1015,           /**< Invalid port */
    LORAWAN_STATUS_CONNECT_IN_PROGRESS = -1016,    /**< Services started - Connection in progress */
    LORAWAN_STATUS_NO_ACTIVE_SESSIONS = -1017,     /**< Services not started - No active session */
    LORAWAN_STATUS_IDLE = -1018,                   /**< Services started - Idle at the moment */
    LORAWAN_STATUS_NO_OP = -1019,                  /**< Cannot perform requested operation */
    LORAWAN_STATUS_DUTYCYCLE_RESTRICTED = -1020,   /**< Transmission will continue after duty cycle backoff*/
    LORAWAN_STATUS_NO_CHANNEL_FOUND = -1021,       /**< None of the channels is enabled at the moment*/
    LORAWAN_STATUS_NO_FREE_CHANNEL_FOUND = -1022,  /**< None of the enabled channels is ready for another TX (duty cycle limited)*/
    LORAWAN_STATUS_METADATA_NOT_AVAILABLE = -1023, /**< Meta-data after an RX or TX is stale*/
    LORAWAN_STATUS_ALREADY_CONNECTED = -1024              /**< The device has already joined a network*/
} lorawan_status_t;
 
/** The lorawan_connect_otaa structure.
 *
 * A structure representing the LoRaWAN Over The Air Activation
 * parameters.
 */
typedef struct {
    /** End-device identifier
     *
     * LoRaWAN Specification V1.0.2, chapter 6.2.1
     */
    uint8_t *dev_eui;
    /** Application identifier
     *
     * LoRaWAN Specification V1.0.2, chapter 6.1.2
     */
    uint8_t *app_eui;
    /** AES-128 application key
     *
     * LoRaWAN Specification V1.0.2, chapter 6.2.2
     */
    uint8_t *app_key;
    /** Join request trials
     *
     * Number of trials for the join request.
     */
    uint8_t nb_trials;
} lorawan_connect_otaa_t;
 
/** The lorawan_connect_abp structure.
 *
 * A structure representing the LoRaWAN Activation By Personalization
 * parameters.
 */
typedef struct {
    /** Network identifier
     *
     * LoRaWAN Specification V1.0.2, chapter 6.1.1
     */
    uint32_t nwk_id;
    /** End-device address
     *
     * LoRaWAN Specification V1.0.2, chapter 6.1.1
     */
    uint32_t dev_addr;
    /** Network session key
     *
     * LoRaWAN Specification V1.0.2, chapter 6.1.3
     */
    uint8_t *nwk_skey;
    /** Application session key
     *
     * LoRaWAN Specification V1.0.2, chapter 6.1.4
     */
    uint8_t *app_skey;
} lorawan_connect_abp_t;
 
/** lorawan_connect_t structure
 *
 * A structure representing the parameters for different connections.
 */
typedef struct lorawan_connect {
    /**
     * Select the connection type, either LORAWAN_CONNECTION_OTAA
     * or LORAWAN_CONNECTION_ABP.
     */
    uint8_t connect_type;
 
    union {
        /**
         * Join the network using OTA
         */
        lorawan_connect_otaa_t otaa;
        /**
         * Authentication by personalization
         */
        lorawan_connect_abp_t abp;
    } connection_u;
 
} lorawan_connect_t;
 
/**
 * Events needed to announce stack operation results.
 *
 * CONNECTED            - When the connection is complete
 * DISCONNECTED         - When the protocol is shut down in response to disconnect()
 * TX_DONE              - When a packet is sent
 * TX_TIMEOUT,          - When stack was unable to send packet in TX window
 * TX_ERROR,            - A general TX error
 * CRYPTO_ERROR,        - A crypto error indicating wrong keys
 * TX_SCHEDULING_ERROR, - When stack is unable to schedule packet
 * RX_DONE,             - When there is something to receive
 * RX_TIMEOUT,          - Not yet mapped
 * RX_ERROR             - A general RX error
 * JOIN_FAILURE         - When all Joining retries are exhausted
 * UPLINK_REQUIRED      - Stack indicates application that some uplink needed
 * AUTOMATIC_UPLINK_ERROR - Stack tried automatically send uplink but some error occurred.
 *                          Application should initiate uplink as soon as possible.
 *
 */
typedef enum lora_events {
    CONNECTED = 0,
    DISCONNECTED,
    TX_DONE,
    TX_TIMEOUT,
    TX_ERROR,
    CRYPTO_ERROR,
    TX_CRYPTO_ERROR = CRYPTO_ERROR, //keeping this for backward compatibility
    TX_SCHEDULING_ERROR,
    RX_DONE,
    RX_TIMEOUT,
    RX_ERROR,
    JOIN_FAILURE,
    UPLINK_REQUIRED,
    AUTOMATIC_UPLINK_ERROR,
} lorawan_event_t;
 
/**
 * Stack level callback functions
 *
 * 'lorawan_app_callbacks_t' is a structure that holds pointers to the application
 * provided methods which are needed to be called in response to certain
 * requests. The structure is default constructed to set all pointers to NULL.
 * So if the user does not provide the pointer, a response will not be posted.
 * However, the 'lorawan_events' callback is mandatory to be provided as it
 * contains essential events.
 *
 * A link check request could be sent whenever the device tries to send a
 * message and if the network server responds with a link check response,
 * the stack notifies the application be calling the appropriate method set using
 * 'link_check_resp' callback. The result is thus transported to the application
 * via callback function provided.
 *
 * 'battery_level' callback goes in the down direction, i.e., it informs
 * the stack about the battery level by calling a function provided
 * by the upper layers.
 */
typedef struct {
    /**
     * Mandatory. Event Callback must be provided
     */
    mbed::Callback<void(lorawan_event_t)> events;
 
    /**
     * This callback is optional
     *
     * The first parameter to the callback function is the demodulation margin, and the second
     * parameter is the number of gateways that successfully received the last request.
     */
    mbed::Callback<void(uint8_t, uint8_t)> link_check_resp;
 
    /**
     * This callback is optional. If the callback is not set, the stack returns 255 to gateway.
     *
     * Battery level return value must follow the specification
     * for DevStatusAns MAC command:
     *
     *     0       The end-device is connected to an external power source
     *     1 - 254 The battery level, 1 being at minimum and 254 being at maximum
     *     255     The end-device was not able to measure the battery level.
     */
    mbed::Callback<uint8_t(void)> battery_level;
} lorawan_app_callbacks_t;
 
/**
 * DO NOT MODIFY, WILL BREAK THE API!
 *
 * Structure containing a given data rate range.
 */
typedef union {
    /**
     * Byte-access to the bits.
     */
    uint8_t value;
    /**
     * The structure to store the minimum and the maximum datarate.
     */
    struct fields_s {
        /**
         * The minimum data rate.
         *
         * LoRaWAN Regional Parameters V1.0.2rB.
         *
         * The allowed ranges are region-specific.
         * Please refer to \ref DR_0 to \ref DR_15 for details.
         */
        uint8_t min : 4;
        /**
         * The maximum data rate.
         *
         * LoRaWAN Regional Parameters V1.0.2rB.
         *
         * The allowed ranges are region-specific.
         * Please refer to \ref DR_0 to \ref DR_15 for details.
         */
        uint8_t max : 4;
    } fields;
} dr_range_t;
 
/**
 * DO NOT MODIFY, WILL BREAK THE API!
 *
 * LoRaMAC channel definition.
 */
typedef struct {
    /**
     * The frequency in Hz.
     */
    uint32_t frequency;
    /**
     * The alternative frequency for RX window 1.
     */
    uint32_t rx1_frequency;
    /**
     * The data rate definition.
     */
    dr_range_t dr_range;
    /**
     * The band index.
     */
    uint8_t band;
} channel_params_t;
 
/**
 * DO NOT MODIFY, WILL BREAK THE API!
 *
 * Structure to hold parameters for a LoRa channel.
 */
typedef struct lora_channels_s {
    uint8_t id;
    channel_params_t ch_param;
} loramac_channel_t;
 
/**
 * DO NOT MODIFY, WILL BREAK THE API!
 *
 * This data structures contains LoRaWAN channel plan, i.e., a pointer to a
 * list of channels and the total number of channels included in the plan.
 */
typedef struct lora_channelplan {
    uint8_t nb_channels;    // number of channels
    loramac_channel_t *channels;
} lorawan_channelplan_t;
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF12 - BW125
 * AU915        | SF10 - BW125
 * CN470        | SF12 - BW125
 * CN779        | SF12 - BW125
 * EU433        | SF12 - BW125
 * EU868        | SF12 - BW125
 * IN865        | SF12 - BW125
 * KR920        | SF12 - BW125
 * US915        | SF10 - BW125
 * US915_HYBRID | SF10 - BW125
 */
#define DR_0                                        0
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF11 - BW125
 * AU915        | SF9  - BW125
 * CN470        | SF11 - BW125
 * CN779        | SF11 - BW125
 * EU433        | SF11 - BW125
 * EU868        | SF11 - BW125
 * IN865        | SF11 - BW125
 * KR920        | SF11 - BW125
 * US915        | SF9  - BW125
 * US915_HYBRID | SF9  - BW125
 */
#define DR_1                                        1
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF10 - BW125
 * AU915        | SF8  - BW125
 * CN470        | SF10 - BW125
 * CN779        | SF10 - BW125
 * EU433        | SF10 - BW125
 * EU868        | SF10 - BW125
 * IN865        | SF10 - BW125
 * KR920        | SF10 - BW125
 * US915        | SF8  - BW125
 * US915_HYBRID | SF8  - BW125
 */
#define DR_2                                        2
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF9  - BW125
 * AU915        | SF7  - BW125
 * CN470        | SF9  - BW125
 * CN779        | SF9  - BW125
 * EU433        | SF9  - BW125
 * EU868        | SF9  - BW125
 * IN865        | SF9  - BW125
 * KR920        | SF9  - BW125
 * US915        | SF7  - BW125
 * US915_HYBRID | SF7  - BW125
 */
#define DR_3                                        3
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF8  - BW125
 * AU915        | SF8  - BW500
 * CN470        | SF8  - BW125
 * CN779        | SF8  - BW125
 * EU433        | SF8  - BW125
 * EU868        | SF8  - BW125
 * IN865        | SF8  - BW125
 * KR920        | SF8  - BW125
 * US915        | SF8  - BW500
 * US915_HYBRID | SF8  - BW500
 */
#define DR_4                                        4
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF7  - BW125
 * AU915        | RFU
 * CN470        | SF7  - BW125
 * CN779        | SF7  - BW125
 * EU433        | SF7  - BW125
 * EU868        | SF7  - BW125
 * IN865        | SF7  - BW125
 * KR920        | SF7  - BW125
 * US915        | RFU
 * US915_HYBRID | RFU
 */
#define DR_5                                        5
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | SF7  - BW250
 * AU915        | RFU
 * CN470        | SF12 - BW125
 * CN779        | SF7  - BW250
 * EU433        | SF7  - BW250
 * EU868        | SF7  - BW250
 * IN865        | SF7  - BW250
 * KR920        | RFU
 * US915        | RFU
 * US915_HYBRID | RFU
 */
#define DR_6                                        6
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | FSK
 * AU915        | RFU
 * CN470        | SF12 - BW125
 * CN779        | FSK
 * EU433        | FSK
 * EU868        | FSK
 * IN865        | FSK
 * KR920        | RFU
 * US915        | RFU
 * US915_HYBRID | RFU
 */
#define DR_7                                        7
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF12 - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF12 - BW500
 * US915_HYBRID | SF12 - BW500
 */
#define DR_8                                        8
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF11 - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF11 - BW500
 * US915_HYBRID | SF11 - BW500
 */
#define DR_9                                        9
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF10 - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF10 - BW500
 * US915_HYBRID | SF10 - BW500
 */
#define DR_10                                       10
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF9  - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF9  - BW500
 * US915_HYBRID | SF9  - BW500
 */
#define DR_11                                       11
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF8  - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF8  - BW500
 * US915_HYBRID | SF8  - BW500
 */
#define DR_12                                       12
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | SF7  - BW500
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | SF7  - BW500
 * US915_HYBRID | SF7  - BW500
 */
#define DR_13                                       13
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | RFU
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | RFU
 * US915_HYBRID | RFU
 */
#define DR_14                                       14
 
/*!
 * Region       | SF
 * ------------ | :-----:
 * AS923        | RFU
 * AU915        | RFU
 * CN470        | RFU
 * CN779        | RFU
 * EU433        | RFU
 * EU868        | RFU
 * IN865        | RFU
 * KR920        | RFU
 * US915        | RFU
 * US915_HYBRID | RFU
 */
#define DR_15                                       15
 
/**
 * Enumeration for LoRaWAN connection type.
 */
typedef enum lorawan_connect_type {
    LORAWAN_CONNECTION_OTAA = 0,    /**< Over The Air Activation */
    LORAWAN_CONNECTION_ABP          /**< Activation By Personalization */
} lorawan_connect_type_t;
 
 
/**
 * Meta-data collection for a transmission
 */
typedef struct {
    /**
     * The transmission time on air of the frame.
     */
    uint32_t tx_toa;
    /**
     * The uplink channel used for transmission.
     */
    uint32_t channel;
    /**
     * The transmission power.
     */
    int8_t tx_power;
    /**
     * The uplink datarate.
     */
    uint8_t data_rate;
    /**
     * Provides the number of retransmissions.
     */
    uint8_t nb_retries;
    /**
     * A boolean to mark if the meta data is stale
     */
    bool stale;
} lorawan_tx_metadata;
 
/**
 * Meta-data collection for the received packet
 */
typedef struct {
    /**
     * The RSSI for the received packet.
     */
    int16_t rssi;
    /**
     * Data rate of reception
     */
    uint8_t rx_datarate;
    /**
     * The SNR for the received packet.
     */
    int8_t snr;
    /**
     * A boolean to mark if the meta data is stale
     */
    bool stale;
    /**
     * Frequency for the downlink channel
     */
    uint32_t channel;
    /**
     * Time spent on air by the RX frame
     */
    uint32_t rx_toa;
} lorawan_rx_metadata;
 
#endif /* MBED_LORAWAN_TYPES_H_ */