From cd5be6cebeb1dbe9aa89864f64031664e67ca779 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 18:01:19 +0200 Subject: [PATCH 01/21] Update docs --- .claude/rules.zip | Bin 0 -> 10629 bytes .claude/rules/CLAUDE.md | 65 ++ .claude/rules/app-framework.md | 18 + .claude/rules/architecture-device-model.md | 10 + .claude/rules/architecture-layers.md | 7 + .claude/rules/build-system.md | 5 + .claude/rules/building.md | 62 ++ .claude/rules/coding-style.md | 35 + .claude/rules/hardware-abstraction-layer.md | 31 + .claude/rules/key-conventions.md | 7 + .claude/rules/lvgl.md | 8 + .claude/rules/platform-abstraction.md | 4 + .claude/rules/project-overview.md | 3 + .claude/rules/service-framework.md | 3 + CLAUDE.md | 1 - Documentation/README.md | 164 ----- Documentation/ideas.md | 4 +- Documentation/license-tactility.md | 636 ------------------ Documentation/license-tactilitykernel.md | 157 ----- THIRD-PARTY-NOTICES.md | 23 +- .../Source/app/chat/README.md | 0 .../Source/service/displayidle/README.md | 0 .../Source/service/webserver/README.md | 0 23 files changed, 266 insertions(+), 977 deletions(-) create mode 100644 .claude/rules.zip create mode 100644 .claude/rules/CLAUDE.md create mode 100644 .claude/rules/app-framework.md create mode 100644 .claude/rules/architecture-device-model.md create mode 100644 .claude/rules/architecture-layers.md create mode 100644 .claude/rules/build-system.md create mode 100644 .claude/rules/building.md create mode 100644 .claude/rules/coding-style.md create mode 100644 .claude/rules/hardware-abstraction-layer.md create mode 100644 .claude/rules/key-conventions.md create mode 100644 .claude/rules/lvgl.md create mode 100644 .claude/rules/platform-abstraction.md create mode 100644 .claude/rules/project-overview.md create mode 100644 .claude/rules/service-framework.md delete mode 120000 CLAUDE.md delete mode 100644 Documentation/README.md delete mode 100644 Documentation/license-tactility.md delete mode 100644 Documentation/license-tactilitykernel.md rename Documentation/chat.md => Tactility/Source/app/chat/README.md (100%) rename Documentation/screensavers.md => Tactility/Source/service/displayidle/README.md (100%) rename Documentation/webserver.md => Tactility/Source/service/webserver/README.md (100%) diff --git a/.claude/rules.zip b/.claude/rules.zip new file mode 100644 index 0000000000000000000000000000000000000000..4690a988a0dba3ab3850d6129541a1d550b63788 GIT binary patch literal 10629 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, not a C++ class. Each app has an `AppManifest` (`id`, `name`, `category`, `location`, `flags`) and a `main(app_instance_id, argc, argv)` entry point (`AppMainFn`), modelled on a C program's `main()`. Every app instance gets its own dedicated task for its whole lifetime, and blocks in that task until it returns. + +Lifecycle and inter-app communication go through `app_manager_*()` (`app/manager.h`) and `app_event_*()` (`app/event.h`): +- `app_manager_start()`/`app_manager_start_with_parameters()` launch a plain instance; `app_manager_start_for_result()` launches a modal child that reports back to a parent instance. +- An app subscribes with `app_event_subscribe()`/`app_event_await()` and reacts to `APP_EVENT_CLOSE` (terminate now) and `APP_EVENT_RESULT` (a child it started reported back). +- An app closes itself by calling `app_manager_finish()` right before returning from `main()`; another instance is closed via `app_manager_stop()`. + +Apps are registered at startup via `app_manager_add()`. External apps can be loaded from SD card via `manifest.properties` files, or side-loaded as ELF binaries on ESP32 (see `app/loader.h`'s `AppLoaderApi`). + +Apps can be loaded from: + +- memory (`APP_LOCATION_MEMORY`) +- a path pointing to an install folder where an `.app` file was installed (`APP_LOCATION_PATH`) +- a path pointing to an `.elf` file (`APP_LOCATION_PATH`) + +An app can build an optional UI via the LVGL window-manager module (see `lvgl.md`). diff --git a/.claude/rules/architecture-device-model.md b/.claude/rules/architecture-device-model.md new file mode 100644 index 000000000..024b391ec --- /dev/null +++ b/.claude/rules/architecture-device-model.md @@ -0,0 +1,10 @@ +# Architecture: Device/Driver/Module System (kernel layer, C API) + +The kernel uses a Linux-inspired device model: + +- **Module** (`struct Module`): loadable unit that registers drivers, hardware and symbols. Lifecycle: `module_construct` → `module_add` → `module_start`. Each device board and platform is a module. +- **Driver** (`struct Driver`): binds to devices via `compatible` strings (like devicetree). Has `start_device`/`stop_device` callbacks and an `api` pointer for type-specific operations. +- **Device** (`struct Device`): represents hardware. Lifecycle: `device_construct` → `device_add` → `device_start`. Has a parent-child tree, driver binding, and locking. +- **DeviceType** (`struct DeviceType`): enables discovering devices by category (e.g. `DISPLAY_TYPE`, `TOUCH_TYPE`, `UART_CONTROLLER_TYPE`). + +Devices are defined via **devicetree** `.dts` files in each `Devices//` folder. A custom devicetree compiler (`Buildscripts/DevicetreeCompiler/compile.py`) generates C code from these files. Each device folder also has a `devicetree.yaml` specifying dependencies and the `.dts` file. diff --git a/.claude/rules/architecture-layers.md b/.claude/rules/architecture-layers.md new file mode 100644 index 000000000..ad151971f --- /dev/null +++ b/.claude/rules/architecture-layers.md @@ -0,0 +1,7 @@ +# Architecture: Layer Stack (bottom to top) + +- **TactilityKernel** — C API kernel: device/driver/module lifecycle, concurrency primitives (thread, mutex, timer, dispatcher), filesystem, logging. Header convention: `` (lowercase snake_case). +- **TactilityFreeRtos** — Thin C++ wrappers around FreeRTOS primitives. +- **Tactility** — Main OS layer: app framework, service framework, LVGL integration, networking and services (Wi-Fi, BLE, NTP, ESP-NOW), settings, i18n. +- **TactilityC** — C bindings (`tt_*.h`) for Tactility, used by side-loaded ELF apps on ESP32. Deprecated, replaced by TactilityKernel. +- **Firmware** — Entry point (`app_main`). diff --git a/.claude/rules/build-system.md b/.claude/rules/build-system.md new file mode 100644 index 000000000..8630c51c2 --- /dev/null +++ b/.claude/rules/build-system.md @@ -0,0 +1,5 @@ +# Architecture: Build System + +The `tactility_add_module()` CMake macro (in `Buildscripts/module.cmake`) wraps ESP-IDF's `idf_component_register` on ESP32 and standard `add_library` on POSIX, allowing the same source to build for both targets. + +`device.py` reads `Devices//device.properties` and generates the `sdkconfig` file with all necessary ESP-IDF config (target chip, flash size, SPIRAM, LVGL fonts, Bluetooth, USB, etc.). diff --git a/.claude/rules/building.md b/.claude/rules/building.md new file mode 100644 index 000000000..11bdbf3f5 --- /dev/null +++ b/.claude/rules/building.md @@ -0,0 +1,62 @@ +# Building + +## Git + +The repository uses git submodules. Make sure to use `--recurse-submodules` on relevant git commands. + +## Simulator (Linux/macOS, no ESP-IDF needed) + +> [!IMPORTANT] +> The simulator does **NOT** build or run on native Windows (Win32/PowerShell/cmd). This is +> a hard platform limitation, not a missing tool or PATH issue — do not attempt `cmake -B +> buildsim` on Windows, it will not work. WSL is a separate, Linux environment and is fine. + +```bash +cmake -B buildsim -G Ninja +ninja -C buildsim # build firmware + tests +./buildsim/Firmware/Tactility # run simulator +``` + +## ESP32 firmware + +```bash +python device.py # generate sdkconfig for device (e.g. lilygo-tdeck) +python device.py --dev # dev mode: force 4MB partition table +idf.py build # build firmware +idf.py flash monitor # flash and monitor +``` + +Device IDs are the folder names under `Devices/` (e.g. `lilygo-tdeck`, `m5stack-cores3`, `cyd-2432s028r`). + +### Windows: activating the ESP-IDF environment + +On native Windows, `idf.py` is not on PATH by default — it must be activated per-shell first. +The install script places a PowerShell profile activator per IDF version at +`%IDF_TOOL_PATH%\Microsoft.v.PowerShell_profile.ps1` (path controlled by the +`IDF_TOOL_PATH` environment variable, set to wherever ESP-IDF's tools were installed, e.g. +`C:\Espressif\tools`). Source it before running any `idf.py` command: + +```powershell +. "$env:IDF_TOOL_PATH\Microsoft.v5.5.2.PowerShell_profile.ps1" # match the installed IDF version +Set-Location "" +idf.py build 2>&1 | Select-Object -Last 250 +``` + +This is Windows-specific setup (the main dev works on Linux, where `idf.py` is normally +already on PATH via `export.sh`/`. ./export.sh` or a shell profile). + +## Devicetree + +A device implementation has a `.dts` file. +The parser at `Buildscripts/DevicetreeCompiler/` converts DTS into C code. +It's called from the `Firmware/` build process. + +## Tests + +Tests use Doctest and run on simulator (POSIX) target only: + +```bash +cmake -B buildsim -G Ninja +ninja -C buildsim build-tests +cd buildsim && ctest --test-dir Tests +``` diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md new file mode 100644 index 000000000..ca3af292a --- /dev/null +++ b/.claude/rules/coding-style.md @@ -0,0 +1,35 @@ +# Coding Style + +Two conventions coexist; which one to use depends on the project layer: + +- **C code** (TactilityKernel, drivers): `lower_snake_case` for files, functions, variables. `UpperCamelCase` for types. Files in `source/`, `include/`, `private/` directories. +- **C++ code** (Tactility, apps, services): `UpperCamelCase` for files and types. `lowerCamelCase` for functions. Files in `Source/`, `Include/`, `Private/` directories. + +For projects that emit C headers and have a C++ implementation file: the internal C++ function naming should be snake_case. + +Formatting is enforced by `.clang-format` (LLVM-based, 4-space indent, no column limit). +Never throw exceptions — use return types for error handling. Use `enum class` over plain `enum` when writing C++ code. +Don't do null checks for function parameters: the caller is responsible for passing valid data. +Pointers are expected to be non-null unless documented otherwise. + +Code Comments: + +- Should be as short as possible, leaving only important context. +- Should avoid explaining what the code does, unless the code complexity is high enough to warrant an explanation. +- Must avoid explaining how the code was before, or how it was changed. +- Should explain why code is implemented. +- Should be as brief as possible without losing critical information. +- Should avoid explaining what was not implemented. +- Should avoid referring to designs of other subsystems. +- Must avoid interjections: avoid hyphens or braces to interject. If interjections provide crucial info, use Doxygen entity/anchor references like: +/** + * A dedicated completion \signal for one app instance's task. + * Whichever \side finishes with it last is the one that deletes `semaphore` and frees this struct. + * + * \signal Not the task's shared default FreeRTOS notification, which app_event.cpp's AppEventSubscription also uses. + * An unrelated event delivered to the same task could otherwise unblock a waiter early. + * \side The exiting task or a concurrent app_scheduler_stop() that found the entry in time and is waiting on `semaphore`. + */ +``` + + diff --git a/.claude/rules/hardware-abstraction-layer.md b/.claude/rules/hardware-abstraction-layer.md new file mode 100644 index 000000000..6c50f1686 --- /dev/null +++ b/.claude/rules/hardware-abstraction-layer.md @@ -0,0 +1,31 @@ +# Architecture: Hardware Abstraction Layer + +## Driver + +A driver generally consists of: +- Registration of driver in parent module (optional, but desirable) +- YAML bindings in the `bindings/` folder +- An `#include` that is used in the `.dts` file. The include is in `[projectname]/bindings/[drivername].h` +- The driver implementation: a `.cpp` and `.h` file. The implementation is C++, but the header exposes pure C functions. C implementations are allowed, but C++ is preferred. + +Drivers are part of a kernel module. + +Modules with drivers can be stored in: +- TactilityKernel +- A subproject in `Platforms` folder +- A subproject in `Devices` folder +- A subproject in `Drivers` folder + +## Kernel Modules + +Kernel module names are lower case and postfixed with `-module`. + +Projects that are kernel modules: + +1. Declare a `struct Module` +2. Contain a `devicetree.yaml` file that declares a list of dependencies (for parsing the devicetree) and specifies the bindings folder that contains the drivers' YAML definitions. For example: +```yaml +dependencies: + - TactilityKernel +bindings: bindings +``` diff --git a/.claude/rules/key-conventions.md b/.claude/rules/key-conventions.md new file mode 100644 index 000000000..777cef80f --- /dev/null +++ b/.claude/rules/key-conventions.md @@ -0,0 +1,7 @@ +# Key Conventions + +- `#ifdef ESP_PLATFORM` guards ESP32-specific code; the simulator uses POSIX equivalents. +- The `Drivers/` directory contains hardware drivers (display controllers, touch controllers, PMICs, etc.) — each is its own CMake component. +- `Modules/` contains cross-cutting modules. e.g.`lvgl-module` (LVGL task management). +- `Data/system/` and `Data/data/` are flashed as FAT filesystem images on ESP32. +- Translations are in `Translations/` as CSV files, generated via `generate.py`. diff --git a/.claude/rules/lvgl.md b/.claude/rules/lvgl.md new file mode 100644 index 000000000..c6c73ed9a --- /dev/null +++ b/.claude/rules/lvgl.md @@ -0,0 +1,8 @@ +# Architecture: LVGL + +User interfaces should scale well for everything between very large (e.g. 1280x720) and small (e.g. 135x240) displays. Vertical and horizontal layouts are supported. + +Two kernel modules cover LVGL: + +- **`lvgl-module`** (`Modules/lvgl-module/`, ``) owns LVGL's lifecycle: init/deinit, the LVGL task loop, and `lvgl_lock()`/`lvgl_try_lock()`/`lvgl_unlock()` mutex-based locking that any task must hold before touching LVGL objects. It bridges Tactility's device model to LVGL indevs (`lvgl/devices/*.h`: `display`, `pointer`, `keyboard`, `trackball`), and provides shared fonts (`lvgl/fonts.h`: Montserrat text sizes, Material Symbols icon sets for statusbar/launcher/shared use) and a few shared widgets (`lvgl/widgets/*.h`: `toolbar`, `spinner`, `sliderbox`). +- **`lvgl-window-manager-module`** (`Modules/lvgl-window-manager-module/`, ``) manages a single stacked window per app instance on top of `lvgl-module`. `window_manager_start()`/`window_manager_stop()` create/tear down the root widget (plus optional chrome from a configured `WindowManagerScreenInitFn`); `window_manager_create()`/`window_manager_remove()` push/pop an app's window and (re)populate it via a `WindowCreateWidgetsFn`. Only the topmost window ever has live widgets - burying and resurfacing a window deletes and rebuilds its widget tree rather than hiding/showing it. That rebuild-on-remove path can run `create_widgets` on a *different* app's thread (whichever app's `window_manager_remove()` call caused this window to resurface), so `create_widgets` must only rebuild already-committed state, never decide what happens next - state transitions belong in the app's own `main()` event loop, driven by real `APP_EVENT_RESULT`s. diff --git a/.claude/rules/platform-abstraction.md b/.claude/rules/platform-abstraction.md new file mode 100644 index 000000000..09a016939 --- /dev/null +++ b/.claude/rules/platform-abstraction.md @@ -0,0 +1,4 @@ +# Architecture: Platform Abstraction + +- `Platforms/platform-esp32/` — ESP-IDF specific implementations +- `Platforms/platform-posix/` — POSIX simulator implementations (SDL for display) diff --git a/.claude/rules/project-overview.md b/.claude/rules/project-overview.md new file mode 100644 index 000000000..c3d0cfe3d --- /dev/null +++ b/.claude/rules/project-overview.md @@ -0,0 +1,3 @@ +# Project Overview + +Tactility is an operating system for the ESP32 microcontroller family. It runs on 40+ supported devices (CYD boards, LilyGO, M5Stack, Elecrow, etc.) and includes a desktop simulator. Built with C++23, ESP-IDF, LVGL, and FreeRTOS. diff --git a/.claude/rules/service-framework.md b/.claude/rules/service-framework.md new file mode 100644 index 000000000..2cf756a1e --- /dev/null +++ b/.claude/rules/service-framework.md @@ -0,0 +1,3 @@ +# Architecture: Service Framework + +Services are a C API (`service-module`, ``), not a C++ class. Each service has a `ServiceManifest` (`id`, `create_service`/`destroy_service` for its custom data, `on_start`/`on_stop` callbacks) registered via `service_manager_add()`, and is started/stopped via `service_manager_start()`/`service_manager_stop()`. Services are long-running background processes (GUI, Wi-Fi, loader, statusbar, GPS, etc.). diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 06e71defe..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Documentation/README.md \ No newline at end of file diff --git a/Documentation/README.md b/Documentation/README.md deleted file mode 100644 index 628acd143..000000000 --- a/Documentation/README.md +++ /dev/null @@ -1,164 +0,0 @@ -# README - -## Project Overview - -Tactility is an operating system for the ESP32 microcontroller family. It runs on 40+ supported devices (CYD boards, LilyGO, M5Stack, Elecrow, etc.) and includes a desktop simulator. Built with C++23, ESP-IDF, LVGL, and FreeRTOS. - -## Building - -### Git - -The repository uses git submodules. Make sure to use `--recurse-submodules` on relevant git commands. - -### Simulator (Linux/macOS, no ESP-IDF needed) - -> [!IMPORTANT] -> The simulator does **NOT** build or run on native Windows (Win32/PowerShell/cmd). This is -> a hard platform limitation, not a missing tool or PATH issue — do not attempt `cmake -B -> buildsim` on Windows, it will not work. WSL is a separate, Linux environment and is fine. - -```bash -cmake -B buildsim -G Ninja -ninja -C buildsim # build firmware + tests -./buildsim/Firmware/Tactility # run simulator -``` - -### ESP32 firmware - -```bash -python device.py # generate sdkconfig for device (e.g. lilygo-tdeck) -python device.py --dev # dev mode: force 4MB partition table -idf.py build # build firmware -idf.py flash monitor # flash and monitor -``` - -Device IDs are the folder names under `Devices/` (e.g. `lilygo-tdeck`, `m5stack-cores3`, `cyd-2432s028r`). - -#### Windows: activating the ESP-IDF environment - -On native Windows, `idf.py` is not on PATH by default — it must be activated per-shell first. -The install script places a PowerShell profile activator per IDF version at -`%IDF_TOOL_PATH%\Microsoft.v.PowerShell_profile.ps1` (path controlled by the -`IDF_TOOL_PATH` environment variable, set to wherever ESP-IDF's tools were installed, e.g. -`C:\Espressif\tools`). Source it before running any `idf.py` command: - -```powershell -. "$env:IDF_TOOL_PATH\Microsoft.v5.5.2.PowerShell_profile.ps1" # match the installed IDF version -Set-Location "" -idf.py build 2>&1 | Select-Object -Last 250 -``` - -This is Windows-specific setup (the main dev works on Linux, where `idf.py` is normally -already on PATH via `export.sh`/`. ./export.sh` or a shell profile). - -### Devicetree - -A device implementation has a `.dts` file. -The parser at `Buildscripts/DevicetreeCompiler/` converts DTS into C code. -It's called from the `Firmware/` build process. - -### Tests - -Tests use Doctest and run on simulator (POSIX) target only: - -```bash -cmake -B buildsim -G Ninja -ninja -C buildsim build-tests -cd buildsim && ctest --test-dir Tests -``` - -## Architecture - -### Layer Stack (bottom to top) - -- **TactilityKernel** — C API kernel: device/driver/module lifecycle, concurrency primitives (thread, mutex, timer, dispatcher), filesystem, logging. Header convention: `` (lowercase snake_case). -- **TactilityFreeRtos** — Thin C++ wrappers around FreeRTOS primitives. -- **Tactility** — Main OS layer: app framework, service framework, LVGL integration, networking and services (Wi-Fi, BLE, NTP, ESP-NOW), settings, i18n. -- **TactilityC** — C bindings (`tt_*.h`) for Tactility, used by side-loaded ELF apps on ESP32. Deprecated, replaced by TactilityKernel. -- **Firmware** — Entry point (`app_main`). - -### Device/Driver/Module System (kernel layer, C API) - -The kernel uses a Linux-inspired device model: - -- **Module** (`struct Module`): loadable unit that registers drivers and hardware. Lifecycle: `module_construct` → `module_add` → `module_start`. Each device board and platform is a module. -- **Driver** (`struct Driver`): binds to devices via `compatible` strings (like devicetree). Has `start_device`/`stop_device` callbacks and an `api` pointer for type-specific operations. -- **Device** (`struct Device`): represents hardware. Lifecycle: `device_construct` → `device_add` → `device_start`. Has a parent-child tree, driver binding, and locking. -- **DeviceType** (`struct DeviceType`): enables discovering devices by category (e.g. `DISPLAY_TYPE`, `TOUCH_TYPE`, `UART_CONTROLLER_TYPE`). - -Devices are defined via **devicetree** `.dts` files in each `Devices//` folder. A custom devicetree compiler (`Buildscripts/DevicetreeCompiler/compile.py`) generates C code from these files. Each device folder also has a `devicetree.yaml` specifying dependencies and the `.dts` file. - -### App Framework - -Apps implement `tt::app::App` (or just provide callbacks). Each app has an `AppManifest` with `appId`, `appName`, `appCategory`, and a factory function `createApp`. Apps are registered at startup in `Tactility.cpp`. External apps can be loaded from SD card via `manifest.properties` files, or side-loaded as ELF binaries on ESP32. - -### Service Framework - -Services implement `tt::service::Service` with a `ServiceManifest`. Services are long-running background processes (GUI, Wi-Fi, loader, statusbar, GPS, etc.). - -### Hardware Abstraction Layer - -#### Driver - -A driver generally consists of: -- Registration of driver in parent module (optional, but desirable) -- YAML bindings in the `bindings/` folder -- An `#include` that is used in the `.dts` file. The include is in `[projectname]/bindings/[drivername].h` -- The driver implementation: a `.cpp` and `.h` file. The implementation is C++, but the header exposes pure C functions. C implementations are allowed, but C++ is preferred. - -Drivers are part of a kernel module. - -Modules with drivers can be stored in: -- TactilityKernel -- A subproject in `Platforms` folder -- A subproject in `Devices` folder -- A subproject in `Drivers` folder - -#### Kernel Modules - -Kernel module names are lower case and postfixed with `-module`. - -Projects that are kernel modules: - -1. Declare a `struct Module` -2. Contain a `devicetree.yaml` file that declares a list of dependencies (for parsing the devicetree) and specifies the bindings folder that contains the drivers' YAML definitions. For example: -```yaml -dependencies: - - TactilityKernel -bindings: bindings -``` - -### Platform Abstraction - -- `Platforms/platform-esp32/` — ESP-IDF specific implementations -- `Platforms/platform-posix/` — POSIX simulator implementations (SDL for display) - -### Build System - -The `tactility_add_module()` CMake macro (in `Buildscripts/module.cmake`) wraps ESP-IDF's `idf_component_register` on ESP32 and standard `add_library` on POSIX, allowing the same source to build for both targets. - -`device.py` reads `Devices//device.properties` and generates the `sdkconfig` file with all necessary ESP-IDF config (target chip, flash size, SPIRAM, LVGL fonts, Bluetooth, USB, etc.). - -### LVGL - -User interfaces should scale well for everything between very large (e.g. 1280x720) and small (e.g. 135x240) displays. Vertical and horizontal layouts are supported. - -## Coding Style - -Two conventions coexist; which one to use depends on the project layer: - -- **C code** (TactilityKernel, drivers): `lower_snake_case` for files, functions, variables. `UpperCamelCase` for types. Files in `source/`, `include/`, `private/` directories. -- **C++ code** (Tactility, apps, services): `UpperCamelCase` for files and types. `lowerCamelCase` for functions. Files in `Source/`, `Include/`, `Private/` directories. - -Formatting is enforced by `.clang-format` (LLVM-based, 4-space indent, no column limit). -Never throw exceptions — use return types for error handling. Use `enum class` over plain `enum`. -Don't do null checks: caller is responsible for passing valid data. -Pointers are expected to be non-null unless documented otherwise. - -## Key Conventions - -- `#ifdef ESP_PLATFORM` guards ESP32-specific code; the simulator uses POSIX equivalents. -- The `Drivers/` directory contains hardware drivers (display controllers, touch controllers, PMICs, etc.) — each is its own CMake component. -- `Modules/` contains cross-cutting modules. e.g.`lvgl-module` (LVGL task management). -- `Data/system/` and `Data/data/` are flashed as FAT filesystem images on ESP32. -- Translations are in `Translations/` as CSV files, generated via `generate.py`. \ No newline at end of file diff --git a/Documentation/ideas.md b/Documentation/ideas.md index dc64f4e75..fc3ebddc8 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -2,7 +2,6 @@ ## Before release -- Remove incubating flag from various devices - Add `// SPDX-License-Identifier: GPL-3.0-only` and `// SPDX-License-Identifier: Apache-2.0` to individual files in the project - Elecrow Basic & Advance 3.5" memory issue: not enough memory for App Hub - App Hub crashes if you close it while an app is being installed @@ -12,7 +11,7 @@ ## Higher Priority -- Devices with a keyboard attached should always highlight the first widget (~Cardputer navigation issue), same for LV_INDEV_TYPE_ENCODER being present +- lvgl-window-manager: When a keyboard or LV_INDEV_TYPE_ENCODER is attached, always highlight the first widget (~Cardputer navigation issue) in a window when a window is created. - Make it more clear to end-users that an SD card is required to run Tactility - Move "# Fix error "PSRAM space not enough for the Flash instructions" on boot:" fix from T-Deck and others to device.py - Make it possible to override stack size for an app via config file (loaded at boot), and make it possible to set preferred memory location (e.g. internal/external) @@ -54,6 +53,7 @@ ## Medium Priority +- `struct Driver` has an `.owner`, but it's not always set. Either validate on Module construct that it matches, or otherwise set it during module start. The problem: NULL parent currently means that driver is not removable. This clashes with setting it dynamically. Consider some kind of flag to determine removability. - Consider moving certain drivers into separate modules: audio, bt, wifi, etc - Consider using https://github.com/Graphify-Labs/graphify - Consider implementing LVGL gridnav in apps https://lvgl.io/docs/open/9.3/details/auxiliary-modules/gridnav.html diff --git a/Documentation/license-tactility.md b/Documentation/license-tactility.md deleted file mode 100644 index 85c7c6967..000000000 --- a/Documentation/license-tactility.md +++ /dev/null @@ -1,636 +0,0 @@ -# GNU GENERAL PUBLIC LICENSE -Version 3, 29 June 2007 - -Copyright (C) 2007 [Free Software Foundation, Inc.](http://fsf.org/) - -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. - -## Preamble - -The GNU General Public License is a free, copyleft license for software and -other kinds of works. - -The licenses for most software and other practical works are designed to take -away your freedom to share and change the works. By contrast, the GNU General -Public License is intended to guarantee your freedom to share and change all -versions of a program--to make sure it remains free software for all its users. -We, the Free Software Foundation, use the GNU General Public License for most -of our software; it applies also to any other work released this way by its -authors. You can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not price. Our -General Public Licenses are designed to make sure that you have the freedom to -distribute copies of free software (and charge for them if you wish), that you -receive source code or can get it if you want it, that you can change the -software or use pieces of it in new free programs, and that you know you can do -these things. - -To protect your rights, we need to prevent others from denying you these rights -or asking you to surrender the rights. Therefore, you have certain -responsibilities if you distribute copies of the software, or if you modify it: -responsibilities to respect the freedom of others. - -For example, if you distribute copies of such a program, whether gratis or for -a fee, you must pass on to the recipients the same freedoms that you received. -You must make sure that they, too, receive or can get the source code. And you -must show them these terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: - - 1. assert copyright on the software, and - 2. offer you this License giving you legal permission to copy, distribute - and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains that -there is no warranty for this free software. For both users' and authors' sake, -the GPL requires that modified versions be marked as changed, so that their -problems will not be attributed erroneously to authors of previous versions. - -Some devices are designed to deny users access to install or run modified -versions of the software inside them, although the manufacturer can do so. This -is fundamentally incompatible with the aim of protecting users' freedom to -change the software. The systematic pattern of such abuse occurs in the area of -products for individuals to use, which is precisely where it is most -unacceptable. Therefore, we have designed this version of the GPL to prohibit -the practice for those products. If such problems arise substantially in other -domains, we stand ready to extend this provision to those domains in future -versions of the GPL, as needed to protect the freedom of users. - -Finally, every program is threatened constantly by software patents. States -should not allow patents to restrict development and use of software on -general-purpose computers, but in those that do, we wish to avoid the special -danger that patents applied to a free program could make it effectively -proprietary. To prevent this, the GPL assures that patents cannot be used to -render the program non-free. - -The precise terms and conditions for copying, distribution and modification -follow. - -## TERMS AND CONDITIONS - -### 0. Definitions. - -*This License* refers to version 3 of the GNU General Public License. - -*Copyright* also means copyright-like laws that apply to other kinds of works, -such as semiconductor masks. - -*The Program* refers to any copyrightable work licensed under this License. -Each licensee is addressed as *you*. *Licensees* and *recipients* may be -individuals or organizations. - -To *modify* a work means to copy from or adapt all or part of the work in a -fashion requiring copyright permission, other than the making of an exact copy. -The resulting work is called a *modified version* of the earlier work or a work -*based on* the earlier work. - -A *covered work* means either the unmodified Program or a work based on the -Program. - -To *propagate* a work means to do anything with it that, without permission, -would make you directly or secondarily liable for infringement under applicable -copyright law, except executing it on a computer or modifying a private copy. -Propagation includes copying, distribution (with or without modification), -making available to the public, and in some countries other activities as well. - -To *convey* a work means any kind of propagation that enables other parties to -make or receive copies. Mere interaction with a user through a computer -network, with no transfer of a copy, is not conveying. - -An interactive user interface displays *Appropriate Legal Notices* to the -extent that it includes a convenient and prominently visible feature that - - 1. displays an appropriate copyright notice, and - 2. tells the user that there is no warranty for the work (except to the - extent that warranties are provided), that licensees may convey the work - under this License, and how to view a copy of this License. - -If the interface presents a list of user commands or options, such as a menu, a -prominent item in the list meets this criterion. - -### 1. Source Code. - -The *source code* for a work means the preferred form of the work for making -modifications to it. *Object code* means any non-source form of a work. - -A *Standard Interface* means an interface that either is an official standard -defined by a recognized standards body, or, in the case of interfaces specified -for a particular programming language, one that is widely used among developers -working in that language. - -The *System Libraries* of an executable work include anything, other than the -work as a whole, that (a) is included in the normal form of packaging a Major -Component, but which is not part of that Major Component, and (b) serves only -to enable use of the work with that Major Component, or to implement a Standard -Interface for which an implementation is available to the public in source code -form. A *Major Component*, in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system (if any) on -which the executable work runs, or a compiler used to produce the work, or an -object code interpreter used to run it. - -The *Corresponding Source* for a work in object code form means all the source -code needed to generate, install, and (for an executable work) run the object -code and to modify the work, including scripts to control those activities. -However, it does not include the work's System Libraries, or general-purpose -tools or generally available free programs which are used unmodified in -performing those activities but which are not part of the work. For example, -Corresponding Source includes interface definition files associated with source -files for the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, such as -by intimate data communication or control flow between those subprograms and -other parts of the work. - -The Corresponding Source need not include anything that users can regenerate -automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same work. - -### 2. Basic Permissions. - -All rights granted under this License are granted for the term of copyright on -the Program, and are irrevocable provided the stated conditions are met. This -License explicitly affirms your unlimited permission to run the unmodified -Program. The output from running a covered work is covered by this License only -if the output, given its content, constitutes a covered work. This License -acknowledges your rights of fair use or other equivalent, as provided by -copyright law. - -You may make, run and propagate covered works that you do not convey, without -conditions so long as your license otherwise remains in force. You may convey -covered works to others for the sole purpose of having them make modifications -exclusively for you, or provide you with facilities for running those works, -provided that you comply with the terms of this License in conveying all -material for which you do not control copyright. Those thus making or running -the covered works for you must do so exclusively on your behalf, under your -direction and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 makes it -unnecessary. - -### 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological measure -under any applicable law fulfilling obligations under article 11 of the WIPO -copyright treaty adopted on 20 December 1996, or similar laws prohibiting or -restricting circumvention of such measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention is -effected by exercising rights under this License with respect to the covered -work, and you disclaim any intention to limit operation or modification of the -work as a means of enforcing, against the work's users, your or third parties' -legal rights to forbid circumvention of technological measures. - -### 4. Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you receive it, -in any medium, provided that you conspicuously and appropriately publish on -each copy an appropriate copyright notice; keep intact all notices stating that -this License and any non-permissive terms added in accord with section 7 apply -to the code; keep intact all notices of the absence of any warranty; and give -all recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, and you may -offer support or warranty protection for a fee. - -### 5. Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to produce it -from the Program, in the form of source code under the terms of section 4, -provided that you also meet all of these conditions: - - - a) The work must carry prominent notices stating that you modified it, and - giving a relevant date. - - b) The work must carry prominent notices stating that it is released under - this License and any conditions added under section 7. This requirement - modifies the requirement in section 4 to *keep intact all notices*. - - c) You must license the entire work, as a whole, under this License to - anyone who comes into possession of a copy. This License will therefore - apply, along with any applicable section 7 additional terms, to the whole - of the work, and all its parts, regardless of how they are packaged. This - License gives no permission to license the work in any other way, but it - does not invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your work need - not make them do so. - -A compilation of a covered work with other separate and independent works, -which are not by their nature extensions of the covered work, and which are not -combined with it such as to form a larger program, in or on a volume of a -storage or distribution medium, is called an *aggregate* if the compilation and -its resulting copyright are not used to limit the access or legal rights of the -compilation's users beyond what the individual works permit. Inclusion of a -covered work in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -### 6. Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of sections 4 -and 5, provided that you also convey the machine-readable Corresponding Source -under the terms of this License, in one of these ways: - - - a) Convey the object code in, or embodied in, a physical product (including - a physical distribution medium), accompanied by the Corresponding Source - fixed on a durable physical medium customarily used for software - interchange. - - b) Convey the object code in, or embodied in, a physical product (including - a physical distribution medium), accompanied by a written offer, valid for - at least three years and valid for as long as you offer spare parts or - customer support for that product model, to give anyone who possesses the - object code either - 1. a copy of the Corresponding Source for all the software in the product - that is covered by this License, on a durable physical medium - customarily used for software interchange, for a price no more than your - reasonable cost of physically performing this conveying of source, or - 2. access to copy the Corresponding Source from a network server at no - charge. - - c) Convey individual copies of the object code with a copy of the written - offer to provide the Corresponding Source. This alternative is allowed only - occasionally and noncommercially, and only if you received the object code - with such an offer, in accord with subsection 6b. - - d) Convey the object code by offering access from a designated place - (gratis or for a charge), and offer equivalent access to the Corresponding - Source in the same way through the same place at no further charge. You - need not require recipients to copy the Corresponding Source along with the - object code. If the place to copy the object code is a network server, the - Corresponding Source may be on a different server operated by you or a - third party) that supports equivalent copying facilities, provided you - maintain clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the Corresponding - Source, you remain obligated to ensure that it is available for as long as - needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided you - inform other peers where the object code and Corresponding Source of the - work are being offered to the general public at no charge under subsection - 6d. - -A separable portion of the object code, whose source code is excluded from the -Corresponding Source as a System Library, need not be included in conveying the -object code work. - -A *User Product* is either - - 1. a *consumer product*, which means any tangible personal property which is - normally used for personal, family, or household purposes, or - 2. anything designed or sold for incorporation into a dwelling. - -In determining whether a product is a consumer product, doubtful cases shall be -resolved in favor of coverage. For a particular product received by a -particular user, *normally used* refers to a typical or common use of that -class of product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected to use, -the product. A product is a consumer product regardless of whether the product -has substantial commercial, industrial or non-consumer uses, unless such uses -represent the only significant mode of use of the product. - -*Installation Information* for a User Product means any methods, procedures, -authorization keys, or other information required to install and execute -modified versions of a covered work in that User Product from a modified -version of its Corresponding Source. The information must suffice to ensure -that the continued functioning of the modified object code is in no case -prevented or interfered with solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as part of a -transaction in which the right of possession and use of the User Product is -transferred to the recipient in perpetuity or for a fixed term (regardless of -how the transaction is characterized), the Corresponding Source conveyed under -this section must be accompanied by the Installation Information. But this -requirement does not apply if neither you nor any third party retains the -ability to install modified object code on the User Product (for example, the -work has been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates for a -work that has been modified or installed by the recipient, or for the User -Product in which it has been modified or installed. Access to a network may be -denied when the modification itself materially and adversely affects the -operation of the network or violates the rules and protocols for communication -across the network. - -Corresponding Source conveyed, and Installation Information provided, in accord -with this section must be in a format that is publicly documented (and with an -implementation available to the public in source code form), and must require -no special password or key for unpacking, reading or copying. - -### 7. Additional Terms. - -*Additional permissions* are terms that supplement the terms of this License by -making exceptions from one or more of its conditions. Additional permissions -that are applicable to the entire Program shall be treated as though they were -included in this License, to the extent that they are valid under applicable -law. If additional permissions apply only to part of the Program, that part may -be used separately under those permissions, but the entire Program remains -governed by this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option remove any -additional permissions from that copy, or from any part of it. (Additional -permissions may be written to require their own removal in certain cases when -you modify the work.) You may place additional permissions on material, added -by you to a covered work, for which you have or can give appropriate copyright -permission. - -Notwithstanding any other provision of this License, for material you add to a -covered work, you may (if authorized by the copyright holders of that material) -supplement the terms of this License with terms: - - - a) Disclaiming warranty or limiting liability differently from the terms of - sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or author - attributions in that material or in the Appropriate Legal Notices displayed - by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in reasonable - ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or authors - of the material; or - - e) Declining to grant rights under trademark law for use of some trade - names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that material by - anyone who conveys the material (or modified versions of it) with - contractual assumptions of liability to the recipient, for any liability - that these contractual assumptions directly impose on those licensors and - authors. - -All other non-permissive additional terms are considered *further restrictions* -within the meaning of section 10. If the Program as you received it, or any -part of it, contains a notice stating that it is governed by this License along -with a term that is a further restriction, you may remove that term. If a -license document contains a further restriction but permits relicensing or -conveying under this License, you may add to a covered work material governed -by the terms of that license document, provided that the further restriction -does not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you must place, -in the relevant source files, a statement of the additional terms that apply to -those files, or a notice indicating where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the form of a -separately written license, or stated as exceptions; the above requirements -apply either way. - -### 8. Termination. - -You may not propagate or modify a covered work except as expressly provided -under this License. Any attempt otherwise to propagate or modify it is void, -and will automatically terminate your rights under this License (including any -patent licenses granted under the third paragraph of section 11). - -However, if you cease all violation of this License, then your license from a -particular copyright holder is reinstated - - - a) provisionally, unless and until the copyright holder explicitly and - finally terminates your license, and - - b) permanently, if the copyright holder fails to notify you of the - violation by some reasonable means prior to 60 days after the cessation. - -Moreover, your license from a particular copyright holder is reinstated -permanently if the copyright holder notifies you of the violation by some -reasonable means, this is the first time you have received notice of violation -of this License (for any work) from that copyright holder, and you cure the -violation prior to 30 days after your receipt of the notice. - -Termination of your rights under this section does not terminate the licenses -of parties who have received copies or rights from you under this License. If -your rights have been terminated and not permanently reinstated, you do not -qualify to receive new licenses for the same material under section 10. - -### 9. Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run a copy -of the Program. Ancillary propagation of a covered work occurring solely as a -consequence of using peer-to-peer transmission to receive a copy likewise does -not require acceptance. However, nothing other than this License grants you -permission to propagate or modify any covered work. These actions infringe -copyright if you do not accept this License. Therefore, by modifying or -propagating a covered work, you indicate your acceptance of this License to do -so. - -### 10. Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically receives a -license from the original licensors, to run, modify and propagate that work, -subject to this License. You are not responsible for enforcing compliance by -third parties with this License. - -An *entity transaction* is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered work -results from an entity transaction, each party to that transaction who receives -a copy of the work also receives whatever licenses to the work the party's -predecessor in interest had or could give under the previous paragraph, plus a -right to possession of the Corresponding Source of the work from the -predecessor in interest, if the predecessor has it or can get it with -reasonable efforts. - -You may not impose any further restrictions on the exercise of the rights -granted or affirmed under this License. For example, you may not impose a -license fee, royalty, or other charge for exercise of rights granted under this -License, and you may not initiate litigation (including a cross-claim or -counterclaim in a lawsuit) alleging that any patent claim is infringed by -making, using, selling, offering for sale, or importing the Program or any -portion of it. - -### 11. Patents. - -A *contributor* is a copyright holder who authorizes use under this License of -the Program or a work on which the Program is based. The work thus licensed is -called the contributor's *contributor version*. - -A contributor's *essential patent claims* are all patent claims owned or -controlled by the contributor, whether already acquired or hereafter acquired, -that would be infringed by some manner, permitted by this License, of making, -using, or selling its contributor version, but do not include claims that would -be infringed only as a consequence of further modification of the contributor -version. For purposes of this definition, *control* includes the right to grant -patent sublicenses in a manner consistent with the requirements of this -License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free patent -license under the contributor's essential patent claims, to make, use, sell, -offer for sale, import and otherwise run, modify and propagate the contents of -its contributor version. - -In the following three paragraphs, a *patent license* is any express agreement -or commitment, however denominated, not to enforce a patent (such as an express -permission to practice a patent or covenant not to sue for patent -infringement). To *grant* such a patent license to a party means to make such -an agreement or commitment not to enforce a patent against the party. - -If you convey a covered work, knowingly relying on a patent license, and the -Corresponding Source of the work is not available for anyone to copy, free of -charge and under the terms of this License, through a publicly available -network server or other readily accessible means, then you must either - - 1. cause the Corresponding Source to be so available, or - 2. arrange to deprive yourself of the benefit of the patent license for this - particular work, or - 3. arrange, in a manner consistent with the requirements of this License, to - extend the patent license to downstream recipients. - -*Knowingly relying* means you have actual knowledge that, but for the patent -license, your conveying the covered work in a country, or your recipient's use -of the covered work in a country, would infringe one or more identifiable -patents in that country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or arrangement, you -convey, or propagate by procuring conveyance of, a covered work, and grant a -patent license to some of the parties receiving the covered work authorizing -them to use, propagate, modify or convey a specific copy of the covered work, -then the patent license you grant is automatically extended to all recipients -of the covered work and works based on it. - -A patent license is *discriminatory* if it does not include within the scope of -its coverage, prohibits the exercise of, or is conditioned on the non-exercise -of one or more of the rights that are specifically granted under this License. -You may not convey a covered work if you are a party to an arrangement with a -third party that is in the business of distributing software, under which you -make payment to the third party based on the extent of your activity of -conveying the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory patent -license - - - a) in connection with copies of the covered work conveyed by you (or copies - made from those copies), or - - b) primarily for and in connection with specific products or compilations - that contain the covered work, unless you entered into that arrangement, or - that patent license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting any implied -license or other defenses to infringement that may otherwise be available to -you under applicable patent law. - -### 12. No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not excuse -you from the conditions of this License. If you cannot convey a covered work so -as to satisfy simultaneously your obligations under this License and any other -pertinent obligations, then as a consequence you may not convey it at all. For -example, if you agree to terms that obligate you to collect a royalty for -further conveying from those to whom you convey the Program, the only way you -could satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -### 13. Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have permission to -link or combine any covered work with a work licensed under version 3 of the -GNU Affero General Public License into a single combined work, and to convey -the resulting work. The terms of this License will continue to apply to the -part which is the covered work, but the special requirements of the GNU Affero -General Public License, section 13, concerning interaction through a network -will apply to the combination as such. - -### 14. Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions of the GNU -General Public License from time to time. Such new versions will be similar in -spirit to the present version, but may differ in detail to address new problems -or concerns. - -Each version is given a distinguishing version number. If the Program specifies -that a certain numbered version of the GNU General Public License *or any later -version* applies to it, you have the option of following the terms and -conditions either of that numbered version or of any later version published by -the Free Software Foundation. If the Program does not specify a version number -of the GNU General Public License, you may choose any version ever published by -the Free Software Foundation. - -If the Program specifies that a proxy can decide which future versions of the -GNU General Public License can be used, that proxy's public statement of -acceptance of a version permanently authorizes you to choose that version for -the Program. - -Later license versions may give you additional or different permissions. -However, no additional obligations are imposed on any author or copyright -holder as a result of your choosing to follow a later version. - -### 15. Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE -LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER -PARTIES PROVIDE THE PROGRAM *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER -EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE -QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -### 16. Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY -COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS -PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, -INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE -THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED -INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE -PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY -HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -### 17. Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided above cannot -be given local legal effect according to their terms, reviewing courts shall -apply local law that most closely approximates an absolute waiver of all civil -liability in connection with the Program, unless a warranty or assumption of -liability accompanies a copy of the Program in return for a fee. - -## END OF TERMS AND CONDITIONS ### - -### How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest possible -use to the public, the best way to achieve this is to make it free software -which everyone can redistribute and change under these terms. - -To do so, attach the following notices to the program. It is safest to attach -them to the start of each source file to most effectively state the exclusion -of warranty; and each file should have at least the *copyright* line and a -pointer to where the full notice is found. - - - Copyright (C) - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short notice like -this when it starts in an interactive mode: - - Copyright (C) - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w` and `show c` should show the appropriate -parts of the General Public License. Of course, your program's commands might -be different; for a GUI interface, you would use an *about box*. - -You should also get your employer (if you work as a programmer) or school, if -any, to sign a *copyright disclaimer* for the program, if necessary. For more -information on this, and how to apply and follow the GNU GPL, see -[http://www.gnu.org/licenses/](http://www.gnu.org/licenses/). - -The GNU General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may consider -it more useful to permit linking proprietary applications with the library. If -this is what you want to do, use the GNU Lesser General Public License instead -of this License. But first, please read -[http://www.gnu.org/philosophy/why-not-lgpl.html](http://www.gnu.org/philosophy/why-not-lgpl.html). diff --git a/Documentation/license-tactilitykernel.md b/Documentation/license-tactilitykernel.md deleted file mode 100644 index 6fb6a01ee..000000000 --- a/Documentation/license-tactilitykernel.md +++ /dev/null @@ -1,157 +0,0 @@ -# GNU LESSER GENERAL PUBLIC LICENSE - -Version 3, 29 June 2007 - -Copyright (C) 2007 Free Software Foundation, Inc. - - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -This version of the GNU Lesser General Public License incorporates the -terms and conditions of version 3 of the GNU General Public License, -supplemented by the additional permissions listed below. - -## 0. Additional Definitions. - -As used herein, "this License" refers to version 3 of the GNU Lesser -General Public License, and the "GNU GPL" refers to version 3 of the -GNU General Public License. - -"The Library" refers to a covered work governed by this License, other -than an Application or a Combined Work as defined below. - -An "Application" is any work that makes use of an interface provided -by the Library, but which is not otherwise based on the Library. -Defining a subclass of a class defined by the Library is deemed a mode -of using an interface provided by the Library. - -A "Combined Work" is a work produced by combining or linking an -Application with the Library. The particular version of the Library -with which the Combined Work was made is also called the "Linked -Version". - -The "Minimal Corresponding Source" for a Combined Work means the -Corresponding Source for the Combined Work, excluding any source code -for portions of the Combined Work that, considered in isolation, are -based on the Application, and not on the Linked Version. - -The "Corresponding Application Code" for a Combined Work means the -object code and/or source code for the Application, including any data -and utility programs needed for reproducing the Combined Work from the -Application, but excluding the System Libraries of the Combined Work. - -## 1. Exception to Section 3 of the GNU GPL. - -You may convey a covered work under sections 3 and 4 of this License -without being bound by section 3 of the GNU GPL. - -## 2. Conveying Modified Versions. - -If you modify a copy of the Library, and, in your modifications, a -facility refers to a function or data to be supplied by an Application -that uses the facility (other than as an argument passed when the -facility is invoked), then you may convey a copy of the modified -version: - -- a) under this License, provided that you make a good faith effort - to ensure that, in the event an Application does not supply the - function or data, the facility still operates, and performs - whatever part of its purpose remains meaningful, or -- b) under the GNU GPL, with none of the additional permissions of - this License applicable to that copy. - -## 3. Object Code Incorporating Material from Library Header Files. - -The object code form of an Application may incorporate material from a -header file that is part of the Library. You may convey such object -code under terms of your choice, provided that, if the incorporated -material is not limited to numerical parameters, data structure -layouts and accessors, or small macros, inline functions and templates -(ten or fewer lines in length), you do both of the following: - -- a) Give prominent notice with each copy of the object code that - the Library is used in it and that the Library and its use are - covered by this License. -- b) Accompany the object code with a copy of the GNU GPL and this - license document. - -## 4. Combined Works. - -You may convey a Combined Work under terms of your choice that, taken -together, effectively do not restrict modification of the portions of -the Library contained in the Combined Work and reverse engineering for -debugging such modifications, if you also do each of the following: - -- a) Give prominent notice with each copy of the Combined Work that - the Library is used in it and that the Library and its use are - covered by this License. -- b) Accompany the Combined Work with a copy of the GNU GPL and this - license document. -- c) For a Combined Work that displays copyright notices during - execution, include the copyright notice for the Library among - these notices, as well as a reference directing the user to the - copies of the GNU GPL and this license document. -- d) Do one of the following: - - 0) Convey the Minimal Corresponding Source under the terms of - this License, and the Corresponding Application Code in a form - suitable for, and under terms that permit, the user to - recombine or relink the Application with a modified version of - the Linked Version to produce a modified Combined Work, in the - manner specified by section 6 of the GNU GPL for conveying - Corresponding Source. - - 1) Use a suitable shared library mechanism for linking with - the Library. A suitable mechanism is one that (a) uses at run - time a copy of the Library already present on the user's - computer system, and (b) will operate properly with a modified - version of the Library that is interface-compatible with the - Linked Version. -- e) Provide Installation Information, but only if you would - otherwise be required to provide such information under section 6 - of the GNU GPL, and only to the extent that such information is - necessary to install and execute a modified version of the - Combined Work produced by recombining or relinking the Application - with a modified version of the Linked Version. (If you use option - 4d0, the Installation Information must accompany the Minimal - Corresponding Source and Corresponding Application Code. If you - use option 4d1, you must provide the Installation Information in - the manner specified by section 6 of the GNU GPL for conveying - Corresponding Source.) - -## 5. Combined Libraries. - -You may place library facilities that are a work based on the Library -side by side in a single library together with other library -facilities that are not Applications and are not covered by this -License, and convey such a combined library under terms of your -choice, if you do both of the following: - -- a) Accompany the combined library with a copy of the same work - based on the Library, uncombined with any other library - facilities, conveyed under the terms of this License. -- b) Give prominent notice with the combined library that part of it - is a work based on the Library, and explaining where to find the - accompanying uncombined form of the same work. - -## 6. Revised Versions of the GNU Lesser General Public License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU Lesser General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -as you received it specifies that a certain numbered version of the -GNU Lesser General Public License "or any later version" applies to -it, you have the option of following the terms and conditions either -of that published version or of any later version published by the -Free Software Foundation. If the Library as you received it does not -specify a version number of the GNU Lesser General Public License, you -may choose any version of the GNU Lesser General Public License ever -published by the Free Software Foundation. - -If the Library as you received it specifies that a proxy can decide -whether future versions of the GNU Lesser General Public License shall -apply, that proxy's public statement of acceptance of any version is -permanent authorization for you to choose that version for the -Library. diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md index 8f97c9f98..1e44f7681 100644 --- a/THIRD-PARTY-NOTICES.md +++ b/THIRD-PARTY-NOTICES.md @@ -8,15 +8,6 @@ Website: https://www.espressif.com/ License: [Apache License v2.0](https://github.com/espressif/esp-idf/blob/master/LICENSE) -### Flipper Zero Firmware - -Some of the code in inside the Tactility or TactilityCore project has originally been adapted -from the Flipper Zero firmware it was changed to fit the Tactility project. - -Website: https://github.com/flipperdevices/flipperzero-firmware/ - -License: [GPL v3.0](https://github.com/flipperdevices/flipperzero-firmware/blob/dev/LICENSE) - ### Google Fonts & Material Design Icons Websites: @@ -44,14 +35,6 @@ Website: https://github.com/kosma/minmea License: [WTFPL](https://github.com/kosma/minmea/blob/master/LICENSE.grants), [LGPL 3.0](https://github.com/kosma/minmea/blob/master/LICENSE.LGPL-3.0), [MIT](https://github.com/kosma/minmea/blob/master/LICENSE.MIT) -### Meshtastic Firmware - -Parts of the Meshtastic firmware were copied and modified for Tactility. - -Website: https://github.com/meshtastic/firmware - -License: [GPL v3.0](https://github.com/meshtastic/firmware/blob/master/LICENSE) - ### BQ27220 Driver Website: https://github.com/Xinyuan-LilyGO/T-Echo/blob/main/LICENSE @@ -64,6 +47,12 @@ Website: https://github.com/UsefulElectronics/esp32s3-gc9a01-lvgl License: [Explicitly granted by author](https://github.com/TactilityProject/Tactility/pull/295#discussion_r2226215423) +### Andrej Karpathy Skills + +Website: https://github.com/multica-ai/andrej-karpathy-skills + +License: MIT according to [README.md](https://github.com/multica-ai/andrej-karpathy-skills/tree/main) + ### Other Dependencies Some dependencies contain their own license. For example: the subprojects in `Libraries/` diff --git a/Documentation/chat.md b/Tactility/Source/app/chat/README.md similarity index 100% rename from Documentation/chat.md rename to Tactility/Source/app/chat/README.md diff --git a/Documentation/screensavers.md b/Tactility/Source/service/displayidle/README.md similarity index 100% rename from Documentation/screensavers.md rename to Tactility/Source/service/displayidle/README.md diff --git a/Documentation/webserver.md b/Tactility/Source/service/webserver/README.md similarity index 100% rename from Documentation/webserver.md rename to Tactility/Source/service/webserver/README.md From 88c0b9a6ea82ef465f556495ec9727ecddc44ee1 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 20:02:31 +0200 Subject: [PATCH 02/21] Select default widget when no pointer device is present --- Documentation/ideas.md | 1 - .../private/lvgl/devices/indev_private.h | 13 +++++++++++++ .../private/lvgl/devices/keyboard_private.h | 1 - Modules/lvgl-module/source/devices/indev.cpp | 15 +++++++++++++++ Modules/lvgl-module/source/widgets/toolbar.cpp | 5 ++++- Tactility/Source/app/launcher/Launcher.cpp | 14 +++++++++++++- 6 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 Modules/lvgl-module/private/lvgl/devices/indev_private.h create mode 100644 Modules/lvgl-module/source/devices/indev.cpp diff --git a/Documentation/ideas.md b/Documentation/ideas.md index fc3ebddc8..663c00871 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -11,7 +11,6 @@ ## Higher Priority -- lvgl-window-manager: When a keyboard or LV_INDEV_TYPE_ENCODER is attached, always highlight the first widget (~Cardputer navigation issue) in a window when a window is created. - Make it more clear to end-users that an SD card is required to run Tactility - Move "# Fix error "PSRAM space not enough for the Flash instructions" on boot:" fix from T-Deck and others to device.py - Make it possible to override stack size for an app via config file (loaded at boot), and make it possible to set preferred memory location (e.g. internal/external) diff --git a/Modules/lvgl-module/private/lvgl/devices/indev_private.h b/Modules/lvgl-module/private/lvgl/devices/indev_private.h new file mode 100644 index 000000000..b22ec2e34 --- /dev/null +++ b/Modules/lvgl-module/private/lvgl/devices/indev_private.h @@ -0,0 +1,13 @@ +#pragma once + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +bool lvgl_has_indev_of_type(lv_indev_type_t type); + +#ifdef __cplusplus +} +#endif diff --git a/Modules/lvgl-module/private/lvgl/devices/keyboard_private.h b/Modules/lvgl-module/private/lvgl/devices/keyboard_private.h index 0f385d8b4..21d1c3658 100644 --- a/Modules/lvgl-module/private/lvgl/devices/keyboard_private.h +++ b/Modules/lvgl-module/private/lvgl/devices/keyboard_private.h @@ -4,7 +4,6 @@ extern "C" { #endif - void lvgl_keyboard_on_start_lvgl(); void lvgl_keyboard_on_stop_lvgl(); diff --git a/Modules/lvgl-module/source/devices/indev.cpp b/Modules/lvgl-module/source/devices/indev.cpp new file mode 100644 index 000000000..e432a8009 --- /dev/null +++ b/Modules/lvgl-module/source/devices/indev.cpp @@ -0,0 +1,15 @@ +#include + +extern "C" { + +bool lvgl_has_indev_of_type(lv_indev_type_t type) { + for (lv_indev_t* indev = lv_indev_get_next(nullptr); indev != nullptr; indev = lv_indev_get_next(indev)) { + lv_indev_type_t to_check = lv_indev_get_type(indev); + if (to_check == type) { + return true; + } + } + return false; +} + +} // extern "C" diff --git a/Modules/lvgl-module/source/widgets/toolbar.cpp b/Modules/lvgl-module/source/widgets/toolbar.cpp index 612f4f019..b83fc7ce7 100644 --- a/Modules/lvgl-module/source/widgets/toolbar.cpp +++ b/Modules/lvgl-module/source/widgets/toolbar.cpp @@ -2,9 +2,10 @@ #define LV_USE_PRIVATE_API 1 // For actual lv_obj_t declaration #include -#include + #include #include +#include #include #include @@ -160,7 +161,9 @@ lv_obj_t* lvgl_toolbar_create(lv_obj_t* parent, const char* title) { // In that scenario we want to automatically have the close button selected so the user doesn't have to press the widget selection // an extra time for every screen. if (!device_has_active_by_type(&POINTER_TYPE)) { + lv_obj_update_layout(obj); // Resolve flex layout first, so focus/state invalidate against final coords lv_group_focus_obj(toolbar->close_button); + lv_obj_add_state(toolbar->close_button, LV_STATE_FOCUS_KEY); } return obj; diff --git a/Tactility/Source/app/launcher/Launcher.cpp b/Tactility/Source/app/launcher/Launcher.cpp index c72548958..e0b6a66d3 100644 --- a/Tactility/Source/app/launcher/Launcher.cpp +++ b/Tactility/Source/app/launcher/Launcher.cpp @@ -1,3 +1,6 @@ +#include "tactility/drivers/pointer.h" + + #include #include #include @@ -165,7 +168,7 @@ void createWidgets(lv_obj_t* parent, void*) { ? computeButtonMargin(lv_display_get_horizontal_resolution(display), total_button_size) : computeButtonMargin(lv_display_get_vertical_resolution(display), total_button_size); - createAppButton(buttons_wrapper, ui_density, LVGL_ICON_LAUNCHER_APPS, "AppList", margin, is_landscape_display); + auto* app_list_button = createAppButton(buttons_wrapper, ui_density, LVGL_ICON_LAUNCHER_APPS, "AppList", margin, is_landscape_display); createAppButton(buttons_wrapper, ui_density, LVGL_ICON_LAUNCHER_FOLDER, "Files", margin, is_landscape_display); createAppButton(buttons_wrapper, ui_density, LVGL_ICON_LAUNCHER_SETTINGS, "Settings", margin, is_landscape_display); @@ -189,6 +192,15 @@ void createWidgets(lv_obj_t* parent, void*) { lv_label_set_text(power_label, LV_SYMBOL_POWER); lv_obj_set_style_text_color(power_label, lv_theme_get_color_primary(parent), LV_STATE_DEFAULT); } + + // If we don't have a touch device, we assume there's some other kind of input like a keyboard, an encoder or button control + // In that scenario we want to automatically have the app list button selected so the user doesn't have to press the widget selection + // an extra time. + if (!device_has_active_by_type(&POINTER_TYPE)) { + // lv_obj_update_layout(parent); // Resolve flex layout first, so focus/state invalidate against final coords + lv_group_focus_obj(app_list_button); + lv_obj_add_state(app_list_button, LV_STATE_FOCUS_KEY); + } } void runAutoStart() { From 2ab15766db280fd89d473c3d6075a1d79a2b93bf Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 20:05:21 +0200 Subject: [PATCH 03/21] Update ideas.md --- Documentation/ideas.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Documentation/ideas.md b/Documentation/ideas.md index 663c00871..579f636c9 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -17,11 +17,7 @@ - Put task stacks in PSRAM when possible. - Wrap file operations like fopen/fclose with file_mutex - Add bold fonts for e-ink readability improvement -- Split up Claude instructions: https://code.claude.com/docs/en/memory#import-additional-files - and add https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md - Move test projects to their relevant subproject -- tt_alertdialog start() etc is broken as it can't fetch the app instance id. Fetch automatically via thread context? -- Migrate Tactility/Paths.cpp functions to TactilityKernel - app_manager_find_manifest() should make a copy, not return a pointer. - Httpd.cpp: warn if running on same CPU core (or task) as UI/LVGL/window manager. - Improve Setup: Show "Step done" screen @@ -56,12 +52,10 @@ - Consider moving certain drivers into separate modules: audio, bt, wifi, etc - Consider using https://github.com/Graphify-Labs/graphify - Consider implementing LVGL gridnav in apps https://lvgl.io/docs/open/9.3/details/auxiliary-modules/gridnav.html -- Implement a LED kernel driver (single colour and RGB, plain GPIO and PWM) - Make USB host driver disabled by default, so it doesn't consume memory - Filtering for apps in App Hub: - apps that only work on a specific device - Diceware app has large "+" and "-' buttons on Cardputer. It should be smaller. -- Create PwmRgbLedDevice class and implement it for all CYD devices - TactilityTool: Make API compatibility table (and check for compatibility in the tool itself) - Improve EspLcdDisplay to contain all the standard configuration options, and implement a default init function. Add a configuration class. - Make WiFi setup app that starts an access point and hosts a webpage to set up the device. @@ -113,7 +107,6 @@ - Weather app: https://lab.flipper.net/apps/flip_weather - wget app: https://lab.flipper.net/apps/web_crawler (add profiles for known public APIs?) - Chip 8 emulator -- BadUSB (in December 2024, TinyUSB has a bug where uninstalling and re-installing the driver fails) - Discord bot - IR transceiver app - GPS app From 97cadd88b63fbac74c52f6c8207a550a86e789df Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 22:00:35 +0200 Subject: [PATCH 04/21] Update ideas.md --- Documentation/ideas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/ideas.md b/Documentation/ideas.md index 579f636c9..18a90dd63 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -48,6 +48,7 @@ ## Medium Priority +- `platform-esp32`'s module drivers are declared in start/stop of the module but they should be set via `Module::drivers` - `struct Driver` has an `.owner`, but it's not always set. Either validate on Module construct that it matches, or otherwise set it during module start. The problem: NULL parent currently means that driver is not removable. This clashes with setting it dynamically. Consider some kind of flag to determine removability. - Consider moving certain drivers into separate modules: audio, bt, wifi, etc - Consider using https://github.com/Graphify-Labs/graphify From 208c2d6b3155bcd238c53730407bd74cda6b9a30 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 22:14:50 +0200 Subject: [PATCH 05/21] Fix the PSRAM XIP issue in a generic way --- Devices/cl32/device.properties | 6 +----- Devices/lilygo-tdeck-plus/device.properties | 6 ++---- Devices/lilygo-tdeck/device.properties | 1 + Devices/waveshare-esp32-s3-geek/device.properties | 6 +----- .../waveshare-s3-touch-lcd-128/device.properties | 6 +----- Documentation/ideas.md | 1 - device.py | 13 ++++++++++--- 7 files changed, 16 insertions(+), 23 deletions(-) diff --git a/Devices/cl32/device.properties b/Devices/cl32/device.properties index f59540f82..09ed3d8da 100644 --- a/Devices/cl32/device.properties +++ b/Devices/cl32/device.properties @@ -8,6 +8,7 @@ hardware.flashSize=8MB hardware.spiRam=true hardware.spiRamMode=QUAD hardware.spiRamSpeed=80M +hardware.spiRamXipDisabled=true hardware.esptoolFlashFreq=80M hardware.bluetooth=true @@ -19,8 +20,3 @@ display.dpi=139 lvgl.colorDepth=8 lvgl.theme=Mono - -# Fix error "PSRAM space not enough for the Flash instructions" on boot: -sdkconfig.CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n -sdkconfig.CONFIG_SPIRAM_RODATA=n -sdkconfig.CONFIG_SPIRAM_XIP_FROM_PSRAM=n diff --git a/Devices/lilygo-tdeck-plus/device.properties b/Devices/lilygo-tdeck-plus/device.properties index 594b5fc50..d26b67f62 100644 --- a/Devices/lilygo-tdeck-plus/device.properties +++ b/Devices/lilygo-tdeck-plus/device.properties @@ -8,6 +8,7 @@ hardware.flashSize=16MB hardware.spiRam=true hardware.spiRamMode=OCT hardware.spiRamSpeed=120M +hardware.spiRamXipDisabled=true hardware.tinyUsb=true hardware.esptoolFlashFreq=120M hardware.bluetooth=true @@ -24,7 +25,4 @@ lvgl.colorDepth=16 sdkconfig.CONFIG_CODEC_DUMMY_SUPPORT=y -# Fix error "PSRAM space not enough for the Flash instructions" on boot: -sdkconfig.CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n -sdkconfig.CONFIG_SPIRAM_RODATA=n -sdkconfig.CONFIG_SPIRAM_XIP_FROM_PSRAM=n + diff --git a/Devices/lilygo-tdeck/device.properties b/Devices/lilygo-tdeck/device.properties index 7f4b9e457..549d82094 100644 --- a/Devices/lilygo-tdeck/device.properties +++ b/Devices/lilygo-tdeck/device.properties @@ -8,6 +8,7 @@ hardware.flashSize=16MB hardware.spiRam=true hardware.spiRamMode=OCT hardware.spiRamSpeed=120M +hardware.spiRamXipDisabled=true hardware.tinyUsb=true hardware.esptoolFlashFreq=120M hardware.bluetooth=true diff --git a/Devices/waveshare-esp32-s3-geek/device.properties b/Devices/waveshare-esp32-s3-geek/device.properties index 19b06a31b..2cc4f8f7f 100644 --- a/Devices/waveshare-esp32-s3-geek/device.properties +++ b/Devices/waveshare-esp32-s3-geek/device.properties @@ -10,6 +10,7 @@ hardware.flashSize=16MB hardware.spiRam=true hardware.spiRamMode=QUAD hardware.spiRamSpeed=120M +hardware.spiRamXipDisabled=true hardware.tinyUsb=true hardware.esptoolFlashFreq=120M hardware.bluetooth=true @@ -22,8 +23,3 @@ display.dpi=143 lvgl.colorDepth=16 lvgl.uiDensity=compact - -# Fix error "PSRAM space not enough for the Flash instructions" on boot: -sdkconfig.CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n -sdkconfig.CONFIG_SPIRAM_RODATA=n -sdkconfig.CONFIG_SPIRAM_XIP_FROM_PSRAM=n diff --git a/Devices/waveshare-s3-touch-lcd-128/device.properties b/Devices/waveshare-s3-touch-lcd-128/device.properties index a000dbbae..fe358d6e4 100644 --- a/Devices/waveshare-s3-touch-lcd-128/device.properties +++ b/Devices/waveshare-s3-touch-lcd-128/device.properties @@ -10,6 +10,7 @@ hardware.flashSize=16MB hardware.spiRam=true hardware.spiRamMode=QUAD hardware.spiRamSpeed=120M +hardware.spiRamXipDisabled=true hardware.tinyUsb=true hardware.esptoolFlashFreq=120M hardware.bluetooth=true @@ -22,8 +23,3 @@ display.dpi=265 lvgl.colorDepth=16 lvgl.uiDensity=compact - -# Fix error "PSRAM space not enough for the Flash instructions" on boot: -sdkconfig.CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n -sdkconfig.CONFIG_SPIRAM_RODATA=n -sdkconfig.CONFIG_SPIRAM_XIP_FROM_PSRAM=n diff --git a/Documentation/ideas.md b/Documentation/ideas.md index 18a90dd63..c8bd793aa 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -12,7 +12,6 @@ ## Higher Priority - Make it more clear to end-users that an SD card is required to run Tactility -- Move "# Fix error "PSRAM space not enough for the Flash instructions" on boot:" fix from T-Deck and others to device.py - Make it possible to override stack size for an app via config file (loaded at boot), and make it possible to set preferred memory location (e.g. internal/external) - Put task stacks in PSRAM when possible. - Wrap file operations like fopen/fclose with file_mutex diff --git a/device.py b/device.py index 448908258..ba0ea5622 100644 --- a/device.py +++ b/device.py @@ -210,9 +210,16 @@ def write_spiram_variables(output_file, device_properties: dict): output_file.write("CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP=y\n") # Performance improvements if idf_target == "esp32s3": - output_file.write("CONFIG_SPIRAM_FETCH_INSTRUCTIONS=y\n") - output_file.write("CONFIG_SPIRAM_RODATA=y\n") - output_file.write("CONFIG_SPIRAM_XIP_FROM_PSRAM=y\n") + apply_fix = get_property_or_default(device_properties, "hardware.spiRamXipDisabled", "false").lower() + if apply_fix == "true": + output_file.write("# Fix error \"PSRAM space not enough for the Flash instructions\" on boot:") + output_file.write("CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n\n") + output_file.write("CONFIG_SPIRAM_RODATA=n\n") + output_file.write("CONFIG_SPIRAM_XIP_FROM_PSRAM=n\n") + else: + output_file.write("CONFIG_SPIRAM_FETCH_INSTRUCTIONS=y\n") + output_file.write("CONFIG_SPIRAM_RODATA=y\n") + output_file.write("CONFIG_SPIRAM_XIP_FROM_PSRAM=y\n") def write_performance_improvements(output_file, device_properties: dict): idf_target = get_property_or_exit(device_properties, "hardware.target").lower() From c119bdf01f6ee18ad9a7b7b02710785bf7e4a846 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 22:47:25 +0200 Subject: [PATCH 06/21] Use PSRAM for task if possible --- Tactility/Source/lvgl/UsbHidInput.cpp | 67 ++++++++++++++++++++------- 1 file changed, 50 insertions(+), 17 deletions(-) diff --git a/Tactility/Source/lvgl/UsbHidInput.cpp b/Tactility/Source/lvgl/UsbHidInput.cpp index 87f3f8449..56bd6b93c 100644 --- a/Tactility/Source/lvgl/UsbHidInput.cpp +++ b/Tactility/Source/lvgl/UsbHidInput.cpp @@ -7,6 +7,7 @@ #include #include #include +#include #include #include @@ -43,6 +44,9 @@ struct UsbHidInputCtx { QueueHandle_t key_queue = nullptr; TaskHandle_t task = nullptr; SemaphoreHandle_t task_done = nullptr; + // Task control block must stay in internal RAM; only the stack may live in SPIRAM + StackType_t* task_stack = nullptr; + StaticTask_t* task_tcb = nullptr; std::atomic running{false}; std::atomic subscribed{false}; @@ -148,24 +152,12 @@ static void usbHidInputTask(void* arg) { auto* ctx = static_cast(arg); LOG_I(TAG, "started"); - // TODO: Implement time-out - while (!lv_is_initialized()) { - vTaskDelay(pdMS_TO_TICKS(100)); - } - + // The mouse cursor image (loaded from the flash-backed asset filesystem) is created by + // startUsbHidInput() on the caller's stack, before this task exists: this task's stack may + // live in SPIRAM, and touching flash I/O from a SPIRAM stack crashes when the flash cache + // gets disabled mid-read. lvgl_lock(); - // Without a registered display, lv_layer_sys() is NULL: creating the cursor image on it trips - // an LVGL assert whose default handler is an infinite loop (while(1);), hanging this task while - // it holds the LVGL lock. Only create the cursor when a system layer actually exists. - lv_obj_t* sys_layer = lv_layer_sys(); - if (sys_layer != nullptr) { - ctx->mouse_cursor = lv_image_create(sys_layer); - lv_obj_remove_flag(ctx->mouse_cursor, LV_OBJ_FLAG_CLICKABLE); - lv_image_set_src(ctx->mouse_cursor, TT_ASSETS_UI_CURSOR); - lv_obj_add_flag(ctx->mouse_cursor, LV_OBJ_FLAG_HIDDEN); - } - ctx->mouse_indev = lv_indev_create(); lv_indev_set_type(ctx->mouse_indev, LV_INDEV_TYPE_POINTER); lv_indev_set_read_cb(ctx->mouse_indev, mouse_read_cb); @@ -314,6 +306,22 @@ void startUsbHidInput() { return; } + // Created here (not in usbHidInputTask) because loading the cursor image touches the + // flash-backed asset filesystem, which the task's (potentially SPIRAM-backed) stack must + // never do - see the comment in usbHidInputTask. + lvgl_lock(); + // Without a registered display, lv_layer_sys() is NULL: creating the cursor image on it trips + // an LVGL assert whose default handler is an infinite loop (while(1);). Only create the + // cursor when a system layer actually exists. + lv_obj_t* sys_layer = lv_layer_sys(); + if (sys_layer != nullptr) { + ctx->mouse_cursor = lv_image_create(sys_layer); + lv_obj_remove_flag(ctx->mouse_cursor, LV_OBJ_FLAG_CLICKABLE); + lv_image_set_src(ctx->mouse_cursor, TT_ASSETS_UI_CURSOR); + lv_obj_add_flag(ctx->mouse_cursor, LV_OBJ_FLAG_HIDDEN); + } + lvgl_unlock(); + Device* hid_dev = nullptr; if (device_get_first_active_by_type(&USB_HOST_HID_TYPE, &hid_dev) == ERROR_NONE) { ctx->subscribed = usb_host_hid_subscribe(hid_dev, ctx->hid_queue); @@ -321,7 +329,23 @@ void startUsbHidInput() { } ctx->running = true; - if (xTaskCreate(usbHidInputTask, "usb_hid_inp", TASK_STACK, ctx, TASK_PRIORITY, &ctx->task) != pdPASS) { + + static constexpr MemoryPolicy STACK_POLICY = { 0, MEMORY_CAPABILITY_EXTERNAL, 0 }; + ctx->task_stack = static_cast(memory_alloc_with_policy(TASK_STACK * sizeof(StackType_t), &STACK_POLICY)); + if (ctx->task_stack != nullptr) { + static constexpr MemoryPolicy TCB_POLICY = { MEMORY_CAPABILITY_INTERNAL, 0, 0 }; + ctx->task_tcb = static_cast(memory_alloc_with_policy(sizeof(StaticTask_t), &TCB_POLICY)); + } + + if (ctx->task_tcb != nullptr) { + ctx->task = xTaskCreateStatic(usbHidInputTask, "usb_hid_inp", TASK_STACK, ctx, TASK_PRIORITY, ctx->task_stack, ctx->task_tcb); + } else { + memory_free(ctx->task_stack); + ctx->task_stack = nullptr; + xTaskCreate(usbHidInputTask, "usb_hid_inp", TASK_STACK, ctx, TASK_PRIORITY, &ctx->task); + } + + if (ctx->task == nullptr) { LOG_E(TAG, "failed to create task"); ctx->running = false; if (ctx->subscribed) { @@ -331,6 +355,13 @@ void startUsbHidInput() { device_put(cleanup_dev); } } + memory_free(ctx->task_stack); + memory_free(ctx->task_tcb); + if (ctx->mouse_cursor != nullptr) { + lvgl_lock(); + lv_obj_delete(ctx->mouse_cursor); + lvgl_unlock(); + } vQueueDelete(ctx->hid_queue); vQueueDelete(ctx->key_queue); vSemaphoreDelete(ctx->task_done); @@ -366,6 +397,8 @@ void stopUsbHidInput() { } } ctx->task = nullptr; + memory_free(ctx->task_stack); + memory_free(ctx->task_tcb); if (ctx->subscribed) { Device* hid_dev; From 5e4a93c2da993c54b7740a15fcbdb2f8f32bcf69 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:00:25 +0200 Subject: [PATCH 07/21] Update ideas and code docs for wifi callstack requirements for LVGL --- Documentation/ideas.md | 3 ++- Tactility/Source/Tactility.cpp | 4 +--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/Documentation/ideas.md b/Documentation/ideas.md index c8bd793aa..17f03dd89 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -11,9 +11,10 @@ ## Higher Priority +- wifi: wifi_add_event_callback() and wifi_remove_event_callback() should be replaced by a subscribe/await pattern like system events. + When that's changed reduce LVGL callstack size in Tactility.cpp run() - Make it more clear to end-users that an SD card is required to run Tactility - Make it possible to override stack size for an app via config file (loaded at boot), and make it possible to set preferred memory location (e.g. internal/external) -- Put task stacks in PSRAM when possible. - Wrap file operations like fopen/fclose with file_mutex - Add bold fonts for e-ink readability improvement - Move test projects to their relevant subproject diff --git a/Tactility/Source/Tactility.cpp b/Tactility/Source/Tactility.cpp index 7fa77d4a6..5c1181dde 100644 --- a/Tactility/Source/Tactility.cpp +++ b/Tactility/Source/Tactility.cpp @@ -514,9 +514,7 @@ void run(Module* const dtsModules[], const DtsDevice dtsDevices[]) { .on_start = onLvglStarted, .on_stop = onLvglStopped, .task_priority = THREAD_PRIORITY_HIGHER, - /** Minimum seems to be about 3500. In some scenarios, the WiFi app crashes at 8192, - * so we now have 9120 to run in a stable manner. We should figure out a way to avoid this. - * Perhaps we can give apps their own stack space and deal with lvgl callback handlers in a clever way. */ + // TODO: Remove Wi-Fi driver callback mechanism and use subscribe/await from wifi app to be able to reduce callstack .task_stack_size = 9120, #ifdef ESP_PLATFORM .task_affinity = getCpuAffinityConfiguration().graphics From f320023b381362785c29713e324ca6d0e2059b35 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:03:19 +0200 Subject: [PATCH 08/21] Reduce main task stack size from 6kB to 4kB --- Buildscripts/sdkconfig/default.properties | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Buildscripts/sdkconfig/default.properties b/Buildscripts/sdkconfig/default.properties index 6987bea55..d7574c1a0 100644 --- a/Buildscripts/sdkconfig/default.properties +++ b/Buildscripts/sdkconfig/default.properties @@ -1,7 +1,7 @@ # Increase stack size for Wi-Fi (fixes crash after scan) CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=3072 # Ensure large enough stack for network operations -CONFIG_ESP_MAIN_TASK_STACK_SIZE=6144 +CONFIG_ESP_MAIN_TASK_STACK_SIZE=4096 # Fixes static assertion: FLASH and PSRAM Mode configuration are not supported CONFIG_IDF_EXPERIMENTAL_FEATURES=y # Free up IRAM From 203c97eac2e57b3493938a5821dde31b0067d51d Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:10:52 +0200 Subject: [PATCH 09/21] app_manager_find_manifest() makes a copy instead of return a pointer. --- Documentation/ideas.md | 1 - Modules/app-module/include/app/manager.h | 8 +++++-- Modules/app-module/source/manager.cpp | 22 ++++++++++++------- .../Source/app/appdetails/AppDetails.cpp | 2 +- Tactility/Source/app/apphub/AppHubApp.cpp | 3 ++- .../app/apphubdetails/AppHubDetailsApp.cpp | 5 +++-- Tactility/Source/app/boot/Boot.cpp | 3 ++- Tactility/Source/app/launcher/Launcher.cpp | 5 +++-- .../development/DevelopmentService.cpp | 3 ++- .../service/webserver/WebServerService.cpp | 10 ++++----- 10 files changed, 38 insertions(+), 24 deletions(-) diff --git a/Documentation/ideas.md b/Documentation/ideas.md index 17f03dd89..e46b8124a 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -18,7 +18,6 @@ - Wrap file operations like fopen/fclose with file_mutex - Add bold fonts for e-ink readability improvement - Move test projects to their relevant subproject -- app_manager_find_manifest() should make a copy, not return a pointer. - Httpd.cpp: warn if running on same CPU core (or task) as UI/LVGL/window manager. - Improve Setup: Show "Step done" screen - Improve Setup: Add keyboard/keypad navigation explanation diff --git a/Modules/app-module/include/app/manager.h b/Modules/app-module/include/app/manager.h index e35ba5db2..f535282a8 100644 --- a/Modules/app-module/include/app/manager.h +++ b/Modules/app-module/include/app/manager.h @@ -27,8 +27,12 @@ error_t app_manager_add(const struct AppManifest* manifest); */ error_t app_manager_remove(const char* id); -/** @return the manifest, or NULL if not found. */ -const struct AppManifest* app_manager_find_manifest(const char* id); +/** + * @param[out] out_manifest set to a copy of the manifest on success + * @retval ERROR_NOT_FOUND no manifest with this id is registered + * @retval ERROR_NONE on success + */ +error_t app_manager_find_manifest(const char* id, struct AppManifest* out_manifest); /** * Calls `@a` visitor once for every registered manifest. Iteration order is unspecified. diff --git a/Modules/app-module/source/manager.cpp b/Modules/app-module/source/manager.cpp index ae91cbb0f..8db6489a0 100644 --- a/Modules/app-module/source/manager.cpp +++ b/Modules/app-module/source/manager.cpp @@ -48,13 +48,17 @@ error_t app_manager_remove(const char* id) { return ERROR_NONE; } -const AppManifest* app_manager_find_manifest(const char* id) { +error_t app_manager_find_manifest(const char* id, AppManifest* out_manifest) { auto& ledger = app_ledger(); mutex_lock(&ledger.mutex); auto iterator = ledger.manifests.find(id); - const AppManifest* manifest = (iterator != ledger.manifests.end()) ? iterator->second : nullptr; + if (iterator == ledger.manifests.end()) { + mutex_unlock(&ledger.mutex); + return ERROR_NOT_FOUND; + } + *out_manifest = *iterator->second; mutex_unlock(&ledger.mutex); - return manifest; + return ERROR_NONE; } void app_manager_for_each_manifest(AppManifestVisitorFn visitor, void* context) { @@ -88,15 +92,17 @@ char** copy_arguments(int argc, const char* const argv[]) { // app_scheduler_start() frees it on any failure path, and the spawned task frees it once its // run() returns. error_t start_internal(const char* id, AppInstanceId parent_instance_id, int argc, char* argv[], AppInstanceId* out_app_instance_id) { - const AppManifest* manifest = app_manager_find_manifest(id); - if (manifest == nullptr) { + auto& ledger = app_ledger(); + + mutex_lock(&ledger.mutex); + auto manifest_iterator = ledger.manifests.find(id); + if (manifest_iterator == ledger.manifests.end()) { + mutex_unlock(&ledger.mutex); app_ledger_free_arguments(argc, argv); return ERROR_NOT_FOUND; } + const AppManifest* manifest = manifest_iterator->second; - auto& ledger = app_ledger(); - - mutex_lock(&ledger.mutex); AppInstanceId target_id = ledger.next_instance_id++; AppInstanceRecord record { target_id, manifest, APP_INSTANCE_STATE_STARTING, nullptr }; record.parent_id = parent_instance_id; diff --git a/Tactility/Source/app/appdetails/AppDetails.cpp b/Tactility/Source/app/appdetails/AppDetails.cpp index d7f1b72a9..b5e123711 100644 --- a/Tactility/Source/app/appdetails/AppDetails.cpp +++ b/Tactility/Source/app/appdetails/AppDetails.cpp @@ -109,7 +109,7 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { Context ctx {}; ctx.appInstanceId = appInstanceId; ctx.targetAppId = (argc > 0) ? argv[0] : std::string(); - ctx.targetManifest = *app_manager_find_manifest(ctx.targetAppId.c_str()); + app_manager_find_manifest(ctx.targetAppId.c_str(), &ctx.targetManifest); AppEventSubscription sub {}; sub.app_instance_id = appInstanceId; diff --git a/Tactility/Source/app/apphub/AppHubApp.cpp b/Tactility/Source/app/apphub/AppHubApp.cpp index 724c831cf..8ede11b52 100644 --- a/Tactility/Source/app/apphub/AppHubApp.cpp +++ b/Tactility/Source/app/apphub/AppHubApp.cpp @@ -99,7 +99,8 @@ void showApps(Context* ctx) { for (int i = 0; i < ctx->entries.size(); i++) { auto& entry = ctx->entries[i]; LOG_I(TAG, "Adding %s", entry.appName.c_str()); - const char* icon = app_manager_find_manifest(entry.appId.c_str()) != nullptr ? LV_SYMBOL_OK : nullptr; + AppManifest manifest; + const char* icon = app_manager_find_manifest(entry.appId.c_str(), &manifest) == ERROR_NONE ? LV_SYMBOL_OK : nullptr; auto* entry_button = lv_list_add_button(list, icon, entry.appName.c_str()); auto int_as_voidptr = reinterpret_cast(i); lv_obj_set_user_data(entry_button, int_as_voidptr); diff --git a/Tactility/Source/app/apphubdetails/AppHubDetailsApp.cpp b/Tactility/Source/app/apphubdetails/AppHubDetailsApp.cpp index e6dbc4528..6570798a7 100644 --- a/Tactility/Source/app/apphubdetails/AppHubDetailsApp.cpp +++ b/Tactility/Source/app/apphubdetails/AppHubDetailsApp.cpp @@ -159,7 +159,8 @@ void updateApp(Context* ctx) { void updateViews(Context* ctx) { lvgl_toolbar_clear_actions(ctx->toolbar); auto app_id = ctx->entry.appId.c_str(); - const auto manifest = app_manager_find_manifest(app_id); + AppManifest manifest; + bool is_installed = app_manager_find_manifest(app_id, &manifest) == ERROR_NONE; ctx->spinner = lvgl_toolbar_add_spinner_action(ctx->toolbar); lv_obj_add_flag(ctx->spinner, LV_OBJ_FLAG_HIDDEN); lv_obj_add_flag(ctx->updateLabel, LV_OBJ_FLAG_HIDDEN); @@ -177,7 +178,7 @@ void updateViews(Context* ctx) { return; } - if (manifest != nullptr) { + if (is_installed) { if (metadata.app_version_code < ctx->entry.appVersionCode) { ctx->updateButton = lvgl_toolbar_add_image_button_action(ctx->toolbar, LV_SYMBOL_DOWNLOAD, onUpdatePressed, ctx); lv_obj_remove_flag(ctx->updateLabel, LV_OBJ_FLAG_HIDDEN); diff --git a/Tactility/Source/app/boot/Boot.cpp b/Tactility/Source/app/boot/Boot.cpp index 49b299c5b..1f83331f6 100644 --- a/Tactility/Source/app/boot/Boot.cpp +++ b/Tactility/Source/app/boot/Boot.cpp @@ -149,7 +149,8 @@ std::string getLauncherAppId() { } // If the app in the boot.properties does not exist, return default - if (app_manager_find_manifest(boot_properties.launcherAppId.c_str()) == nullptr) { + AppManifest manifest; + if (app_manager_find_manifest(boot_properties.launcherAppId.c_str(), &manifest) != ERROR_NONE) { LOG_E(TAG, "Launcher app %s not found", boot_properties.launcherAppId.c_str()); return CONFIG_TT_LAUNCHER_APP_ID; } diff --git a/Tactility/Source/app/launcher/Launcher.cpp b/Tactility/Source/app/launcher/Launcher.cpp index e0b6a66d3..ac83bcbe7 100644 --- a/Tactility/Source/app/launcher/Launcher.cpp +++ b/Tactility/Source/app/launcher/Launcher.cpp @@ -205,10 +205,11 @@ void createWidgets(lv_obj_t* parent, void*) { void runAutoStart() { settings::BootSettings boot_properties; + AppManifest manifest; if ( // Auto-start due to built-in requirement strcmp(CONFIG_TT_AUTO_START_APP_ID, "") != 0 && - app_manager_find_manifest(CONFIG_TT_AUTO_START_APP_ID) != nullptr + app_manager_find_manifest(CONFIG_TT_AUTO_START_APP_ID, &manifest) == ERROR_NONE ) { LOG_I(TAG, "Starting %s", CONFIG_TT_AUTO_START_APP_ID); uint32_t app_launch_id; @@ -217,7 +218,7 @@ void runAutoStart() { // Auto-start due to user configuration settings::loadBootSettings(boot_properties) && !boot_properties.autoStartAppId.empty() && - app_manager_find_manifest(boot_properties.autoStartAppId.c_str()) != nullptr + app_manager_find_manifest(boot_properties.autoStartAppId.c_str(), &manifest) == ERROR_NONE ) { LOG_I(TAG, "Starting %s", boot_properties.autoStartAppId.c_str()); uint32_t app_launch_id; diff --git a/Tactility/Source/service/development/DevelopmentService.cpp b/Tactility/Source/service/development/DevelopmentService.cpp index 0edd78493..3c0d0abba 100644 --- a/Tactility/Source/service/development/DevelopmentService.cpp +++ b/Tactility/Source/service/development/DevelopmentService.cpp @@ -225,7 +225,8 @@ esp_err_t DevelopmentService::handleAppUninstall(httpd_req_t* request) { return ESP_FAIL; } - if (!app_manager_find_manifest(id_key_pos->second.c_str())) { + AppManifest manifest; + if (app_manager_find_manifest(id_key_pos->second.c_str(), &manifest) != ERROR_NONE) { LOG_I(TAG, "[200] /app/uninstall %s (app wasn't installed)", id_key_pos->second.c_str()); httpd_resp_send(request, nullptr, 0); return ESP_OK; diff --git a/Tactility/Source/service/webserver/WebServerService.cpp b/Tactility/Source/service/webserver/WebServerService.cpp index 97a551249..8297386f2 100644 --- a/Tactility/Source/service/webserver/WebServerService.cpp +++ b/Tactility/Source/service/webserver/WebServerService.cpp @@ -1261,8 +1261,8 @@ esp_err_t WebServerService::handleApiAppsRun(httpd_req_t* request) { return ESP_FAIL; } - auto* manifest = app_manager_find_manifest(appId.c_str()); - if (manifest == nullptr) { + AppManifest manifest; + if (app_manager_find_manifest(appId.c_str(), &manifest) != ERROR_NONE) { httpd_resp_send_err(request, HTTPD_404_NOT_FOUND, "app not found"); return ESP_FAIL; } @@ -1287,15 +1287,15 @@ esp_err_t WebServerService::handleApiAppsUninstall(httpd_req_t* request) { return ESP_FAIL; } - auto* manifest = app_manager_find_manifest(appId.c_str()); - if (manifest == nullptr) { + AppManifest manifest; + if (app_manager_find_manifest(appId.c_str(), &manifest) != ERROR_NONE) { LOG_I(TAG, "[200] /api/apps/uninstall %s (app wasn't installed)", appId.c_str()); httpd_resp_sendstr(request, "ok"); return ESP_OK; } // Only allow uninstalling external (side-loaded) apps - if (manifest->location.type != APP_LOCATION_PATH) { + if (manifest.location.type != APP_LOCATION_PATH) { httpd_resp_send_err(request, HTTPD_403_FORBIDDEN, "cannot uninstall system apps"); return ESP_FAIL; } From a0dc9ee759d82f52bc608ab045ad4ca512039ee8 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:10:58 +0200 Subject: [PATCH 10/21] Bit notation improvement --- Modules/app-module/include/app/manifest.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Modules/app-module/include/app/manifest.h b/Modules/app-module/include/app/manifest.h index ec393d74a..0e2e6e2dc 100644 --- a/Modules/app-module/include/app/manifest.h +++ b/Modules/app-module/include/app/manifest.h @@ -21,7 +21,7 @@ enum AppManifestFlags { /** Excluded from generic app-browsing UIs (AppList, Settings) - for apps only ever reached * by direct navigation (modal dialogs, detail views that require parameters, wizard/ * bootstrap steps). */ - APP_MANIFEST_FLAG_HIDDEN = 0b00000001, + APP_MANIFEST_FLAG_HIDDEN = 1 >> 0, }; /** Describes a registrable app. One manifest exists per app id. */ From d8d06908dc2a7c580678a0df5b6516f409183ae1 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:16:13 +0200 Subject: [PATCH 11/21] Update ideas.md --- Documentation/ideas.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Documentation/ideas.md b/Documentation/ideas.md index e46b8124a..f27e2160c 100644 --- a/Documentation/ideas.md +++ b/Documentation/ideas.md @@ -11,6 +11,7 @@ ## Higher Priority +- Move USB host task stacks to SPIRAM when available: esp32_usbhost*.cpp - wifi: wifi_add_event_callback() and wifi_remove_event_callback() should be replaced by a subscribe/await pattern like system events. When that's changed reduce LVGL callstack size in Tactility.cpp run() - Make it more clear to end-users that an SD card is required to run Tactility @@ -24,7 +25,6 @@ - display.h API: get_backlight does not change ref counting, but it should - bluetooth: various getters for child devices do not change ref counting, but they should - Improve kernel_init.cpp (and other modules): create driver_ensure_added() and driver_ensure_destructed() -- Remove and migrate `Include/Tactility/kernel/Kernel.h` into `tactility/delay.h` - Drivers/audio-codec-module is not a module. Move it somewhere else. Or make it an actual module. - LilyGO T-Dongle S3: 1 button control, stop auto-launching web server - Core2: support power off via software @@ -32,7 +32,6 @@ - Get rid of TactilityC in favour of TactilityKernel and kernel modules - Improve SPI kernel driver (implement read, write, transactions) - Add font design tokens such as "regular", "title" and "smaller". Perhaps via the LVGL kernel module. -- Kernel concepts for ELF loading (generic approach for GUI apps, console apps, libraries). - Fix glitches when installing app via App Hub with 4.3" Waveshare - TCA9534 keyboards should use interrupts - External app loading: Check the version of Tactility and check ESP target hardware to check for compatibility @@ -58,8 +57,6 @@ - Diceware app has large "+" and "-' buttons on Cardputer. It should be smaller. - TactilityTool: Make API compatibility table (and check for compatibility in the tool itself) - Improve EspLcdDisplay to contain all the standard configuration options, and implement a default init function. Add a configuration class. -- Make WiFi setup app that starts an access point and hosts a webpage to set up the device. - This will be useful for devices without a screen, a small screen or a non-touch screen. - Unify the way displays are dimmed. Some implementations turn off the display when it's fully dimmed. Make this a separate functionality. - Bug: Crash handling app cannot be exited with an EncoderDevice. (current work-around is to manually reset the device) @@ -87,6 +84,8 @@ - Calculator app should show regular text input field on non-touch devices that have a keyboard (Cardputer, T-Lora Pager) - Allow for WSAD keys to navigate LVGL (this is extra nice for cardputer, but just handy in general) - Create a "How to" app for a device. It could explain things like keyboard navigation on first start. +- Make WiFi setup app that starts an access point and hosts a webpage to set up the device. + This will be useful for devices without a screen, a small screen or a non-touch screen. # Nice-to-haves From 086662702fb0649b2b7b737829d81514dfae345b Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:29:43 +0200 Subject: [PATCH 12/21] Re-add Meshtastic with better note --- THIRD-PARTY-NOTICES.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md index 1e44f7681..ec0d5e520 100644 --- a/THIRD-PARTY-NOTICES.md +++ b/THIRD-PARTY-NOTICES.md @@ -35,6 +35,14 @@ Website: https://github.com/kosma/minmea License: [WTFPL](https://github.com/kosma/minmea/blob/master/LICENSE.grants), [LGPL 3.0](https://github.com/kosma/minmea/blob/master/LICENSE.LGPL-3.0), [MIT](https://github.com/kosma/minmea/blob/master/LICENSE.MIT) +### Meshtastic Firmware + +Parts of the Meshtastic firmware are used in `gps-meshtastic-module`. This module is included by the `Tactility/` and `Firmware/` projects. + +Website: https://github.com/meshtastic/firmware + +License: [GPL v3.0](https://github.com/meshtastic/firmware/blob/master/LICENSE) + ### BQ27220 Driver Website: https://github.com/Xinyuan-LilyGO/T-Echo/blob/main/LICENSE From 8bf33ee4bb00ad7b77dd9670bcf029d6080e3b38 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:30:43 +0200 Subject: [PATCH 13/21] Coding style improvement --- .claude/rules/coding-style.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md index ca3af292a..86af2023b 100644 --- a/.claude/rules/coding-style.md +++ b/.claude/rules/coding-style.md @@ -9,8 +9,7 @@ For projects that emit C headers and have a C++ implementation file: the interna Formatting is enforced by `.clang-format` (LLVM-based, 4-space indent, no column limit). Never throw exceptions — use return types for error handling. Use `enum class` over plain `enum` when writing C++ code. -Don't do null checks for function parameters: the caller is responsible for passing valid data. -Pointers are expected to be non-null unless documented otherwise. +Do not add redundant null checks for parameters with an explicit non-null precondition. Code Comments: From efa07a7e583a05ed0a6e163886d70224e54e054d Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:32:18 +0200 Subject: [PATCH 14/21] Fix docs --- .claude/rules/key-conventions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.claude/rules/key-conventions.md b/.claude/rules/key-conventions.md index 777cef80f..6ec61199a 100644 --- a/.claude/rules/key-conventions.md +++ b/.claude/rules/key-conventions.md @@ -1,6 +1,7 @@ # Key Conventions -- `#ifdef ESP_PLATFORM` guards ESP32-specific code; the simulator uses POSIX equivalents. +- Shared cross-platform code uses `#ifdef ESP_PLATFORM` for ESP32-specific paths. + Code in `Platforms/PlatformEsp32/` is already ESP-only and does not need guards around ESP-IDF includes. - The `Drivers/` directory contains hardware drivers (display controllers, touch controllers, PMICs, etc.) — each is its own CMake component. - `Modules/` contains cross-cutting modules. e.g.`lvgl-module` (LVGL task management). - `Data/system/` and `Data/data/` are flashed as FAT filesystem images on ESP32. From 5d1e86b4f3ebcd566038aa93d7cef7af46fd252e Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:32:41 +0200 Subject: [PATCH 15/21] Fix for variable name --- .claude/rules/building.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/rules/building.md b/.claude/rules/building.md index 11bdbf3f5..753c8fc54 100644 --- a/.claude/rules/building.md +++ b/.claude/rules/building.md @@ -32,12 +32,12 @@ Device IDs are the folder names under `Devices/` (e.g. `lilygo-tdeck`, `m5stack- On native Windows, `idf.py` is not on PATH by default — it must be activated per-shell first. The install script places a PowerShell profile activator per IDF version at -`%IDF_TOOL_PATH%\Microsoft.v.PowerShell_profile.ps1` (path controlled by the -`IDF_TOOL_PATH` environment variable, set to wherever ESP-IDF's tools were installed, e.g. +`%IDF_TOOLS_PATH%\Microsoft.v.PowerShell_profile.ps1` (path controlled by the +`IDF_TOOLS_PATH` environment variable, set to wherever ESP-IDF's tools were installed, e.g. `C:\Espressif\tools`). Source it before running any `idf.py` command: ```powershell -. "$env:IDF_TOOL_PATH\Microsoft.v5.5.2.PowerShell_profile.ps1" # match the installed IDF version +. "$env:IDF_TOOLS_PATH\Microsoft.v5.5.2.PowerShell_profile.ps1" # match the installed IDF version Set-Location "" idf.py build 2>&1 | Select-Object -Last 250 ``` From c7dd768b51ed594337aec3efa94314b55e5e84aa Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:35:02 +0200 Subject: [PATCH 16/21] Fix for error handling --- Tactility/Source/app/appdetails/AppDetails.cpp | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Tactility/Source/app/appdetails/AppDetails.cpp b/Tactility/Source/app/appdetails/AppDetails.cpp index b5e123711..34d810f43 100644 --- a/Tactility/Source/app/appdetails/AppDetails.cpp +++ b/Tactility/Source/app/appdetails/AppDetails.cpp @@ -109,7 +109,11 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { Context ctx {}; ctx.appInstanceId = appInstanceId; ctx.targetAppId = (argc > 0) ? argv[0] : std::string(); - app_manager_find_manifest(ctx.targetAppId.c_str(), &ctx.targetManifest); + if (app_manager_find_manifest(ctx.targetAppId.c_str(), &ctx.targetManifest) != ERROR_NONE) { + LOG_W(TAG, "App %s not found", ctx.targetAppId.c_str()); + app_manager_finish(appInstanceId); + return 0; + } AppEventSubscription sub {}; sub.app_instance_id = appInstanceId; From c4835c2c70cfb58e1aa76a2c2a8e4e9d4cc6a6f6 Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Wed, 12 Aug 2026 23:42:23 +0200 Subject: [PATCH 17/21] Task cleanup fix --- Tactility/Source/lvgl/UsbHidInput.cpp | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/Tactility/Source/lvgl/UsbHidInput.cpp b/Tactility/Source/lvgl/UsbHidInput.cpp index 56bd6b93c..65d2f7d5f 100644 --- a/Tactility/Source/lvgl/UsbHidInput.cpp +++ b/Tactility/Source/lvgl/UsbHidInput.cpp @@ -274,7 +274,13 @@ static void usbHidInputTask(void* arg) { LOG_I(TAG, "stopped"); xSemaphoreGive(ctx->task_done); - vTaskDelete(nullptr); + + // Never self-delete: vTaskDelete(NULL) can only defer its TCB/stack cleanup to the idle + // task, which would still be touching task_stack/task_tcb after stopUsbHidInput() frees + // them. Suspending instead leaves this task parked (never running again) so + // stopUsbHidInput() can delete it from its own task context, where a non-running target + // makes vTaskDelete() free everything synchronously, before it touches those buffers. + vTaskSuspend(nullptr); } void startUsbHidInput() { @@ -382,9 +388,9 @@ void stopUsbHidInput() { if (xSemaphoreTake(ctx->task_done, pdMS_TO_TICKS(STOP_TIMEOUT_MS)) != pdTRUE) { LOG_W(TAG, "task stop timed out, force terminating"); - vTaskDelete(ctx->task); - // Task was killed before it could clean up LVGL objects; do it here to - // prevent mouse_read_cb / keyboard_read_cb from running with a freed ctx. + // Task hasn't reached its own cleanup/vTaskSuspend() yet; do the LVGL cleanup here to + // prevent mouse_read_cb / keyboard_read_cb from running with a freed ctx. The task + // itself is deleted below, same as the non-timeout path. if (lvgl_try_lock(pdMS_TO_TICKS(200))) { if (ctx->mouse_indev) { lv_indev_delete(ctx->mouse_indev); ctx->mouse_indev = nullptr; } if (ctx->mouse_cursor) { lv_obj_delete(ctx->mouse_cursor); ctx->mouse_cursor = nullptr; } @@ -396,6 +402,16 @@ void stopUsbHidInput() { lvgl_unlock(); } } + + // usbHidInputTask() always ends by suspending itself (never self-deletes), so it's + // guaranteed to still exist here. Wait until it's actually not running before deleting it: + // vTaskDelete() on a non-running target runs its TCB/stack cleanup synchronously instead + // of deferring it to the idle task, which is what makes it safe to free task_stack/ + // task_tcb right below - a deferred cleanup would still be touching them. + while (eTaskGetState(ctx->task) == eRunning) { + taskYIELD(); + } + vTaskDelete(ctx->task); ctx->task = nullptr; memory_free(ctx->task_stack); memory_free(ctx->task_tcb); From 58a0c191b31954ab68ca54479ca420f01b2ff83b Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Thu, 13 Aug 2026 19:23:10 +0200 Subject: [PATCH 18/21] Fix for view update issue when app was in background --- .../lvgl_window_manager/window_manager.h | 26 ++++++++++ .../source/window_manager.cpp | 48 +++++++++++++++---- .../Private/Tactility/app/wifimanage/View.h | 3 ++ Tactility/Source/app/wifimanage/View.cpp | 13 +++++ .../Source/app/wifimanage/WifiManage.cpp | 11 ++++- 5 files changed, 90 insertions(+), 11 deletions(-) diff --git a/Modules/lvgl-window-manager-module/include/lvgl_window_manager/window_manager.h b/Modules/lvgl-window-manager-module/include/lvgl_window_manager/window_manager.h index aee01d8b8..4651f94ae 100644 --- a/Modules/lvgl-window-manager-module/include/lvgl_window_manager/window_manager.h +++ b/Modules/lvgl-window-manager-module/include/lvgl_window_manager/window_manager.h @@ -85,6 +85,26 @@ error_t window_manager_stop(void); */ typedef void (*WindowCreateWidgetsFn)(lv_obj_t* root, void* user_data); +/** + * Called whenever this window's live widgets are about to be deleted while the window record + * itself survives - i.e. its owning app is still running and may see this window resurface + * later. + * Always paired 1:1 with a prior @a create_widgets call that actually ran. + * Never called for a window whose widgets were never built. + * @param[in] user_data whatever was passed to window_manager_create_ext() for this window + * @warning Called on the LVGL task with the LVGL lock already held (same as + * WindowCreateWidgetsFn) - do NOT call window_manager_start()/stop()/create()/create_ext()/ + * remove() from this callback, that would deadlock. + * @warning Do NOT acquire any other lock from this callback either. It runs while a thread + * elsewhere may already be holding that lock and blocked waiting for the LVGL lock this + * callback is running under - acquiring it here would deadlock against that thread. Only touch + * memory that needs no other synchronization, e.g. null out this window's own cached + * lv_obj_t* pointers (they're only ever otherwise touched under the LVGL lock anyway) so a + * stale update arriving after this call can detect the window is gone instead of using freed + * widgets. + */ +typedef void (*WindowDestroyWidgetsFn)(void* user_data); + /** * Creates a new window on top of the stack (last created = topmost). Deletes the previously * topmost window's widgets (if any) and builds this window's widgets immediately via @@ -97,6 +117,12 @@ typedef void (*WindowCreateWidgetsFn)(lv_obj_t* root, void* user_data); */ WindowId window_manager_create(AppInstanceId app_instance_id, WindowCreateWidgetsFn create_widgets, void* user_data); +/** + * Same as window_manager_create(), but also registers @a destroy_widgets - see its docs. + * @param[in] destroy_widgets may be NULL to opt out (equivalent to window_manager_create()) + */ +WindowId window_manager_create_ext(AppInstanceId app_instance_id, WindowCreateWidgetsFn create_widgets, WindowDestroyWidgetsFn destroy_widgets, void* user_data); + /** * Removes a window, wherever it is in the stack - not necessarily the topmost one. If it was * topmost, its widgets are deleted and whichever window is now on top (if any) has its diff --git a/Modules/lvgl-window-manager-module/source/window_manager.cpp b/Modules/lvgl-window-manager-module/source/window_manager.cpp index 9c1c7c69e..d71167440 100644 --- a/Modules/lvgl-window-manager-module/source/window_manager.cpp +++ b/Modules/lvgl-window-manager-module/source/window_manager.cpp @@ -38,6 +38,7 @@ struct WindowRecord { WindowId id; uint32_t app_instance_id; WindowCreateWidgetsFn create_widgets; + WindowDestroyWidgetsFn destroy_widgets; void* user_data; /** Set by window_manager_await_state_change() when a task is blocked waiting on this @@ -108,11 +109,16 @@ lv_obj_t* build_window_widget(lv_obj_t* content, WindowCreateWidgetsFn create_wi return widget; } -void delete_widget(lv_obj_t* widget) { +// destroy_widgets, if set, is called inside the same LVGL-locked section as the deletion - see +// WindowDestroyWidgetsFn's warnings about what it may safely do from in here. +void delete_widget(lv_obj_t* widget, WindowDestroyWidgetsFn destroy_widgets = nullptr, void* user_data = nullptr) { if (widget == nullptr) { return; } lvgl_lock(); + if (destroy_widgets != nullptr) { + destroy_widgets(user_data); + } lv_obj_delete(widget); lvgl_unlock(); } @@ -220,6 +226,7 @@ error_t window_manager_start(void) { // task stays blocked in its own event loop forever, with no window and no signal telling // it to rebuild one. WindowCreateWidgetsFn top_create_widgets = nullptr; + WindowDestroyWidgetsFn top_destroy_widgets = nullptr; void* top_user_data = nullptr; WindowId top_id = 0; bool has_top = false; @@ -230,6 +237,7 @@ error_t window_manager_start(void) { s.started = true; if (!s.windows.empty()) { top_create_widgets = s.windows.back().create_widgets; + top_destroy_widgets = s.windows.back().destroy_widgets; top_user_data = s.windows.back().user_data; top_id = s.windows.back().id; has_top = true; @@ -249,7 +257,7 @@ error_t window_manager_start(void) { // The window stack changed while we were building, e.g. a concurrent remove() - // discard what we just made. - delete_widget(new_widget); + delete_widget(new_widget, top_destroy_widgets, top_user_data); } mutex_unlock(&s.lifecycle_mutex); @@ -278,6 +286,10 @@ error_t window_manager_stop(void) { waiters.push_back(signal); } } + // Only the topmost window has a live widget - it's the only one whose destroy_widgets needs + // to fire. + WindowDestroyWidgetsFn top_destroy_widgets = !s.windows.empty() ? s.windows.back().destroy_widgets : nullptr; + void* top_user_data = !s.windows.empty() ? s.windows.back().user_data : nullptr; s.real_root_widget = nullptr; s.content_root_widget = nullptr; s.top_widget = nullptr; @@ -297,13 +309,17 @@ error_t window_manager_stop(void) { } // Deleting the real widget cascades to everything under it - chrome and top_widget alike. - delete_widget(widget); + delete_widget(widget, top_destroy_widgets, top_user_data); mutex_unlock(&s.lifecycle_mutex); return ERROR_NONE; } WindowId window_manager_create(AppInstanceId app_instance_id, WindowCreateWidgetsFn create_widgets, void* user_data) { + return window_manager_create_ext(app_instance_id, create_widgets, nullptr, user_data); +} + +WindowId window_manager_create_ext(AppInstanceId app_instance_id, WindowCreateWidgetsFn create_widgets, WindowDestroyWidgetsFn destroy_widgets, void* user_data) { if (app_instance_id == 0) { return 0; } @@ -324,16 +340,24 @@ WindowId window_manager_create(AppInstanceId app_instance_id, WindowCreateWidget lv_obj_t* content = s.content_root_widget; lv_obj_t* old_top_widget = s.top_widget; // The current topmost window, if any, is about to be superseded - claim its waiter here - // so it gets notified below. - WindowWaitSignal* waiter = !s.windows.empty() ? claim_waiter_locked(s.windows.back()) : nullptr; + // so it gets notified below, and grab its destroy_widgets so it can be told its widget is + // about to go away. + WindowWaitSignal* waiter = nullptr; + WindowDestroyWidgetsFn old_destroy_widgets = nullptr; + void* old_user_data = nullptr; + if (!s.windows.empty()) { + waiter = claim_waiter_locked(s.windows.back()); + old_destroy_widgets = s.windows.back().destroy_widgets; + old_user_data = s.windows.back().user_data; + } s.top_widget = nullptr; WindowId new_id = s.next_id++; - s.windows.push_back(WindowRecord { new_id, app_instance_id, create_widgets, user_data }); + s.windows.push_back(WindowRecord { new_id, app_instance_id, create_widgets, destroy_widgets, user_data }); mutex_unlock(&s.mutex); give_and_release(waiter); - delete_widget(old_top_widget); + delete_widget(old_top_widget, old_destroy_widgets, old_user_data); lv_obj_t* new_widget = build_window_widget(content, create_widgets, user_data); mutex_lock(&s.mutex); @@ -346,7 +370,7 @@ WindowId window_manager_create(AppInstanceId app_instance_id, WindowCreateWidget // Another window became topmost while we were building, e.g. a concurrent create() from // another app thread - discard what we just made. - delete_widget(new_widget); + delete_widget(new_widget, destroy_widgets, user_data); mutex_unlock(&s.lifecycle_mutex); return new_id; @@ -374,11 +398,14 @@ void window_manager_remove(WindowId id) { // since stopped being topmost without being removed, window_manager_create() would already // have claimed and cleared it. So a buried window's waiting_signal is always already null. WindowWaitSignal* waiter = claim_waiter_locked(*iterator); + WindowDestroyWidgetsFn removed_destroy_widgets = iterator->destroy_widgets; + void* removed_user_data = iterator->user_data; s.windows.erase(iterator); lv_obj_t* content = s.content_root_widget; lv_obj_t* old_widget = nullptr; WindowCreateWidgetsFn next_create_widgets = nullptr; + WindowDestroyWidgetsFn next_destroy_widgets = nullptr; void* next_user_data = nullptr; WindowId next_id = 0; bool has_next = false; @@ -388,6 +415,7 @@ void window_manager_remove(WindowId id) { s.top_widget = nullptr; if (!s.windows.empty()) { next_create_widgets = s.windows.back().create_widgets; + next_destroy_widgets = s.windows.back().destroy_widgets; next_user_data = s.windows.back().user_data; next_id = s.windows.back().id; has_next = true; @@ -403,7 +431,7 @@ void window_manager_remove(WindowId id) { return; } - delete_widget(old_widget); + delete_widget(old_widget, removed_destroy_widgets, removed_user_data); lv_obj_t* new_widget = has_next ? build_window_widget(content, next_create_widgets, next_user_data) : nullptr; mutex_lock(&s.mutex); @@ -414,7 +442,7 @@ void window_manager_remove(WindowId id) { } mutex_unlock(&s.mutex); - delete_widget(new_widget); + delete_widget(new_widget, next_destroy_widgets, next_user_data); mutex_unlock(&s.lifecycle_mutex); } diff --git a/Tactility/Private/Tactility/app/wifimanage/View.h b/Tactility/Private/Tactility/app/wifimanage/View.h index fdf989547..f00379168 100644 --- a/Tactility/Private/Tactility/app/wifimanage/View.h +++ b/Tactility/Private/Tactility/app/wifimanage/View.h @@ -36,6 +36,9 @@ class View final { void init(uint32_t appInstanceId, lv_obj_t* parent); void update(); + /** Called when this window's widgets have been (or are about to be) deleted out from under + * it - see WindowDestroyWidgetsFn. Only nulls out pointers; must stay lock-free. */ + void reset(); }; diff --git a/Tactility/Source/app/wifimanage/View.cpp b/Tactility/Source/app/wifimanage/View.cpp index b841544a4..2deb6407e 100644 --- a/Tactility/Source/app/wifimanage/View.cpp +++ b/Tactility/Source/app/wifimanage/View.cpp @@ -323,10 +323,23 @@ void View::init(uint32_t newAppInstanceId, lv_obj_t* parent) { } void View::update() { + if (root == nullptr) { + // Buried (or not yet built) - see reset(). + return; + } updateWifiToggle(); updateScanning(); updateNetworkList(); updateConnectToHidden(); } +void View::reset() { + root = nullptr; + enable_switch = nullptr; + enable_on_boot_switch = nullptr; + scanning_spinner = nullptr; + networks_list = nullptr; + connect_to_hidden = nullptr; +} + } // namespace diff --git a/Tactility/Source/app/wifimanage/WifiManage.cpp b/Tactility/Source/app/wifimanage/WifiManage.cpp index 1748b0392..006335146 100644 --- a/Tactility/Source/app/wifimanage/WifiManage.cpp +++ b/Tactility/Source/app/wifimanage/WifiManage.cpp @@ -65,6 +65,8 @@ static void onConnectToHidden() { void requestViewUpdate(Context* ctx) { ctx->lock(); lvgl_lock(); + // Safe even while buried (e.g. WifiApSettings/WifiConnect opened on top): destroyWidgets() + // nulls the view's widget pointers before they're deleted, and update() no-ops on that. ctx->view.update(); lvgl_unlock(); ctx->unlock(); @@ -103,6 +105,13 @@ void createWidgets(lv_obj_t* parent, void* userData) { ctx->unlock(); } +// Runs with the LVGL lock already held, possibly on another app's thread - see +// WindowDestroyWidgetsFn's warnings. Must stay lock-free: View::reset() only nulls pointers. +void destroyWidgets(void* userData) { + auto* ctx = static_cast(userData); + ctx->view.reset(); +} + int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { Context ctx; ctx.appInstanceId = appInstanceId; @@ -127,7 +136,7 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { sub.app_instance_id = appInstanceId; app_event_subscribe(&sub); - WindowId window = window_manager_create(appInstanceId, createWidgets, &ctx); + WindowId window = window_manager_create_ext(appInstanceId, createWidgets, destroyWidgets, &ctx); service::wifi::RadioState radio_state = service::wifi::getRadioState(); bool can_scan = radio_state == service::wifi::RadioState::On || From f3ea5f081c87040dc384853a5bcc168fd33e8a4b Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Thu, 13 Aug 2026 19:27:22 +0200 Subject: [PATCH 19/21] Fix --- Tactility/Source/lvgl/UsbHidInput.cpp | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Tactility/Source/lvgl/UsbHidInput.cpp b/Tactility/Source/lvgl/UsbHidInput.cpp index 65d2f7d5f..b5b55a4d9 100644 --- a/Tactility/Source/lvgl/UsbHidInput.cpp +++ b/Tactility/Source/lvgl/UsbHidInput.cpp @@ -388,19 +388,22 @@ void stopUsbHidInput() { if (xSemaphoreTake(ctx->task_done, pdMS_TO_TICKS(STOP_TIMEOUT_MS)) != pdTRUE) { LOG_W(TAG, "task stop timed out, force terminating"); - // Task hasn't reached its own cleanup/vTaskSuspend() yet; do the LVGL cleanup here to - // prevent mouse_read_cb / keyboard_read_cb from running with a freed ctx. The task - // itself is deleted below, same as the non-timeout path. - if (lvgl_try_lock(pdMS_TO_TICKS(200))) { - if (ctx->mouse_indev) { lv_indev_delete(ctx->mouse_indev); ctx->mouse_indev = nullptr; } - if (ctx->mouse_cursor) { lv_obj_delete(ctx->mouse_cursor); ctx->mouse_cursor = nullptr; } - if (ctx->kb_indev) { - lvgl_hardware_keyboard_remove_custom(ctx->kb_indev); - lv_indev_delete(ctx->kb_indev); - ctx->kb_indev = nullptr; - } - lvgl_unlock(); + // Task hasn't reached its own cleanup/vTaskSuspend() yet - it may even be blocked inside + // its own lvgl_lock() (usbHidInputTask's post-loop cleanup), which leaves it eBlocked + // rather than eRunning. If we gave up here on a failed try-lock, the eTaskGetState() + // loop below would see that same eBlocked state, treat the task as done, and delete() + // ctx below while the indevs still hold it as user_data. Block for as long as it takes + // to get the lock instead - the task's own cleanup is idempotent (guarded by these same + // null checks) so it's harmless if it also runs this after us. + lvgl_lock(); + if (ctx->mouse_indev) { lv_indev_delete(ctx->mouse_indev); ctx->mouse_indev = nullptr; } + if (ctx->mouse_cursor) { lv_obj_delete(ctx->mouse_cursor); ctx->mouse_cursor = nullptr; } + if (ctx->kb_indev) { + lvgl_hardware_keyboard_remove_custom(ctx->kb_indev); + lv_indev_delete(ctx->kb_indev); + ctx->kb_indev = nullptr; } + lvgl_unlock(); } // usbHidInputTask() always ends by suspending itself (never self-deletes), so it's From 178e85aff96ff5f9c0e84e87015796b45f0f144b Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Thu, 13 Aug 2026 19:39:27 +0200 Subject: [PATCH 20/21] Another wifi crash fix --- .../app/wifiapsettings/WifiApSettings.cpp | 26 +++++++++++++++---- .../Source/app/wificonnect/WifiConnect.cpp | 11 +++++--- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/Tactility/Source/app/wifiapsettings/WifiApSettings.cpp b/Tactility/Source/app/wifiapsettings/WifiApSettings.cpp index 349b20660..7c5a81527 100644 --- a/Tactility/Source/app/wifiapsettings/WifiApSettings.cpp +++ b/Tactility/Source/app/wifiapsettings/WifiApSettings.cpp @@ -105,6 +105,10 @@ void updateBusySpinner(Context* ctx) { } void updateViews(Context* ctx) { + if (ctx->connectButton == nullptr) { + // Buried (e.g. the forget confirmation dialog opened on top) - see destroyWidgets(). + return; + } updateConnectButton(ctx); updateBusySpinner(ctx); } @@ -115,12 +119,17 @@ void requestViewUpdate(Context* ctx) { lvgl_unlock(); } -void createWidgets(lv_obj_t* parent, void* userData) { +// Runs with the LVGL lock already held, possibly on another app's thread - see +// WindowDestroyWidgetsFn's warnings. Must stay lock-free: only nulls pointers. +void destroyWidgets(void* userData) { auto* ctx = static_cast(userData); + ctx->busySpinner = nullptr; + ctx->connectButton = nullptr; + ctx->disconnectButton = nullptr; +} - ctx->wifiSubscription = service::wifi::getPubsub()->subscribe([ctx](auto) { - requestViewUpdate(ctx); - }); +void createWidgets(lv_obj_t* parent, void* userData) { + auto* ctx = static_cast(userData); lv_obj_set_flex_flow(parent, LV_FLEX_FLOW_COLUMN); lv_obj_set_style_pad_row(parent, 0, LV_STATE_DEFAULT); @@ -202,7 +211,14 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { sub.app_instance_id = appInstanceId; app_event_subscribe(&sub); - WindowId window = window_manager_create(appInstanceId, createWidgets, &ctx); + // Subscribed once here, not in createWidgets(): that callback re-runs on every + // burial/resurface rebuild, and re-subscribing there would leak the previous subscription + // (and its captured ctx pointer) every time, only the last of which shutdown ever cleans up. + ctx.wifiSubscription = service::wifi::getPubsub()->subscribe([&ctx](auto) { + requestViewUpdate(&ctx); + }); + + WindowId window = window_manager_create_ext(appInstanceId, createWidgets, destroyWidgets, &ctx); bool shouldClose = false; while (!shouldClose) { diff --git a/Tactility/Source/app/wificonnect/WifiConnect.cpp b/Tactility/Source/app/wificonnect/WifiConnect.cpp index 587b9d8e9..c36f424a6 100644 --- a/Tactility/Source/app/wificonnect/WifiConnect.cpp +++ b/Tactility/Source/app/wificonnect/WifiConnect.cpp @@ -198,10 +198,6 @@ void createBottomButtons(Context* ctx, lv_obj_t* parent) { void createWidgets(lv_obj_t* parent, void* userData) { auto* ctx = static_cast(userData); - ctx->wifiSubscription = service::wifi::getPubsub()->subscribe([ctx](auto event) { - onWifiEvent(ctx, event); - }); - lv_obj_set_flex_flow(parent, LV_FLEX_FLOW_COLUMN); lv_obj_set_style_pad_row(parent, 0, LV_STATE_DEFAULT); @@ -302,6 +298,13 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { sub.app_instance_id = appInstanceId; app_event_subscribe(&sub); + // Subscribed once here, not in createWidgets(): that callback re-runs on every + // burial/resurface rebuild, and re-subscribing there would leak the previous subscription + // (and its captured ctx pointer) every time, only the last of which shutdown ever cleans up. + ctx.wifiSubscription = service::wifi::getPubsub()->subscribe([&ctx](auto event) { + onWifiEvent(&ctx, event); + }); + WindowId window = window_manager_create(appInstanceId, createWidgets, &ctx); bool shouldClose = false; From ef98f6eebe979e6c3835ed3935ff6824117bc37e Mon Sep 17 00:00:00 2001 From: Ken Van Hoeylandt Date: Thu, 13 Aug 2026 19:52:48 +0200 Subject: [PATCH 21/21] Improvements --- .../source/window_manager.cpp | 4 ++++ .../Source/app/wificonnect/WifiConnect.cpp | 21 ++++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/Modules/lvgl-window-manager-module/source/window_manager.cpp b/Modules/lvgl-window-manager-module/source/window_manager.cpp index d71167440..193c4561d 100644 --- a/Modules/lvgl-window-manager-module/source/window_manager.cpp +++ b/Modules/lvgl-window-manager-module/source/window_manager.cpp @@ -324,6 +324,10 @@ WindowId window_manager_create_ext(AppInstanceId app_instance_id, WindowCreateWi return 0; } + if (destroy_widgets != nullptr) { + check(create_widgets != nullptr); + } + auto& s = state(); // See lifecycle_mutex's comment: blocks a concurrent window_manager_stop() (or another diff --git a/Tactility/Source/app/wificonnect/WifiConnect.cpp b/Tactility/Source/app/wificonnect/WifiConnect.cpp index c36f424a6..0b4c74c44 100644 --- a/Tactility/Source/app/wificonnect/WifiConnect.cpp +++ b/Tactility/Source/app/wificonnect/WifiConnect.cpp @@ -120,6 +120,11 @@ void setLoading(Context* ctx, bool loading) { } void updateView(Context* ctx) { + if (ctx->connect_button == nullptr) { + // Buried (e.g. this window's own connecting state closed it, or a future dialog opens + // on top) - see destroyWidgets(). + return; + } if (ctx->connectionError) { setLoading(ctx, false); resetErrors(ctx); @@ -194,6 +199,20 @@ void createBottomButtons(Context* ctx, lv_obj_t* parent) { lv_obj_add_event_cb(ctx->connect_button, onConnectPressed, LV_EVENT_SHORT_CLICKED, ctx); } +// Runs with the LVGL lock already held, possibly on another app's thread - see +// WindowDestroyWidgetsFn's warnings. Must stay lock-free: only nulls pointers. +void destroyWidgets(void* userData) { + auto* ctx = static_cast(userData); + ctx->ssid_textarea = nullptr; + ctx->ssid_error = nullptr; + ctx->password_textarea = nullptr; + ctx->password_error = nullptr; + ctx->connect_button = nullptr; + ctx->remember_switch = nullptr; + ctx->connecting_spinner = nullptr; + ctx->connection_error = nullptr; +} + // TODO: Standardize dialogs void createWidgets(lv_obj_t* parent, void* userData) { auto* ctx = static_cast(userData); @@ -305,7 +324,7 @@ int32_t appMain(uint32_t appInstanceId, int argc, char* argv[]) { onWifiEvent(&ctx, event); }); - WindowId window = window_manager_create(appInstanceId, createWidgets, &ctx); + WindowId window = window_manager_create_ext(appInstanceId, createWidgets, destroyWidgets, &ctx); bool shouldClose = false; while (!shouldClose) {