Параметри та налаштування

PX4 використовує param subsystem (таблицю значень float і int32_t) і текстові файли (для скриптів запуску) для створення конфігурації.

У цьому розділі детально розглянуто підсистему param. У ньому описано, як відображати, зберігати і завантажувати параметри, а також як їх описувати і робити доступними для наземних станцій.

TIP

Запуск системи та роботу скриптів запуску конфігурації фреймів описано на інших сторінках.

Використання командного рядка

Системна консоль PX4 пропонує інструмент param, за допомогою якого можна встановлювати параметри, зчитувати їх значення, зберігати їх, а також експортувати й зберігати у файлах та відновлювати з них.

Отримання та встановлення параметрів

Команда param show виводить усі параметри системи:

param show

Для більшої вибірковості можна використовувати часткове ім'я параметра з символом підстановки "*":

nsh> param show RC_MAP_A*
Symbols: x = used, + = saved, * = unsaved
x   RC_MAP_AUX1 [359,498] : 0
x   RC_MAP_AUX2 [360,499] : 0
x   RC_MAP_AUX3 [361,500] : 0
x   RC_MAP_ACRO_SW [375,514] : 0

 723 parameters total, 532 used.

Ви можете використовувати прапорець -c, щоб показати всі параметри, які було змінено (порівняно з їх значеннями за замовчуванням):

param show -c

Ви можете використати param show-for-airframe, щоб показати всі параметри, які було змінено від значень за замовчуванням лише для поточного файлу літального апарату (та значень за замовчуванням, які він імпортує).

Параметри експорту та завантаження

Ви можете зберігати будь-які параметри, які були змінені (які відрізняються від параметрів за замовчуванням).

Стандартна команда param save збереже параметри у поточному файлі за замовчуванням:

param save

Якщо вказати аргумент, вона збереже параметри у новому каталозі:

param save /fs/microsd/vtol_param_backup

Існує дві різні команди для завантаження параметрів:

• param load спочатку виконує повне скидання всіх параметрів до значень за замовчуванням, а потім перезаписує значення параметрів будь-якими значеннями, збереженими у файлі.
• param import просто перезаписує значення параметрів значеннями з файлу, а потім зберігає результат (тобто фактично викликає param save).

Команда load ефективно скидає параметри до стану, у якому вони були збережені (ми говоримо "ефективно", тому що будь-які параметри, збережені у файлі, буде оновлено, але інші параметри можуть мати інші значення за замовчуванням, визначені у прошивці, ніж під час створення файлу параметрів).

На противагу цьому, import об'єднує параметри у файлі з поточним станом апарату. Наприклад, можна просто імпортувати файл параметрів, що містить дані калібрування, не перезаписуючи решту конфігурації системи.

Приклади для обох випадків показані нижче:

# Reset the parameters to when file was saved
param load /fs/microsd/vtol_param_backup
# Optionally save params (not done automatically with load)
param save

# Merge the saved parameters with current parameters
param import /fs/microsd/vtol_param_backup

Створення/визначення параметрів

Опис параметрів складається з двох частин:

• Метадані параметрів визначають значення за замовчуванням для кожного параметра у прошивці разом з іншими метаданими для відображення (і редагування) параметрів на наземних станціях керування та у документації.
• Код C/C++, який надає доступ до отримання та/або зміни значень параметрів з модулів та драйверів PX4.

Нижче описано кілька підходів до написання метаданих та коду. Де це можливо, код повинен використовувати оновлені метадані YAML та C++ API, а не старі визначення параметрів/коду C, оскільки вони є більш гнучкими та надійними.

Метадані параметрів компілюються у прошивку, і надаються наземним станціям за посередництвом служби MAVLink Component Information service.

Назви параметрів:

Назви параметрів не повинні перевищувати 16 ASCII символів.

За загальним правилом, кожен параметр у групі повинен мати однаковий (значущий) префікс, за яким слідує символ підкреслення, а MC_ і FW_ використовуються для параметрів, що відносяться саме до мультикоптерних або систем з фіксованим крилом. Ця конвенція не є обов'язковою.

Назва має збігатися як у коді, так і у метаданих параметру, щоб правильно асоціювати параметр з його метаданими (включно зі значенням за замовчуванням у прошивці).

C / C++ API

Існують окремі C і C++ API, які можна використовувати для отримання доступу до значень параметрів з модулів і драйверів PX4.

Однією з важливих відмінностей між API є те, що версія на C++ має більш ефективний стандартизований механізм синхронізації зі змінами значень параметрів (наприклад, з GCS).

Синхронізація важлива, оскільки параметр може бути змінений на інше значення в будь-який момент. Ваш код повинен завжди використовувати поточне значення зі сховища даних. Якщо отримати останню версію неможливо, то після зміни параметра буде потрібно перезавантаження ( вкажіть цю вимогу за допомогою метаданих @reboot_required).

