doc: add manual on setting up env & flashing demo firmware

and3rson · Feb 21, 2024 · 086eda7 · 086eda7
1 parent 9ed4fe0
commit 086eda7
Show file tree

Hide file tree

Showing 38 changed files with 185 additions and 12 deletions.
diff --git a/docs/library/index.rst b/docs/library/index.rst
@@ -1,7 +1,9 @@
 Бібліотека ``lilka``
 ====================
 
-Проєкт "Лілка" має однойменну бібліотеку ``lilka``, яка дозволяє працювати з компонентами пристрою.
+Проєкт "Лілка" має однойменну бібліотеку ``lilka``, яка спрощує роботу з Лілкою та дозволяє вам швидко створювати програми для неї.
+
+Ця бібліотека доступна в `реєстрі бібліотек PlatformIO <https://registry.platformio.org/libraries/and3rson/Lilka/installation>`_.
 
 Звісно ж, ви можете використовувати Лілку і без бібліотеки ``lilka`` - ніхто не змушує вас використовувати її.
 Весь код, який ви побачите в цій документації, можна написати самостійно, без використання ``lilka``.
@@ -13,6 +15,8 @@
 Також ``lilka`` спрощує ініціалізацію дисплею, кнопок, батареї, звуку, SD-карти та інших компонентів, що входять до складу Лілки. Для цього потрібно викликати лише одну функцію - ``lilka::begin()``.
 
 .. code-block:: cpp
+    :linenos:
+    :emphasize-lines: 1,4
 
     #include <lilka.h>
 
@@ -29,7 +33,7 @@
             // Отримати стан кнопок
             lilka::State state = lilka::controller.getState();
 
-            if (state.a.justPressed) // Якщо щойно була натиснута кнопка "A"...
+            if (state.a.justPressed) { // Якщо щойно була натиснута кнопка "A"...
                 // Розпочати відтворення звуку на частоті 440 Гц
                 lilka::buzzer.play(440);
                 // Заповнити екран червоним кольором
@@ -40,6 +44,7 @@
                 // Заповнити екран зеленим кольором
                 lilka::display.fillScreen(lilka::display.color565(0, 255, 0));
             }
+        }
     }
 
 Тому, незалежно від рівня вашої кваліфікації, ми радимо використовувати бібліолеку ``lilka`` для роботи з Лілкою.
@@ -53,6 +58,8 @@
     Якщо не хочете щоразу писати ``lilka::`` перед кожною функцією та об'єктом бібліотеки ``lilka``, ви можете використати директиву ``using namespace``:
 
     .. code-block:: cpp
+        :linenos:
+        :emphasize-lines: 3,12,16,20,22,25,27
 
         #include <lilka.h>
 
@@ -71,7 +78,7 @@
                 // Отримати стан кнопок
                 State state = controller.getState();
 
-                if (state.a.justPressed) // Якщо щойно була натиснута кнопка "A"...
+                if (state.a.justPressed) { // Якщо щойно була натиснута кнопка "A"...
                     // Розпочати відтворення звуку на частоті 440 Гц
                     buzzer.play(440);
                     // Заповнити екран червоним кольором
@@ -82,6 +89,7 @@
                     // Заповнити екран зеленим кольором
                     display.fillScreen(display.color565(0, 255, 0));
                 }
+            }
         }
 
 .. toctree::

diff --git a/docs/manual/environment.rst b/docs/manual/environment.rst
@@ -1,4 +1,133 @@
-Налаштування середовища розробки
-================================
+Запуск першої прошивки
+======================
 
