How flintvn/flintespjvm works
Purpose and Entry Points
FlintESPJVM embeds the FlintJVM runtime in ESP-IDF firmware so ESP32-family devices can execute JVM bytecode and be debugged over serial. Firmware startup is espjvm/core/src/main.cpp; board-specific ESP-IDF applications select and build the shared runtime through board projects such as boards/ESP32/CMakeLists.txt and boards/ESP32-S3FH4R2/CMakeLists.txt.
Build and Board Target Layer
Each supported hardware SKU is an independent ESP-IDF project with target-specific SDK defaults, flash partitioning, and component dependencies. This boundary adapts one runtime to differing Xtensa/RISC-V chips, flash sizes, and PSRAM availability.
• boards/Common.cmake
• boards/FlintJVM.cmake
• boards/ESP32-C6FH8/sdkconfig.defaults.esp32c6
• boards/ESP32-S3N16RX/partitions.csv
ESP-IDF v5.5.0+ is the primary build/runtime infrastructure. The espjvm/flintjvm path is a submodule-backed FlintJVM dependency.
Runtime Bootstrap and Platform Abstraction
The core initializes the ESP board, chooses runtime services, and starts FlintJVM. Board abstraction separates common JVM boot logic from processor-family implementations.
• espjvm/core/src/main.cpp
• espjvm/core/inc/esp_board.h
• espjvm/core/src/esp_board_esp32_s3.cpp
Platform implementations are split across original ESP32, C3/C6, S2, and S3 families, allowing differences in memory and device capabilities without changing JVM-facing APIs.
Debug Transport Boundary
FlintJVM debugging is exposed through serial-capable ESP transports. The debugger implementation can use UART, USB CDC, or USB Serial/JTAG depending on board capability; this is the boundary consumed by the FlintJVM Debug VS Code extension.
• espjvm/core/inc/esp_debugger.h
• espjvm/core/src/esp_uart_debugger.cpp
• espjvm/core/src/esp_usb_serial_jtag_debugger.cpp
USB device support is implemented separately in espjvm/core/src/esp_usb_device.c.
JVM Native Hardware API
Native bindings translate JVM-level library calls into ESP-IDF peripheral operations. A central native dispatch layer coordinates implementations for GPIO/ports, ADC/DAC, serial, buses, timing-oriented I/O, touch, and Wi‑Fi.
• espjvm/native/src/esp_native.cpp
• espjvm/native/inc/esp_native_common.h
• espjvm/native/src/esp_native_wifi.cpp
Important hardware service boundaries include I2C, SPI, I2S, UART, OneWire, bitstream, pin/port control, and analog interfaces, represented under espjvm/native/inc/.
System API and Java Library Inputs
A system API component provides ESP-specific JVM/system integration, while prebuilt JARs form the on-device-compatible Java library set used by application builds.
• espjvm/system_api/src/esp_system_api.cpp
• files/lib/java.base.jar
• files/lib/flint.io.jar
• files/lib/flint.net.jar
Application bytecode is expected to be built externally with FlintJDK-compatible libraries; this repository primarily supplies firmware/runtime rather than an application project.
Deployment Interfaces
Firmware is flashed either through normal ESP-IDF workflows or the external browser-based ESP Web Tool (esp.flint.vn). Included Windows utilities provide local ESP flashing support:
• boards/tools/esptool-win64/esptool.exe
• boards/tools/esptool-win64/espsecure.exe
Main entry points: FlintJVM.cmake Board build selection · flintjvm FlintJVM · main.cpp Firmware bootstrap · esp_debugger.h Debugger transport API
Components 20
Board projects
ESP-IDF projects adapt the shared runtime to each hardware SKU.
- ESP-IDF 5.5+ · Builds board firmware and provides ESP platform services.
- Board build selection · Selects target defaults, partitions, and shared FlintJVM runtime components.
boards/FlintJVM.cmake - Target SDK defaults
boards/ESP32-C6FH8/sdkconfig.defaults.esp32c6 - Flash partitions
boards/ESP32-S3N16RX/partitions.csv
ESP firmware runtime
- FlintJVM · Submodule-backed runtime that executes JVM bytecode.
espjvm/flintjvm - Firmware bootstrap · Initializes the board, installs services, and starts the JVM.
espjvm/core/src/main.cpp - Board abstraction API
espjvm/core/inc/esp_board.h - ESP32-S3 board implementation · Representative processor-family implementation behind the board API.
espjvm/core/src/esp_board_esp32_s3.cpp - Debugger transport API
espjvm/core/inc/esp_debugger.h - UART debugger
espjvm/core/src/esp_uart_debugger.cpp - USB Serial/JTAG debugger
espjvm/core/src/esp_usb_serial_jtag_debugger.cpp - USB device support
espjvm/core/src/esp_usb_device.c - ESP system API
espjvm/system_api/src/esp_system_api.cpp
Native hardware API
- Native dispatch · Routes JVM hardware calls to ESP-IDF-backed peripheral implementations.
espjvm/native/src/esp_native.cpp - Native hardware API · Covers GPIO, analog, serial, buses, timing I/O, touch, and Wi-Fi.
espjvm/native/inc/esp_native_common.h - Wi-Fi native binding
espjvm/native/src/esp_native_wifi.cpp
Java and deployment inputs
- Prebuilt Java libraries · FlintJDK-compatible libraries used to build application bytecode.
files/lib/java.base.jar - Application bytecode · Built externally against FlintJDK-compatible libraries.
- FlintJVM Debug extension
- Flashing interfaces · Deploys built firmware to ESP devices.
boards/tools/esptool-win64/esptool.exe
Connections 20
- ESP-IDF 5.5+ → Board build selection: builds
- Target SDK defaults → Board build selection: configures
- Flash partitions → Board build selection: defines flash layout
- Board build selection → Firmware bootstrap: assembles
- Board build selection → FlintJVM: includes
- Firmware bootstrap → Board abstraction API: uses
- Board abstraction API → ESP32-S3 board implementation: implemented by
- Firmware bootstrap → Debugger transport API: selects transport
- Debugger transport API → UART debugger: supports
- Debugger transport API → USB Serial/JTAG debugger: supports
- USB Serial/JTAG debugger → USB device support: uses
- FlintJVM Debug extension → Debugger transport API: serial debugging
- Firmware bootstrap → FlintJVM: starts
- FlintJVM → Native dispatch: invokes native calls
- Native dispatch → Native hardware API: implements
- Native dispatch → Wi-Fi native binding: routes Wi-Fi calls
- FlintJVM → ESP system API: uses system services
- Prebuilt Java libraries → Application bytecode: compile-time APIs
- Application bytecode → FlintJVM: executes on device
- Board build selection → Flashing interfaces: produces firmware for