The Tutorial App allows the user to access the vehicles position data from a custom UI and even command position changes. Follow this guide to learn how to write an app that can read and influence the state of the vehicle and make it accessible from a custom UI.
These are the main functions this app provides which will be explained in this guide.
Telemetry reading
Command sending
Custom UI
Along with these functions there will also be general explanations on the structure and functions of AuterionOS apps and how to build, install and use those apps.
Setting Up the Development Environment
Install the Auterion CLI
The Auterion CLI can easily be installed using PIP (python’s package manager) with the following command:
pip3 install auterion-cli
To get more detailed Information on the Setup go to
Clone the app-tutorial-code Repository to use the example code, take a look at one of the example codes in Application Development or build up your own according to the structure outlined in the next section.
Structure
Every AuterionOS app should follow the same file structure in order to be built and deployed using the Auterion CLI. There are 3 things that make up an AuterionOS app and these will be explained in the following 3 subsections. More information about this topic can be found in the Application Development Section.
For this app mavlink and libmav are used so they need to be added as git submodules.
Directory Structure of the App
An AuterionOS app minimally requires an auterion-app.yml needs to be in the root directory, in this case app-tutorial-code. The rest of the structure is optional, but all the referencing in the example code is based on this structure so any changes to the structure need to be changed there as well. The Dockerfile, the submodules that will be added and the source code will be in services/web-navigation. Since this app will be in C++, the CMakeList.txt will be in this directory as well, main.cpp will be in the src folder and the index.html in the website folder.
app-tutorial-code/ # Root directory of the application
auterion-app.yml # Auterion app metadata file. Has to be in root dir
services/ # Folder to contain the individual services
web-navigation/ # Folder for the "web-navigation" service
Dockerfile # Describes how "web-navigation" image is built
CMakeLists.txt # Describes how our C++ app is built
src/ # Diretory for source code of our C++ app
main.cpp # Source code of our C++ app
website/ # Directory for the HTML content of our web-UI
index.html # Source code of our web UI
libmav[subm]/ # libmav C++ library as submodule
mavlink[subm]/ # mavlink message definitions as submodule
Git submodules
After creating the directory the app will be created in, use git to add the necessary submodules. If git isn't already installed you can follow this Guide. To turn your created directory into a git repository use git init.
git init
Then add libmav and mavlink as submodules to your repository by going to the directory the submodules should be added to and using git submodule add.
cd services/web-navigation/
git submodule add https://github.com/Auterion/libmav.git
git submodule add https://github.com/mavlink/mavlink.git
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. More detailed explanations can be found here.
auterion-api-version: 2 # Auterion API version this app is targeting
auterion-app-base: v2 # Version of the auterion/app-base
app-name: tutorial-web-navigation # The name of your app
app-version: 0.0.1 # The version of your app
app-author: com.auterion # The authoring entity (reverse-domain notation)
target-platform: [skynode, ainode] # Supported platforms (skynode or ainode)
Like in docker-compose, your app can consist of multiple docker containers. In 'services' you list all the docker containers that make up your app. In most cases, this is just one service. The API configuration for the web interface is also added here.
services:
web-navigation: # Name of the service
build: services/web-navigation # Location of the Dockerfile
ssh: true # Enable SSH port forwarding
http:
/: # The URI that should be mapped
static-root: /data/webroot # Static content points to a directory
function:
type: ui # Assign function UI to the endpoint
label: Tutorial Web Navigation # Make site reachable from vehicle webpage
/api: # The URI that should be mapped
proxy: # Proxying the requests
port: 8080 # The port in the docker container to proxy to
main.cpp
Create this file in services/web-navigation/src. It contains all the necessary C++ code. First some general setup.
To later use for the change in position, functions which change the coordinate a given distance. For this example, this uses a crude distance estimation function, but is sufficient for demo purpose.
class App {
private:
mav::MessageSet _message_set;
std::shared_ptr<mav::TCPClient> _phy;
std::shared_ptr<mav::NetworkRuntime> _runtime;
std::shared_ptr<mav::Connection> _connection;
std::mutex _system_state_mtx;
SystemState _system_state;
//add code here
public:
App() : _message_set("mavlink/common.xml") {
}
void run() {
connectMAVLink();
std::cout << ".. Connected to MAVLink" << std::endl;
auto global_position_int_id = _message_set.idForMessage("GLOBAL_POSITION_INT");
auto battery_status_id = _message_set.idForMessage("BATTERY_STATUS");
//add code here
}
};
int main(int argc, char** argv) {
App app;
app.run();
return 0;
}
Telemetry Reading
To get flight information or to influence the flight path Mavlink messages can be used. In the Tutorial App a Mavlink connection is established and then used to receive Telemetry data and send commands for a position change to the flight controller. In this App libmav is used.
To create an interface for the Mavlink connection and connect with Mavlink, add this to the private section of main.cpp. It will be called in run().
The tutorial App uses a custom interface explained in the index.html section to change the position of the vehicle. The main.cpp handles these requests and communicates them to the flight controller.
Create a router to handle the http requests from the web interface. This router is created with restinio, to learn more go to RESTinio Documentation. Add this to the private section of the code.
std::unique_ptr<restinio::router::express_router_t<>> createRouter() {
auto router = std::make_unique<restinio::router::express_router_t<>>();
//add code for telemetry data
//add code for reposition commands
return router;
}
Add this to createRouter() to provide the telemetry data for the web interface.
Add this to run() in the public section to start the server.
struct my_server_traits : public restinio::default_single_thread_traits_t {
using request_handler_t = restinio::router::express_router_t<>;
};
std::cout << "Starting server on port 8080" << std::endl;
restinio::run(
restinio::on_this_thread<my_server_traits>()
.port(8080)
.address("0.0.0.0")
.request_handler(this->createRouter())
);
index.html
Create this file in services/web-navigation/website. It contains the scripts for the UI. The Interface can be designed with html and will be accessible in the local updater.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>WEB Navigation example</title>
<script lang="javascript">
// add javascript code here
</script>
<!-- add html layout here -->
A javascript function using the API is used to get the telemetry data and display it on the web interface.
To create the page and call the reposition function html is used.
<style>
body {
font-family: Arial, Helvetica, sans-serif;
}
</style>
</head>
<body>
<h1>
Tutorial app example
</h1>
<div id="status-info">
Loading...
</div>
<hr />
<button onclick="goDirection('north')">Go north (1m)</button>
<button onclick="goDirection('east')">Go east (1m)</button>
<button onclick="goDirection('south')">Go south (1m)</button>
<button onclick="goDirection('west')">Go west (1m)</button>
</body>
</html>
After installing the App on a Skynode, open 10.41.1.1 and click "Show installed apps" to show all apps installed on the Skynode and click on the "Tutorial Web Navigation" Link to open the web interface.
CMakeList.txt
The CMakeList file contains the information on how to compile.
Add a file named "Dockerfile" to services/web-navigation.Describes how to actually build and run the app. Any docker command can be used 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.
This app will inherit from version 2 of the App Base.
FROM auterion/app-base:v2
This will install restinio. To learn more about restinio, and how to use it, go to the RESTinio Documentation.
To install on a Skynode the device must be selected in the Auterion CLI. First discover the devices connected. When no device is selected and the Skynode is connected with USB it will be selected by default so this step can be skipped.
auterion-cli device discover
To select a device the serial number is needed. The "*" in the first column shows if the device is already selected and the serial number is in the second column.
selected serial version addresses
---------- --------- --------- -------------
* 009128332 v2.15.0 {'10.41.1.1'}
Use the serial number to select the device.
auterion-cli device select <device serial number>
If the selection was successful this is the shown output.
$ auterion-cli device select 009128332
Selected device with ID 009128332 on address 10.41.1.1
Build and Install app on Skynode using Auterion CLI
First the App needs to be built. Execute this command in the folder the App is in.
auterion-cli app build
The App base version specified in the auterion-app.yml needs to be installed on the device first. The App can be installed either over the local updater on 10.41.1.1 or by using this command.
