From 209d8abe97422ef9486084202004797aba2f408a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 11 Aug 2026 16:15:37 +0200 Subject: [PATCH 1/5] Update, correct format and content --- BUILD.md | 45 +++++++----- DECISIONS.md | 23 ++++-- README.md | 137 ++++++++++++++++++++++++++--------- mockup/vector-cube/README.md | 31 +++++++- 4 files changed, 172 insertions(+), 64 deletions(-) diff --git a/BUILD.md b/BUILD.md index a6bb0d7..0f58183 100644 --- a/BUILD.md +++ b/BUILD.md @@ -4,7 +4,8 @@ This document describes the build process and requirements. ## 1. Operating System -We recommend using a standard Debian-based Linux distribution. Compilation has been tested on *Devuan* (Debian-based) and on an *Ubuntu Hardened 26.04 LTS* system. +We recommend using a standard Debian-based Linux distribution. Compilation has been tested on *Devuan* (Debian-based) and on +an *Ubuntu Hardened 26.04 LTS* system. ## 2. Cabling @@ -12,7 +13,8 @@ Make sure you also have a working USB-C or USB-C-to-USB cable and all peripheral ## 3. Requirements -The *ESP-IDF* Development Framework (see [section 5](#5-install-esp-idf)), `Python 3`, `python3-venv`, `pip3`, and `CMake` must be installed before proceeding. +The *ESP-IDF* Development Framework (see [section 5](#5-install-esp-idf)), `Python 3`, `python3-venv`, `pip3`, and `CMake` must +be installed before proceeding. ```bash apt-get install python3 python3-venv python3-pip cmake @@ -20,7 +22,8 @@ apt-get install python3 python3-venv python3-pip cmake ### 3.1. External Includes -The following external static libraries and C++ header files—including a *patched* *MicroPython* **embed port**—must be cross-compiled for the matching target architecture. Instructions for the **ESP32-C3** and **ESP32-S3** boards are linked below. +The following external static libraries and C++ header files—including a *patched* *MicroPython* **embed port**—must be cross-compiled +for the matching target architecture. Instructions for the **ESP32-C3** and **ESP32-S3** boards are linked below. The list below provides an overview of exactly what these libraries are used for. @@ -39,7 +42,8 @@ A short overview of the framework features before continuing with the installati ## 5. Install ESP-IDF -The installation process is one of the easiest I have ever encountered. Programming, compiling, and external component integration are also very straightforward **without** losing any flexibility. +The installation process is one of the easiest I have ever encountered. Programming, compiling, and external component integration +are also very straightforward **without** losing any flexibility. Clone and install *ESP-IDF* as a development user (non-root). @@ -69,17 +73,15 @@ Done! You can now compile ESP-IDF projects. ## 7. Cross-Compiling MicroPython The standard *MicroPython* repository does not support out-of-the-box cross-compilation to a static library for embedding into external projects. -A dedicated fork at [clauspruefer/micropython](https://github.com/clauspruefer/micropython/tree/embedding) (branch `embedding`) provides CMake-based build examples that produce `libmicropython.a` for each *ESP32* target architecture using the *ESP-IDF* cross-compiler toolchain. +A dedicated fork at [clauspruefer/micropython](https://github.com/clauspruefer/micropython/tree/embedding) (branch `embedding`) provides CMake-based +build examples that produce `libmicropython.a` for each *ESP32* target architecture using the *ESP-IDF* cross-compiler toolchain. -This fork also adds the `mp_embed_exec_string_function(char* function_name, char* function_param_value)` function, which enables direct C/C++ calls to *MicroPython* functions with a single string (JSON) parameter. This is used internally to pass JSON messages from the C++ application server layer to the running *MicroPython* interpreter / PONG structures. +This fork also adds the `mp_embed_exec_string_function(char* function_name, char* function_param_value)` function, which enables direct C/C++ calls +to *MicroPython* functions with a single string (JSON) parameter. This is used internally to pass JSON messages from the C++ application server layer +to the running *MicroPython* interpreter / PONG structures. -> [!WARNING] -> The *ESP-IDF* framework, including cross-compilers for **ESP32-C3** and **ESP32-S3** (installed in your `$HOME/.espressif` directory), must be installed and activated before cross-compiling. - -> [!NOTE] -> Also clone the upstream *MicroPython* source tree (`https://github.com/micropython/micropython.git`), as it is required by the embed build step. - -The **ESP32-C3** (RISC-V RV32IMC) and **ESP32-S3** (Xtensa LX7) are completely different architectures and require separate build steps. Detailed per-variant instructions are available at: +The **ESP32-C3** (RISC-V RV32IMC) and **ESP32-S3** (Xtensa LX7) are completely different architectures and require separate build steps. +Detailed per-variant instructions are available at: - **ESP32-S3**: https://github.com/clauspruefer/micropython/blob/embedding/examples/embedding/esp32/s3/README.md - **ESP32-C3**: https://github.com/clauspruefer/micropython/blob/embedding/examples/embedding/esp32/c3/README.md @@ -144,7 +146,8 @@ After installation the static library and header are placed at: ## 8. Cross-Compiling HTTP Libraries -The HTTP/1.1 parser and message-generator libraries from the [WEBcodeX1/http-1.2](https://github.com/WEBcodeX1/http-1.2) project must also be cross-compiled for the target *ESP32* architecture before building `micropython-as`. +The HTTP/1.1 parser and message-generator libraries from the [WEBcodeX1/http-1.2](https://github.com/WEBcodeX1/http-1.2) project +must also be cross-compiled for the target *ESP32* architecture before building `micropython-as`. Detailed instructions for each board type are available under the `ports/arduino/` subdirectory of that repository: @@ -208,7 +211,9 @@ After installation the static library and headers are placed at: Change to the `micropython-as` repository, select your board type, compile it, and then flash it to the microcontroller. > [!WARNING] -> The current default board, including settings, is **ESP32-S3**, not **ESP32-C3**. There are also **hardcoded** *GPIO* settings inside the C++ header files that you currently must change manually. Also note that the **ESP32-C3** MicroPython interpreter currently crashes on floating-point arithmetic. +> The current default board, including settings, is **ESP32-S3**, not **ESP32-C3**. There are also **hardcoded** *GPIO* +> settings inside the C++ header files that you currently must change manually. Also note that the **ESP32-C3** *MicroPython* +> interpreter currently crashes on floating-point arithmetic. ```bash cd ~/src/micropython-as/src @@ -222,7 +227,9 @@ idf.py flash ## 10. Linux Server Build (Stability Testing) -The HTTP server component can be compiled and run as a **native Linux binary** for stability and crash analysis — without any *ESP32* hardware, *ESP-IDF*, or *FreeRTOS*. This enables the use of tools such as `gdb`, Valgrind, and the Clang/GCC sanitizers (AddressSanitizer, ThreadSanitizer) to pinpoint crashes and timeout-related bugs. +The HTTP server component can be compiled and run as a **native Linux binary** for stability and crash analysis — without any +*ESP32* hardware, *ESP-IDF*, or *FreeRTOS*. This enables the use of tools such as `gdb`, Valgrind, and the Clang/GCC sanitizers +(AddressSanitizer, ThreadSanitizer) to pinpoint crashes and timeout-related bugs. Only the following components are compiled: @@ -234,9 +241,11 @@ WiFi, DNS, LED, display, and MicroPython execution are **not** included. ### 10.1. Prerequisites -The same HTTP parser and generator libraries from the FalconAS project are required, but built for the **host Linux architecture** instead of a microcontroller cross-target. +The same HTTP parser and generator libraries from the FalconAS project are required, but built for the **host Linux architecture** +instead of a microcontroller cross-target. -Follow the instructions in the [WEBcodeX1/http-1.2](https://github.com/WEBcodeX1/http-1.2) repository under `ports/linux/` and install the resulting static libraries and headers: +Follow the instructions in the [WEBcodeX1/http-1.2](https://github.com/WEBcodeX1/http-1.2) repository under `ports/linux/` and install +the resulting static libraries and headers: ``` /usr/local/lib/linux/libhttpparser.a or /usr/local/libs/libhttpparser.a diff --git a/DECISIONS.md b/DECISIONS.md index 7f4438e..0fcc159 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -4,29 +4,38 @@ This document should give insights about the **WHY** we did **WHAT** and **WHEN* ## Multiprocessing -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. +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. -To produce clean code we should abstract these two layers for both a) single core and b) dual core processing in a generic way. These two possibilities exist: +To produce clean code we should abstract these two layers for both a) single core and b) dual core processing +in a generic way. These two possibilities exist: - RTOS tasks - C++11 threading library -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. +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. > [!NOTE] -> The C++ POSIX Thread Wrapper Library runs perfectly on the ESP-IDF platform. The LED fading control has been implemented using the POSIX thread API. Additionally, because RISC-V 32-bit and Xtensa 32-bit chipsets execute atomic reads and writes of 32-bit variables, using a thread::lock is unnecessary for simple, unprotected read / write mechanisms. +> The C++ POSIX Thread Wrapper Library runs perfectly on the ESP-IDF platform. The LED fading control has been +> implemented using the POSIX thread API. Additionally, because RISC-V 32-bit and Xtensa 32-bit chipsets execute +> atomic reads and writes of 32-bit variables, using a thread::lock is unnecessary for simple, unprotected +> read / write mechanisms. ## Project Goal The project goal is to provide a in-web-server playable PONG game on two connected wifi-clients (smartphones). The ESP32-C3 acts as a Micropython Application Server, the game logic will be programmed in Python. -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. +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. ## DNS -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*. +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*. The DNS server also will be *run* as RTOS task. diff --git a/README.md b/README.md index dfe4a0e..4a10d26 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,22 @@ # Embedding MicroPython in a C++ HTTP/1.1 Application Server (ESP32-S3, ESP32-C3) -This project embeds *MicroPython* in *ESP32* microcontrollers using the **Falcon-AS** C++ HTTP/1.1 parser library -and modified application server code adapted to the microcontroller architecture. +This project embeds *MicroPython* in *ESP32* microcontrollers using the **Falcon-AS** +C++ HTTP/1.1 parser library and modified application server code adapted to the microcontroller +architecture. Refer to [./BUILD.md](./BUILD.md) to learn how to build the project. -I have added some videos showing the current project status / progress in [./video/](./video/) (gameplay and browser integration). +I have added some videos showing the current project status / progress in [./video/](./video/) +(gameplay and browser integration). > [!WARNING] -> Currently, only the **ESP32-S3** is supported. **ESP32-C3** *MicroPython* crashes during floating-point math processing. +> Currently, only the **ESP32-S3** is supported. **ESP32-C3** *MicroPython* crashes during +> floating-point math processing. # 1. Architecture -The following diagrams show a comparison between the native *MicroPython* design and architecture and our HTTP application server approach. +The following diagrams show a comparison between the native *MicroPython* design and architecture +and our HTTP application server approach. ## 1.1. MicroPython Architecture @@ -49,7 +53,9 @@ The following diagrams show a comparison between the native *MicroPython* design # 3. ESP32-C3 SoC -[Espressif Systems](https://www.espressif.com/) developed the **ESP32-C3** system-on-chip, based on a 32-bit single-core RISC-V CPU. Ready-to-use boards are available from *Seeed Studio* (XIAO ESP32-C3 mini board) at an affordable price point (5€ :moneybag::star2:). +[Espressif Systems](https://www.espressif.com/) developed the **ESP32-C3** system-on-chip, based +on a 32-bit single-core RISC-V CPU. Ready-to-use boards are available from *Seeed Studio* +(XIAO ESP32-C3 mini board) at an affordable price point (5€ :moneybag::star2:). ## 3.1. Base Features @@ -69,7 +75,8 @@ The following diagrams show a comparison between the native *MicroPython* design ## 3.2. Detailed Hardware Specs -For detailed hardware information, start with the manufacturer's wiki: https://wiki.seeedstudio.com/XIAO_ESP32C3_Getting_Started/. +For detailed hardware information, start with the manufacturer's wiki: +https://wiki.seeedstudio.com/XIAO_ESP32C3_Getting_Started/. # 4. Variants @@ -77,18 +84,23 @@ There are also several notable variants. ## 4.1. ESP32-S3 -ESP32-S3R8 Xtensa LX7 dual-core 240 MHz system with optional external HAT extensions, for example a camera or audio add-on. +ESP32-S3R8 Xtensa LX7 dual-core 240 MHz system with optional external HAT extensions, for +example a camera or audio add-on. > [!NOTE] -> The current ESP-IDF integrates a *transparent* C++11 threading implementation that makes code execution across multiple CPU cores much easier :heart_eyes:. +> The current ESP-IDF integrates a *transparent* C++11 threading implementation that makes +> code execution across multiple CPU cores much easier :heart_eyes:. ## 4.2. ESP32-P4 -A high-performance, highly secure board (**without** integrated Wi-Fi or Bluetooth), with attachable MicroSD card and PHY Ethernet (IP101GR). +A high-performance, highly secure board (**without** integrated Wi-Fi or Bluetooth), with +attachable MicroSD card and PHY Ethernet (IP101GR). # 5. Development Frameworks -With this amount of system memory, development should be straightforward. However, there are multiple pitfalls. This document discusses how to choose the **correct** SDK (software development kit) from the available options for your requirements. +With this amount of system memory, development should be straightforward. However, there +are multiple pitfalls. This document discusses how to choose the **correct** SDK (software +development kit) from the available options for your requirements. The following SDKs are usable and working: @@ -98,19 +110,28 @@ The following SDKs are usable and working: # 6. Operating System -Before continuing, here is a short remark about RTOSes (real-time operating systems). In **embedded** multi-core systems, it is advisable to use such a layer to separate, for example, the *Wi-Fi / network stack* from *application code* into **layers / controllable tasks** to improve stability and reduce programming mistakes. +Before continuing, here is a short remark about RTOSes (real-time operating systems). +In **embedded** multi-core systems, it is advisable to use such a layer to separate, for +example, the *Wi-Fi / network stack* from *application code* into **layers / controllable tasks** +to improve stability and reduce programming mistakes. > [!NOTE] > In a single-core microcontroller system, such a design can be counterproductive. -The Espressif ESP-IDF framework integrates *FreeRTOS* into all boards, including the *ESP32-C3* **single-core** devices. This introduces moderate overhead. The implementation details, including advantages and disadvantages of the different SDK approaches, are discussed in the following sections. +The Espressif ESP-IDF framework integrates *FreeRTOS* into all boards, including the +*ESP32-C3* **single-core** devices. This introduces moderate overhead. The implementation +details, including advantages and disadvantages of the different SDK approaches, are +discussed in the following sections. > [!NOTE] -> Using an embedded Linux operating system is only advisable for **much larger** systems where significantly more high-speed peripherals (for example PCIe, multiple 100 GbE NICs, or multiple GPU / DisplayPort devices) must be coordinated. +> Using an embedded Linux operating system is only advisable for **much larger** systems +> where significantly more high-speed peripherals (for example PCIe, multiple 100 GbE NICs, +> or multiple GPU / DisplayPort devices) must be coordinated. # 7. Global Advantages / Disadvantages -Each of the following SDK variants has advantages and disadvantages and is aimed at programmers with different skill levels. +Each of the following SDK variants has advantages and disadvantages and is aimed at +programmers with different skill levels. ## 7.1. Advantages @@ -125,60 +146,98 @@ First, here is a quick overview of useful features included in all SDK variants: ## 7.2. Disadvantages -There are quite a few global disadvantages. The first is the lack of *example networking code* at higher OSI layers, and the second is *exorbitant bloat* in default setups. +There are quite a few global disadvantages. The first is the lack of *example networking code* +at higher OSI layers, and the second is *exorbitant bloat* in default setups. -Many people start development with the native *Arduino IDE*, which is very easy to set up and can be ready for use within minutes after installing the correct board extensions. When compiling the first lines of a simple **sketch** (Arduino project identifier), the first impression is usually that compile times are slow and the resulting flash image is large. +Many people start development with the native *Arduino IDE*, which is very easy to set +up and can be ready for use within minutes after installing the correct board extensions. +When compiling the first lines of a simple **sketch** (Arduino project identifier), the first +impression is usually that compile times are slow and the resulting flash image is large. -I tested a simple Wi-Fi access point implementation with minimal TCP server processing, which resulted in a 1 MB flash image. This is sufficient for the ESP32-C3, but still heavily bloated (details follow below). +I tested a simple Wi-Fi access point implementation with minimal TCP server processing, +which resulted in a 1 MB flash image. This is sufficient for the ESP32-C3, but still heavily +bloated (details follow below). # 8. MicroPython -MicroPython is the choice for the least-experienced C / C++ developer. There is no need **at all** to write C / C++ code. +MicroPython is the choice for the least-experienced C / C++ developer. There is no need +**at all** to write C/C++ code. -But how exactly is MicroPython integrated into the microcontroller? It is *not* **only** a Python interpreter compiled for microcontrollers. MicroPython is *integrated* into the ESP32 RTOS subsystem, bootloader, and main loop. In practice, this means that when the microcontroller boots, the Python interpreter and *additional* **control code** are loaded into the upper memory regions, initialized, started, and then run continuously. +But how exactly is MicroPython integrated into the microcontroller? It is *not* **only** +a Python interpreter compiled for microcontrollers. MicroPython is *integrated* into the ESP32 +RTOS subsystem, bootloader, and main loop. In practice, this means that when the microcontroller +boots, the Python interpreter and *additional* **control code** are loaded into the upper memory +regions, initialized, started, and then run continuously. -Depending on the microcontroller used, this enables uploading, running, flashing, and compiling Python code to bytecode without reflashing the complete firmware. An interpreter console CLI is also accessible over serial to control the interpreter at runtime. +Depending on the microcontroller used, this enables uploading, running, flashing, and compiling +Python code to bytecode without reflashing the complete firmware. An interpreter console CLI is +also accessible over serial to control the interpreter at runtime. -Regarding performance and firmware size optimization, MicroPython allows additional Python modules to be integrated as *pre-compiled bytecode* (virtual filesystem partition) or even *frozen bytecode* (directly into the firmware blob). This makes runtime compilation obsolete and improves performance. As a practical example, controlling a common I2C SSD1306 OLED display using the Python `machine` and `ssd1306` library will not make any noticeable difference compared to a C / C++ implementation. +Regarding performance and firmware size optimization, MicroPython allows additional Python +modules to be integrated as *pre-compiled bytecode* (virtual filesystem partition) or even +*frozen bytecode* (directly into the firmware blob). This makes runtime compilation obsolete and +improves performance. As a practical example, controlling a common I2C SSD1306 OLED display using +the Python `machine` and `ssd1306` library will not make any noticeable difference compared to a +C/C++ implementation. ## 8.1. Disadvantages -Upper-layer networking **server** libraries (including many RPC mechanisms) are **not** easy to implement for inexperienced developers and usually require a significant amount of code. In addition, many protocols and libraries are bloated with features that increase complexity and firmware size. +Upper-layer networking **server** libraries (including many RPC mechanisms) are **not** easy +to implement for inexperienced developers and usually require a significant amount of code. In +addition, many protocols and libraries are bloated with features that increase complexity and +firmware size. > [!NOTE] -> Our project modifies the MicroPython implementation by replacing MicroPython's control logic with a **very simplified** C++ HTTP/1.1 TLS-capable web server (with unnecessary HTTP features removed). On an HTTP POST request with a JSON payload, it executes a MicroPython script with that payload. +> Our project modifies the MicroPython implementation by replacing MicroPython's control logic +> with a **very simplified** C++ HTTP/1.1 TLS-capable web server (with unnecessary HTTP features +> removed). On an HTTP POST request with a JSON payload, it executes a MicroPython script with +> that payload. # 9. ESP-IDF -The IoT Development Framework (ESP-IDF) is more hardware-centric than the Arduino IDE. The application code—**setup** and **main loop**—must be implemented as *FreeRTOS* tasks, so it is more complex than the Arduino IDE. +The IoT Development Framework (ESP-IDF) is more hardware-centric than the Arduino IDE. The +application code—**setup** and **main loop**—must be implemented as *FreeRTOS* tasks, so it is +more complex than the Arduino IDE. -Inside the IDF, many components are much better designed, and using the framework *feels* much nicer from a developer's point of view. Also, the customization process in version 6.1 is very good, giving the developer much better control over included functionality and allowing significantly smaller firmware images. +Inside the IDF, many components are much better designed, and using the framework *feels* much +nicer from a developer's point of view. Also, the customization process in version 6.1 is very +good, giving the developer much better control over included functionality and allowing +significantly smaller firmware images. > [!NOTE] -> We chose ESP-IDF as the development environment, and the project code also demonstrates how to work with advanced ESP-IDF features. +> We chose ESP-IDF as the development environment, and the project code also demonstrates how +> to work with advanced ESP-IDF features. ## 9.1. Advantages -The ESP-IDF framework is much more flexible than the Arduino IDE. Including external C / C++ libraries and writing your own libraries both follow current development practices / standards. +The ESP-IDF framework is much more flexible than the Arduino IDE. Including external C/C++ +libraries and writing your own libraries both follow current development practices / standards. ### 9.1.1. Kconfig -The famous *Kconfig* framework, invented by the Linux kernel for customizing kernel builds, is used for multiple purposes: +The famous *Kconfig* framework, invented by the Linux kernel for customizing kernel builds, +is used for multiple purposes: 1. customize **global** library functions (for example disable IPv6 in the lwIP stack) 2. customize **own** features (for example disable HTTPS) -This is done by mapping compiler preprocessor directives inside a custom `/main/Kconfig.projbuild` definition file. +This is done by mapping compiler preprocessor directives inside a custom `/main/Kconfig.projbuild` +definition file. -By calling `idf.py menuconfig`, a classic ncurses-based configuration menu appears where settings can be selected and customized. +By calling `idf.py menuconfig`, a classic ncurses-based configuration menu appears where settings +can be selected and customized. ### 9.1.2. CMake Integration -To provide a very flexible component customization system, IDF uses an *enhanced* CMake-based build system controlled by the internal `idf.py` command. The firmware link and flash process is also controlled by the `idf.py` script, which makes customized automation possible. +To provide a very flexible component customization system, IDF uses an *enhanced* CMake-based +build system controlled by the internal `idf.py` command. The firmware link and flash process is +also controlled by the `idf.py` script, which makes customized automation possible. ## 9.2. Disadvantages -In contrast to the *arduino-esp32* C++ libraries, IDF only provides libraries written in pure C. Due to the IDF's CMake integration, you are free to choose between the following development approaches: +In contrast to the *arduino-esp32* C++ libraries, IDF only provides libraries written in pure C. +Due to the IDF's CMake integration, you are free to choose between the following development +approaches: 1. Exclusively use the IDF C libraries (providing suboptimal programming interfaces) 2. Link C++ libraries from *arduino-esp32* (often with unnecessary overhead) @@ -186,14 +245,20 @@ In contrast to the *arduino-esp32* C++ libraries, IDF only provides libraries wr 4. Write your own C++ libraries using the IDF C libraries (best choice for keeping firmware images small) > [!NOTE] -> Because our project embeds MicroPython, our HTTPS web server code already contains working C++ classes, and optional web server content must also be packed into firmware: option 4 seems to be the right choice. +> Because our project embeds MicroPython, our HTTPS web server code already contains working +> C++ classes, and optional web server content must also be packed into firmware: option 4 seems +> to be the right choice. # 10. Documentation / Examples -The Espressif *ESP32* (Sphinx-generated) documentation and the examples section under `/examples` provide extensive development information. +The Espressif *ESP32* (Sphinx-generated) documentation and the examples section under `/examples` +provide extensive development information. > [!WARNING] -> Some higher-level networking examples (especially HTTP) are horrible and should be avoided, our web server implementation will use the lwIP Berkeley socket API and provide *clean code* (similar to the ESP-IDF's C++11 threading example, which is written at a high-quality programming level). +> Some higher-level networking examples (especially HTTP) are horrible and should be avoided, +> our web server implementation will use the lwIP Berkeley socket API and provide *clean code* +> (similar to the ESP-IDF's C++11 threading example, which is written at a high-quality programming +> level). Nevertheless, we will provide an excerpt of the most important *ESP32-C3* links for you: diff --git a/mockup/vector-cube/README.md b/mockup/vector-cube/README.md index 9bcc037..4287b0e 100644 --- a/mockup/vector-cube/README.md +++ b/mockup/vector-cube/README.md @@ -2,12 +2,37 @@ The title screen will contain a PONG puck rendered as a vector cube (animation). +## Dependencies + +This mockup uses *SDL2* for rendering and requires the *SDL2* headers and library. + +``` +apt-get install libsdl2-dev +``` + +## Compilation + +Compile and run with: + +``` +./compile.sh +./cube-animation +``` + ## Vertices Format -The cube animations vertices have been pre-calculated using OpenGL, each animation consists of 16 integer values (8 structs containing x and y coordinates). -Initially a third value "visible" (screen z-axis) was intended to hide vertices "behind" surfaces. The calculation of this value in the pre-rendering is broken, so i decided to drop this "feature", the current vector cube rendering despite it looks real good. +The cube animations vertices have been pre-calculated using OpenGL, each animation consists +of 16 integer values (8 structs containing x and y coordinates). Initially a third value "visible" +(screen z-axis) was intended to hide vertices "behind" surfaces. The calculation of this value in +the pre-rendering is broken, so i decided to drop this "feature", the current vector cube rendering +despite it looks very good. ## Line Drawing All vertices will be "connected" by drawing 12 lines in total (4 x-axis, 4 y-axis and 4 z-axis). -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. +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. + +> [!NOTE] +> The ESP32-S3 implementation has been verified and runs smoothly. From fdb3cc3066b79e73bff612c41f581aefe5389776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 11 Aug 2026 16:29:08 +0200 Subject: [PATCH 2/5] Make generic --- DECISIONS.md | 2 +- README.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/DECISIONS.md b/DECISIONS.md index 0fcc159..6e157d0 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -6,7 +6,7 @@ This document should give insights about the **WHY** we did **WHAT** and **WHEN* 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. +web server processing and the *MicroPython* code execution. To produce clean code we should abstract these two layers for both a) single core and b) dual core processing in a generic way. These two possibilities exist: diff --git a/README.md b/README.md index 4a10d26..ee65990 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Embedding MicroPython in a C++ HTTP/1.1 Application Server (ESP32-S3, ESP32-C3) -This project embeds *MicroPython* in *ESP32* microcontrollers using the **Falcon-AS** +This project embeds *MicroPython* in *ESP32* microcontrollers using the **FalconAS** C++ HTTP/1.1 parser library and modified application server code adapted to the microcontroller architecture. @@ -160,11 +160,11 @@ bloated (details follow below). # 8. MicroPython -MicroPython is the choice for the least-experienced C / C++ developer. There is no need +*MicroPython* is the choice for the least-experienced C / C++ developer. There is no need **at all** to write C/C++ code. -But how exactly is MicroPython integrated into the microcontroller? It is *not* **only** -a Python interpreter compiled for microcontrollers. MicroPython is *integrated* into the ESP32 +But how exactly is *MicroPython* integrated into the microcontroller? It is *not* **only** +a Python interpreter compiled for microcontrollers. *MicroPython* is *integrated* into the ESP32 RTOS subsystem, bootloader, and main loop. In practice, this means that when the microcontroller boots, the Python interpreter and *additional* **control code** are loaded into the upper memory regions, initialized, started, and then run continuously. @@ -173,7 +173,7 @@ Depending on the microcontroller used, this enables uploading, running, flashing Python code to bytecode without reflashing the complete firmware. An interpreter console CLI is also accessible over serial to control the interpreter at runtime. -Regarding performance and firmware size optimization, MicroPython allows additional Python +Regarding performance and firmware size optimization, *MicroPython* allows additional Python modules to be integrated as *pre-compiled bytecode* (virtual filesystem partition) or even *frozen bytecode* (directly into the firmware blob). This makes runtime compilation obsolete and improves performance. As a practical example, controlling a common I2C SSD1306 OLED display using @@ -188,9 +188,9 @@ addition, many protocols and libraries are bloated with features that increase c firmware size. > [!NOTE] -> Our project modifies the MicroPython implementation by replacing MicroPython's control logic +> Our project modifies the *MicroPython* implementation by replacing *MicroPython's* control logic > with a **very simplified** C++ HTTP/1.1 TLS-capable web server (with unnecessary HTTP features -> removed). On an HTTP POST request with a JSON payload, it executes a MicroPython script with +> removed). On an HTTP POST request with a JSON payload, it executes a *MicroPython* script with > that payload. # 9. ESP-IDF @@ -245,7 +245,7 @@ approaches: 4. Write your own C++ libraries using the IDF C libraries (best choice for keeping firmware images small) > [!NOTE] -> Because our project embeds MicroPython, our HTTPS web server code already contains working +> Because our project embeds *MicroPython*, our HTTPS web server code already contains working > C++ classes, and optional web server content must also be packed into firmware: option 4 seems > to be the right choice. From 43defec83866e465ae0672ab14188a25e496a50b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 11 Aug 2026 16:29:47 +0200 Subject: [PATCH 3/5] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- mockup/vector-cube/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/mockup/vector-cube/README.md b/mockup/vector-cube/README.md index 4287b0e..b8960f5 100644 --- a/mockup/vector-cube/README.md +++ b/mockup/vector-cube/README.md @@ -21,11 +21,11 @@ Compile and run with: ## Vertices Format -The cube animations vertices have been pre-calculated using OpenGL, each animation consists -of 16 integer values (8 structs containing x and y coordinates). Initially a third value "visible" +The cube animation vertices have been pre-calculated using OpenGL; each animation consists +of 16 integer values (8 structs containing x and y coordinates). Initially, a third value "visible" (screen z-axis) was intended to hide vertices "behind" surfaces. The calculation of this value in -the pre-rendering is broken, so i decided to drop this "feature", the current vector cube rendering -despite it looks very good. +the pre-rendering is broken, so I decided to drop this "feature"; the current vector cube rendering +still looks very good. ## Line Drawing From 7780663379471e5a67535ba378d636fe1262743f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 11 Aug 2026 16:53:55 +0200 Subject: [PATCH 4/5] Add section about cloning MicroPython fork, correct dependencies --- BUILD.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/BUILD.md b/BUILD.md index 0f58183..ef0a7e9 100644 --- a/BUILD.md +++ b/BUILD.md @@ -30,7 +30,7 @@ The list below provides an overview of exactly what these libraries are used for 1. A *patched* *MicroPython* **embed port** (MicroPython sources remain untouched) to execute *MicroPython* functions directly from C++ code (see [section 7](#7-cross-compiling-micropython)) 2. An HTTP/1.1 *parsing* and *message generation* library from the *NLAP/FalconAS* project to parse and generate HTTP/1.1 messages (see [section 8](#8-cross-compiling-http-libraries)) -## 4. ESP IoT Development Framework Features +## 4. ESP-IDF Framework Features A short overview of the framework features before continuing with the installation process. @@ -40,7 +40,7 @@ A short overview of the framework features before continuing with the installati - Automated ELF-to-firmware image conversion / linking - Command-line firmware flashing -## 5. Install ESP-IDF +## 5. ESP-IDF Installation The installation process is one of the easiest I have ever encountered. Programming, compiling, and external component integration are also very straightforward **without** losing any flexibility. @@ -48,15 +48,16 @@ are also very straightforward **without** losing any flexibility. Clone and install *ESP-IDF* as a development user (non-root). ```bash -# clone git repository +# clone repository +cd ~/src git clone https://github.com/espressif/esp-idf.git # install idf as non-root user -cd ./esp-idf +cd ~/src/esp-idf ./install.sh ``` -## 6. Activating the Build Environment +## 6. ESP-IDF Build Environment After installation, the build environment must be activated (sourced) from the current installation path. @@ -86,15 +87,26 @@ Detailed per-variant instructions are available at: - **ESP32-S3**: https://github.com/clauspruefer/micropython/blob/embedding/examples/embedding/esp32/s3/README.md - **ESP32-C3**: https://github.com/clauspruefer/micropython/blob/embedding/examples/embedding/esp32/c3/README.md -### 7.1. ESP32-S3 (Xtensa LX7) +### 7.1. Clone Repository + +It is required to clone the dedicated fork repository using the following commands: + +``` +cd ~/src +git clone https://github.com/clauspruefer/micropython.git +cd ./micropython +git checkout embedding +``` + +### 7.2. ESP32-S3 (Xtensa LX7) ```bash # Activate ESP-IDF environment -cd src/esp-idf +cd ~/src/esp-idf . ./export.sh # Change to the ESP32-S3 embedding example -cd src/micropython/examples/embedding/esp32/s3/ +cd ~/src/micropython/examples/embedding/esp32/s3/ # Generate a CMake-compatible toolchain setup from the current user environment ./adjust-cross-build.sh @@ -115,7 +127,7 @@ After installation the static library and header are placed at: - Library: `/usr/local/lib/esp32s3/libmicropython.a` - Header: `/usr/local/include/esp32s3/micropython_embed.h` -### 7.2. ESP32-C3 (RISC-V) +### 7.3. ESP32-C3 (RISC-V) ```bash # Activate ESP-IDF environment @@ -158,11 +170,11 @@ Detailed instructions for each board type are available under the `ports/arduino ```bash # Activate ESP-IDF environment (if not already active) -cd src/esp-idf +cd ~/src/esp-idf . ./export.sh # Change to the ESP32-S3 Arduino port of http-1.2 -cd src/http-1.2/ports/arduino/esp32s3/ +cd ~/src/http-1.2/ports/arduino/esp32s3/ # Generate a CMake-compatible toolchain setup from the current user environment ./adjust-cross-build.sh From 6898082700c63aa369fb4c75b54b7cce37433738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Claus=20Pr=C3=BCfer?= Date: Tue, 11 Aug 2026 17:10:23 +0200 Subject: [PATCH 5/5] Correct mistakes --- BUILD.md | 2 +- DECISIONS.md | 6 +++--- mockup/vector-cube/README.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/BUILD.md b/BUILD.md index ef0a7e9..59a5c0c 100644 --- a/BUILD.md +++ b/BUILD.md @@ -13,7 +13,7 @@ Make sure you also have a working USB-C or USB-C-to-USB cable and all peripheral ## 3. Requirements -The *ESP-IDF* Development Framework (see [section 5](#5-install-esp-idf)), `Python 3`, `python3-venv`, `pip3`, and `CMake` must +The *ESP-IDF* Development Framework (see [section 5](#5-esp-idf-installation)), `Python 3`, `python3-venv`, `pip3`, and `CMake` must be installed before proceeding. ```bash diff --git a/DECISIONS.md b/DECISIONS.md index 6e157d0..f6fe883 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -5,7 +5,7 @@ This document should give insights about the **WHY** we did **WHAT** and **WHEN* ## Multiprocessing 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 +and thus limited. A *bigger* variant ESP32-S3 integrates 2 CPU cores, it could be a good idea to separate the web server processing and the *MicroPython* code execution. To produce clean code we should abstract these two layers for both a) single core and b) dual core processing @@ -14,7 +14,7 @@ in a generic way. These two possibilities exist: - RTOS tasks - C++11 threading library -Seperating the web server and the python code could be done using 2 RTOS tasks, on dual-core controllers the +Separating 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. > [!NOTE] @@ -29,7 +29,7 @@ The project goal is to provide a in-web-server playable PONG game on two connect The ESP32-C3 acts as a Micropython Application Server, the game logic will be programmed in Python. 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 +web server will also host the application files, on smartphone browser connect the application will be transferred to the browser, started; following communication is abstracted via HTTP/1.1 POST with JSON payload. ## DNS diff --git a/mockup/vector-cube/README.md b/mockup/vector-cube/README.md index b8960f5..b21a512 100644 --- a/mockup/vector-cube/README.md +++ b/mockup/vector-cube/README.md @@ -32,7 +32,7 @@ still looks very good. All vertices will be "connected" by drawing 12 lines in total (4 x-axis, 4 y-axis and 4 z-axis). 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. +directly on the *ESP32* device. > [!NOTE] > The ESP32-S3 implementation has been verified and runs smoothly.