8. Конфигурирование ПО Raspberry Pi (LE)

8.1. Назначение и общие положения

Этот раздел описывает структуру и назначение параметров JSON‑конфигурации программного обеспечения Location Engine (LE), работающего на Raspberry Pi под Ubuntu Server 24.04.
Файл конфигурации указывается при запуске LE ключом -c и может располагаться в любом пути, принятые варианты в проекте:

/home/uwblandle/config/config.json;

Рабочий каталог рекомендуется передавать ключом -w как /home/uwblandle.
Логи проекта хранятся в /home/uwblandle/logs/ (каталог должен существовать и принадлежать пользователю uwblandle, который включён в группу dialout).

8.1.1. Пример ручного запуска

/usr/local/bin/uwb_landle   -w /home/uwblandle   -c /home/uwblandle/config/config.json

8.2. Исходный JSON‑файл конфигурации (эталон)

Ниже приведён исходный файл (без изменений), далее — подробные пояснения по каждому разделу и рекомендуемые настройки.

{
  "logging": {
    "level": "info",
    "console_output": true,
    "file_output": true,
    "file_path": "./logs/uwb_landing_system.log",
    "colored_output": true,
    "include_timestamp": true,
    "include_thread_id": false,
    "max_log_files": 5,
    "max_log_size_mb": 20
  },
  "binary_logging": {
    "enabled": true,
    "file_path": "./logs/uwb_landing_system.bin",
    "buffer_size": 10000,
    "flush_interval_ms": 100,
    "log_inputs": true,
    "log_outputs": true,
    "max_log_files": 5,
    "max_log_size_mb": 20
  },
  "timesync": {
    "enabled": true,
    "sync_rate_hz": 1.0,
    "sample_window": 10,
    "max_rtt_ms": 100.0,
    "min_samples_for_sync": 3,
    "sync_timeout_sec": 5.0,
    "max_offset_ms": 60000.0,
    "max_abs_time_diff_ms": 3600000.0
  },
  "system": {
    "system_id": 1,
    "component_id": 191
  },
  "buffering": {
    "packet_buffer_size": 1000,
    "drop_threshold_ms": 1000
  },
  "estimator": {
    "enabled": true,
    "update_rate_hz": 50,
    "output_rate_hz": 20,
    "site_status_timeout_sec": 10,
    "initial_position": [0.0, 0.0, 0.0],
    "initial_velocity": [0.0, 0.0, 0.0],
    "initial_covariance_diagonal": [30.0, 30.0, 30.0, 0.1, 0.1, 0.1, 0.01, 1.0],
    "process_noise_velocity": 0.5,
    "process_noise_attitude": 0.00001,
    "process_noise_baro_bias": 1.0,
    "measurement_noise_uwb": 0.1,
    "measurement_noise_baro": 10.0,
    "standby_min_ranges": 10,
    "max_uncertainty": 10.0
  },
  "devices": {
    "uav": {
      "transport": {
        "type": "udp",
        "udp": {
          "listen_ip": "0.0.0.0",
          "listen_port": 14554,
          "socket_buffer_size": 2097152,
          "receive_timeout_ms": 1000
        },
        "serial": {
          "device": "/dev/ttyAMA4",
          "baudrate": 115200,
          "flow_control": false,
          "receive_timeout_ms": 1000
        }
      },
      "mavlink": {
        "expected_system_id": 1,
        "expected_component_id": 1
      },
      "message_filter": {
        "enabled": true,
        "allowed_message_ids": [31, 32, 61, 105, 111]
      },
      "heartbeat": {
        "interval_ms": 1000,
        "enabled": true
      },
      "message_request": {
        "interval_ms": 1000,
        "enabled": true,
        "requested_messages": [
          {
            "message_id": 31,
            "rate_hz": 20
          },
          {
            "message_id": 105,
            "rate_hz": 20
          }
        ]
      }
    },
    "uwb1": {
      "transport": {
        "type": "udp",
        "udp": {
          "listen_ip": "0.0.0.0",
          "listen_port": 14551,
          "socket_buffer_size": 2097152,
          "receive_timeout_ms": 1000
        },
        "serial": {
          "device": "/dev/ttyAMA3",
          "baudrate": 115200,
          "flow_control": false,
          "receive_timeout_ms": 1000
        }
      },
      "mavlink": {
        "expected_system_id": 1,
        "expected_component_id": 25
      },
      "message_filter": {
        "enabled": true,
        "allowed_message_ids": [111, 42010, 42011, 42012, 42013]
      },
      "heartbeat": {
        "interval_ms": 1000,
        "enabled": true
      },
      "message_request": {
        "interval_ms": 3000,
        "enabled": false,
        "requested_messages": []
      }
    },
    "uwb2": {
      "transport": {
        "type": "udp",
        "udp": {
          "listen_ip": "0.0.0.0",
          "listen_port": 14552,
          "socket_buffer_size": 2097152,
          "receive_timeout_ms": 1000
        },
        "serial": {
          "device": "/dev/ttyAMA2",
          "baudrate": 115200,
          "flow_control": false,
          "receive_timeout_ms": 1000
        }
      },
      "mavlink": {
        "expected_system_id": 1,
        "expected_component_id": 26
      },
      "message_filter": {
        "enabled": true,
        "allowed_message_ids": [111, 42010, 42011, 42012, 42013]
      },
      "heartbeat": {
        "interval_ms": 1000,
        "enabled": true
      },
      "message_request": {
        "interval_ms": 3000,
        "enabled": false,
        "requested_messages": []
      }
    }
  }
}

