doc: add assembly instructions

and3rson · Apr 18, 2024 · 54ae2f2 · 54ae2f2
1 parent 14a952c
commit 54ae2f2
Show file tree

Hide file tree

Showing 31 changed files with 143 additions and 16 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -21,4 +21,4 @@ autobuild: clean doxygen
 
 .PHONY: clean
 clean:
-	rm -rf _build
+	rm -rf _build _doxygen/xml
diff --git a/docs/about/what_is_lilka.rst b/docs/about/what_is_lilka.rst
@@ -17,7 +17,7 @@
 - :ref:`Емулятор NES <sd-card-feature>`, який дозволить вам грати в нінтендівські ігри
 - Можливість :ref:`запускати DOOM <sd-card-feature>` з непоганим FPS
 - Вбудований WiFi- та Bluetooth-передавач
-- :doc:`Роз'єм розширення </manual/extension>` для під'єднання власних модулів
+- :ref:`Роз'єм розширення <extension>` для під'єднання власних модулів
 - :ref:`Підтримка Lua <lua-intro>` для легкого створення власних ігор та програм
 - Можливість запуску програм з SD-карти
 

diff --git a/docs/assembly/every_component.rst b/docs/assembly/every_component.rst
@@ -136,7 +136,7 @@
 
 Для цього і потрібен роз'єм розширення ``J2``: він має виводи для живлення сторонніх компонентів, а також декілька GPIO-ліній мікроконтролера, які можна використовувати для підключення додаткових пристроїв.
 
-Детальніше про роз'єм розширення можна прочитатиj тут: :ref:`extension`.
+Детальніше про роз'єм розширення можна прочитати в розділі :ref:`extension`.
 
 Модуль SD-карти (``J3``)
 ------------------------

diff --git a/docs/assembly/images/hover.png b/docs/assembly/images/hover.png
diff --git a/docs/assembly/images/hover.xcf b/docs/assembly/images/hover.xcf
diff --git a/docs/assembly/images/sandwich.png b/docs/assembly/images/sandwich.png
diff --git a/docs/assembly/images/sandwich.xcf b/docs/assembly/images/sandwich.xcf
diff --git a/docs/assembly/index.rst b/docs/assembly/index.rst
@@ -13,3 +13,4 @@
     configurations
     components
     every_component
