ПО для разработки

Для программирования Доски H723 понадобятся компилятор и утилиты ST, CMake, Git и Python 3. Редактор — любой; для VSCode в проекте уже есть задачи сборки, прошивки и отладки.

Что установить

STM32CubeCLT 1.18 или новее — компилятор arm-none-eabi-gcc, CMake, Ninja, STM32_Programmer_CLI и GDB-сервер. Все эти программы должны быть в PATH.
STM32CubeMX — генератор кода периферии; нужен, только если меняются выводы, такты или DMA.
Git и Python 3 — для скриптов прошивки и сборки архива SD-карты.
Visual Studio Code и расширения:
- C/C++ — подсветка и навигация по коду;
- CMake Tools — сборка из редактора;
- Cortex-Debug — прошивка и отладка из редактора.

Получение исходников

Сторонние библиотеки подключены как git submodule, поэтому после клонирования их нужно скачать:

git clone https://github.com/Kits-Lab-Dev/Board-H723.git
cd Board-H723
git submodule update --init

Архив zip для сборки не подходит: в нём нет сторонних библиотек.

На Windows:

перед клонированием включите длинные пути: git config --global core.longpaths true, иначе часть файлов wolfSSL не создастся;
клонируйте в короткий путь, например C:\src\Board-H723: при длинном пути CMake предупреждает о пределе в 250 символов на путь объектного файла.

Что в репозитории

В папке examples два проекта:

BoardH723 — готовый проект для платы:
- драйвер Wi-Fi и BLE (ESP32-C2 по SPI с DMA), совместимый с сокетами Unix;
- USB-NCM (USB-Ethernet) и DHCP-сервер для USB и точки доступа Wi-Fi;
- FreeRTOS и FreeRTOS+TCP;
- FatFs: microSD (/SD) и RAM-диск в SDRAM (/RAM), менеджер памяти SDRAM;
- SSH-сервер с SFTP (загрузка файлов на SD-карту) и терминалом;
- интерпретатор Lua: GPIO, SPI, I2C, UART, потоки, Wi-Fi, сокеты, HTTPS;
ESP-Loader — мост USB-UART для прошивки ESP32-C2 через STM32.

Рядом лежат рецепты — готовые модули на C, docs/board.md с описанием железа для прошивки и tools/ со скриптами. Состав и лицензии сторонних библиотек — THIRD_PARTY.md.

Сборка

cd examples/BoardH723
cmake --preset Release
cmake --build build/Release

Результат — build/Release/BoardH723.elf, .hex и .bin; ELF содержит отладочную информацию. Собирается GCC 13 (из STM32CubeCLT) и GCC 14 (Arm GNU Toolchain).

Опции CMake добавляются к первой команде:

Опция	Что делает
`-DH723_WITH_SSH=OFF`	убирает SSH и SFTP
`-DH723_WITH_TLS=OFF`	убирает HTTPS для Lua
`-DH723_WITH_LUA=OFF`	убирает Lua целиком, вместе с HTTPS для него — освобождается Flash под LVGL
`-DH723_IDLE_SLEEP=ON`	в простое ядро засыпает командой WFI: кристалл остывает с 66 до 51 °C
`-DH723_RECIPES="a;b"`	подключает рецепты, список

Размер прошивки при GCC 13: около 808 КБ со всем, 629 КБ без SSH, 530 КБ без SSH и TLS; без Lua, но с SSH — 482 КБ.

Сборка и отладка из VSCode

Откройте папку examples/BoardH723. CMake Tools предложит выбрать пресет — выберите Release.
При настройке проекта CMake создаёт в .vscode файлы tasks.json и launch.json из шаблонов tasks.json.in и launch.json.in:
- задача build — сборка;
- задача DFU Upload — сборка и запись прошивки через STM32_Programmer_CLI по USB DFU;
- конфигурация отладки stlink для Cortex-Debug.
В переменной среды STM32CLT_PATH должен быть путь к STM32CubeCLT: по нему конфигурации находят программатор и файл описания регистров STM32H723.svd.

Прошивка

По USB, без кнопок и отладчика. Плата подключена кабелем USB-C, в ней работает прошивка из этого проекта:

python tools/dfu_flash.py

Скрипт отправляет плате UDP-пакет dfu, плата перезагружается в системный загрузчик STM32, скрипт записывает build/Release/BoardH723.hex, запускает прошивку и ждёт ответа на ping — около 40 секунд. Другой файл: python tools/dfu_flash.py путь/к/файлу.hex.

