mission.yaml
file format#
A mission.yaml
file is composed of:
Some required metadata fields
[0-1]
custom fsup plugin field[0-N]
custom guidance mode fields[0-8]
custom services fields[0-N]
custom dependencies fields[0-N]
customlibmsghub
messages fields[0-1]
signature field
The order of each fields in the file is irrelevant
Required metadata fields#
All missions must have those values filled
api_version: 1
kind: Mission
metadata:
uid: com.example.missions.mission_name
name: mission_name
description: mission description
version: 0.0.0
target_model_id: 091A
target_min_version: 7.5.0
target_max_version: 7.5.99
key |
description |
restrictions |
---|---|---|
|
Version of the |
|
|
Content of the |
|
|
UID of the mission. A reverse-domain-name notation is recommended |
Lowercase letters, numbers and underscores |
|
Display name of the mission. |
ASCII letters, numbers and underscores |
|
Description of the mission |
Freeform UTF-8 |
|
Mission version number. This number is chosen by the mission developer. The drone will only accept a mission
update if the new number is higher
than the previous one, or is the
special value |
Valid parrot version number |
|
Target drone model |
|
|
Minimum drone firmware version for the mission |
Valid parrot version number |
|
Maximum drone firmware version for the mission |
Valid parrot version number |
Note
A parrot version number is in the form X.Y.Z[-suffixW]
, where:
X
Can be any number.Y
Can be any number between 0 and 99.Z
Can be any number between 0 and 99.-suffix
Can be either empty, or one of-alpha
,-beta
or-rc
.Z
Can be any number between 0 and 99, but must not be present if the suffix is empty.
The 0.0.0
version code should only be used for development versions
Custom fsup field#
If your mission requires a custom flight supervisor plugin, the mission.yaml
should include
the following:
fsup:
lang: python
The fsup
field tells airsdk-cli
that you have a custom flight supervisor plugin, while the
lang: python
tells that the plugin is written in python, which is the only supported language
for flight supervisor plugins.
The source code of your plugin should reside in the <mission>/fsup/
directory. All .py
files
within this directory will be considered to be part of your plugin.
A plugin must at least contain a mission.py
file (its entry point) and a __init__.py
file
(which can be empty). More details about the flight supervisor plugins can be found in the AirSDK
documentation (TODO: Link)
Custom guidance mode fields#
If your mission requires custom guidance mode, the mission.yaml
should include a guidance
field, with one or more subfields (one for each mode).
guidance:
example_cpp_mode:
lang: c++
example_python_mode:
lang: python
example_custom_built_mode:
lang: custom
Where example_xxx_mode
should be replaced by the name of the custom mode.
The source code of a custom mode is assumed to be in the <mission>/guidance/mode_name/
directory
The lang
subfield determines how the mode is built :
c++
: All.cpp
files in the directory (including subdirectories) are built, then linked together as a.so
file.python
: All.py
files in the directory (including subdirectories) are copied to the mission site-packages folder, so the root package can be imported. In this case the sources must present a valid python package.custom
: For more complex build requirements, anatom.mk
file provided by the developer is used. This is more complex, but allows as much flexibility as the legacy build system for some edge use-cases.
c++
guidance modes can also have custom dependencies:
guidance:
example_cpp_mode:
lang: c++
depends:
- libpomp
- msghub::my_messages
- my_library
Those dependencies can be:
Libraries exposed by AirSDK (e.g.
libpomp
).Custom
libmsghub
messages (e.g.msghub::my_messages
). See Custom libmsghub messages fieldsCustom libraries included in the mission (e.g.
my_library
). See Custom dependencies fields
Custom services fields#
A mission can have up to 8 different services, each service is declared using the following syntax
services:
example_c_service:
lang: c
example_cpp_service:
lang: c++
example_python_service:
lang: python
example_custom_built_service:
lang: custom
Where example_xxx_service
should be replaced by the name of the service.
The source code of a service is assumed to be in the <mission>/services/service_name/
directory
Each service can have a args
subfield, containing a list of arguments that will be passed to the
service process.
The lang
subfield determines how the service is built :
c
: All.c
files in the directory (including subdirectories) are built, then linked together as an executable.c++
: All.cpp
files in the directory (including subdirectories) are built, then linked together as an executable.python
: All.py
files in the directory (including subdirectories) are copied to the mission site-packages folder. The service is expected to be a valid python package with both a__init__.py
file (which might be empty) and amain.py
file containing themain()
function. This function will be called when the service is started, with the custom arguments in thesys.argv
list as usual.custom
: For more complex build requirements, anatom.mk
file provided by the developer is used. This is more complex, but allows as much flexibility as the legacy build system for some edge use-cases.
c
or c++
services can also have custom dependencies:
services:
example_c_service:
lang: c
depends:
- libpomp
- msghub::my_messages
- my_library
Those dependencies can be:
Libraries exposed by AirSDK (e.g.
libpomp
).Custom
libmsghub
messages (e.g.msghub::my_messages
). See Custom libmsghub messages fieldsCustom libraries included in the mission (e.g.
my_library
). See Custom dependencies fields
Custom dependencies fields#
Some services and guidance modes can depend on libraries not directly available through AirSDK.
In this case, those libraries should be declared as “dependencies” of the mission, and will be built
by airsdk-cli
during the build of the whole mission.
deps:
example_c_library:
lang: c
example_cpp_library:
lang: c++
example_custom_built_service:
lang: custom
Where example_xxx_library
should be replaced by the name of the library.
This is the name that should be added in the depends:
field of guidance mode, services, or other
libraries depending on this library.
The source code of a dependency is assumed to be in the <mission>/deps/library_name/
directory
The lang
subfield determines how the library is built :
c
: All.c
files in the directory (including subdirectories) are built, then linked together as a.so
file.c++
: All.cpp
files in the directory (including subdirectories) are built, then linked together as a.so
file.custom
: For more complex build requirements, anatom.mk
file provided by the developer is used. This is more complex, but allows as much flexibility as the legacy build system for some edge use-cases.
For c
or c++
libraries, the headers
subfield specifies the directory that will be added
to the dependent libraries/services include path. If not specified, then the source directory is
instead added:
deps:
example_c_library:
lang: c
# This library will add '<mission>/deps/example_c_library/'
# to its dependent include path
example_cpp_library:
lang: c++
headers: include
# This library will add '<mission>/deps/example_cpp_library/include/'
# to its dependent include path
c
or c++
libraries can also have custom dependencies:
deps:
example_c_library:
lang: c
depends:
- libpomp
- msghub::my_messages
- my_library
Those dependencies can be:
Libraries exposed by AirSDK (e.g.
libpomp
).Custom
libmsghub
messages (e.g.msghub::my_messages
). See Custom libmsghub messages fieldsOther custom libraries included in the mission (e.g.
my_library
).
Custom libmsghub
messages fields#
libmsghub
is a library handling inter-process messaging, and heavily used by AirSDK and the
drone firmware. Using it as the IPC method for a mission is not mandatory, but a helper is provided
as it is the recommended way of running inter-process communications within a mission.
libmsghub
uses protobuf messages as it’s data serialization method. A custom msghub field
describes a list of libmsghub
packages and their respective .proto
protobuf files locations
under the <mission>/msghub
directory. A custom msghub
list is declared with the following
syntax:
msghub:
- name: custom_msgs_A
include_path: example/missions/A
- name: custom_msgs_B
include_path: example/missions/B
Where custom_msgs_X
should be replaced by the custom msghub
package name and where
example/missions/X
is the actual protobuf file locations under the <mission>/msghub
directory.
The name
of the package is the name used in the `` - msghub::<name>`` values of the depends:
fields for previously described objects.
The include_path
field is optional and defaults to the name of the package.
A custom message package is composed of all messages described in all .proto
files in the
<mission>/msghub/<include_path>/
directory (including subdirectories). The <mission>/msghub
directory is the root protobuf path for every *.proto
file (regardless of the include_path
field value).
Libraries, guidance modes and services depending on msghub packages will have access to both
the generated protobuf messages directly, and the generated msghub
wrappers. Those wrappers are
available in either c
, c++
and python
.
Mission signature#
By default, an unsigned mission can only be installed on a simulated drone. Using a physical drone requires the mission to be signed, and the associated public key to be trusted by the firmware. More informations can be found in the AirSDK documentation (TODO: Link)
Note
airsdk-cli
only support local or aws_kms stored ecdsa keys.
The signature can be configured by adding a signature:
field to the yaml file:
# Exemple for a local signature file using an absolute path
signature:
type: local
path: /absolute/path/to/key.pem
# Exemple for a local signature file using a relative path
signature:
type: local
path: relative/path/to/key.pem # starts from the directory containing the mission.yaml file
# Exemple for a AWS Key Management System managed key
signature:
type: aws-kms
key_id: kms_key_id