v1.2.0

- Added feature: new GPS module in the library for synchronization
- Removed feature: no more missed deadline detection in TX because of incompatibility with GPS
- Added documentation for GPS and legal notice
- Added flags in Makefiles for easier cross-compilation

README

@@ -50,5 +50,27 @@ contain little information, on no protocol (ie. MAC address) information but
 can be used to assess the functionality of a gateway downlink using other
 gateways as receivers.
 
+3. Legal notice
+----------------
+
+The information presented in this project documentation does not form part of 
+any quotation or contract, is believed to be accurate and reliable and may be 
+changed without notice. No liability will be accepted by the publisher for any 
+consequence of its use. Publication thereof does not convey nor imply any 
+license under patent or other industrial or intellectual property rights. 
+Semtech assumes no responsibility or liability whatsoever for any failure or 
+unexpected operation resulting from misuse, neglect improper installation, 
+repair or improper handling or unusual physical or electrical stress 
+including, but not limited to, exposure to parameters beyond the specified 
+maximum ratings or operation outside the specified range. 
+
+SEMTECH PRODUCTS ARE NOT DESIGNED, INTENDED, AUTHORIZED OR WARRANTED TO BE 
+SUITABLE FOR USE IN LIFE-SUPPORT APPLICATIONS, DEVICES OR SYSTEMS OR OTHER 
+CRITICAL APPLICATIONS. INCLUSION OF SEMTECH PRODUCTS IN SUCH APPLICATIONS IS 
+UNDERSTOOD TO BE UNDERTAKEN SOLELY AT THE CUSTOMER�S OWN RISK. Should a 
+customer purchase or use Semtech products for any such unauthorized 
+application, the customer shall indemnify and hold Semtech and its officers, 
+employees, subsidiaries, affiliates, and distributors harmless against all 
+claims, costs damages and attorney fees which could arise.
 
 *EOF*

libloragw/Makefile

@@ -17,7 +17,7 @@ endif
 
 # general build targets
 
-all: libloragw.a test_loragw_spi test_loragw_reg test_loragw_hal
+all: libloragw.a test_loragw_spi test_loragw_reg test_loragw_hal test_loragw_gps
 
 clean:
 	rm -f *.a
@@ -43,8 +43,8 @@ endif
 
 # static library
 
-libloragw.a: obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
-	$(CROSS_COMPILE)ar rcs libloragw.a obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+libloragw.a: obj/loragw_hal.o obj/loragw_gps.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+	$(CROSS_COMPILE)ar rcs libloragw.a obj/loragw_hal.o obj/loragw_gps.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
 
 # library module target
 
@@ -62,17 +62,23 @@ endif
 obj/loragw_reg.o: .conf_ok src/loragw_reg.c inc/loragw_reg.h inc/loragw_spi.h
 	$(CROSS_COMPILE)$(CC) -c $(C99FLAGS) src/loragw_reg.c -o obj/loragw_reg.o $(FLAG_REG)
 
-obj/loragw_hal.o: .conf_ok VERSION 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
+obj/loragw_hal.o: .conf_ok src/loragw_hal.c inc/loragw_hal.h inc/loragw_reg.h inc/loragw_aux.h VERSION src/arb_fw.var src/agc_fw.var
 	$(CROSS_COMPILE)$(CC) -c $(C99FLAGS) src/loragw_hal.c -o obj/loragw_hal.o -D LGW_PHY="\"$(LGW_PHY)\"" $(FLAG_HAL)
 
