/ _____)             _              | |
( (____  _____ ____ _| |_ _____  ____| |__
 \____ \| ___ |    (_   _) ___ |/ ___)  _ \
 _____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
  (C)2020 Semtech

LoRa 2.4Ghz Gateway project

1. Core library: libloragw

This directory contains the sources of the library to build a gateway based on a Semtech LoRa 2.4GHz concentrator board (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 few basic tests programs that are used to test the different sub-modules of the library.

Please refer to the readme.md file located in the libloragw directory for more details.

2. Concentrator MCU firmware: mcu_bin

This directory contains the binary file to be flashed on the concentrator MCU. There is a version with debug information "dbg_xxx.bin" and a release version without those debug information "rlz_xxx.bin". Please refer to util_boot/readme.md for more information about how to flash it.

3. 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.

3.1. packet_forwarder

The packet forwarder is a program running on the host of a Lora gateway that forwards RF packets receive by the concentrator to a server through a IP/UDP link, and emits RF packets that are sent by the server.

((( Y )))
    |
    |
+- -|- - - - - - - - - - - - -+        xxxxxxxxxxxx          +--------+
|+--+-----------+     +------+|       xx x  x     xxx        |        |
||              |     |      ||      xx  Internet  xx        |        |
|| Concentrator |<----+ Host |<------xx     or    xx-------->|        |
||              | USB |      ||      xx  Intranet  xx        | Server |
|+--------------+     +------+|       xxxx   x   xxxx        |        |
|                             |           xxxxxxxx           |        |
|                             |                              |        |
|            Gateway          |                              +--------+
+- - - - - - - - - - - - - - -+

Uplink: radio packets received by the gateway, with metadata added by the gateway, forwarded to the server. Might also include gateway status.

Downlink: packets generated by the server, with additional metadata, to be transmitted by the gateway on the radio channel. Might also include configuration data for the gateway.

Please refer to the readme.md file located in the packet_forwarder directory for more details.

3.2. util_net_downlink

The downlink packet sender is a simple helper program listening on a single UDP port, responding to PUSH_DATA and PULL_DATA datagrams with proper ACK, and sending downlink JSON packets to the socket, with given frame parameters, at regular time interval. It is a network packet sender.

It can also be used as a UDP packet logger to store received uplinks in a local CSV file.

Please refer to the readme.md file located in the util_net_downlink directory for more details.

3.3. util_boot

This utility can be used to switch the concentrator in DFU mode in order to program its internal MCU. Please refer to the util_boot/readme.md to get information about how to use dfu-util for flashing the MCU with binaries provided in the mcu_bin directory.

3.4. util_chip_id

This utility configures the concentrator to be able to retrieve its EUI. It can then be used as a Gateway ID.

4. Compile and run instructions

All the libraries and test programs can be compiled and installed from the root directory of this project.

4.1. Clean and compile everything

make clean all

4.3. Cross-compile from a PC

• Add the path to the binaries of the compiler corresponding to the target platform to the PATH environment variable.
• set the ARCH environment variable to arm.
• set the CROSS_COMPILE environment variable to the prefix corresponding to the compiler for the target platform.

An example for a Raspberry Pi target:

• export PATH=[path]/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin
• export ARCH=arm
• export CROSS_COMPILE=arm-linux-gnueabihf-

Then, from the same console where the previous environment variables have been set, do:

make clean all

5. Third party libraries

This project relies on several third-party open source libraries, that can be found in the libtools directory.

• parson: a JSON parser (http://kgabis.github.com/parson/)
• tinymt32: a pseudo-random generator (only used for debug/test)

6. Helper scripts

6.1. tools/rpi_configure_gpio.sh

This script is to be used when using the gateway board on a Raspberry Pi through the adaptation board, in order to properly drive the MCU_RESET and MCU_BOOT0 pins.

7. Changelog

v1.1.0

Notes

• This intermediate release aims to fix the wrong naming issue for coding rate, and be aligned with the network servers which correcly use 4/8LI instead of 4/7LI.

Changes

• HAL: Fixed coding rate enum e_coding_rate for 4/8LI which was wrongly named 4/7LI. 4/7LI doesn't exist and was wrongly described in the sx1280 datasheet. The actual physical coding rate is 4/8LI.
• Packet Forwarder: Set uplink coding rate to "4/8LI" instead of "4/7LI" in the "rxpk" JSON frame, as it should be expected by the Network Server.
• Packet Forwarder: Accept both "4/7LI" and "4/8LI" as coding rate in the downlink request "txpk" JSON frame. The network server should use "4/8LI" but keep compatible with "4/7LI".
• net_downlink: Updated default and expected coding rate from 4/7LI to 4/8LI

v1.0.2

• Initial release for LoRa 2.4Ghz gateway

8. License

See the LICENSE.TXT file provided in the root directory of this project.

EOF