Menu Creation

To fully utilize the capabilities of Parasect, you will need to specify certain information about your desired autopilot configuration. This comes down to creating a folder structure that represents your Meals Menu.

Note

It is highly recommended that you read the Concepts section first and get acquainted with the Restaurant Analogy that is used as nomenclature.

See also

You can find a generic example Meals Menu as well as an PX4 example Meals Menu, that are part of the unit tests of Parasect. Refer to it while following this guide or use them as a starting point for your own use cases.

First, create your main Parasect input folder, which we’ll call menu for now (the actual folder name isn’t important). You can place this folder anywhere in your system. You will point Parasect to it later.

By the end of this guide, its tree will look something like this:

menu/
├── custom_dishes/
│   ├── bread.yaml
│   ├── coffee.yaml
│   ├── dairy.yaml
│   ├── desert.yaml
│   ├── extra_quantities.yaml
│   ├── fruit.yaml
│   ├── meat_and_potatoes.yaml
│   └── salad.yaml
├── meals.yaml
└── staple_dishes/
    ├── calibration.yaml
    ├── footer.yaml
    ├── header.yaml
    └── operator.yaml

Make two subfolders in it: custom_dishes and staple_dishes.

Filling in Staple Dishes

Each file contains all necessary information to create a Dish. A Dish is supposed to reflect one coherent set of parameters, for example related to PID gains, peripherals configuration, Remote Controller configuration or the installed battery.

There are currently four Staple Dishes in Parasect: calibration.yaml, operator.yaml, header.yaml and footer.yaml. They are reserved dishes that are used by Parasect in either the comparison or build functions.

calibration.yaml: This is a Dish that contains the names of the calibration parameters of your autopilot. List those parameters here to: a) not take them into account when comparing parameter sets and b) to remove them from generated parameter sets. An example Calibration Dish follows:

common:
  ingredients:
    - [SALT, ~, Each has his own taste]

Notice how each list item is a triplet of items, representing a parameter. The first value is the parameter name. The second is the parameter value. For the calibration Dish you do not need to specify a value, you can leave it as None (~). Finally, the third item is a string, where you can document why you chose to include this parameter here. You can also set it to None (as ~).

Tip

Python regular expressions can be used to capture more than one parameter name per line, e.g.

common:
ingredients:
   - [RC\d+_TRIM, ~, Disregard channel trim values]

operator.yaml: This is a Dish (with the usual Dish syntax) that contains the names of the operator parameters of your autopilot. List those parameters here to: a) not take them into account when comparing parameter sets and b) to remove them from generated parameter sets. You do not need to specify a value for a operator parameter either, leave it as None (~).

Its syntax is the same as calibration.yaml.

Note

calibration.yaml and operator.yaml are the only Dish files that are used by the compare command. If you only plan to use that and not build any parameter sets, then you can ignore the rest of this guide.

header.yaml and footer.yaml. These are files that don’t follow the usual Dish syntax. They contain the boilerplate text that your autopilot may require of the generated parameter files. The top-level dictionary does contain a Common section, that applies to all exported formats, but then alongside is a formats section.

This reflects the available export Formats that Parasect offers (e.g. px4 parameters and px4afv1 and px4afv2 for PX4 airframe files.)

Each named format then contains a common and variants section as usual, which you can refer to in your Meal.

An example header.yaml is:

common:
  - "# Parameter file exported by Parasect."

formats:
  csv:
    common:
      - "# Parameter name, Parameter value"
  px4:
    common:
      - "PX4-format header line 1\n"
      - "PX4-format header line 2\n"
  px4afv1:
    common:
      - "PX4-airframe-format header line 1\n"
      - "PX4-airframe-format header line 2\n"

Creating Custom Dishes

Next, you can create the Dishes that describe your parameter sets. Within the custom_dishes folder, create as many Dish .yaml files as you want and name them as you like.

In each Dish file, start by defining your Common Ingredients as a list of triplets, just as in calibration.yaml and operator.yaml. Each triplet refers to a single parameter and its contents are:

1. The parameter name.

2. The parameter value.

3. A justification string, to remind you why you chose to fix this parameter and why selected this particular value. Can be set to None (~).

If you plan to generate only one Meal (a single parameter set), then put all your parameter definitions here. Otherwise, put in the Common Ingredients only those parameters who are common across all of your Meals.

