Application Development

Workflow to build and install an app on AuterionOS

Only install apps from trusted sources

Make sure to have right safety precautions when testing apps Apps can have the possibility to deeply interact with the system. Malfunctioning apps can have flight-safety critical implications to the operation of the aircraft.

You need to be an Auterion OEM or part of the App Developer program in order to distribute apps

Getting app examples

App examples can be downloaded from Auterion Suite. There are currently the following examples available:

• minimal-cpp: A bare minimum example app using C++

• get-telemetry-cpp: A C++ app that obtains vehicle telemetry via MAVLink

• get-telemetry-python: A python app that obtains vehicle telemetry via MAVLink

• crosscompile-cpp: A minimal C++ with a full cross-compilation setup

The apps, albeit fairly minimal, can serve as a starting point for developing your own apps.

Building the example apps

Go into the directory of the app, which is the directory that contains the auterion-app.yml file, and run

auterion-cli app build

This command will create a new directory called build that contains a *.auterionos file. The *.auterionos is the app image that can be installed your Auterion device.

You need a working docker installation as well as docker-compose-plugin for building apps

Build failed? Auterion-cli simply calls docker build in the background. For debugging, you can cd in the directory where your Dockerfile is, and run docker build --platform=linux/arm64 .

Building for Virtual Skynode

If you are building your app for Virtual Skynode, you must provide the --simulation flag to specify the correct simulation target architecture:

auterion-cli app build --simulation

By doing so, the app's target architecture is configured to linux/amd64, enabling it to run within the simulation environment on your machine, provided your machine operates on the specified architecture.

Installing the app-base

Most AuterionOS apps require an app base to be installed on the target Skynode. The app base is a common layer that includes most of the runtime dependencies for apps. This allows the image size of apps to remain small, while still be able to access powerful libraries and tools.

The app base itself is distributed as an app (.auterionos file) as well and can be obtained from the developer account on Auterion Suite.

To install the app base, run

auterion-cli app install /PATH/TO/app-base-v0.auterionos

The installation can take up to 10 minutes. The app base itself is large, but only needs to be installed once.

The app base needs to be installed before any app can be installed on Skynode

To verify that the app base was correctly installed, you can run the app list command of auterion-cli:

$ auterion-cli app list

Name                   Version    Status    Enable    Services              Status    Enable
---------------------  ---------  --------  --------  --------------------  --------  --------
app-base-v0            v0         stopped   unknown   base-image            exited    unknown

The app base will show as "stopped". This is intended and normal. The app base itself does not do any work, its only purpose is to be present for other apps to use. Therefore, it is correct that it does not run, it only has to be present.

Installing the example app

You can install the example app, (or any other app) using the app install command. In case of the example app we built above, the .auterionos file will be in the build directory.

$ auterion-cli app install build/com.auterion.test-app.auterionos
 
Installing artifact build/com.auterion.test-app.auterionos
Looking for the update artifact
Check if your device is online...
API: v1.2
Uploading artifact: 99.5kit [00:00, 42.2Mit/s]                                                                                                                                   
Waiting for the device to complete the installation
The device has been updated successfully

Show status and logs of an app

You can get the status of an app using the app list command. A working app will be shown as "running".

If an app crashes, it gets restarted automatically by the system. If an app crashes on boot, the app will constantly appear as "restarting".

$ auterion-cli app list

Name                   Version    Status    Enable    Services              Status    Enable
---------------------  ---------  --------  --------  --------------------  --------  --------
app-base-v0            v0         stopped   unknown   base-image            exited    unknown
com.auterion.test-app  0.0.1      running   enabled   test-app              running   running

To get live logs of an app, use the app logs command.

auterion-cli app logs -f <APP NAME>

Live logs with the `-f` option require at least AuterionOS 2.7 or later

e.g.

$ auterion-cli app logs -f com.auterion.test-app

test-app  | Running since 293 seconds ..
test-app  | Running since 294 seconds ..
test-app  | Running since 295 seconds ..
test-app  | Running since 296 seconds ..
test-app  | Running since 297 seconds ..
test-app  | Running since 298 seconds ..

Press CTRL+C to quit the live log

Extending the examples

An AuterionOS app is structured the following way

• auterion-app.yml - Contains all meta-information about the app, like name, version, author etc. This file needs to be in the project root directory. Each build entry points to the location of a Dockerfile that needs to be built and run.

• Dockerfile - Describes how to actually build and run your app. You can use any docker command in here. Apps shall inherit from the auterion/app-base image. The Dockerfile gets discovered in the build process by the tool looking at the locations indicated in the auterion-app.yml file.

• Source files - The source files of your app. They can be in any language, since the app runs in a docker container

To extend the examples, do the following steps

1. In the auterion-app.yml, set

   1. app-name with the name of your app

   2. app-author with the reverse-domain notation of your entity, e.g. com.auterion

   3. app-version with the version of your app

   4. In services list your the services (Docker images / containers) your app will have. Most apps just have one service. Set the build of your service to the location where the Dockerfile for your service is. It is also possible to use existing docker images which the machine where auterion-cli will be executed has access to. To do so use the image: directive instead of build:. auterion-cli will attempt to docker pull any images that are not built from source.

2. Add the sources for your app

3. Edit / replace the Dockerfile with instructions how to build / run your app

App services should inherit from the auterion/app-base image.

The auterion/app-base image is a multi-arch image for both aarch64(arm64) and x86-64(amd64). When building for Skynode using auterion-cli, it will automatically choose the aarch64 version and run all your build instructions in an aarch64 context.

If, for testing, you build the docker image to run on your local machine, it will chose the native architecture of your machine, most likely x86-64.