Merge branch 'main' into alder/modplayer

.github/workflows/code-quality.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Run clang-format
         run: |
           apt update -y
-          apt install -y make clang-format-18
+          apt install -y make clang-format-17
           make clang-format
 
   cppcheck:

Makefile

@@ -1,6 +1,6 @@
 IMAGE2CODE = ./sdk/tools/image2code/image2code.py
 CPPCHECK ?= cppcheck
-CLANG_FORMAT ?= $(shell command -v clang-format-18 2>/dev/null || echo clang-format)
+CLANG_FORMAT ?= $(shell command -v clang-format-17 2>/dev/null || echo clang-format)
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-16s\033[0m %s\n", $$1, $$2}'
@@ -38,7 +38,7 @@ icons:
 		-not \( -name SimpleFTPServer -prune \) \
 		-not \( -name *splash* -prune \) \
 		-not \( -name *weather* -prune \) \
-		-iname *.png \
+		-iname '*.png' \
 		-exec $(IMAGE2CODE) {} \;
 
 .PHONY: check
@@ -49,7 +49,7 @@ check-docker: ## Run all checks in docker
 	docker build -t lilka-check -f - . <<EOF
 		FROM ubuntu:24.04
 		RUN apt-get update -y && \
-		apt-get install -y clang-format-18 cppcheck findutils grep make
+		apt-get install -y clang-format-17 cppcheck findutils grep make
 	EOF
 	docker run --rm -it -v $(PWD):/lilka -w /lilka lilka-check make check
 

README.md

@@ -20,7 +20,11 @@ DIY-консоль, яку можна зібрати з дешевих гото
 
 ## Демо
 
-Відео про проєкт:
+Новини про проєкт Лілка V2:
+
+[![Новини про проєкт "Лілка](https://img.youtube.com/vi/Xh49N__p2jE/hqdefault.jpg)](https://www.youtube.com/watch?v=Xh49N__p2jE)
+
+Перша версія Лілки:
 
 [![Проєкт "Лілка"](https://img.youtube.com/vi/6Tz70vqRrs0/hqdefault.jpg)](https://www.youtube.com/watch?v=6Tz70vqRrs0)
 

docs/about/index.rst

@@ -1,5 +1,5 @@
-По проєкт
-===========
+:octicon:`package` Про проєкт
+=============================
 
 .. include:: what_is_lilka.rst
 

docs/assembly/components.rst

@@ -126,7 +126,7 @@
    * - 1
      - U2
      - 280x240 1.69\" TFT
-     - 1.7\" TFT Display (ST7789)
+     - 1.7\" IPS TFT Display (ST7789)
      - `arduino.ua <https://arduino.ua/prod6568-tft-displei-1-7-spi-240x280-rgb>`__
      - 176
      -

docs/assembly/index.rst

@@ -1,5 +1,5 @@
-Як зібрати Лілку
-================
+:octicon:`tools` Як зібрати Лілку
+=================================
 
 .. warning:: Ця документація знаходиться в розробці. Інформація є неповною, може бути недостовірною і/або застарілою, і може значно змінюватися в майбутньому.
 
@@ -12,3 +12,4 @@
 
     configurations
     components
+    every_component

docs/community.rst

@@ -0,0 +1,33 @@
+:octicon:`people` Спільнота
+===========================
+
+``Rustilka``: Rust для Лілки
+----------------------------
+
+Автор: **black.ghost.off**
+
+Rustilka - це мініпроєкт підтримки мови Rust для Лілки, який має таку саму мету, як і сама консоль - "полегшити" розробку.
+
+Також цей проєкт чисто технічно незалежний від оригінального SDK: при наявності можливостей ми могли б мати IDF версію, але, на думку автора Rustilka, це не має сенсу.
+
+`Хочете писати код для Лілки на Rust? Тоді вам сюди! <https://rust.lilka.dev>`_
+
+``MeowUI``: Альтернативний UI-фреймворк для Лілки
+-------------------------------------------------
+
+Автор: **kolodieiev**
+
+MeowUI - набір бібліотек, що спрощують створення графічного інтерфейсу користувача для електронних пристроїв на базі esp32 та esp32s3.
+
+З самого початку даний проєкт створювався, як шаблон, для швидкої побудови багаторівневого графічного інтерфейсу в стилі “Quadratisch. Praktisch. Gut”.
+Мета - управління різноманітними датчиками за допомогою мікроконтролера ESP32.
+
+Після знайомства з проєктом "Лілка", автором MeowUI було прийнято рішення про розширення та доопрацювання функціоналу MeowUI.
+
+`Детальніше про проєкт можна дізнатися тут. <https://github.com/Kolodieiev/MeowUI>`_
+
+Спілкування
+-----------
+
+- Весь код проєкту доступний на `GitHub <https://github.com/and3rson/lilka>`_.
+- Приєднуйтесь до нашого `Discord-сервера <https://discord.gg/HU68TaKCu6>`_!

docs/conf.py

@@ -39,18 +39,16 @@
 
 # https://protips.readthedocs.io/pdf-font.html
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-    'papersize': 'a4paper',
-
-# The font size ('10pt', '11pt' or '12pt').
-    'pointsize': '11pt',
-
-# Additional stuff for the LaTeX preamble.
-    'preamble': r'''
+    # The paper size ('letterpaper' or 'a4paper').
+    "papersize": "a4paper",
+    # The font size ('10pt', '11pt' or '12pt').
+    "pointsize": "11pt",
+    # Additional stuff for the LaTeX preamble.
+    "preamble": r"""
         \usepackage{charter}
         \usepackage[defaultsans]{lato}
         \usepackage{inconsolata}
-    ''',
+    """,
 }
 
 # -- Custom CSS --------------------------------------------------------------
@@ -79,14 +77,21 @@ def setup(app):
 extensions.append("sphinx_lua")
 
 lua_source_path = ["../sdk/addons/lualilka/"]
-lua_source_encoding = 'utf8'
-lua_source_comment_prefix = '---'
+lua_source_encoding = "utf8"
+lua_source_comment_prefix = "---"
 lua_source_use_emmy_lua_syntax = True
-lua_source_private_prefix = '_'
+lua_source_private_prefix = "_"
 
 # -- Toolbox -----------------------------------------------------------------
 
 extensions.append("sphinx_toolbox.sidebar_links")
 extensions.append("sphinx_toolbox.github")
 github_username = "and3rson"
 github_repository = "lilka"
+
+# -- Graphviz ----------------------------------------------------------------
+
+extensions.append("sphinx.ext.graphviz")
+
+# -- Sphinx-Design ------------------------------------------------------------
+extensions.append("sphinx_design")

docs/faq/coding.rst

@@ -0,0 +1,126 @@
+Програмування
+=============
+
+.. contents:: Зміст
+   :local:
+
+Що таке "Arduino", "ESP-IDF" і ця ваша "бібліотека lilka"?
+--------------------------------------------------------------
+
+- **Arduino** - це фреймворк, яка дозволяє швидко і просто створювати програми для мікроконтролерів.
+
+  Основна перевага Arduino - це стандартизований і простий інтерфейс програмування, який дозволяє швидко створювати програми для мікроконтролерів.
+  Неважливо, чи ви пишете код для ESP32, чи для STM32, чи для ATmega: ви можете використовувати однаковий інтерфейс програмування, однакові функції та навіть однакові бібліотеки.
+
+  Тобто Arduino - це своєрідна абстракція, яка дозволяє вам писати код для мікроконтролерів, не замислюючись про те, який саме мікроконтролер ви використовуєте.
+
+- **ESP-IDF** - це офіційний фреймворк для програмування мікроконтролерів сімейства ESP32 від компанії Espressif.
+
+  ESP-IDF - це більш низькорівневий фреймворк, який дозволяє вам працювати з ESP32 на більш низькому рівні, ніж Arduino.
+  Код, написаний на ESP-IDF, може бути більш швидким і ефективним, ніж код, написаний на Arduino, але він також буде складнішим і працюватиме тільки на мікроконтролерах сімействі ESP32.
+
+- **Бібліотека lilka** - це бібліотека, яку ми написали для роботи з ESP32-S3 на платформі Arduino.
+
+  Це - спроба поєднати простоту Arduino з ефективністю ESP-IDF саме для написання програм для Лілки, а також надати додаткові функції, які допоможуть вам створити програми для Лілки швидше і простіше.
+
+Але не лякайтесь: **ви можете одночасно використовувати і Arduino, і ESP-IDF, і бібліотеку lilka**!
+
+Річ у тім, що бібліотека ``lilka`` написана на основі ESP32-Arduino, а ESP32-Arduino, в свою чергу, використовує ESP-IDF.
+Це означає, що ви можете використовувати в своєму коді і функції ESP-IDF, і функції Arduino, і функції бібліотеки ``lilka``.
+
+.. graphviz::
+
+    digraph G {
+        rankdir=LR;
+        node[shape=box];
+        "Ваш код" [style=filled, fillcolor="#aaffaa"];
+
+        subgraph cluster_0 {
+            style=filled;
+            color=lightgrey;
+            node [style=filled,color=white];
+            "Бібліотека lilka";
+            "ESP32 Arduino";
+            "ESP-IDF";
+        }
+
+        "Ваш код" -> "Бібліотека lilka" [minlen=5];
+        "Ваш код" -> "ESP32 Arduino";
+        "Ваш код" -> "ESP-IDF";
+        "Бібліотека lilka" -> "ESP32 Arduino" -> "ESP-IDF" [minlen=2];
+        "Бібліотека lilka" -> "ESP-IDF";
+
+        { rank=max; "Ваш код" }
+    }
+
+Що таке "паніка"?
+-----------------
+
+"Паніка" ("panic") - це загальна назва критичних ситуацій, які виникають, коли програма не може продовжувати свою роботу через критичну помилку або через потенційну можливість пошкодження даних.
+
+Класична паніка - це дереференсія нульового вказівника:
+
+.. code-block:: c
+
+    int *p = NULL;
+    *p = 42; // Паніка!
+
+Проте паніка може бути викликана іншими причинами, такими як переповнення стеку, помилки вводу-виводу, помилки пам'яті, помилки в програмному коді, помилки в апаратурі, і так далі.
+
+В більшості випадків при паніці ESP32 виводить в консоль не лише повідомлення про помилку, але і стек викликів, який привів до паніки.
+
+Цей стек можна розкодувати, щоб побачити, які функції були викликані перед панікою і в якому порядку.
+
+В KeiraOS для цього є "команда" ``decode_backtrace``, який використовує утиліту ``addr2line`` з комплекту ESP-IDF для розкодування стеку викликів. Ось як його використовувати:
+
+.. code-block:: bash
+
+    pio run -e v2 -t decode_backtrace -a '0x42013efa:0x3fcbbc10 0x4200894d:0x3fcbbcd0 0x4201962e:0x3fcbbd10 0x4201987b:0x3fcbbd30 0x4202724c:0x3fcbbd60'
+
+Це виведе розкодовані функції та рядки, які викликалися перед панікою, від "найглибшої" до "найповерхневішої". Тобто перший рядок - це момент, де відбулася паніка.
+
+Детальнішу інформацію про паніки можна знайти в `документації ESP-IDF <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/fatal-errors.html>`_.
+
+Я отримую паніку ``Stack canary watchpoint triggered``
+------------------------------------------------------
+
+В ESP32 є спеціальний механізм, який дозволяє виявити переповнення стеку. Цей механізм називається "стекова канарка" (stack canary).
+Він слідкує за переповненням стеку задачі.
+
+Оскільки в FreeRTOS кожна задача при створенні отримує свою власну область стеку, яка визначається параметром ``stack_depth`` функцій ``xTaskCreate...``,
+найчастіше ця помилка виникає через недостатньо велику область стеку вашої задачі. Ви можете збільшити розмір її стеку, визначивши більший розмір стеку при виклику ``xTaskCreate...``.
+
+.. warning::
+
+    Збільшення розміру стеку означає, що ваша програма буде використовувати більше пам'яті.
+
+    Лілка використовує мікроконтролер ESP32-S3, який має всього декілька сотень кілобайт внутрішньої оперативної пам'яті (RAM), але крім неї вона має зовнішню оперативну пам'ять, яка називається PSRAM.
+
+    Стек задачі зберігається у внутрішній RAM.
+
+    Якщо вам потрібно зберігати великі обсяги даних в пам'яті, то можливо замість збільшення стеку вам краще варто використовувати динамічне виділення пам'яті в "купі",
+    використовуючи функцію ``ps_malloc``, яка виділяє пам'ять у PSRAM (якої в Лілці аж 8 МБ).
+
+    PSRAM дещо повільніша за внутрішню RAM, але вона дозволяє зберігати в десятки разів більше даних. В більшості випадків різниця в швидкості взагалі не буде помітною.
+
+Я отримую паніку ``IllegalInstruction``
+---------------------------------------
+
+Ця помилка найчастіше трапляється, коли задача FreeRTOS, створена за допомогою одної з функцій ``xTaskCreate...``,
+доходить до кінця (або робить ``return``) без виклику ``vTaskDelete(NULL)``.
+
+Переконайтеся, що ваша задача завершується викликом ``vTaskDelete(NULL)``: іншими словами, викликайте ``vTaskDelete(NULL)`` замість ``return``.
+
+Я отримую паніку ``Task watchdog got triggered``
+------------------------------------------------
+
+Ця помилка виникає, коли задача не викликає ``vTaskDelay`` або ``vTaskDelayUntil`` протягом певного часу.
+
+В ESP32 є механізм "сторожового таймера" (watchdog timer), який слідкує за тим, щоб задачі виконувалися вчасно.
+Якщо задача не викликає ``vTaskDelay`` або ``vTaskDelayUntil`` протягом певного часу (зазвичай 10 секунд), ви отримаєте помилку ``Task watchdog got triggered``.
+Це робиться для того, щоб уникнути "зависання" задачі, яка не виконується.
+
+Переконайтеся, що ваша задача час від часу викликає ``taskYIELD()`` чи ``vTaskDelay(1)``.
+
+Якщо це неможливо - наприклад, якщо ви використовуєте сторонню бібліотеку, яка робить довгі і складні обчислення - ви можете збільшити таймаут сторожового таймера,
+викликавши `esp_task_wdt_init <https://docs.espressif.com/projects/esp-idf/en/v4.4/esp32/api-reference/system/wdts.html#_CPPv417esp_task_wdt_init8uint32_tb>`_ з більшим значенням таймауту.

docs/faq.rst → docs/faq/general.rst

@@ -1,5 +1,5 @@
-Поширені запитання
-==================
+Загальна інформація
+===================
 
 .. contents:: Зміст
    :local:
@@ -16,13 +16,6 @@
 Якщо ви шукаєте потужну ігрову консоль, то Лілка, можливо, не найкращий вибір для вас.
 (Хоча на ній можна без проблем грати в досить популярні старі ігри, такі як Doom чи Wolfenstein, а також запускати на ній емулятори NES, SNES та інших консолей.)
 
-Я не можу завантажити прошивку на свій пристрій. Що робити?
------------------------------------------------------------
-
-Переконайтеся, що ви використовуєте саме так званий "data" кабель, а не "power" кабель. "Power" кабель призначений лише для заряджання пристрою, а "data" кабель - і для передачі даних, і для заряджання.
-
-.. warning:: Зверніть увагу: Лілка не підтримує USB 3.0, тому ви не зможете прошивати її через кабель Type C - Type C. Використовуйте кабель Type C - Type A.
-
 Я хочу більший дисплей!
 -----------------------