Then, define your Allergen Ingredients. These are parameters that you don’t want to exist in your generated parameter set. They will be removed from the default parameters list, if you point to one as a basis of your Meal. Some autopilot software group their parameters in parameter groups (e.g. PX4). This makes it easier to mark them as allergens as a whole, by placing the group name in the Allergen Groups section of the Dish.

If you plan to use slightly different versions of your Dish across the different Meals, then add a Variants section in your Dish. This is a dictionary where you can specialize your Dish with different Ingredients and Allergens for each Variant.

The contents of an example dish are:

common:
  ingredients:
    - [BEEF, 1, ~]
    - [POTATOES, 2, ~]
    - [THYME, 0.001, ~]
    - [GRAVY, 0.01, ~]
  allergens:
    substances:
      - [MUSHROOMS, ~, My stomach really can't handle them]
    groups:

variants:
  spicy:
    common:
      ingredients:
        - [CHILLI, 1, ~]
    variants:
      extra:
        common:
          ingredients:
            - [JALLAPENOS, 2, ~]

Note that it is possible to nest the Variants more than one level deep.

Creating your Menu

Now that your Dishes and their Variants are specified, you can bring it all together by designating Meals in your Menu. Create a meals.yaml file in the top-level directory of your Menu folder. This is a dictionary from strings to dictionaries.

Each section represents a unique autopilot configuration and it starts with an arbitrary name.

Then, in each row you add Dishes to your Meal. The key is the Dish name and the value is the Dish Variant. Set the value to None (~) to use only the Dish Common section. Refer to the nested Variants using a slash (/).

Example Meals Menu:

snack:
  fruit: single
  header: ~
  footer: ~

breakfast:
  dairy: cereal
  header: ~
  footer: ~

light_meal:
  salad: ~
  meat_and_potatoes: ~
  remove_calibration: True
  remove_operator: True
  header: ~
  footer: ~

spicy_meal:
  salad: ~
  meat_and_potatoes: spicy/extra
  remove_calibration: True
  remove_operator: True
  header: ~
  footer: ~

full_meal:
  salad: ~
  meat_and_potatoes: ~
  bread: baguette
  desert: ~
  header: ~
  footer: full_meal

christmass_at_grandmas:
  parent: full_meal
  salad: village
  extra_quantities: ~
  add_new: True

dangerous_combinations:
  parent: breakfast
  coffee: filter
  add_new: True

There are also some reserved, optional keywords for the Meal dictionary:

• defaults: Specifies a filepath where the default parameters file is found. If it is not absolute, then it is relative to your menu folder. This option overrides the Parsect default parameters filepath configuration.

• sitl: Marks the Meal for Simulation-In-The-Loop (SITL) purposes. You can select to build SITL or non-SITL Meals with the corresponding argument of the build API function.

• hitl: Marks the Meal for Hardware-In-The-Loop (HITL). In some output formats (e.g. PX4), this affects the output filename.

• parent: Adds a reference to another Meal, to be used as a parent for the current Meal. For more information see section Parent Meals.

• remove_calibration: Removes the Calibration Dish Ingredients from this Meal. Strongly recommended to be set to true.

• remove_operator: Removes the Operator Dish Ingredients from this Meal. Strongly recommended to be set to true.

• add_new: Allows the addition of Ingredients that are not stated in the default parameter set (or the parent, if one is specified).

• frame_id: This is applicable to PX4 output formats. It sets the SYS_AUTOSTART parameter.

Parent Meals

Sometimes you want to specify a base Meal (parameter set) and then a bunch more that are basically identical to that first one, except for very few changes. One such example is wanting a basic parameter set and then additional vehicles with adjustments to the values of certain parameters. Another example is wanting additional Meal variations configuring a camera mount or a secondary radio.

Instead of re-specifying an identical Meal with the additional Dishes, you can specify the base Meal as the parent of the new Meal and specify only the additional Dishes.

The Default Parameter set is not used for the child-Meals. The parameter set of the parent is used instead. Editing the parent Ingredients is thus always possible, but to add new parameters that don’t exist in the parent Meal you will need to also set add_new to true.

See also

Now that you have created your Meals Menu, find out how to point Parasect to it in Setting Paths.