`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] custom libmsghub 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
`api_version`	Version of the `mission.yaml` file	`1`
`kind`	Content of the `mission.yaml` file	`Mission`
`metadata.uid`	UID of the mission. A reverse-domain-name notation is recommended	Lowercase letters, numbers and underscores
`metadata.name`	Display name of the mission.	ASCII letters, numbers and underscores
`metadata.description`	Description of the mission	Freeform UTF-8
`metadata.version`	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 `0.0.0`	Valid parrot version number
`metadata.target_model_id`	Target drone model	`091A` (ANAFI Ai)
`metadata.target_min_version`	Minimum drone firmware version for the mission	Valid parrot version number
`metadata.target_max_version`	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, an atom.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 fields
Custom 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 a main.py file containing the main() function. This function will be called when the service is started, with the custom arguments in the sys.argv list as usual.
custom: For more complex build requirements, an atom.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 fields
Custom 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, an atom.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 fields
Other 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

mission.yaml file format#

Required metadata fields#

Custom fsup field#

Custom guidance mode fields#

Custom services fields#

Custom dependencies fields#

Custom libmsghub messages fields#

Mission signature#

`mission.yaml` file format#

Custom `libmsghub` messages fields#