diff options
Diffstat (limited to 'libloragw/doc')
| -rw-r--r-- | libloragw/doc/99-libftdi.rules | 8 | ||||
| -rw-r--r-- | libloragw/doc/CHANGELOG.TXT | 80 | ||||
| -rw-r--r-- | libloragw/doc/INSTALL_FTDI.TXT | 46 | ||||
| -rw-r--r-- | libloragw/doc/LICENSE.TXT | 24 | ||||
| -rw-r--r-- | libloragw/doc/MANUAL.TXT | 287 |
5 files changed, 0 insertions, 445 deletions
diff --git a/libloragw/doc/99-libftdi.rules b/libloragw/doc/99-libftdi.rules deleted file mode 100644 index 8487413..0000000 --- a/libloragw/doc/99-libftdi.rules +++ /dev/null @@ -1,8 +0,0 @@ -# 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 deleted file mode 100644 index a03e7e0..0000000 --- a/libloragw/doc/CHANGELOG.TXT +++ /dev/null @@ -1,80 +0,0 @@ -Lora Gateway HAL changelog -========================== - - 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 24 dBm - * 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 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 deleted file mode 100644 index d26ad4b..0000000 --- a/libloragw/doc/INSTALL_FTDI.TXT +++ /dev/null @@ -1,46 +0,0 @@ -# / _____) _ | | -# ( (____ _____ ____ _| |_ _____ ____| |__ -# \____ \| ___ | (_ _) ___ |/ ___) _ \ -# _____) ) ____| | | || |_| ____( (___| | | | -# (______/|_____)_|_|_| \__)_____)\____)_| |_| -# ©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 deleted file mode 100644 index ff287f3..0000000 --- a/libloragw/doc/LICENSE.TXT +++ /dev/null @@ -1,24 +0,0 @@ -Copyright (c) 2013, SEMTECH S.A. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of the Semtech corporation nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/libloragw/doc/MANUAL.TXT b/libloragw/doc/MANUAL.TXT deleted file mode 100644 index 7fdefeb..0000000 --- a/libloragw/doc/MANUAL.TXT +++ /dev/null @@ -1,287 +0,0 @@ - / _____) _ | | - ( (____ _____ ____ _| |_ _____ ____| |__ - \____ \| ___ | (_ _) ___ |/ ___) _ \ - _____) ) ____| | | || |_| ____( (___| | | | - (______/|_____)_|_|_| \__)_____)\____)_| |_| - ©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 5 modules: - -* loragw_hal -* loragw_reg -* loragw_spi -* loragw_aux -* loragw_gps - -The library also contains 4 test programs 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. - -### 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 ------------------------- - -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 - -### 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 --------- - -### 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 |