+obj/loragw_gps.o: .conf_ok src/loragw_gps.c inc/loragw_gps.h
+	$(CROSS_COMPILE)$(CC) -c $(C99FLAGS) src/loragw_gps.c -o obj/loragw_gps.o $(FLAG_GPS)
+
 # test programs
 
 test_loragw_spi: tst/test_loragw_spi.c obj/loragw_spi.o
 	$(CROSS_COMPILE)$(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
 	$(CROSS_COMPILE)$(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
 	$(CROSS_COMPILE)$(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)
 
+test_loragw_gps: tst/test_loragw_gps.c obj/loragw_gps.o obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o
+	$(CROSS_COMPILE)$(CC) $(C99FLAGS) tst/test_loragw_gps.c obj/loragw_gps.o obj/loragw_hal.o obj/loragw_reg.o obj/loragw_spi.o obj/loragw_aux.o -o test_loragw_gps $(LDFLAGS)
+

libloragw/README

@@ -29,27 +29,4 @@ Contain library C sources.
 Contain the C sources for test programs to validate SPI link, register access 
 and hardware functionality.
 
-2. Legal notice
-----------------
-
-The information presented in this project documentation does not form part of 
-any quotation or contract, is believed to be accurate and reliable and may be 
-changed without notice. No liability will be accepted by the publisher for any 
-consequence of its use. Publication thereof does not convey nor imply any 
-license under patent or other industrial or intellectual property rights. 
-Semtech assumes no responsibility or liability whatsoever for any failure or 
-unexpected operation resulting from misuse, neglect improper installation, 
-repair or improper handling or unusual physical or electrical stress 
-including, but not limited to, exposure to parameters beyond the specified 
-maximum ratings or operation outside the specified range. 
-
-SEMTECH PRODUCTS ARE NOT DESIGNED, INTENDED, AUTHORIZED OR WARRANTED TO BE 
-SUITABLE FOR USE IN LIFE-SUPPORT APPLICATIONS, DEVICES OR SYSTEMS OR OTHER 
-CRITICAL APPLICATIONS. INCLUSION OF SEMTECH PRODUCTS IN SUCH APPLICATIONS IS 
-UNDERSTOOD TO BE UNDERTAKEN SOLELY AT THE CUSTOMER�S OWN RISK. Should a 
-customer purchase or use Semtech products for any such unauthorized 
-application, the customer shall indemnify and hold Semtech and its officers, 
-employees, subsidiaries, affiliates, and distributors harmless against all 
-claims, costs damages and attorney fees which could arise.
-
 *EOF*

libloragw/VERSION

@@ -1,8 +1,8 @@
 /* Software library version: */
-#define VERSION_LIBRARY			"1.1.0"
+#define VERSION_LIBRARY			"1.2.0"
 
 /* API version */
-#define VERSION_API				"1.0"
+#define VERSION_API				"1"
 
 /* Accepted value of CHIP_ID (SPI registers) must match reg default value in loragw_reg.c */
 #define ACCEPT_CHIP_ID			"1"

libloragw/doc/CHANGELOG.TXT

@@ -1,6 +1,14 @@
 Lora Gateway HAL changelog
 ==========================
 
+ v1.2.0
+---------------------
+
+ * Added feature: new GPS module in the library for synchronization
+ * Removed feature: no more missed deadline detection in TX because of incompatibility with GPS
+ * Added documentation for GPS and legal notice
+ * Added flags in Makefiles for easier cross-compilation
+
  v1.1.0
 ---------------------
 

libloragw/doc/MANUAL.TXT

@@ -22,14 +22,15 @@ used to send and receive packets wirelessly using Lora or FSK modulations.
 2. Components of the library
 ----------------------------
 
-The library is composed of 4 modules:
+The library is composed of 5 modules:
 
 * loragw_hal
 * loragw_reg
 * loragw_spi
 * loragw_aux
+* loragw_gps
 
-The library also contains 3 test program to demonstrate code use and check
+The library also contains 4 test programs to demonstrate code use and check
 functionality.
 
 ### 2.1. loragw_hal ###
@@ -113,6 +114,33 @@ 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.
 
+### 2.5. loragw_gps ###
+
+This module contains functions to synchronize the concentrator internal 
+counter with an absolute time reference, in our case a GPS satellite receiver.
+
+The internal concentrator counter is used to timestamp incoming packets and to 
+triggers outgoing packets with a microsecond accuracy.
+In some cases, it might be useful to be able to transform that internal 
+timestamp (that is independent for each concentrator running in a typical 
+networked system) into an absolute UTC time.
+
+In a typical implementation a GPS specific thread will be called, doing the
+following things after opening the serial port:
+
+* blocking reads on the serial port (using system read() function)
+* parse NMEA sentences (using lgw_parse_nmea)
+
+And each time an RMC sentence has been received:
+* get the concentrator timestamp (using lgw_get_trigcnt, mutex needed to 
+  protect access to the concentrator)
+* get the UTC time contained in the NMEA sentence (using lgw_gps_get)
+* call the lgw_gps_sync function (use mutex to protect the time reference that 
+  should be a global shared variable).
+
+Then, in other threads, you can simply used that continuously adjusted time 
+reference to convert internal timestamps to UTC time (using lgw_cnt2utc) or 
+the other way around (using lgw_utc2cnt).
 
 3. Software dependencies
 ------------------------
@@ -167,6 +195,33 @@ 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
 
+### 4.3. GPS receiver (or other GNSS system) ###
+
+To use the GPS module of the library, the host must be connected to a GPS 
+receiver via a serial link (or an equivalent receiver using a different 
+satellite constellation).
+The serial link must appear as a "tty" device in the /dev/ directory, and the 
+user launching the program must have the proper system rights to read and 
+write on that device.
+Use `chmod a+rw` to allow all users to access that specific tty device, or use
+sudo to run all your programs (eg. `sudo ./test_loragw_gps`).
+
+In the current revision, the library only reads data from the serial port, 
+expecting to receive NMEA frames that are generally sent by GPS receivers as 
+soon as they are powered up.
+
+The GPS receiver __MUST__ send RMC NMEA sentences (starting with "$G<any 
+character>RMC") shortly after sending a PPS pulse on to allow internal 
+concentrator timestamps to be converted to absolute UTC time.
+If the GPS receiver sends a GGA sentence, the gateway 3D position will also be 
+available.
+
+The PPS pulse must be sent to the pin 22 of connector CONN400 on the Semtech 
+FPGA-based nano-concentrator board. Ground is available on pins 2 and 12 of 
+the same connector.
+The pin is loaded by an FPGA internal pull-down, and the signal level coming 
+in the FPGA must be 3.3V.
+Timing is captured on the rising edge of the PPS signal.
 
 5. Usage
 --------

libloragw/inc/loragw_aux.h

@@ -7,7 +7,7 @@
     ©2013 Semtech-Cycleo
 
 Description:
-	Lora gateway auxiliary functions
+	Lora gateway library common auxiliary functions
 
 License: Revised BSD License, see LICENSE.TXT file include in the project
 Maintainer: Sylvain Miermont