+    instructions
diff --git a/docs/assembly/instructions.rst b/docs/assembly/instructions.rst
@@ -0,0 +1,95 @@
+Збір пристрою
+=============
+
+:term:`PCB` Лілки спроєктована для максимально простого збору зі збереженням її мінімального розміру.
+
+Більшість компонентів - це :term:`THT`-компоненти, тобто компоненти, які вставляються в отвори плати і паяються з задньої сторони. Це дозволяє збирати плату без використання спеціального обладнання.
+
+Декілька компонентів - це :term:`SMD`-компоненти, які паяються зверху. Серед них - мікроконтролер ESP32-S3-WROOM-1-N16R8, регулятор напруги TLV1117LV-33DCYR та транзистор IRLML6401.
+
+Порядок збору
+-------------
+
+1. **Перш за все, припаяйте SMD-компоненти.**
+
+   Вони займають найменше місця та не заважатимуть вам при пайці решти компонентів.**
+
+   * ``U1`` (мікроконтролер ESP32-S3-WROOM-1-N16R8)
+   * ``U3`` (регулятор TLV1117LV-33DCYR)
+   * ``Q1`` IRLML6401 (якщо ви використовуєте комплектацію з батареєю)
+
+2. **Припаяйте модуль USB-C** (``J1``).
+
+   Переконайтесь, що ви вставили модуль USB-C вірно. Він має бути вирівняний з краєм плати.
+
+   Є два способи паяти такі модулі на плату:
+
+   - **Спосіб 1**: Ви можете прикласти його до плати та вставити штирьові контакти крізь нього та плату, утворивши таким чином "сендвіч". Після цього вам потрібно припаяти штирьові контакти з обох сторін.
+     Таким чином модуль щільно прилягатиме до плати та не буде провисати.
+
+     .. image:: ./images/sandwich.png
+
+   - **Спосіб 2**: Ви можете спершу припаяти штирьові контакти на модуль USB-C, а потім припаяти модуль на плату. Цей спосіб простіший, але модуль буде провисати, оскільки між
+     ним та платою буде вільний простір, утворений пластиковим тримачем штирьових контактів.
+
+     .. image:: ./images/hover.png
+
+   Є й інші способи - не бійтесь проявляти креативність!
+
+3. **Якщо ви збираєте комплектацію з батареєю, припаяйте наступні компоненти (вони всі позначені пунктирними лініями на задній стороні плати)**
+
+   * ``Q1`` IRLML6401
+   * ``D1`` (діод 1N4001)
+   * Резистори ``R3`` (100 кОм) та ``R4`` (33 кОм)
+   * ``J4`` (модуль заряду/розряду батареї на базі TP4056)
+   * LiPo батарея на ваш вибір (припаюється безпосередньо до пінів модуля заряду/розряду, позначених як B+ та B-)
+
+   **Якщо ви збираєте комплектацію без батареї, не паяйте ці компоненти!**
+
+   Натомість **замкніть** джампер ``JP1``, який знаходиться всередині посадкового місця діода ``D1``. Для цього використайте паяльник та припій, щоб замкнути контакти джампера.
+
+4. **Припаяйте наступні компоненти:**
+
+   * Резистори ``R1`` (10 кОм) ``R2`` (100 кОм)
+   * Конденсатори ``C1``, ``C2`` та ``C3`` (1 мкФ)
+
+5. **Припаяйте 6-мм тактильні кнопки**:
+
+   * ``SW9`` (Select)
+   * ``SW10`` (Start)
+   * ``SW12`` (Start)
+
+6. **Припаяйте модуль SD-карти** ``J3``.
+
+   Як і модуль USB-C, модуль SD-карти можна припаяти двома способами.
+
+   **Переконайтесь, що ви вставили модуль SD-карти вірно!** Металеве гніздо для SD-карти повинне знаходитися **зовні** плати!
+
+7. **Припаяйте 8 12-мм кнопок**:
+
+   * ``SW1`` (Up)
+   * ``SW2`` (Down)
+   * ``SW3`` (Left)
+   * ``SW4`` (Right)
+   * ``SW5`` (A)
+   * ``SW6`` (B)
+   * ``SW7`` (C)
+   * ``SW8`` (D)
+
+8. **Якщо ви збираєте комплектацію зі звуком, припаяйте** :term:`ЦАП`-модуль ``U4`` (MAX98357A).
+
+   * Якщо ви плануєте паяти роз'єм для навушників, **обов'язково припаяйте всі 9 контактів модуля!** Після цього припаяйте роз'єм для навушників ``J6`` до плати.
+   * Якщо ж ви хочете використовувати власний динамік, **вам достатньо припаяти лише 7 основних контактів**, а контакти динаміка припаяти безпосередньо до пінів (+) та (-) модуля.
+
+9. **Припаяйте п'єзоелектричний динамік** ``BZ1``.
+
+   Він дозволяє відтворювати примітивні звуки. Він працює окремо від :term:`ЦАП`-модуля, тому ви можете використовувати його навіть якщо не паяєте :term:`ЦАП`-модуль.
+
+10. **Припаяйте роз'єм дисплея та роз'єм розширення:**
+
+   * ``U2`` (роз'єм дисплея типу "мама")
+   * ``J2`` (роз'єм розширення типу "тато")
+
+11. **Припаяйте вимикач живлення** ``SW11``.
+
+Вітаємо, ваша плата готова до використання! Тепер вам залишається лише завантажити програмне забезпечення на ESP32-S3. Для цього читайте наступний розділ - :ref:`programming`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -95,3 +95,10 @@ def setup(app):
 
 # -- Sphinx-Design ------------------------------------------------------------
 extensions.append("sphinx_design")
+
+# -- Hoverxref ---------------------------------------------------------------
+extensions.append("hoverxref.extension")
+hoverxref_roles = ["term"]
+hoverxref_role_types = {
+    "term": "tooltip",
+}
diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -37,3 +37,20 @@
     Легка скриптова мова програмування, яка використовується для написання скриптів та програм для вбудованих систем.
 
     Вона чудово підходить для :ref:`написання ігор <lua-intro>`!
+
+   PCB
+    "Printed Circuit Board", тобто "друкована плата". Плата, на якій розміщені електронні компоненти.
+
+   THT
+    "Through-Hole Technology", тобто "технологія з монтажем через отвори". Технологія монтажу електронних компонентів на плату через отвори.
+
+   SMD
+    "Surface-Mount Device", тобто "прилади з монтажем на поверхню". Технологія монтажу електронних компонентів на поверхню плати.
+
+   ЦАП
+    Цифро-аналоговий перетворювач (:term:`DAC`). Електронний пристрій, який перетворює цифрові сигнали в аналогові. Найчастіше використовується для відтворення звуку.
+
+   DAC
+    Digital-to-Analog Converter, тобто "цифро-аналоговий перетворювач".
+
+    Див. :term:`ЦАП`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -15,7 +15,7 @@
     about/index
     hardware/index
     assembly/index
-    manual/index
+    programming/index
     keira/index
     library/index
     faq/index

diff --git a/docs/keira/lua/reference/gpio.rst b/docs/keira/lua/reference/gpio.rst
@@ -1,7 +1,7 @@
 ``gpio`` - Керування GPIO-пінами
 ================================
 
-Функції для роботи з GPIO-пінами :doc:`роз'єму розширення </manual/extension>`.
+Функції для роботи з GPIO-пінами :ref:`роз'єму розширення <extension>`.
 
 Приклад:
 

diff --git a/docs/manual/index.rst b/docs/manual/index.rst
diff --git a/docs/manual/development.rst → docs/programming/development.rst b/docs/manual/development.rst → docs/programming/development.rst
diff --git a/docs/manual/environment.rst → docs/programming/environment.rst b/docs/manual/environment.rst → docs/programming/environment.rst
diff --git a/docs/manual/extension.rst → docs/programming/extension.rst b/docs/manual/extension.rst → docs/programming/extension.rst
diff --git a/docs/manual/gpio.svg → docs/programming/gpio.svg b/docs/manual/gpio.svg → docs/programming/gpio.svg
diff --git a/docs/manual/header.svg → docs/programming/header.svg b/docs/manual/header.svg → docs/programming/header.svg
diff --git a/docs/manual/images/01_download_vscode.png → ...programming/images/01_download_vscode.png b/docs/manual/images/01_download_vscode.png → ...programming/images/01_download_vscode.png
diff --git a/...ual/images/01_download_vscode_cropped.png → ...ing/images/01_download_vscode_cropped.png b/...ual/images/01_download_vscode_cropped.png → ...ing/images/01_download_vscode_cropped.png
diff --git a/docs/manual/images/04_install_platformio.png → ...gramming/images/04_install_platformio.png b/docs/manual/images/04_install_platformio.png → ...gramming/images/04_install_platformio.png
diff --git a/.../images/04_install_platformio_cropped.png → .../images/04_install_platformio_cropped.png b/.../images/04_install_platformio_cropped.png → .../images/04_install_platformio_cropped.png
diff --git a/...manual/images/06_download_git_for_win.png → ...amming/images/06_download_git_for_win.png b/...manual/images/06_download_git_for_win.png → ...amming/images/06_download_git_for_win.png
diff --git a/...mages/06_download_git_for_win_cropped.png → ...mages/06_download_git_for_win_cropped.png b/...mages/06_download_git_for_win_cropped.png → ...mages/06_download_git_for_win_cropped.png
diff --git a/...manual/images/07_use_vs_code_with_git.png → ...amming/images/07_use_vs_code_with_git.png b/...manual/images/07_use_vs_code_with_git.png → ...amming/images/07_use_vs_code_with_git.png
diff --git a/...mages/07_use_vs_code_with_git_cropped.png → ...mages/07_use_vs_code_with_git_cropped.png b/...mages/07_use_vs_code_with_git_cropped.png → ...mages/07_use_vs_code_with_git_cropped.png
diff --git a/docs/programming/index.rst b/docs/programming/index.rst
@@ -0,0 +1,16 @@
+.. _programming:
+
+:octicon:`book` Програмування
+=============================
+
+Отже, ви зібрали Лілку!
+
+В цьому розділі ви знайдете інструкції, як налаштувати робоче середовище, як її запрограмувати, як розширити функціонал, а також як розробляти власні розширення.
+
+.. toctree::
+    :maxdepth: 1
+
+    environment
+    keira
+    development
+    extension
diff --git a/docs/manual/keira.rst → docs/programming/keira.rst b/docs/manual/keira.rst → docs/programming/keira.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 breathe==4.35.0
 sphinx-design==0.5.0
+sphinx-hoverxref==1.3.0
 sphinx-lua==1.1.5
 sphinx-rtd-theme==1.3.0
 sphinx-toolbox==3.5.0

diff --git a/sdk/addons/lualilka/library/gpio.lua b/sdk/addons/lualilka/library/gpio.lua
@@ -26,7 +26,7 @@ function gpio.read(pin) end
 ---Читає аналогове значення з GPIO-піна. Воно може бути в діапазоні від ``0`` до ``4095`` (включно).
 ---
 ---Майте на увазі, що ця функція працює тільки з пінами, які підтримують аналогове введення.
----Детальніше про це - на сторінці :doc:`/manual/extension`.
+---Детальніше про це - на сторінці :ref:`extension`.
 ---@param pin integer номер піна
 ---@return integer
 function gpio.analog_read(pin) end