Skip to content

Commit 8b60766

Browse files
qlrdqlrd
committed
docs: add source documentation for readthedocs poe task
This commit add a big set of techinical documentation for every package, module and function of krux `firmware`. It's important to say that the `src.boot` isnt autogenerated and `src.krux` is. This happen because of issues during setup that could be fixed in a followup.
1 parent 29ed270 commit 8b60766

File tree

89 files changed

+1031
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

89 files changed

+1031
-0
lines changed

‎docs/source/modules.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Overview
2+
========
3+
4+
.. module:: src.boot
5+
:synopsis: Krux source package
6+
:platform: RISC-V K210
7+
8+
.. moduleauthor:: Jeff Sun
9+
10+
The `krux` firmware is divided between two modules, packaged on ``src``:
11+
12+
- 📦 ``src``: the parent module that encapsulate all the firmware source code;
13+
14+
- 🥾 ``src.boot``: a module to load the firmware onto the device;
15+
- 🧙🏼‍♂️ ``src.krux``: a module to cook potions, write magic and enchantments.
16+
17+
18+
.. toctree::
19+
:maxdepth: 2
20+
21+
src

‎docs/source/src.boot.rst‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
🥾 src.boot module
2+
==================
3+
4+
.. module:: src.boot
5+
:synopsis: Boot sequence for Krux devices
6+
:platform: Linux, MacOS, Windows
7+
8+
.. moduleauthor:: Jeff Sun
9+
10+
The boot module handles the initial startup sequence for Krux hardware devices.
11+
12+
.. warning::
13+
This module requires hardware-specific dependencies and cannot be fully
14+
auto-documented in a standard Python environment.
15+
16+
The ``src/boot.py`` module is the entry point when a Krux device powers on. It:
17+
18+
1. Initializes the display hardware
19+
2. check for firmware updates and forbid to do downgrades;
20+
3. initial garbage collection;
21+
4. check for ``tc_code_verification``;
22+
5. Launches the main application (`login` and `home` methods).
23+
24+
25+
📞 The five callers
26+
^^^^^^^^^^^^^^^^^^^
27+
28+
This is made through 5 methods:
29+
30+
- ``src.krux.on_preimport_ticks``;
31+
- ``src.krux.on_postimport_ticks``;
32+
- ``src.krux.on_tc_code_verification``;
33+
- ``src.krux.on_run``;
34+
- ``src.krux.on_shutdown``
35+
36+
You can check them at the end of ``src/boot.py``:
37+
38+
.. code-block:: python
39+
40+
preimport_ticks = on_preimport_ticks()
41+
42+
ctx.power_manager = power_manager
43+
auto_shutdown.add_ctx(ctx)
44+
45+
on_postimport_ticks(preimport_ticks)
46+
on_tc_code_verification(power_manager)
47+
on_run()
48+
on_shutdown()
49+
50+
51+
⚙️ Functions
52+
^^^^^^^^^^^^
53+
54+
.. py:function:: check_for_updates()
55+
56+
Checks SD card, if a valid firmware is found asks if user wants to update the device.
57+
58+
.. py:function:: draw_splash()
59+
60+
Draws the Krux splash screen on the device display during boot.
61+
62+
.. py:function:: login(ctx_login)
63+
64+
Loads and run the Login page.
65+
66+
.. py:function:: home(ctx_home)
67+
68+
Loads and run the Login page.
69+
70+
.. py:function:: main()
71+
72+
Main entry point that initializes all hardware and starts the application loop.
73+
74+
.. py:function:: on_preimport_ticks()
75+
76+
Draw K logo, check for new firmare and make garbage collector work.
77+
78+
.. py:function:: on_postimport_ticks(pt)
79+
80+
If importing happened too fast, sleep the difference so the logo will be shown.
81+
82+
.. py:function:: on_tc_code_verification(pm)
83+
84+
Check for TC_CODE and if it fails, shutdown the device.
85+
86+
.. py:function:: on_run()
87+
88+
Basic architecture of krux:
89+
90+
- Runs ``src.krux.pages.login.Login`` page;
91+
- cleans memory calling ``garbage.collect``;
92+
- runs ``src.krux.pages.home.Home`` page.
93+
94+
.. code-block:: python
95+
96+
login(ctx)
97+
gc.collect()
98+
home(ctx)
99+
100+
.. py:function:: on_shutdown()
101+
102+
Clear the current ``src.krux.context.Context`` and calls ``power_manager.shutdown``.
103+
104+
.. py:function:: tc_code_verification(ctx_pin)
105+
106+
Loads and run the Pin Verification page.

‎docs/source/src.krux.auto_shutdown.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.auto\_shutdown module
2+
==============================
3+
4+
.. automodule:: src.krux.auto_shutdown
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.baseconv.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.baseconv module
2+
========================
3+
4+
.. automodule:: src.krux.baseconv
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.bbqr.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.bbqr module
2+
====================
3+
4+
.. automodule:: src.krux.bbqr
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.bip39.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.bip39 module
2+
=====================
3+
4+
.. automodule:: src.krux.bip39
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.buttons.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.buttons module
2+
=======================
3+
4+
.. automodule:: src.krux.buttons
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.camera.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.camera module
2+
======================
3+
4+
.. automodule:: src.krux.camera
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.context.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.context module
2+
=======================
3+
4+
.. automodule:: src.krux.context
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

‎docs/source/src.krux.display.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src.krux.display module
2+
=======================
3+
4+
.. automodule:: src.krux.display
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:

0 commit comments

Comments
 (0)