# flintvn/flintespjvm architecture

> Architecture diagram of the GitHub repository flintvn/flintespjvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flintvn/flintespjvm
- Repository: https://github.com/flintvn/flintespjvm

## Overview

#### 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: [`boards/FlintJVM.cmake`](https://github.com/flintvn/flintespjvm/blob/master/boards/FlintJVM.cmake) (Board build selection), [`espjvm/flintjvm`](https://github.com/flintvn/flintespjvm/tree/master/espjvm/flintjvm) (FlintJVM), [`espjvm/core/src/main.cpp`](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/main.cpp) (Firmware bootstrap), [`espjvm/core/inc/esp_debugger.h`](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/inc/esp_debugger.h) (Debugger transport API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boards["Board projects"]
  node_esp_idf{{"ESP-IDF 5.5+<br/>build/runtime infrastructure"}}
  node_board_build["Board build selection<br/>CMake integration<br/>[FlintJVM.cmake]"]
  node_board_defaults["Target SDK defaults<br/>board configuration"]
  node_partitions["Flash partitions<br/>board layout<br/>[partitions.csv]"]
end

subgraph group_firmware["ESP firmware runtime"]
  node_flintjvm{{"FlintJVM<br/>embedded JVM runtime"}}
  node_firmware_main["Firmware bootstrap<br/>ESP application entry point<br/>[main.cpp]"]
  node_board_api["Board abstraction API<br/>platform interface<br/>[esp_board.h]"]
  node_s3_board_impl["ESP32-S3 board implementation<br/>platform implementation"]
  node_debug_api["Debugger transport API<br/>debug interface<br/>[esp_debugger.h]"]
  node_uart_debug["UART debugger<br/>serial debug transport"]
  node_usb_jtag_debug["USB Serial/JTAG debugger<br/>USB debug transport"]
  node_usb_device["USB device support<br/>USB transport service<br/>[esp_usb_device.c]"]
  node_system_api["ESP system API<br/>JVM system integration<br/>[esp_system_api.cpp]"]
end

subgraph group_native["Native hardware API"]
  node_native_dispatch["Native dispatch<br/>JVM native binding layer<br/>[esp_native.cpp]"]
  node_native_api["Native hardware API<br/>binding interface"]
  node_wifi_native["Wi-Fi native binding<br/>network peripheral binding"]
end

subgraph group_inputs["Java and deployment inputs"]
  node_java_libs["Prebuilt Java libraries<br/>on-device JAR set<br/>[java.base.jar]"]
  node_application_bytecode["Application bytecode<br/>external JVM application"]
  node_debug_extension["FlintJVM Debug extension<br/>external IDE client"]
  node_flash_tools["Flashing interfaces<br/>[esptool.exe]"]
end

node_esp_idf -->|"builds"| node_board_build
node_board_defaults -->|"configures"| node_board_build
node_partitions -->|"defines flash layout"| node_board_build
node_board_build -->|"assembles"| node_firmware_main
node_board_build -->|"includes"| node_flintjvm
node_firmware_main -->|"uses"| node_board_api
node_board_api -->|"implemented by"| node_s3_board_impl
node_firmware_main -->|"selects transport"| node_debug_api
node_debug_api -->|"supports"| node_uart_debug
node_debug_api -->|"supports"| node_usb_jtag_debug
node_usb_jtag_debug -->|"uses"| node_usb_device
node_debug_extension -.->|"serial debugging"| node_debug_api
node_firmware_main -->|"starts"| node_flintjvm
node_flintjvm -->|"invokes native calls"| node_native_dispatch
node_native_dispatch -->|"implements"| node_native_api
node_native_dispatch -->|"routes Wi-Fi calls"| node_wifi_native
node_flintjvm -->|"uses system services"| node_system_api
node_java_libs -.->|"compile-time APIs"| node_application_bytecode
node_application_bytecode -.->|"executes on device"| node_flintjvm
node_board_build -->|"produces firmware for"| node_flash_tools

