Порт Arduboy2 для SF32LB52¶

Что такое Arduboy2-SiFli?¶

OpenSiFli/Arduboy2-SiFli — порт библиотеки Arduboy2, поддерживаемый OpenSiFli для среды разработки SiFli. Arduboy2 задаёт модель приложения для компактного игрового устройства: цикл кадров, буфер дисплея, кнопки, спрайты, текст и, при необходимости, управление звуком. Поэтому порт SiFli полезен как проверка совместимости: он позволяет оценить, какую часть игры в стиле Arduboy можно сохранить при адаптации платы, дисплея, ввода, аудио и процесса сборки для SF32.

Репозиторий содержит референсную программную реализацию, а не готовую игровую консоль или проект аппаратуры для производства. README, дерево исходного кода, примеры, история issues и файлы лицензий служат основными источниками сведений о целевой плате, поддерживаемых API, инструкциях сборки и условиях распространения. Эта страница систематизирует инженерные решения для этой реализации, но не заменяет исполняемые инструкции из репозитория.

Зачем нужен этот порт для SF32?¶

Приложение в стиле Arduboy позволяет в компактном примере проверить сразу несколько проектных решений для встраиваемого устройства: предсказуемый цикл отрисовки, небольшие монохромные или низкого разрешения ресурсы, ввод кнопками, временные характеристики аудио и ограниченный бюджет памяти. Перенос этой модели на SF32 может стать отправной точкой для портативных игр, демонстраторов интерфейса, учебных устройств и других продуктов с локальным и предсказуемым взаимодействием.

Ценность порта не в том, что любой скетч для Arduboy заработает без изменений, а в том, что он показывает границы совместимости:

• Игра может сохранить высокоуровневую логику обновления, ввода, рисования и работы с ресурсами, если она использует только поддерживаемый API Arduboy2.
• Порт должен адаптировать предположения о дисплее, кнопках, аудио, временных интервалах и хранении данных, которые были заложены в исходное оборудование.
• Любой скетч, напрямую работающий с регистрами AVR, специальными выводами Arduboy, транзакциями дисплея, таймерами или структурой EEPROM, требует осознанной адаптации и отдельного подтверждения регрессионными тестами.

Это инженерные ожидания, а не подтверждённые измерениями заявления о совместимости. Сверьте их с актуальной версией репозитория OpenSiFli и зафиксируйте результат для выбранных платы и коммита.

Результат, область применения и условия начала¶

На этой странице описан поэтапный путь от примера OpenSiFli к воспроизводимой игре или интерактивной демонстрации на SF32. Она не утверждает, что порт поддерживает все возможности Arduboy2, любые игры Arduboy или платы SF32, и не гарантирует временные характеристики дисплея и аудио производственного уровня. Страница также не предоставляет лицензий на игры, шрифты, графику и другие ресурсы из сторонних репозиториев.

Ожидаемый результат: сборка Arduboy2-SiFli с ревизией исходников, зафиксированной в системе контроля версий, которая запускает один пример из репозитория или небольшой тестовый скетч, подтверждает работу выбранных трактов дисплея, ввода и аудио и фиксирует результаты для решения о целесообразности разработки более крупной игры или адаптации продукта.

Для кого: инженеры по прошивке, аппаратуре и продукту, умеющие работать с инструментами Arduino, читать код C/C++, загружать прошивку в плату SF32, анализировать последовательный вывод и выполнять базовые измерения дисплея, ввода и питания.

Перед началом подготовьте:

• Отладочную плату SF32LB52 с вариантом ArduinoCore-Zephyr sf32lb52_devkit_lcd_sf32lb525uc6, а также внешние периферийные устройства, описанные ниже. В README указано, что дисплей, кнопки, внешняя EEPROM и аудиотракт проверялись на оборудовании SF32LB52. Путь для RGB-светодиода описан, но результаты его тестирования не приведены. Физическая ревизия платы и точная модель OLED-модуля также не зафиксированы.
• Заведомо работоспособную установку Arduino и соответствующий пакет плат OpenSiFli. Имя варианта задаёт программную конфигурацию и карту выводов, но не доказывает, что все физические версии SF32LB52-DevKit-LCD соответствуют внешней разводке проекта. Перед подключением периферии сверьтесь со схемой конкретной платы.
• Точный коммит Arduboy2-SiFli, версию ядра/пакета Arduino, ОС хоста и инструмент загрузки.
• USB-кабель с линиями данных и возможность сохранить последовательный журнал и наблюдать за дисплеем, кнопками и звуком.
• Права на использование и распространение всех игр, изображений, шрифтов и звуковых ресурсов, включённых в производную адаптацию.

Аппаратные и программные спецификации¶

Аппаратная спецификация¶

Программная спецификация¶

Выбор поддерживаемой базовой конфигурации¶

