============================== Compiling LoRa Basics™ Station ============================== There are two ways to compile LoRa Basics™ Station for a specific hardware platform: 1. Compile directly on the target platform 2. 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 .. - ``doc``: Documentation files .. - ``platform``: Platform-specific files and scripts .. - ``regr-tests``: Regression tests .. - ``utils``: Additional utilities 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. .. code-block:: make 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: 1. 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: .. code-block:: shell 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: .. code-block:: shell make platform=corecell variant=std deps s-clean s-all 2. To compile a Station on a Raspberry Pi Linux system, use the following commands: .. code-block:: shell 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: .. code-block:: shell 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: .. code-block:: shell 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: .. code-block:: shell 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