Compiling LoRa Basics™ Station

There are two ways to compile LoRa Basics™ Station for a specific hardware platform:

Compile directly on the target platform
Cross-compile for the target platform

Compiling on the target platform is only possible if sufficient resources are available on the platform, such as a Raspberry Pi. For other embedded gateways that have limited resources (e.g., Kerlink), cross-compiling is the only viable option.

Repository Structure

The Station repository has the following directory structure:

build-$platform-$variant: Generated directory for resulting binaries
deps: Required libraries
examples: Examples for station usage
pysys: Shared Python scripts for simulation and testing
src: Core source files
src-$platform: Platform-specific source files

Make Environment

Use the make utility to create a binary executable. The following files are relevant for the make environment.

makefile: The core rules for building the executable
makefile.s2core: Makefile rules for the core of the Station
setup.gmk: Main setup file for the make environment. This controls the configuration for different platforms
setup-$platform.gmk: Optional platform-specific rules and environment settings

Typically, the platform and its corresponding variant are specified as parameters for a make target. Based on these parameters, the build environment is set up according to the rules specified in setup.gmk or setup-$platform.gmk.

The following core make targets are available:

deps: Builds the required dependencies
s-all: Builds the Station binary, together with all required object files
s-clean: Cleans the object files and binaries related to the Station
clean: Cleans all Station objects and dependencies
super-clean: Cleans all Git repositories for the dependencies, as well as all Station objects and dependencies

Dependencies

LoRa Basics Station has the following third-party library dependencies:

mbed TLS == 2.6;
sx1301 libloragw == 5.01. For v1.5 & v2 Concentrator design.
sx1302 libloragw == 1.0.5. For Corecell Concentrator design.

Building a Station from source, requires

gcc >= 4.8.1 with support for C11 with GNU extensions;
GNU make
bash

In addition, git is used for source-code versioning and control.

Depending on the target platform, specific implementations of the libloragw library or additional libraries may be required. Dependencies are downloaded from online repositories during the build process, typically using git, and should be patched as required.

Preparing libloragw

Patching

By default, the libloragw library is downloaded from an online repository, depending on the specific platform. If the target platform requires modifications to the standard libloragw library, these can be added as a patch (e.g., deps/lgw/patch-$platform.patch).

Changing the Library

If the target platform requires a different libloragw library, this dependency also can be configured in the setup.gmk makefile configuration file.

The build environment requires a makefile which places the resulting libloragw archive and corresponding include files in the build-platform-variant/lib and the build-platform-variant/include directories.

TD=../..
include ${TD}/setup.gmk

TEKUI_LIB=${TD}/${BD}/lib/libtekui.a
TEKUI_INC=${TD}/${BD}/include/tekui

TEKUI_VERSION=3.5.6

ARTEFACTS = ${TEKUI_LIB} ${TEKUI_INC}

all: prepare ${ARTEFACTS}

prepare:
     @mkdir -p ${TD}/${BD}/include ${TD}/${BD}/lib

${TEKUI_LIB} : ${TEKUI_VERSION}/libsx1301ar/libsx1301ar.a
     cp $< $@

${TEKUI_INC} : ${TEKUI_VERSION}/libsx1301ar/api_inc
     cp -r $< $@-temp
     rm -rf $@
     mv $@-temp $@

clean super-clean:
     rm -rf ${ARTEFACTS}

.PHONY: prepare all clean super-clean

Compiling on Target

Compiling on the target platform requires installing a gcc compiler together with the make build tools on the target platform.

For example:

To compile a Station for the Corecell platform using a Raspberry Pi Linux system as host and Semtech SX1302CxxxGW1 as Concentrator, use the following commands:

make platform=corecell variant=std

To compile the required dependencies and cleanly re-compile a Station on a Raspberry Pi Linux system, use these commands:

make platform=corecell variant=std deps s-clean s-all

To compile a Station on a Raspberry Pi Linux system, use the following commands:

make platform=rpi variant=std

To compile the required dependencies and cleanly re-compile a Station on a Raspberry Pi Linux system, use these commands:

make platform=rpi variant=std deps s-clean s-all

See the setup.gmk makefile for a list of supported platforms and their respective configurations.

Cross-Compiling for a Specific Target

When cross-compiling for a specific target platform, you need a matching cross-compiler toolchain. The make rules will select the toolchain based on the PLATFORM. The toolchain therefore must be installed in the user’s $HOME directory, following the naming convention toolchain-platform.

For example, to cross-compile for a Kerlink gateway, use the following commands:

make platform=kerlink variant=std

Note: For Kerlink, the toolchain_x86_64_v3.3 is required.

Adding a New Platform

To add a new target platform with newcool as the platform identifier, the following entries must be added to the setup.gmk file. In most cases, these entries are very similar to the existing platforms. You can use these for inspiration:

ARCH.newcool: Specifies the cross-compiler prefix;
CFG.newcool: Defines the underlying operating system, the radio abstraction layer for the libloragw library, and other configurations such as LEDS and so on;
DEPS.newcool: Specifies the library dependencies. At a minimum these are the libloragw library (with potentially special variants) and mbed TLS;
CFLAGS.newcool: Here, special compiler flags can be set if required;
LIBS.newcool: Define shared libraries to link against.

To simply compile for the new target platform, you can use these commands:

cd $STATION_REPO
make platform=newcool variant=std

Porting Checklist

While porting a Station to a new platform, consider the following:

1. Prepare
   Determine the Gateway Reference Architecture: lgw1, lgw2, smtcpico
   Create a platform-specific lgw patch
   Determine required hardware capabilities: GPS/PPS, fine-timestamping, multi-board
   Re-define platform-specific default-parameters in s2conf.h
   Create station.conf, reflecting the required hardware capabilities and parameters (TX LUT, RSSI offset, etc.)

2. Cross-Compile
   Adapt setup.gmk for new $platform
   Integrate toolchain into build environment
   Check that no errors or warnings are shown during compilation

3. Integrate
   Ensure proper back-haul network management (3G, Ethernet, DHCP, DNS, etc)
   Installation
      Create system startup scripts - initd, systemd
      Create installation and upgrade packages if applicable (e.g. opkg, dpkg, installer/upgrade scripts, etc.)
      Facilitate personalization/provisioning (e.g. generate cups-boot.{uri,crt,key,trust}, sig-0.key)
   Create a radio reset script
   (Optional) Create a health reporting script

4. Test
   Check that the Station properly derives the gateway ID
   Test that network requirements are satisfied (DHCP, DNS, Firewall rules)
   Test all scripting: installer, startup after reboot, radio reset, health reporting, etc.
   Test the Station's hardware capabilities
      Radio (low-level tests to be performed using HAL testing utilities)
      GPS (NMEA/UBX parsing, if position resolution is required)
      PPS acquisition
      SPI speed and transaction setup delays
      Clock drifts
   Conduct end-to-end testing with network server and end-device
   Conduct end-to-end testing to update the Station using the CUPS protocol
   Fine-tune the default parameters in s2conf.h for optimal performance