Final Documentation Adjustments Before Version 1.0

[clauspruefer]

Description

Documentation Fine-tuning.

[Copilot]

Pull request overview

Documentation-only PR focused on readability and “last mile” adjustments ahead of v1.0, primarily by reflowing long paragraphs and adding a small amount of usage guidance.

Changes:

• Reflowed/line-wrapped multiple Markdown documents for improved readability.
• Added dependency + compilation/run instructions to the vector-cube SDL mockup README.
• Minor wording tweaks across build and decision-history docs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
README.md	Reformats introductory documentation text and warnings for readability.
mockup/vector-cube/README.md	Adds dependency/install + compile/run instructions and reflows existing mockup notes.
DECISIONS.md	Reflows decision-history text for readability.
BUILD.md	Reflows build instructions, especially around MicroPython embedding steps.

Suppressed comments (4)

DECISIONS.md:18

• Spelling/capitalization: "Seperating" -> "Separating" and "python" -> "Python"; also split the run-on sentence for readability.

Seperating the web server and the python code could be done using 2 RTOS tasks, on dual-core controllers the
*MicroPython* task later on can be run on a different CPU core.

DECISIONS.md:33

• Spelling/grammar: "realtime" -> "real time" and "transfered" -> "transferred"; the current text is also a run-on sentence.

The ESP32-C3 has an attached OLED 1306 display which renders the complete game in realtime. The ESP32-C3 integrated
web server will also host the application files, on smartphone browser connect the application will be transfered to
the browser, started; following communication is abstracted via HTTP/1.1 POST with JSON payload.

DECISIONS.md:38

• Grammar: "applications host" should be possessive ("application's host").

To connect the smartphones without using other peripherals, we also will integrate a micro-tiny DNS (UDP-only)
server which will only react on a single *static* DNS IPv4 A query to the applications host *pong.game*.

mockup/vector-cube/README.md:35

• This sentence is grammatically incorrect ("..., if ... behaves like expected must ..."). Rephrase to avoid the run-on and use "as expected".

The C++ line drawing routines have been validated using this Linux SDL mockup, if the line drawing
routine included in `/src/components/peripherals/ssd1306.c` behaves like expected must be checked
directly on the ESP32 device.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

DECISIONS.md:18

• Spelling: “Seperating” should be “Separating”.

Seperating the web server and the python code could be done using 2 RTOS tasks, on dual-core controllers the
*MicroPython* task later on can be run on a different CPU core.

DECISIONS.md:33

• Spelling: “transfered” should be “transferred”.

The ESP32-C3 has an attached OLED 1306 display which renders the complete game in realtime. The ESP32-C3 integrated
web server will also host the application files, on smartphone browser connect the application will be transfered to
the browser, started; following communication is abstracted via HTTP/1.1 POST with JSON payload.

BUILD.md:16

• The internal link to section 5 still points to the old heading anchor (#5-install-esp-idf). Since the section heading was renamed to “ESP-IDF Installation”, this link will be broken on GitHub.

The *ESP-IDF* Development Framework (see [section 5](#5-install-esp-idf)), `Python 3`, `python3-venv`, `pip3`, and `CMake` must

DECISIONS.md:9

• Spelling: “seperate” should be “separate”.

This issue also appears in the following locations of the same file:

• line 17
• line 31

The *FalconAS* Linux port allows binding processes to CPU core IDs. The ESP32-C3 is a single core processor,
and thus limited. A *bigger* variant ESP32-S3 integrates 2 CPU cores, it could be a good idea to seperate the
web server processing and the *MicroPython* code execution.

mockup/vector-cube/README.md:35

• This sentence has a comma splice and awkward phrasing (“behaves like expected”). Rewording would make the instructions clearer.

The C++ line drawing routines have been validated using this Linux SDL mockup, if the line drawing
routine included in `/src/components/peripherals/ssd1306.c` behaves like expected must be checked
directly on the ESP32 device.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

BUILD.md:98

• This new clone block leaves the shell in ~/src/micropython. A user who then follows the ESP32-C3 path in section 7.3 will resolve cd src/esp-idf as ~/src/micropython/src/esp-idf, which does not exist. Return to a known directory here (or make the C3 paths absolute).

git checkout embedding

BUILD.md:52

• The setup assumes ~/src already exists, but this is the first command that uses it. On a clean account, cd fails and the clone happens from the caller's previous directory. Create the directory before entering it.

cd ~/src

mockup/vector-cube/README.md:18

• The newly documented compile command currently fails: compile.sh builds test-sdl-animation.cpp, which includes the nonexistent ../../src/components/peripherals/cube-animation.hpp; the header is now at ../../src/main/cube-animation.hpp. Update that source include before advertising this command as runnable.

./compile.sh

mockup/vector-cube/README.md:35

• This paragraph points to a nonexistent file (components/peripherals/ssd1306.c) and says device verification is still pending, while the newly added note says the ESP32-S3 implementation has been verified. Use the actual components/ssd1306/ssd1306.c path and make the status consistent.

The C++ line drawing routines have been validated using this Linux SDL mockup, if the line drawing
routine included in `/src/components/peripherals/ssd1306.c` behaves like expected must be checked
directly on the *ESP32* device.