Betaflight. Локальная сборка прошивки из исходного кода

1. Цели статьи

• Изучить архитектуру прошивки полетных контроллеров (ПК) в среде Betaflight и механизм сборки бинарных файлов.
• Развернуть и настроить подсистему Linux (WSL) в ОС Windows 10/11 для выполнения кросс-компиляции C-кода.
• Освоить работу с Git-ветками репозитория Betaflight и подгрузку целевых конфигураций betaflight/configs.
• Научиться решать реальные ошибки компилятора ARM SDK (блокировки DNS curl, отсутствие arm-none-eabi-gcc в PATH, несоответствие GCC_REQUIRED_VERSION).
• Научиться извлекать параметры Cloud Build из логов Betaflight Configurator и воспроизводить их локально через консоль make.
• Обеспечить 100% независимость от сетевых ресурсов, серверов в США и интернет-соединения при подготовке дронов.

2. Базовый контекст и концепция автономной сборки

Стандартный процесс прошивки полетного контроллера через Betaflight Configurator опирается на облачный сервис компиляции. Когда пользователь выбирает версию прошивки и список функций (OSD, GPS, DSHOT, Pin IO), Configurator отправляет запрос на удаленный сервер в США, где происходит сборка бинарного .hex-файла, возвращаемого по сети.

В условиях работы в полевых зонах, при радиоэлектронных помехах или ограничении доступа к внешним ресурсам эта схема перестает работать. Локальная компиляция полностью решает эту проблему: прошивка собирается непосредственно на процессоре вашего ПК всего за 5–15 секунд без использования сети.

Материалы и документация

Для работы используются официальные открытые репозитории проекта Betaflight:

• Основной код Betaflight Firmware: https://github.com/betaflight/betaflight.git
• Репозиторий целевых конфигураций плат: https://github.com/betaflight/configs.git

3. Подтема 1: Установка и запуск среды WSL

Развертывание подсистемы WSL

Исходный код Betaflight написан на языке C и рассчитан на сборку с помощью GNU Toolchain (GCC ARM). Наиболее удобной и стабильной средой для выполнения этой задачи в ОС Windows является подсистема WSL (Windows Subsystem for Linux).

Для установки подсистемы Linux в Windows 10/11 достаточно запустить Командную строку или PowerShell от имени администратора и выполнить единственную команду:

# Установка WSL и дистрибутива Ubuntu по умолчанию
wsl --install

Проверка дистрибутива

После перезагрузки системы и создания логина/пароля пользователя Linux введите команду wsl для входа в консоль. Для проверки установленного дистрибутива выполните:

# Вывод информации о релизе ОС Linux
cat /etc/os-release

Типичные ошибки при работе с WSL

4. Подтема 2: Настройка окружения и скачивание исходного кода

Установка зависимостей Linux

Перед сборкой исходного кода необходимо установить базовые утилиты сборки, компилятор Clang, Git и Python. В Linux все зависимости устанавливаются одной консольной командой:

# Обновление индекса пакетов и установленных программ
sudo apt update && sudo apt upgrade -y

# Установка необходимых утилит компиляции и системного компилятора ARM
sudo apt install -y build-essential git curl clang gcc python3 gcc-arm-none-eabi libnewlib-arm-none-eabi

Клонирование Git-репозитория и выбор стабильной ветки

Создадим директорию проектов ~/proj и выполним клонирование целевой стабильной ветки. Ветка master содержит нестабильный код, поэтому рекомендуется использовать релизные ветки серии maintenance.

# Создание и переход в папку проектов
cd ~/
mkdir -p proj
cd proj

# Клонирование только стабильной релизной ветки
git clone --single-branch --branch "2025.12-maintenance" https://github.com/betaflight/betaflight.git

# Переход в каталог с исходным кодом
cd betaflight

Типичные ошибки при загрузке кода

5. Подтема 3: Подготовка ARM SDK и решение ошибок тулчейна

Установка кросс-компилятора ARM и конфликт версий GCC

Для компиляции кода под ARM-архитектуру полетных контроллеров (STM32 / AT32) требуется тулчейн gcc-arm-none-eabi. При использовании стандартной команды Betaflight make arm_sdk_install утилита пытается скачать архив с внешнего сервера developer.arm.com. В случае блокировок или сбоев DNS возникает ошибка curl: (6) Could not resolve host.

Наиболее надежным решением является установка системного пакета из репозиториев Ubuntu:

# Установка системного пакета кросс-компилятора ARM
sudo apt update
sudo apt install -y gcc-arm-none-eabi libnewlib-arm-none-eabi

# Проверка установленной версии компилятора
arm-none-eabi-gcc --version

Подгрузка базы конфигураций таргетов и обход проверки версий