Крім того, версія на C++ має кращу типізацію та менші витрати оперативної пам'яті. Недоліком є те, що ім'я параметра має бути відоме під час компіляції, тоді як C API може приймати динамічно створене ім'я як рядок.

C++ API

C++ API надає макроси для оголошення параметрів як атрибутів класу. Ви додаєте якийсь "шаблонний" код для регулярного виявлення змін у uORB Topic, пов'язаних з будь-яким оновленням параметрів. Потім код фреймворку (невидимо) відстежує повідомлення uORB, які впливають на атрибути ваших параметрів, і підтримує їх синхронізацію. У решті коду ви можете просто використовувати визначені атрибути параметрів, і вони завжди будуть актуальними!

Насамперед включіть необхідні заголовки до заголовка класу вашого модуля або драйвера:

• px4_platform_common/module_params.h для отримання макросу DEFINE_PARAMETERS:

  #include <px4_platform_common/module_params.h>

• parameter_update.h для доступу до повідомлень uORB parameter_update:

  #include <uORB/topics/parameter_update.h>

• Subscription.hpp для uORB C++ API підписки:

  #include <uORB/Subscription.hpp>

Створіть свій клас з ModuleParams і використовуйте DEFINE_PARAMETERS, щоб вказати список параметрів і пов'язані з ними атрибути класу. Назви параметрів мають збігатися з визначеннями метаданих параметрів.

class MyModule : ..., public ModuleParams
{
public:
    ...

private:

    /**
     * Check for parameter changes and update them if needed.
     */
    void parameters_update();

    DEFINE_PARAMETERS(
        (ParamInt<px4::params::SYS_AUTOSTART>) _sys_autostart,   /**< example parameter */
        (ParamFloat<px4::params::ATT_BIAS_MAX>) _att_bias_max  /**< another parameter */
    )

    // Subscriptions
    uORB::SubscriptionInterval _parameter_update_sub{ORB_ID(parameter_update), 1_s};

};

Оновіть файл cpp за допомогою шаблону, щоб перевірити наявність повідомлення uORB, пов'язаного з оновленням параметрів.

Періодично викликайте parameters_update(); у коді, щоб перевірити, чи відбулося оновлення:

void Module::parameters_update()
{
    if (_parameter_update_sub.updated()) {
        parameter_update_s param_update;
        _parameter_update_sub.copy(&param_update);

        // If any parameter updated, call updateParams() to check if
        // this class attributes need updating (and do so).
        updateParams();
    }
}

У наведеному вище методі:

• _param_update_sub.updated() повідомляє нам, чи є будь-яке оновлення в uORB-повідомленні param_update (але не вказує, який саме параметр змінено).
• Якщо було оновлено "деякий" параметр, ми копіюємо оновлення у parameter_update_s (param_update), щоб очистити очікуване оновлення.
• Потім викликаємо ModuleParams::updateParams(). Це "під капотом" оновлює всі атрибути параметрів, перелічені у нашому списку DEFINE_PARAMETERS.

Атрибути параметрів (_sys_autostart і _att_bias_max у цьому випадку) можна використовувати для відображення параметрів, і вони будуть оновлюватися щоразу, коли значення параметра змінюватиметься.

TIP

Шаблон Програми/Модуля використовує новий стиль C++ API, але не включає метадані параметрів.

C API

C API можна використовувати як у модулях, так і в драйверах.

Спочатку включіть параметр API:

#include <parameters/param.h>

Потім отримайте параметр і присвойте його змінній (тут my_param), як показано нижче для PARAM_NAME. Змінна my_param може бути використана в коді вашого модуля.

int32_t my_param = 0;
param_get(param_find("PARAM_NAME"), &my_param);

:::note Якщо у метаданих параметра було оголошено PARAM_NAME, то буде встановлене його значення за замовчуванням, і наведений вище виклик для пошуку параметра завжди буде успішним. :::

param_find() є "дорогою" операцією, яка повертає хендл, що може бути використаний param_get(). Якщо ви збираєтеся читати параметр багато разів, ви можете кешувати хендл і використовувати його в param_get() за потреби

# Get the handle to the parameter
param_t my_param_handle = PARAM_INVALID;
my_param_handle = param_find("PARAM_NAME");

# Query the value of the parameter when needed
int32_t my_param = 0;
param_get(my_param_handle, &my_param);

Метадані параметра

PX4 використовує розгалужену систему метаданих параметрів для управління дружнім до користувача представленням параметрів, а також для встановлення значень за замовчуванням для кожного параметра у прошивці.

TIP

Правильні метадані мають вирішальне значення для якісного користувацького досвіду на наземній станції.

