Збірка, прошивання та налагодження

Коли код вже написаний, є три різні дії: перевірити його, зібрати ELF і записати на пристрій. А якщо запуск планується через Keira — ще перетворити ELF в application .bin. Це не одна й та сама команда.

Спочатку перевірка

З теки потрібного прикладу:

cargo +esp check --locked
cargo +esp build --release --locked

check швидший, але остаточне компонування прошивки не перевіряє. Помилка лінкера може з'явитись тільки під час build. Тому перед запуском потрібна повна збірка.

У workspace ELF лежить у спільному target/xtensa-esp32s3-none-elf/release/. У власному окремому проєкті — в його target/. ELF без розширення .bin містить ще й інформацію, потрібну інструментам налагодження.

Пряме прошивання

У готових прикладах runner налаштований на probe-rs:

cargo +esp run --release --locked

Це вже запис на пристрій, а не симулятор. Для підключення потрібні доступ до відповідного USB debug-інтерфейсу та права на нього. У Linux проблеми прав вирішуються правилами udev для встановленого інструмента; постійно запускати всю збірку через sudo не треба.

Якщо прошивальник взагалі не бачить пристрій, перевірте кабель з передачею даних, USB-порт і режим завантаження. Якщо запис проходить, але програма падає, це вже інша проблема — дивіться panic та boot-лог.

Application bin для KeiraOS

Потрібен встановлений cargo-espflash:

cargo install cargo-espflash --locked

З теки пакета, наприклад examples/basics/:

cargo +esp espflash save-image --release --chip esp32s3 basics.bin

Команда збирає та конвертує програму у файл. Окремий скрипт для цього не потрібен. Не додавайте --merge: для Keira MultiBoot потрібен застосунок, без bootloader та таблиці розділів.

Якщо встановлений тільки звичайний espflash, можна зберегти вже зібраний ELF. Для examples/basics/ у цьому workspace:

espflash save-image --chip esp32s3 \
  ../../target/xtensa-esp32s3-none-elf/release/basics basics.bin

Скопіюйте .bin на microSD й запустіть його через Keira. Це окрема прошивка: MultiBoot записує її в OTA-розділ і перезапускає ESP32-S3. Вона не виконується поряд з Keira як процес і не може просто викликати її C++-об'єкти.

Саме тому RTC успадковується через збережений апаратний стан, а SD, дисплей та кнопки застосунок ініціалізує власним SDK. Умови для часу описані окремо.

Логи та panic

У прикладах використовується esp-println, а залежності мають defmt. Залиште відповідні features та defmt.x у build.rs, якщо не плануєте свідомо змінити спосіб логування.

Друкуйте не тільки «щось зламалось», а й етап: початок main, завершення ініціалізації, монтування карти, початок запису, результат закриття. Це допомагає відрізнити проблему файлової системи від падіння ще до запуску вашого коду.

Велика кількість логів у циклі теж уповільнює програму. Для частих подій краще друкувати тільки зміни стану або зводити статистику раз на секунду.

Типові помилки

Немає тулчейна esp або Xtensa GCC. Перевірте espup install і підключення shell-оточення, яке створив espup. Для Linux це часто пропущений крок після встановлення, а не проблема SDK.

Конфлікт blocking та async. Перевірте default-features = false і що ви збираєте один пакет. Коли треба зрозуміти, звідки прийшов feature, виконайте cargo +esp tree -e features -i lilkaoxide з теки цього пакета.

Немає global allocator. Сам build-std = ["alloc", "core"] його не створює. Зокрема, поточний SD-драйвер безумовно підключає alloc, навіть коли виконуваний код не виділяє пам'ять. Це вимога компонування, а не доказ потреби SD у heap. Можна використати звичайний allocator з ініціалізованим heap, як у прикладах, або allocator, який відмовляє в алокаціях, якщо весь виконуваний код обходиться без них. Докладніше — пояснення SD та alloc.

Переповнення RAM або стека. Перевірте великі локальні масиви, framebuffer та кількість задач. Зменшення зображення до смуги іноді дає більше, ніж довге налаштування оптимізатора. Детальніше — пам'ять.

Дисплей працює, SD ні. Перевірте lilka.sd, частоту SPI, MBR і FAT16/FAT32. Успішний Lilka::init не означає, що карта обов'язково є.

Перевірка самої документації

З кореня репозиторію:

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r requirements-docs.txt
.venv-docs/bin/mkdocs serve

Для остаточної перевірки — .venv-docs/bin/mkdocs build --strict. Код навчальних програм вставляється прямо з examples/, тому після його зміни треба перевірити і збірку прошивки, і сторінку. На Windows executables цього venv лежать у .venv-docs\Scripts\.