Skip to content

Firmware Compilation

Experienced Users Only

Modification of the firmware should be done by experienced users only. Changes may result in dysfunctional firmware or may even lead to permanent hardware failure or damage.

If you only want to use the ahoi modem as-is, firmware compilation and modification are not required!

The ahoi modem is fully open-source. You may download the firmware sources from project's Git Repositories, modify and compile them. This requires the additional installation of the build toolchain, which is described below.

Operating System Support

In the following, we assume that you have a debian-based Linux (such as Ubuntu) running on your machine. If this is not the case, we recommend to either set up a Linux in a virtual machine or install a Linux via the MS Windows WSL (see External Links page).

Toolchain Installation

GNU Tools for ARM Embedded Processor

Compiler Version

The firmware has been developed and tested with version "15.2.Rel1" of the toolchain. We recommend to use this version. Newer versions may work, but it is possible that there might be small changes in the behavior.

The first step is to install the toolchain (compiler), namely the GNU Tools for ARM Embedded Processor. If you are an experienced Linux user, feel free to download and install from the link provided on the External Links page. For everyone else (or if you want to make sure that everything is hooked up correctly) follow this installation procedure.

Open a terminal, create a folder for the compiler and switch to it:

mkdir -p ~/.gcc-arm
cd ~/.gcc-arm

Next, we download and unpack the compiler, and we create an alias. The last step is for the case that, at some point, there is reason to install a different version of the compiler and switch to it easily.

export arch=$(test $(uname -s) = Darwin && echo darwin-)$(uname -m)
wget https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-$arch-arm-none-eabi.tar.xz
tar xfv arm-gnu-toolchain-15.2.rel1-$arch-arm-none-eabi.tar.xz
ln -s arm-gnu-toolchain-15.2.rel1-$arch-arm-none-eabi current

Finally, you need to add the executables of the compiler to the system's search path. Open the file ~/.bashrc using, e.g., nano ~/.bashrc and add the following line:

export PATH=$PATH:~/.gcc-arm/current/bin

Then, close the terminal and open a new one. This is required to make the previous change effective. Finally, we check that the compiler is found by the system and that its version matches our expectation. Typing

arm-none-eabi-gcc --version

should produce the following output:

arm-none-eabi-gcc (Arm GNU Toolchain 15.2.Rel1 (Build arm-15.86)) 15.2.1 20251203
Copyright (C) 2025 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Make

The next step is to install the make utils. In a Debian-based Linux, just type:

sudo apt install make build-essential

Firmware Compilation

Source Download

Clone the ahoi firmware repository using: 

git clone <URL>

Replace <URL> with the current address of the repository found on the page Git Repositories.

Configuration

Navigate into the subfolder src of the downloaded GIT repository in the previous step.

Copy the template file config.mk.dist to config.mk by typing

cp config.mk.dist config.mk

The newly created file config.mk is your local configuration file. Apply changes if applicable. The copy-and-modify procedure prevents pull-conflicts when updating your repository. However, updating to the newest release or a development branch from GIT may result in erroneous behavior, if the configuration template has been changed. Make sure to track such changes.

Building

The firmware is compiled via the command

make t=<target> [tx=<tx_board>]

in the subfolder src of your local copy of the firmware repository.

The following parameter values are currently supported:

  • Compilation target <target>:

    • stm: ahoi modem firmware image (default)
    • sim: Simulation Program for PC (without real modem hardware)

  • Transmitter board <tx_board> (optional, see Hardware Overview):

    • single: low-power transmitter TX
    • bridge: high-power transmitter TXB (default)

Compilation will produce the firmware image in different formats such as ahoi.bin and ahoi.hex in the subfolder build/<target>. It will also create temporary files. All of these can be deleted via 

make t=<target> clean

Known Bug: No Automatic Recompilation

If the configuration is changed, some modules are not automatically recompiled. We recommend to run make clean after changes to the configuration.

Flashing the Firmware

Your firmware image can be installed on a modem as explained in the Stock Firmware Installation documentation. If you have installed the build toolchain, you can exploit the following shortcut 

make t=stm [tx=<tx board>] program

Follow the instructions provided in the Stock Firmware Installation documentation to prepare your modem before and after firmware installation.