Merge pull request #3 from and3rson/ad/rtos-framebuffers

WIP: Rewrite main firmware into RTOS-based

.clang-format

@@ -4,23 +4,29 @@ AccessModifierOffset: -4
 AlignAfterOpenBracket: BlockIndent
 # IndentAccessModifiers: 'true'
 # AlignConsecutiveAssignments: 'true'
-# AlignConsecutiveDeclarations: 'true'
+AlignConsecutiveDeclarations:
+  Enabled: false
+AlignConsecutiveMacros:
+  Enabled: true
+  AcrossEmptyLines: true
+  AcrossComments: false
 AlignOperands: 'true'
 AllowAllParametersOfDeclarationOnNextLine: 'false'
 AllowShortCaseLabelsOnASingleLine: 'false'
-AllowShortFunctionsOnASingleLine: Empty
+AllowShortFunctionsOnASingleLine: None
 AllowShortLoopsOnASingleLine: 'false'
+AllowShortIfStatementsOnASingleLine: AllIfsAndElse
 AlwaysBreakAfterDefinitionReturnType: None
 AlwaysBreakAfterReturnType: None
 AlwaysBreakBeforeMultilineStrings: 'false'
-BinPackArguments: 'true'
-BinPackParameters: 'true'
+BinPackArguments: 'false'
+# BinPackParameters: 'false'
 ColumnLimit: '120'
 IndentCaseLabels: 'true'
 IndentPPDirectives: AfterHash
 IndentWidth: '4'
 MaxEmptyLinesToKeep: '1'
-PointerAlignment: Right
+PointerAlignment: Left
 SortIncludes: 'false'
 SpaceBeforeAssignmentOperators: 'true'
 SpaceBeforeParens: ControlStatements
@@ -33,5 +39,9 @@ ShortNamespaceLines: 0
 BreakArrays: 'true'
 ContinuationIndentWidth: 4
 ReflowComments: false
+DerivePointerAlignment: false
+# AllowShortBlocksOnASingleLine: Never
+# InsertTrailingCommas: Wrapped
+BreakConstructorInitializers: AfterColon
 
 ...

.github/workflows/code_style.yml

@@ -0,0 +1,16 @@
+name: code_style
+
+on: [push]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    container: ubuntu:24.04
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run linters
+        run: |
+          apt update -y
+          apt install -y make clang-format
+          make lint

.github/workflows/firmware_main.yml → .github/workflows/firmware_keira.yml

@@ -1,4 +1,4 @@
-name: firmware/main
+name: firmware/keira
 
 on: [push]
 
@@ -13,7 +13,7 @@ jobs:
           path: |
             ~/.cache/pip
             ~/.platformio/.cache
-            ./firmware/main/.pio
+            ./firmware/keira/.pio
           key: ${{ runner.os }}-pio
       - uses: actions/setup-python@v4
         with:
@@ -22,5 +22,5 @@ jobs:
         run: pip install --upgrade platformio
 
       - name: Build PlatformIO Project
-        working-directory: ./firmware/main
+        working-directory: ./firmware/keira
         run: pio run -e v2

Makefile

@@ -1,10 +1,68 @@
-.PHONY: reformat
-reformat:
+# .PHONY: reformat
+# reformat:
+# 	find \
+# 		./firmware-demo/src/ \
+# 		./lib/lilka \
+# 		-not \( -name .ccls-cache -prune \) \
+# 		-not \( -name .pio -prune \) \
+# 		-iname *.h \
+# 		-o -iname *.cpp \
+# 		| xargs clang-format -i
+
+all:
+	false
+
+.PHONY: todo
+todo:
+	@# Find all files, but exclude .pio and .ccls-cache directories
+	@# Preserve colors in output
+	@find \
+		. \
+		-not \( -name .ccls-cache -prune \) \
+		-not \( -name .pio -prune \) \
+		-not \( -name mjs -prune \) \
+		-not \( -name doomgeneric -prune \) \
+		-not \( -name bak -prune \) \
+		-iname *.h \
+		-o -iname *.cpp \
+		-o -iname *.c \
+		-o -iname *.hpp \
+		-o -iname *.h \
+		-o -iname *.rst \
+		| xargs grep --color=always -n -H -E "TODO|FIXME|XXX" \
+
+.PHONY: lint
+lint:
+	# Find all files, but exclude .pio and .ccls-cache directories
+	# Preserve colors in output
+	find \
+		. \
+		-not \( -name .ccls-cache -prune \) \
+		-not \( -name .pio -prune \) \
+		-not \( -name mjs -prune \) \
+		-not \( -name doomgeneric -prune \) \
+		-not \( -name bak -prune \) \
+		-iname *.h \
+		-o -iname *.cpp \
+		-o -iname *.c \
+		-o -iname *.hpp \
+		-o -iname *.h \
+		| xargs clang-format --dry-run --Werror
+
+.PHONY: fix
+fix:
+	# Find all files, but exclude .pio and .ccls-cache directories
+	# Preserve colors in output
 	find \