Начните с сочетания платы и ПО, указанного в репозитории OpenSiFli, а не выбирайте похожую плату из каталога продуктов. Пакет платы, подключение дисплея, карта ввода, способ загрузки и предположения библиотеки входят в исходную конфигурацию.

В репозитории Arduboy2-SiFli нет отдельного файла с картой выводов платы: подробная таблица опубликована в README в разделе SiFli IO mapping. Логические определения выводов библиотеки находятся в pins_sifli.h, а разводка для конкретной платы задаётся в Devicetree overlay проекта ArduinoCore-Zephyr. Эти источники описывают программную исходную конфигурацию, а не проверенную физическую сборку. Перед подключением сверьте фактическую ревизию платы и её схему.

В репозитории указаны программный вариант платы и карта выводов периферии; также сообщается, что дисплей, кнопки, внешняя EEPROM и аудиотракт проверялись на оборудовании SF32LB52. Путь для внешнего RGB-светодиода описан, но результаты его тестирования не приведены. Физическая ревизия платы, точная модель/контроллер OLED-модуля и полный комплект аксессуаров не указаны. Перед подключением или заявлением о воспроизводимости аппаратной конфигурации сверьте карту выводов варианта со схемой конкретной платы и запишите использованные компоненты и ревизии. Не заполняйте пробелы данными о выводах или адресах из другого проекта SF32.

Этапы проекта¶

Используйте этапы как точки принятия решений, а не как перечень функций.

Архитектура системы и зависимости¶

flowchart LR
    G["Игровой скетч\nобновление, ввод, отрисовка, ресурсы"] --> A["Arduboy2-SiFli\nслой совместимости"]
    A --> C["Ядро Arduino\nпакет платы и среда выполнения"]
    C --> S["SiFli-SDK / SF32\nGPIO, дисплей, таймеры, хранилище, аудио"]
    S --> H["Выбранная плата SF32\nдисплей, кнопки, динамик, USB"]
    A --> R["Эталонные тесты\nпоследовательный журнал и визуальная проверка"]

Это модель для принятия решений, а не утверждение, что в репозитории используются именно такие имена внутренних модулей. Прежде чем менять порт, проверьте фактические границы в исходном коде. Ключевые области проектирования продукта:

• Кадры и временные характеристики: игровой цикл должен обновлять и выводить кадры с повторяемой частотой; аудио и ввод, чувствительные к временным параметрам, необходимо измерить на целевой плате.
• Дисплей: слой совместимости должен сопоставить буфер и геометрию игры с выбранными контроллером дисплея, форматом пикселя, ориентацией и способом обновления.
• Ввод: имена и полярность кнопок, подавление дребезга, одновременные нажатия и поведение при пробуждении/сбросе следует проверить по разводке платы.
• Аудио: генерацию тонов, использование таймера, подключение динамика, громкость и отключение звука следует считать особенностями конкретной платы до проверки.
• Ресурсы и хранение: после компоновки выбранной игры необходимо измерить шрифты, спрайты, звуковые данные, размещение во флеш-памяти и использование RAM.
• Восстановление: перед экспериментами с временными параметрами, памятью или низким энергопотреблением сохраните проверенный способ загрузки прошивки и восстановления.

Основные области отказа — совместимость приложения/API, конфигурация дисплея, подключение ввода, работа аудио/таймеров, память и размещение ресурсов, загрузка и восстановление. Не следует сводить отказ в любой из этих областей к формулировке «порт не работает».

Этап 1 — Зафиксируйте неизменённый пример¶

Цель: проверить работоспособность базы, описанной в репозитории, прежде чем менять библиотеку или игру.

1. Прочитайте инструкции репозитория, запишите основную ветку или выпуск, изучите примеры, конфигурацию платы, зависимости и файлы лицензий.
2. Установите точные версии ядра/пакета Arduino и инструментов, требуемые репозиторием. Запишите ОС хоста и версии инструментов.
3. Соберите и загрузите самый простой документированный пример или тестовый скетч.
4. Сохраните последовательный вывод и запишите, что отображается на дисплее, как реагируют кнопки и есть ли звук в примере.

Что сохранить: коммит репозитория, версии зависимостей и пакетов, ревизию платы, сведения о подключении или схеме, результат сборки, журналы загрузки и последовательного порта, краткое описание поведения.

Критерий выхода из контрольной точки 1: исходный пример собирается и загружается на выбранную плату, а описанное поведение повторяется после сброса или цикла питания.

Этап 2 — Проверьте периферию и временные характеристики¶

Цель: отличить успешную компиляцию от базовой конфигурации, пригодной для игрового устройства.

