Initial Commit

1 files changed, 410 insertions, 0 deletions

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..cdfd8d1
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,410 @@
+	 / _____)             _              | |    
+	( (____  _____ ____ _| |_ _____  ____| |__  
+	 \____ \| ___ |    (_   _) ___ |/ ___)  _ \ 
+	 _____) ) ____| | | || |_| ____( (___| | | |
+	(______/|_____)_|_|_| \__)_____)\____)_| |_|
+	  (C)2013 Semtech-Cycleo
+
+LoRa Gateway project
+=====================
+
+1. Core library: libloragw
+---------------------------
+
+This directory contains the sources of the library to build a gateway based on 
+a Semtech LoRa multi-channel RF receiver (a.k.a. concentrator).
+Once compiled all the code is contained in the libloragw.a file that will be 
+statically linked (ie. integrated in the final executable).
+
+The library also comes with a bunch of basic tests programs that are used to 
+test the different sub-modules of the library.
+
+2. Helper programs
+-------------------
+
+Those programs are included in the project to provide examples on how to use 
+the HAL library, and to help the system builder test different parts of it.
+
+### 2.1. util_pkt_logger ###
+
+This software is used to set up a LoRa concentrator using a JSON configuration
+file and then record all the packets received in a log file, indefinitely, until
+the user stops the application.
+
+### 2.2. util_spi_stress ###
+
+This software is used to check the reliability of the link between the host
+platform (on which the program is run) and the LoRa concentrator register file
+that is the interface through which all interaction with the LoRa concentrator
+happens.
+
+### 2.3. util_tx_test ###
+
+This software is used to send test packets with a LoRa concentrator. The packets
+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.
+
+### 2.4. util_tx_continuous ###
+
+This software is used to set LoRa concentrator in Tx continuous mode,
+for spectral measurement.
+
+### 2.5. util_spectral_scan ###
+
+This software is used to scan the spectral band in background, where the LoRa
+gateway operates.
+
+### 2.6. util_lbt_test ###
+
+This software is used to test "Listen-Before-Talk" channels timestamps.
+
+3. Helper scripts
+-----------------
+
+### 3.1. reset_lgw.sh
+
+This script must be launched on IoT Start Kit platform to reset concentrator
+chip through GPIO, before starting any application using the concentrator.
+
+4. Changelog
+-------------
+
+### v5.0.1 ###
+
+* HAL: Reworked the way the TX start delay is calculated, taking into account
+the delay introduced by TX notch filter (when enabled) and the delay linked to
+signal bandwidth separately.
+
+### v5.0.0 ###
+
+* HAL: Changed GPS module to get native GPS time (monotonic, no leap second).
+**WARNING**: The native GPS time is not given in standard NMEA messages, so we
+get it from a proprietary message of the GPS module used on gateway reference
+design, u-blox 7. If you are not using the same GPS module, you may have to
+update the lgw_parse_ubx() function.
+* HAL: Added lgw_cnt2gps() and lgw_gps2cnt() functions for SX1301<->GPS time
+conversion.
+* HAL: Changed serial port configuration for GPS to properly handle binary
+messages (UBX).
+* HAL: Added a lgw_gps_disable() function to restore serial configuration as
+it was before HAL initialization.
+* HAL: Fixed packet time on air calculation using the actual packet preamble
+size.
+* HAL: Adjusted TX_START_DELAY based on the board reference design to ensure
+that a packet is sent exactly at 1500µs after the TX trigger (TIMESTAMP or PPS),
+with a tolerance of +/- 1µs. This is mandatory to comply with LoRaWAN
+specification for Class-B beaconing precise timing.
+**WARNING**: This release provides tx start delay values to be used for Semtech
+reference designs AP1 and AP2. The HAL automatically detects the board version
+by detecting a FPGA or not. If you are using a different reference design or
+a different FPGA binary version than the one provided with this release, the
+value to be used for TX start delay may be different.
+
+### v4.1.3 ###
+
+* HAL: Reference clock frequency error improvement: The lora_gateway HAL has
+been updated (3 registers changed) to improve the performance of all gateways
+based on SX130x. The fix greatly improves the reception of packet at SF12, when
+the frequency offset of the incoming packet is large (mostly below -20ppm of
+frequency offset).
+
+WARNING: Systems which do not have the patch will be more prone to packet loss
+over time, when the crystals of the end-devices will be ageing and have more
+frequency offset.
+
+### v4.1.2 ###
+
+* HAL: Changed configuration of IQ polarity of FPGA for TX to comply with FPGA
+version greater than v27. (Only required for AP2 Semtech reference design)
+* HAL: Updated default LoRa preamble size according to LoRaWAN spec.
+
+### v4.1.1 ###
+
+* HAL: Fixed bug in "Listen-Before-Talk" which was preventing from configuring
+the Scan Time to 5ms.
+* MISC: Added GPIO number to reset_lgw.sh command arguments.
+
+### v4.1.0 ###
+
+* HAL: Reworked "Listen-Before-Talk" feature to have more flexibility to define
+LBT channels frequency, and to be able to have spectral scan running in parallel
+* HAL: Updated lgw_time_on_air() function for FSK packets
+* HAL: Disabled GPS UART input being re-echoed as output to avoid sending wrong
+commands to GPS module
+* HAL: Fixed IF frequency configuration check issue for channel bandwidths 250K
+and 500HKz.
+* FPGA: Updated to v31 for new LBT and spectral scan design.
+* util_spectral_scan: updated to match new spectral scan FPGA sequence
+* util_lbt_test: updated to match LBT rework
+
+Note: The provided LBT feature has been validated for Japan only, and supports
+8 downlink channels maximum.
+
+### v4.0.1 ###
+
+* HAL: SX1301AP2: Only FPGA v27 is supported, removed (v18,v19) from the list
+        of supported FPGA images.
+
+WARNING: If you are using a Semtech SX1301AP2 ref design (GW1.5), the FPGA must
+be reprogrammed with one of the images provided with this release (fpga/ dir).
+
+### v4.0.0 ###
+
+* HAL: Added "Listen-Before-Talk" support for Semtech SX1301AP2 Ref Design.
+       A description of the feature implementation can be found in
+       libloragw/readme.md.
+* HAL: Updated FSK RSSI calculation for better linearization
+* util_lbt_test: New utility provided for basic "Listen-Before-Talk" testing.
+* util_tx_test: Extended to configure and test "LBT" through the HAL.
+* Added a reset_lgw.sh script to be used with IoT Starter Kit (v1.0) to reset
+the concentrator through the HOST GPIO pin.
+
+### v3.2.1 ###
+
+* HAL: Fixed downlink support for SX1301AP2 reference design: soft reset of the
+FPGA was missing for proper IQ inversion configuration.
+* HAL: Added support for several versions of FPGA (currently v18 and v19)
+* HAL: Reduced radio TX PLL bandwidth to reduce the noise level.
+* util_tx_test: Added FSK support and added minimal TX gain LUT.
+* util_spectral_scan: Removed FPGA soft reset, now done by the HAL.
+* util_tx_continous: reworked to use HAL functions instead of 'manual' config,
+and use same SX1301 calibration firmware as the HAL.
+* Updated all makefiles to handle the creation of obj directory when necessary.
+* Change cs_change usage policy in SPI module to let the driver handle the chip
+select.
+
+### v3.2.0 ###
+
+* Added support for SX1301AP2 reference design (with FPGA and additional
+SX127x). When a FPGA is detected at startup, the HAL automatically adapts SPI
+communication requests (using SPI header or not).
+* Added util_spectral_scan diagnostic tool to scan the spectral band in
+background, where the LoRa gateway operates. (can only be used with SX1301AP2
+or similar design). By default it uses the same SPI device as the one used by
+the HAL, but it can be changed depending on the hardware architecture on which
+it is used by updating the SPI_DEV_PATH constant defined in file
+util_spectral_scan/src/loragw_fpga_spi.c.
+Note: when using same SPI device from 2 applications, we rely on the host SPI
+driver and OS to properly handle concurrent SPI requests. It has been tested on
+Raspberry Pi / Raspbian with spi_bcm2708 driver.* Removed SPI FTDI support due
+to lack of performances to properly handle heavy packet traffic. Only native
+SPI usage is recommended.
+* HAL: added a check that SX1301 firmwares have been properly loaded at startup.
+
+### v3.1.0 ###
+
+* Removed GPIO module from HAL, that was specific to IoT Starter Kit platform.
+GPIO configuration will be done from application script instead.
+* Removed CFG_BRD configuration from library.cfg, not needed anymore
+
+### v3.0.2 ###
+
+* Bugfix: Fixed frequency calculation on uplinks: lgw_receive() function was
+using a variable to calculate the frequency before it was initialized with
+correct value. 
+* Bugfix: util_pkt_logger crashed when no gateway_ID is not defined in
+global_conf.json
+
+### v3.0.1 ###
+
+* Bufgix: Fixed util_tx_continuous compilation issue, by adding empty obj
+directory
+* Bugfix: Fixed HAL compilation issue for CFG_SPI=ftdi, removed dependency on
+loragw_gpio in this case
+
+### v3.0.0 ###
+
+* Added new HAL function lgw_board_setconf() to configure board/concentrator
+specific parameters: network type (LoRa public or private), concentrator clock
+source. Note: those parameters are not any more set from the library.cfg file
+configuration (CFG_NET, CFG_BRD),
+and should be passed at initialization by the application.
+* Added new HAL function lgw_txgain_setconf() to configure concentrator TX gain
+table. It can now be dynamically set by the application at initialization time.
+* Changed HAL function lgw_rxrf_setconf(), it will now also configure the radio
+type (CFG_RADIO has been removed from library.cfg), the RSSI offset to be used
+for this radio and if TX is enabled or not on this radio.
+* Added support of IoT Starter Kit platform, which is now the default board.
+* Added util_tx_continuous utility for gateway TX power calibration and
+spectral emission measurements/qualification.
+* Removed CFG_BAND configuration from library.cfg. Band configuration is done
+by application and passed dynamically at initialization time.
+* Updated makefiles to allow cross compilation from environment variable (ARCH,
+CROSS_COMPILE).
+
+** WARNING: **
+** Known issue: a problem with carrier leakage calibration has been seen on
+433MHz boards. **
+
+### v2.0.0 ###
+
+* Added support for Kerlink 868 27dBm gateway
+* Updated global_conf.eu868.json (in packet logger) to new LoRaWAN frequency
+plan
+* Added version numbers to AGC, arbiter and calibration firmware (those
+versions are checked at startup)
+* Added test_loragw_cal to test radio calibrations
+* Fixed minor bug in error coverage in register read/write functions
+
+/!\ warning: Kerlink 868 27dBm gateway includes a FPGA that MUST be programmed
+before running any application
+
+### v1.7.0 ###
+
+* Added TX 'start delay' compensation for timestamp mode (fix time window
+alignment issue at low SF and/or high BW)
+* Added adaptive narrowband/wideband TX filtering for LoRa
+* Added a command-line option to set CR in util_tx_test
+* Added notes for TX 'start delay' in immediate and triggered mode
+
+/!\ warning: due to start delay compensation being implemented, TX that were 
+previously 1.5ms late will be sent on time. At low datarate, this is not an 
+issue. At high LoRa data rate (and FSK) you might have to adjust your timing.
+
+### v1.6.0 ###
+
+* Fixed bug with 250kHz and 500 kHz TX filtering
+* Adjusted FSK timestamp calibration in RX for accurate RX/TX alignment
+* Added lgw_abort_tx() function to stop a TX at any time (scheduled or ongoing)
+* Added support for user-settable FSK sync word (same for RX and TX)
+* Added support for the Chinese 780 MHz band
+* Added support for Kerlink 433 gateway
+* Added support for Cisco 433, 470 & 780 MHz concentrators boards
+
+### v1.5.0 ###
+
+* Adding option to isolate public LoRa MAC networks at PHY level.
+
+### v1.4.1 ###
+
+* Enabling support for FSK per LoRa MAC specification
+* Adjusting TX and RX calibration set on 868 reference board
+* Added specific RX/TX calibration set for Kerlink 868 "IoT station" gateway
+* Changed default SPI port for native driver to Kerlink SPI device number
+
+### v1.4.0 ###
+
+* Added calibration routine to optimize RF performance
+* Added support for SX1301 433 MHz reference board
+* Improved AGC firmware
+* Improved RSSI accuracy
+* Improved utilities Makefile
+
+### v1.3.0 ###
+
+* Added TX power management.
+* Added full support for SX1301 reference board.
+* Changed build system with configuration for multiple chip/radio/band support.
+* SX125x bandwidth set to 1MHz by default (was 800 kHz).
+* Solved warnings with 64b integer printf when compiling on x86_64.
+* Renamed helper programs to reduce the concentrator vs. gateway confusion.
+
+### v1.2.2 ###
+
+* Added a GPIO toggle on the FTDI SPI module to reset the SX1301 board.
+
+### v1.2.1 ###
+
+* Fixed 'floating point exception' crash when concentrator returned a packet
+with SF=0 (CRC error on LoRa header).
+* Fixed buggy timezone handling.
+
+### 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 ###
+
+* Fixed bug 'no TX on radio B' (rfch 1).
+* Added feature: concentrator processing delay compensation in the receive()
+function for accurate 'end of packet' even timestamping.
+* Added feature: TX 'start delay' compensation in the send() function to emit
+packet exactly on target timestamp.
+* Added feature: timestamp counter verification in send() function, return an
+error if scheduling was too late.
+* Switched license to 'Revised BSD'.
+
+### v1.0.0 (from beta 8) ###
+
+* Switched FTDI as default SPI phy layer in library.cfg.
+* Fixed a bug in TX power control; still only two TW power available, 14 and
+24dBm.
+* Changed library directory name from loragw_hal to libloragw to follow usual
+conventions.
+
+### Beta 8 (from beta 7) ###
+
+* API: lgw_receive now return info on RX frequency and RF path for each packet
+(no need to keep track of RF/IF settings).
+* Unified some portion of the code with the 470 MHz variant of the HAL (use
+SX1255 radios instead of SX1257).
+* Improved AGC and ARB firmwares.
+* Adding -Wall -Wextra for compilation, fixing all the new warnings for cleaner
+code.
+* Fixed bugs in handling of FSK datarate.
+* test_loragw_hal now dumps the content of all LoRa registers after
+configuration in reg_dump.log.
+
+### 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 concentrator).
+* 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 ###
+
+Private 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.
+* Added 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.
+
+5. 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*