Betaflight проверяет соответствие версии компилятора макросу GCC_REQUIRED_VERSION (например, ожидает 13.3.1, а системный пакета APT устанавливает 13.2.1). Для устранения конфликта версий достаточно переопределить требование к версии в локальном файле mk/local.mk:

# Обновление подмодуля конфигураций полетных контроллеров (>650 таргетов)
make configs

# Фиксация используемой версии GCC в локальном файле конфигурации
echo "GCC_REQUIRED_VERSION := 13.2.1" > mk/local.mk

# Первичная сборка прошивки под таргет HAKRCF405V2 с модулями GPS и LED
make HAKRCF405V2 EXTRA_FLAGS="-DUSE_GPS -DUSE_LED_STRIP"

Мы собрали прошивку, которую теперь можно загрузить через Betaflight Configurator локально, без наличия интернет соединения. 

Разбор практических ошибок сборки

6. Подтема 4: Воспроизведение онлайн-сборки и кастомизация

Извлечение параметров из Betaflight Configurator

При сборке онлайн Betaflight Configurator генерирует массив флагов предпроцессора C. Их можно скопировать из ссылки на лог сборки (Build Log) в окне Configurator. Пример аналогичного вызова команды make на локальном ПК:

# Воспроизведение полного набора облачных флагов сборки для HAKRCF405V2
make HAKRCF405V2 EXTRA_FLAGS="-D'BUILD_KEY=213cf822cf423b1f9c0b05ead8ec33fd' -D'RELEASE_NAME=2025.12.5' -DCLOUD_BUILD -DUSE_DSHOT -DUSE_OSD -DUSE_OSD_SD -DUSE_PINIO -DUSE_SERIALRX -DUSE_SERIALRX_CRSF -DUSE_SERVO -DUSE_TELEMETRY -DUSE_TELEMETRY_CRSF -DUSE_VTX"

Кастомизация названия релизов и флагов C

Локальная сборка позволяет менять значения системных макросов, например имя релиза (RELEASE_NAME) и уникальный ключ сборки (BUILD_KEY), что позволяет маркировать партийные прошивки:

# Кастомная сборка с изменением системных тегов
make HAKRCF405V2 EXTRA_FLAGS="-D'RELEASE_NAME=technobee' -D'BUILD_KEY=it_is_custom_firmware' -DCLOUD_BUILD -DUSE_DSHOT -DUSE_LED_STRIP -DUSE_OSD -DUSE_OSD_SD -DUSE_PINIO -DUSE_SERVO -DUSE_RANGEFINDER -DUSE_SERIALRX -DUSE_SERIALRX_CRSF -DUSE_VTX"

После прошивки сформированного файла obj/betaflight_HAKRCF405V2.hex в полетный контроллер, команда status в консоли CLI выведет ваши кастомные идентификаторы.

Типичные ошибки передачи параметров EXTRA_FLAGS

7. Практика: типовые задачи (с решениями)

Блок задач 1: Подготовка универсальных прошивок СВО и Walksnail

# Решение задачи 1
cd ~/proj/betaflight
make HAKRCF405V2 EXTRA_FLAGS="-DCLOUD_BUILD -DUSE_DSHOT -DUSE_OSD -DUSE_PINIO -DUSE_SERIALRX -DUSE_SERIALRX_CRSF -DUSE_SERVO -DUSE_VTX"
# Результат: Файл obj/betaflight_HAKRCF405V2.hex готов к автономной прошивке

# Решение задачи 2
cd ~/proj/betaflight
make MATEKF405TE EXTRA_FLAGS="-DCLOUD_BUILD -DUSE_DSHOT -DUSE_OSD -DUSE_OSD_HD -DUSE_SERIALRX -DUSE_SERIALRX_CRSF -DUSE_TELEMETRY_CRSF -DUSE_VTX"
# Результат: Сформирован бинарник с поддержкой HD OSD протокола

Блок задач 2: Обход несоответствия версий GCC и кастомный релиз

# Решение задачи 3
cd ~/proj/betaflight

# Фиксируем установленную версию GCC в файле mk/local.mk
echo "GCC_REQUIRED_VERSION := 13.2.1" > mk/local.mk

# Запускаем компиляцию
make HAKRCF405V2 EXTRA_FLAGS="-D'RELEASE_NAME=spec_unit_1' -DCLOUD_BUILD -DUSE_DSHOT -DUSE_OSD -DUSE_PINIO -DUSE_SERIALRX_CRSF -DUSE_VTX"

# Скопировать HEX файл из obj/ в Windows и прошить через Betaflight Configurator (Локальная прошивка)
# В CLI Betaflight выполнить:
# status
# В ответе терминала будет указано: MCU STM32F405, Release: spec_unit_1

8. Чек-лист самопроверки знаний

Отметьте пункты, которые вы действительно понимаете и можете выполнить на практике без сторонних подсказок.