Damian Gabino / picoGW_hal

Host driver/HAL to build a LoRa Picocell Gateway which communicates through USB with a concentrator board based on Semtech SX1308 multi-channel modem and SX1257/SX1255 RF transceivers.

libloragw/inc/loragw_hal.h@0:102b50f941d0, 2018-04-11 (annotated)

Committer:
dgabino
Date:
Wed Apr 11 14:38:42 2018 +0000
Revision:
0:102b50f941d0
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dgabino 0:102b50f941d0 1 /*
dgabino 0:102b50f941d0 2 / _____) _ | |
dgabino 0:102b50f941d0 3 ( (____ _____ ____ _| |_ _____ ____| |__
dgabino 0:102b50f941d0 4 \____ \| ___ | (_ _) ___ |/ ___) _ \
dgabino 0:102b50f941d0 5 _____) ) ____| | | || |_| ____( (___| | | |
dgabino 0:102b50f941d0 6 (______/|_____)_|_|_| \__)_____)\____)_| |_|
dgabino 0:102b50f941d0 7 (C)2017 Semtech-Cycleo
dgabino 0:102b50f941d0 8
dgabino 0:102b50f941d0 9 Description:
dgabino 0:102b50f941d0 10 LoRa concentrator Hardware Abstraction Layer
dgabino 0:102b50f941d0 11
dgabino 0:102b50f941d0 12 License: Revised BSD License, see LICENSE.TXT file include in the project
dgabino 0:102b50f941d0 13
dgabino 0:102b50f941d0 14 */
dgabino 0:102b50f941d0 15
dgabino 0:102b50f941d0 16
dgabino 0:102b50f941d0 17 #ifndef _LORAGW_HAL_H
dgabino 0:102b50f941d0 18 #define _LORAGW_HAL_H
dgabino 0:102b50f941d0 19
dgabino 0:102b50f941d0 20 /* -------------------------------------------------------------------------- */
dgabino 0:102b50f941d0 21 /* --- DEPENDANCIES --------------------------------------------------------- */
dgabino 0:102b50f941d0 22
dgabino 0:102b50f941d0 23 #include <stdint.h> /* C99 types */
dgabino 0:102b50f941d0 24 #include <stdbool.h> /* bool type */
dgabino 0:102b50f941d0 25
dgabino 0:102b50f941d0 26 #include "config.h" /* library configuration options (dynamically generated) */
dgabino 0:102b50f941d0 27
dgabino 0:102b50f941d0 28 /* -------------------------------------------------------------------------- */
dgabino 0:102b50f941d0 29 /* --- PUBLIC MACROS -------------------------------------------------------- */
dgabino 0:102b50f941d0 30
dgabino 0:102b50f941d0 31 #define IS_LORA_BW(bw) ((bw == BW_125KHZ) || (bw == BW_250KHZ) || (bw == BW_500KHZ))
dgabino 0:102b50f941d0 32 #define IS_LORA_STD_DR(dr) ((dr == DR_LORA_SF7) || (dr == DR_LORA_SF8) || (dr == DR_LORA_SF9) || (dr == DR_LORA_SF10) || (dr == DR_LORA_SF11) || (dr == DR_LORA_SF12))
dgabino 0:102b50f941d0 33 #define IS_LORA_MULTI_DR(dr) ((dr & ~DR_LORA_MULTI) == 0) /* ones outside of DR_LORA_MULTI bitmask -> not a combination of LoRa datarates */
dgabino 0:102b50f941d0 34 #define IS_LORA_CR(cr) ((cr == CR_LORA_4_5) || (cr == CR_LORA_4_6) || (cr == CR_LORA_4_7) || (cr == CR_LORA_4_8))
dgabino 0:102b50f941d0 35
dgabino 0:102b50f941d0 36 #define IS_FSK_BW(bw) ((bw >= 1) && (bw <= 7))
dgabino 0:102b50f941d0 37 #define IS_FSK_DR(dr) ((dr >= DR_FSK_MIN) && (dr <= DR_FSK_MAX))
dgabino 0:102b50f941d0 38
dgabino 0:102b50f941d0 39 #define IS_TX_MODE(mode) ((mode == IMMEDIATE) || (mode == TIMESTAMPED) || (mode == ON_GPS))
dgabino 0:102b50f941d0 40
dgabino 0:102b50f941d0 41 /* -------------------------------------------------------------------------- */
dgabino 0:102b50f941d0 42 /* --- PUBLIC CONSTANTS ----------------------------------------------------- */
dgabino 0:102b50f941d0 43
dgabino 0:102b50f941d0 44 /* return status code */
dgabino 0:102b50f941d0 45 #define LGW_HAL_SUCCESS 0
dgabino 0:102b50f941d0 46 #define LGW_HAL_ERROR -1
dgabino 0:102b50f941d0 47
dgabino 0:102b50f941d0 48 /* radio-specific parameters */
dgabino 0:102b50f941d0 49 #define LGW_XTAL_FREQU 32000000 /* frequency of the RF reference oscillator */
dgabino 0:102b50f941d0 50 #define LGW_RF_CHAIN_NB 2 /* number of RF chains */
dgabino 0:102b50f941d0 51 #define LGW_RF_RX_BANDWIDTH {1000000, 1000000} /* bandwidth of the radios */
dgabino 0:102b50f941d0 52
dgabino 0:102b50f941d0 53 /* type of if_chain + modem */
dgabino 0:102b50f941d0 54 #define IF_UNDEFINED 0
dgabino 0:102b50f941d0 55 #define IF_LORA_STD 0x10 /* if + standard single-SF LoRa modem */
dgabino 0:102b50f941d0 56 #define IF_LORA_MULTI 0x11 /* if + LoRa receiver with multi-SF capability */
dgabino 0:102b50f941d0 57 #define IF_FSK_STD 0x20 /* if + standard FSK modem */
dgabino 0:102b50f941d0 58
dgabino 0:102b50f941d0 59 /* concentrator chipset-specific parameters */
dgabino 0:102b50f941d0 60 /* to use array parameters, declare a local const and use 'if_chain' as index */
dgabino 0:102b50f941d0 61 #define LGW_IF_CHAIN_NB 10 /* number of IF+modem RX chains */
dgabino 0:102b50f941d0 62 #define LGW_PKT_FIFO_SIZE 16 /* depth of the RX packet FIFO */
dgabino 0:102b50f941d0 63 #define LGW_DATABUFF_SIZE 1024 /* size in bytes of the RX data buffer (contains payload & metadata) */
dgabino 0:102b50f941d0 64 #define LGW_REF_BW 125000 /* typical bandwidth of data channel */
dgabino 0:102b50f941d0 65 #define LGW_MULTI_NB 8 /* number of LoRa 'multi SF' chains */
dgabino 0:102b50f941d0 66 #define LGW_IFMODEM_CONFIG {\
dgabino 0:102b50f941d0 67 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 68 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 69 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 70 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 71 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 72 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 73 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 74 IF_LORA_MULTI, \
dgabino 0:102b50f941d0 75 IF_LORA_STD, \
dgabino 0:102b50f941d0 76 IF_FSK_STD } /* configuration of available IF chains and modems on the hardware */
dgabino 0:102b50f941d0 77
dgabino 0:102b50f941d0 78 /* values available for the 'modulation' parameters */
dgabino 0:102b50f941d0 79 /* NOTE: arbitrary values */
dgabino 0:102b50f941d0 80 #define MOD_UNDEFINED 0
dgabino 0:102b50f941d0 81 #define MOD_LORA 0x10
dgabino 0:102b50f941d0 82 #define MOD_FSK 0x20
dgabino 0:102b50f941d0 83
dgabino 0:102b50f941d0 84 /* values available for the 'bandwidth' parameters (LoRa & FSK) */
dgabino 0:102b50f941d0 85 /* NOTE: directly encode FSK RX bandwidth, do not change */
dgabino 0:102b50f941d0 86 #define BW_UNDEFINED 0
dgabino 0:102b50f941d0 87 #define BW_500KHZ 0x01
dgabino 0:102b50f941d0 88 #define BW_250KHZ 0x02
dgabino 0:102b50f941d0 89 #define BW_125KHZ 0x03
dgabino 0:102b50f941d0 90 #define BW_62K5HZ 0x04
dgabino 0:102b50f941d0 91 #define BW_31K2HZ 0x05
dgabino 0:102b50f941d0 92 #define BW_15K6HZ 0x06
dgabino 0:102b50f941d0 93 #define BW_7K8HZ 0x07
dgabino 0:102b50f941d0 94
dgabino 0:102b50f941d0 95 /* values available for the 'datarate' parameters */
dgabino 0:102b50f941d0 96 /* NOTE: LoRa values used directly to code SF bitmask in 'multi' modem, do not change */
dgabino 0:102b50f941d0 97 #define DR_UNDEFINED 0
dgabino 0:102b50f941d0 98 #define DR_LORA_SF7 0x02
dgabino 0:102b50f941d0 99 #define DR_LORA_SF8 0x04
dgabino 0:102b50f941d0 100 #define DR_LORA_SF9 0x08
dgabino 0:102b50f941d0 101 #define DR_LORA_SF10 0x10
dgabino 0:102b50f941d0 102 #define DR_LORA_SF11 0x20
dgabino 0:102b50f941d0 103 #define DR_LORA_SF12 0x40
dgabino 0:102b50f941d0 104 #define DR_LORA_MULTI 0x7E
dgabino 0:102b50f941d0 105 /* NOTE: for FSK directly use baudrate between 500 bauds and 250 kbauds */
dgabino 0:102b50f941d0 106 #define DR_FSK_MIN 500
dgabino 0:102b50f941d0 107 #define DR_FSK_MAX 250000
dgabino 0:102b50f941d0 108
dgabino 0:102b50f941d0 109 /* values available for the 'coderate' parameters (LoRa only) */
dgabino 0:102b50f941d0 110 /* NOTE: arbitrary values */
dgabino 0:102b50f941d0 111 #define CR_UNDEFINED 0
dgabino 0:102b50f941d0 112 #define CR_LORA_4_5 0x01
dgabino 0:102b50f941d0 113 #define CR_LORA_4_6 0x02
dgabino 0:102b50f941d0 114 #define CR_LORA_4_7 0x03
dgabino 0:102b50f941d0 115 #define CR_LORA_4_8 0x04
dgabino 0:102b50f941d0 116
dgabino 0:102b50f941d0 117 /* values available for the 'status' parameter */
dgabino 0:102b50f941d0 118 /* NOTE: values according to hardware specification */
dgabino 0:102b50f941d0 119 #define STAT_UNDEFINED 0x00
dgabino 0:102b50f941d0 120 #define STAT_NO_CRC 0x01
dgabino 0:102b50f941d0 121 #define STAT_CRC_BAD 0x11
dgabino 0:102b50f941d0 122 #define STAT_CRC_OK 0x10
dgabino 0:102b50f941d0 123
dgabino 0:102b50f941d0 124 /* values available for the 'tx_mode' parameter */
dgabino 0:102b50f941d0 125 #define IMMEDIATE 0
dgabino 0:102b50f941d0 126 #define TIMESTAMPED 1
dgabino 0:102b50f941d0 127 #define ON_GPS 2
dgabino 0:102b50f941d0 128 //#define ON_EVENT 3
dgabino 0:102b50f941d0 129 //#define GPS_DELAYED 4
dgabino 0:102b50f941d0 130 //#define EVENT_DELAYED 5
dgabino 0:102b50f941d0 131
dgabino 0:102b50f941d0 132 /* values available for 'select' in the status function */
dgabino 0:102b50f941d0 133 #define TX_STATUS 1
dgabino 0:102b50f941d0 134 #define RX_STATUS 2
dgabino 0:102b50f941d0 135
dgabino 0:102b50f941d0 136 /* status code for TX_STATUS */
dgabino 0:102b50f941d0 137 /* NOTE: arbitrary values */
dgabino 0:102b50f941d0 138 #define TX_STATUS_UNKNOWN 0
dgabino 0:102b50f941d0 139 #define TX_OFF 1 /* TX modem disabled, it will ignore commands */
dgabino 0:102b50f941d0 140 #define TX_FREE 2 /* TX modem is free, ready to receive a command */
dgabino 0:102b50f941d0 141 #define TX_SCHEDULED 3 /* TX modem is loaded, ready to send the packet after an event and/or delay */
dgabino 0:102b50f941d0 142 #define TX_EMITTING 4 /* TX modem is emitting */
dgabino 0:102b50f941d0 143
dgabino 0:102b50f941d0 144 /* status code for RX_STATUS */
dgabino 0:102b50f941d0 145 /* NOTE: arbitrary values */
dgabino 0:102b50f941d0 146 #define RX_STATUS_UNKNOWN 0
dgabino 0:102b50f941d0 147 #define RX_OFF 1 /* RX modem is disabled, it will ignore commands */
dgabino 0:102b50f941d0 148 #define RX_ON 2 /* RX modem is receiving */
dgabino 0:102b50f941d0 149 #define RX_SUSPENDED 3 /* RX is suspended while a TX is ongoing */
dgabino 0:102b50f941d0 150
dgabino 0:102b50f941d0 151 /* Maximum size of Tx gain LUT */
dgabino 0:102b50f941d0 152 #define TX_GAIN_LUT_SIZE_MAX 16
dgabino 0:102b50f941d0 153
dgabino 0:102b50f941d0 154 /* -------------------------------------------------------------------------- */
dgabino 0:102b50f941d0 155 /* --- PUBLIC TYPES --------------------------------------------------------- */
dgabino 0:102b50f941d0 156
dgabino 0:102b50f941d0 157 /**
dgabino 0:102b50f941d0 158 @enum lgw_radio_type_e
dgabino 0:102b50f941d0 159 @brief Radio types that can be found on the LoRa Gateway
dgabino 0:102b50f941d0 160 */
dgabino 0:102b50f941d0 161 enum lgw_radio_type_e {
dgabino 0:102b50f941d0 162 LGW_RADIO_TYPE_NONE,
dgabino 0:102b50f941d0 163 LGW_RADIO_TYPE_SX1255,
dgabino 0:102b50f941d0 164 LGW_RADIO_TYPE_SX1257,
dgabino 0:102b50f941d0 165 LGW_RADIO_TYPE_SX1272,
dgabino 0:102b50f941d0 166 LGW_RADIO_TYPE_SX1276
dgabino 0:102b50f941d0 167 };
dgabino 0:102b50f941d0 168
dgabino 0:102b50f941d0 169 /**
dgabino 0:102b50f941d0 170 @struct lgw_conf_board_s
dgabino 0:102b50f941d0 171 @brief Configuration structure for board specificities
dgabino 0:102b50f941d0 172 */
dgabino 0:102b50f941d0 173 struct lgw_conf_board_s {
dgabino 0:102b50f941d0 174 bool lorawan_public; /*!> Enable ONLY for *public* networks using the LoRa MAC protocol */
dgabino 0:102b50f941d0 175 uint8_t clksrc; /*!> Index of RF chain which provides clock to concentrator */
dgabino 0:102b50f941d0 176 };
dgabino 0:102b50f941d0 177
dgabino 0:102b50f941d0 178 /**
dgabino 0:102b50f941d0 179 @struct lgw_conf_rxrf_s
dgabino 0:102b50f941d0 180 @brief Configuration structure for a RF chain
dgabino 0:102b50f941d0 181 */
dgabino 0:102b50f941d0 182 struct lgw_conf_rxrf_s {
dgabino 0:102b50f941d0 183 bool enable; /*!> enable or disable that RF chain */
dgabino 0:102b50f941d0 184 uint32_t freq_hz; /*!> center frequency of the radio in Hz */
dgabino 0:102b50f941d0 185 float rssi_offset; /*!> Board-specific RSSI correction factor */
dgabino 0:102b50f941d0 186 enum lgw_radio_type_e type; /*!> Radio type for that RF chain (SX1255, SX1257....) */
dgabino 0:102b50f941d0 187 bool tx_enable; /*!> enable or disable TX on that RF chain */
dgabino 0:102b50f941d0 188 };
dgabino 0:102b50f941d0 189
dgabino 0:102b50f941d0 190 /**
dgabino 0:102b50f941d0 191 @struct lgw_conf_rxif_s
dgabino 0:102b50f941d0 192 @brief Configuration structure for an IF chain
dgabino 0:102b50f941d0 193 */
dgabino 0:102b50f941d0 194 struct lgw_conf_rxif_s {
dgabino 0:102b50f941d0 195 bool enable; /*!> enable or disable that IF chain */
dgabino 0:102b50f941d0 196 uint8_t rf_chain; /*!> to which RF chain is that IF chain associated */
dgabino 0:102b50f941d0 197 int32_t freq_hz; /*!> center frequ of the IF chain, relative to RF chain frequency */
dgabino 0:102b50f941d0 198 uint8_t bandwidth; /*!> RX bandwidth, 0 for default */
dgabino 0:102b50f941d0 199 uint32_t datarate; /*!> RX datarate, 0 for default */
dgabino 0:102b50f941d0 200 uint8_t sync_word_size; /*!> size of FSK sync word (number of bytes, 0 for default) */
dgabino 0:102b50f941d0 201 uint64_t sync_word; /*!> FSK sync word (ALIGN RIGHT, eg. 0xC194C1) */
dgabino 0:102b50f941d0 202 };
dgabino 0:102b50f941d0 203
dgabino 0:102b50f941d0 204 /**
dgabino 0:102b50f941d0 205 @struct lgw_pkt_rx_s
dgabino 0:102b50f941d0 206 @brief Structure containing the metadata of a packet that was received and a pointer to the payload
dgabino 0:102b50f941d0 207 */
dgabino 0:102b50f941d0 208 struct lgw_pkt_rx_s {
dgabino 0:102b50f941d0 209 uint32_t freq_hz; /*!> central frequency of the IF chain */
dgabino 0:102b50f941d0 210 uint8_t if_chain; /*!> by which IF chain was packet received */
dgabino 0:102b50f941d0 211 uint8_t status; /*!> status of the received packet */
dgabino 0:102b50f941d0 212 uint32_t count_us; /*!> internal concentrator counter for timestamping, 1 microsecond resolution */
dgabino 0:102b50f941d0 213 uint8_t rf_chain; /*!> through which RF chain the packet was received */
dgabino 0:102b50f941d0 214 uint8_t modulation; /*!> modulation used by the packet */
dgabino 0:102b50f941d0 215 uint8_t bandwidth; /*!> modulation bandwidth (LoRa only) */
dgabino 0:102b50f941d0 216 uint32_t datarate; /*!> RX datarate of the packet (SF for LoRa) */
dgabino 0:102b50f941d0 217 uint8_t coderate; /*!> error-correcting code of the packet (LoRa only) */
dgabino 0:102b50f941d0 218 float rssi; /*!> average packet RSSI in dB */
dgabino 0:102b50f941d0 219 float snr; /*!> average packet SNR, in dB (LoRa only) */
dgabino 0:102b50f941d0 220 float snr_min; /*!> minimum packet SNR, in dB (LoRa only) */
dgabino 0:102b50f941d0 221 float snr_max; /*!> maximum packet SNR, in dB (LoRa only) */
dgabino 0:102b50f941d0 222 uint16_t crc; /*!> CRC that was received in the payload */
dgabino 0:102b50f941d0 223 uint16_t size; /*!> payload size in bytes */
dgabino 0:102b50f941d0 224 uint8_t payload[256]; /*!> buffer containing the payload */
dgabino 0:102b50f941d0 225 };
dgabino 0:102b50f941d0 226 #define LGW_PKT_RX_METADATA_SIZE_ALIGNED 44
dgabino 0:102b50f941d0 227 /* ---------- WARNING -------------
dgabino 0:102b50f941d0 228 This metadata size is used to convert the byte array received from the MCU to a
dgabino 0:102b50f941d0 229 lgw_pkt_rx_s structure. Structure members are 64-bits aligned in the byte array.
dgabino 0:102b50f941d0 230 Any modification of this structure has to be done with caution!
dgabino 0:102b50f941d0 231 --------------WARNING ------------- */
dgabino 0:102b50f941d0 232 #define LGW_PKT_RX_STRUCT_SIZE_ALIGNED (256 + LGW_PKT_RX_METADATA_SIZE_ALIGNED)
dgabino 0:102b50f941d0 233
dgabino 0:102b50f941d0 234 /**
dgabino 0:102b50f941d0 235 @struct lgw_pkt_tx_s
dgabino 0:102b50f941d0 236 @brief Structure containing the configuration of a packet to send and a pointer to the payload
dgabino 0:102b50f941d0 237 */
dgabino 0:102b50f941d0 238 struct lgw_pkt_tx_s {
dgabino 0:102b50f941d0 239 uint32_t freq_hz; /*!> center frequency of TX */
dgabino 0:102b50f941d0 240 uint8_t tx_mode; /*!> select on what event/time the TX is triggered */
dgabino 0:102b50f941d0 241 uint32_t count_us; /*!> timestamp or delay in microseconds for TX trigger */
dgabino 0:102b50f941d0 242 uint8_t rf_chain; /*!> through which RF chain will the packet be sent */
dgabino 0:102b50f941d0 243 int8_t rf_power; /*!> TX power, in dBm */
dgabino 0:102b50f941d0 244 uint8_t modulation; /*!> modulation to use for the packet */
dgabino 0:102b50f941d0 245 uint8_t bandwidth; /*!> modulation bandwidth (LoRa only) */
dgabino 0:102b50f941d0 246 uint32_t datarate; /*!> TX datarate (baudrate for FSK, SF for LoRa) */
dgabino 0:102b50f941d0 247 uint8_t coderate; /*!> error-correcting code of the packet (LoRa only) */
dgabino 0:102b50f941d0 248 bool invert_pol; /*!> invert signal polarity, for orthogonal downlinks (LoRa only) */
dgabino 0:102b50f941d0 249 uint8_t f_dev; /*!> frequency deviation, in kHz (FSK only) */
dgabino 0:102b50f941d0 250 uint16_t preamble; /*!> set the preamble length, 0 for default */
dgabino 0:102b50f941d0 251 bool no_crc; /*!> if true, do not send a CRC in the packet */
dgabino 0:102b50f941d0 252 bool no_header; /*!> if true, enable implicit header mode (LoRa), fixed length (FSK) */
dgabino 0:102b50f941d0 253 uint16_t size; /*!> payload size in bytes */
dgabino 0:102b50f941d0 254 uint8_t payload[256]; /*!> buffer containing the payload */
dgabino 0:102b50f941d0 255 };
dgabino 0:102b50f941d0 256 #define LGW_PKT_TX_METADATA_SIZE_ALIGNED 30
dgabino 0:102b50f941d0 257 /* ---------- WARNING -------------
dgabino 0:102b50f941d0 258 This metadata size is used to convert a lgw_pkt_tx_s structure to the byte array
dgabino 0:102b50f941d0 259 sent to the MCU to. The structure members are 64-bits aligned in the byte array.
dgabino 0:102b50f941d0 260 Any modification of this structure has to be done with caution!
dgabino 0:102b50f941d0 261 --------------WARNING ------------- */
dgabino 0:102b50f941d0 262 #define LGW_PKT_TX_STRUCT_SIZE_ALIGNED (256 + LGW_PKT_TX_METADATA_SIZE_ALIGNED)
dgabino 0:102b50f941d0 263
dgabino 0:102b50f941d0 264 /**
dgabino 0:102b50f941d0 265 @struct lgw_tx_gain_s
dgabino 0:102b50f941d0 266 @brief Structure containing all gains of Tx chain
dgabino 0:102b50f941d0 267 */
dgabino 0:102b50f941d0 268 struct lgw_tx_gain_s {
dgabino 0:102b50f941d0 269 uint8_t dig_gain; /*!> 2 bits, control of the digital gain of SX1301 */
dgabino 0:102b50f941d0 270 uint8_t pa_gain; /*!> 2 bits, control of the external PA (SX1301 I/O) */
dgabino 0:102b50f941d0 271 uint8_t dac_gain; /*!> 2 bits, control of the radio DAC */
dgabino 0:102b50f941d0 272 uint8_t mix_gain; /*!> 4 bits, control of the radio mixer */
dgabino 0:102b50f941d0 273 int8_t rf_power; /*!> measured TX power at the board connector, in dBm */
dgabino 0:102b50f941d0 274 };
dgabino 0:102b50f941d0 275
dgabino 0:102b50f941d0 276 /**
dgabino 0:102b50f941d0 277 @struct lgw_tx_gain_lut_s
dgabino 0:102b50f941d0 278 @brief Structure defining the Tx gain LUT
dgabino 0:102b50f941d0 279 */
dgabino 0:102b50f941d0 280 struct lgw_tx_gain_lut_s {
dgabino 0:102b50f941d0 281 struct lgw_tx_gain_s lut[TX_GAIN_LUT_SIZE_MAX]; /*!> Array of Tx gain struct */
dgabino 0:102b50f941d0 282 uint8_t size; /*!> Number of LUT indexes */
dgabino 0:102b50f941d0 283 };
dgabino 0:102b50f941d0 284
dgabino 0:102b50f941d0 285 /* -------------------------------------------------------------------------- */
dgabino 0:102b50f941d0 286 /* --- PUBLIC FUNCTIONS PROTOTYPES ------------------------------------------ */
dgabino 0:102b50f941d0 287
dgabino 0:102b50f941d0 288 /**
dgabino 0:102b50f941d0 289 @brief Configure the gateway board
dgabino 0:102b50f941d0 290 @param conf structure containing the configuration parameters
dgabino 0:102b50f941d0 291 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 292 */
dgabino 0:102b50f941d0 293 int lgw_board_setconf(struct lgw_conf_board_s conf);
dgabino 0:102b50f941d0 294
dgabino 0:102b50f941d0 295 /**
dgabino 0:102b50f941d0 296 @brief Configure an RF chain (must configure before start)
dgabino 0:102b50f941d0 297 @param rf_chain number of the RF chain to configure [0, LGW_RF_CHAIN_NB - 1]
dgabino 0:102b50f941d0 298 @param conf structure containing the configuration parameters
dgabino 0:102b50f941d0 299 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 300 */
dgabino 0:102b50f941d0 301 int lgw_rxrf_setconf(uint8_t rf_chain, struct lgw_conf_rxrf_s conf);
dgabino 0:102b50f941d0 302
dgabino 0:102b50f941d0 303 /**
dgabino 0:102b50f941d0 304 @brief Configure an IF chain + modem (must configure before start)
dgabino 0:102b50f941d0 305 @param if_chain number of the IF chain + modem to configure [0, LGW_IF_CHAIN_NB - 1]
dgabino 0:102b50f941d0 306 @param conf structure containing the configuration parameters
dgabino 0:102b50f941d0 307 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 308 */
dgabino 0:102b50f941d0 309 int lgw_rxif_setconf(uint8_t if_chain, struct lgw_conf_rxif_s conf);
dgabino 0:102b50f941d0 310
dgabino 0:102b50f941d0 311 /**
dgabino 0:102b50f941d0 312 @brief Configure the Tx gain LUT
dgabino 0:102b50f941d0 313 @param pointer to structure defining the LUT
dgabino 0:102b50f941d0 314 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 315 */
dgabino 0:102b50f941d0 316 int lgw_txgain_setconf(struct lgw_tx_gain_lut_s *conf);
dgabino 0:102b50f941d0 317
dgabino 0:102b50f941d0 318 /**
dgabino 0:102b50f941d0 319 @brief Connect to the LoRa concentrator, reset it and configure it according to previously set parameters
dgabino 0:102b50f941d0 320 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 321 */
dgabino 0:102b50f941d0 322 int lgw_start(void);
dgabino 0:102b50f941d0 323
dgabino 0:102b50f941d0 324 /**
dgabino 0:102b50f941d0 325 @brief Stop the LoRa concentrator and disconnect it
dgabino 0:102b50f941d0 326 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 327 */
dgabino 0:102b50f941d0 328 int lgw_stop(void);
dgabino 0:102b50f941d0 329
dgabino 0:102b50f941d0 330 /**
dgabino 0:102b50f941d0 331 @brief A non-blocking function that will fetch up to 'max_pkt' packets from the LoRa concentrator FIFO and data buffer
dgabino 0:102b50f941d0 332 @param max_pkt maximum number of packet that must be retrieved (equal to the size of the array of struct)
dgabino 0:102b50f941d0 333 @param pkt_data pointer to an array of struct that will receive the packet metadata and payload pointers
dgabino 0:102b50f941d0 334 @return LGW_HAL_ERROR id the operation failed, else the number of packets retrieved
dgabino 0:102b50f941d0 335 */
dgabino 0:102b50f941d0 336 int lgw_receive(uint8_t max_pkt, struct lgw_pkt_rx_s *pkt_data);
dgabino 0:102b50f941d0 337
dgabino 0:102b50f941d0 338 /**
dgabino 0:102b50f941d0 339 @brief Schedule a packet to be send immediately or after a delay depending on tx_mode
dgabino 0:102b50f941d0 340 @param pkt_data structure containing the data and metadata for the packet to send
dgabino 0:102b50f941d0 341 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 342
dgabino 0:102b50f941d0 343 /!\ When sending a packet, there is a 1.5 ms delay for the analog circuitry to start and be stable (TX_START_DELAY).
dgabino 0:102b50f941d0 344 In 'timestamp' mode, this is transparent: the modem is started 1.5ms before the user-set timestamp value is reached, the preamble of the packet start right when the internal timestamp counter reach target value.
dgabino 0:102b50f941d0 345 In 'immediate' mode, the packet is emitted as soon as possible: transferring the packet (and its parameters) from the host to the concentrator takes some time, then there is the TX_START_DELAY, then the packet is emitted.
dgabino 0:102b50f941d0 346 In 'triggered' mode (aka PPS/GPS mode), the packet, typically a beacon, is emitted 1.5ms after a rising edge of the trigger signal. Because there is no way to anticipate the triggering event and start the analog circuitry beforehand, that delay must be taken into account in the protocol.
dgabino 0:102b50f941d0 347 */
dgabino 0:102b50f941d0 348 int lgw_send(struct lgw_pkt_tx_s pkt_data);
dgabino 0:102b50f941d0 349
dgabino 0:102b50f941d0 350 /**
dgabino 0:102b50f941d0 351 @brief Give the the status of different part of the LoRa concentrator
dgabino 0:102b50f941d0 352 @param select is used to select what status we want to know
dgabino 0:102b50f941d0 353 @param code is used to return the status code
dgabino 0:102b50f941d0 354 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 355 */
dgabino 0:102b50f941d0 356 int lgw_status(uint8_t select, uint8_t *code);
dgabino 0:102b50f941d0 357
dgabino 0:102b50f941d0 358 /**
dgabino 0:102b50f941d0 359 @brief Abort a currently scheduled or ongoing TX
dgabino 0:102b50f941d0 360 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 361 */
dgabino 0:102b50f941d0 362 int lgw_abort_tx(void);
dgabino 0:102b50f941d0 363
dgabino 0:102b50f941d0 364 /**
dgabino 0:102b50f941d0 365 @brief Return value of internal counter when latest event (eg GPS pulse) was captured
dgabino 0:102b50f941d0 366 @param trig_cnt_us pointer to receive timestamp value
dgabino 0:102b50f941d0 367 @return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
dgabino 0:102b50f941d0 368 */
dgabino 0:102b50f941d0 369 int lgw_get_trigcnt(uint32_t* trig_cnt_us);
dgabino 0:102b50f941d0 370
dgabino 0:102b50f941d0 371 /**
dgabino 0:102b50f941d0 372 @brief Allow user to check the version/options of the library once compiled
dgabino 0:102b50f941d0 373 @return pointer on a human-readable null terminated string
dgabino 0:102b50f941d0 374 */
dgabino 0:102b50f941d0 375 const char* lgw_version_info(void);
dgabino 0:102b50f941d0 376
dgabino 0:102b50f941d0 377 /**
dgabino 0:102b50f941d0 378 @brief Allow user to check the version of the concentrator MCU firmware
dgabino 0:102b50f941d0 379 @return An integer value representing the firmware version
dgabino 0:102b50f941d0 380 */
dgabino 0:102b50f941d0 381 int lgw_mcu_version_info(void);
dgabino 0:102b50f941d0 382
dgabino 0:102b50f941d0 383 /**
dgabino 0:102b50f941d0 384 @brief Return time on air of given packet, in milliseconds
dgabino 0:102b50f941d0 385 @param packet is a pointer to the packet structure
dgabino 0:102b50f941d0 386 @return the packet time on air in milliseconds
dgabino 0:102b50f941d0 387 */
dgabino 0:102b50f941d0 388 uint32_t lgw_time_on_air(struct lgw_pkt_tx_s *packet);
dgabino 0:102b50f941d0 389
dgabino 0:102b50f941d0 390 #endif
dgabino 0:102b50f941d0 391
dgabino 0:102b50f941d0 392 /* --- EOF ------------------------------------------------------------------ */