-TODO
+Для розробки програмного забезпечення для Lilka використовується середовище PlatformIO.
+
+PlatformIO - це набір інструментів для розробки вбудованого програмного забезпечення, який автоматизує процес збірки, завантаження та налагодження програмного забезпечення для мікроконтролерів.
+
+PlatformIO автоматично встановлює необхідні залежності, такі як компілятори, бібліотеки та інші інструменти, що необхідні для написання програм.
+
+В цьому документі описано процес налаштування середовища розробки для Lilka з використанням PlatformIO та Visual Studio Code для ОС Windows на прикладі демонстраційної прошивки для Лілки.
+
+Якщо ви використовуєте MacOS, процес буде схожим, але можуть бути деякі відмінності в налаштуваннях. А якщо ви використовуєте Linux, то ви, скоріш за все, вже знаєте, що робити, і цей документ вам не потрібен. ;)
+
+Встановлення Visual Studio Code, PlatformIO та Git
+--------------------------------------------------
+
+1. Встановіть **Visual Studio Code** з офіційного сайту: https://code.visualstudio.com/
+
+   .. image:: ./images/01_download_vscode_cropped.png
+       :width: 50%
+
+2. Запустіть **Visual Studio Code** та встановіть плагін **PlatformIO IDE**.
+
+   Для цього відкрийте вкладку **Extensions** (``Ctrl`` + ``Shift`` + ``X``), введіть "**PlatformIO**" в поле пошуку та встановіть плагін.
+
+   .. image:: ./images/04_install_platformio_cropped.png
+       :width: 50%
+
+   .. .. image:: ./images/05_installed_platformio.png
+   ..     :width: 50%
+
+3. Тепер нам потрібно встановити **Git**.
+
+   **Git** - це система керування версіями, яка дозволяє ділитися кодом з іншими розробниками та використовувати код з відкритих репозиторіїв.
+
+   Весь код для Лілки, а також бібліотеки, які використовуються в проекті, знаходяться на `GitHub <https://github.com/and3rson/lilka>`_, тому нам потрібно встановити **Git**, щоб здійснювати роботу з репозиторіями.
+
+   Для встановлення **Git** перейдіть на вкладку **Source Control** (``Ctrl`` + ``Shift`` + ``G``) та натисніть "**Download Git for Windows**".
+
+   .. image:: ./images/06_download_git_for_win_cropped.png
+       :width: 50%
+
+   В процесі встановлення не змінюйте жодних параметрів, залиште все так, як є за замовчуванням, окрім кроку "**Choosing the default editor used by Git**".
+
+   На цьому кроці виберіть "**Use Visual Studio Code as Git's default editor**".
+
+   .. image:: ./images/07_use_vs_code_with_git_cropped.png
+       :width: 50%
+
+4. Після встановлення **Git** перезапустіть **Visual Studio Code**.
+
+Клонування репозиторію та побудова демонстраційної прошивки
+-----------------------------------------------------------
+
+1. Перейдіть на вкладку **Source Control** (``Ctrl`` + ``Shift`` + ``G``) та клонуйте репозиторій `Lilka <https://github.com/and3rson/lilka>`_:
+
+   .. image:: ./images/08_clone_repo_cropped.png
+       :width: 50%
+
+   Для цього натисніть "**Clone Repository**" та введіть адресу репозиторію:
+
+   ``https://github.com/and3rson/lilka``
+
+   .. image:: ./images/09_clone_cropped.png
+       :width: 50%
+
+2. Після клонування репозиторію перейдіть на вкладку **PlatformIO** та імпортуйте проєкт основної прошивки для Лілки. Для цього натисніть "**Open Project**" та виберіть директорію ``lilka/firmware/main``.
+
+   .. image:: ./images/11_open_pio_project_cropped.png
+       :width: 50%
+
+3. Тепер нам потрібно дочекатися налаштування середовища розробки.
+
+   **PlatformIO** автоматично встановить необхідні залежності, такі як компілятори, бібліотеки та інші інструменти, що необхідні для написання програм для Лілки.
+
+   .. image:: ./images/13_wait_pio_project_init_more_cropped.png
+       :width: 50%
+
+4. Після налаштування середовища розробки перейдіть на вкладку **PlatformIO** та виберіть ``v2`` в якості цільової платформи. Потім натисніть "**Build**".
+
+   .. image:: ./images/14_pio_build_v2_cropped.png
+       :width: 50%
+
+   Тепер потрібно дочекатися завершення збірки. Перша збірка може зайняти деякий час.
+
+   .. image:: ./images/15_pio_build_v2_progress_cropped.png
+       :width: 50%
+
+   Щойно збірка завершиться, ви побачите повідомлення про успішне завершення збірки:
+
+   .. image:: ./images/16_pio_build_ok_cropped.png
+       :width: 50%
+
+Завантаження демонстраційної прошивки в Лілку
+---------------------------------------------
+
+1. Підключіть Лілку до комп'ютера за допомогою USB-кабеля та увімкніть її.
+
+   Windows може вимагати встановлення драйверів для Лілки. Якщо вам буде запропоновано встановити драйвери, встановіть їх.
+
+   Після цього вимкніть Лілку.
+
+   Тепер вам потрібно натиснути та утримувати кнопку ``SELECT`` і увімкнути Лілку. Після цього можна відпустити кнопку ``SELECT``.
+   Це переведе Лілку в **режим завантаження** (**bootloader mode**): в цьому режимі ви можете завантажити в неї нову прошику.
+
+2. Тепер перейдіть на вкладку **PlatformIO** та виберіть ``v2`` в якості цільової платформи. Потім натисніть "**Upload**".
+
+   Спершу **PlatformIO** виконає підготовчі дії, а потім розпочне завантаження нашої свіжозібраної прошивки в Лілку.
+
+   .. image:: ./images/17_run_upload_v2_cropped.png
+       :width: 50%
+
+   Початок завантаження виглядатиме ось так:
+
+   .. image:: ./images/18_upload_progress_cropped.png
+       :width: 50%
+
+   Тепер потрібно дочекатися завершення завантаження. Щойно завантаження завершиться, ви побачите повідомлення про успішне завершення завантаження:
+
+   TODO: додати скріншот, оскільки я це все робив під віртуалкою без Лілки під рукою. :)
+
+3. Коли завантаження завершиться, натисніть кнопку ``RESET`` на Лілці та насолоджуйтесь новою прошивкою!
+
+Вітаємо!
+--------
+
+Вітаємо, ви успішно налаштували середовище розробки та завантажили демонстраційну прошивку в Лілку!
+
+Ви можете потицяти Лілку та переконатися, що вона працює і спробувати різні демо. Також ви можете перейти на вкладку **Explorer** (``Ctrl`` + ``Shift`` + ``E``), відкрити файл ``src/main.cpp`` та поглянути, як виглядає код прошивки, яку ми щойно зібрали і запустили на Лілці.
+
+**Лілка - це відкрита платформа**, тому ви можете змінювати код прошивки, додавати нові функції та вдосконалювати Лілку, або навіть створювати власні прошивки для неї.
+
+**Але перш ніж приступати до цього**, рекомендуємо ознайомитися з документацією бібліотеки `lilka`, яка спрощує роботу з Лілкою, за `цим посиланням </library>`_.
diff --git a/docs/manual/flashing.rst b/docs/manual/flashing.rst
diff --git a/docs/manual/images/01_download_vscode.png b/docs/manual/images/01_download_vscode.png
diff --git a/docs/manual/images/01_download_vscode_cropped.png b/docs/manual/images/01_download_vscode_cropped.png
diff --git a/docs/manual/images/02_inside_vscode.png b/docs/manual/images/02_inside_vscode.png
diff --git a/docs/manual/images/03_go_to_extensions.png b/docs/manual/images/03_go_to_extensions.png
diff --git a/docs/manual/images/04_install_platformio.png b/docs/manual/images/04_install_platformio.png
diff --git a/docs/manual/images/04_install_platformio_cropped.png b/docs/manual/images/04_install_platformio_cropped.png
diff --git a/docs/manual/images/05_installed_platformio.png b/docs/manual/images/05_installed_platformio.png
diff --git a/docs/manual/images/06_download_git_for_win.png b/docs/manual/images/06_download_git_for_win.png
diff --git a/docs/manual/images/06_download_git_for_win_cropped.png b/docs/manual/images/06_download_git_for_win_cropped.png
diff --git a/docs/manual/images/07_use_vs_code_with_git.png b/docs/manual/images/07_use_vs_code_with_git.png
diff --git a/docs/manual/images/07_use_vs_code_with_git_cropped.png b/docs/manual/images/07_use_vs_code_with_git_cropped.png
diff --git a/docs/manual/images/08_clone_repo.png b/docs/manual/images/08_clone_repo.png
diff --git a/docs/manual/images/08_clone_repo_cropped.png b/docs/manual/images/08_clone_repo_cropped.png
diff --git a/docs/manual/images/09_clone.png b/docs/manual/images/09_clone.png
diff --git a/docs/manual/images/09_clone_cropped.png b/docs/manual/images/09_clone_cropped.png
diff --git a/docs/manual/images/10_see_cloned_repo.png b/docs/manual/images/10_see_cloned_repo.png
diff --git a/docs/manual/images/11_open_pio_project.png b/docs/manual/images/11_open_pio_project.png
diff --git a/docs/manual/images/11_open_pio_project_cropped.png b/docs/manual/images/11_open_pio_project_cropped.png
diff --git a/docs/manual/images/12_wait_pio_project_init.png b/docs/manual/images/12_wait_pio_project_init.png
diff --git a/docs/manual/images/13_wait_pio_project_init_more.png b/docs/manual/images/13_wait_pio_project_init_more.png
diff --git a/docs/manual/images/13_wait_pio_project_init_more_cropped.png b/docs/manual/images/13_wait_pio_project_init_more_cropped.png
diff --git a/docs/manual/images/14_pio_build_v2.png b/docs/manual/images/14_pio_build_v2.png
diff --git a/docs/manual/images/14_pio_build_v2_cropped.png b/docs/manual/images/14_pio_build_v2_cropped.png
diff --git a/docs/manual/images/15_pio_build_v2_progress.png b/docs/manual/images/15_pio_build_v2_progress.png
diff --git a/docs/manual/images/15_pio_build_v2_progress_cropped.png b/docs/manual/images/15_pio_build_v2_progress_cropped.png
diff --git a/docs/manual/images/16_pio_build_ok.png b/docs/manual/images/16_pio_build_ok.png
diff --git a/docs/manual/images/16_pio_build_ok_cropped.png b/docs/manual/images/16_pio_build_ok_cropped.png
diff --git a/docs/manual/images/17_run_upload_v2.png b/docs/manual/images/17_run_upload_v2.png
diff --git a/docs/manual/images/17_run_upload_v2_cropped.png b/docs/manual/images/17_run_upload_v2_cropped.png
diff --git a/docs/manual/images/18_upload_progress.png b/docs/manual/images/18_upload_progress.png
diff --git a/docs/manual/images/18_upload_progress_cropped.png b/docs/manual/images/18_upload_progress_cropped.png
diff --git a/docs/manual/index.rst b/docs/manual/index.rst
@@ -8,6 +8,5 @@ TODO
 
     assembly
     environment
