`mission.yaml` file format#

A mission.yaml file is composed of:

Some required metadata
The list of mission targets
[0-1] signatures dictionary
[1-M] code dictionaries, consisting of:
- [0-1] fsup plugin dictionary
- [0-N] guidance modes dictionaries
- [0-8] services dictionaries
- [0-N] dependencies dictionaries
- [0-N] libmsghub messages dictionaries
- [0-N] pip packages dependencies dictionaries

The order of each element in the file is irrelevant

Required metadata fields#

All missions must have those values filled

api_version: 3
kind: Mission
metadata:
  uid: com.example.missions.mission_name
  name: mission_name
  description: mission description
  version: 0.0.0

key	description	restrictions
`api_version`	Version of the `mission.yaml` file	`3`
`kind`	Content of the `mission.yaml` file	`Mission`
`metadata.uid`	UID of the mission. A reverse-domain-name notation is recommended	Lowercase letters, numbers, dots 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

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

Mission build targets#

Any mission must have at least one build target. A call to airsdk build will build the mission for all of its declared targets.

# Example for Anafi Ai full support (physical & simulated drones)
targets:
  Anafi Ai:
  Anafi Ai Simulator:

Valid targets are :

Target name	Aliases	Description
`Anafi Ai:`	`Anafi 2:`	Physical Anafi Ai drone
`Anafi Ai Simulator:`	`Anafi 2 Simulator:` `Anafi Ai PC:` `Anafi Ai Simulator:`	Simulated Anafi Ai drone

Target name

Aliases

Description

Anafi Ai:

Anafi 2:

Physical Anafi Ai drone

Anafi Ai Simulator:

Anafi 2 Simulator:

Anafi Ai PC:

Anafi Ai Simulator:

Simulated Anafi Ai drone

Mission signatures#

This field is used to specify the private key(s) used to sign the mission. It can be omitted during development or when using the simulator. For a physical drone, when the signature is omitted, airsdk-cli will use an auto-generated key, and install it alongside the mission with the airsdk install command).

The signatures field is a list of signature dictionaries. For production deployment on physical drones, at least one signature named “signature.ecdsa” must but present. This signature is the only one that is verified by the drone firmware during the mission installation. Other signatures may be present in this the mission.yaml file and may be verified by by a third-party software.

Each signature dictionary can contain the following keys:

key	description	required	valid values
`name`	name of signature	always	`signature.ecdsa`
`type`	Type of signature	always	`local`, `aws-kms`
`path`	Path to the private key	if `type` is `local`
`key_id`	Identifier of the aws-kms key to use	if `type` is `aws-kms`

 # Example for a local signature file using an absolute path
 signatures:
   - name: signature.ecdsa
     type: local
     path: /absolute/path/to/key.pem

 # Example for a local signature file using a relative path
 signatures:
   - name: signature.ecdsa
     type: local
     path: relative/path/to/key.pem # starts from the directory containing the mission.yaml file

# Example for a AWS Key Management System managed key
 signatures:
   - name: signature.ecdsa
     type: aws-kms
     key_id: kms_key_id

Flight supervisor plugin dictionary#

The presence of an fsup dictionary tells airsdk-cli that the mission uses a custom flight supervisor plugin. The source code of the plugin should reside in the <mission>/fsup/ directory.

The fsup dictionary can contain the following keys:

key	description	required	valid values
`type`	Type of fsup plugin	only if not `auto`	`auto`, `alchemy_module`
`lang`	Language used by the plugin	if `type` is `auto` or absent	`python`
`depends`	List of dependencies of the plugin	if `type` is `auto` or absent	List of modules the plugin depends on
`module`	Name of the alchemy module	if `type` is `alchemy_module` and more than one module are declared

# Fsup plugin example
fsup:
  lang: python
  depends: msghub::exampleMessages

# Alchemy-built fsup plugin example
fsup:
  type: alchemy_module
  module: plugin_name # Can be omitted if only a single alchemy module is declared

If the type is auto (or omitted), then all .py files within the plugin directory will be considered to be part of the plugin. A plugin must at least contain a mission.py file (its entry point) and a __init__.py file (which can be empty).

If the type is set to alchemy_module, then the build system expects to find an atom.mk file within the <mission>/fsup/ directory. If the atom.mk file declares more than one module, then the module value will be used to select only the proper one.