Если плата не отвечает (нет USB-сети, прошивка старая или зависла): зажмите BOOT, нажмите RESET (или переподключите USB), отпустите BOOT — плата входит в DFU — и запустите скрипт ещё раз. На Windows для DFU нужен драйвер STM32 DFU, он ставится вместе со STM32CubeProgrammer; устройство в диспетчере называется «STM32 BOOTLOADER».

Отладчик «Лобзик» по SWD (разъём J6) — прошивка, чтение памяти и регистров на работающей плате, разбор HardFault, лог USART1: навык и скрипты.

Модуль ESP32-C2 прошивается через STM32 командой reboot esploader в SSH (или rtos.reboot("esploader") в Lua): плата запускает мост ESP-Loader с SD-карты, и на ПК появляется USB-UART для esptool. Прошивка модуля — проект esp32c2phy, собирается ESP-IDF 5.4.

SD-карта

Плата работает и без карты, но SSH, Lua и многие рецепты используют её. Содержимое карты — файлы из examples/BoardH723/app/SD (скрипт загрузки boot.lua, библиотеки Lua, шрифты, utils/ESPLoader.bin):

готовый архив sd-card.zip лежит в релизах; его распаковывают в корень карты FAT32;
собрать архив самостоятельно: python tools/make_sd_zip.py (результат — build/sd-card.zip);
на работающую плату файлы заливаются по SFTP в /SD/.

Вход по SSH

Плата в USB-сети — 192.168.4.1, вход ssh root@192.168.4.1; по Wi-Fi — на адрес, выданный роутером (команда ip в терминале).

Пароль при первом запуске плата создаёт сама, сохраняет в файл /SD/.ssh/password на SD-карте и печатает в лог (USART1). Сменить пароль — исправить этот файл и перезагрузить плату. Без карты войти по паролю нельзя.

Вход по ключу: создайте пару ssh-keygen -t rsa -b 4096, скопируйте открытый ключ на карту в /SD/.ssh/mcu.key.pub и входите командой ssh root@192.168.4.1 -i ~/.ssh/mcu.key. Пока на карте есть этот файл, вход по паролю выключен.

Команды терминала: help, ls, cat, cd, top, ip, reboot (reboot dfu — в загрузчик USB, reboot esploader — режим прошивки ESP32-C2), lua -f /SD/x.lua, exit. Терминал режет аргументы по пробелам и не понимает кавычки — Lua-код запускайте файлом.

Lua

Lua — дополнительный интерпретатор для быстрых опытов; основной язык проекта — C. Скрипты кладут на SD-карту и запускают командой lua -f /SD/x.lua; /SD/boot.lua выполняется при загрузке. Описание модулей — в репозитории, в examples/BoardH723/libs/lua/docs: pio (GPIO, ШИМ, АЦП), serial, spi, i2c, lthread, wifi, rtos.

Рецепты

Готовые модули на C — кнопка, UART с DMA, датчик на I2C, Wi-Fi и HTTP, скорость TCP, файлы на SD, задачи FreeRTOS, дисплей и LVGL — с объяснением, как они устроены: Рецепты для Доски H723. Подключаются к проекту BoardH723 одной опцией CMake и не требуют правки его кода.

Свой код и CubeMX

Своё приложение проще всего начать с ближайшего рецепта. Иначе — файлы в app/ или libs/<имя>/, добавленные в target_sources и board_includes в CMakeLists.txt. Новые задачи FreeRTOS создаются из appTask (app/app.c) после запуска нужных подсистем.
В файлах, созданных CubeMX (Core/, Drivers/), правьте только внутри блоков /* USER CODE BEGIN ... */ ... /* USER CODE END ... */ — остальное перезаписывается при генерации. Такты, выводы, MPU, DMA и периферию меняют в BoardH723.ioc и генерируют код заново.
Выводы SDRAM, microSD, ESP32-C2 и USB разведены на плате — не переназначайте их (таблица занятых выводов). MPU-регион SDRAM должен остаться «не Shareable».
Внутренней памяти мало: большие буферы берите из SDRAM (sdramMalloc) или из кучи FreeRTOS (pvPortMalloc; malloc уже перенаправлен в неё).
Сторонние библиотеки в third_party/ не правятся: настройки лежат в config/, неизбежные правки — в cmake/patch_source.cmake.
В коде проекта (app/, libs/, Core/, recipes/) неявное объявление функции, смешение указателя с целым и return без значения — ошибки сборки: объявляйте функции в заголовках.
Лог выводится в USART1 (115200 8N1, PB14 TX / PB15 RX; разъём J6 и J2); макросы INF, WRN, ERR из app/log.h.