Метадані параметрів можна зберігати будь-де у дереві коду у вигляді визначень параметрів .c або .yaml (визначення параметрів у форматі YAML є новішим і гнучкішим). Зазвичай він зберігається разом з відповідним модулем.

Система збірки витягує метадані (за допомогою make parameters_metadata) для створення довідника параметрів та інформації про параметри, що використовуються наземними станціями.

WARNING

Після додавання файлу параметрів new вам слід викликати make clean перед збіркою, щоб згенерувати нові параметри (файли параметрів додаються як частина кроку конфігурації cmake, який відбувається для чистих збірок і якщо файл cmake змінено).

Метадані YAML

:::note На момент написання статті визначення параметрів YAML не можна використовувати у бібліотеках. :::

Метадані YAML призначені для повної заміни .c визначень. Він підтримує ті самі метадані, а також нові можливості, такі як множинні визначення.

• Схема метаданих параметрів YAML знаходиться тут: validation/module_schema.yaml.

• Приклад використання визначень YAML можна знайти у визначенні параметрів MAVLink: /src/modules/mavlink/module.yaml.

• YAML-файл реєструється у системі збірки cmake шляхом додавання

  MODULE_CONFIG
    module.yaml

  до секції px4_add_module файлу CMakeLists.txt цього модуля.

Мета-дані YAML з багатьма екземплярами (шаблонами)

Шаблонні визначення параметрів підтримуються у YAML визначеннях параметрів (шаблонний код параметрів не підтримується).

YAML дозволяє визначати кількість екземплярів у назвах параметрів, описах, тощо за допомогою ${i}. Наприклад, нижче буде згенеровано MY_PARAM_1_RATE, MY_PARAM_2_RATE і т.д.

MY_PARAM_${i}_RATE:
  description:
    short: Maximum rate for instance ${i}

Наступні визначення YAML містять початковий та кінцевий індекси.

• num_instances (за замовчуванням 1): Кількість інстансів, які потрібно згенерувати (>=1)
• instance_start (за замовчуванням 0): Номер першого інстансу. Якщо 0, ${i} розширюється до [0, N-1]`.

Повний приклад див. у визначенні параметрів MAVLink: /src/modules/mavlink/module.yaml.

c параметр метаданих

Застарілий підхід для визначення метаданих параметрів знаходиться у файлі з розширенням .c (на момент написання цієї статті це підхід, який найчастіше використовується у дереві коду).

Розділи метаданих параметрів виглядають так, як показано в наступних прикладах:

/**
 * Pitch P gain
 *
 * Pitch proportional gain, i.e. desired angular speed in rad/s for error 1 rad.
 *
 * @unit 1/s
 * @min 0.0
 * @max 10
 * @decimal 2
 * @increment 0.0005
 * @reboot_required true
 * @group Multicopter Attitude Control
 */
PARAM_DEFINE_FLOAT(MC_PITCH_P, 6.5f);

/**
 * Acceleration compensation based on GPS
 * velocity.
 *
 * @group Attitude Q estimator
 * @boolean
 */
PARAM_DEFINE_INT32(ATT_ACC_COMP, 1);

Макрос PARAM_DEFINE_* в кінці визначає тип параметра (PARAM_DEFINE_FLOAT або PARAM_DEFINE_INT32), ім'я параметра (яке має відповідати імені, що використовується у коді) та значення за замовчуванням у прошивці.

Рядки в блоці коментарів є необов'язковими, і в основному використовуються для керування параметрами відображення та редагування на наземній станції. Призначення кожного рядка наведено нижче (докладніше див. module_schema.yaml).

/**
 * <title>
 *
 * <longer description, can be multi-line>
 *
 * @unit <the unit, e.g. m for meters>
 * @min <the minimum sane value. Can be overridden by the user>
 * @max <the maximum sane value. Can be overridden by the user>
 * @decimal <the minimum sane value. Can be overridden by the user>
 * @increment <the "ticks" in which this value will increment in the UI>
 * @reboot_required true <add this if changing the param requires a system restart.>
 * @boolean <add this for integer parameters that represent a boolean value>
 * @group <a title for parameters that form a group>
 */

Публікація метаданих параметрів у GCS

JSON-файл метаданих параметрів компілюється у прошивку (або хоститься в Інтернеті) і стає доступним наземним станціям через службу MAVLink Component Metadata Service. Це гарантує, що метадані завжди актуальні для коду, який виконується на апараті.

Цей процес такий самий, як і для метаданих подій. Для отримання додаткової інформації див. Метадані PX4 (Переклад і публікація).

Подальша інформація

• Пошук/оновлення параметрів
• Довідник параметрів
• Реалізація параметрів (інформація про .get(), .commit() та інші методи)