click node_board_build "https://github.com/flintvn/flintespjvm/blob/master/boards/FlintJVM.cmake"
click node_board_defaults "https://github.com/flintvn/flintespjvm/blob/master/boards/ESP32-C6FH8/sdkconfig.defaults.esp32c6"
click node_partitions "https://github.com/flintvn/flintespjvm/blob/master/boards/ESP32-S3N16RX/partitions.csv"
click node_flintjvm "https://github.com/flintvn/flintespjvm/tree/master/espjvm/flintjvm"
click node_firmware_main "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/main.cpp"
click node_board_api "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/inc/esp_board.h"
click node_s3_board_impl "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_board_esp32_s3.cpp"
click node_debug_api "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/inc/esp_debugger.h"
click node_uart_debug "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_uart_debugger.cpp"
click node_usb_jtag_debug "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_usb_serial_jtag_debugger.cpp"
click node_usb_device "https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_usb_device.c"
click node_native_dispatch "https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/src/esp_native.cpp"
click node_native_api "https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/inc/esp_native_common.h"
click node_wifi_native "https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/src/esp_native_wifi.cpp"
click node_system_api "https://github.com/flintvn/flintespjvm/blob/master/espjvm/system_api/src/esp_system_api.cpp"
click node_java_libs "https://github.com/flintvn/flintespjvm/blob/master/files/lib/java.base.jar"
click node_flash_tools "https://github.com/flintvn/flintespjvm/blob/master/boards/tools/esptool-win64/esptool.exe"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_esp_idf,node_board_build,node_board_defaults,node_partitions toneBlue
class node_flintjvm,node_firmware_main,node_board_api,node_s3_board_impl,node_debug_api,node_uart_debug,node_usb_jtag_debug,node_usb_device,node_system_api toneAmber
class node_native_dispatch,node_native_api,node_wifi_native toneMint
class node_java_libs,node_application_bytecode,node_debug_extension,node_flash_tools toneRose
```

## Components

### Board projects

ESP-IDF projects adapt the shared runtime to each hardware SKU.

- **ESP-IDF 5.5+**: build/runtime infrastructure · Builds board firmware and provides ESP platform services.
- [Board build selection](https://github.com/flintvn/flintespjvm/blob/master/boards/FlintJVM.cmake): CMake integration · Selects target defaults, partitions, and shared FlintJVM runtime components. · `boards/FlintJVM.cmake`
- [Target SDK defaults](https://github.com/flintvn/flintespjvm/blob/master/boards/ESP32-C6FH8/sdkconfig.defaults.esp32c6): board configuration · `boards/ESP32-C6FH8/sdkconfig.defaults.esp32c6`
- [Flash partitions](https://github.com/flintvn/flintespjvm/blob/master/boards/ESP32-S3N16RX/partitions.csv): board layout · `boards/ESP32-S3N16RX/partitions.csv`

### ESP firmware runtime

- [FlintJVM](https://github.com/flintvn/flintespjvm/tree/master/espjvm/flintjvm): embedded JVM runtime · Submodule-backed runtime that executes JVM bytecode. · `espjvm/flintjvm`
- [Firmware bootstrap](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/main.cpp): ESP application entry point · Initializes the board, installs services, and starts the JVM. · `espjvm/core/src/main.cpp`
- [Board abstraction API](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/inc/esp_board.h): platform interface · `espjvm/core/inc/esp_board.h`
- [ESP32-S3 board implementation](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_board_esp32_s3.cpp): platform implementation · Representative processor-family implementation behind the board API. · `espjvm/core/src/esp_board_esp32_s3.cpp`
- [Debugger transport API](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/inc/esp_debugger.h): debug interface · `espjvm/core/inc/esp_debugger.h`
- [UART debugger](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_uart_debugger.cpp): serial debug transport · `espjvm/core/src/esp_uart_debugger.cpp`
- [USB Serial/JTAG debugger](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_usb_serial_jtag_debugger.cpp): USB debug transport · `espjvm/core/src/esp_usb_serial_jtag_debugger.cpp`
- [USB device support](https://github.com/flintvn/flintespjvm/blob/master/espjvm/core/src/esp_usb_device.c): USB transport service · `espjvm/core/src/esp_usb_device.c`
- [ESP system API](https://github.com/flintvn/flintespjvm/blob/master/espjvm/system_api/src/esp_system_api.cpp): JVM system integration · `espjvm/system_api/src/esp_system_api.cpp`

### Native hardware API

- [Native dispatch](https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/src/esp_native.cpp): JVM native binding layer · Routes JVM hardware calls to ESP-IDF-backed peripheral implementations. · `espjvm/native/src/esp_native.cpp`
- [Native hardware API](https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/inc/esp_native_common.h): binding interface · Covers GPIO, analog, serial, buses, timing I/O, touch, and Wi-Fi. · `espjvm/native/inc/esp_native_common.h`
- [Wi-Fi native binding](https://github.com/flintvn/flintespjvm/blob/master/espjvm/native/src/esp_native_wifi.cpp): network peripheral binding · `espjvm/native/src/esp_native_wifi.cpp`

### Java and deployment inputs

- [Prebuilt Java libraries](https://github.com/flintvn/flintespjvm/blob/master/files/lib/java.base.jar): on-device JAR set · FlintJDK-compatible libraries used to build application bytecode. · `files/lib/java.base.jar`
- **Application bytecode**: external JVM application · Built externally against FlintJDK-compatible libraries.
- **FlintJVM Debug extension**: external IDE client
- [Flashing interfaces](https://github.com/flintvn/flintespjvm/blob/master/boards/tools/esptool-win64/esptool.exe): ESP-IDF, Web Tool, Windows utilities · Deploys built firmware to ESP devices. · `boards/tools/esptool-win64/esptool.exe`

## Connections

- 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