8.3. Блок `logging` — текстовый лог

Параметр	Тип	Назначение / рекомендации
`level`	string	Уровень логирования: `trace`, `debug`, `info`, `warn`, `error`. Для эксплуатации — `info`; для отладки — `debug`.
`console_output`	bool	Вывод в консоль. На стендах удобно `true`.
`file_output`	bool	Запись в файл. Рекомендуется `true`.
`file_path`	string	Путь к файлу. Рекомендуем абсолютный: `/home/uwblandle/logs/uwb_landing_system.log`.
`colored_output`	bool	Цветной вывод в консоль.
`include_timestamp`	bool	Метка времени в строках лога.
`include_thread_id`	bool	ID потока в логах (полезно для отладки).
`max_log_files`	int	Количество файлов ротации.
`max_log_size_mb`	int	Размер одного файла для ротации.

Убедитесь, что каталог /home/uwblandle/logs/ существует и владелец — uwblandle:uwblandle.

8.4. Блок `binary_logging` — двоичный трейс

Параметр	Тип	Назначение / рекомендации
`enabled`	bool	Включение бинарного лога (быстрый трейс входов/выходов).
`file_path`	string	Рекомендуем абсолютный путь `/home/uwblandle/logs/uwb_landing_system.bin`.
`buffer_size`	int	Размер буфера (событий/байтов — по реализации). 10 000 — типично.
`flush_interval_ms`	int	Интервал сброса буфера на диск.
`log_inputs` / `log_outputs`	bool	Сохранять входящие/исходящие MAVLink-фреймы.
`max_log_files` / `max_log_size_mb`	int	Политика ротации бинарных логов.

8.5. Блок `timesync` — синхронизация времени

Параметр	Тип	Назначение / рекомендации
`enabled`	bool	Включить TIMESYNC для LE↔FCU и LE↔ридеры.
`sync_rate_hz`	float	Частота синхронизации. Рекомендовано: 2.0 Гц (каждые 500 мс) — согласовано с Разделом 5.
`sample_window`	int	Размер окна оценивания смещения/RTT.
`max_rtt_ms`	float	Фильтр по максимальному RTT (устраняет выбросы).
`min_samples_for_sync`	int	Минимум валидных образцов для статуса «синхронизировано».
`sync_timeout_sec`	float	Тайм‑аут ожидания прогресса синхронизации.
`max_offset_ms`	float	Максимально допустимый сдвиг часов до предупреждения.
`max_abs_time_diff_ms`	float	Абсолютное критическое расхождение (десинхронизация).

