diff --git a/docs/library/build_flags.rst b/docs/library/build_flags.rst index 9dfc2328..01513f92 100644 --- a/docs/library/build_flags.rst +++ b/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 diff --git a/docs/library/ui.rst b/docs/library/ui.rst index d13df4c8..e5a9cfe4 100644 --- a/docs/library/ui.rst +++ b/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: diff --git a/docs/manual/hashbrown/environment.rst b/docs/manual/environment.rst similarity index 77% rename from docs/manual/hashbrown/environment.rst rename to docs/manual/environment.rst index daf89d24..9a02c638 100644 --- a/docs/manual/hashbrown/environment.rst +++ b/docs/manual/environment.rst @@ -1,9 +1,13 @@ Налаштування середовища розробки ================================ -Для розробки програмного забезпечення для Лілки ми використовуємо середовище **PlatformIO**. +Отже, ви зібрали Лілку. Чи, можливо, якийсь інший пристрій на базі мікроконтролера ESP32. І ви хочете написати для нього програмне забезпечення. З чого почати? +(Саме так: багато що з цього документу може бути корисним і для інших пристроїв на базі ESP32, але ми будемо говорити здебільшого саме про Лілку.) + +Для розробки програмного забезпечення для Лілки ми використовуємо середовище **PlatformIO**, і дуже рекомендуємо вам теж спробувати його. До речі, **PlatformIO** - це український проект, і ми пишаємося тим, що він став таким популярним у всьому світі! 🇺🇦 **PlatformIO** - це набір інструментів для розробки вбудованого програмного забезпечення, який автоматизує процес збірки, завантаження та налагодження програмного забезпечення для мікроконтролерів. +Якщо ви колись працювали з Arduino IDE, то ви знаєте, що воно хоч і зручне, але має свої обмеження. **PlatformIO** - це таке собі "Arduino для дорослих". **PlatformIO** автоматично встановлює необхідні залежності, такі як компілятори, бібліотеки та інші інструменти, що необхідні для написання програм. diff --git a/docs/manual/hashbrown/index.rst b/docs/manual/hashbrown/index.rst deleted file mode 100644 index 5dcb4bb2..00000000 --- a/docs/manual/hashbrown/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -Хешбраун OS -=========== - -Лілка постачається з нашою власною прошивкою, яка називається **Хешбраун** (**Hashbrown**) і включає в себе основні функції для демонстрації можливостей пристрою. - -.. toctree:: - :maxdepth: 3 - - environment - flashing - features - sdcard - lua/intro - lua/reference/index diff --git a/docs/manual/hashbrown/images/01_download_vscode.png b/docs/manual/images/01_download_vscode.png similarity index 100% rename from docs/manual/hashbrown/images/01_download_vscode.png rename to docs/manual/images/01_download_vscode.png diff --git a/docs/manual/hashbrown/images/01_download_vscode_cropped.png b/docs/manual/images/01_download_vscode_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/01_download_vscode_cropped.png rename to docs/manual/images/01_download_vscode_cropped.png diff --git a/docs/manual/hashbrown/images/04_install_platformio.png b/docs/manual/images/04_install_platformio.png similarity index 100% rename from docs/manual/hashbrown/images/04_install_platformio.png rename to docs/manual/images/04_install_platformio.png diff --git a/docs/manual/hashbrown/images/04_install_platformio_cropped.png b/docs/manual/images/04_install_platformio_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/04_install_platformio_cropped.png rename to docs/manual/images/04_install_platformio_cropped.png diff --git a/docs/manual/hashbrown/images/06_download_git_for_win.png b/docs/manual/images/06_download_git_for_win.png similarity index 100% rename from docs/manual/hashbrown/images/06_download_git_for_win.png rename to docs/manual/images/06_download_git_for_win.png diff --git a/docs/manual/hashbrown/images/06_download_git_for_win_cropped.png b/docs/manual/images/06_download_git_for_win_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/06_download_git_for_win_cropped.png rename to docs/manual/images/06_download_git_for_win_cropped.png diff --git a/docs/manual/hashbrown/images/07_use_vs_code_with_git.png b/docs/manual/images/07_use_vs_code_with_git.png similarity index 100% rename from docs/manual/hashbrown/images/07_use_vs_code_with_git.png rename to docs/manual/images/07_use_vs_code_with_git.png diff --git a/docs/manual/hashbrown/images/07_use_vs_code_with_git_cropped.png b/docs/manual/images/07_use_vs_code_with_git_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/07_use_vs_code_with_git_cropped.png rename to docs/manual/images/07_use_vs_code_with_git_cropped.png diff --git a/docs/manual/index.rst b/docs/manual/index.rst index ebd58b7b..344ff122 100644 --- a/docs/manual/index.rst +++ b/docs/manual/index.rst @@ -4,6 +4,7 @@ .. toctree:: :maxdepth: 1 - hashbrown/index + environment + keira/index development extension diff --git a/docs/manual/hashbrown/features.rst b/docs/manual/keira/features.rst similarity index 74% rename from docs/manual/hashbrown/features.rst rename to docs/manual/keira/features.rst index 0cb1543d..c0af79a5 100644 --- a/docs/manual/hashbrown/features.rst +++ b/docs/manual/keira/features.rst @@ -1,7 +1,7 @@ -.. _hashbrown-firmware-features: +.. _keira-firmware-features: -Можливості Хешбраун OS -====================== +Можливості +========== .. contents:: :local: @@ -12,11 +12,11 @@ Запуск прошивок з SD-картки --------------------------- -Основна прошивка підтримує запуск другорядних прошивок з SD-картки. Такі файли мають розширення ``.bin``. Це дозволяє вам скомпілювати (або завантажити з інтернету) нестандартну прошивку, скопіювати її на SD-картку, і запустити її на Лілці. +Keira підтримує запуск другорядних прошивок з SD-картки. Такі файли мають розширення ``.bin``. Це дозволяє вам скомпілювати (або завантажити з інтернету) нестандартну прошивку, скопіювати її на SD-картку, і запустити її на Лілці. Це має деякі великі переваги: -- Ви можете використовувати більше пам'яті, ніж доступно в Хешбраун OS. +- Ви можете використовувати більше пам'яті, ніж доступно в Keira. - Вам не потрібно щоразу перепрошивати Лілку, щоб випробувати другорядні прошивки: просто скопіюйте їх на SD-картку. - Ви можете ділитися своїми скомпільованими прошивками (у вигляді ``.bin``-файлів) з іншими користувачами Лілки, без необхідності відправляти їм весь код вашої власної прошивки. @@ -31,14 +31,14 @@ Тепер ви можете вставити SD-картку в Лілку і вибрати ``doom.bin`` у браузері SD-картки. Лілка перезавантажиться, і ви зможете зіграти в Doom! -Після перезавантаження Лілки ви повернетеся до Хешбраун OS. +Після перезавантаження Лілки ви повернетеся до Keira. .. _nes-emulator-feature: Запуск ігор NES з SD-картки --------------------------- -Основна прошивка має вбудовану підтримку запуску ігор `NES `_ з SD-картки. Це означає, що ви можете скопіювати файли ігор NES (`.rom` або `.nes`) на SD-картку, і грати в них на Лілці. +Keira має вбудовану підтримку запуску ігор `NES `_ з SD-картки. Це означає, що ви можете скопіювати файли ігор NES (`.rom` або `.nes`) на SD-картку, і грати в них на Лілці. Для емуляції NES Лілка використовує емулятор `Nofrendo `_. Він може мати деякі обмеження, але, наприклад, Super Mario Bros працює бездоганно. @@ -47,7 +47,7 @@ Запуск Lua-скриптів з SD-картки ------------------------------- -Основна прошивка має вбудовану підтримку запуску `Lua `_-скриптів з SD-картки. Це означає, що ви можете скопіювати файли Lua (`.lua`) на SD-картку, і виконувати їх на Лілці. +Keira має вбудовану підтримку запуску `Lua `_-скриптів з SD-картки. Це означає, що ви можете скопіювати файли Lua (`.lua`) на SD-картку, і виконувати їх на Лілці. Для виконання Lua-скриптів Лілка використовує вбудований інтерпретатор Lua, який базується на `Lua 5.4.6 `_. @@ -59,7 +59,7 @@ ------------------------------- mJS - це `мінімалістичний двигун JavaScript `_, який використовується в Лілці для виконання скриптів. -Основна прошивка має вбудовану підтримку запуску mJS-скриптів з SD-картки. Це означає, що ви можете скопіювати файли, написані діалектом mJS (з розширенням ``.js``) на SD-картку і виконувати їх на Лілці. +Keira має вбудовану підтримку запуску mJS-скриптів з SD-картки. Це означає, що ви можете скопіювати файли, написані діалектом mJS (з розширенням ``.js``) на SD-картку і виконувати їх на Лілці. Я не впевнений, наскільки корисною буде ця функція, і ми рекомендуємо використовувати для цього Lua, яка має значно більше можливостей, ніж mJS. Проте ця функція є, і ви можете спробувати її, якщо вам цікаво. diff --git a/docs/manual/hashbrown/flashing.rst b/docs/manual/keira/flashing.rst similarity index 85% rename from docs/manual/hashbrown/flashing.rst rename to docs/manual/keira/flashing.rst index 3ff116e2..12277b6c 100644 --- a/docs/manual/hashbrown/flashing.rst +++ b/docs/manual/keira/flashing.rst @@ -1,11 +1,9 @@ -Запуск Хешбраун OS -================== +Запуск +====== -Лілка постачається з готовою прошивкою, яка вміє багато різних речей. Ця прошивка використовується для демонстрації можливостей Лілки, а також як приклад для розробки власних програм. +Лілка постачається з готовою прошивкою Keira, яка вміє багато різних речей. Ця прошивка використовується для :ref:`демонстрації можливостей Лілки, а також як приклад для розробки власних програм `. -TODO: links to features - -В цьому розділі ми розглянемо, як завантажити Хешбраун OS у в Лілку. +В цьому розділі ми розглянемо, як завантажити операційну систему Keira в Лілку. Клонування репозиторію та побудова прошивки ------------------------------------------- @@ -22,7 +20,7 @@ TODO: links to features .. image:: ./images/09_clone_cropped.png :width: 80% -2. Після клонування репозиторію перейдіть на вкладку **PlatformIO** та імпортуйте проєкт прошивки Хешбраун OS для Лілки. Для цього натисніть "**Open Project**" та виберіть директорію ``lilka/firmware/hashbrown``. +2. Після клонування репозиторію перейдіть на вкладку **PlatformIO** та імпортуйте проєкт прошивки Keira для Лілки. Для цього натисніть "**Open Project**" та виберіть директорію ``lilka/firmware/keira``. .. image:: ./images/11_open_pio_project_cropped.png :width: 80% @@ -83,14 +81,14 @@ TODO: links to features **Тепер вам не потрібно щоразу вручну переводити Лілку в режим завантаження, щоб завантажити нову прошивку!** - Крім прошивки Хешбраун OS, ви щойно завантажили в Лілку ще й програму-завантажувач (bootloader). Тепер ви можете завантажувати нові прошивки в Лілку безпосередньо з **PlatformIO**. + Крім прошивки Keira, ви щойно завантажили в Лілку ще й програму-завантажувач (bootloader). Тепер ви можете завантажувати нові прошивки в Лілку безпосередньо з **PlatformIO**. Просто натисніть кнопку ``Upload`` в **PlatformIO** та вона автоматично переведе Лілку в режим завантаження та завантажить нову прошивку! Вітаємо! -------- -Вітаємо, ви успішно налаштували середовище розробки та завантажили Хешбраун OS в Лілку! +Вітаємо, ви успішно налаштували середовище розробки та завантажили Keira в Лілку! Ви можете потицяти Лілку та переконатися, що вона працює і спробувати різні демо. Також ви можете перейти на вкладку **Explorer** (``Ctrl`` + ``Shift`` + ``E``), відкрити файл ``src/main.cpp`` та поглянути, як виглядає код прошивки, яку ми щойно зібрали і запустили на Лілці. diff --git a/docs/manual/hashbrown/images/02_inside_vscode.png b/docs/manual/keira/images/02_inside_vscode.png similarity index 100% rename from docs/manual/hashbrown/images/02_inside_vscode.png rename to docs/manual/keira/images/02_inside_vscode.png diff --git a/docs/manual/hashbrown/images/03_go_to_extensions.png b/docs/manual/keira/images/03_go_to_extensions.png similarity index 100% rename from docs/manual/hashbrown/images/03_go_to_extensions.png rename to docs/manual/keira/images/03_go_to_extensions.png diff --git a/docs/manual/hashbrown/images/05_installed_platformio.png b/docs/manual/keira/images/05_installed_platformio.png similarity index 100% rename from docs/manual/hashbrown/images/05_installed_platformio.png rename to docs/manual/keira/images/05_installed_platformio.png diff --git a/docs/manual/hashbrown/images/08_clone_repo.png b/docs/manual/keira/images/08_clone_repo.png similarity index 100% rename from docs/manual/hashbrown/images/08_clone_repo.png rename to docs/manual/keira/images/08_clone_repo.png diff --git a/docs/manual/hashbrown/images/08_clone_repo_cropped.png b/docs/manual/keira/images/08_clone_repo_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/08_clone_repo_cropped.png rename to docs/manual/keira/images/08_clone_repo_cropped.png diff --git a/docs/manual/hashbrown/images/09_clone.png b/docs/manual/keira/images/09_clone.png similarity index 100% rename from docs/manual/hashbrown/images/09_clone.png rename to docs/manual/keira/images/09_clone.png diff --git a/docs/manual/hashbrown/images/09_clone_cropped.png b/docs/manual/keira/images/09_clone_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/09_clone_cropped.png rename to docs/manual/keira/images/09_clone_cropped.png diff --git a/docs/manual/hashbrown/images/10_see_cloned_repo.png b/docs/manual/keira/images/10_see_cloned_repo.png similarity index 100% rename from docs/manual/hashbrown/images/10_see_cloned_repo.png rename to docs/manual/keira/images/10_see_cloned_repo.png diff --git a/docs/manual/hashbrown/images/11_open_pio_project.png b/docs/manual/keira/images/11_open_pio_project.png similarity index 100% rename from docs/manual/hashbrown/images/11_open_pio_project.png rename to docs/manual/keira/images/11_open_pio_project.png diff --git a/docs/manual/hashbrown/images/11_open_pio_project_cropped.png b/docs/manual/keira/images/11_open_pio_project_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/11_open_pio_project_cropped.png rename to docs/manual/keira/images/11_open_pio_project_cropped.png diff --git a/docs/manual/hashbrown/images/12_wait_pio_project_init.png b/docs/manual/keira/images/12_wait_pio_project_init.png similarity index 100% rename from docs/manual/hashbrown/images/12_wait_pio_project_init.png rename to docs/manual/keira/images/12_wait_pio_project_init.png diff --git a/docs/manual/hashbrown/images/13_wait_pio_project_init_more.png b/docs/manual/keira/images/13_wait_pio_project_init_more.png similarity index 100% rename from docs/manual/hashbrown/images/13_wait_pio_project_init_more.png rename to docs/manual/keira/images/13_wait_pio_project_init_more.png diff --git a/docs/manual/hashbrown/images/13_wait_pio_project_init_more_cropped.png b/docs/manual/keira/images/13_wait_pio_project_init_more_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/13_wait_pio_project_init_more_cropped.png rename to docs/manual/keira/images/13_wait_pio_project_init_more_cropped.png diff --git a/docs/manual/hashbrown/images/14_pio_build_v2.png b/docs/manual/keira/images/14_pio_build_v2.png similarity index 100% rename from docs/manual/hashbrown/images/14_pio_build_v2.png rename to docs/manual/keira/images/14_pio_build_v2.png diff --git a/docs/manual/hashbrown/images/14_pio_build_v2_cropped.png b/docs/manual/keira/images/14_pio_build_v2_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/14_pio_build_v2_cropped.png rename to docs/manual/keira/images/14_pio_build_v2_cropped.png diff --git a/docs/manual/hashbrown/images/15_pio_build_v2_progress.png b/docs/manual/keira/images/15_pio_build_v2_progress.png similarity index 100% rename from docs/manual/hashbrown/images/15_pio_build_v2_progress.png rename to docs/manual/keira/images/15_pio_build_v2_progress.png diff --git a/docs/manual/hashbrown/images/15_pio_build_v2_progress_cropped.png b/docs/manual/keira/images/15_pio_build_v2_progress_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/15_pio_build_v2_progress_cropped.png rename to docs/manual/keira/images/15_pio_build_v2_progress_cropped.png diff --git a/docs/manual/hashbrown/images/16_pio_build_ok.png b/docs/manual/keira/images/16_pio_build_ok.png similarity index 100% rename from docs/manual/hashbrown/images/16_pio_build_ok.png rename to docs/manual/keira/images/16_pio_build_ok.png diff --git a/docs/manual/hashbrown/images/16_pio_build_ok_cropped.png b/docs/manual/keira/images/16_pio_build_ok_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/16_pio_build_ok_cropped.png rename to docs/manual/keira/images/16_pio_build_ok_cropped.png diff --git a/docs/manual/hashbrown/images/17_run_upload_v2.png b/docs/manual/keira/images/17_run_upload_v2.png similarity index 100% rename from docs/manual/hashbrown/images/17_run_upload_v2.png rename to docs/manual/keira/images/17_run_upload_v2.png diff --git a/docs/manual/hashbrown/images/17_run_upload_v2_cropped.png b/docs/manual/keira/images/17_run_upload_v2_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/17_run_upload_v2_cropped.png rename to docs/manual/keira/images/17_run_upload_v2_cropped.png diff --git a/docs/manual/hashbrown/images/18_upload_progress.png b/docs/manual/keira/images/18_upload_progress.png similarity index 100% rename from docs/manual/hashbrown/images/18_upload_progress.png rename to docs/manual/keira/images/18_upload_progress.png diff --git a/docs/manual/hashbrown/images/18_upload_progress_cropped.png b/docs/manual/keira/images/18_upload_progress_cropped.png similarity index 100% rename from docs/manual/hashbrown/images/18_upload_progress_cropped.png rename to docs/manual/keira/images/18_upload_progress_cropped.png diff --git a/docs/manual/hashbrown/images/cursor.png b/docs/manual/keira/images/cursor.png similarity index 100% rename from docs/manual/hashbrown/images/cursor.png rename to docs/manual/keira/images/cursor.png diff --git a/docs/manual/keira/index.rst b/docs/manual/keira/index.rst new file mode 100644 index 00000000..e657fbd8 --- /dev/null +++ b/docs/manual/keira/index.rst @@ -0,0 +1,17 @@ +Keira OS +======== + +Ми написали для Лілки власну прошивку, яка називається **"Keira OS"** (**Операційна Система "Кіра"**) і включає в себе основні функції для демонстрації можливостей пристрою. + +**Keira** - це операційна система, що базується на проєкті FreeRTOS. Вона підтримує мультизадачність, мережу, запуск Lua-програм та сторонніх прошивок з SD-карти та багато іншого. + +Більше інформації про **Keira OS** - на `наступній сторінці `_. + +.. toctree:: + :maxdepth: 3 + + features + flashing + sdcard + lua/intro + lua/reference/index diff --git a/docs/manual/hashbrown/lua/images/select_com_port.png b/docs/manual/keira/lua/images/select_com_port.png similarity index 100% rename from docs/manual/hashbrown/lua/images/select_com_port.png rename to docs/manual/keira/lua/images/select_com_port.png diff --git a/docs/manual/hashbrown/lua/images/select_com_port.xcf b/docs/manual/keira/lua/images/select_com_port.xcf similarity index 100% rename from docs/manual/hashbrown/lua/images/select_com_port.xcf rename to docs/manual/keira/lua/images/select_com_port.xcf diff --git a/docs/manual/hashbrown/lua/images/send_entire_file.png b/docs/manual/keira/lua/images/send_entire_file.png similarity index 100% rename from docs/manual/hashbrown/lua/images/send_entire_file.png rename to docs/manual/keira/lua/images/send_entire_file.png diff --git a/docs/manual/hashbrown/lua/images/serial_monitor.png b/docs/manual/keira/lua/images/serial_monitor.png similarity index 100% rename from docs/manual/hashbrown/lua/images/serial_monitor.png rename to docs/manual/keira/lua/images/serial_monitor.png diff --git a/docs/manual/hashbrown/lua/images/serial_monitor.xcf b/docs/manual/keira/lua/images/serial_monitor.xcf similarity index 100% rename from docs/manual/hashbrown/lua/images/serial_monitor.xcf rename to docs/manual/keira/lua/images/serial_monitor.xcf diff --git a/docs/manual/hashbrown/lua/intro.rst b/docs/manual/keira/lua/intro.rst similarity index 76% rename from docs/manual/hashbrown/lua/intro.rst rename to docs/manual/keira/lua/intro.rst index 04f019a7..1fe08dcc 100644 --- a/docs/manual/hashbrown/lua/intro.rst +++ b/docs/manual/keira/lua/intro.rst @@ -3,7 +3,7 @@ Написання програм на Lua ======================== -Основна прошивка Лілки має вбудовану віртуальну машину мови програмування Lua. Це дозволяє писати та виконувати програми на Lua прямо з SD-картки, без необхідності компіляції чи перепрошивання Лілки. +Keira має вбудовану віртуальну машину мови програмування Lua. Це дозволяє писати та виконувати програми на Lua прямо з SD-картки, без необхідності компіляції чи перепрошивання Лілки. .. warning:: Якщо ви не знайомі з мовою Lua, рекомендуємо прочитати туторіал з Lua перед тим, як продовжувати: https://www.lua.org/pil/1.html @@ -16,27 +16,28 @@ Приклад програми ---------------- -Оскільки Lua сама по собі - це універсальна мова програмування, вона не має вбудованих функцій для роботи з дисплеєм, звуком тощо. Тому для роботи з цими пристроями на Лілці використовуються спеціальні вбудовані модулі, які надають доступ до функцій пристроїв. +Оскільки Lua сама по собі - це універсальна мова програмування, вона не має вбудованих функцій для роботи з дисплеєм, звуком тощо. Тому для роботи з цими пристроями на Лілці в Keira доступні спеціальні вбудовані модулі, які надають доступ до функцій пристроїв. -Модулі в Lua на Лілці завантажуються автоматично - не потрібно писати жодних ``require(...)``. Ось приклад простої програми на Lua, яка виводить текст "Hello, world!" на екран: +Модулі завантажуються автоматично - не потрібно писати жодних ``require(...)``. Ось приклад простої програми на Lua, яка виводить текст "Hello, world!" на екран: .. code-block:: lua :linenos: - -- Заповнюємо екран чорним кольором: - display.fill_screen(display.color565(0, 0, 0)) - - -- Виводимо текст "Hello, world!" на екран: - display.set_cursor(0, 32) - display.print("Hello, world!") - - -- Відображаємо все, що ми намалювали на екрані: - display.render() + function lilka::update() + if controller.get_state().a.just_pressed then + -- Завершуємо програму при натисканні кнопки "A" + util.exit() + end + end - -- Чекаємо 2 секунди: - util.sleep(2) + function lilka::draw() + -- Заповнюємо екран чорним кольором: + display.fill_screen(display.color565(0, 0, 0)) - -- На цьому програма автоматично завершиться. + -- Виводимо текст "Hello, world!" на екран: + display.set_cursor(0, 32) + display.print("Hello, world!") + end Ви можете зберегти цей код у файл з розширенням ``.lua`` на SD-картці, а потім виконати його, обравши його в браузері SD-картки. @@ -44,14 +45,16 @@ .. _lua-games: -Написання ігор --------------- +``init``, ``update``, ``draw`` +------------------------------ В іграх важливо, щоб гра була плавною та виконувалася з певною стабільною кількістю кадрів на секунду. -Для простих програм на Lua, які не вимагають точності в швидкості виконання, можна використовувати :lua:func:`util.sleep()` для затримки виконання програми. Однак це незручно для ігор. +Імовірно, ви знайомі з функцією ``delay(...)`` з фреймворка Arduino, яка затримує виконання програми на певну кількість мілісекунд. +Це зручно для простих програм, що не використовують дисплей, але для ігор це не підходить, оскільки такі функції заблокують виконання програми на певну кількість мілісекунд, +незалежно від швидкості виконання програми, а також не дозволяють вам взаємодіяти з грою під час затримки. -Для цього існує можливість визначити функції :lua:func:`lilka.init()`, :lua:func:`lilka.update()` і :lua:func:`lilka.draw()`. Якщо при запуску вашої програми Лілка знайде цю функції, вона буде викликати їх автоматично. +Для цього існує можливість визначити функції :lua:func:`lilka.init()`, :lua:func:`lilka.update()` і :lua:func:`lilka.draw()`. Якщо при запуску вашої програми Keira знайде цю функції, вона буде викликати їх автоматично. * :lua:func:`lilka.init()` викликається один раз при запуску програми. @@ -59,14 +62,13 @@ * :lua:func:`lilka.draw()` викликається після :lua:func:`lilka.update()` та використовується для малювання графіки на екрані. -.. note:: Вам не потрібно викликати :lua:func:`display.render()` всередині вашої :lua:func:`lilka.draw()` - це буде зроблено автоматично. Звісно, ви можете здійснювати все малювання графіки в функції :lua:func:`lilka.update()`, але для читабельності коду краще розділити логіку гри та малювання графіки на окремі функції. Для цього і є поділ на :lua:func:`lilka.update()` та :lua:func:`lilka.draw()`. - .. warning:: - - Якщо ви визначите :lua:func:`lilka.update()` або :lua:func:`lilka.draw()` у своїй програмі, то для завершення програми вам потрібно викликати :lua:func:`util.exit()`. Інакше програма буде виконуватися постійно, поки ви не вимкнете Лілку. + Програма на Lua буде виконуватись доти, доки не буде викликано функцію :lua:func:`util.exit()`. Інакше для виходу вам доведеться перезавантажити Лілку. .. warning:: - Не варто використовувати :lua:func:`util.sleep` всередині ваших функцій :lua:func:`lilka.update()` та :lua:func:`lilka.draw()`, оскільки це призведе до заповільнення виконання програми. + Не варто використовувати :lua:func:`util.sleep` всередині ваших функцій :lua:func:`lilka.update()` та :lua:func:`lilka.draw()`, оскільки це призведе до заповільнення виконання програми. + + Намагайтесь писати код, який не блокує виконання програми, а використовує функцію :lua:func:`lilka.update()` для оновлення стану гри та обробки введення користувача. :lua:func:`lilka.update()` також отримує необов'язковий аргумент ``delta``, який вказує (в секундах), скільки часу пройшло з початку її попереднього виклику. Це дозволяє вам робити рухи та анімації, які будуть відбуватись з однаковою швидкістю незалежно від швидкості виконання програми. @@ -143,7 +145,7 @@ Щоразу, коли ви зберігаєте програму на SD-картці, ви повинні виймати її з Лілки, вставляти в комп'ютер, зберігати файл, виймати з комп'ютера, вставляти в Лілку, вибирати файл в браузері SD-картки, запускати програму, перевіряти, в͟и̛п͜р͢а̵в̀л͟я̕т̴и͜ ̢п͟о̨м͘и̴л͢к͡и́,͝ ̕з́б͠е͞р͠і͞г͏а̢т͞и̧ ͘з̶н̛о̶в͢у̢,͡ ͡О НІ! Це - нестерпно і в нас немає часу на це! -Саме тому Хешбраун OS має функцію, яка називається **Live Lua**. Вона дозволяє вам запускати Lua-код на Лілці через USB-кабель прямо з вашого комп'ютера, без необхідності зберігати його на SD-картці. +Саме тому Keira має функцію, яка називається **Live Lua**. Вона дозволяє вам запускати Lua-код на Лілці через USB-кабель прямо з вашого комп'ютера, без необхідності зберігати його на SD-картці. .. warning:: @@ -167,13 +169,11 @@ .. code-block:: lua :linenos: - display.fill_screen(display.color565(128, 0, 128)) -- Темно-фіолетовий колір - - display.set_cursor(64, 64) - display.print("Привіт!") - display.render() - - util.sleep(2) + display.fill_screen(display.color565(255, 0, 0)) + display.set_cursor(50, 50) + print('A') + print('B') + print('C') Тепер перейдіть на вкладку "Serial Monitor" у VS Code, оберіть COM-порт, на якому підключена Лілка, та натисніть "Start Monitoring": @@ -217,7 +217,6 @@ :linenos: display.fill_screen(display.color565(255, 0, 0)) - display.render() Після введення другого рядка та натиску на клавішу ``Enter``, екран Лілки має забарвитися червоним кольором. diff --git a/docs/manual/hashbrown/lua/reference/controller.rst b/docs/manual/keira/lua/reference/controller.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/controller.rst rename to docs/manual/keira/lua/reference/controller.rst diff --git a/docs/manual/hashbrown/lua/reference/display.rst b/docs/manual/keira/lua/reference/display.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/display.rst rename to docs/manual/keira/lua/reference/display.rst diff --git a/docs/manual/hashbrown/lua/reference/geometry.rst b/docs/manual/keira/lua/reference/geometry.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/geometry.rst rename to docs/manual/keira/lua/reference/geometry.rst diff --git a/docs/manual/hashbrown/lua/reference/gpio.rst b/docs/manual/keira/lua/reference/gpio.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/gpio.rst rename to docs/manual/keira/lua/reference/gpio.rst diff --git a/docs/manual/hashbrown/lua/reference/index.rst b/docs/manual/keira/lua/reference/index.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/index.rst rename to docs/manual/keira/lua/reference/index.rst diff --git a/docs/manual/hashbrown/lua/reference/lilka.rst b/docs/manual/keira/lua/reference/lilka.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/lilka.rst rename to docs/manual/keira/lua/reference/lilka.rst diff --git a/docs/manual/hashbrown/lua/reference/math.rst b/docs/manual/keira/lua/reference/math.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/math.rst rename to docs/manual/keira/lua/reference/math.rst diff --git a/docs/manual/hashbrown/lua/reference/resources.rst b/docs/manual/keira/lua/reference/resources.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/resources.rst rename to docs/manual/keira/lua/reference/resources.rst diff --git a/docs/manual/hashbrown/lua/reference/state.rst b/docs/manual/keira/lua/reference/state.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/state.rst rename to docs/manual/keira/lua/reference/state.rst diff --git a/docs/manual/hashbrown/lua/reference/util.rst b/docs/manual/keira/lua/reference/util.rst similarity index 100% rename from docs/manual/hashbrown/lua/reference/util.rst rename to docs/manual/keira/lua/reference/util.rst diff --git a/docs/manual/hashbrown/sdcard.rst b/docs/manual/keira/sdcard.rst similarity index 82% rename from docs/manual/hashbrown/sdcard.rst rename to docs/manual/keira/sdcard.rst index 414199c0..fcf1bd2d 100644 --- a/docs/manual/hashbrown/sdcard.rst +++ b/docs/manual/keira/sdcard.rst @@ -1,7 +1,7 @@ Карта microSD ============= -Лілка підтримує карти пам'яті microSD для запуску програм та зберігання даних. +Keira підтримує карти пам'яті microSD для запуску програм та зберігання даних. Перш ніж використовувати карту пам'яті, вона повинна бути відформатована в файлову систему FAT32. Це можна зробити за допомогою програми форматування в операційній системі Windows або за допомогою команди ``mkfs.vfat`` в операційній системі GNU/Linux. @@ -34,10 +34,10 @@ Наповнення карти пам'яті демонстраційними програмами ---------------------------------------------------- -Перш ніж використовувати карту пам'яті з Лілкою, ви можете записати на неї демонстраційні програми. +Перш ніж використовувати карту пам'яті з Keira, ви можете записати на неї демонстраційні програми. -Вони знаходяться в директорії ``firmware/hashbrown/sdcard`` в репозиторії проєкту на GitHub. +Вони знаходяться в директорії ``firmware/keira/sdcard`` в репозиторії проєкту на GitHub. -Підключіть карту пам'яті до комп'ютера та скопіюйте файли з директорії ``firmware/hashbrown/sdcard`` на карту пам'яті. Після цього відключіть карту пам'яті від комп'ютера та вставте її в Лілку. +Підключіть карту пам'яті до комп'ютера та скопіюйте файли з директорії ``firmware/keira/sdcard`` на карту пам'яті. Після цього відключіть карту пам'яті від комп'ютера та вставте її в Лілку. Коли Лілка запуститься, виберіть пункт "Браузер SD-карти" в головному меню і спробуйте запустити одну з Lua-програм! (Вони мають розширення ``.lua`` і синю іконку. diff --git a/sdk/lib/lilka/src/lilka/display.h b/sdk/lib/lilka/src/lilka/display.h index 46f436e0..cc559732 100644 --- a/sdk/lib/lilka/src/lilka/display.h +++ b/sdk/lib/lilka/src/lilka/display.h @@ -56,8 +56,10 @@ class Display : public Arduino_ST7789 { /// /// За замовчуванням відображається вітальний екран Лілки. /// + /// @note Якщо викликати цей метод, то вітальний екран буде відображатись навіть якщо `LILKA_NO_SPLASH` встановлено в `true`. + /// /// Його потрібно викликати перед викликом `lilka::begin()` або не викликати взагалі. - /// @param splash Масив 16-бітних кольорів (5-6-5) розміром `LILKA_DISPLAY_WIDTH` * `LILKA_DISPLAY_HEIGHT`. + /// @param splash Масив 16-бітних кольорів (5-6-5) з розміром 280*240. void setSplash(const uint16_t *splash); #ifdef DOXYGEN // `Arduino_GFX_Library` має купу гарних методів, але вони погано документовані. diff --git a/sdk/lib/lilka/src/lilka/multiboot.h b/sdk/lib/lilka/src/lilka/multiboot.h index a9c35563..ad05f532 100644 --- a/sdk/lib/lilka/src/lilka/multiboot.h +++ b/sdk/lib/lilka/src/lilka/multiboot.h @@ -10,8 +10,8 @@ namespace lilka { /// Завантажувач прошивок з microSD-картки. /// -/// Дозволяє прочитати файл прошивки з microSD-картки в OTA-розділ та запустити його один зар, -/// не замінюючи основну прошивку. +/// Дозволяє прочитати файл прошивки з microSD-картки в OTA-розділ та запустити його один раз, +/// не замінюючи поточну прошивку. /// /// Нова прошивка зберігається в OTA-розділі та запускається при перезавантаженні, /// але активною залишається основна прошивка (app rollback). @@ -30,9 +30,9 @@ namespace lilka { /// /// Serial.println("Завантаження прошивки 'firmware.bin' з microSD-картки..."); /// -/// lilka::multiboot->start("/sd/firmware.bin"); // Почати завантаження +/// lilka::multiboot.start("/sd/firmware.bin"); // Почати завантаження /// while (lilka::multiboot.process() != 0) { // Обробити завантаження -/// Serial.printf("Завантажено %d/%d байтів\n", lilka::multiboot.getBytesWritten(), lilka::multiboot.getBytesTotal()); +/// Serial.println("Завантажено " + String(lilka::multiboot.getBytesWritten()) + "/" + String(lilka::multiboot.getBytesTotal()) + " байтів"); /// } /// lilka::multiboot.finishAndReboot(); // Завершити завантаження та перезавантажити пристрій /// } diff --git a/sdk/lib/lilka/src/lilka/ui.h b/sdk/lib/lilka/src/lilka/ui.h index 283668af..35c178fc 100644 --- a/sdk/lib/lilka/src/lilka/ui.h +++ b/sdk/lib/lilka/src/lilka/ui.h @@ -10,48 +10,15 @@ typedef uint16_t const menu_icon_t[576]; // 24x24px icon namespace lilka { -/// Відобразити меню. -/// -/// Блокує виконання програми, доки користувач не обере пункт меню та не натисне кнопку A. -/// Повертає індекс вибраного пункту меню. -/// -/// @param title Заголовок меню. -/// @param menu Масив пунктів меню. -/// @param menu_size Розмір масиву пунктів меню. -/// @param cursor Початковий курсор. За замовчуванням встановлено в 0. -/// @param icons Масив іконок для кожного пункту меню. Якщо значення елементу (або весь масив) буде рівним 0, то іконка не відображається. -/// @param colors Масив кольорів для кожного пункту меню (в форматі RGB 5-6-5). Якщо значення елементу (або весь масив) буде рівним 0, то використовується стандартний колір. -/// @return Індекс вибраного пункту меню. -/// -/// Приклад використання: -/// -/// @code -/// #include -/// -/// void setup() { -/// lilka::begin(); -/// } -/// -/// void loop() { -/// String items[] = {"Смерть русні", "Ядерка на червону площу", "Повернення Криму"}; -/// int selected = lilka::ui_menu("Оберіть щось", items, 3); -/// lilka::ui_alert( -/// "Гарний вибір!", -/// "Ви обрали " + menu[selected] + "\nДавайте оберемо ще щось!" -/// ); -/// } -/// @endcode +typedef struct { + String title; + const menu_icon_t *icon; + uint16_t color; +} MenuItem; -// int ui_menu( -// Canvas *canvas, String title, String menu[], int menu_size, int cursor = 0, const menu_icon_t *icons[] = 0, -// const uint16_t colors[] = 0 -// ); -/// Відобразити сповіщення. -/// -/// Блокує виконання програми, доки користувач не натисне кнопку A. +/// Клас для відображення меню. /// -/// @param title Заголовок підтвердження. -/// @param message Повідомлення підтвердження. +/// Дозволяє відобразити меню з пунктами, які можна вибирати за допомогою стрілок вгору/вниз та підтвердити вибір кнопкою A. /// /// Приклад використання: /// @@ -63,24 +30,54 @@ namespace lilka { /// } /// /// void loop() { -/// lilka::ui_alert("Увага", "Повітряна тривога в москві, загроза балістичних ракет!"); +/// lilka::Menu dreams("Оберіть щось"); +/// dreams.addItem("Смерть русні"); +/// dreams.addItem("Ядерка на червону площу"); +/// dreams.addItem("Повернення Криму"); +/// int index = -1; +/// while (index == -1) { +/// dreams.update(); +/// dreams.draw(&lilka::display); +/// index = dreams.getSelectedIndex(); +/// } +/// Serial.println("Ви обрали пункт номер " + String(index)); /// } /// @endcode -// void ui_alert(Canvas *canvas, String title, String message); - -typedef struct { - String title; - const menu_icon_t *icon; - uint16_t color; -} MenuItem; - class Menu { public: + /// Конструктор класу. + /// + /// @param title Заголовок меню. Menu(String title); + /// Додати пункт до меню. + /// @param title Заголовок пункту. + /// @param icon Іконка пункту (масив з ``uint16_t`` розміром 576 елементів, який представляє 24x24px зображення). За замовчуванням ``0`` (відсутня іконка). + /// @param color Колір пункту. За замовчуванням ``0`` (стандартний колір). void addItem(String title, const menu_icon_t *icon = 0, uint16_t color = 0); + /// Встановити курсор на пункт меню. + /// @param cursor Індекс пункту меню. void setCursor(int16_t cursor); + /// Оновити стан меню. + /// + /// Цю функцію потрібно викликати, щоб меню опрацювало вхідні дані від користувача та оновило свій стан. void update(); + /// Намалювати меню на Display або Canvas. + /// + /// @param canvas Вказівник на Display або Canvas, на якому потрібно намалювати меню. + /// + /// Приклад використання: + /// @code + /// // ... + /// menu.draw(&lilka::display); // намалювати меню на Display + /// menu.draw(&canvas); // намалювати меню на Canvas + /// // ... + /// @endcode void draw(Arduino_GFX *canvas); + /// Отримати індекс обраного пункту меню. + /// + /// Якщо жоден пункт не обрано, повертається ``-1``. + /// + /// Також ця функція очищує обраний пункт, тому щойно вона поверне індекс обраного пункту, вона почне повертати ``-1`` до тих пір, поки не буде обрано новий пункт. int16_t getSelectedIndex(); private: @@ -91,11 +88,54 @@ class Menu { int16_t selectedIndex; }; +/// Клас для відображення сповіщення. +/// +/// Дозволяє відобразити сповіщення, яке користувач може закрити кнопкою A. +/// +/// Приклад використання: +/// +/// @code +/// #include +/// +/// void setup() { +/// lilka::begin(); +/// } +/// +/// void loop() { +/// lilka::Alert warning("Увага", "Повітряна тривога в москві, загроза балістичних ракет!"); +/// warning.draw(&lilka::display); +/// while (!warning.isDone()) { +/// warning.update(); +/// } +/// } +/// @endcode class Alert { public: + /// Конструктор класу. + /// + /// @param title Заголовок сповіщення. + /// @param message Повідомлення сповіщення. Alert(String title, String message); + /// Оновити стан сповіщення. + /// + /// Цю функцію потрібно викликати, щоб сповіщення опрацювало вхідні дані від користувача та оновило свій стан. void update(); + /// Намалювати сповіщення на Display або Canvas. + /// + /// @param canvas Вказівник на Display або Canvas, на якому потрібно намалювати сповіщення. + /// + /// Приклад використання: + /// + /// @code + /// // ... + /// alert.draw(&lilka::display); // намалювати сповіщення на Display + /// alert.draw(&canvas); // намалювати сповіщення на Canvas + /// // ... + /// @endcode void draw(Arduino_GFX *canvas); + /// Перевірити, чи користувач закрив сповіщення. + /// + /// Якщо сповіщення закрито (користувач натиснув кнопку "A"), повертається ``true``, інакше ``false``. bool isDone(); private: @@ -104,11 +144,55 @@ class Alert { bool done; }; +/// Клас для відображення індикатора виконання. +/// +/// Дозволяє відобразити індикатор виконання, який можна оновлювати та змінювати його повідомлення. +/// +/// Приклад використання: +/// +/// @code +/// #include +/// +/// void setup() { +/// lilka::begin(); +/// } +/// +/// void loop() { +/// lilka::ProgressDialog progress("Почекайте", "Завантаження даних..."); +/// for (int i = 0; i <= 100; i++) { +/// progress.setProgress(i); +/// progress.draw(&lilka::display); +/// delay(100); +/// } +/// progress.setMessage("Дані завантажено!"); +/// delay(1000); +/// } +/// @endcode class ProgressDialog { public: + /// Конструктор класу. + /// + /// @param title Заголовок індикатора виконання. + /// @param message Повідомлення індикатора виконання. ProgressDialog(String title, String message); + /// Встановити прогрес виконання. + /// + /// @param progress Прогрес виконання від 0 до 100. void setProgress(int16_t progress); + /// Встановити повідомлення. + /// @param message Повідомлення. void setMessage(String message); + /// Намалювати індикатор виконання на Display або Canvas. + /// @param canvas Вказівник на Display або Canvas, на якому потрібно намалювати індикатор виконання. + /// + /// Приклад використання: + /// + /// @code + /// // ... + /// progress.draw(&lilka::display); // намалювати індикатор виконання на Display + /// progress.draw(&canvas); // намалювати індикатор виконання на Canvas + /// // ... + /// @endcode void draw(Arduino_GFX *canvas); private: