SatNOGS-COMMS: Building and flashing the firmware

Searching...

No Matches

Requirements

Before you start building the software your system should meet some requirements. In general the host system should have at least:

Git
CMake (>= 3.20)
C++17
GNU Make or Ninja
Zephyr SDK (>= 0.16)
west (Zephyr’s meta-tool)
Device Tree Compiler (dtc)
clang-format (>= 17.0)
protobuf-compiler (protoc)

Deprecated: Protocol buffers are deprecated and will be removed at the next major release of the firmware

Optional

Some optional tools that may also be useful.

openOCD (>= 0.11) (for testing and debugging)
jlink (for testing and debugging)

Build instructions

As the SatNOGS-COMMS firmware relies on the Zephyr-RTOS, most of the steps required to install all the necessary requirements and compile the project can be found at the Getting Started Guide of the Zephyr-RTOS.

To build the SatNOGS-COMMS firmware there are two choices provided by the software team:

Build a docker image that automatically downloads all of the dependencies and sets up the toolchain for you in a container.
Set everything up by hand in your native machine by following the provided instructions.

1. Using docker

Set up the development environment.

Build the Docker image to setup the development environment

Requirements:

Building. To build the docker image you should have:
- Packages: docker, docker-compose
Flashing (and debugging):
- docker should have access to your host's usb ports.

The environment is built using docker compose.

Docker scripts are inside contrib/docker directory, so before using docker compose, make sure you are already in that directory:

cd contrib/docker

Note: Some environment variables are needed to be passed as arguments in order for the environment to work properply. User id, group and username are used, so any files produced withing the container belong to the host user.

Export the needed environment variables:
export UID=$(id -u)

export GID=$(id -g)

export USER=$(id -un)

export REPO_HOST_PATH=$(git rev-parse --show-toplevel)
Build and start the container using docker compose:
docker compose up --build -d

Use of the environment

Note: Container's root password is: docker

Start a new bash process inside the container:
docker exec -it satnogs-comms-dev bash
Inside this container you can use west out of the box and build the code using west. Sample commands are presented at the end of this document.

Debugging:

This docker image is shipped with openOCD package installed. If you need to start a debugging session you can start the openOCD server from the repository's root directory with:
openocd --file openocd/openocd-jlink.cfg -c "bindto 0.0.0.0"

Then you can connect to it from host by using for example the Cortex-Debug plugin. Please refer to Development page for more.

2. Setting everything up natively.

Ensure you have every dependency downloaded and updated. For Ubuntu/Debian:

apt install -qy --no-install-recommends git cmake ninja-build gperf ccache dfu-util device-tree-compiler wget python3-venv python3-pip python3-setuptools python3-tk python3-wheel xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 doxygen graphviz

Download and setup zephyr-sdk (home directory is suggested):

wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/zephyr-sdk-0.16.8_linux-x86_64_minimal.tar.xz
tar xf zephyr-sdk-0.16.8_linux-x86_64_minimal.tar.xz
cd zephyr-sdk-0.16.8
./setup.sh -t arm-zephyr-eabi -h -c

Clone the repository with all the necessary submodules

Return to your workspace (e.g. $HOME), then run:

git clone --recurse-submodules https://gitlab.com/librespacefoundation/satnogs-comms/satnogs-comms-software-mcu.git

Enter the project's directory

cd satnogs-comms-software-mcu

Note: If you don’t already have the west tool installed, we suggest installing it inside a venv:
python3 -m venv .venv

source .venv/bin/activate

pip install west

Fetch the Zephyr-RTOS codebase at the specific version associated with the project using the west manifest file shipped with the project

west init -l .

Update west and install packages

west update -o=--depth=1 -n
west zephyr-export
west packages pip --install

Build the firmware using the west tool.

To build the firmware you have to know the hardware version of your board. For example for the version 0.3.2:

west build --board=satnogs_comms@0.3.3 -d build --pristine -o=-j$(nproc) -- -DEXTRA_CONF_FILE=boards/lsf/satnogs_comms/debug.conf -DBOARD_ROOT=$PWD

This will result to a basic, yet functional firmware. For further customization, especially on the available IO interfaces refer to Configuration and customization

Warning: These instructions are for reference only. The project is under development so things may change. You can always refer to project's Gitlab CI to find the latest working build procedure at any time.

Flashing

The project provides flashing capabilities utilizing the west flash command. Several runners are available including jlink, stm32cubeprogrammer and openocd covering the majority of the flashing probes.

Depending on the usage of Sysbuild (see BootloaderBootloader) you may also have to specify the domain (mcuboot or satnogs-comms) in order to flash the bootloader or the selected firmware slot.

For example the command:

west flash --runner openocd -- --config interface/jlink.cfg --config target/stm32h7x.cfg

will flash the firmware that was build without Sysbuild and with no bootloader support, uttilizing the jlink software and a supported flashing probe. On the other hand, the command:

west flash --domain mcuboot --runner openocd -- --config interface/jlink.cfg --config target/stm32h7x.cfg

will flash the bootloader, if the project has been built with Sysbuild. The corresponding command to flash the firmware with bootloader support would be the:

west flash --domain satnogs-comms --runner openocd -- --config interface/jlink.cfg --config target/stm32h7x.cfg