8.6. Блок `system` — MAVLink‑идентификация LE

Параметр	Тип	Описание
`system_id`	int	System ID LE. Внимание: избегайте конфликта с FCU (обычно FCU=1). Практика — LE в диапазоне 12–127.
`component_id`	int	Component ID LE. 191 — типичный “onboard computer”.

8.7. Блок `buffering` — очереди и старение данных

Параметр	Тип	Описание
`packet_buffer_size`	int	Размер внутренней очереди входящих пакетов.
`drop_threshold_ms`	int	Порог «старения» пакета, по которому он отбрасывается.

8.8. Блок `estimator` — фильтр/оцениватель положения

Параметр	Тип	Назначение / рекомендации
`enabled`	bool	Включает алгоритм слияния (UWB + инерциальные данные).
`update_rate_hz`	int	Частота обновления состояния (типично 50 Гц).
`output_rate_hz`	int	Частота публикации результатов (например, 20 Гц). `LANDING_TARGET` можно выдавать с 8 Гц.
`site_status_timeout_sec`	int	Тайм‑аут давности `UWB_SITE_STATUS` до деградации.
`initial_position`	[x,y,z]	Начальная позиция (м).
`initial_velocity`	[vx,vy,vz]	Начальная скорость (м/с).
`initial_covariance_diagonal`	array	Диагональ начальной ковариации (длина 8).
`process_noise_velocity`	float	Процессный шум скорости.
`process_noise_attitude`	float	Процессный шум ориентации.
`process_noise_baro_bias`	float	Шум дрейфа барометрического биаса.
`measurement_noise_uwb`	float	Дисперсия UWB‑измерений (м). 0.1 — агрессивно, для хорошего LOS.
`measurement_noise_baro`	float	Дисперсия баро (м).
`standby_min_ranges`	int	Минимальное количество измерений от UWB ридеров для выхода из режима ожидания.
`max_uncertainty`	float	Порог максимальной неопределённости решения.

8.9. Блок `devices` — каналы связи

Каждый подпункт (uav, uwb1, uwb2) содержит одинаковые под‑блоки: transport, mavlink, message_filter, heartbeat, message_request.

8.9.1. Общие поля устройства

transport.type — udp или serial.
- udp.listen_ip, udp.listen_port, udp.socket_buffer_size, udp.receive_timeout_ms
- serial.device, serial.baudrate, serial.flow_control, serial.receive_timeout_ms
mavlink.expected_system_id / expected_component_id — верификация источника.
message_filter.enabled / allowed_message_ids — белый список ID.
heartbeat.enabled / interval_ms — параметры HEARTBEAT с данной стороны.
message_request.enabled / interval_ms / requested_messages — периодические запросы сообщений/частот.

8.9.2. `devices.uav` — вход от автопилота (FCU)

Транспорт: UDP (0.0.0.0:14554) или Serial (/dev/ttyAMA4 @ 115200).
Ожидание FCU: expected_system_id=1, expected_component_id=1.
Фильтр: allowed_message_ids=[31, 32, 61, 105, 111]
- 31 — ATTITUDE_QUATERNION
- 32 — LOCAL_POSITION_NED (опционально)
- 61 — (историческое/зарезервированное; можно исключить, если не используется)
- 105 — HIGHRES_IMU
- 111 — TIMESYNC
Запросы: ATTITUDE_QUATERNION и HIGHRES_IMU по 20 Гц.

Если FCU не выдаёт LOCAL_POSITION_NED, ID 32 можно удалить из фильтра.

8.9.3. `devices.uwb1` / `devices.uwb2` — входы от ридеров