-		./firmware-demo/src/ \
-		./lib/lilka \
+		. \
 		-not \( -name .ccls-cache -prune \) \
 		-not \( -name .pio -prune \) \
+		-not \( -name mjs -prune \) \
+		-not \( -name doomgeneric -prune \) \
+		-not \( -name bak -prune \) \
 		-iname *.h \
 		-o -iname *.cpp \
+		-o -iname *.c \
+		-o -iname *.hpp \
+		-o -iname *.h \
 		| xargs clang-format -i

README.md

@@ -3,7 +3,8 @@
 ![Made in Ukraine](https://img.shields.io/badge/Made%20in-Ukraine-blue?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAwIiBoZWlnaHQ9IjgwMCI%2BCjxyZWN0IHdpZHRoPSIxMjAwIiBoZWlnaHQ9IjgwMCIgZmlsbD0iIzAwNTdCNyIvPgo8cmVjdCB3aWR0aD0iMTIwMCIgaGVpZ2h0PSI0MDAiIHk9IjQwMCIgZmlsbD0iI0ZGRDcwMCIvPgo8L3N2Zz4%3D)
 [![Documentation Status](https://readthedocs.org/projects/lilka/badge/?version=latest)](https://docs.lilka.dev)
 [![PlatformIO Registry](https://badges.registry.platformio.org/packages/and3rson/library/Lilka.svg)](https://registry.platformio.org/libraries/and3rson/Lilka)
-[![firmware/main](https://github.com/and3rson/lilka/actions/workflows/firmware_main.yml/badge.svg)](https://github.com/and3rson/lilka/actions/workflows/firmware_main.yml)
+[![firmware/hashbrown](https://github.com/and3rson/lilka/actions/workflows/firmware_hashbrown.yml/badge.svg)](https://github.com/and3rson/lilka/actions/workflows/firmware_hashbrown.yml)
+[![code style](https://github.com/and3rson/lilka/actions/workflows/code_style.yml/badge.svg)](https://github.com/and3rson/lilka/actions/workflows/code_style.yml)
 [![Discord](https://img.shields.io/discord/1202315568846213172?label=Discord)][discord]
 
 DIY-консоль, яку можна зібрати з дешевих готових модулів.

docs/index.rst

@@ -14,9 +14,9 @@
 
     about/index
     hardware/index
+    assembly/index
     manual/index
     library/index
-    lua/index
     faq
     glossary
 

docs/library/build_flags.rst

@@ -3,7 +3,7 @@
 
 Бібліотека ``lilka`` постачається з рядом вбудованих можливостей, які за замовчуванням увімкнені.
 
-Можливо, вам не подобаються деякі налаштування, які вибрані за замовчуванням. Наприклад, ви хочете вимкнути підтримку Lua, бо не плануєте використовувати цю мову програмування.
+Можливо, вам не подобаються деякі налаштування, які вибрані за замовчуванням. Наприклад, ви не хочете, щоб привітальне зображення відображалося при запуску Лілки.
 
 Завдяки :term:`PlatformIO` ви можете змінити налаштування, відредагувавши файл `platformio.ini`. Для цього є опція ``build_flags``.
 
@@ -32,32 +32,3 @@
     Видалити привітальне зображення.
 
     Пришвидшує запуск Лілки та звільняє ~134 КБ флеш-пам'яті.
-
-.. c:macro:: LILKA_NO_MJS
-
-    Вимкнути підтримку mJS.
-
-    Звільняє ~49 КБ флеш-пам'яті.
-
-.. c:macro:: LILKA_NO_LUA
-
-    Вимкнути підтримку Lua.
-
-    Звільняє ~162 КБ флеш-пам'яті.
-
-Мінімальна конфігурація
------------------------
-
-Якщо ви хочете вимкнути всі можливості (наприклад, ви хочете використати бібліотеку ``lilka`` без Lua, mJS та привітального зображення), ви можете використати наступний рядок:
-
-.. code-block:: ini
-    :linenos:
-    :emphasize-lines: 7
-
-    [env:v2]
-    platform = espressif32
-    board = lilka_v2
-    framework = arduino
-    lib_deps =
-        lilka
-    build_flags = -D LILKA_NO_SPLASH -D LILKA_NO_MJS -D LILKA_NO_LUA

docs/library/ui.rst

@@ -1,6 +1,13 @@
 ``UI``: Інтерфейс користувача
 =============================
 
-.. doxygenfunction:: lilka::ui_menu
+Цей модуль містить класи, які відповідають за відображення простих елементів інтерфейсу користувача: меню, сповіщення тощо.
 
-.. doxygenfunction:: lilka::ui_alert
+.. doxygenclass:: lilka::Menu
+    :members:
+
+.. doxygenclass:: lilka::Alert
+    :members:
+
+.. doxygenclass:: lilka::ProgressDialog
+    :members:

docs/manual/main_firmware/environment.rst → docs/manual/environment.rst

@@ -1,9 +1,13 @@
 Налаштування середовища розробки
 ================================
 
-Для розробки програмного забезпечення для Лілки ми використовуємо середовище **PlatformIO**.
+Отже, ви зібрали Лілку. Чи, можливо, якийсь інший пристрій на базі мікроконтролера ESP32. І ви хочете написати для нього програмне забезпечення. З чого почати?
+(Саме так: багато що з цього документу може бути корисним і для інших пристроїв на базі ESP32, але ми будемо говорити здебільшого саме про Лілку.)
+
+Для розробки програмного забезпечення для Лілки ми використовуємо середовище **PlatformIO**, і дуже рекомендуємо вам теж спробувати його. До речі, **PlatformIO** - це український проект, і ми пишаємося тим, що він став таким популярним у всьому світі! 🇺🇦
 
 **PlatformIO** - це набір інструментів для розробки вбудованого програмного забезпечення, який автоматизує процес збірки, завантаження та налагодження програмного забезпечення для мікроконтролерів.
+Якщо ви колись працювали з Arduino IDE, то ви знаєте, що воно хоч і зручне, але має свої обмеження. **PlatformIO** - це таке собі "Arduino для дорослих".
 
 **PlatformIO** автоматично встановлює необхідні залежності, такі як компілятори, бібліотеки та інші інструменти, що необхідні для написання програм.
 

docs/manual/index.rst

@@ -4,7 +4,7 @@
 .. toctree::
     :maxdepth: 1
 
-    assembly/index
-    main_firmware/index
+    environment
+    keira/index
     development
     extension

docs/manual/main_firmware/features.rst → docs/manual/keira/features.rst

@@ -1,7 +1,7 @@
-.. _main-firmware-features:
+.. _keira-firmware-features:
 
-Можливості основної прошивки
-============================
+Можливості
+==========
 
 .. contents::
    :local:
@@ -12,33 +12,33 @@
 Запуск прошивок з SD-картки
 ---------------------------
 
-Основна прошивка підтримує запуск другорядних прошивок з SD-картки. Такі файли мають розширення ``.bin``. Це дозволяє вам скомпілювати (або завантажити з інтернету) нестандартну прошивку, скопіювати її на SD-картку, і запустити її на Лілці.
+Keira підтримує запуск другорядних прошивок з SD-картки. Такі файли мають розширення ``.bin``. Це дозволяє вам скомпілювати (або завантажити з інтернету) нестандартну прошивку, скопіювати її на SD-картку, і запустити її на Лілці.
 
 Це має деякі великі переваги:
 
-- Ви можете використовувати більше пам'яті, ніж доступно в основній прошивці.
+- Ви можете використовувати більше пам'яті, ніж доступно в Keira.
 - Вам не потрібно щоразу перепрошивати Лілку, щоб випробувати другорядні прошивки: просто скопіюйте їх на SD-картку.
-- Ви можете ділитися своїми скомпільованими прошивками (у вигляді ``.bin``-файлів) з іншими користувачами Лілки, без необхідності відправляти їм весь код вашої основної прошивки.
+- Ви можете ділитися своїми скомпільованими прошивками (у вигляді ``.bin``-файлів) з іншими користувачами Лілки, без необхідності відправляти їм весь код вашої власної прошивки.
 
 Найяскравіший приклад використання цієї функції - запуск Doom. Достатньо скопіювати в корінь SD-карти файли ``doom.bin`` і ``doom.wad`` (або ``doom1.wad``), і ви зможете грати в Doom!
 
 .. note:: Щоб отримати ``doom.bin``, вам потрібно скомпілювати прошивку, що знаходиться в папці ``firmware/doom``, і тоді скопіювати файл ``doom.bin`` на SD-картку.
 
 .. note::
 
-    Щоб отримати ``doom.wad``, ви можете завантажити безкоштовну shareware-версію Doom `за цим посиланням <https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad>_`,
+    Щоб отримати ``doom.wad``, ви можете завантажити безкоштовну shareware-версію Doom `за цим посиланням <https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad>`_,
     або ж мати повну ліцензійну копію Doom і витягти з неї файл ``doom.wad``.
 
 Тепер ви можете вставити SD-картку в Лілку і вибрати ``doom.bin`` у браузері SD-картки. Лілка перезавантажиться, і ви зможете зіграти в Doom!
 
-Після перезавантаження Лілки, ви повернетеся до основної прошивки.
+Після перезавантаження Лілки ви повернетеся до Keira.
 
 .. _nes-emulator-feature:
 
 Запуск ігор NES з SD-картки
 ---------------------------
 
-Основна прошивка має вбудовану підтримку запуску ігор `NES <https://uk.wikipedia.org/wiki/Nintendo_Entertainment_System>`_ з SD-картки. Це означає, що ви можете скопіювати файли ігор NES (`.rom` або `.nes`) на SD-картку, і грати в них на Лілці.
+Keira має вбудовану підтримку запуску ігор `NES <https://uk.wikipedia.org/wiki/Nintendo_Entertainment_System>`_ з SD-картки. Це означає, що ви можете скопіювати файли ігор NES (`.rom` або `.nes`) на SD-картку, і грати в них на Лілці.
 
 Для емуляції NES Лілка використовує емулятор `Nofrendo <https://github.com/moononournation/arduino-nofrendo>`_. Він може мати деякі обмеження, але, наприклад, Super Mario Bros працює бездоганно.
 
@@ -47,19 +47,19 @@
 Запуск Lua-скриптів з SD-картки
 -------------------------------
 
-Основна прошивка має вбудовану підтримку запуску `Lua <https://uk.wikipedia.org/wiki/Lua>`_-скриптів з SD-картки. Це означає, що ви можете скопіювати файли Lua (`.lua`) на SD-картку, і виконувати їх на Лілці.
+Keira має вбудовану підтримку запуску `Lua <https://uk.wikipedia.org/wiki/Lua>`_-скриптів з SD-картки. Це означає, що ви можете скопіювати файли Lua (`.lua`) на SD-картку, і виконувати їх на Лілці.
 
 Для виконання Lua-скриптів Лілка використовує вбудований інтерпретатор Lua, який базується на `Lua 5.4.6 <https://www.lua.org/manual/5.4/manual.html>`_.
 
-Написати власний Lua-скрипт для Лілки дуже просто. Для цього вам потрібно знати основи Lua, а також використовувати :doc:`Lua API </lua/index>` Лілки.
+Написати власний Lua-скрипт для Лілки дуже просто. Для цього вам потрібно знати основи Lua, а також використовувати Lua API  Лілки. Детальніше про це - в розділі :ref:`lua-intro`.
 
 Детальніше про те, як писати Lua-скрипти для Лілки, ви можете прочитати в розділі :ref:`lua-intro`.
 
 Запуск mJS-скриптів з SD-картки
 -------------------------------
 
 mJS - це `мінімалістичний двигун JavaScript <https://github.com/cesanta/mjs>`_, який використовується в Лілці для виконання скриптів.
-Основна прошивка має вбудовану підтримку запуску mJS-скриптів з SD-картки. Це означає, що ви можете скопіювати файли, написані діалектом mJS (з розширенням ``.js``) на SD-картку і виконувати їх на Лілці.
+Keira має вбудовану підтримку запуску mJS-скриптів з SD-картки. Це означає, що ви можете скопіювати файли, написані діалектом mJS (з розширенням ``.js``) на SD-картку і виконувати їх на Лілці.
 
 Я не впевнений, наскільки корисною буде ця функція, і ми рекомендуємо використовувати для цього Lua, яка має значно більше можливостей, ніж mJS. Проте ця функція є, і ви можете спробувати її, якщо вам цікаво.