Doc updates (#110)

doc: add graphviz to .readthedocs.yaml doc: add link to quick flashing doc: add custom firmware tutorial
and3rson · Apr 20, 2024 · 81260b4 · 81260b4
1 parent 2867a96
commit 81260b4
Show file tree

Hide file tree

Showing 19 changed files with 116 additions and 7 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -10,6 +10,7 @@ build:
     python: "3.12"
   apt_packages:
     - doxygen
+    - graphviz
   # Ubuntu 22.04 has KiCad 6.0, which does not have kicad-cli.
   # We'll have to keep this commented (and generate PDFs manually with `make gen`) until ReadTheDocs adds Ubuntu 24.04.
   # apt_packages:

diff --git a/docs/_static/extra_style.css b/docs/_static/extra_style.css
diff --git a/docs/keira/flashing.rst b/docs/keira/flashing.rst
@@ -1,3 +1,5 @@
+.. _keira-flashing:
+
 Запуск
 ======
 

diff --git a/docs/programming/custom_firmware.rst b/docs/programming/custom_firmware.rst
@@ -0,0 +1,108 @@
+Створення власної прошивки
+==========================
+
+1. Відкрийте Visual Studio Code, перейдіть на вкладку ``PlatformIO`` та виберіть ``Create New Project``.
+
+   .. image:: ./images/custom_firmware/02_pio_new_proj_2.png
+      :width: 60%
+
+   У вікні, що відкриється, натисніть на кнопку ``New Project``.
+
+2. Придумайте назву свого проєкту - наприклад, ``first_project``.
+
+   У переліку boards оберіть ``Lilka v2 (Anderson & friends)``.
+
+   У переліку frameworks оберіть ``Arduino``.
+
+   .. image:: ./images/custom_firmware/03_pio_new_proj_sel_lilka.png
+      :width: 60%
+
+   Після цього натисніть на кнопку ``Finish``.
+
+   .. note::
+
+      Якщо ви не бачите в переліку ``Lilka v2 (Anderson & friends)`` або у вас виникає помилка при створенні проєкту, вам потрібно оновити пакети PlatformIO.
+
+      Для цього виконайте команду ``pio pkg update -g -p espressif32`` в терміналі Visual Studio Code.
+
+      Щоб відкрити термінал, в панелі ``Quick Access`` виберіть ``Miscellaneous`` і тоді натисніть на ``PlatformIO Core CLI``.
+      Консоль відкриється внизу вікна Visual Studio Code.
+
+      Після цього вам слід перезапустити Visual Studio Code.
+
+3. Ваш новий проєкт відкриється у новому вікні Visual Studio Code, і ви побачите файл ``platformio.ini``.
+
+   .. image:: ./images/custom_firmware/04_project_ready.png
+      :width: 60%
+
+   Це - конфігураційний файл проєкту, в якому вказані всі налаштування проєкту: платформа, фреймворк, бібліотеки тощо.
+
+   Ми можете редагувати його вручну, а можете використовувати графічний інтерфейс PlatformIO.
+
+4. Давайте додамо до проєкту бібліотеку :ref:`lilka <lilka-lib>`. Для цього відкрийте вкладку ``PlatformIO`` та в панелі ``Quick Access`` виберіть ``Libraries``.
+
+   Після цього введіть у поле пошуку ``lilka``:
+
+   .. image:: ./images/custom_firmware/05_install_lilka_lib.png
+      :width: 60%
+
+   Тепер натисніть на кнопку ``Add to Project``.
+
+   .. image:: ./images/custom_firmware/06_install_lilka_lib.png
+      :width: 60%
+
+   Після завершення завантаження бібліотеки ви побачите, що вона з'явилась у полі ``lib_deps`` файлу ``platformio.ini``.
+
+   .. image:: ./images/custom_firmware/08_lilka_lib_installed.png
+      :width: 60%
+
+   Це поле вказує на те, які бібліотеки використовуються у проєкті. PlatformIO автоматично завантажує та встановлює всі бібліотеки, вказані у цьому полі, а також їх залежності.
+
+   Встановлення бібліотеки ``lilka`` автоматично встановлює різні бібліотеки для роботи з Лілкою, наприклад ``Arduino-GFX``, яка використовується для роботи з дисплеєм Лілки.
+
+5. Напишемо простий код нашої прошивки. Відкрийте файл ``src/main.cpp`` та напишіть наступний код:
+
+   .. code-block:: cpp
+
+      #include <lilka.h>
+
+      void setup() {
+        // Ця функція виконається один раз при увімкненні
+
+        // Ініціалізуємо дисплей, карту пам'яті, звук, кнопки і все на світі
+        lilka::begin();
+
+        // Заповнюємо екран білим кольором
+        lilka::display.fillScreen(lilka::colors::White);
+      }
+
+      void loop() {
+        // Ця функція буде виконуватись по колу
+
+        // Читаємо стан кнопок
+        lilka::State state = lilka::controller.getState();
+
+        if (state.a.justPressed) {
+          // Кнопка A щойно була натиснена
+          lilka::display.fillScreen(lilka::colors::Red);
+          lilka::buzzer.play(lilka::NOTE_C4);
+        } else if (state.a.justReleased) {
+          // Кнопка A щойно буда відпущена
+          lilka::display.fillScreen(lilka::colors::Green);
+          lilka::buzzer.stop();
+        }  
+      }
+
+   Це - проста програма, яка при натисканні на кнопку A змінює колір екрану на червоний та відтворює звук, а при відпусканні - заповнює екран зеленим кольором та зупиняє звук.
+
+   .. image:: ./images/custom_firmware/10_simple_program.png
+      :width: 60%
+
+6. Тепер ми можемо скомпілювати нашу прошивку та завантажити її в Лілку.
+
+   Для цього під'єднайте Лілку до комп'ютера за допомогою USB-кабеля, відкрийте вкладку ``PlatformIO`` та натисніть на дію ``Upload``.
+
+   .. image:: ./images/custom_firmware/12_compiling.png
+      :width: 60%
+
+   Після завершення компіляції та завантаження прошивки ви побачите, як Лілка виконує вашу програму. Спробуйте натиснути та відпустити кнопку A та переконайтеся, що все працює!
diff --git a/docs/programming/development.rst b/docs/programming/development.rst
diff --git a/docs/programming/images/custom_firmware/01_pio_new_proj.png b/docs/programming/images/custom_firmware/01_pio_new_proj.png
diff --git a/docs/programming/images/custom_firmware/02_pio_new_proj_2.png b/docs/programming/images/custom_firmware/02_pio_new_proj_2.png
diff --git a/docs/programming/images/custom_firmware/03_pio_new_proj_sel_lilka.png b/docs/programming/images/custom_firmware/03_pio_new_proj_sel_lilka.png
diff --git a/docs/programming/images/custom_firmware/04_project_ready.png b/docs/programming/images/custom_firmware/04_project_ready.png
diff --git a/docs/programming/images/custom_firmware/05_install_lilka_lib.png b/docs/programming/images/custom_firmware/05_install_lilka_lib.png
diff --git a/docs/programming/images/custom_firmware/06_install_lilka_lib.png b/docs/programming/images/custom_firmware/06_install_lilka_lib.png
diff --git a/docs/programming/images/custom_firmware/07_install_lilka_lib.png b/docs/programming/images/custom_firmware/07_install_lilka_lib.png
diff --git a/docs/programming/images/custom_firmware/08_lilka_lib_installed.png b/docs/programming/images/custom_firmware/08_lilka_lib_installed.png
diff --git a/docs/programming/images/custom_firmware/09_lilka_begin.png b/docs/programming/images/custom_firmware/09_lilka_begin.png
diff --git a/docs/programming/images/custom_firmware/10_simple_program.png b/docs/programming/images/custom_firmware/10_simple_program.png
diff --git a/docs/programming/images/custom_firmware/11_start_build.png b/docs/programming/images/custom_firmware/11_start_build.png
diff --git a/docs/programming/images/custom_firmware/12_compiling.png b/docs/programming/images/custom_firmware/12_compiling.png
diff --git a/docs/programming/index.rst b/docs/programming/index.rst
@@ -12,5 +12,5 @@
 
     environment
     keira
-    development
+    custom_firmware
     extension
diff --git a/docs/programming/keira.rst b/docs/programming/keira.rst
@@ -6,3 +6,5 @@ Keira OS
 **Keira** - це операційна система, що базується на проєкті FreeRTOS. Вона підтримує мультизадачність, мережу, запуск Lua-програм та сторонніх прошивок з SD-карти та багато іншого.
 
 Більше інформації про **Keira OS** - на сторінці :ref:`keira-firmware-features`.
+
+Якщо вам кортить якнайшвидше спробувати **Keira OS**, переходьте на сторінку :ref:`keira-flashing`.