Beta 7 (beta6 skipped)v1.b7

- API: change memory allocation for payload, they are now part of the struct for TX/RX, no need to malloc/free
- reduced number of SPI transactions to fetch a packet (improved number a packets par second that can be downloaded from gateway)
- streamlined build process, main target is now a static library: libloragw.a
- All RX chains can use any of the two radios now
- FSK is available and working in TX and RX (variable length mode)
- Calibrated RSSI for FSK
- lgw_connect now check the CHIP_ID
- Added a license file and a changelog
- Added a function returning a version string to allow identification of the version/options once compiled

24 files changed, 5448 insertions, 0 deletions

diff --git a/libloragw/Makefile b/libloragw/Makefile
new file mode 100644
index 0000000..38d2fae
--- /dev/null
+++ b/libloragw/Makefile
@@ -0,0 +1,77 @@
+# putting the configuration in a separate file
+include library.cfg
+
+# constant symbols
+CC=gcc
+CFLAGS=-O2 -Iinc -I.
+C99FLAGS=-O2 -std=c99 -Iinc -I.
+
+# configuration-dependant symbols
+ifeq ($(LGW_PHY),native)
+LDFLAGS=-lrt
+endif
+ifeq ($(LGW_PHY),ftdi)
+LDFLAGS=-lrt -lmpsse
+endif
+
+# general build targets
+
+all: libloragw.a test_loragw_spi test_loragw_reg test_loragw_hal
+
+clean:
+	rm -f *.a
+	rm -f test_*
+	rm -f obj/*.o
+	rm -f .conf_ok
+
+.conf_ok: library.cfg
+	@echo "*** Checking Lora gateway HAL library config ***"
+	@rm -f .conf_ok
+ifeq ($(LGW_PHY),native)
+	@echo "Selected SPI interface type: Linux native driver"
+else
+ifeq ($(LGW_PHY),ftdi)
+	@echo "Selected SPI interface type: FTDI SPI-over-USB bridge"
+else
+	$(error No SPI physical layer selected)
+endif
+endif
+	@echo "*** Config seems ok ***"
+	@echo ""
+	@touch .conf_ok
+
+# static library
+
+libloragw.a: obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+	ar rcs libloragw.a obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+
+# library module target
+
+obj/loragw_aux.o: .conf_ok src/loragw_aux.c inc/loragw_aux.h
+	$(CC) -c $(CFLAGS) src/loragw_aux.c -o obj/loragw_aux.o $(FLAG_AUX)
+
+obj/loragw_spi.o: .conf_ok src/loragw_spi.native.c src/loragw_spi.ftdi.c inc/loragw_spi.h
+ifeq ($(LGW_PHY),native)
+	$(CC) -c $(C99FLAGS) src/loragw_spi.native.c -o obj/loragw_spi.o $(FLAG_SPI)
+endif
+ifeq ($(LGW_PHY),ftdi)
+	$(CC) -c $(C99FLAGS) src/loragw_spi.ftdi.c -o obj/loragw_spi.o $(FLAG_SPI)
+endif
+
+obj/loragw_reg.o: .conf_ok src/loragw_reg.c inc/loragw_reg.h inc/loragw_spi.h
+	$(CC) -c $(C99FLAGS) src/loragw_reg.c -o obj/loragw_reg.o $(FLAG_REG)
+
+obj/loragw_hal.o: .conf_ok src/loragw_hal.c src/arb_fw.var src/agc_fw.var inc/loragw_hal.h inc/loragw_reg.h inc/loragw_spi.h inc/loragw_aux.h
+	$(CC) -c $(C99FLAGS) src/loragw_hal.c -o obj/loragw_hal.o -D LGW_PHY="\"$(LGW_PHY)\"" $(FLAG_HAL)
+
+# test programs
+
+test_loragw_spi: tst/test_loragw_spi.c obj/loragw_spi.o
+	$(CC) $(C99FLAGS) tst/test_loragw_spi.c obj/loragw_spi.o -o test_loragw_spi $(LDFLAGS)
+
+test_loragw_reg: tst/test_loragw_reg.c obj/loragw_reg.o obj/loragw_spi.o
+	$(CC) $(C99FLAGS) tst/test_loragw_reg.c obj/loragw_reg.o obj/loragw_spi.o -o test_loragw_reg $(LDFLAGS)
+	
+test_loragw_hal: tst/test_loragw_hal.c obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+	$(CC) $(C99FLAGS) tst/test_loragw_hal.c obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o -o test_loragw_hal $(LDFLAGS)
+
diff --git a/libloragw/README.TXT b/libloragw/README.TXT
new file mode 100644
index 0000000..9d13a4a
--- /dev/null
+++ b/libloragw/README.TXT
@@ -0,0 +1,30 @@
+Lora Gateway HAL library - Content of subdirectories
+====================================================
+
+## 1. doc ##
+
+Contains the user manual, licensing informations, udev rules, etc.
+
+## 2. inc ##
+
+Contain C header files for the different sub-modules of the library.
+
+You *MUST* include loragw_hal.h in your application.
+You *MAY* include loragw_reg.h in your application if you need direct registers 
+access.
+
+## 3. obj ##
+
+Contained the compiled intermediary objects.
+
+## 4. src ##
+
+Contain library C sources.
+
+## 5. tst ##
+
+Contain the C sources for test programs to validate SPI link, register access 
+and hardware functionality.
+
+
+*EOF*
\ No newline at end of file
diff --git a/libloragw/VERSION b/libloragw/VERSION
new file mode 100644
index 0000000..87b0704
--- /dev/null
+++ b/libloragw/VERSION
@@ -0,0 +1,20 @@
+/* Software library version: */
+#define VERSION_LIBRARY			"beta7"
+
+/* API version */
+#define VERSION_API				"beta"
+
+/* Accepted value of CHIP_ID (SPI registers) must match reg default value in loragw_reg.c */
+#define ACCEPT_CHIP_ID			"1"
+
+/* Accepted value of VERSION (SPI registers) must match reg default value in loragw_reg.c */
+#define	ACCEPT_VERSION_REG		"103"
+
+/* Accepted radio components */
+#define	INFO_RADIO_CHIP			"dual SX1257"
+
+/* Radio constants defined for the following bands */
+#define	INFO_RF_PARAM			"863-870 MHz TX&RX"
+
+/* Library validated on the following concentrator boards */
+#define	INFO_REF_HARDWARE		"Semtech Nano Concentrator v1 and v2"
diff --git a/libloragw/doc/99-libftdi.rules b/libloragw/doc/99-libftdi.rules
new file mode 100644
index 0000000..8487413
--- /dev/null
+++ b/libloragw/doc/99-libftdi.rules
@@ -0,0 +1,8 @@
+# FTDI Devices: FT232BM/L/Q, FT245BM/L/Q, FT232RL/Q, FT245RL/Q, VNC1L with VDPS Firmware
+SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0664", GROUP="plugdev"
+
+# FTDI Devices: FT2232C/D/L, FT2232HL/Q
+SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0664", GROUP="plugdev"
+
+# FTDI Devices: FT4232HL/Q
+SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6011", MODE="0664", GROUP="plugdev"
diff --git a/libloragw/doc/CHANGELOG.TXT b/libloragw/doc/CHANGELOG.TXT
new file mode 100644
index 0000000..4ec6bd7
--- /dev/null
+++ b/libloragw/doc/CHANGELOG.TXT
@@ -0,0 +1,35 @@
+Lora Gateway HAL changelog
+==========================
+
+ Beta 7 (from beta 5)
+---------------------
+
+ * Reduced number of SPI transactions to fetch a packet (improved number a packets par second that can be downloaded from gateway)
+ * Streamlined build process, main target is now a static library: libloragw.a
+ * Change memory allocation for payload: they are now part of the struct for TX/RX, no need to malloc/free
+ * All RX chains can use any of the two radios now
+ * FSK is available and working in TX and RX (variable length mode)
+ * Calibrated RSSI for FSK
+ * lgw_connect now check the CHIP_ID
+ * Added a license file and a changelog
+ * Added a function returning a version string to allow identification of the version/options once compiled
+
+ Beta 6
+-------
+
+Not a mainline release, not taken into account in that changelog.
+
+ Beta 5 (from beta 4)
+---------------------
+
+ * Updated registers, firmware and configuration to align with r986 bitstream revision
+ * Calibrated RSSI for Lora "multi" and Lora "stand alone" modems
+ * Renamed some confusing TX status code
+ * Preliminary FSK support
+
+ Beta 4 (from beta 3)
+---------------------
+
+ * Unified build environment with selectable SPI layer (Linux native or FTDI SPI-over-USB bridge)
+ * Remove the 500 kHz limit on radio bandwith, back to the nominal 800 kHz
+ * Renamed debug flags
diff --git a/libloragw/doc/INSTALL_FTDI.TXT b/libloragw/doc/INSTALL_FTDI.TXT
new file mode 100644
index 0000000..d26ad4b
--- /dev/null
+++ b/libloragw/doc/INSTALL_FTDI.TXT
@@ -0,0 +1,46 @@
+#  / _____)             _              | |
+# ( (____  _____ ____ _| |_ _____  ____| |__
+#  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
+#  _____) ) ____| | | || |_| ____( (___| | | |
+# (______/|_____)_|_|_| \__)_____)\____)_| |_|
+#     ©2013 Semtech-Cycleo
+#
+# Description:
+#	Installation procedure for FTDI SPI-over-USB dependencies
+
+# [STEP 1] Install libftdi
+sudo apt-get install libftdi-dev
+
+# this should install :
+# - libftdi-dev 0.19-4 (armhf)
+# - libftdil 0.19-4 (armhf)
+# - libusb-dev 2:0.1.12-20 (armhf)
+
+# [STEP 2] Download and unpack the libMPSSE 1.3
+# File must match SHA1 Checksum: 1b994a23b118f83144261e3e786c43df74a81cd5
+wget http://libmpsse.googlecode.com/files/libmpsse-1.3.tar.gz
+sha1sum libmpsse-1.3.tar.gz
+tar -xzvf libmpsse-1.3.tar.gz
+
+# Go to the src directory and install the library
+./configure --disable-python
+make
+sudo make install
+# Static and dynamic libraries compiled code is put into /usr/local/lib
+# Header file is put into /usr/local/include
+
+# On the Pcduino, you must regenerate the library cache (might some time).
+sudo ldconfig
+
+# [STEP 3] to allow non-root applications to access the FTDI device on USB
+# copy the provided 99-libftdi.rules file in /etc/udev/rules.d
+# For the nano board, only the FT2232H line is required.
+# Non-root users members of plugdev group will be able to access the device.
+
+# [STEP 4] Unpack the Lora Gateway HAL and go to its directory.
+# Configure build options in library.cfg, then build the library and examples.
+make all
+
+# [STEP 5] Connect a nanoconcentrator and run test_loragw_reg to test that
+# you have access to Lora registers.
+# Less than 50 registers of the ~300 registers should return a mismatch.
diff --git a/libloragw/doc/LICENSE.TXT b/libloragw/doc/LICENSE.TXT
new file mode 100644
index 0000000..eab9548
--- /dev/null
+++ b/libloragw/doc/LICENSE.TXT
@@ -0,0 +1,8 @@
+THE FOLLOWING SOFTWARE IS PROVIDED: (1) "AS IS" WITH NO WARRANTY; AND 
+(2)TO ENABLE ACCESS TO CODING INFORMATION TO GUIDE AND FACILITATE CUSTOMER.
+CONSEQUENTLY, SEMTECH SHALL NOT BE HELD LIABLE FOR ANY DIRECT, INDIRECT OR
+CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE CONTENT
+OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING INFORMATION
+CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
+
+Copyright (C) SEMTECH S.A.
diff --git a/libloragw/doc/MANUAL.TXT b/libloragw/doc/MANUAL.TXT
new file mode 100644
index 0000000..1659f03
--- /dev/null
+++ b/libloragw/doc/MANUAL.TXT
@@ -0,0 +1,232 @@
+	 / _____)             _              | |    
+	( (____  _____ ____ _| |_ _____  ____| |__  
+	 \____ \| ___ |    (_   _) ___ |/ ___)  _ \ 
+	 _____) ) ____| | | || |_| ____( (___| | | |
+	(______/|_____)_|_|_| \__)_____)\____)_| |_|
+		©2013 Semtech-Cycleo
+
+Lora Gateway HAL user manual
+============================
+
+1. Introduction
+---------------
+
+The Lora Gateway Hardware Abstraction Layer is a C library that allow you to
+use a Semtech Lora gateway hardware through a reduced number of high level C
+functions to configure the hardware, send and receive packets.
+
+The Semtech Lora gateway is a digital multi-channel multi-standard packet radio
+used to send and receive packets wirelessly using Lora or FSK modulations.
+
+
+2. Components of the library
+----------------------------
+
+The library is composed of 4 modules:
+
+* loragw_hal
+* loragw_reg
+* loragw_spi
+* loragw_aux
+
+The library also contains 3 test program to demonstrate code use and check
+functionality.
+
+### 2.1. loragw_hal ###
+
+This is the main module and contains the high level functions to configure and
+use the Lora gateway:
+
+* lgw_rxrf_setconf, to set the configuration of the radio channels
+* lgw_rxif_setconf, to set the configuration of the IF+modem channels
+* lgw_start, to apply the set configuration to the hardware and start it
+* lgw_stop, to stop the hardware
+* lgw_receive, to fetch packets if any was received
+* lgw_send, to send a single packet (non-blocking, see warning in usage section)
+* lgw_status, to check when a packet has effectively been sent
+
+For an standard application, include only this module.
+The use of this module is detailed on the usage section.
+
+### 2.2. loragw_reg ###
+
+This module is used to access to the Lora gateway registers by name instead of
+by address:
+
+* lgw_connect, to initialise and check the connection with the hardware
+* lgw_disconnect, to disconnect the hardware
+* lgw_soft_reset, to reset the whole hardware by resetting the register array
+* lgw_reg_check, to check all registers vs. their default value and output the
+result to a file
+* lgw_reg_r, read a named register
+* lgw_reg_w, write a named register
+* lgw_reg_rb, read a name register in burst
+* lgw_reg_wb, write a named register in burst
+
+This module handles pagination, read-only registers protection, multi-byte
+registers management, signed registers management, read-modify-write routines
+for sub-byte registers and read/write burst fragmentation to respect SPI
+maximum burst length constraints.
+
+It make the code much easier to read and to debug.
+Moreover, if registers are relocated between different hardware revisions but
+keep the same function, the code written using register names can be reused "as
+is".
+
+If you need access to all the registers, include this module in your
+application.
+
+**/!\ Warning** please be sure to have a good understanding of the Lora gateway
+inner working before accessing the internal registers directly.
+
+### 2.3. loragw_spi ###
+
+This module contains the functions to access the Lora gateway register array
+through the SPI interface:
+
+* lgw_spi_r to read one byte
+* lgw_spi_w to write one byte
+* lgw_spi_rb to read two bytes or more
+* lgw_spi_wb to write two bytes or more
+
+Please *do not* include that module directly into your application.
+
+**/!\ Warning** Accessing the Lora gateway register array without the checks
+and safety provided by the functions in loragw_reg is not recommended.
+
+### 2.4. loragw_aux ###
+
+This module contains a single host-dependant function wait_ms to pause for a
+defined amount of milliseconds.
+
+The procedure to start and configure the Lora gateway hardware contained in the
+loragw_hal module requires to wait for several milliseconds at certain steps,
+typically to allow for supply voltages or clocks to stabilize after been
+switched on.
+
+An accuracy of 1 ms or less is ideal.
+If your system doesn't allow that level of accuracy, make sure that the actual
+delay is *longer* that the time specified when the function is called (ie.
+wait_ms(X) *MUST NOT* before X milliseconds under any circumstance).
+
+If the minimum delays are not guaranteed during the configuration and start
+procedure, the hardware might not work at nominal performance.
+Most likely, it will not work at all.
+
+
+3. Software dependencies
+------------------------
+
+The library is written following ANSI C conventions but using C99 explicit
+length data type for all data exchanges with hardware and for parameters.
+
+The loragw_aux module contains POSIX dependant functions for millisecond
+accuracy pause.
+For embedded platforms, the function could be rewritten using hardware times.
+
+All modules use the fprintf(stderr,...) function to display debug diagnostic
+messages if the DEBUG_xxx is set to 1 in library.cfg
+
+Depending on config, SPI module needs LibMPSSE to access the FTDI SPI-over-USB
+bridge. Please go to that URL to download that library:
+http://code.google.com/p/libmpsse/
+
+The code was tested with version 1.3 of LibMPSSE:
+http://libmpsse.googlecode.com/files/libmpsse-1.3.tar.gz
+SHA1 Checksum: 	1b994a23b118f83144261e3e786c43df74a81cd5
+
+That library has some dependencies itself, please read the installation
+instructions.
+
+
+4. Hardware dependencies
+------------------------
+
+### 4.1. Hardware revision ###
+
+The loragw_reg and loragw_hal are written for a specific version on the Semtech
+hardware (IP and/or silicon revision).
+All relevant details are contained in the VERSION.TXT file.
+
+The library will not work if there is a mismatch between the hardware version 
+and the library version. You can use the test program test_loragw_reg to check 
+if the hardware registers match their software declaration.
+
+### 4.2. SPI communication ###
+
+loragw_spi contains 4 SPI functions (read, write, burst read, burst write) that
+are platform-dependant.
+The functions must be rewritten depending on the SPI bridge you use:
+
+* SPI master matched to the Linux SPI device driver (provided)
+* SPI over USB using FTDI components (provided)
+* native SPI using a microcontroller peripheral (not provided)
+
+Edit library.cfg to chose which SPI physical interface you want to use.
+
+You can use the test program test_loragw_spi to check with a logic analyser
+that the SPI communication is working
+
+
+5. Usage
+--------
+
+### 5.1. Setting the software environment ###
+
+For a typical application you need to:
+
+* include loragw_hal.h in your program source
+* link to the libloragw.a static library during compilation
+* link to the librt library due to loragw_aux dependencies (timing functions)
+* link to the libmpsse library if you use a FTDI SPI-over-USB bridge
+
+For an application that will also access the concentrator configuration 
+registers directly (eg. for advanced configuration) you also need to:
+
+* include loragw_reg.h in your program source
+
+### 5.2. Using the software API ###
+
+To use the HAL in your application, you must follow some basic rules:
+
+* configure the radios path and IF+modem path before starting the radio
+* the configuration is only transferred to hardware when you call the *start*
+function
+* you cannot receive packets until one (or +) radio is enabled AND one (or +)
+IF+modem part is enabled AND the gateway is started
+* you cannot send packets until one (or +) radio is enabled AND the gateway is
+started
+* you must stop the gateway before changing the configuration
+
+A typical application flow for using the HAL is the following:
+
+<configure the radios and IF+modems>
+<start the Lora gateway>
+loop {
+	<fetch packets that were received by the gateway>
+	<process, store and/or forward received packets>
+	<send packets through the gateway>
+}
+<stop the gateway>
+
+**/!\ Warning** The lgw_send function is non-blocking and returns while the
+Lora gateway is still sending the packet, or even before the packet has started
+to be transmitted if the packet is triggered on a future event.
+While a packet is emitted, no packet can be received (limitation intrinsic to
+most radio frequency systems).
+
+Your application *must* take into account the time it takes to send a packet or 
+check the status (using lgw_status) before attempting to send another packet.
+
+Trying to send a packet while the previous packet has not finished being send
+will result in the previous packet not being sent or being sent only partially
+(resulting in a CRC error in the receiver).
+
+### 5.3. Debugging mode ###
+
+To debug your application, it might help to compile the loragw_hal function
+with the debug messages activated (set DEBUG_HAL=1 in library.cfg).
+It then send a lot of details, including detailed error messages to *stderr*.
+
+
+*EOF*
\ No newline at end of file
diff --git a/libloragw/inc/loragw_aux.h b/libloragw/inc/loragw_aux.h
new file mode 100644
index 0000000..09f543f
--- /dev/null
+++ b/libloragw/inc/loragw_aux.h
@@ -0,0 +1,28 @@
+/*
+ / _____)             _              | |
+( (____  _____ ____ _| |_ _____  ____| |__
+ \____ \| ___ |    (_   _) ___ |/ ___)  _ \
+ _____) ) ____| | | || |_| ____( (___| | | |
+(______/|_____)_|_|_| \__)_____)\____)_| |_|
+    ©2013 Semtech-Cycleo
+
+Description:
+	Lora gateway Hardware Abstraction Layer
+*/
+
+
+#ifndef _LORAGW_AUX_H
+#define _LORAGW_AUX_H
+
+/* -------------------------------------------------------------------------- */
+/* --- PUBLIC FUNCTIONS PROTOTYPES ------------------------------------------ */
+
+/**
+@brief Wait for a certain time (millisecond accuracy)
+@param t number of milliseconds to wait.
+*/
+void wait_ms(unsigned long t);
+
+#endif
+
+/* --- EOF ------------------------------------------------------------------ */
diff --git a/libloragw/inc/loragw_hal.h b/libloragw/inc/loragw_hal.h
new file mode 100644
index 0000000..08aa945
--- /dev/null
+++ b/libloragw/inc/loragw_hal.h
@@ -0,0 +1,283 @@
+/*
+ / _____)             _              | |
+( (____  _____ ____ _| |_ _____  ____| |__
+ \____ \| ___ |    (_   _) ___ |/ ___)  _ \
+ _____) ) ____| | | || |_| ____( (___| | | |
+(______/|_____)_|_|_| \__)_____)\____)_| |_|
+    ©2013 Semtech-Cycleo
+
+Description:
+	Lora gateway Hardware Abstraction Layer
+*/
+
+
+#ifndef _LORAGW_HAL_H
+#define _LORAGW_HAL_H
+
+/* -------------------------------------------------------------------------- */
+/* --- DEPENDANCIES --------------------------------------------------------- */
+
+#include <stdint.h>		/* C99 types */
+#include <stdbool.h>	/* bool type */
+
+/* -------------------------------------------------------------------------- */
+/* --- PUBLIC MACROS -------------------------------------------------------- */
+
+#define IS_LORA_BW(bw)			((bw == BW_125KHZ) || (bw == BW_250KHZ) || (bw == BW_500KHZ))
+#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))
+#define IS_LORA_MULTI_DR(dr)	((dr & ~DR_LORA_MULTI) == 0) /* ones outside of DR_LORA_MULTI bitmask -> not a combination of Lora datarates */
+#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))
+
+#define IS_FSK_BW(bw)			((bw >= 1) && (bw <= 7))
+#define IS_FSK_DR(dr)			((dr >= DR_FSK_MIN) && (dr <= DR_FSK_MAX))
+
+#define	IS_TX_MODE(mode)		((mode == IMMEDIATE) || (mode == TIMESTAMPED) || (mode == ON_GPS))
+
+/* -------------------------------------------------------------------------- */
+/* --- PUBLIC CONSTANTS ----------------------------------------------------- */
+
+/* return status code */
+#define LGW_HAL_SUCCESS		0
+#define LGW_HAL_ERROR		-1
+
+/* hardware characteristics */
+#define LGW_RF_CHAIN_NB		2	/* number of RF chains */
+#define LGW_IF_CHAIN_NB		10	/* number of IF+modem RX chains */
+#define LGW_MULTI_NB		4	/* number of Lora 'multi SF' chains */
+
+#define LGW_PKT_FIFO_SIZE	8			/* depth of the RX packet FIFO */
+#define LGW_DATABUFF_SIZE	1024		/* size in bytes of the RX data buffer (contains payload & metadata) */
+#define LGW_REF_BW			125000		/* typical bandwidth of data channel */
+#define LGW_XTAL_FREQU		32000000	/* frequency of the RF reference oscillator */
+
+/* to use those parameters, declare a local constant, and use 'rf_chain' as index */
+#define LGW_RF_RX_LOWFREQ	{863000000, 863000000}	/* lower limit of the usable band in RX for each radio */
+#define LGW_RF_RX_UPFREQ	{870000000, 870000000}	/* upper limit of the usable band in RX for each radio */
+#define LGW_RF_RX_BANDWIDTH	{800000, 	800000}		/* bandwidth of the radios */
+#define LGW_RF_TX_LOWFREQ	{863000000, 863000000}	/* lower limit of the usable band in TX for each radio */
+#define LGW_RF_TX_UPFREQ	{870000000, 870000000}	/* upper limit of the usable band in TX for each radio */
+
+/* type of if_chain + modem */
+#define IF_UNDEFINED		0
+#define IF_LORA_STD			0x10	/* if + standard single-SF Lora modem */
+#define IF_LORA_MULTI		0x11	/* if + Lora receiver with multi-SF capability */
+#define IF_FSK_STD			0x20	/* if + standard FSK modem */
+
+/* configuration of available IF chains and modems on the hardware */
+/* to use, declare a local constant, and use 'if_chain' as index */
+#define LGW_IFMODEM_CONFIG {\
+	IF_LORA_MULTI, \
+	IF_LORA_MULTI, \
+	IF_LORA_MULTI, \
+	IF_LORA_MULTI, \
+	IF_UNDEFINED, \
+	IF_UNDEFINED, \
+	IF_UNDEFINED, \
+	IF_UNDEFINED, \
+	IF_LORA_STD, \
+	IF_FSK_STD }
+
+/* values available for the 'modulation' parameters */
+/* NOTE: arbitrary values */
+#define MOD_UNDEFINED	0
+#define MOD_LORA		0x10
+#define MOD_FSK			0x20
+
+/* values available for the 'bandwidth' parameters (Lora & FSK) */
+/* NOTE: directly encode FSK RX bandwidth, do not change */
+#define BW_UNDEFINED	0
+#define BW_500KHZ		0x01
+#define BW_250KHZ		0x02
+#define BW_125KHZ		0x03
+#define BW_62K5HZ		0x04
+#define BW_31K2HZ		0x05
+#define BW_15K6HZ		0x06
+#define BW_7K8HZ		0x07
+
+/* values available for the 'datarate' parameters */
+/* NOTE: Lora values used directly to code SF bitmask in 'multi' modem, do not change */
+#define DR_UNDEFINED	0
+#define DR_LORA_SF7		0x02
+#define DR_LORA_SF8		0x04
+#define DR_LORA_SF9		0x08
+#define DR_LORA_SF10	0x10
+#define DR_LORA_SF11	0x20
+#define DR_LORA_SF12	0x40
+#define DR_LORA_MULTI	0x7E
+/* NOTE: for FSK directly use baudrate between 300 bauds and 250 kbauds */
+#define DR_FSK_MIN		300
+#define DR_FSK_MAX		250000
+
+/* values available for the 'coderate' parameters (Lora only) */
+/* NOTE: arbitrary values */
+#define CR_UNDEFINED	0
+#define CR_LORA_4_5		0x01
+#define CR_LORA_4_6		0x02
+#define CR_LORA_4_7		0x03
+#define CR_LORA_4_8		0x04
+
+/* values available for the 'status' parameter */
+/* NOTE: values according to hardware specification */
+#define STAT_UNDEFINED	0x00
+#define STAT_NO_CRC		0x01
+#define STAT_CRC_BAD	0x11
+#define STAT_CRC_OK		0x10
+
+/* values available for the 'tx_mode' parameter */
+#define IMMEDIATE		0
+#define TIMESTAMPED		1
+#define ON_GPS			2
+//#define ON_EVENT		  3
+//#define GPS_DELAYED	  4
+//#define EVENT_DELAYED	  5
+
+/* values available for 'select' in the status function */
+#define	TX_STATUS		1
+#define	RX_STATUS		2
+
+/* status code for TX_STATUS */
+/* NOTE: arbitrary values */
+#define TX_STATUS_UNKNOWN	0
+#define	TX_OFF				1	/* TX modem disabled, it will ignore commands */
+#define TX_FREE				2	/* TX modem is free, ready to receive a command */
+#define TX_SCHEDULED		3	/* TX modem is loaded, ready to send the packet after an event and/or delay */
+#define TX_EMITTING			4	/* TX modem is emitting */
+
+/* status code for RX_STATUS */
+/* NOTE: arbitrary values */
+#define RX_STATUS_UNKNOWN	0
+#define RX_OFF				1	/* RX modem is disabled, it will ignore commands  */
+#define RX_ON				2	/* RX modem is receiving */
+#define RX_SUSPENDED		3	/* RX is suspended while a TX is ongoing */
+
+/* -------------------------------------------------------------------------- */
+/* --- PUBLIC TYPES --------------------------------------------------------- */
+
+/**
+@struct lgw_conf_rxrf_s
+@brief Configuration structure for a RF chain
+*/
+struct lgw_conf_rxrf_s {
+	bool		enable;		/*!> enable or disable that RF chain */
+	uint32_t	freq_hz;	/*!> center frequency of the radio in Hz */
+};
+
+/**
+@struct lgw_conf_rxif_s
+@brief Configuration structure for an IF chain
+*/
+struct lgw_conf_rxif_s {
+	bool		enable;		/*!> enable or disable that IF chain */
+	uint8_t		rf_chain;	/*!> to which RF chain is that IF chain associated */
+	int32_t		freq_hz;	/*!> center frequ of the IF chain, relative to RF chain frequency */
+	uint8_t		bandwidth;	/*!> RX bandwidth, 0 for default */
+	uint32_t	datarate;	/*!> RX datarate, 0 for default */
+};
+
+/**
+@struct lgw_pkt_rx_s
+@brief Structure containing the metadata of a packet that was received and a pointer to the payload
+*/
+struct lgw_pkt_rx_s {
+	uint8_t		if_chain;	/*!> by which IF chain was packet received */
+	uint8_t		status;		/*!> status of the received packet */
+	uint8_t		modulation; /*!> modulation used by the packet */
+	uint8_t		bandwidth;	/*!> modulation bandwidth (Lora only) */
+	uint16_t	datarate;	/*!> RX datarate of the packet */
+	uint8_t		coderate;	/*!> error-correcting code of the packet */
+	uint32_t	count_us;	/*!> internal gateway counter for timestamping, 1 microsecond resolution */
+	float		rssi;		/*!> average packet RSSI in dB */
+	float		snr;		/*!> average packet SNR, in dB (Lora only) */
+	float		snr_min;	/*!> minimum packet SNR, in dB (Lora only) */
+	float		snr_max;	/*!> maximum packet SNR, in dB (Lora only) */
+	uint16_t	crc;		/*!> CRC that was received in the payload */
+	uint16_t	size;		/*!> payload size in bytes */
+	uint8_t		payload[256]; /*!> buffer containing the payload */
+};
+
+/**
+@struct lgw_pkt_tx_s
+@brief Structure containing the configuration of a packet to send and a pointer to the payload
+*/
+struct lgw_pkt_tx_s {
+	uint32_t	freq_hz;	/*!> center frequency of TX */
+	uint8_t		tx_mode;	/*!> select on what event/time the TX is triggered */
+	uint32_t	count_us;	/*!> timestamp or delay in microseconds for TX trigger */
+	uint8_t		rf_chain;	/*!> through which RF chain will the packet be sent */
+	int8_t		rf_power;	/*!> TX power, in dBm */
+	uint8_t		modulation; /*!> modulation to use for the packet */
+	uint8_t		bandwidth;	/*!> modulation bandwidth (Lora only) */
+	bool		invert_pol;	/*!> invert signal polarity, for orthogonal downlinks (Lora only) */
+	uint8_t		f_dev;		/*!> frequency deviation, in kHz (FSK only) */
+	uint16_t	datarate;	/*!> TX datarate (baudrate for FSK) */
+	uint8_t		coderate;	/*!> error-correcting code of the packet (Lora only) */
+	uint16_t	preamble;	/*!> set the preamble length, 0 for default */
+	bool		no_crc;		/*!> if true, do not send a CRC in the packet */
+	bool		no_header;	/*!> if true, enable implicit header mode (Lora), fixed length (FSK) */
+	uint16_t	size;		/*!> payload size in bytes */
+	uint8_t		payload[256]; /*!> buffer containing the payload */
+};
+
+/* -------------------------------------------------------------------------- */
+/* --- PUBLIC FUNCTIONS PROTOTYPES ------------------------------------------ */
+
+/**
+@brief Configure an RF chain (must configure before start)
+@param rf_chain number of the RF chain to configure [0, LGW_RF_CHAIN_NB - 1]
+@param conf structure containing the configuration parameters
+@return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
+*/
+int lgw_rxrf_setconf(uint8_t rf_chain, struct lgw_conf_rxrf_s conf);
+
+/**
+@brief Configure an IF chain + modem (must configure before start)
+@param if_chain number of the IF chain + modem to configure [0, LGW_IF_CHAIN_NB - 1]
+@param conf structure containing the configuration parameters
+@return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
+*/
+int lgw_rxif_setconf(uint8_t if_chain, struct lgw_conf_rxif_s conf);
+
+/**
+@brief Connect to the Lora gateway, reset it and configure it according to previously set parameters
+@return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
+*/
+int lgw_start(void);
+
+/**
+@brief Stop the Lora gateway and disconnect it
+@return LGW_HAL_ERROR id the operation failed, LGW_HAL_SUCCESS else
+*/
+int lgw_stop(void);
+
+/**
+@brief A non-blocking function that will fetch up to 'max_pkt' packets from the Lora gateway FIFO and data buffer
+@param max_pkt maximum number of packet that must be retrieved (equal to the size of the array of struct)
+@param pkt_data pointer to an array of struct that will receive the packet metadata and payload pointers
+@return LGW_H