diff options
Diffstat (limited to 'libloragw/doc')
| -rw-r--r-- | libloragw/doc/99-libftdi.rules | 8 | ||||
| -rw-r--r-- | libloragw/doc/CHANGELOG.TXT | 35 | ||||
| -rw-r--r-- | libloragw/doc/INSTALL_FTDI.TXT | 46 | ||||
| -rw-r--r-- | libloragw/doc/LICENSE.TXT | 8 | ||||
| -rw-r--r-- | libloragw/doc/MANUAL.TXT | 232 |
5 files changed, 329 insertions, 0 deletions
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 |