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/readme.md@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 (C)2013 Semtech-Cycleo
dgabino 0:102b50f941d0 7
dgabino 0:102b50f941d0 8 LoRa concentrator HAL user manual
dgabino 0:102b50f941d0 9 ============================
dgabino 0:102b50f941d0 10
dgabino 0:102b50f941d0 11 1. Introduction
dgabino 0:102b50f941d0 12 ---------------
dgabino 0:102b50f941d0 13
dgabino 0:102b50f941d0 14 The LoRa concentrator Hardware Abstraction Layer is a C library that allow you
dgabino 0:102b50f941d0 15 to use a Semtech concentrator chip through a reduced number of high level C
dgabino 0:102b50f941d0 16 functions to configure the hardware, send and receive packets.
dgabino 0:102b50f941d0 17
dgabino 0:102b50f941d0 18 The Semtech LoRa concentrator is a digital multi-channel multi-standard packet
dgabino 0:102b50f941d0 19 radio used to send and receive packets wirelessly using LoRa or FSK modulations.
dgabino 0:102b50f941d0 20
dgabino 0:102b50f941d0 21 2. Components of the library
dgabino 0:102b50f941d0 22 ----------------------------
dgabino 0:102b50f941d0 23
dgabino 0:102b50f941d0 24 The library is composed of 6 modules:
dgabino 0:102b50f941d0 25
dgabino 0:102b50f941d0 26 * loragw_hal
dgabino 0:102b50f941d0 27 * loragw_reg
dgabino 0:102b50f941d0 28 * loragw_mcu
dgabino 0:102b50f941d0 29 * loragw_com
dgabino 0:102b50f941d0 30 * loragw_aux
dgabino 0:102b50f941d0 31 * loragw_radio
dgabino 0:102b50f941d0 32
dgabino 0:102b50f941d0 33 The library also contains basic test programs to demonstrate code use and check
dgabino 0:102b50f941d0 34 functionality.
dgabino 0:102b50f941d0 35
dgabino 0:102b50f941d0 36 ### 2.1. loragw_hal ###
dgabino 0:102b50f941d0 37
dgabino 0:102b50f941d0 38 This is the main module and contains the high level functions to configure and
dgabino 0:102b50f941d0 39 use the LoRa concentrator:
dgabino 0:102b50f941d0 40
dgabino 0:102b50f941d0 41 * lgw_board_setconf, to set the configuration of the concentrator
dgabino 0:102b50f941d0 42 * lgw_rxrf_setconf, to set the configuration of the radio channels
dgabino 0:102b50f941d0 43 * lgw_rxif_setconf, to set the configuration of the IF+modem channels
dgabino 0:102b50f941d0 44 * lgw_txgain_setconf, to set the configuration of the concentrator gain table
dgabino 0:102b50f941d0 45 * lgw_start, to apply the set configuration to the hardware and start it
dgabino 0:102b50f941d0 46 * lgw_stop, to stop the hardware
dgabino 0:102b50f941d0 47 * lgw_receive, to fetch packets if any was received
dgabino 0:102b50f941d0 48 * lgw_send, to send a single packet (non-blocking, see warning in usage section)
dgabino 0:102b50f941d0 49 * lgw_status, to check when a packet has effectively been sent
dgabino 0:102b50f941d0 50
dgabino 0:102b50f941d0 51 For an standard application, include only this module.
dgabino 0:102b50f941d0 52 The use of this module is detailed on the usage section.
dgabino 0:102b50f941d0 53
dgabino 0:102b50f941d0 54 /!\ When sending a packet, there is a 1.5 ms delay for the analog circuitry to
dgabino 0:102b50f941d0 55 start and be stable (TX_START_DELAY).
dgabino 0:102b50f941d0 56
dgabino 0:102b50f941d0 57 In 'timestamp' mode, this is transparent: the modem is started 1.5ms before the
dgabino 0:102b50f941d0 58 user-set timestamp value is reached, the preamble of the packet start right when
dgabino 0:102b50f941d0 59 the internal timestamp counter reach target value.
dgabino 0:102b50f941d0 60
dgabino 0:102b50f941d0 61 In 'immediate' mode, the packet is emitted as soon as possible: transferring the
dgabino 0:102b50f941d0 62 packet (and its parameters) from the host to the concentrator takes some time,
dgabino 0:102b50f941d0 63 then there is the TX_START_DELAY, then the packet is emitted.
dgabino 0:102b50f941d0 64
dgabino 0:102b50f941d0 65 In 'triggered' mode (aka PPS/GPS mode), the packet, typically a beacon, is
dgabino 0:102b50f941d0 66 emitted 1.5ms after a rising edge of the trigger signal. Because there is no
dgabino 0:102b50f941d0 67 way to anticipate the triggering event and start the analog circuitry
dgabino 0:102b50f941d0 68 beforehand, that delay must be taken into account in the protocol.
dgabino 0:102b50f941d0 69
dgabino 0:102b50f941d0 70 ### 2.2. loragw_mcu ###
dgabino 0:102b50f941d0 71
dgabino 0:102b50f941d0 72 This module wraps the HAL functions into commands to be sent to the concentrator
dgabino 0:102b50f941d0 73 MCU.
dgabino 0:102b50f941d0 74
dgabino 0:102b50f941d0 75 The HAL structures are serialized in a byte array and sent over the COM/USB
dgabino 0:102b50f941d0 76 interface.
dgabino 0:102b50f941d0 77
dgabino 0:102b50f941d0 78 * board configuration
dgabino 0:102b50f941d0 79 * send/receive packets
dgabino 0:102b50f941d0 80 * ...
dgabino 0:102b50f941d0 81
dgabino 0:102b50f941d0 82 ### 2.3. loragw_reg ###
dgabino 0:102b50f941d0 83
dgabino 0:102b50f941d0 84 This module is used to access to the LoRa concentrator registers by name instead
dgabino 0:102b50f941d0 85 of by address:
dgabino 0:102b50f941d0 86
dgabino 0:102b50f941d0 87 * lgw_connect, to initialise and check the connection with the hardware
dgabino 0:102b50f941d0 88 * lgw_disconnect, to disconnect the hardware
dgabino 0:102b50f941d0 89 * lgw_soft_reset, to reset the whole hardware by resetting the register array
dgabino 0:102b50f941d0 90 * lgw_reg_check, to check all registers vs. their default value and output the
dgabino 0:102b50f941d0 91 result to a file
dgabino 0:102b50f941d0 92 * lgw_reg_r, read a named register
dgabino 0:102b50f941d0 93 * lgw_reg_w, write a named register
dgabino 0:102b50f941d0 94 * lgw_reg_rb, read a name register in burst
dgabino 0:102b50f941d0 95 * lgw_reg_wb, write a named register in burst
dgabino 0:102b50f941d0 96
dgabino 0:102b50f941d0 97 This module handles pagination, read-only registers protection, multi-byte
dgabino 0:102b50f941d0 98 registers management, signed registers management, read-modify-write routines
dgabino 0:102b50f941d0 99 for sub-byte registers and read/write burst fragmentation to respect SPI
dgabino 0:102b50f941d0 100 maximum burst length constraints.
dgabino 0:102b50f941d0 101
dgabino 0:102b50f941d0 102 It make the code much easier to read and to debug.
dgabino 0:102b50f941d0 103 Moreover, if registers are relocated between different hardware revisions but
dgabino 0:102b50f941d0 104 keep the same function, the code written using register names can be reused "as
dgabino 0:102b50f941d0 105 is".
dgabino 0:102b50f941d0 106
dgabino 0:102b50f941d0 107 If you need access to all the registers, include this module in your
dgabino 0:102b50f941d0 108 application.
dgabino 0:102b50f941d0 109
dgabino 0:102b50f941d0 110 **/!\ Warning** please be sure to have a good understanding of the LoRa
dgabino 0:102b50f941d0 111 concentrator inner working before accessing the internal registers directly.
dgabino 0:102b50f941d0 112
dgabino 0:102b50f941d0 113 ### 2.4. loragw_com ###
dgabino 0:102b50f941d0 114
dgabino 0:102b50f941d0 115 This module contains the functions to access the LoRa concentrator register
dgabino 0:102b50f941d0 116 array through the USB/UART interface:
dgabino 0:102b50f941d0 117
dgabino 0:102b50f941d0 118 * lgw_com_r to read one byte
dgabino 0:102b50f941d0 119 * lgw_com_w to write one byte
dgabino 0:102b50f941d0 120 * lgw_com_rb to read two bytes or more
dgabino 0:102b50f941d0 121 * lgw_com_wb to write two bytes or more
dgabino 0:102b50f941d0 122
dgabino 0:102b50f941d0 123 Please *do not* include that module directly into your application.
dgabino 0:102b50f941d0 124
dgabino 0:102b50f941d0 125 **/!\ Warning** Accessing the LoRa concentrator register array without the
dgabino 0:102b50f941d0 126 checks and safety provided by the functions in loragw_reg is not recommended.
dgabino 0:102b50f941d0 127
dgabino 0:102b50f941d0 128 ### 2.5. loragw_aux ###
dgabino 0:102b50f941d0 129
dgabino 0:102b50f941d0 130 This module contains a single host-dependant function wait_ms to pause for a
dgabino 0:102b50f941d0 131 defined amount of milliseconds.
dgabino 0:102b50f941d0 132
dgabino 0:102b50f941d0 133 The procedure to start and configure the LoRa concentrator hardware contained in
dgabino 0:102b50f941d0 134 the loragw_hal module requires to wait for several milliseconds at certain
dgabino 0:102b50f941d0 135 steps, typically to allow for supply voltages or clocks to stabilize after been
dgabino 0:102b50f941d0 136 switched on.
dgabino 0:102b50f941d0 137
dgabino 0:102b50f941d0 138 An accuracy of 1 ms or less is ideal.
dgabino 0:102b50f941d0 139 If your system does not allow that level of accuracy, make sure that the actual
dgabino 0:102b50f941d0 140 delay is *longer* that the time specified when the function is called (ie.
dgabino 0:102b50f941d0 141 wait_ms(X) **MUST NOT** before X milliseconds under any circumstance).
dgabino 0:102b50f941d0 142
dgabino 0:102b50f941d0 143 If the minimum delays are not guaranteed during the configuration and start
dgabino 0:102b50f941d0 144 procedure, the hardware might not work at nominal performance.
dgabino 0:102b50f941d0 145 Most likely, it will not work at all.
dgabino 0:102b50f941d0 146
dgabino 0:102b50f941d0 147 ### 2.6. loragw_radio ###
dgabino 0:102b50f941d0 148
dgabino 0:102b50f941d0 149 This module contains functions to handle the configuration of SX125x radios.
dgabino 0:102b50f941d0 150
dgabino 0:102b50f941d0 151
dgabino 0:102b50f941d0 152 3. Software build process
dgabino 0:102b50f941d0 153 --------------------------
dgabino 0:102b50f941d0 154
dgabino 0:102b50f941d0 155 ### 3.1. Details of the software ###
dgabino 0:102b50f941d0 156
dgabino 0:102b50f941d0 157 The library is written following ANSI C conventions but using C99 explicit
dgabino 0:102b50f941d0 158 length data type for all data exchanges with hardware and for parameters.
dgabino 0:102b50f941d0 159
dgabino 0:102b50f941d0 160 The loragw_aux module contains POSIX dependant functions for millisecond
dgabino 0:102b50f941d0 161 accuracy pause.
dgabino 0:102b50f941d0 162 For embedded platforms, the function could be rewritten using hardware timers.
dgabino 0:102b50f941d0 163
dgabino 0:102b50f941d0 164 ### 3.2. Building options ###
dgabino 0:102b50f941d0 165
dgabino 0:102b50f941d0 166 All modules use a fprintf(stderr,...) function to display debug diagnostic
dgabino 0:102b50f941d0 167 messages if the DEBUG_xxx is set to 1 in library.cfg
dgabino 0:102b50f941d0 168
dgabino 0:102b50f941d0 169 ### 3.3. Building procedures ###
dgabino 0:102b50f941d0 170
dgabino 0:102b50f941d0 171 For cross-compilation set the ARCH and CROSS_COMPILE variables in the Makefile,
dgabino 0:102b50f941d0 172 or in your shell environment, with the correct toolchain name and path.
dgabino 0:102b50f941d0 173 ex:
dgabino 0:102b50f941d0 174 export PATH=/home/foo/rpi-toolchain/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin:$PATH
dgabino 0:102b50f941d0 175 export ARCH=arm
dgabino 0:102b50f941d0 176 export CROSS_COMPILE=arm-linux-gnueabihf-
dgabino 0:102b50f941d0 177
dgabino 0:102b50f941d0 178 The Makefile in the libloragw directory will parse the library.cfg file and
dgabino 0:102b50f941d0 179 generate a config.h C header file containing #define options.
dgabino 0:102b50f941d0 180 Those options enables and disables sections of code in the loragw_xxx.h files
dgabino 0:102b50f941d0 181 and the *.c source files.
dgabino 0:102b50f941d0 182
dgabino 0:102b50f941d0 183 The library.cfg is also used directly to select the proper set of dynamic
dgabino 0:102b50f941d0 184 libraries to be linked with.
dgabino 0:102b50f941d0 185
dgabino 0:102b50f941d0 186 ### 3.4. Export ###
dgabino 0:102b50f941d0 187
dgabino 0:102b50f941d0 188 Once build, to use that library on another system, you need to export the
dgabino 0:102b50f941d0 189 following files :
dgabino 0:102b50f941d0 190
dgabino 0:102b50f941d0 191 * libloragw/library.cfg -> root configuration file
dgabino 0:102b50f941d0 192 * libloragw/libloragw.a -> static library, to be linked with a program
dgabino 0:102b50f941d0 193 * libloragw/readme.md -> required for license compliance
dgabino 0:102b50f941d0 194 * libloragw/inc/config.h -> C configuration flags, derived from library.cfg
dgabino 0:102b50f941d0 195 * libloragw/inc/loragw_*.h -> take only the ones you need (eg. _hal and _gps)
dgabino 0:102b50f941d0 196
dgabino 0:102b50f941d0 197 After statically linking the library to your application, only the license
dgabino 0:102b50f941d0 198 is required to be kept or copied inside your program documentation.
dgabino 0:102b50f941d0 199
dgabino 0:102b50f941d0 200 4. Hardware dependencies
dgabino 0:102b50f941d0 201 ------------------------
dgabino 0:102b50f941d0 202
dgabino 0:102b50f941d0 203 ### 4.1. Hardware revision ###
dgabino 0:102b50f941d0 204
dgabino 0:102b50f941d0 205 The loragw_reg and loragw_hal are written for a specific version on the Semtech
dgabino 0:102b50f941d0 206 hardware (IP and/or silicon revision).
dgabino 0:102b50f941d0 207
dgabino 0:102b50f941d0 208 This code has been written for:
dgabino 0:102b50f941d0 209
dgabino 0:102b50f941d0 210 * Semtech SX1301 chip
dgabino 0:102b50f941d0 211 * Semtech SX1257 or SX1255 I/Q transceivers
dgabino 0:102b50f941d0 212
dgabino 0:102b50f941d0 213 The library will not work if there is a mismatch between the hardware version
dgabino 0:102b50f941d0 214 and the library version. You can use the test program test_loragw_reg to check
dgabino 0:102b50f941d0 215 if the hardware registers match their software declaration.
dgabino 0:102b50f941d0 216
dgabino 0:102b50f941d0 217 ### 4.2. USB/UART communication ###
dgabino 0:102b50f941d0 218
dgabino 0:102b50f941d0 219 loragw_com contains 4 functions (read, write, burst read, burst write) that are
dgabino 0:102b50f941d0 220 platform-dependant.
dgabino 0:102b50f941d0 221 The functions must be rewritten depending on the communication bridge you use:
dgabino 0:102b50f941d0 222
dgabino 0:102b50f941d0 223 * USB/UART over linux tty port (provided)
dgabino 0:102b50f941d0 224
dgabino 0:102b50f941d0 225 You can use the test program test_loragw_com to check that the USB communication
dgabino 0:102b50f941d0 226 is working.
dgabino 0:102b50f941d0 227
dgabino 0:102b50f941d0 228
dgabino 0:102b50f941d0 229 5. Usage
dgabino 0:102b50f941d0 230 --------
dgabino 0:102b50f941d0 231
dgabino 0:102b50f941d0 232 ### 5.1. Setting the software environment ###
dgabino 0:102b50f941d0 233
dgabino 0:102b50f941d0 234 For a typical application you need to:
dgabino 0:102b50f941d0 235
dgabino 0:102b50f941d0 236 * include loragw_hal.h in your program source
dgabino 0:102b50f941d0 237 * link to the libloragw.a static library during compilation
dgabino 0:102b50f941d0 238 * link to the librt library due to loragw_aux dependencies (timing functions)
dgabino 0:102b50f941d0 239
dgabino 0:102b50f941d0 240 For an application that will also access the concentrator configuration
dgabino 0:102b50f941d0 241 registers directly (eg. for advanced configuration) you also need to:
dgabino 0:102b50f941d0 242
dgabino 0:102b50f941d0 243 * include loragw_reg.h in your program source
dgabino 0:102b50f941d0 244
dgabino 0:102b50f941d0 245 ### 5.2. Using the software API ###
dgabino 0:102b50f941d0 246
dgabino 0:102b50f941d0 247 To use the HAL in your application, you must follow some basic rules:
dgabino 0:102b50f941d0 248
dgabino 0:102b50f941d0 249 * configure the radios path and IF+modem path before starting the radio
dgabino 0:102b50f941d0 250 * the configuration is only transferred to hardware when you call the *start*
dgabino 0:102b50f941d0 251 function
dgabino 0:102b50f941d0 252 * you cannot receive packets until one (or +) radio is enabled AND one (or +)
dgabino 0:102b50f941d0 253 IF+modem part is enabled AND the concentrator is started
dgabino 0:102b50f941d0 254 * you cannot send packets until one (or +) radio is enabled AND the concentrator
dgabino 0:102b50f941d0 255 is started
dgabino 0:102b50f941d0 256 * you must stop the concentrator before changing the configuration
dgabino 0:102b50f941d0 257
dgabino 0:102b50f941d0 258 A typical application flow for using the HAL is the following:
dgabino 0:102b50f941d0 259
dgabino 0:102b50f941d0 260 <configure the radios and IF+modems>
dgabino 0:102b50f941d0 261 <start the LoRa concentrator>
dgabino 0:102b50f941d0 262 loop {
dgabino 0:102b50f941d0 263 <fetch packets that were received by the concentrator>
dgabino 0:102b50f941d0 264 <process, store and/or forward received packets>
dgabino 0:102b50f941d0 265 <send packets through the concentrator>
dgabino 0:102b50f941d0 266 }
dgabino 0:102b50f941d0 267 <stop the concentrator>
dgabino 0:102b50f941d0 268
dgabino 0:102b50f941d0 269 **/!\ Warning** The lgw_send function is non-blocking and returns while the
dgabino 0:102b50f941d0 270 LoRa concentrator is still sending the packet, or even before the packet has
dgabino 0:102b50f941d0 271 started to be transmitted if the packet is triggered on a future event.
dgabino 0:102b50f941d0 272 While a packet is emitted, no packet can be received (limitation intrinsic to
dgabino 0:102b50f941d0 273 most radio frequency systems).
dgabino 0:102b50f941d0 274
dgabino 0:102b50f941d0 275 Your application *must* take into account the time it takes to send a packet or
dgabino 0:102b50f941d0 276 check the status (using lgw_status) before attempting to send another packet.
dgabino 0:102b50f941d0 277
dgabino 0:102b50f941d0 278 Trying to send a packet while the previous packet has not finished being send
dgabino 0:102b50f941d0 279 will result in the previous packet not being sent or being sent only partially
dgabino 0:102b50f941d0 280 (resulting in a CRC error in the receiver).
dgabino 0:102b50f941d0 281
dgabino 0:102b50f941d0 282 ### 5.3. Debugging mode ###
dgabino 0:102b50f941d0 283
dgabino 0:102b50f941d0 284 To debug your application, it might help to compile the loragw_hal function
dgabino 0:102b50f941d0 285 with the debug messages activated (set DEBUG_HAL=1 in library.cfg).
dgabino 0:102b50f941d0 286 It then send a lot of details, including detailed error messages to *stderr*.
dgabino 0:102b50f941d0 287
dgabino 0:102b50f941d0 288 6. License
dgabino 0:102b50f941d0 289 -----------
dgabino 0:102b50f941d0 290
dgabino 0:102b50f941d0 291 Copyright (c) 2013, SEMTECH S.A.
dgabino 0:102b50f941d0 292 All rights reserved.
dgabino 0:102b50f941d0 293
dgabino 0:102b50f941d0 294 Redistribution and use in source and binary forms, with or without
dgabino 0:102b50f941d0 295 modification, are permitted provided that the following conditions are met:
dgabino 0:102b50f941d0 296
dgabino 0:102b50f941d0 297 * Redistributions of source code must retain the above copyright
dgabino 0:102b50f941d0 298 notice, this list of conditions and the following disclaimer.
dgabino 0:102b50f941d0 299 * Redistributions in binary form must reproduce the above copyright
dgabino 0:102b50f941d0 300 notice, this list of conditions and the following disclaimer in the
dgabino 0:102b50f941d0 301 documentation and/or other materials provided with the distribution.
dgabino 0:102b50f941d0 302 * Neither the name of the Semtech corporation nor the
dgabino 0:102b50f941d0 303 names of its contributors may be used to endorse or promote products
dgabino 0:102b50f941d0 304 derived from this software without specific prior written permission.
dgabino 0:102b50f941d0 305
dgabino 0:102b50f941d0 306 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
dgabino 0:102b50f941d0 307 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
dgabino 0:102b50f941d0 308 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
dgabino 0:102b50f941d0 309 DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY
dgabino 0:102b50f941d0 310 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
dgabino 0:102b50f941d0 311 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
dgabino 0:102b50f941d0 312 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
dgabino 0:102b50f941d0 313 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
dgabino 0:102b50f941d0 314 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
dgabino 0:102b50f941d0 315 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
dgabino 0:102b50f941d0 316
dgabino 0:102b50f941d0 317 *EOF*