Транспорт: UDP (14551/14552) или Serial (/dev/ttyAMA3//dev/ttyAMA3 @ 115200).
Ожидаемые компоненты: component_id=201 и 202 (разделяют два ридера).
Фильтр: allowed_message_ids=[111, 42010, 42011, 42012, 42013]
- 111 — TIMESYNC
- 42010 — UWB_READER_CONFIG
- 42011 — UWB_SITE_STATUS
- 42012 — UWB_RANGE
- 42013 — UWB_SITE_ANNOUNCE
HEARTBEAT: enabled=true, interval_ms=1000 (1 Гц).

8.10. Рекомендуемые изменения под согласованную логику (Раздел 5)

timesync.sync_rate_hz → 2.0 (каждые 500 мс), чтобы соответствовать характеристикам из Раздела 5.7.
Превращать относительные пути логов в абсолютные (в каталог /home/uwblandle/logs/).
Проверить уникальность system.system_id относительно FCU (обычно FCU=1; LE назначить, например, 12).
Убедиться, что пользователь uwblandle состоит в группе dialout для доступа к UART.

8.11. Типовые ошибки и проверки

Симптом	Что проверить	Как исправить
LE не читает конфиг	Путь в ключе `-c`; права доступа; валидность JSON	Указать правильный путь; `chown/chmod`; проверить JSON через `jq`
Нет логов	Каталог логов отсутствует; относительные пути	Создать `/home/uwblandle/logs/`; заменить на абсолютные пути
TIMESYNC «не готов»	Недостаточная частота; перегрузка канала	Установить 2.0 Гц; проверить RTT и UART/UDP тайм‑ауты
Нет `UWB_RANGE`	Фильтр сообщений; `expected_component_id`	Добавить 42012; сверить comp_id ридеров (25/26)
Конфликт sysid	FCU и LE оба `system_id=1`	Задать LE `system_id` ≠ 1 (например, 12)

8.12. Примеры корректных фрагментов

8.12.1. TIMESYNC 2 Гц

"timesync": {
  "enabled": true,
  "sync_rate_hz": 2.0,
  "sample_window": 10,
  "max_rtt_ms": 100.0,
  "min_samples_for_sync": 3,
  "sync_timeout_sec": 5.0,
  "max_offset_ms": 60000.0,
  "max_abs_time_diff_ms": 3600000.0
}

8.12.2. Абсолютные пути логов

"logging": {
  "level": "info",
  "console_output": true,
  "file_output": true,
  "file_path": "/home/uwblandle/logs/uwb_landing_system.log",
  "colored_output": true,
  "include_timestamp": true,
  "include_thread_id": false,
  "max_log_files": 5,
  "max_log_size_mb": 20
},
"binary_logging": {
  "enabled": true,
  "file_path": "/home/uwblandle/logs/uwb_landing_system.bin",
  "buffer_size": 10000,
  "flush_interval_ms": 100,
  "log_inputs": true,
  "log_outputs": true,
  "max_log_files": 5,
  "max_log_size_mb": 20
}

8.13. Размещение файла конфигурации

Фактический путь задаётся при запуске LE. В проекте принят путь:
/home/uwblandle/config/config.json

Каталог должен существовать и быть доступен для чтения пользователю uwblandle. При использовании systemd убедитесь, что WorkingDirectory указывает на /home/uwblandle, чтобы относительные пути внутри JSON (если они остаются) интерпретировались корректно.

Конец раздела 8.

8. Конфигурирование ПО Raspberry Pi (LE)

8.1. Назначение и общие положения

8.1.1. Пример ручного запуска

8.2. Исходный JSON‑файл конфигурации (эталон)

8.3. Блок logging — текстовый лог

8.4. Блок binary_logging — двоичный трейс

8.5. Блок timesync — синхронизация времени

8.6. Блок system — MAVLink‑идентификация LE

8.7. Блок buffering — очереди и старение данных

8.8. Блок estimator — фильтр/оцениватель положения

8.9. Блок devices — каналы связи