Guidance mode dictionary#

If a mission includes one or more guidance mode, they should be declared in a guidance dictionary at the root of the mission.yaml file. Each mode is declared as a dictionary within the guidance dictionary, the key being the name of the mode. Each modes source code should reside in the <mission>/guidance/<mode_name>/ directory.

A mode dictionary can contain the following keys:

key	description	required	valid values
`type`	Type of guidance mode	only if not `auto`	`auto`, `alchemy_module`
`lang`	Language used by the mode	if `type` is `auto` or absent	`c++`, `python`
`depends`	List of dependencies of the mode	if `type` is `auto` or absent	List of modules this mode depends on
`module`	Name of the alchemy module	if `type` is `alchemy_module` and more than one module are declared

# Example of guidance modes
guidance:
  example_cpp_mode:
    lang: c++
    depends:
      - exampleLib
      - msghub::exampleMessages
  example_python_mode:
    type: auto # Implicit, can be omitted
    lang: python
  example_alchemy_mode:
    type: alchemy_module

If the type is auto (or omitted), then airsdk-cli will use the lang field to determine how to build the mode:

If lang is c++, then all .cpp files within the directory will be considered to be the source files.
If lang is python, then all .py files within the directory will be considered to be the source files.

The depends list syntax is explained in detail here

If the type is set to alchemy_module, then the build system expects to find an atom.mk file within the <mission>/guidance/<mode_name> directory. If the atom.mk file declares more than one module, then the module value will be used to select only the proper one.

Services dictionary#

If a mission includes one or more services, they should be declared in a services dictionary at the root of the mission.yaml file. Each service is declared as a dictionary within the services dictionary, the key being the name of the service. Each service source code should reside in the <mission>/services/<service_name>/ directory.

A mission can have up to 8 different services, each service dictionary can contain the following keys:

key	description	required	valid values
`type`	Type of service	only if not `auto`	`auto`, `alchemy_module`
`lang`	Language used by the service	if `type` is `auto` or absent	`c`, `c++`, `python`
`depends`	List of dependencies of the service	if `type` is `auto` or absent	List of modules this service depends on
`module`	Name of the alchemy module	if `type` is `alchemy_module` and more than one module are declared
`args`	List of arguments passed to the service	optional	List of strings

services:
  example_c_service:
    type: auto # Implicit, can be omitted
    lang: c
  example_cpp_service:
    lang: c++
    depends:
      - exampleLib
      - msghub::exampleMessages
  example_python_service:
    lang: python
    args:
      - someArg
      - someOtherArg
  example_alchemy_service:
    type: alchemy_module
    module: alchemy_module_name

If the type is auto (or omitted), then airsdk-cli will use the lang field to determine how to build the service:

If lang is c, then all .c files within the directory will be considered to be the source files.
If lang is c++, then all .cpp files within the directory will be considered to be the source files.
If lang is python, then all .py files within the directory will be considered to be the source files.

The depends list syntax is explained in detail here

If the type is set to alchemy_module, then the build system expects to find an atom.mk file within the <mission>/services/<service_name> directory. If the atom.mk file declares more than one module, then the module value will be used to select only the proper one.

Dependencies dictionary#

Some services and guidance modes can depend on libraries not directly available through Air SDK. Such libraries can be declared in a deps dictionary at the root of the mission.yaml file. Each library is declared as a dictionary within the deps dictionary, the key being either the name of the library (when type is auto or absent), or simply the name of the directory containing the atom.mk file for the library (when type is alchemy). In all cases, the source code should reside in the <mission>/deps/<dep_name> directory.

A dependency dictionary can contain the following keys:

key	description	required	valid values
`type`	Type of dependency	only if not `auto`	`auto`, `alchemy`
`lang`	Language used by the library	if `type` is `auto` or absent	`c`, `c++`
`depends`	List of dependencies of the library	if `type` is `auto` or absent	List of modules this library depends on
`headers`	Path of exported headers of the library	optional, only available if `type` is `auto` or absent	Relative path of exported headers (defaults to `.` if not given)

deps:
  example_c_library:
    type: auto # Implicit, can be omitted
    lang: c
    # This library will add '<mission>/deps/example_c_library/'
    # to its dependent include path
    depends:
      - exampleLib
      - msghub::exampleMessages
  example_cpp_library:
    lang: c++
    headers: include
    # This library will add '<mission>/deps/example_cpp_library/include/'
    # to its dependent include path
  example_alchemy_library:
    type: alchemy

