Compiling Station

There are two ways to compile Station for a specific hardware platform: (1) Compile directly on the target platform, or (2) Cross-compile for the target platform. Compiling on the target platform is only possible if sufficient resources are available on the platform like, for example, on a Raspberry Pi. For other embedded gateways with limited resources (e.g., Kerlink), cross-compiling is the only viable way.

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

For creating a binary executable, the make utility is used. 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, which 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 setup according to the rules specified in setup.gmk or setup-$platform.gmk.

The following core make targets are available:

  • deps: To build the required dependencies;
  • s-all: To build the Station binary together with all required object files;
  • s-clean: To clean the object files and binaries related to the Station;
  • clean: To clean all Station objects and dependencies;
  • super-clean: To clean also all git repositories for the dependencies.

Dependencies

Station has the following third party library dependencies:

  • mbed TLS == 2.6;
  • libloragw == 5.01.

Building 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 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).

Different 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 build-platform-variant/include directories. Such an example makefile is the following:

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 Station on a Raspberry-Pi Linux system, the following commands MAY be used:

cd $STATION_REPO
make platform=rpi variant=std

For example, to compile the required dependencies and a clean re-compile of Station on a Raspberry-Pi Linux system, the following commands MAY be used:

cd $STATION_REPO
make platform=linux 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 Target

For cross-compilation for a specific target platform, a matching cross-compiler toolchain is required. The make rules will select the toolchain based on the PLATFORM. The toolchain therefore MUST be installed in the $HOME directory of the user following the naming convention toolchain-platform.

For example, to cross-compile for a Kerlink gateway, the following commands MAY be used:

cd $STATION_REPO
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 platform identifier, the following entries must be added to the setup.gmk file. In most cases, these entries are very similar to existing platforms, which MAY be used 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 configuration 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 compile for the new target platform simply, the following commands MAY be used:

cd $STATION_REPO
make platform=newcool variant=std