-    flashing
     development
     extension
diff --git a/sdk/lib/lilka/README.md b/sdk/lib/lilka/README.md
@@ -0,0 +1,36 @@
+# Lilka
+
+Бібліотека для роботи з компонентами [Лілки](https://lilka.readthedocs.io/).
+
+# Приклад використання
+
+```cpp
+#include <lilka.h>
+
+void setup() {
+    lilka::begin();
+    // Все залізо готове до роботи!
+}
+
+void loop() {
+    // Заповнити екран чорним кольором
+    lilka::display.fillScreen(lilka::display.color565(0, 255, 0));
+
+    while (1) {
+        // Отримати стан кнопок
+        lilka::State state = lilka::controller.getState();
+
+        if (state.a.justPressed) { // Якщо щойно була натиснута кнопка "A"...
+            // Розпочати відтворення звуку на частоті 440 Гц
+            lilka::buzzer.play(440);
+            // Заповнити екран червоним кольором
+            lilka::display.fillScreen(lilka::display.color565(255, 0, 0));
+        } else if (state.a.justReleased) { // Якщо кнопка "A" щойно була відпущена...
+            // Зупинити відтворення звуку
+            lilka::buzzer.stop();
+            // Заповнити екран зеленим кольором
+            lilka::display.fillScreen(lilka::display.color565(0, 255, 0));
+        }
+    }
+}
+```
diff --git a/sdk/lib/lilka/library.json b/sdk/lib/lilka/library.json
@@ -1,6 +1,6 @@
 {
     "name": "Lilka",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -19,5 +19,9 @@
         "platformio.ini",
         "Makefile",
         "*.tar.gz"
+    ],
+    "include": [
+        "src",
+        "README.md"
     ]
 }
diff --git a/sdk/lib/lilka/src/lilka/ui.h b/sdk/lib/lilka/src/lilka/ui.h
@@ -37,6 +37,7 @@ namespace lilka {
 ///     );
 /// }
 /// @endcode
+
 int ui_menu(String title, String menu[], int menu_size, int cursor = 0, const menu_icon_t *icons[] = 0);
 /// Відобразити сповіщення.
 ///