From 7c383be1542368f2601015d9fc2a417197677677 Mon Sep 17 00:00:00 2001 From: Harsh Sharma <92harshsharma@gmail.com> Date: Wed, 13 Jun 2018 13:24:54 -0500 Subject: Initial Commit --- readme.md | 410 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 readme.md (limited to 'readme.md') 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* -- cgit v1.2.3