# highcodeh/tentacleos architecture

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

- Interactive diagram: https://gitdiagram.com/highcodeh/tentacleos
- Repository: https://github.com/highcodeh/tentacleos

## Overview

TentacleOS is modular dual-target firmware for ESP32-P4 and ESP32-C5. On P4, startup tracks boot loops, initializes the kernel, and confirms pending OTA only after successful initialization; the repository also contains UI, app-runtime and scripting services, storage, radio/mesh applications, and C5 Wi-Fi/Bluetooth/ESP-NOW features. The README describes the component layers, while sampled source confirms only selected startup, storage, scripting, and UI behavior. Other feature branches are represented from the tree without inferred call flows.

Main entry points: [`firmware_p4/main/main.c`](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/main/main.c) (P4 startup), [`firmware_p4/components/Service/storage_api/storage_impl.c`](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/storage_api/storage_impl.c) (Storage API), [`tools/hle/src/main.cpp`](https://github.com/highcodeh/tentacleos/blob/main/tools/hle/src/main.cpp) (HLE simulator), [`firmware_p4/components/Service/script_engine/script_engine.c`](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/script_engine/script_engine.c) (Script engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and UI"]
  node_p4main["P4 startup<br/>[main.c]"]
  node_kernel["Kernel manager<br/>[kernel.c]"]
  node_ui["Device UI"]
end

subgraph group_services["Platform services"]
  node_ota["OTA service<br/>[ota_service.c]"]
  node_app_runtime["App runtime ABI<br/>[tos_api.h]"]
  node_script["Script engine<br/>[script_engine.c]"]
  node_storage_api["Storage API<br/>[storage_impl.c]"]
  node_storage_vfs[("Storage VFS")]
  node_assets[("Asset storage<br/>[storage_assets.c]")]
  node_spi_bridge["C5 SPI bridge"]
end

subgraph group_apps["P4 applications"]
  node_subghz["Sub-GHz tools"]
  node_rfid["RFID storage<br/>[rfid_storage.c]"]
  node_meshcore["MeshCore"]
  node_meshtastic["Meshtastic"]
end

subgraph group_c5["C5 applications"]
  node_wifi_apps["Wi-Fi tools"]
  node_bt_apps["Bluetooth tools"]
  node_espnow_chat["ESP-NOW chat<br/>[espnow_chat.c]"]
end

subgraph group_simulator["Host simulator"]
  node_hle["HLE simulator<br/>[main.cpp]"]
end

node_user(("Device user"))
node_host(("Linux developer"))

node_user -.->|"boots device"| node_p4main
node_p4main -->|"initializes"| node_kernel
node_p4main -->|"checks update"| node_ota
node_storage_api -->|"calls VFS"| node_storage_vfs
node_script -->|"dispatches ABI"| node_app_runtime
node_subghz -->|"uses storage"| node_storage_api
node_host -->|"runs simulator"| node_hle
node_hle -.->|"emulates firmware flow"| node_p4main

click node_p4main "https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/main/main.c"
click node_kernel "https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Core/kernel.c"
click node_ota "https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Service/ota/ota_service.c"
click node_ui "https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/ui"
click node_app_runtime "https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/app_runtime/include/tos_api.h"
click node_script "https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/script_engine/script_engine.c"
click node_storage_api "https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/storage_api/storage_impl.c"
click node_storage_vfs "https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Service/storage_vfs"
click node_assets "https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Service/storage_assets/storage_assets.c"
click node_subghz "https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/SubGhz"
click node_rfid "https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Applications/rfid/rfid_storage.c"
click node_meshcore "https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/LoRa/meshcore"
click node_meshtastic "https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/LoRa/meshtastic"
click node_wifi_apps "https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Applications/wifi"
click node_bt_apps "https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Applications/bluetooth"
click node_espnow_chat "https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Applications/espnow_chat/espnow_chat.c"
click node_spi_bridge "https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Service/spi_bridge"
click node_hle "https://github.com/highcodeh/tentacleos/blob/main/tools/hle/src/main.cpp"

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_p4main,node_kernel,node_ui,node_user toneBlue
class node_ota,node_app_runtime,node_script,node_storage_api,node_storage_vfs,node_assets,node_spi_bridge toneAmber
class node_subghz,node_rfid,node_meshcore,node_meshtastic toneMint
class node_wifi_apps,node_bt_apps,node_espnow_chat toneRose
class node_hle,node_host toneIndigo
```

## Components

### Startup and UI

- [P4 startup](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/main/main.c): `firmware_p4/main/main.c`
- [Kernel manager](https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Core/kernel.c): `firmware_c5/components/Core/kernel.c`
- [Device UI](https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/ui): `firmware_p4/components/Applications/ui`

### Platform services

- [OTA service](https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Service/ota/ota_service.c): `firmware_c5/components/Service/ota/ota_service.c`
- [App runtime ABI](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/app_runtime/include/tos_api.h): `firmware_p4/components/Service/app_runtime/include/tos_api.h`
- [Script engine](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/script_engine/script_engine.c): `firmware_p4/components/Service/script_engine/script_engine.c`
- [Storage API](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Service/storage_api/storage_impl.c): `firmware_p4/components/Service/storage_api/storage_impl.c`
- [Storage VFS](https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Service/storage_vfs): `firmware_c5/components/Service/storage_vfs`
- [Asset storage](https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Service/storage_assets/storage_assets.c): `firmware_c5/components/Service/storage_assets/storage_assets.c`
- [C5 SPI bridge](https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Service/spi_bridge): `firmware_c5/components/Service/spi_bridge`

### P4 applications

- [Sub-GHz tools](https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/SubGhz): `firmware_p4/components/Applications/SubGhz`
- [RFID storage](https://github.com/highcodeh/tentacleos/blob/main/firmware_p4/components/Applications/rfid/rfid_storage.c): `firmware_p4/components/Applications/rfid/rfid_storage.c`
- [MeshCore](https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/LoRa/meshcore): `firmware_p4/components/Applications/LoRa/meshcore`
- [Meshtastic](https://github.com/highcodeh/tentacleos/tree/main/firmware_p4/components/Applications/LoRa/meshtastic): `firmware_p4/components/Applications/LoRa/meshtastic`

### C5 applications

- [Wi-Fi tools](https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Applications/wifi): `firmware_c5/components/Applications/wifi`
- [Bluetooth tools](https://github.com/highcodeh/tentacleos/tree/main/firmware_c5/components/Applications/bluetooth): `firmware_c5/components/Applications/bluetooth`
- [ESP-NOW chat](https://github.com/highcodeh/tentacleos/blob/main/firmware_c5/components/Applications/espnow_chat/espnow_chat.c): `firmware_c5/components/Applications/espnow_chat/espnow_chat.c`

### Host simulator

- [HLE simulator](https://github.com/highcodeh/tentacleos/blob/main/tools/hle/src/main.cpp): `tools/hle/src/main.cpp`

### Other components

- **Device user**
- **Linux developer**

## Connections

- Device user → P4 startup: boots device
- P4 startup → Kernel manager: initializes (evidence: `firmware_p4/main/main.c`)
- P4 startup → OTA service: checks update (evidence: `firmware_p4/main/main.c`)
- Storage API → Storage VFS: calls VFS (evidence: `firmware_p4/components/Service/storage_api/storage_impl.c`)
- Script engine → App runtime ABI: dispatches ABI (evidence: `firmware_p4/components/Service/script_engine/script_engine.c`)
- Sub-GHz tools → Storage API: uses storage (evidence: `firmware_p4/components/Applications/SubGhz/subghz_storage.c`)
- Linux developer → HLE simulator: runs simulator (evidence: `README.md`)
- HLE simulator → P4 startup: emulates firmware flow (evidence: `README.md`)