1. Проверьте очистку дисплея, обновление полного кадра, вывод спрайта или bitmap, работу с текстом и предположения примера о геометрии/ориентации.
2. Проверьте все используемые проектом входы: отпускание и одновременное нажатие кнопок, быстрые нажатия, а также пробуждение или сброс, если применимо.
3. Если используется аудио, проверьте запуск/остановку тона, взаимодействие с таймерами, отключение звука и влияние активности дисплея и ввода на аудиотракт.
4. Прервите штатную работу сбросом, отключением/подключением кабеля и недопустимой или неполной последовательностью ввода. Запишите, возвращается ли плата в рабочее состояние для загрузки и запуска.

Что сохранить: визуальные результаты или снимки экрана, матрицу ввода, наблюдения за временными параметрами и аудио, журнал сбросов/восстановления, а также измерения тока и задержки, влияющие на решение по продукту.

Критерий выхода из контрольной точки 2: выбранный путь работы с периферией достаточно понятен, чтобы отличать ошибки приложения от проблем конфигурации платы, таймингов или питания.

Этап 3 — Создайте воспроизводимую базу исходников¶

Цель: обеспечить воспроизводимость порта без привязки к одной машине разработчика или готовому бинарному файлу.

1. Начните с чистого checkout и инициализируйте все зависимости репозитория.
2. Запишите пакет платы, версии Arduino IDE/CLI, компилятора и инструментов, файлы конфигурации и созданные ресурсы.
3. Выполните сборку в чистом каталоге, сохраните образ и доступные сведения map/size, а также команду или вывод инструмента загрузки.
4. Повторите сборку на второй машине или после удаления каталога сборки.

Что сохранить: ревизии исходников и зависимостей, сведения о хосте и инструментах, журнал сборки, бинарный файл или другой артефакт, отчёт о размере, журналы загрузки и последовательного порта.

Критерий выхода из контрольной точки 3: чистый checkout воспроизводит образ, проходящий проверки периферии этапа 2, без недокументированных локальных файлов и ручных правок.

Этап 4 — Осознанно адаптируйте одну игру¶

Цель: проверить границы совместимости одним контролируемым изменением продукта.

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

Не переносите в проект SF32 доступ к регистрам AVR, предположения о выводах исходной Arduboy или адреса хранения без инженерного решения, подтверждённого источниками. Храните лицензии сторонних игр и ресурсов рядом с адаптированным кодом; удаляйте всё, условия распространения чего неясны.

Что сохранить: проверенный diff, происхождение ресурсов, изображения до и после, журналы сборки и загрузки, результаты регрессии и образ для отката.

Критерий выхода из контрольной точки 4: адаптированная игра проходит эталонные проверки периферии; ограничения по памяти, временным параметрам, восстановлению и лицензированию записаны.

Этап 5 — Оцените готовность продукта¶

Не переходите от демонстрации порта к собственной аппаратуре или полевым испытаниям, пока команда не ответит на вопросы:

• Для каких точных моделей платы SF32, дисплея, кнопок, динамика и источника питания подтверждена работа, а что пока остаётся предположением?
• Какие частота кадров, задержка ввода, поведение аудио, время запуска и профиль тока измерены на предполагаемой базе продукта?
• Сколько flash и RAM потребляют игра, ресурсы, шрифты и среда выполнения, включая максимальный объём контента?
• Что происходит после сброса, просадки питания, его потери во время сохранения, повреждения ресурсов, неудачной загрузки прошивки или незавершённого обновления?
• Кто поддерживает разные части порта: команда продукта, OpenSiFli, SiFli или исходное сообщество Arduboy2?
• Совместимы ли лицензии всех игр, шрифтов, изображений, звуков и библиотек с предполагаемой моделью распространения?

Критерий выхода из контрольной точки 5: для оставшихся рисков назначены ответственные и собраны доказательства; для каждого риска определена мера снижения, явно согласовано отложенное решение либо принято решение остановить работу.

Передача материалов для проектирования изделия¶

Перенесите в раздел «Аппаратная часть» выбранную модель SF32, архитектуру дисплея и ввода, план аудио и таймеров, размещение флеш-памяти и ресурсов, результаты измерений энергопотребления, способ восстановления и исходные допущения для производственных испытаний. Если требования игры к дисплею, памяти, типу корпуса, питанию или подключению меняют список подходящих устройств, воспользуйтесь подбором компонентов SF32. Для подготовки программной среды начните с руководства по началу работы с Arduino, затем изучите обзор платформы Arduino.

Пример выполнил свою задачу по развитию продукта, когда другой инженер может повторно собрать порт, воспроизвести результаты проверки периферии, объяснить каждую адаптацию под конкретную плату и изучить доказательства до утверждения собственной платы или расширенной библиотеки игр.

Основные источники¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• Начало работы с Arduino на SF32
• Обзор платформы Arduino
• Подбор компонентов SF32

Последнее обновление: 2026-10-21