If the type is auto (or omitted), then airsdk-cli will use the lang field to determine how to build the library:

If lang is c, then all .c files within the directory will be considered to be the source files.
If lang is c++, then all .cpp files within the directory will be considered to be the source files.

The depends list syntax is explained in detail here

If the type is set to alchemy, then the build system expects to find one or more atom.mk files within the <mission>/deps/<dep_name> directory. In this case, it is possible for a single dictionary in deps: to declare multiple libraries if the atom.mk file contains multiple module declarations.

Note

Any dependency declared this way will only be built and included in the mission bundle if it is included in the dependencies (direct or indirect) or the flight supervisor plugin, a guidance mode or a service.

`libmsghub` messages list#

libmsghub is a library handling inter-process messaging,which is heavily used by Air SDK and the drone firmware, using protobuf messages to represent the data being exchanged. airsdk-cli allows a mission to declare custom protobuf messages, and will generate the required libmsghub code to use those messages with the library.

Note

Using libmsghub as the inter-process communication library within a mission is not required. A mission can use any method to exchange data between its elements.

If the mission uses custom defined protobuf messages for use within libmsghub, they should be declared in a msghub list at the root of the mission.yaml file. Each set of message is declared as a dictionary containing the following keys:

key	description	required	notes
`name`	Name of the message set	always
`include_path`	Path (relative to `<mission>/msghub/`) where the `.proto` files are located	optional	If not provided, defaults to the value of `name`

# Example of messages sets
msghub:
  # Message set with .proto files within <mission>/msghub/example/mission/A/
  - name: custom_msgs_A
    include_path: example/mission/A
  # Message set with .proto files within <mission>/msghub/custom_msgs_B/
  - name: custom_msgs_B

The name of the package is the name used in the `` - msghub::<name>`` values of the depends keys for previously described elements.

The <mission>/msghub directory is the root protobuf path for every .proto file, regardless of the include_path field value. This means that for the custom_msgs_A example, the messages will reside in the example.mission.A package.

Note

This helper will generate both the protobuf messages directly and the libmsghub wrappers in C, C++ and Python, but only the depended-on languages will actually be built.

`depends` field in code dictionaries#

All source dictionaries can have a depends list when their type is auto. If omitted, the list is assumed to be empty (i.e. the element does not depend on any non-basic library or msghub messages set).

This list can include the following elements:

Libraries exported by Air SDK itself (e.g. libtelemetry). A subset of the Air SDK libraries is automatically added as dependencies to all elements for convenience purpose, but repeating them in the list is supported.
Libraries declared within a mission with type == auto. In this case, simply add the library name (its key withing the deps: dictionary) to the list.
Libraries declared within a mission with type == `alchemy. In this case, add the proper alchemy module name to the list
libmsghub messages sets (including the corresponding protobuf & libmsghub wrappers). In this case, add msghub::<message_set_name> (e.g. msghub::custom_msgs_A) to the list

`pip` packages dictionary#

If the mission needs a specific pip usage, this dictionary enables to provide such a custom purpose.

This list can include the following elements:

Requirements are the pip packages dependencies the mission needs. There is two ways of registering the pip packages to install. Either via the path of a requirements.txt file, that can be obtained via a pip freeze of the environment, or one at a time. A particular version may be specified. The version format is identical to the one used via a classical pip usage.

Package format	Description	Example
with a path	Relative path of the ‘requirements.txt’ is given	`- path: "relative/path/to/requirements.txt"`
single package	No version is specified	`- pip_pkg`
package with version	A specific version of the package is specified	`- pip_pkg==1.0.0`
package below version	Will consider the higher available version below the specified version	`- pip_pkg<=1.0.0`

mission.yaml file format#

Required metadata fields#

Mission build targets#

Mission signatures#

Flight supervisor plugin dictionary#

Guidance mode dictionary#

Services dictionary#

Dependencies dictionary#

libmsghub messages list#

depends field in code dictionaries#

pip packages dictionary#

`mission.yaml` file format#

`libmsghub` messages list#

`depends` field in code dictionaries#

`pip` packages dictionary#