Refactor RootLayout and UIHandler for improved structure and functionality

- Updated RootLayout to manage layout initialization and deinitialization more effectively.
- Removed unnecessary dependencies and streamlined event handling for keyboard events.
- Enhanced UIHandler to utilize shared pointers for app descriptors, improving memory management.
- Added methods for showing and hiding navigation elements in RootLayout.
- Introduced textarea widget with instant response by disabling animations.
- Improved error handling and logging throughout the UI components.

.clang-tidy

@@ -0,0 +1 @@
+Checks: '-clang-diagnostic-builtin-macro-redefined'

.clangd

@@ -0,0 +1,2 @@
+CompileFlags:
+    Remove: [-f*, -m*]

.devcontainer/Dockerfile

@@ -0,0 +1,13 @@
+ARG DOCKER_TAG=latest
+FROM espressif/idf:${DOCKER_TAG}
+
+ENV LC_ALL=C.UTF-8
+ENV LANG=C.UTF-8
+
+RUN apt-get update -y && apt-get install udev -y
+
+RUN echo "source /opt/esp/idf/export.sh > /dev/null 2>&1" >> ~/.bashrc
+
+ENTRYPOINT [ "/opt/esp/entrypoint.sh" ]
+
+CMD ["/bin/bash", "-c"]

.devcontainer/devcontainer.json

@@ -0,0 +1,30 @@
+{
+	"name": "ESP-IDF QEMU",
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"terminal.integrated.defaultProfile.linux": "bash",
+				"idf.espIdfPath": "/opt/esp/idf",
+				"idf.toolsPath": "/opt/esp",
+				"idf.gitPath": "/usr/bin/git"
+			},
+			"extensions": [
+				"espressif.esp-idf-extension",
+				"espressif.esp-idf-web",
+				"ms-vscode.cpptools",
+				"streetsidesoftware.code-spell-checker",
+				"mhutchie.git-graph",
+				"oderwat.indent-rainbow",
+				"SirTori.indenticator",
+				"christian-kohler.path-intellisense",
+				"esbenp.prettier-vscode",
+				"redhat.vscode-yaml"
+
+			]
+		}
+	},
+	"runArgs": ["--privileged"]
+}

.gitignore

@@ -0,0 +1,90 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Directory metadata
+.directory
+
+# Temporary files
+*~
+*.swp
+*.swo
+*.bak
+*.tmp
+
+# Log files
+*.log
+
+# Build artifacts and directories
+**/build/
+build/
+*.o
+*.a
+*.out
+*.exe # For any host-side utilities compiled on Windows
+
+# ESP-IDF specific build outputs
+*.bin
+*.elf
+*.map
+flasher_args.json # Generated in build directory
+sdkconfig.old
+sdkconfig
+
+# ESP-IDF dependencies
+# For older versions or manual component management
+/components/.idf/
+**/components/.idf/
+# For modern ESP-IDF component manager
+managed_components/
+# If ESP-IDF tools are installed/referenced locally to the project
+.espressif/
+
+# CMake generated files
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+install_manifest.txt
+CTestTestfile.cmake
+
+# Python environment files
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+*.egg-info/
+dist/
+
+# Virtual environment folders
+venv/
+.venv/
+env/
+
+# Language Servers
+.clangd/
+.ccls-cache/
+compile_commands.json
+
+# Windows specific
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# User-specific configuration files
+*.user
+*.workspace # General workspace files, can be from various tools
+*.suo       # Visual Studio Solution User Options
+*.sln.docstates # Visual Studio
+
+# cache files
+.cache/
+
+# vscode settings
+.vscode/
+
+# sample code
+sample-code/
+
+.env
+*.env

CMakeLists.txt

@@ -0,0 +1,43 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+# target_compile_options(${COMPONENT_LIB} PRIVATE -std=c++23)
+
+# Define the path to your .env file
+set(ENV_FILE "${CMAKE_SOURCE_DIR}/.env")
+
+# Check if the .env file exists
+if(EXISTS ${ENV_FILE})
+    # Read the .env file line by line
+    file(STRINGS ${ENV_FILE} ENV_VARS)
+
+    foreach(VAR ${ENV_VARS})
+        # Use regex to extract the key and value
+        if (VAR MATCHES "([^=]+)=(.*)")
+            set(ENV{${CMAKE_MATCH_1}} ${CMAKE_MATCH_2})
+            message(STATUS "Loaded environment variable from .env: ${CMAKE_MATCH_1}")
+        endif()
+    endforeach()
+else()
+    message(STATUS ".env file not found at ${ENV_FILE}")
+endif()
+
+# If build-time WiFi environment variables were loaded above, expose them
+# as compile-time definitions so C++ can use them.
+if(DEFINED ENV{WIFI_SSID})
+    add_compile_definitions(BUILD_WIFI_SSID="$ENV{WIFI_SSID}")
+    message(STATUS "Added BUILD_WIFI_SSID compile definition")
+else()
+    message(STATUS "WIFI_SSID not defined; skipping BUILD_WIFI_SSID compile definition")
+endif()
+if(DEFINED ENV{WIFI_PASSWORD})
+    add_compile_definitions(BUILD_WIFI_PASSWORD="$ENV{WIFI_PASSWORD}")
+    message(STATUS "Added BUILD_WIFI_PASSWORD compile definition")
+else()
+    message(STATUS "WIFI_PASSWORD not defined; skipping BUILD_WIFI_PASSWORD compile definition")
+endif()
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(ink-board)

assets/mtr_line_station.json

@@ -0,0 +1,556 @@
+{
+  "AEL": {
+    "name": "機場快綫",
+    "code": "AEL",
+    "line_color": "#00888A",
+    "stations": [
+      {
+        "code": "HOK",
+        "name": "香港"
+      },
+      {
+        "code": "KOW",
+        "name": "九龍"
+      },
+      {
+        "code": "TSY",
+        "name": "青衣"
+      },
+      {
+        "code": "AIR",
+        "name": "機場"
+      },
+      {
+        "code": "AWE",
+        "name": "博覽館"
+      }
+    ]
+  },
+  "TCL": {
+    "name": "東涌綫",
+    "code": "TCL",
+    "line_color": "#F38B00",
+    "stations": [
+      {
+        "code": "HOK",
+        "name": "香港"
+      },
+      {
+        "code": "KOW",
+        "name": "九龍"
+      },
+      {
+        "code": "OLY",
+        "name": "奧運"
+      },
+      {
+        "code": "NAC",
+        "name": "南昌"
+      },
+      {
+        "code": "LAK",
+        "name": "荔景"
+      },
+      {
+        "code": "TSY",
+        "name": "青衣"
+      },
+      {
+        "code": "SUN",
+        "name": "欣澳"
+      },
+      {
+        "code": "TUC",
+        "name": "東涌"
+      }
+    ]
+  },
+  "TML": {
+    "name": "屯馬綫",
+    "code": "TML",
+    "line_color": "#9A3820",
+    "stations": [
+      {
+        "code": "WKS",
+        "name": "烏溪沙"
+      },
+      {
+        "code": "MOS",
+        "name": "馬鞍山"
+      },
+      {
+        "code": "HEO",
+        "name": "恆安"
+      },
+      {
+        "code": "TSH",
+        "name": "大水坑"
+      },
+      {
+        "code": "SHM",
+        "name": "石門"
+      },
+      {
+        "code": "CIO",
+        "name": "第一城"
+      },
+      {
+        "code": "STW",
+        "name": "沙田圍"
+      },
+      {
+        "code": "CKT",
+        "name": "車公廟"
+      },
+      {
+        "code": "TAW",
+        "name": "大圍"
+      },
+      {
+        "code": "HIK",
+        "name": "顯徑"
+      },
+      {
+        "code": "DIH",
+        "name": "鑽石山"
+      },
+      {
+        "code": "KAT",
+        "name": "啟德"
+      },
+      {
+        "code": "SUW",
+        "name": "宋皇臺"
+      },
+      {
+        "code": "TKW",
+        "name": "土瓜灣"
+      },
+      {
+        "code": "HOM",
+        "name": "何文田"
+      },
+      {
+        "code": "HUH",
+        "name": "紅磡"
+      },
+      {
+        "code": "ETS",
+        "name": "尖東"
+      },
+      {
+        "code": "AUS",
+        "name": "柯士甸"
+      },
+      {
+        "code": "NAC",
+        "name": "南昌"
+      },
+      {
+        "code": "MEF",
+        "name": "美孚"
+      },
+      {
+        "code": "TWW",
+        "name": "荃灣西"
+      },
+      {
+        "code": "KSR",
+        "name": "錦上路"
+      },
+      {
+        "code": "YUL",
+        "name": "元朗"
+      },
+      {
+        "code": "LOP",
+        "name": "朗屏"
+      },
+      {
+        "code": "TIS",
+        "name": "天水圍"
+      },
+      {
+        "code": "SIH",
+        "name": "兆康"
+      },
+      {
+        "code": "TUM",
+        "name": "屯門"
+      }
+    ]
+  },
+  "TKL": {
+    "name": "將軍澳綫",
+    "code": "TKL",
+    "line_color": "#A35EB5",
+    "stations": [
+      {
+        "code": "NOP",
+        "name": "北角"
+      },
+      {
+        "code": "QUB",
+        "name": "鰂魚涌"
+      },
+      {
+        "code": "YAT",
+        "name": "油塘"
+      },
+      {
+        "code": "TIK",
+        "name": "調景嶺"
+      },
+      {
+        "code": "TKO",
+        "name": "將軍澳"
+      },
+      {
+        "code": "LHP",
+        "name": "康城"
+      },
+      {
+        "code": "HAH",
+        "name": "坑口"
+      },
+      {
+        "code": "POA",
+        "name": "寶琳"
+      }
+    ]
+  },
+  "EAL": {
+    "name": "東鐵綫",
+    "code": "EAL",
+    "line_color": "#53B7E8",
+    "stations": [
+      {
+        "code": "ADM",
+        "name": "金鐘"
+      },
+      {
+        "code": "EXC",
+        "name": "會展"
+      },
+      {
+        "code": "HUH",
+        "name": "紅磡"
+      },
+      {
+        "code": "MKK",
+        "name": "旺角東"
+      },
+      {
+        "code": "KOT",
+        "name": "九龍塘"
+      },
+      {
+        "code": "TAW",
+        "name": "大圍"
+      },
+      {
+        "code": "SHT",
+        "name": "沙田"
+      },
+      {
+        "code": "FOT",
+        "name": "火炭"
+      },
+      {
+        "code": "RAC",
+        "name": "馬場"
+      },
+      {
+        "code": "UNI",
+        "name": "大學"
+      },
+      {
+        "code": "TAP",
+        "name": "大埔墟"
+      },
+      {
+        "code": "TWO",
+        "name": "太和"
+      },
+      {
+        "code": "FAN",
+        "name": "粉嶺"
+      },
+      {
+        "code": "SHS",
+        "name": "上水"
+      },
+      {
+        "code": "LOW",
+        "name": "羅湖"
+      },
+      {
+        "code": "LMC",
+        "name": "落馬洲"
+      }
+    ]
+  },
+  "SIL": {
+    "name": "南港島綫",
+    "code": "SIL",
+    "line_color": "#B6BD00",
+    "stations": [
+      {
+        "code": "ADM",
+        "name": "金鐘"
+      },
+      {
+        "code": "OCP",
+        "name": "海洋公園"
+      },
+      {
+        "code": "WCH",
+        "name": "黃竹坑"
+      },
+      {
+        "code": "LET",
+        "name": "利東"
+      },
+      {
+        "code": "SOH",
+        "name": "海怡半島"
+      }
+    ]
+  },
+  "TWL": {
+    "name": "荃灣綫",
+    "code": "TWL",
+    "line_color": "#E2231A",
+    "stations": [
+      {
+        "code": "CEN",
+        "name": "中環"
+      },
+      {
+        "code": "ADM",
+        "name": "金鐘"
+      },
+      {
+        "code": "TST",
+        "name": "尖沙咀"
+      },
+      {
+        "code": "JOR",
+        "name": "佐敦"
+      },
+      {
+        "code": "YMT",
+        "name": "油麻地"
+      },
+      {
+        "code": "MOK",
+        "name": "旺角"
+      },
+      {
+        "code": "PRE",
+        "name": "太子"
+      },
+      {
+        "code": "SSP",
+        "name": "深水埗"
+      },
+      {
+        "code": "CSW",
+        "name": "長沙灣"
+      },
+      {
+        "code": "LCK",
+        "name": "荔枝角"
+      },
+      {
+        "code": "MEF",
+        "name": "美孚"
+      },
+      {
+        "code": "LAK",
+        "name": "荔景"
+      },
+      {
+        "code": "KWF",
+        "name": "葵芳"
+      },
+      {
+        "code": "KWH",
+        "name": "葵興"
+      },
+      {
+        "code": "TWH",
+        "name": "大窩口"
+      },
+      {
+        "code": "TSW",
+        "name": "荃灣"
+      }
+    ]
+  },
+  "ISL": {
+    "name": "港島綫",
+    "code": "ISL",
+    "line_color": "#007DC5",
+    "stations": [
+      {
+        "code": "KET",
+        "name": "堅尼地城"
+      },
+      {
+        "code": "HKU",
+        "name": "香港大學"
+      },
+      {
+        "code": "SYP",
+        "name": "西營盤"
+      },
+      {
+        "code": "SHW",
+        "name": "上環"
+      },
+      {
+        "code": "CEN",
+        "name": "中環"
+      },
+      {
+        "code": "ADM",
+        "name": "金鐘"
+      },
+      {
+        "code": "WAC",
+        "name": "灣仔"
+      },
+      {
+        "code": "CAB",
+        "name": "銅鑼灣"
+      },
+      {
+        "code": "TIH",
+        "name": "天后"
+      },
+      {
+        "code": "FOH",
+        "name": "炮台山"
+      },
+      {
+        "code": "NOP",
+        "name": "北角"
+      },
+      {
+        "code": "QUB",
+        "name": "鰂魚涌"
+      },
+      {
+        "code": "TAK",
+        "name": "太古"
+      },
+      {
+        "code": "SWH",
+        "name": "西灣河"
+      },
+      {
+        "code": "SKW",
+        "name": "筲箕灣"
+      },
+      {
+        "code": "HFC",
+        "name": "杏花邨"
+      },
+      {
+        "code": "CHW",
+        "name": "柴灣"
+      }
+    ]
+  },
+  "KTL": {
+    "name": "觀塘綫",
+    "code": "KTL",
+    "line_color": "#00AB4E",
+    "stations": [
+      {
+        "code": "WHA",
+        "name": "黃埔"
+      },
+      {
+        "code": "HOM",
+        "name": "何文田"
+      },
+      {
+        "code": "YMT",
+        "name": "油麻地"
+      },
+      {
+        "code": "MOK",
+        "name": "旺角"
+      },
+      {
+        "code": "PRE",
+        "name": "太子"
+      },
+      {
+        "code": "SKM",
+        "name": "石硤尾"
+      },
+      {
+        "code": "KOT",
+        "name": "九龍塘"
+      },
+      {
+        "code": "LOF",
+        "name": "樂富"
+      },
+      {
+        "code": "WTS",
+        "name": "黃大仙"
+      },
+      {
+        "code": "DIH",
+        "name": "鑽石山"
+      },
+      {
+        "code": "CHH",
+        "name": "彩虹"
+      },
+      {
+        "code": "KOB",
+        "name": "九龍灣"
+      },
+      {
+        "code": "NTK",
+        "name": "牛頭角"
+      },
+      {
+        "code": "KWT",
+        "name": "觀塘"
+      },
+      {
+        "code": "LAT",
+        "name": "藍田"
+      },
+      {
+        "code": "YAT",
+        "name": "油塘"
+      },
+      {
+        "code": "TIK",
+        "name": "調景嶺"
+      }
+    ]
+  },
+  "DRL": {
+    "name": "迪士尼綫",
+    "code": "DRL",
+    "line_color": "#F550A6",
+    "stations": [
+      {
+        "code": "SUN",
+        "name": "欣澳"
+      },
+      {
+        "code": "DIS",
+        "name": "迪士尼"
+      }
+    ]
+  }
+}

dependencies.lock

@@ -0,0 +1,80 @@
+dependencies:
+  espressif/cjson:
+    component_hash: 9372811fb197926f522c467627cf4a8e72b681e0366e17879631da801103aef3
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.7.19
+  espressif/esp_lcd_touch:
+    component_hash: 3f85a7d95af876f1a6ecca8eb90a81614890d0f03a038390804e5a77e2caf862
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=4.4.2'
+    source:
+      registry_url: https://components.espressif.com
+      type: service
+    version: 1.2.1
+  espressif/esp_lcd_touch_gt911:
+    component_hash: be02e243d18b9a661bc13b0d22c0a5cfa3f708cf04d6eb059772276c8c8a4d76
+    dependencies:
+    - name: espressif/esp_lcd_touch
+      registry_url: https://components.espressif.com
+      require: public
+      version: ^1.2.0
+    - name: idf
+      require: private
+      version: '>=4.4.2'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.2.0~1
+  espressif/esp_lvgl_port:
+    component_hash: f872401524cb645ee6ff1c9242d44fb4ddcfd4d37d7be8b9ed3f4e85a404efcd
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.1'
+    - name: lvgl/lvgl
+      registry_url: https://components.espressif.com
+      require: public
+      version: '>=8,<10'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 2.7.0
+  idf:
+    source:
+      type: idf
+    version: 5.5.2
+  joltwallet/littlefs:
+    component_hash: 1808d73e99168f6f3c26dd31799a248484762b3a320ec4962dec11a145f4277f
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.20.3
+  lvgl/lvgl:
+    component_hash: 17e68bfd21f0edf4c3ee838e2273da840bf3930e5dbc3bfa6c1190c3aed41f9f
+    dependencies: []
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 9.4.0
+direct_dependencies:
+- espressif/cjson
+- espressif/esp_lcd_touch_gt911
+- espressif/esp_lvgl_port
+- idf
+- joltwallet/littlefs
+- lvgl/lvgl
+manifest_hash: 534b6804ed0fcb2390bfe237db938fe86c9ba00561b361035a89dde4847214f2
+target: esp32s3
+version: 2.0.0

diagram.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "author": "GW_ MC",
+  "editor": "wokwi",
+  "parts": [
+    {
+      "type": "board-esp32-s3-devkitc-1",
+      "id": "esp",
+      "top": 0,
+      "left": 0,
+      "attrs": {}
+    }
+  ],
+  "connections": [
+    [
+      "esp:TX",
+      "$serialMonitor:RX",
+      "",
+      []
+    ],
+    [
+      "esp:RX",
+      "$serialMonitor:TX",
+      "",
+      []
+    ]
+  ],
+  "dependencies": {}
+}

main/CMakeLists.txt

@@ -0,0 +1,41 @@
+set(requires esp-tls spi_flash nvs_flash esp_event esp_netif esp_http_client esp_wifi esp_psram esp_lvgl_port)
+file(GLOB SRCS "main.cpp" "*.cpp" "*.c" "**/*.cpp" "**/*.cpp" "ui/**/*.cpp" "ui/**/*.c" "external/**/*.cpp" "external/**/*.c")
+
+
+# Path to the source JSON in this component
+set(ASSETS_SRC_DIR ${CMAKE_CURRENT_LIST_DIR}/../assets)
+set(ASSETS_BINARY_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/assets)
+set(MTR_JSON_SRC ${ASSETS_SRC_DIR}/MTR_LINE_STATION.json)
+set(MTR_JSON_HEADER ${ASSETS_BINARY_OUTPUT_DIR}/MTR_LINE_STATION.h)
+set(CUSTOM_CMAKE_MODULES_DIR ${CMAKE_CURRENT_LIST_DIR}/cmake)
+
+## Generate a minified header at configure time using Python
+find_package(Python3 COMPONENTS Interpreter)
+file(MAKE_DIRECTORY ${ASSETS_BINARY_OUTPUT_DIR})
+if (Python3_Interpreter_FOUND)
+    execute_process(
+        COMMAND ${Python3_EXECUTABLE} -c "import json,sys,io; sys.stdout.write(json.dumps(json.load(open(sys.argv[1], 'r', encoding='utf-8')),separators=(',',':')))"
+        "${MTR_JSON_SRC}"
+        RESULT_VARIABLE _mtr_json_minify_result
+        OUTPUT_VARIABLE MTR_JSON_MINIFIED
+        ERROR_VARIABLE _mtr_json_minify_error
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    if (_mtr_json_minify_result)
+        message(WARNING "Python minify failed (code=${_mtr_json_minify_result}): ${_mtr_json_minify_error}\nEmbedding original ${MTR_JSON_SRC} instead.")
+        file(READ ${MTR_JSON_SRC} MTR_JSON_MINIFIED)
+    elseif (NOT MTR_JSON_MINIFIED)
+        message(WARNING "Python minified output empty; embedding original ${MTR_JSON_SRC} instead.")
+        file(READ ${MTR_JSON_SRC} MTR_JSON_MINIFIED)
+    endif()
+else()
+    message(WARNING "Python3 not found; embedding original JSON without minification.")
+    file(READ ${MTR_JSON_SRC} MTR_JSON_MINIFIED)
+endif()
+
+file(WRITE ${MTR_JSON_HEADER} "#pragma once\nstatic const char MTR_LINE_STATION_JSON[] = R\"json(${MTR_JSON_MINIFIED})json\";\n")
+
+
+idf_component_register(SRCS ${SRCS}
+                        PRIV_REQUIRES ${requires}
+                        INCLUDE_DIRS "." "${CMAKE_CURRENT_BINARY_DIR}" "display" "network" "ui" "ui/apps" "io" "common" "external")

main/Kconfig.projbuild

@@ -0,0 +1,9 @@
+menu "ink-board Configuration"
+
+    config PARTIAL_REFRESH_LIMIT
+        int "Partial Refresh Limit"
+        default 20
+        range 5 100
+        help "Number of partial updates before full refresh"
+
+endmenu

main/cmake/write_json_header.cmake

@@ -0,0 +1,20 @@
+if(NOT DEFINED INPUT)
+  message(FATAL_ERROR "write_json_header.cmake: INPUT not defined")
+endif()
+if(NOT DEFINED OUTPUT)
+  message(FATAL_ERROR "write_json_header.cmake: OUTPUT not defined")
+endif()
+
+find_package(Python3 COMPONENTS Interpreter REQUIRED)
+
+execute_process(
+  COMMAND ${Python3_EXECUTABLE} -c "import json,sys;print(json.dumps(json.load(open(sys.argv[1])),separators=(', ',':')) )" ${INPUT}
+  OUTPUT_VARIABLE MINIFIED_JSON
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+
+if(NOT MINIFIED_JSON)
+  message(FATAL_ERROR "write_json_header.cmake: failed to minify ${INPUT}")
+endif()
+
+file(WRITE ${OUTPUT} "#pragma once\nstatic const char MTR_LINE_STATION_JSON[] = R\"json(${MINIFIED_JSON})json\";\n")

main/common/constants.h

@@ -0,0 +1,17 @@
+#pragma once
+// 800x480 = 384,000 pixels
+
+#define EINK_WIDTH    800
+#define EINK_HEIGHT   480
+
+#define CORE_0 0
+#define CORE_1 1
+
+#define SYSTEM_SHUTDOWN_BIT     (1 << 0)
+#define SYSTEM_RESTART_BIT      (1 << 1)
+#define SYSTEM_START_BIT        (1 << 2)
+//
+#define DISPLAY_READY_BIT       (1 << 1)
+#define TOUCH_CALIBRATED_BIT    (1 << 2)
+#define STORAGE_READY_BIT       (1 << 3)
+#define NETWORK_READY_BIT       (1 << 4)

main/common/queue_defs.h

@@ -0,0 +1,31 @@
+#pragma once
+#include <indev/lv_indev.h>
+
+typedef enum {
+  CMD_DISPLAY_UPDATE,
+  CMD_SAVE_DATA,
+  CMD_LOAD_DATA,
+  CMD_REFRESH_DISPLAY,
+  CMD_SYSTEM_STATUS,
+} cmd_type_t;
+
+typedef struct {
+  cmd_type_t type;
+  uint32_t id;
+  void* data;
+  size_t len;
+  QueueHandle_t reply_to;  // NULL if one-way
+} async_cmd_t;
+
+extern QueueHandle_t command_queue;
+
+typedef struct {
+  uint16_t x, y;
+  lv_indev_state_t state;  // LV_INDEV_STATE_PR/REL
+  uint32_t timestamp;
+  uint8_t gesture;         // TAP, SWIPE, LONG_PRESS
+} touch_event_t;
+
+extern QueueHandle_t touch_queue;
+
+extern EventGroupHandle_t system_event_group;

main/common/semaphore_guard.h

@@ -0,0 +1,49 @@
+#pragma once
+#include "freertos/semphr.h"
+#include "freertos/portmacro.h"
+#include "esp_log.h"
+
+struct SemaphoreGuard {
+public:
+
+  SemaphoreGuard(SemaphoreHandle_t semaphore) : semaphore(semaphore) { }
+
+  portBASE_TYPE take(TickType_t ticks_to_wait = portMAX_DELAY) {
+    if (this->semaphore == nullptr) {
+      ESP_LOGE("SemaphoreGuard", "Attempted to take a null semaphore");
+      return pdFALSE;
+    }
+    portBASE_TYPE result = xSemaphoreTake(this->semaphore, ticks_to_wait);
+    taken = (result == pdTRUE);
+    return result;
+  }
+
+  ~SemaphoreGuard() {
+    if (taken) {
+      xSemaphoreGive(this->semaphore);
+    }
+  }
+
+  // allow move semantics
+  SemaphoreGuard(SemaphoreGuard&& other) noexcept
+    : semaphore(other.semaphore), taken(other.taken) {
+    other.taken = false;
+  }
+  SemaphoreGuard& operator=(SemaphoreGuard&& other) noexcept {
+    if (this != &other) {
+      // move from other
+      taken = other.taken;
+      other.taken = false;
+      semaphore = other.semaphore;
+      other.semaphore = nullptr;
+    }
+    return *this;
+  }
+
+private:
+  // prevent copying
+  SemaphoreGuard(const SemaphoreGuard&) = delete;
+  SemaphoreGuard& operator=(const SemaphoreGuard&) = delete;
+  SemaphoreHandle_t semaphore = nullptr;
+  bool taken = false;
+};

main/display/constants.h

@@ -0,0 +1,14 @@
+#pragma once
+#include "driver/spi_master.h"
+#include "driver/gpio.h"
+
+#define PIN_TOUCH_IRQ GPIO_NUM_4
+#define PIN_TOUCH_SDA GPIO_NUM_5
+#define PIN_TOUCH_SCL GPIO_NUM_6
+#define PIN_BUSY      GPIO_NUM_7
+#define PIN_RST       GPIO_NUM_8
+#define PIN_DC        GPIO_NUM_9
+#define PIN_CS        GPIO_NUM_10
+#define PIN_MOSI      GPIO_NUM_11
+#define PIN_SCK       GPIO_NUM_12
+#define PIN_TOUCH_RST GPIO_NUM_13

main/display/eink_display_handler.cpp

@@ -0,0 +1,789 @@
+#include "display/eink_display_handler.h"
+#include "display/constants.h"
+#include "common/constants.h"
+#include "esp_lcd_touch_gt911.h"
+#include "esp_log.h"
+#include <driver/i2c.h>
+#include <vector>
+#include "common/semaphore_guard.h"
+
+#define TAG "EInkDisplayHandler"
+#define DISPLAY_BUFFER_SIZE (EINK_HEIGHT* EINK_WIDTH) / 8 // 1 bit per pixels
+#define MINIMUM_PIN_SETUP_DELAY_MS 10
+#define MINIMUM_POWER_ON_DELAY_MS 100
+#define PARTIAL_REFRESH_THRESHOLD 5  // Full refresh every N partial refreshes
+
+static uint8_t* DRAW_BUFFER; // 1 bit per pixel
+static uint8_t* OLD_DRAW_BUFFER; // 1 bit per pixel
+static uint8_t* black_data;
+static uint8_t* white_data;
+
+EInkDisplayHandler::EInkDisplayHandler() {
+  black_data = static_cast<uint8_t*>(heap_caps_malloc(DISPLAY_BUFFER_SIZE, MALLOC_CAP_SPIRAM));
+  white_data = static_cast<uint8_t*>(heap_caps_malloc(DISPLAY_BUFFER_SIZE, MALLOC_CAP_SPIRAM));
+  DRAW_BUFFER = static_cast<uint8_t*>(heap_caps_malloc(DISPLAY_BUFFER_SIZE, MALLOC_CAP_SPIRAM));
+  OLD_DRAW_BUFFER = static_cast<uint8_t*>(heap_caps_malloc(DISPLAY_BUFFER_SIZE, MALLOC_CAP_SPIRAM));
+  memset(black_data, 0xFF, DISPLAY_BUFFER_SIZE); // eink uses 1 for black
+  memset(white_data, 0x00, DISPLAY_BUFFER_SIZE);
+  memset(DRAW_BUFFER, 0x00, DISPLAY_BUFFER_SIZE); // start with all white (0 = white in e-ink)
+  memset(OLD_DRAW_BUFFER, 0x00, DISPLAY_BUFFER_SIZE); // start with all white (0 = white in e-ink)
+  draw_buffer_ = DRAW_BUFFER;
+  old_buffer_ = OLD_DRAW_BUFFER;
+
+  refresh_mutex_ = xSemaphoreCreateMutex();
+  if (refresh_mutex_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create refresh mutex");
+  }
+}
+
+EInkDisplayHandler::~EInkDisplayHandler() {
+  if (refresh_mutex_ != nullptr) {
+    vSemaphoreDelete(refresh_mutex_);
+  }
+  if (tp_handle_ != nullptr) {
+    esp_lcd_touch_del(tp_handle_);
+  }
+  if (tp_io_handle_ != nullptr) {
+    esp_lcd_panel_io_del(tp_io_handle_);
+  }
+  if (black_data != nullptr) {
+    heap_caps_free(black_data);
+  }
+  if (white_data != nullptr) {
+    heap_caps_free(white_data);
+  }
+  if (DRAW_BUFFER != nullptr) {
+    heap_caps_free(DRAW_BUFFER);
+  }
+  if (OLD_DRAW_BUFFER != nullptr) {
+    heap_caps_free(OLD_DRAW_BUFFER);
+  }
+}
+
+esp_err_t EInkDisplayHandler::deep_sleep_display(void) {
+  ESP_LOGI(TAG, "Putting display into deep sleep mode...");
+  if (is_deep_sleep_) {
+    ESP_LOGI(TAG, "Display is already in deep sleep mode");
+    return ESP_OK;
+  }
+  {
+    esp_err_t err = ESP_OK;
+    TransactionGuard transaction_guard(this->epd_handler_);
+    err = transaction_guard.begin(pdMS_TO_TICKS(5000));
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to begin transaction for deep sleep: %s", esp_err_to_name(err));
+      return err;
+    }
+    epd_handler_.wait_for_idle();
+
+    err = epd_handler_.epd_write_cmd(0x02, transaction_guard.transaction_id()); // power off
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send power off command: %s", esp_err_to_name(err));
+      return err;
+    }
+    epd_handler_.wait_for_idle();
+    err = epd_handler_.epd_write_cmd(0x07, transaction_guard.transaction_id());   //deep sleep
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send deep sleep command: %s", esp_err_to_name(err));
+      return err;
+    }
+    err = epd_handler_.epd_write_data(0xA5, transaction_guard.transaction_id());
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send deep sleep data: %s", esp_err_to_name(err));
+      return err;
+    }
+    is_deep_sleep_ = true;
+    return err;
+  }
+}
+
+esp_err_t EInkDisplayHandler::refresh_display() {
+  esp_err_t err = ESP_OK;
+
+
+  if (is_deep_sleep_) {
+
+    err = full_write(draw_buffer_, true);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Full write failed during refresh_display: %s", esp_err_to_name(err));
+      return err;
+    }
+  } else {
+    // refresh does not correctly work after recovering from deep sleep due to sram reset
+    {
+      ESP_LOGI(TAG, "Waiting for display to be idle...");
+      TransactionGuard transaction_guard(this->epd_handler_);
+      err = transaction_guard.begin(pdMS_TO_TICKS(10000));
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to begin transaction for display refresh: %s", esp_err_to_name(err));
+        return err;
+      }
+      if (is_deep_sleep_) {
+        epd_init_internal_(transaction_guard.transaction_id());
+      }
+
+      epd_handler_.wait_for_idle();
+      ESP_LOGI(TAG, "Starting display refresh...");
+      err = epd_handler_.epd_write_cmd(0x92, transaction_guard.transaction_id()); // enter normal mode
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to enter normal mode: %s", esp_err_to_name(err));
+        return err;
+      }
+      err = epd_handler_.epd_write_cmd(0x12, transaction_guard.transaction_id()); // display refresh
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send display refresh command: %s", esp_err_to_name(err));
+        return err;
+      }
+      vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS)); // at least 200us delay
+      epd_handler_.wait_for_idle();
+    }
+  }
+
+  {
+    SemaphoreGuard guard(refresh_mutex_);
+    if (guard.take(pdMS_TO_TICKS(5000)) != pdTRUE) {
+      ESP_LOGE(TAG, "Refresh mutex timeout in refresh_display");
+      return ESP_ERR_TIMEOUT;
+    }
+    partial_refresh_count_ = 0;
+    force_full_refresh_ = false;
+  }
+
+  ESP_LOGI(TAG, "Refresh complete");
+  return ESP_OK;
+}
+
+esp_err_t EInkDisplayHandler::full_write(const uint8_t* framebuffer, const bool white_basemap) {
+  ESP_LOGI(TAG, "Starting full refresh (3 seconds)...");
+  esp_err_t err = ESP_OK;
+
+
+  {
+    TransactionGuard transaction_guard(this->epd_handler_);
+    err = transaction_guard.begin(pdMS_TO_TICKS(10000));
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to begin transaction for full refresh: %s", esp_err_to_name(err));
+      return err;
+    }
+    if (is_deep_sleep_) {
+      epd_init_internal_(transaction_guard.transaction_id());
+    }
+
+    write_to_buffer_(framebuffer, RefreshArea { 0, 0, DISPLAY_WIDTH - 1,  DISPLAY_HEIGHT - 1 });
+
+    epd_handler_.wait_for_idle();
+    // Step 0: Enter normal mode
+    err = epd_handler_.epd_write_cmd(0x92, transaction_guard.transaction_id()); // enter normal mode
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to enter normal mode: %s", esp_err_to_name(err));
+      return err;
+    }
+    // Step 1: Write old data (0x10) - Arduino uses 0xFF (all white) for base map
+    {
+      err = epd_handler_.epd_write_cmd(0x10, transaction_guard.transaction_id());
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send old data command: %s", esp_err_to_name(err));
+        return err;
+      }
+      err = epd_handler_.transfer_spi_data(white_basemap ? black_data : white_data, DISPLAY_BUFFER_SIZE, transaction_guard.transaction_id()); // Send all white data (0xFF)
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send all white data for old data: %s", esp_err_to_name(err));
+        return err;
+      }
+    }
+
+    // Step 2: Write new data (0x13)
+    {
+      err = epd_handler_.epd_write_cmd(0x13, transaction_guard.transaction_id());
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send new data command: %s", esp_err_to_name(err));
+        return err;
+      }
+
+      err = epd_handler_.transfer_spi_data(draw_buffer_, DISPLAY_BUFFER_SIZE, transaction_guard.transaction_id()); // Send new framebuffer data
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send framebuffer data for new data: %s", esp_err_to_name(err));
+        return err;
+      }
+    }
+    // Step 3: Trigger display refresh (DRF)
+    err = epd_handler_.epd_write_cmd(0x12, transaction_guard.transaction_id());
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send display refresh command: %s", esp_err_to_name(err));
+      return err;
+    }
+
+    vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS)); // at least 200us delay
+    ESP_LOGI(TAG, "Display refresh triggered, BUSY pin: %d", gpio_get_level(PIN_BUSY));
+
+    // Wait for refresh to complete
+    epd_handler_.wait_for_idle();
+  }
+
+  err = deep_sleep_display();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to enter deep sleep after full refresh: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  refresh_area_.reset();
+  memcpy(old_buffer_, draw_buffer_, DISPLAY_BUFFER_SIZE);
+
+  ESP_LOGI(TAG, "Full refresh complete");
+  return ESP_OK;
+}
+
+// TODO: Partial refresh is inverted in color
+esp_err_t EInkDisplayHandler::partial_refresh(const uint8_t* incoming_partial_framebuffer, const RefreshArea& incoming_area, const bool is_last_partial_update) {
+  ESP_LOGI(TAG, "Starting partial refresh (0.3 seconds)...");
+  esp_err_t err = ESP_OK;
+
+  write_to_buffer_(incoming_partial_framebuffer, incoming_area);
+
+  // Always expand refresh_area_ to include incoming_area
+  refresh_area_.expand_to_include(incoming_area);
+
+  if (!is_last_partial_update) {
+    ESP_LOGI(TAG, "Partial refresh skipped (not last partial update)");
+    return ESP_OK;
+  }
+
+  {
+    TransactionGuard transaction_guard(this->epd_handler_);
+    err = transaction_guard.begin(pdMS_TO_TICKS(5000));
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to begin transaction for partial refresh: %s", esp_err_to_name(err));
+      return err;
+    }
+    // Wake display from deep sleep INSIDE the transaction to prevent race conditions
+    if (is_deep_sleep_) {
+      err = epd_init_internal_(transaction_guard.transaction_id());
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to initialize EPD for partial refresh: %s", esp_err_to_name(err));
+        return err;
+      }
+      err = refresh_old_buffer_(transaction_guard.transaction_id());
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to refresh old buffer during partial refresh init: %s", esp_err_to_name(err));
+        return err;
+      }
+    }
+
+
+    RefreshArea area = refresh_area_;
+    if (area.x1 % 8 != 0 || area.x2 % 8 != 7) {
+      ESP_LOGE(TAG, "Partial refresh area x1 and x2 must be byte-aligned (x1 %% 8 == 0 and x2 %% 8 == 7)");
+      ESP_LOGI(TAG, "Given area: x1=%d, x2=%d", area.x1, area.x2);
+      return ESP_ERR_INVALID_ARG;
+    }
+
+    // Calculate partial buffer size based on the refresh area
+    const uint32_t area_width_bytes = (area.x2 - area.x1 + 1) / 8;
+    const uint32_t area_height = area.y2 - area.y1 + 1;
+    const size_t partial_buffer_size = area_width_bytes * area_height;
+
+    // uint8_t* partial_buffer = new uint8_t[partial_buffer_size];
+    uint8_t* partial_buffer = static_cast<uint8_t*>(heap_caps_malloc(partial_buffer_size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL));
+
+    if (partial_buffer == nullptr) {
+      ESP_LOGE(TAG, "Failed to allocate partial buffer for partial refresh");
+      return ESP_ERR_NO_MEM;
+    }
+    // Copy the relevant area from draw_buffer_ to partial_buffer
+    for (int32_t row = 0; row < area_height; ++row) {
+      uint32_t fb_y = area.y1 + row;
+      uint32_t fb_x_byte_start = area.x1 / 8;
+      uint8_t* fb_ptr = &draw_buffer_[fb_y * (DISPLAY_WIDTH / 8) + fb_x_byte_start];
+      uint8_t* dest_ptr = &partial_buffer[row * area_width_bytes];
+      memcpy(dest_ptr, fb_ptr, area_width_bytes);
+    }
+
+
+    epd_handler_.wait_for_idle();
+
+    // Step 1 VCOM setting
+    std::vector<uint8_t> vcom_data = { 0xA9, 0x07 };
+    err = epd_handler_.epd_write_cmd_with_data(0x50, vcom_data, transaction_guard.transaction_id()); // VCOM for partial refresh
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to set VCOM for partial refresh: %s", esp_err_to_name(err));
+      return err;
+    }
+    // Step 2: Enter partial refresh mode
+    err = epd_handler_.epd_write_cmd(0x91, transaction_guard.transaction_id());  // Enter partial mode
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to enter partial refresh mode: %s", esp_err_to_name(err));
+      return err;
+    }
+    // Step 3: Set partial window
+    {
+      // ------DD
+      // DDDDD000
+      // ------DD
+      // DDDDD111
+      // ------DD
+      // DDDDDDDD
+      // ------DD
+      // DDDDDDDD
+      // -------D
+
+      // area should be multiple of 8 in x direction
+      const int32_t x_bank_start = area.x1 >> 3;
+      const int32_t x_bank_end = area.x2 >> 3;
+      std::vector<uint8_t> window_data = {
+        // x start, [9:8] bit -> 6 and 7 bits of x_bank_start
+        static_cast<uint8_t>((x_bank_start >> 5) & 0x03),
+        // x start, [7:3] bit + 3 bits of 0 -> 5 bits of x_bank_start and pad 3 LSBs as 0
+        static_cast<uint8_t>((x_bank_start & 0x1F) << 3),
+        // x end, [9:8] bit
+        static_cast<uint8_t>((x_bank_end >> 5) & 0x03),
+        // x end, [7:3] bit + 3 bits of 1
+        static_cast<uint8_t>(((x_bank_end & 0x1F) << 3) | 0x07),
+        // y start, [9:8] bit
+        static_cast<uint8_t>((area.y1 >> 8) & 0x03),
+        // y start, [7:0] bit
+        static_cast<uint8_t>(area.y1 & 0xFF),
+        // y end, [9:8] bit
+        static_cast<uint8_t>((area.y2 >> 8) & 0x03),
+        // y end, [7:0] bit
+        static_cast<uint8_t>(area.y2 & 0xFF),
+        0x01  // Gates scan both inside and outside of the partial window
+      };
+      ESP_LOGI(TAG, "Setting partial window: x1=%d, y1=%d, x2=%d, y2=%d",
+        area.x1, area.y1, area.x2, area.y2);
+      ESP_LOGI(TAG, "Partial window data: %02X %02X %02X %02X %02X %02X %02X %02X",
+        window_data[0], window_data[1], window_data[2], window_data[3], window_data[4],
+        window_data[5], window_data[6], window_data[7]);
+      err = epd_handler_.epd_write_cmd_with_data(0x90, window_data, transaction_guard.transaction_id());  // Set partial window
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send set partial window command: %s", esp_err_to_name(err));
+        return err;
+      }
+    }
+
+    // Step 5: Write new data (0x13)
+    {
+      err = epd_handler_.epd_write_cmd(0x13, transaction_guard.transaction_id());
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send new data command for partial refresh: %s", esp_err_to_name(err));
+        heap_caps_free(partial_buffer);
+        return err;
+      }
+
+      // Send only the partial area data, not the full display buffer
+      ESP_LOGI(TAG, "Sending new partial buffer: %zu bytes (area: %dx%d)",
+        partial_buffer_size, area_width_bytes * 8, area_height);
+      err = epd_handler_.transfer_spi_data(partial_buffer, partial_buffer_size, transaction_guard.transaction_id(), true); // Inverted for partial refresh
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to send partial_buffer data for partial refresh: %s", esp_err_to_name(err));
+        heap_caps_free(partial_buffer);
+        return err;
+      }
+
+      memcpy(old_buffer_, draw_buffer_, DISPLAY_BUFFER_SIZE);
+    }
+
+    // Clean up partial buffer
+    heap_caps_free(partial_buffer);
+
+    // Step 6: Trigger partial display refresh (DRF)
+    // Use 0x12 (Display Update) command - same as full refresh, per sample code
+    err = epd_handler_.epd_write_cmd(0x12, transaction_guard.transaction_id());
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send display refresh command for partial refresh: %s", esp_err_to_name(err));
+      return err;
+    }
+
+    vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS)); // at least 200us delay
+
+    epd_handler_.wait_for_idle();
+    // Step 7: Exit partial mode
+    err = epd_handler_.epd_write_cmd(0x92, transaction_guard.transaction_id());
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to exit partial refresh mode: %s", esp_err_to_name(err));
+      return err;
+    }
+  }
+  ESP_LOGI(TAG, "Partial refresh complete");
+
+  err = deep_sleep_display();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to enter deep sleep after partial refresh: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  if (force_full_refresh_) {
+    ESP_LOGI(TAG, "Full refresh already requested, skipping partial refresh count increment");
+    err = refresh_display();
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to perform forced full refresh: %s", esp_err_to_name(err));
+      return err;
+    }
+    return ESP_OK;
+  }
+
+  {
+    SemaphoreGuard guard(refresh_mutex_);
+    if (guard.take(pdMS_TO_TICKS(5000)) != pdTRUE) {
+      ESP_LOGE(TAG, "Refresh mutex timeout in partial_refresh");
+      return ESP_ERR_TIMEOUT;
+    }
+
+    if (partial_refresh_count_ < UINT32_MAX) {
+      partial_refresh_count_++;
+    }
+    if (partial_refresh_count_ >= PARTIAL_REFRESH_THRESHOLD) {
+      ESP_LOGI(TAG, "Partial refresh count %u reached threshold %u, next refresh will be full",
+        partial_refresh_count_, PARTIAL_REFRESH_THRESHOLD);
+      force_full_refresh_ = true;
+      partial_refresh_count_ = 0;
+    }
+  }
+
+
+
+  refresh_area_.reset();
+
+  return ESP_OK;
+}
+
+esp_err_t EInkDisplayHandler::clear_display(void) {
+  ESP_LOGI(TAG, "Clearing display to all white...");
+
+  esp_err_t err = full_write(white_data, false);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to clear display: %s", esp_err_to_name(err));
+    return err;
+  }
+  ESP_LOGI(TAG, "Display cleared to all white");
+  return ESP_OK;
+}
+
+void EInkDisplayHandler::write_to_buffer_(const uint8_t* src_buffer, const RefreshArea& area) {
+  // Copy the relevant area from src_buffer to draw_buffer_
+  const uint32_t area_width_bytes = (area.x2 - area.x1 + 1) / 8;
+  const uint32_t area_height = area.y2 - area.y1 + 1;
+
+  for (int32_t row = 0; row < area_height; ++row) {
+    uint32_t fb_y = area.y1 + row;
+    uint32_t fb_x_byte_start = area.x1 / 8;
+    const uint8_t* src_ptr = &src_buffer[row * area_width_bytes];
+    uint8_t* dest_ptr = &draw_buffer_[fb_y * (DISPLAY_WIDTH / 8) + fb_x_byte_start];
+    memcpy(dest_ptr, src_ptr, area_width_bytes);
+  }
+}
+
+// Request a full refresh on next flush
+void EInkDisplayHandler::request_full_refresh(void) {
+  SemaphoreGuard guard(refresh_mutex_);
+  if (guard.take(pdMS_TO_TICKS(100))) {
+    force_full_refresh_ = true;
+    partial_refresh_count_ = 0;
+    ESP_LOGI(TAG, "Full refresh requested");
+  } else {
+    ESP_LOGE(TAG, "Failed to take refresh mutex to request full refresh");
+  }
+}
+
+
+esp_err_t EInkDisplayHandler::init_devices(EventGroupHandle_t system_event_group) {
+  esp_err_t err;
+  err = init_display_pins_();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize display pins: %s", esp_err_to_name(err));
+    return err;
+  }
+  err = this->epd_handler_.init();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize EPD handler: %s", esp_err_to_name(err));
+    return err;
+  }
+  err = init_touch_();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize touch: %s", esp_err_to_name(err));
+    return err;
+  }
+  // if system_event_group is provided, set display ready bits
+  if (system_event_group != nullptr) {
+    // Indicate that display is ready
+    xEventGroupSetBits(system_event_group, DISPLAY_READY_BIT | TOUCH_CALIBRATED_BIT);
+    ESP_LOGI(TAG, "Display marked as ready");
+  }
+  return ESP_OK;
+}
+
+esp_err_t EInkDisplayHandler::init_display_pins_(void) {
+  ESP_LOGI(TAG, "Initializing E-Ink display handler...");
+
+  esp_err_t ret;
+
+  // Initialize GPIO pins
+  gpio_config_t io_conf = {};
+  io_conf.pin_bit_mask = (1ULL << PIN_DC) | (1ULL << PIN_RST);
+  io_conf.mode = GPIO_MODE_OUTPUT;
+  io_conf.pull_up_en = GPIO_PULLUP_DISABLE;
+  io_conf.pull_down_en = GPIO_PULLDOWN_DISABLE;
+  io_conf.intr_type = GPIO_INTR_DISABLE;
+  ret = gpio_config(&io_conf);
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to configure GPIO pins: %s", esp_err_to_name(ret));
+    return ret;
+  }
+
+  // Configure BUSY pin as input (no pull-up like sample code)
+  io_conf.pin_bit_mask = (1ULL << PIN_BUSY);
+  io_conf.mode = GPIO_MODE_INPUT;
+  io_conf.pull_up_en = GPIO_PULLUP_DISABLE;
+  io_conf.pull_down_en = GPIO_PULLDOWN_DISABLE;
+  ret = gpio_config(&io_conf);
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to configure BUSY pin: %s", esp_err_to_name(ret));
+    return ret;
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t EInkDisplayHandler::epd_init_internal_(uint32_t transaction_id) {
+  ESP_LOGI(TAG, "Initializing EPD...");
+  esp_err_t err;
+
+
+  // 1. Hardware Reset
+  err = gpio_set_level(PIN_RST, 0);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to set PIN_RST low: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+  err = gpio_set_level(PIN_RST, 1);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to set PIN_RST high: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+
+  // 2. Initialization Sequence
+  std::vector<uint8_t> panel_setting_data = { 0x1F };
+  err = epd_handler_.epd_write_cmd_with_data(0x00, panel_setting_data, transaction_id); // Panel Setting
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Panel Setting command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+  std::vector<uint8_t> vcom_data = { 0x10, 0x07 };
+  err = epd_handler_.epd_write_cmd_with_data(0x50, vcom_data, transaction_id); // VCOM
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send VCOM command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+  err = epd_handler_.epd_write_cmd(0x04, transaction_id); // Power ON
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Power ON command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_POWER_ON_DELAY_MS)); // Wait for power on
+
+  // Check BUSY pin with detailed logging
+  ESP_LOGI(TAG, "Waiting for EPD to be ready after power on...");
+  ESP_LOGI(TAG, "BUSY pin level after power on: %d (0=BUSY, 1=FREE)", gpio_get_level(PIN_BUSY));
+
+  epd_handler_.wait_for_idle();
+  std::vector<uint8_t> booster_data = { 0x27, 0x27, 0x18, 0x17 };
+  err = epd_handler_.epd_write_cmd_with_data(0x06, booster_data, transaction_id); // Booster Soft Start
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Booster Soft Start command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+
+  // Enhanced display drive commands
+  std::vector<uint8_t> e0_data = { 0x02 };
+  err = epd_handler_.epd_write_cmd_with_data(0xE0, e0_data, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Enhanced Display Drive command: %s", esp_err_to_name(err));
+    return err;
+  }
+  std::vector<uint8_t> e5_data = { 0x5A };
+  err = epd_handler_.epd_write_cmd_with_data(0xE5, e5_data, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Enhanced Display Drive command: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  is_deep_sleep_ = false;
+
+  return err;
+}
+
+// Internal version that uses an existing transaction (no separate TransactionGuard)
+esp_err_t EInkDisplayHandler::epd_init_partial_internal_(uint32_t transaction_id) {
+  ESP_LOGI(TAG, "Initializing EPD for partial refresh (internal)...");
+  esp_err_t err = ESP_OK;
+
+  // 1. Hardware Reset
+  err = gpio_set_level(PIN_RST, 0);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to set PIN_RST low: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+  err = gpio_set_level(PIN_RST, 1);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to set PIN_RST high: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+
+  // 2. Panel Setting
+  std::vector<uint8_t> panel_setting_data = { 0x1F };
+  err = epd_handler_.epd_write_cmd_with_data(0x00, panel_setting_data, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Panel Setting command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_PIN_SETUP_DELAY_MS));
+
+  // 3. Power ON
+  err = epd_handler_.epd_write_cmd(0x04, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Power ON command: %s", esp_err_to_name(err));
+    return err;
+  }
+  vTaskDelay(pdMS_TO_TICKS(MINIMUM_POWER_ON_DELAY_MS));
+  epd_handler_.wait_for_idle();
+
+  // 4. Partial initialization sequence - Enhanced Display Drive
+  std::vector<uint8_t> e0_data = { 0x02 };
+  err = epd_handler_.epd_write_cmd_with_data(0xE0, e0_data, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Enhanced Display Drive command (E0): %s", esp_err_to_name(err));
+    return err;
+  }
+
+  std::vector<uint8_t> e5_data = { 0x6E };
+  err = epd_handler_.epd_write_cmd_with_data(0xE5, e5_data, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send Enhanced Display Drive command (E5): %s", esp_err_to_name(err));
+    return err;
+  }
+
+  is_deep_sleep_ = false;
+
+  err = refresh_old_buffer_(transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to refresh old buffer during partial init: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  ESP_LOGI(TAG, "EPD partial init (internal) complete");
+  return ESP_OK;
+}
+
+esp_err_t EInkDisplayHandler::init_touch_() {
+  ESP_LOGI(TAG, "Initializing touch...");
+  esp_err_t err;
+
+  // 1. Initialize I2C Bus
+  i2c_config_t conf = {};
+  conf.mode = I2C_MODE_MASTER;
+  conf.sda_io_num = PIN_TOUCH_SDA;
+  conf.scl_io_num = PIN_TOUCH_SCL;
+  conf.sda_pullup_en = GPIO_PULLUP_ENABLE;
+  conf.scl_pullup_en = GPIO_PULLUP_ENABLE;
+  conf.master.clk_speed = 400000;
+
+  err = i2c_param_config(I2C_NUM_0, &conf);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to configure I2C parameters: %s", esp_err_to_name(err));
+    return err;
+  }
+  err = i2c_driver_install(I2C_NUM_0, I2C_MODE_MASTER, 0, 0, 0);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to install I2C driver: %s", esp_err_to_name(err));
+    return err;
+  }
+  ESP_LOGI("DisplayHandler", "I2C driver installed");
+
+  // 2. Initialize GT911
+  ESP_LOGI("DisplayHandler", "Initializing GT911 touch controller...");
+  esp_lcd_panel_io_i2c_config_t tp_io_config = {};
+  // temporarily disable -Wmissing-field-initializers, as ESP_LCD_TOUCH_IO_I2C_GT911_CONFIG macro does not set all fields
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wmissing-field-initializers"
+  esp_lcd_panel_io_i2c_config_t default_tp_io_config = ESP_LCD_TOUCH_IO_I2C_GT911_CONFIG();
+#pragma GCC diagnostic pop
+  tp_io_config.dev_addr = default_tp_io_config.dev_addr;
+  tp_io_config.control_phase_bytes = default_tp_io_config.control_phase_bytes;
+  tp_io_config.dc_bit_offset = default_tp_io_config.dc_bit_offset;
+  tp_io_config.lcd_cmd_bits = default_tp_io_config.lcd_cmd_bits;
+  tp_io_config.flags = default_tp_io_config.flags;
+  esp_lcd_new_panel_io_i2c(I2C_NUM_0, &tp_io_config, &tp_io_handle_);
+
+  // GT911-specific config with I2C address (0x5D = INT low during reset)
+  static esp_lcd_touch_io_gt911_config_t gt911_config = {
+    .dev_addr = ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS  // 0x5D
+  };
+
+  esp_lcd_touch_config_t tp_cfg = {};
+  tp_cfg.x_max = DISPLAY_WIDTH;
+  tp_cfg.y_max = DISPLAY_HEIGHT;
+  tp_cfg.rst_gpio_num = PIN_TOUCH_RST;
+  tp_cfg.int_gpio_num = PIN_TOUCH_IRQ;
+  tp_cfg.driver_data = &gt911_config;  // Pass GT911-specific config for automatic reset
+
+  err = esp_lcd_touch_new_i2c_gt911(tp_io_handle_, &tp_cfg, &tp_handle_);
+  if (err == ESP_OK && tp_handle_ != nullptr) {
+    ESP_LOGI("DisplayHandler", "GT911 touch controller initialized successfully");
+  } else {
+    ESP_LOGE("DisplayHandler", "GT911 touch controller initialization failed: %s", esp_err_to_name(err));
+    tp_handle_ = nullptr;
+  }
+  return err;
+}
+
+esp_err_t EInkDisplayHandler::refresh_old_buffer_(uint32_t transaction_id) {
+  ESP_LOGI(TAG, "Refreshing display SRAM to restore state after wake...");
+  esp_err_t err;
+
+  err = epd_handler_.epd_write_cmd(0x92, transaction_id); // enter normal mode
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to enter normal mode: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Write OLD data (0x10) as all 0x00 (white in e-ink terms)
+  // This tells the controller: "assume display was all white"
+  // Matches sample's EPD_WhiteScreen_ALL() which uses 0x00 for old SRAM
+  // The differential refresh: old=0 + new=0 → stay white, old=0 + new=1 → drive to black
+  err = epd_handler_.epd_write_cmd(0x10, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send old data command: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Send the old buffer as old data
+  err = epd_handler_.transfer_spi_data(old_buffer_, DISPLAY_BUFFER_SIZE, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send white baseline to old SRAM: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Write NEW data (0x13) with the actual display content
+  // This restores the display to show old_buffer_ content
+  err = epd_handler_.epd_write_cmd(0x13, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send new data command: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Send the last displayed content to new SRAM
+  err = epd_handler_.transfer_spi_data(old_buffer_, DISPLAY_BUFFER_SIZE, transaction_id);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send display content to new SRAM: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  ESP_LOGI(TAG, "Display SRAM restored successfully");
+  return ESP_OK;
+}

main/display/eink_display_handler.h

@@ -0,0 +1,98 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "esp_lcd_touch_gt911.h"
+#include "common/semaphore_guard.h"
+#include <vector>
+#include <atomic>
+#include "epd_handler.h"
+
+// Refresh mode configuration
+#define DISPLAY_WIDTH 800
+#define DISPLAY_HEIGHT 480
+
+// forward declarations
+class EInkDisplayHandler;
+
+struct RefreshArea {
+public:
+  RefreshArea(int32_t x_start, int32_t y_start, int32_t x_end, int32_t y_end)
+    : x1(x_start), y1(y_start), x2(x_end), y2(y_end) { }
+  int32_t x1;
+  int32_t y1;
+  int32_t x2;
+  int32_t y2;
+  // reset to empty area
+  void reset() {
+    x1 = y1 = x2 = y2 = 0;
+  }
+  // expand area to include another area
+  void expand_to_include(const RefreshArea& other) {
+    expand_to_include(other.x1, other.y1, other.x2, other.y2);
+  }
+  void expand_to_include(int32_t x1, int32_t y1, int32_t x2, int32_t y2) {
+    const bool force_update = is_empty();
+    if (x1 < this->x1 || force_update) this->x1 = x1;
+    if (y1 < this->y1 || force_update) this->y1 = y1;
+    if (x2 > this->x2 || force_update) this->x2 = x2;
+    if (y2 > this->y2 || force_update) this->y2 = y2;
+  }
+  bool is_empty() const {
+    return (x1 == 0 && y1 == 0 && x2 == 0 && y2 == 0);
+  }
+  uint32_t area() const {
+    if (is_empty()) return 0;
+    return (x2 - x1 + 1) * (y2 - y1 + 1);
+  }
+};
+
+class EInkDisplayHandler {
+public:
+  EInkDisplayHandler();
+  virtual ~EInkDisplayHandler();
+
+  esp_err_t init_devices(EventGroupHandle_t system_event_group = nullptr);
+
+
+  esp_err_t refresh_display(void);
+  esp_err_t full_write(const uint8_t* framebuffer, const bool white_basemap = true);
+  esp_err_t partial_refresh(const uint8_t* framebuffer, const RefreshArea& area, const bool is_last_partial_update = true);
+  esp_err_t clear_display(void);
+  esp_err_t deep_sleep_display(void);
+  // Request a full refresh on next flush
+  void request_full_refresh(void);
+
+  bool is_busy() {
+    return epd_handler_.is_busy();
+  }
+
+  esp_lcd_touch_handle_t get_touch_handle() const { return tp_handle_; }
+
+private:
+
+  esp_err_t init_display_pins_(void);
+  esp_err_t epd_init_internal_(uint32_t transaction_id); // full fast refresh init
+  esp_err_t epd_init_partial_internal_(uint32_t transaction_id); // partial refresh init (within existing transaction)
+  esp_err_t init_touch_(void);
+
+  // write to the internal draw buffer
+  void write_to_buffer_(const uint8_t* src, const RefreshArea& area);
+  // write the internal draw buffer to the display's old sram
+  esp_err_t refresh_old_buffer_(uint32_t transaction_id);
+
+
+  EPDHandler epd_handler_;
+  uint32_t partial_refresh_count_ = 0;
+  bool force_full_refresh_ = false;
+  std::atomic<bool> is_deep_sleep_ { false };
+
+  SemaphoreHandle_t refresh_mutex_ = nullptr;
+  esp_lcd_panel_io_handle_t tp_io_handle_ = nullptr;
+  esp_lcd_touch_handle_t tp_handle_ = nullptr;
+
+  // this buffer reflects the current display state (1=black, 0=white)
+  uint8_t* draw_buffer_ = nullptr;
+  uint8_t* old_buffer_ = nullptr;
+  RefreshArea refresh_area_ = { 0, 0, 0, 0 };
+};
+

main/display/epd_handler.cpp

@@ -0,0 +1,326 @@
+#include "display/epd_handler.h"
+#include "esp_log.h"
+#include "display/constants.h"
+#include "common/constants.h"
+#include "esp_lcd_touch_gt911.h"
+#include <driver/i2c.h>
+#define TAG "EPDHandler"
+
+#define BUSY_ACTIVE_LEVEL   0  // BUSY pin is active low
+#define BUSY_INACTIVE_LEVEL 1
+#define DMA_TRANSFER_CHUNK_SIZE 4096  // 4KB chunk size for DMA transfers
+
+EPDHandler::EPDHandler() {
+  spi_mutex_ = xSemaphoreCreateMutex();
+  if (spi_mutex_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create SPI mutex");
+  }
+  spi_transaction_mutex_ = xSemaphoreCreateMutex();
+  if (spi_transaction_mutex_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create SPI transaction mutex");
+  }
+}
+
+EPDHandler::~EPDHandler() {
+  if (spi_mutex_ != nullptr) {
+    vSemaphoreDelete(spi_mutex_);
+  }
+  if (spi_transaction_mutex_ != nullptr) {
+    vSemaphoreDelete(spi_transaction_mutex_);
+  }
+  if (spi_ != nullptr) {
+    spi_bus_remove_device(spi_);
+  }
+}
+
+esp_err_t EPDHandler::init() {
+  esp_err_t err;
+
+  // Initialize SPI bus
+  spi_bus_config_t buscfg = {};
+  buscfg.mosi_io_num = 11;  // MOSI pin
+  buscfg.miso_io_num = -1;  // No MISO for e-paper
+  buscfg.sclk_io_num = 12;  // SCK pin
+  buscfg.quadwp_io_num = -1;
+  buscfg.quadhd_io_num = -1;
+  buscfg.max_transfer_sz = DMA_TRANSFER_CHUNK_SIZE;
+
+  err = spi_bus_initialize(SPI2_HOST, &buscfg, SPI_DMA_CH_AUTO);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize SPI bus: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Add SPI device
+  spi_device_interface_config_t devcfg = {};
+  devcfg.clock_speed_hz = 10 * 1000 * 1000;  // 10 MHz
+  devcfg.mode = 0;  // SPI mode 0
+  devcfg.spics_io_num = PIN_CS;
+  devcfg.queue_size = 7;  // Queue size for non-blocking transactions
+  devcfg.pre_cb = nullptr;
+
+  err = spi_bus_add_device(SPI2_HOST, &devcfg, &spi_);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to add SPI device: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  return ESP_OK;
+}
+
+// Check if display is busy (refreshing)
+bool EPDHandler::is_busy(void) const {
+  return gpio_get_level(PIN_BUSY) != BUSY_ACTIVE_LEVEL;  // BUSY is active LOW
+}
+void EPDHandler::wait_for_idle(void) const {
+  ESP_LOGI(TAG, "Waiting for display ready (BUSY pin)...");
+  int initial_level = gpio_get_level(PIN_BUSY);
+  ESP_LOGI(TAG, "Initial BUSY pin level: %d (0=BUSY, 1=FREE)", initial_level);
+
+  // If already free, no need to wait
+  if (initial_level == BUSY_INACTIVE_LEVEL) {
+    ESP_LOGI(TAG, "Display already ready (BUSY pin = 1)");
+    return;
+  }
+  while (gpio_get_level(PIN_BUSY) != BUSY_INACTIVE_LEVEL) {
+    vTaskDelay(pdMS_TO_TICKS(10));
+  }
+  ESP_LOGI(TAG, "Display is now ready (BUSY pin = 1)");
+}
+
+esp_err_t EPDHandler::epd_write_cmd(const uint8_t cmd, uint32_t transaction_id) {
+  ESP_LOGI(TAG, "epd_write_cmd: waiting to send 0x%02X", cmd);
+
+  SemaphoreGuard transaction_guard(spi_transaction_mutex_);
+  esp_err_t err =
+    wait_for_transaction_end_(pdMS_TO_TICKS(5000), transaction_id, transaction_guard);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to wait for previous transaction end before sending cmd 0x%02X: %s",
+      cmd, esp_err_to_name(err));
+    return err;
+  }
+
+  SemaphoreGuard guard(spi_mutex_);
+  if (!guard.take(pdMS_TO_TICKS(5000))) {
+    ESP_LOGE(TAG, "SPI mutex timeout for cmd 0x%02X", cmd);
+    return ESP_ERR_TIMEOUT;
+  }
+  err = dangerous_epd_write_cmd_without_lock_(cmd);
+  ESP_LOGI(TAG, "epd_write_cmd: 0x%02X done", cmd);
+  return err;
+}
+
+esp_err_t EPDHandler::epd_write_data(const uint8_t data, uint32_t transaction_id) {
+  ESP_LOGI(TAG, "epd_write_data: waiting to send 0x%02X", data);
+  SemaphoreGuard transaction_guard(spi_transaction_mutex_);
+  esp_err_t err =
+    wait_for_transaction_end_(pdMS_TO_TICKS(5000), transaction_id, transaction_guard);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to wait for previous transaction end before sending data 0x%02X: %s",
+      data, esp_err_to_name(err));
+    return err;
+  }
+  SemaphoreGuard guard(spi_mutex_);
+  if (!guard.take(pdMS_TO_TICKS(5000))) {
+    ESP_LOGE(TAG, "SPI mutex timeout for data 0x%02X", data);
+    return ESP_ERR_TIMEOUT;
+  }
+  err = dangerous_epd_write_data_without_lock_(data);
+  ESP_LOGI(TAG, "epd_write_data: 0x%02X done", data);
+  return err;
+}
+
+esp_err_t EPDHandler::epd_write_cmd_with_data(const uint8_t cmd, std::vector<uint8_t>& data, uint32_t transaction_id) {
+  const size_t data_len = data.size();
+  ESP_LOGI(TAG, "epd_write_cmd_with_data: waiting to send cmd 0x%02X with %u bytes of data", cmd, data_len);
+
+  SemaphoreGuard transaction_guard(spi_transaction_mutex_);
+  esp_err_t err =
+    wait_for_transaction_end_(pdMS_TO_TICKS(5000), transaction_id, transaction_guard);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to wait for previous transaction end before sending cmd 0x%02X: %s, with data",
+      cmd, esp_err_to_name(err));
+    return err;
+  }
+
+  SemaphoreGuard guard(spi_mutex_);
+  if (!guard.take(pdMS_TO_TICKS(5000))) {
+    ESP_LOGE(TAG, "SPI mutex timeout for cmd with data 0x%02X", cmd);
+    return ESP_ERR_TIMEOUT;
+  }
+  err = dangerous_epd_write_cmd_without_lock_(cmd);
+  if (err != ESP_OK) {
+    return err;
+  };
+  for (size_t i = 0; i < data_len; ++i) {
+    err = dangerous_epd_write_data_without_lock_(data[i]);
+    if (err != ESP_OK) {
+      return err;
+    }
+  }
+  ESP_LOGI(TAG, "epd_write_cmd_with_data: cmd 0x%02X with %u bytes of data done", cmd, data_len);
+  return ESP_OK;
+}
+
+
+esp_err_t EPDHandler::dangerous_epd_write_cmd_without_lock_(const uint8_t cmd) {
+  ESP_LOGI(TAG, "dangerous_epd_write_cmd_without_lock_: sending 0x%02X", cmd);
+  gpio_set_level(PIN_DC, 0); // Command mode
+  spi_transaction_t t {};
+  t.length = 8;t.tx_buffer = &cmd;
+  esp_err_t err = spi_device_polling_transmit(spi_, &t);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send data 0x%02X", cmd);
+  } else {
+    ESP_LOGI(TAG, "dangerous_epd_write_cmd_without_lock_: 0x%02X sent", cmd);
+  }
+  return err;
+}
+
+esp_err_t EPDHandler::dangerous_epd_write_data_without_lock_(const uint8_t data) {
+  ESP_LOGI(TAG, "dangerous_epd_write_data_without_lock_: sending 0x%02X", data);
+  gpio_set_level(PIN_DC, 1); // Data mode
+  spi_transaction_t t = { };
+  t.length = 8; t.tx_buffer = &data;
+  esp_err_t err = spi_device_polling_transmit(spi_, &t);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to send data 0x%02X", data);
+  } else {
+    ESP_LOGI(TAG, "dangerous_epd_write_data_without_lock_: 0x%02X sent", data);
+  }
+  return err;
+}
+
+esp_err_t EPDHandler::transfer_spi_data(const uint8_t* data, const size_t& length, uint32_t transaction_id, bool inverted) {
+  ESP_LOGI(TAG, "transfer_spi_data: waiting to send %zu bytes of data", length);
+
+  SemaphoreGuard transaction_guard(spi_transaction_mutex_);
+  esp_err_t err =
+    wait_for_transaction_end_(pdMS_TO_TICKS(5000), transaction_id, transaction_guard);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to wait for previous transaction end before sending data of %zu bytes: %s",
+      length, esp_err_to_name(err));
+    return err;
+  }
+  SemaphoreGuard guard(spi_mutex_);
+  if (!guard.take(pdMS_TO_TICKS(5000))) {
+    ESP_LOGE(TAG, "SPI mutex timeout for data transfer of %zu bytes", length);
+    return ESP_ERR_TIMEOUT;
+  }
+  ESP_LOGI(TAG, "transfer_spi_data: starting to send %zu bytes of data", length);
+
+  size_t offset = 0;
+  size_t remaining = length;
+  gpio_set_level(PIN_DC, 1); // Data mode
+
+  // Allocate a temporary buffer for inverted data (only if inverted)
+  uint8_t* temp_transfer_buffer = nullptr;
+  if (inverted) {
+    temp_transfer_buffer = (uint8_t*)heap_caps_malloc(DMA_TRANSFER_CHUNK_SIZE, MALLOC_CAP_DMA);
+    if (temp_transfer_buffer == nullptr) {
+      ESP_LOGE(TAG, "Failed to allocate memory for inverted data transfer buffer");
+      ESP_LOGI(TAG, "Current free heap size: %u bytes", esp_get_free_heap_size());
+      ESP_LOGI(TAG, "Current free DMA-capable memory size: %u bytes",
+        heap_caps_get_free_size(MALLOC_CAP_DMA));
+      return ESP_ERR_NO_MEM;
+    }
+  }
+
+  while (remaining > 0) {
+    size_t transfer_size = (remaining < DMA_TRANSFER_CHUNK_SIZE) ? remaining : DMA_TRANSFER_CHUNK_SIZE;
+
+    const uint8_t* transfer_buffer = nullptr;
+    if (inverted) {
+      // Invert only the current chunk into the temporary buffer
+      for (size_t i = 0; i < transfer_size; ++i) {
+        temp_transfer_buffer[i] = ~data[offset + i];
+      }
+      transfer_buffer = temp_transfer_buffer;
+    } else {
+      transfer_buffer = data + offset;
+    }
+
+    spi_transaction_t t = {};
+    t.length = transfer_size * 8;  // Length in bits
+    t.tx_buffer = transfer_buffer;
+
+    esp_err_t ret = spi_device_polling_transmit(spi_, &t);
+    if (ret != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to send SPI chunk at offset %zu: %s", offset, esp_err_to_name(ret));
+      if (ret == ESP_ERR_NO_MEM) {
+        ESP_LOGE(TAG, "Current free heap size: %u bytes", esp_get_free_heap_size());
+        ESP_LOGE(TAG, "Current free DMA-capable memory size: %u bytes",
+          heap_caps_get_free_size(MALLOC_CAP_DMA));
+      }
+      if (inverted && temp_transfer_buffer != nullptr) {
+        // Free the temporary inverted buffer
+        heap_caps_free(temp_transfer_buffer);
+      }
+      return ret;
+    }
+
+    remaining -= transfer_size;
+    offset += transfer_size;
+
+    // Yield every 16KB to prevent watchdog timeout
+    if (offset % (16 * 1024) == 0) {
+      ESP_LOGI(TAG, "New data progress: %zu/%zu bytes sent, yielding...", offset, length);
+      vTaskDelay(pdMS_TO_TICKS(1));
+    }
+  }
+
+  if (inverted && temp_transfer_buffer != nullptr) {
+    // Free the temporary inverted buffer
+    heap_caps_free(temp_transfer_buffer);
+  }
+
+  ESP_LOGI(TAG, "transfer_spi_data: completed sending %zu bytes of data", length);
+  return ESP_OK;
+}
+
+esp_err_t EPDHandler::begin_transaction_(TickType_t timeout, uint32_t& out_id) {
+  ESP_LOGI(TAG, "begin_transaction_: waiting to obtain transaction mutex");
+  if (xSemaphoreTake(spi_transaction_mutex_, timeout) != pdTRUE) {
+    ESP_LOGE(TAG, "begin_transaction_: transaction mutex timeout");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  out_id = ++spi_transaction_id;
+  ESP_LOGI(TAG, "begin_transaction_: transaction mutex obtained");
+  return ESP_OK;
+}
+
+esp_err_t EPDHandler::end_transaction_(void) {
+  ESP_LOGI(TAG, "end_transaction_: releasing transaction mutex");
+  if (xSemaphoreGive(spi_transaction_mutex_) != pdTRUE) {
+    ESP_LOGE(TAG, "end_transaction_: failed to release transaction mutex");
+    return ESP_FAIL;
+  }
+
+  ESP_LOGI(TAG, "end_transaction_: transaction mutex released");
+  return ESP_OK;
+}
+
+esp_err_t EPDHandler::wait_for_transaction_end_(TickType_t timeout, uint32_t awaiting_transaction_id, SemaphoreGuard& out_transaction_guard) {
+  // Validate transaction ID if provided
+  if (awaiting_transaction_id != 0 && awaiting_transaction_id != spi_transaction_id) {
+    // Invalid transaction ID
+    ESP_LOGE(TAG, "Invalid transaction ID 0x%08X while waiting, current transaction ID: 0x%08X",
+      awaiting_transaction_id, spi_transaction_id);
+    return ESP_ERR_INVALID_ARG;
+  }
+  SemaphoreGuard transaction_guard(spi_transaction_mutex_);
+  if (awaiting_transaction_id == 0) {
+    // wait for current transaction to complete
+    ESP_LOGV(TAG, "Waiting for current transaction 0x%08X to complete",
+      spi_transaction_id);
+    // take the mutex to ensure no transaction is active
+    if (!transaction_guard.take(timeout)) {
+      ESP_LOGE(TAG, "SPI transaction mutex timeout while waiting for transaction end");
+      return ESP_ERR_TIMEOUT;
+    }
+  }
+  // awaited_transaction_id is valid and matches current transaction ID or 0
+  out_transaction_guard = std::move(transaction_guard);
+  return ESP_OK;
+}

main/display/epd_handler.h

@@ -0,0 +1,41 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "driver/spi_master.h"
+#include "common/semaphore_guard.h"
+#include <vector>
+#include "display/transaction_guard.h"
+
+class EPDHandler : public WithTransaction {
+public:
+  EPDHandler();
+  ~EPDHandler();
+  esp_err_t init();
+
+  esp_err_t epd_write_cmd(const uint8_t cmd, uint32_t transaction_id);
+  esp_err_t epd_write_data(const uint8_t data, uint32_t transaction_id);
+  esp_err_t epd_write_cmd_with_data(const uint8_t cmd, std::vector<uint8_t>& data, uint32_t transaction_id);
+  esp_err_t transfer_spi_data(const uint8_t* data, const size_t& length, uint32_t transaction_id, bool inverted = false);
+
+  bool is_busy(void) const;
+  void wait_for_idle(void) const;
+
+private:
+
+  esp_err_t dangerous_epd_write_cmd_without_lock_(const uint8_t cmd);
+  esp_err_t dangerous_epd_write_data_without_lock_(const uint8_t data);
+
+  esp_err_t begin_transaction_(TickType_t timeout, uint32_t& out_id) override;
+  esp_err_t end_transaction_(void) override;
+  // given a transaction ID, wait for current transaction to complete. The transaction ID will determine if the wait is needed.
+  esp_err_t wait_for_transaction_end_(TickType_t timeout, uint32_t awaiting_transaction_id, SemaphoreGuard& out_transaction_guard);
+
+  spi_device_handle_t spi_ = nullptr;
+
+  SemaphoreHandle_t spi_mutex_ = nullptr;
+  SemaphoreHandle_t spi_transaction_mutex_ = nullptr;
+
+  uint32_t spi_transaction_id = 0; // For tracking SPI transactions
+
+  friend class TransactionGuard;
+};

main/display/lvgl_handler.cpp

@@ -0,0 +1,318 @@
+#include "display/lvgl_handler.h"
+#include "esp_log.h"
+#include "common/semaphore_guard.h"
+#include "common/constants.h"
+#include <portmacro.h>
+
+#define DISPLAY_BUFFER_SIZE (DISPLAY_WIDTH * DISPLAY_HEIGHT) / 8 // 1 bit per pixels
+#define LVGL_BUFFER_SIZE (DISPLAY_BUFFER_SIZE + 8) // 1 bit per pixels + 8 bytes for palette
+#define LV_DISPLAY_RENDER_MODE LV_DISPLAY_RENDER_MODE_PARTIAL
+#define TAG "LVGLHandler"
+
+LVGLHandler::LVGLHandler(
+  std::unique_ptr<EInkDisplayHandler> display_handler_in
+) : display_handler_(std::move(display_handler_in)) { }
+
+LVGLHandler::~LVGLHandler() {
+  if (lvgl_display_ != nullptr) {
+    lv_display_delete(lvgl_display_);
+    lvgl_display_ = nullptr;
+  }
+  if (lvgl_touch_indev_ != nullptr) {
+    lvgl_port_remove_touch(lvgl_touch_indev_);
+    lvgl_touch_indev_ = nullptr;
+  }
+  if (lvgl_draw_buf_ != nullptr) {
+    lv_draw_buf_destroy(lvgl_draw_buf_);
+    lvgl_draw_buf_ = nullptr;
+  }
+}
+
+esp_err_t LVGLHandler::initLVGL(EventGroupHandle_t system_event_group) {
+  esp_err_t err = initLVGLPort_();
+  if (err != ESP_OK) {
+    return err;
+  }
+  err = initLVGLDisplay_();
+  if (err != ESP_OK) {
+    return err;
+  }
+  err = registerLVGLTouch_();
+  if (err != ESP_OK) {
+    return err;
+  }
+
+
+  auto lvgl_tick_timer_callback = [](TimerHandle_t xTimer) {
+    lv_tick_inc(5);
+    };
+  TickType_t lvgl_tick_period = pdMS_TO_TICKS(5);
+  if (lvgl_tick_period == 0) {
+    lvgl_tick_period = 1; // ensure at least 1 tick to avoid FreeRTOS assert
+  }
+  ESP_LOGV(TAG, "Creating LVGL tick timer with period %u ticks...\n", (unsigned)lvgl_tick_period);
+  TimerHandle_t lvgl_tick_timer = xTimerCreate(
+    "lvgl_tick_timer",
+    lvgl_tick_period,
+    pdTRUE,
+    NULL,
+    lvgl_tick_timer_callback
+  );
+  if (lvgl_tick_timer == NULL) {
+    ESP_LOGE("Main", "Failed to create LVGL tick timer");
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return ESP_ERR_NO_MEM;
+  }
+  ESP_LOGV(TAG, "Starting LVGL tick timer...\n");
+  xTimerStart(lvgl_tick_timer, 0);
+
+  if (system_event_group != nullptr) {
+    xEventGroupSetBits(system_event_group, DISPLAY_READY_BIT | TOUCH_CALIBRATED_BIT);
+  }
+
+  return ESP_OK;
+}
+
+//
+// Private methods
+//
+
+void LVGLHandler::rounder_cb_(lv_display_t* disp, lv_area_t* area) {
+  // align x to byte boundary
+  area->x1 = (area->x1 & ~0x7);
+  area->x2 = (area->x2 | 0x7);
+}
+
+void LVGLHandler::flush_cb_(lv_display_t* disp, const lv_area_t* area, uint8_t* px_map) {
+  if (disp == nullptr || area == nullptr || px_map == nullptr) {
+    ESP_LOGE(TAG, "Null parameters in flush callback");
+    if (disp != nullptr) lv_display_flush_ready(disp);
+    return;
+  }
+  LVGLHandler* handler = static_cast<LVGLHandler*>(lv_display_get_user_data(disp));
+  if (handler == nullptr || handler->display_handler_ == nullptr) {
+    ESP_LOGE(TAG, "Invalid handler in flush callback");
+    lv_display_flush_ready(disp);
+    return;
+  }
+  uint8_t* pixel_data = px_map + 8; // Skip palette
+  //
+  ESP_LOGI(TAG, "Flush callback: x1=%d, y1=%d, x2=%d, y2=%d", area->x1, area->y1, area->x2, area->y2);
+
+  // copy data to framebuffer
+  int32_t area_w = lv_area_get_width(area);
+  int32_t area_h = lv_area_get_height(area);
+  if (area->x1 == 0 && area->y1 == 0 && area_w == DISPLAY_WIDTH && area_h == DISPLAY_HEIGHT) {
+    // revert the pixel data for e-ink (LVGL: 1=white, 0=black; E-Ink: 1=black, 0=white)
+    for (size_t i = 0; i < DISPLAY_BUFFER_SIZE; ++i) {
+      pixel_data[i] = ~pixel_data[i];
+    }
+    esp_err_t err = handler->display_handler_->full_write(
+      pixel_data,
+      true  // white basemap
+    );
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Full refresh request failed: %s", esp_err_to_name(err));
+    }
+  } else {
+    // partial update
+    ESP_LOGI(TAG, "Partial update: x1=%d, y1=%d, w=%d, h=%d", area->x1, area->y1, area_w, area_h);
+
+    // Prepare partial buffer
+    const uint32_t area_width_bytes = (area->x2 - area->x1 + 1) / 8;
+    const uint32_t area_height = area->y2 - area->y1 + 1;
+    const size_t partial_buffer_size = area_width_bytes * area_height;
+    uint8_t* partial_buffer = new uint8_t[partial_buffer_size];
+    if (partial_buffer == nullptr) {
+      ESP_LOGE(TAG, "Failed to allocate partial buffer for flush callback");
+      lv_display_flush_ready(disp);
+      return;
+    }
+    // Copy pixel data to partial buffer and invert for e-ink
+    for (int32_t row = 0; row < area_height; ++row) {
+      for (int32_t col = 0; col < area_width_bytes; ++col) {
+        size_t src_index = row * area_width_bytes + col;
+        partial_buffer[src_index] = ~pixel_data[src_index];
+      }
+    }
+
+    esp_err_t err = handler->display_handler_->partial_refresh(partial_buffer,
+      RefreshArea {
+        area->x1,
+        area->y1,
+        area->x2,
+        area->y2
+      }, lv_display_flush_is_last(disp));
+    delete[] partial_buffer;
+
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Partial refresh request failed: %s", esp_err_to_name(err));
+    }
+  }
+  //
+  lv_display_flush_ready(disp);
+}
+
+void LVGLHandler::touch_read_cb_(lv_indev_t* indev, lv_indev_data_t* data) {
+  LVGLHandler* handler = static_cast<LVGLHandler*>(lv_indev_get_user_data(indev));
+  if (handler == nullptr || handler->display_handler_ == nullptr) {
+    data->state = LV_INDEV_STATE_RELEASED;
+    ESP_LOGE(TAG, "Invalid handler in touch read callback");
+    return;
+  }
+
+  // Disable touch input during display refresh (BUSY)
+  if (handler->display_handler_->is_busy()) {
+    data->state = LV_INDEV_STATE_RELEASED;
+    data->continue_reading = false;
+    return;
+  }
+
+  esp_lcd_touch_handle_t tp_handle = handler->display_handler_->get_touch_handle();
+  if (tp_handle == nullptr) {
+    data->state = LV_INDEV_STATE_RELEASED;
+    return;
+  }
+
+  // Read touch data from GT911
+  esp_err_t ret = esp_lcd_touch_read_data(tp_handle);
+  if (ret == ESP_OK) {
+    uint8_t touch_cnt = 0;
+    // Get touch data using new API
+    esp_lcd_touch_point_data_t point_data[1];
+    esp_lcd_touch_get_data(tp_handle, point_data, &touch_cnt, 1);
+
+    if (touch_cnt > 0) {
+      // ESP_LOGI(TAG, "Touch data read successfully: x=%d, y=%d", point_data[0].x, point_data[0].y);
+      data->point.x = point_data[0].x;
+      data->point.y = point_data[0].y;
+      data->state = LV_INDEV_STATE_PRESSED;
+    } else {
+      data->state = LV_INDEV_STATE_RELEASED;
+    }
+  } else {
+    data->state = LV_INDEV_STATE_RELEASED;
+  }
+
+  data->continue_reading = false;
+}
+
+esp_err_t LVGLHandler::initLVGLDisplay_() {
+  if (display_handler_ == nullptr) {
+    return ESP_ERR_INVALID_STATE;
+  }
+  esp_err_t err = ESP_OK;
+
+  // Lock LVGL to prevent the timer task from accessing partially initialized display
+  if (!lvgl_port_lock(pdMS_TO_TICKS(5000))) {
+    ESP_LOGE(TAG, "Failed to lock LVGL port for display initialization");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  // Create LVGL display
+  lvgl_display_ = lv_display_create(DISPLAY_WIDTH, DISPLAY_HEIGHT);
+  if (lvgl_display_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create LVGL display");
+    lvgl_port_unlock();
+    return ESP_FAIL;
+  }
+
+  // Create a draw buffer covering the entire display
+  lvgl_draw_buf_ = lv_draw_buf_create(DISPLAY_WIDTH, DISPLAY_HEIGHT, LV_COLOR_FORMAT_I1, LV_STRIDE_AUTO);
+  if (lvgl_draw_buf_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create LVGL draw buffer");
+    lv_display_delete(lvgl_display_);
+    lvgl_display_ = nullptr;
+    lvgl_port_unlock();
+    return ESP_FAIL;
+  }
+  lv_display_set_draw_buffers(lvgl_display_, lvgl_draw_buf_, nullptr);
+  lv_display_set_render_mode(lvgl_display_, LV_DISPLAY_RENDER_MODE);
+  //
+  // Configure LVGL display
+  lv_display_set_color_format(lvgl_display_, LV_COLOR_FORMAT_I1);
+  lv_display_set_user_data(lvgl_display_, this);
+
+  lv_display_add_event_cb(lvgl_display_, [](lv_event_t* e) {
+    LVGLHandler* handler = static_cast<LVGLHandler*>(lv_display_get_user_data(static_cast<lv_display_t*>(lv_event_get_target(e))));
+    if (handler != nullptr) {
+      handler->rounder_cb_(static_cast<lv_display_t*>(lv_event_get_target(e)),
+        static_cast<lv_area_t*>(lv_event_get_param(e)));
+    } else {
+      ESP_LOGE(TAG, "Invalid handler in rounder callback");
+    }
+    }, LV_EVENT_INVALIDATE_AREA, lvgl_display_);
+
+  lv_display_set_flush_cb(lvgl_display_, [](lv_display_t* disp, const lv_area_t* area, uint8_t* px_map) {
+    LVGLHandler* handler = static_cast<LVGLHandler*>(lv_display_get_user_data(disp));
+    if (handler != nullptr) {
+      handler->flush_cb_(disp, area, px_map);
+    } else {
+      lv_display_flush_ready(disp);
+    }
+    });
+
+  // Unlock LVGL now that display is fully initialized
+
+  ESP_LOGI(TAG, "Performing initial display write...");
+  // err = display_handler_->full_write(framebuffer_, false);
+  err = display_handler_->clear_display();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Initial display write failed: %d", err);
+  } else {
+    ESP_LOGI(TAG, "Initial display write complete");
+  }
+
+  lvgl_port_unlock();
+
+  ESP_LOGI(TAG, "LVGL display registered");
+  return err;
+}
+
+esp_err_t LVGLHandler::registerLVGLTouch_() {
+  if (display_handler_ == nullptr) {
+    return ESP_ERR_INVALID_STATE;
+  }
+  esp_lcd_touch_handle_t tp_handle = display_handler_->get_touch_handle();
+  if (tp_handle == nullptr) {
+    ESP_LOGE(TAG, "Touch handle is NULL — touch initialization failed; skipping LVGL touch registration");
+    return ESP_FAIL;
+  }
+
+  const lvgl_port_touch_cfg_t touch_cfg = {
+    .disp = lvgl_display_,
+    .handle = tp_handle,
+    .scale = {}, // Default scaling
+  };
+
+  lvgl_touch_indev_ = lvgl_port_add_touch(&touch_cfg);
+  if (lvgl_touch_indev_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to register LVGL touch input");
+    return ESP_FAIL;
+  }
+
+  lv_indev_set_user_data(lvgl_touch_indev_, this);
+  lv_indev_set_read_cb(lvgl_touch_indev_, [](lv_indev_t* indev, lv_indev_data_t* data) {
+    LVGLHandler* handler = static_cast<LVGLHandler*>(lv_indev_get_user_data(indev));
+    if (handler != nullptr) {
+      handler->touch_read_cb_(indev, data);
+    } else {
+      data->state = LV_INDEV_STATE_RELEASED;
+    }
+    });
+
+  ESP_LOGI(TAG, "LVGL touch input registered");
+  return ESP_OK;
+}
+
+esp_err_t LVGLHandler::initLVGLPort_() {
+  const lvgl_port_cfg_t lvgl_cfg = ESP_LVGL_PORT_INIT_CONFIG();
+  esp_err_t err = lvgl_port_init(&lvgl_cfg);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "LVGL port initialization failed: %s", esp_err_to_name(err));
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return ESP_ERR_INVALID_STATE;
+  }
+  ESP_LOGI(TAG, "LVGL port initialized successfully.\n");
+  return ESP_OK;
+}

main/display/lvgl_handler.h

@@ -0,0 +1,34 @@
+#pragma once
+#include "lvgl.h"
+#include "esp_lvgl_port.h"
+#include "display/eink_display_handler.h"
+#include "freertos/semphr.h"
+#include "freertos/event_groups.h"
+#include "esp_err.h"
+#include <memory>
+
+class LVGLHandler {
+public:
+  LVGLHandler(
+    // an owning pointer to the display handler
+    // The display handler must outlive the LVGLHandler
+    // The display handler must be fully initialized before calling initLVGLDisplay
+    std::unique_ptr<EInkDisplayHandler> display_handler_in
+  );
+  ~LVGLHandler();
+  esp_err_t initLVGL(EventGroupHandle_t system_event_group = nullptr);
+
+private:
+  void rounder_cb_(lv_display_t* disp, lv_area_t* area);
+  void flush_cb_(lv_display_t* disp, const lv_area_t* area, uint8_t* px_map);
+  void touch_read_cb_(lv_indev_t* indev, lv_indev_data_t* data);
+  esp_err_t initLVGLDisplay_();
+  esp_err_t registerLVGLTouch_();
+  esp_err_t initLVGLPort_();
+
+  std::unique_ptr<EInkDisplayHandler> display_handler_ = nullptr;
+
+  lv_display_t* lvgl_display_ = nullptr;
+  lv_indev_t* lvgl_touch_indev_ = nullptr;
+  lv_draw_buf_t* lvgl_draw_buf_ = nullptr;
+};

main/display/transaction_guard.h

@@ -0,0 +1,33 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include <esp_err.h>
+#include <type_traits>
+
+class WithTransaction {
+protected:
+  virtual esp_err_t end_transaction_() = 0;
+  virtual esp_err_t begin_transaction_(TickType_t timeout, uint32_t& out_id) = 0;
+
+  friend class TransactionGuard;
+};
+
+class TransactionGuard {
+public:
+  TransactionGuard(WithTransaction& handler, TickType_t timeout = portMAX_DELAY)
+    : handler_(handler) { }
+  ~TransactionGuard() { if (transaction_id_) handler_.end_transaction_(); }
+
+  esp_err_t begin(TickType_t timeout = portMAX_DELAY) {
+    esp_err_t err = handler_.begin_transaction_(timeout, transaction_id_);
+    return err;
+  }
+  uint32_t transaction_id() const { return transaction_id_; }
+  bool is_active() const { return transaction_id_ != 0; }
+private:
+  // delete copy constructor and assignment operator
+  TransactionGuard(const TransactionGuard&) = delete;
+  TransactionGuard& operator=(const TransactionGuard&) = delete;
+  WithTransaction& handler_;
+  uint32_t transaction_id_ = 0;
+};

main/external/mtr/arrival.cpp

@@ -0,0 +1,98 @@
+#include "external/mtr/arrival.h"
+#include "cJSON.h"
+#include "esp_log.h"
+#include <string>
+
+static const char* TAG = "StationArrivalInfo";
+
+StationArrivalInfo::StationArrivalInfo(
+  cJSON* mtr_line_station_json,
+  cJSON* arrival_json,
+  const std::string& train_line_code,
+  const std::string& train_station_code
+) : _status(UNKNOWN_STATUS)
+, _train_line(train_line_code)
+, _train_station(train_station_code) {
+
+  if (!arrival_json) {
+    ESP_LOGE(TAG, "arrival_json is null");
+    _status = FAILED_WITH_MESSAGE;
+    _message = "No arrival data received";
+    return;
+  }
+
+  // Parse status
+  cJSON* status_json = cJSON_GetObjectItem(arrival_json, "status");
+  if (status_json && cJSON_IsNumber(status_json)) {
+    int status_value = status_json->valueint;
+    if (status_value >= 0 && status_value <= 3) {
+      _status = static_cast<StatusEnum>(status_value);
+    }
+  }
+
+  // TODO: verify the arrival json parsing
+
+      // Parse message (if present)
+  cJSON* message_json = cJSON_GetObjectItem(arrival_json, "message");
+  if (message_json && cJSON_IsString(message_json)) {
+    _message = message_json->valuestring;
+  }
+
+  // Parse UP direction arrivals
+  cJSON* up_json = cJSON_GetObjectItem(arrival_json, "UP");
+  if (up_json && cJSON_IsArray(up_json)) {
+    int up_count = cJSON_GetArraySize(up_json);
+    for (int i = 0; i < up_count; i++) {
+      cJSON* arrival_item = cJSON_GetArrayItem(up_json, i);
+      if (arrival_item) {
+        std::string time_str = "";
+        std::string dest_str = "";
+
+        cJSON* time_json = cJSON_GetObjectItem(arrival_item, "time");
+        if (time_json && cJSON_IsString(time_json)) {
+          time_str = time_json->valuestring;
+        }
+
+        cJSON* dest_json = cJSON_GetObjectItem(arrival_item, "dest");
+        if (dest_json && cJSON_IsString(dest_json)) {
+          dest_str = dest_json->valuestring;
+        }
+
+        if (!time_str.empty()) {
+          _up_arrivals.emplace_back(time_str, dest_str);
+        }
+      }
+    }
+  }
+
+  // Parse DOWN direction arrivals
+  cJSON* down_json = cJSON_GetObjectItem(arrival_json, "DOWN");
+  if (down_json && cJSON_IsArray(down_json)) {
+    int down_count = cJSON_GetArraySize(down_json);
+    for (int i = 0; i < down_count; i++) {
+      cJSON* arrival_item = cJSON_GetArrayItem(down_json, i);
+      if (arrival_item) {
+        std::string time_str = "";
+        std::string dest_str = "";
+
+        cJSON* time_json = cJSON_GetObjectItem(arrival_item, "time");
+        if (time_json && cJSON_IsString(time_json)) {
+          time_str = time_json->valuestring;
+        }
+
+        cJSON* dest_json = cJSON_GetObjectItem(arrival_item, "dest");
+        if (dest_json && cJSON_IsString(dest_json)) {
+          dest_str = dest_json->valuestring;
+        }
+
+        if (!time_str.empty()) {
+          _down_arrivals.emplace_back(time_str, dest_str);
+        }
+      }
+    }
+  }
+
+  ESP_LOGI(TAG, "Parsed arrival info for %s/%s: %zu UP, %zu DOWN trains",
+    train_line_code.c_str(), train_station_code.c_str(),
+    _up_arrivals.size(), _down_arrivals.size());
+}

main/external/mtr/arrival.h

@@ -0,0 +1,67 @@
+#pragma once
+#include "external/mtr/arrival.h"
+#include "cJSON.h"
+#include "external/mtr/mtr.h"
+#include <string>
+#include <vector>
+
+// Forward declaration
+class MTRNextTrainHandler;
+
+struct ArrivalInfo {
+public:
+  // Caller transfers ownership of arrival_time to ArrivalInfo
+  ArrivalInfo(
+    const std::string& arrival_time,
+    const std::string& destination_name
+  ) : _arrival_time(arrival_time)
+    , _destination_name(destination_name) { }
+
+  const char* arrival_time() const {
+    return _arrival_time.c_str();
+  }
+
+  const char* destination() const {
+    return _destination_name.c_str();
+  }
+
+private:
+  const std::string _arrival_time;
+  const std::string _destination_name; // not the code of the station
+};
+
+
+enum StatusEnum {
+  SUCCESSFUL_WITHOUT_DELAY = 0,
+  SUCCESSFUL_WITH_DELAY = 1,
+  FAILED_WITH_MESSAGE = 2,
+  UNKNOWN_STATUS = 3
+};
+
+struct StationArrivalInfo {
+public:
+  friend class MTRNextTrainHandler;
+
+  // Public accessors
+  StatusEnum status() const { return _status; }
+  const char* message() const { return _message.c_str(); }
+  const char* train_line() const { return _train_line.c_str(); }
+  const char* train_station() const { return _train_station.c_str(); }
+  const std::vector<ArrivalInfo>* up_arrivals() const { return &_up_arrivals; }
+  const std::vector<ArrivalInfo>* down_arrivals() const { return &_down_arrivals; }
+
+private:
+  StationArrivalInfo(
+    cJSON* mtr_line_station_json,
+    cJSON* arrival_json,
+    const std::string& train_line_code,
+    const std::string& train_station_code
+  );
+
+  StatusEnum _status;
+  std::string _message; // only valid if status == FAILED_WITH_MESSAGE
+  std::string _train_line;
+  std::string _train_station;
+  std::vector<ArrivalInfo> _up_arrivals;
+  std::vector<ArrivalInfo> _down_arrivals;
+};

main/external/mtr/line_info.cpp

@@ -0,0 +1,45 @@
+#include "external/mtr/line_info.h"
+#include "external/mtr/station_info.h"
+#include "cJSON.h"
+#include "esp_log.h"
+
+LineInfo::LineInfo(cJSON* line_json) {
+  if (!line_json) {
+    ESP_LOGE(LINE_INFO_TAG, "line_json is null");
+    return;
+  }
+
+  // Parse line code
+  cJSON* code_json = cJSON_GetObjectItem(line_json, "code");
+  if (code_json && cJSON_IsString(code_json)) {
+    _code = code_json->valuestring;
+  } else {
+    ESP_LOGW(LINE_INFO_TAG, "Missing or invalid 'code' field");
+  }
+
+  // Parse line color (note: field is 'line_color' in JSON, not 'color')
+  cJSON* color_json = cJSON_GetObjectItem(line_json, "line_color");
+  if (color_json && cJSON_IsString(color_json)) {
+    _color = color_json->valuestring;
+  } else {
+    ESP_LOGW(LINE_INFO_TAG, "Missing or invalid 'line_color' field");
+  }
+
+  // Parse stations array
+  cJSON* stations_json = cJSON_GetObjectItem(line_json, "stations");
+  if (stations_json && cJSON_IsArray(stations_json)) {
+    int station_count = cJSON_GetArraySize(stations_json);
+    _stations.reserve(station_count);
+
+    for (int i = 0; i < station_count; i++) {
+      cJSON* station_json = cJSON_GetArrayItem(stations_json, i);
+      if (station_json) {
+        _stations.emplace_back(station_json);
+      }
+    }
+
+    ESP_LOGI(LINE_INFO_TAG, "Created LineInfo: %s with %d stations", _code.c_str(), station_count);
+  } else {
+    ESP_LOGW(LINE_INFO_TAG, "Missing or invalid 'stations' array");
+  }
+}

main/external/mtr/line_info.h

@@ -0,0 +1,46 @@
+#pragma once
+#include "cJSON.h"
+#include "esp_log.h"
+#include "external/mtr/station_info.h"
+#include "external/mtr/mtr.h"
+#include <string>
+#include <vector>
+
+#define LINE_INFO_TAG "LineInfo"
+
+// Forward declaration
+class MTRNextTrainHandler;
+struct StationInfo;
+
+struct LineInfo {
+public:
+
+  // caller does not own the returned char pointers
+  const char* code() const {
+    return _code.c_str();
+  }
+  // caller does not own the returned char pointers
+  const char* color() const {
+    return _color.c_str();
+  }
+  size_t station_count() const {
+    return _stations.size();
+  }
+  // caller does not own the returned array or StationInfo pointers
+  const std::vector<StationInfo>* stations() const {
+    return &_stations;
+  }
+
+  friend class MTRNextTrainHandler;
+
+private:
+  // Caller transfers ownership of stations array and its contents to LineInfo
+  LineInfo(
+    cJSON* line_json
+  );
+
+  std::string _code;
+  std::string _color;
+  std::vector<StationInfo> _stations;
+};
+

main/external/mtr/mtr.cpp

@@ -0,0 +1,167 @@
+#include "external/mtr/mtr.h"
+#include "external/mtr/line_info.h"
+#include "external/mtr/station_info.h"
+#include "external/mtr/arrival.h"
+#include "assets/MTR_LINE_STATION.h"
+#include "network/network.h"
+#include "network/http_handler.h"
+#include "cJSON.h"
+#include "esp_log.h"
+#include <string>
+#include <sstream>
+
+static const char* TAG = "MTRNextTrainHandler";
+
+// MTR Next Train API endpoint
+// Note: This is a placeholder - replace with actual MTR API endpoint
+static const char* MTR_API_BASE = "https://rt.data.gov.hk/v1/transport/mtr/getSchedule.php";
+
+MTRNextTrainHandler::MTRNextTrainHandler() {
+  ESP_LOGI(TAG, "Initializing MTR Next Train Handler");
+  mtr_data = cJSON_Parse(MTR_LINE_STATION_JSON);
+  if (!mtr_data) {
+    ESP_LOGE(TAG, "Failed to parse MTR line station JSON");
+  } else {
+    ESP_LOGI(TAG, "Successfully parsed MTR line station JSON");
+  }
+}
+
+MTRNextTrainHandler::~MTRNextTrainHandler() {
+  if (mtr_data) {
+    cJSON_Delete(mtr_data);
+    mtr_data = nullptr;
+  }
+  ESP_LOGI(TAG, "MTR Next Train Handler destroyed");
+}
+
+std::vector<LineInfo> MTRNextTrainHandler::get_lines() {
+  std::vector<LineInfo> lines;
+
+  if (!mtr_data) {
+    ESP_LOGE(TAG, "MTR data not initialized");
+    return lines;
+  }
+
+  // Iterate through all line objects in the JSON
+  cJSON* line_json = mtr_data->child;
+  while (line_json) {
+    if (cJSON_IsObject(line_json)) {
+      lines.push_back(LineInfo(line_json));
+    }
+    line_json = line_json->next;
+  }
+
+  ESP_LOGI(TAG, "Retrieved %zu MTR lines", lines.size());
+  return lines;
+}
+
+MtrArrivalErrorCode MTRNextTrainHandler::get_next_arrival_info(
+  NetworkHandler* network_handler,
+  std::string& line_code,
+  std::string& station_code,
+  StationArrivalInfo*& out_info,
+  Language lang
+) {
+  if (!network_handler) {
+    ESP_LOGE(TAG, "NetworkHandler is null");
+    return MtrArrivalErrorCode::UNKNOWN;
+  }
+
+  if (!mtr_data) {
+    ESP_LOGE(TAG, "MTR data not initialized");
+    return MtrArrivalErrorCode::UNKNOWN;
+  }
+
+  // Verify line exists
+  cJSON* line_json = cJSON_GetObjectItem(mtr_data, line_code.c_str());
+  if (!line_json) {
+    ESP_LOGW(TAG, "Line not found: %s", line_code.c_str());
+    return MtrArrivalErrorCode::LINE_NOT_FOUND;
+  }
+
+  // Verify station exists in line
+  bool station_found = false;
+  cJSON* stations_json = cJSON_GetObjectItem(line_json, "stations");
+  if (stations_json && cJSON_IsArray(stations_json)) {
+    int station_count = cJSON_GetArraySize(stations_json);
+    for (int i = 0; i < station_count; i++) {
+      cJSON* station = cJSON_GetArrayItem(stations_json, i);
+      cJSON* code_json = cJSON_GetObjectItem(station, "code");
+      if (code_json && cJSON_IsString(code_json)) {
+        if (station_code == code_json->valuestring) {
+          station_found = true;
+          break;
+        }
+      }
+    }
+  }
+
+  if (!station_found) {
+    ESP_LOGW(TAG, "Station not found: %s in line %s", station_code.c_str(), line_code.c_str());
+    return MtrArrivalErrorCode::STATION_NOT_FOUND;
+  }
+
+  // Build API URL
+  std::ostringstream url;
+  url << MTR_API_BASE << "?line=" << line_code << "&sta=" << station_code;
+  if (lang == Language::EN) {
+    url << "&lang=en";
+  }
+
+  std::string url_str = url.str();
+  ESP_LOGI(TAG, "Fetching arrival info from: %s", url_str.c_str());
+
+  // Create HTTP client configuration
+  esp_http_client_config_t http_config = {};
+  http_config.url = url_str.c_str();
+  http_config.timeout_ms = 10000;
+  http_config.transport_type = HTTP_TRANSPORT_OVER_SSL;
+  http_config.use_global_ca_store = true;
+  http_config.skip_cert_common_name_check = false;
+
+  // Get HTTP handler and perform request
+  auto http_handler = network_handler->get_http_handler(std::move(http_config));
+  if (!http_handler) {
+    ESP_LOGE(TAG, "Failed to create HTTP handler");
+    return MtrArrivalErrorCode::UNKNOWN;
+  }
+
+  esp_err_t err = http_handler->perform_request();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "HTTP request failed: %s", esp_err_to_name(err));
+    return MtrArrivalErrorCode::NO_ARRIVAL_INFO;
+  }
+
+  // Get response body
+  char* buffer = nullptr;
+  int total_len = 0;
+  http_handler->get_body(buffer, total_len);
+
+  if (!buffer || total_len <= 0) {
+    ESP_LOGE(TAG, "Empty response from MTR API");
+    if (buffer) {
+      free(buffer);
+    }
+    return MtrArrivalErrorCode::NO_ARRIVAL_INFO;
+  }
+
+  ESP_LOGI(TAG, "Received %d bytes from MTR API", total_len);
+  ESP_LOGD(TAG, "Response: %s", buffer);
+
+  // Parse JSON response
+  cJSON* arrival_json = cJSON_Parse(buffer);
+  free(buffer);
+
+  if (!arrival_json) {
+    ESP_LOGE(TAG, "Failed to parse MTR API response");
+    return MtrArrivalErrorCode::NO_ARRIVAL_INFO;
+  }
+
+  // Create StationArrivalInfo object
+  out_info = new StationArrivalInfo(mtr_data, arrival_json, line_code, station_code);
+
+  cJSON_Delete(arrival_json);
+
+  ESP_LOGI(TAG, "Successfully retrieved arrival info for %s/%s", line_code.c_str(), station_code.c_str());
+  return MtrArrivalErrorCode::NONE;
+}

main/external/mtr/mtr.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#include "assets/MTR_LINE_STATION.h"
+#include "cJSON.h"
+#include <string>
+#include "esp_log.h"
+#include "external/mtr/line_info.h"
+#include <vector>
+#include "network/network.h"
+
+// Forward declaration
+struct StationArrivalInfo;
+struct LineInfo;
+
+enum class MtrArrivalErrorCode {
+  NONE = 0,
+  LINE_NOT_FOUND = 1,
+  STATION_NOT_FOUND = 2,
+  NO_ARRIVAL_INFO = 3,
+  UNKNOWN = 99,
+};
+
+enum class Language {
+  EN,
+  TC,
+};
+
+class MTRNextTrainHandler {
+public:
+
+  /**
+   * @brief Construct a new MTR Next Train Handler object
+   * @param json Pointer to cJSON object containing MTR Next Train data
+   *
+   * > Caller transfers ownership of the cJSON object to MTRNextTrainHandler
+   *
+   * cJSON structure for MTR Next Train data
+   * This structure is used to parse and store the MTR Next Train JSON data.
+   * Record<code name string, {name: string, code: string, color: hex string, station: {code: string, name: string}[]}>
+   */
+  MTRNextTrainHandler();
+  ~MTRNextTrainHandler();
+
+  std::vector<LineInfo> get_lines();
+
+  MtrArrivalErrorCode get_next_arrival_info(
+    NetworkHandler* network_handler,
+    std::string& line_code,
+    std::string& station_code,
+    StationArrivalInfo*& out_info,
+    Language lang = Language::TC
+  );
+
+private:
+  cJSON* mtr_data;
+};
+
+

main/external/mtr/station_info.cpp

@@ -0,0 +1,28 @@
+#include "external/mtr/station_info.h"
+#include "cJSON.h"
+#include "esp_log.h"
+
+StationInfo::StationInfo(cJSON* station_json) {
+  if (!station_json) {
+    ESP_LOGE(STATION_INFO_TAG, "station_json is null");
+    return;
+  }
+
+  // Parse station code
+  cJSON* code_json = cJSON_GetObjectItem(station_json, "code");
+  if (code_json && cJSON_IsString(code_json)) {
+    _code = code_json->valuestring;
+  } else {
+    ESP_LOGW(STATION_INFO_TAG, "Missing or invalid 'code' field");
+  }
+
+  // Parse station name
+  cJSON* name_json = cJSON_GetObjectItem(station_json, "name");
+  if (name_json && cJSON_IsString(name_json)) {
+    _name = name_json->valuestring;
+  } else {
+    ESP_LOGW(STATION_INFO_TAG, "Missing or invalid 'name' field");
+  }
+
+  ESP_LOGD(STATION_INFO_TAG, "Created StationInfo: %s (%s)", _name.c_str(), _code.c_str());
+}

main/external/mtr/station_info.h

@@ -0,0 +1,27 @@
+#pragma once
+#include "esp_log.h"
+#include "external/mtr/line_info.h"
+#include <string>
+
+#define STATION_INFO_TAG "StationInfo"
+
+// Forward declaration
+struct LineInfo;
+
+struct StationInfo {
+public:
+  StationInfo(cJSON* station_json);
+
+  const char* name() const { return _name.c_str(); }
+  const char* code() const { return _code.c_str(); }
+
+  friend class LineInfo;
+
+private:
+  // Caller transfers ownership of station_name and station_code to StationInfo
+  StationInfo(std::string& station_name, std::string& station_code)
+    : _name(station_name), _code(station_code) { }
+
+  std::string _name;
+  std::string _code;
+};

main/idf_component.yml

@@ -0,0 +1,21 @@
+## IDF Component Manager Manifest File
+dependencies:
+  ## Required IDF version
+  idf:
+    version: '>=4.1.0'
+  # # Put list of dependencies here
+  # # For components maintained by Espressif:
+  # component: "~1.0.0"
+  # # For 3rd party components:
+  # username/component: ">=1.0.0,<2.0.0"
+  # username2/component2:
+  #   version: "~1.0.0"
+  #   # For transient dependencies `public` flag can be set.
+  #   # `public` flag doesn't have an effect dependencies of the `main` component.
+  #   # All dependencies of `main` are public by default.
+  #   public: true
+  lvgl/lvgl: ^9.4.0
+  espressif/esp_lcd_touch_gt911: ^1.2.0~1
+  espressif/esp_lvgl_port: ^2.7.0
+  espressif/cjson: ^1.7.19
+  joltwallet/littlefs: ==1.20.3

main/info/info.cpp

@@ -0,0 +1,47 @@
+#include <stdio.h>
+#include <inttypes.h>
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_chip_info.h"
+#include "esp_flash.h"
+#include "esp_system.h"
+#include "esp_psram.h"
+#include "info.h"
+
+void display_chip_info() {
+
+  /* Print chip information */
+  esp_chip_info_t chip_info;
+  uint32_t flash_size;
+  esp_chip_info(&chip_info);
+  printf("This is %s chip with %d CPU core(s), %s%s%s%s%s, ",
+    CONFIG_IDF_TARGET,
+    chip_info.cores,
+    (chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
+    (chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
+    (chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
+    (chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread), " : "",
+    // psram
+    (chip_info.features & CHIP_FEATURE_EMB_PSRAM) ? "with embedded PSRAM, " : ""
+  );
+
+  unsigned major_rev = chip_info.revision / 100;
+  unsigned minor_rev = chip_info.revision % 100;
+  printf("silicon revision v%d.%d, ", major_rev, minor_rev);
+  if (esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
+    printf("Get flash size failed");
+    return;
+  }
+
+  printf("%" PRIu32 "MB %s flash\n", flash_size / (uint32_t)(1024 * 1024),
+    (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");
+
+  printf("Minimum free heap size: %" PRIu32 " bytes\n", esp_get_minimum_free_heap_size());
+  // psram
+  printf("PSRAM size: %u bytes\n", esp_psram_get_size());
+  // dma size
+  printf("DMA-capable memory size: %u bytes\n", heap_caps_get_free_size(MALLOC_CAP_DMA));
+  printf("DMA-capable internal memory size: %u bytes\n", heap_caps_get_free_size(MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL));
+
+}

main/info/info.h

@@ -0,0 +1 @@
+void display_chip_info();

main/io/fs_handler.cpp

@@ -0,0 +1,552 @@
+#include "io/fs_handler.h"
+#include <sys/stat.h>
+#include <dirent.h>
+#include <errno.h>
+#include <cstring>
+#include "esp_partition.h"
+
+#define TAG "LittleFSHandler"
+#define PARTITION_LABEL "storage"
+#define BLOCK_SIZE 512  // Match typical flash sector size
+
+//
+// FSGuard implementation
+//
+
+FSGuard::FSGuard(LittleFSHandler* fs_handler, const std::string& relative_path, const char* flags)
+  : fs_handler_(fs_handler), file_(nullptr) {
+  if (fs_handler_ != nullptr) {
+    fs_handler_->open_file_(relative_path, flags, file_);
+  } else {
+    ESP_LOGE("FSGuard", "FSGuard initialized with null LittleFSHandler");
+  }
+}
+
+FSGuard::~FSGuard() {
+  this->close();
+}
+
+esp_err_t FSGuard::close() {
+  if (file_ != nullptr && fs_handler_ != nullptr) {
+    esp_err_t err = fs_handler_->close_file_(file_);
+    file_ = nullptr;
+    fs_handler_ = nullptr;
+    if (err != ESP_OK) {
+      ESP_LOGE("FSGuard", "Error closing file: %s", esp_err_to_name(err));
+    }
+    return err;
+  }
+  return ESP_OK;
+}
+
+//
+// LittleFSHandler implementation
+//
+
+LittleFSHandler::LittleFSHandler() {
+  this->fs_mutex_ = xSemaphoreCreateMutex();
+  if (this->fs_mutex_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create filesystem mutex");
+  }
+}
+
+LittleFSHandler::~LittleFSHandler() {
+  if (this->is_initialized_()) {
+    esp_vfs_littlefs_unregister(PARTITION_LABEL);
+    this->initialized_ = false;
+  }
+  if (this->fs_mutex_ != nullptr) {
+    vSemaphoreDelete(this->fs_mutex_);
+    this->fs_mutex_ = nullptr;
+  }
+}
+
+esp_err_t LittleFSHandler::init(std::string base_path) {
+  // default config
+  esp_vfs_littlefs_conf_t config = {};
+  config.dont_mount = false;
+  config.partition_label = PARTITION_LABEL;
+  config.base_path = base_path.c_str();
+  config.format_if_mount_failed = true;
+  //
+  base_path_ = base_path;
+  return init(config);
+}
+
+esp_err_t LittleFSHandler::init(const esp_vfs_littlefs_conf_t& config) {
+  base_path_ = std::string(config.base_path);
+  if (this->is_initialized_()) {
+    ESP_LOGW(TAG, "LittleFS already initialized, skipping");
+    return ESP_OK;
+  }
+
+  esp_err_t err = esp_vfs_littlefs_register(&config);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize LittleFS: %s", esp_err_to_name(err));
+
+    if (err == ESP_ERR_NOT_FOUND) {
+      ESP_LOGE(TAG, "Listing all available partitions:");
+      esp_partition_iterator_t it = esp_partition_find(ESP_PARTITION_TYPE_ANY, ESP_PARTITION_SUBTYPE_ANY, NULL);
+      while (it != NULL) {
+        const esp_partition_t* part = esp_partition_get(it);
+        ESP_LOGE(TAG, "  - Label: '%s', Type: 0x%02x, Subtype: 0x%02x, Address: 0x%08x, Size: 0x%08x",
+          part->label, part->type, part->subtype, part->address, part->size);
+        it = esp_partition_next(it);
+      }
+      esp_partition_iterator_release(it);
+    }
+
+    return ESP_ERR_INVALID_STATE;
+  }
+  this->initialized_ = true;
+  return ESP_OK;
+}
+
+std::string LittleFSHandler::get_base_path() const {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized, cannot get base path");
+    return "";
+  }
+  return base_path_;
+}
+
+std::string LittleFSHandler::get_full_path(const std::string& relative_path) const {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized, cannot get full path");
+    return "";
+  }
+  return base_path_ + "/" + relative_path;
+}
+
+esp_err_t LittleFSHandler::write_file(const std::string& relative_path, const uint8_t* data, size_t size, size_t& out_bytes_written) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+  if (data == nullptr) {
+    ESP_LOGE(TAG, "Data pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  // Try to open with r+b first to preserve existing content for comparison
+  FSGuard file_guard(this, relative_path, "r+b");
+
+  // If file doesn't exist, open with wb
+  if (!file_guard.is_open()) {
+    FSGuard new_file_guard(this, relative_path, "wb");
+    if (!new_file_guard.is_open()) {
+      return ESP_ERR_NOT_FOUND;
+    }
+    return this->write_if_different_(new_file_guard.get_file(), data, size, out_bytes_written);
+  }
+  return this->write_if_different_(file_guard.get_file(), data, size, out_bytes_written);
+}
+
+
+// Caller is responsible for opening the file in appropriate mode
+// If the file doesn't exist, use write_file with "wb" mode
+// If the file exists, use "r+b" mode to read and write
+esp_err_t LittleFSHandler::write_file(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written) {
+  return this->write_if_different_(file, data, size, out_bytes_written);
+}
+
+esp_err_t LittleFSHandler::append_file(const std::string& relative_path, const uint8_t* data, size_t size, size_t& out_bytes_written) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+  if (data == nullptr) {
+    ESP_LOGE(TAG, "Data pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  FSGuard file_guard(this, relative_path, "ab");
+  FILE* file = file_guard.get_file();
+  if (file == nullptr) {
+    return ESP_ERR_NOT_FOUND;
+  }
+  return this->append_file(file, data, size, out_bytes_written);
+}
+
+esp_err_t LittleFSHandler::append_file(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written) {
+  if (file == nullptr) {
+    ESP_LOGE(TAG, "File pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+  if (data == nullptr) {
+    ESP_LOGE(TAG, "Data pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  if (fseek(file, 0, SEEK_END) != 0) {
+    ESP_LOGE(TAG, "Failed to seek to end of file");
+    return ESP_ERR_INVALID_STATE;
+  }
+  // write data with POSIX
+  size_t bytes_written = fwrite(data, 1, size, file);
+  if (bytes_written != size) {
+    ESP_LOGE(TAG, "Failed to write all data to file, expected %zu bytes, wrote %zu bytes", size, bytes_written);
+    return ESP_ERR_NO_MEM;
+  }
+  if (fflush(file) != 0) {
+    ESP_LOGE(TAG, "Failed to flush file");
+    return ESP_ERR_INVALID_STATE;
+  }
+  out_bytes_written = bytes_written;
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::read_file(const std::string& relative_path, const size_t max_size, uint8_t* out_data, size_t& out_size) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+  if (out_data == nullptr) {
+    ESP_LOGE(TAG, "Output data pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  FSGuard file_guard(this, relative_path, "rb");
+  FILE* file = file_guard.get_file();
+  if (file == nullptr) {
+    return ESP_ERR_NOT_FOUND;
+  }
+  return this->read_file(file, max_size, out_data, out_size);
+}
+
+esp_err_t LittleFSHandler::read_file(FILE* file, const size_t max_size, uint8_t* out_data, size_t& out_size) {
+  if (file == nullptr) {
+    ESP_LOGE(TAG, "File pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+  if (out_data == nullptr) {
+    ESP_LOGE(TAG, "Output data pointer is null");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  size_t bytes_read = fread(out_data, 1, max_size, file);
+  if (bytes_read == 0 && ferror(file)) {
+    ESP_LOGE(TAG, "Failed to read from file");
+    return ESP_ERR_INVALID_STATE;
+  }
+  out_size = bytes_read;
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::delete_file(const std::string& relative_path) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  std::string full_path = this->get_full_path(relative_path);
+  if (remove(full_path.c_str()) != 0) {
+    ESP_LOGE(TAG, "Failed to delete file %s: %s", full_path.c_str(), strerror(errno));
+    return ESP_ERR_NOT_FOUND;
+  }
+  return ESP_OK;
+}
+
+bool LittleFSHandler::file_exists(const std::string& relative_path) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return false;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return false;
+  }
+
+  std::string full_path = this->get_full_path(relative_path);
+  struct stat st;
+  return (stat(full_path.c_str(), &st) == 0 && S_ISREG(st.st_mode));
+}
+
+esp_err_t LittleFSHandler::get_file_size(const std::string& relative_path, size_t& out_size) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  std::string full_path = this->get_full_path(relative_path);
+  struct stat st;
+  if (stat(full_path.c_str(), &st) != 0) {
+    ESP_LOGE(TAG, "Failed to stat file %s", full_path.c_str());
+    return ESP_ERR_NOT_FOUND;
+  }
+  out_size = st.st_size;
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::create_directory(const std::string& relative_path) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  std::string full_path = this->get_full_path(relative_path);
+  if (mkdir(full_path.c_str(), 0755) != 0) {
+    if (errno == EEXIST) {
+      ESP_LOGW(TAG, "Directory %s already exists", full_path.c_str());
+      return ESP_OK;
+    }
+    ESP_LOGE(TAG, "Failed to create directory %s: %s", full_path.c_str(), strerror(errno));
+    return ESP_ERR_INVALID_STATE;
+  }
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::list_directory(const std::string& relative_path, std::vector<std::string>& out_entries) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  SemaphoreGuard guard(this->fs_mutex_);
+  if (guard.take() != pdTRUE) {
+    ESP_LOGE(TAG, "Failed to acquire filesystem mutex");
+    return ESP_ERR_TIMEOUT;
+  }
+
+  std::string full_path = this->get_full_path(relative_path);
+  DIR* dir = opendir(full_path.c_str());
+  if (dir == nullptr) {
+    ESP_LOGE(TAG, "Failed to open directory %s", full_path.c_str());
+    return ESP_ERR_NOT_FOUND;
+  }
+
+  out_entries.clear();
+  struct dirent* entry;
+  while ((entry = readdir(dir)) != nullptr) {
+    // Skip . and ..
+    if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) {
+      continue;
+    }
+    out_entries.push_back(entry->d_name);
+  }
+  closedir(dir);
+  return ESP_OK;
+}
+
+//
+// Private methods
+//
+
+esp_err_t LittleFSHandler::open_file_(const std::string& relative_path, const char* flags, FILE*& out_file) {
+  if (!this->is_initialized_()) {
+    ESP_LOGE(TAG, "LittleFS is not initialized, cannot open file");
+    return ESP_ERR_INVALID_STATE;
+  }
+  std::string full_path = this->get_full_path(relative_path);
+  FILE* file = fopen(full_path.c_str(), flags);
+  if (file == nullptr) {
+    // Use debug level if file doesn't exist (ENOENT), warning level for other errors
+    if (errno == ENOENT) {
+      ESP_LOGD(TAG, "File %s does not exist (flags %s)", full_path.c_str(), flags);
+    } else {
+      ESP_LOGW(TAG, "Failed to open file %s with flags %s: %s", full_path.c_str(), flags, strerror(errno));
+    }
+    return ESP_ERR_NOT_FOUND;
+  }
+  out_file = file;
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::close_file_(FILE* file) {
+  if (file == nullptr) {
+    return ESP_OK;
+  }
+  if (fclose(file) != 0) {
+    ESP_LOGE(TAG, "Failed to close file: %s", strerror(errno));
+    return ESP_ERR_INVALID_STATE;
+  }
+  return ESP_OK;
+}
+
+esp_err_t LittleFSHandler::write_if_different_(FILE* file, const uint8_t* data, size_t size) {
+  size_t out_bytes_written = 0;
+  return this->write_if_different_(file, data, size, out_bytes_written);
+}
+
+esp_err_t LittleFSHandler::write_if_different_(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written) {
+  if (file == nullptr || data == nullptr) {
+    ESP_LOGE(TAG, "Invalid parameters");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  // Get existing file size
+  if (fseek(file, 0, SEEK_END) != 0) {
+    ESP_LOGE(TAG, "Failed to seek to end of file");
+    return ESP_ERR_INVALID_STATE;
+  }
+  long file_size_long = ftell(file);
+  if (file_size_long < 0) {
+    ESP_LOGE(TAG, "Failed to get file size");
+    return ESP_ERR_INVALID_STATE;
+  }
+  size_t file_size = (size_t)file_size_long;
+
+  if (fseek(file, 0, SEEK_SET) != 0) {
+    ESP_LOGE(TAG, "Failed to seek to beginning of file");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  out_bytes_written = 0;
+  size_t compare_size = (file_size < size) ? file_size : size;
+
+  // Read entire file content for comparison
+  std::vector<uint8_t> existing_data;
+  if (file_size > 0) {
+    existing_data.resize(file_size);
+    size_t bytes_read = fread(existing_data.data(), 1, file_size, file);
+    if (bytes_read != file_size) {
+      ESP_LOGE(TAG, "Failed to read existing file data");
+      return ESP_ERR_INVALID_STATE;
+    }
+  }
+
+  // Compare and identify blocks that need updating
+  std::vector<bool> block_needs_update((size + BLOCK_SIZE - 1) / BLOCK_SIZE, false);
+  bool any_changes = false;
+
+  for (size_t offset = 0; offset < compare_size; offset += BLOCK_SIZE) {
+    size_t chunk_size = BLOCK_SIZE;
+    if (offset + chunk_size > compare_size) {
+      chunk_size = compare_size - offset;
+    }
+
+    if (memcmp(existing_data.data() + offset, data + offset, chunk_size) != 0) {
+      block_needs_update[offset / BLOCK_SIZE] = true;
+      any_changes = true;
+    }
+  }
+
+  // Check if size changed or there are additional blocks to write
+  if (size != file_size) {
+    any_changes = true;
+  }
+
+  if (!any_changes) {
+    ESP_LOGD(TAG, "File content unchanged, skipping write");
+    return ESP_OK;
+  }
+
+  // Seek to beginning to start writing
+  if (fseek(file, 0, SEEK_SET) != 0) {
+    ESP_LOGE(TAG, "Failed to seek to beginning for writing");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  // Write only changed blocks
+  for (size_t offset = 0; offset < compare_size; offset += BLOCK_SIZE) {
+    size_t block_index = offset / BLOCK_SIZE;
+    if (!block_needs_update[block_index]) {
+      // Skip unchanged block
+      if (fseek(file, offset + BLOCK_SIZE, SEEK_SET) != 0) {
+        // If at end of compare region, this is OK
+        if (offset + BLOCK_SIZE > compare_size) {
+          if (fseek(file, compare_size, SEEK_SET) != 0) {
+            ESP_LOGE(TAG, "Failed to seek past unchanged block");
+            return ESP_ERR_INVALID_STATE;
+          }
+        } else {
+          ESP_LOGE(TAG, "Failed to seek past unchanged block at %zu", offset);
+          return ESP_ERR_INVALID_STATE;
+        }
+      }
+      continue;
+    }
+
+    size_t chunk_size = BLOCK_SIZE;
+    if (offset + chunk_size > compare_size) {
+      chunk_size = compare_size - offset;
+    }
+
+    if (fseek(file, offset, SEEK_SET) != 0) {
+      ESP_LOGE(TAG, "Failed to seek to offset %zu", offset);
+      return ESP_ERR_INVALID_STATE;
+    }
+
+    size_t written = fwrite(data + offset, 1, chunk_size, file);
+    if (written != chunk_size) {
+      ESP_LOGE(TAG, "Failed to write block at offset %zu", offset);
+      return ESP_ERR_INVALID_STATE;
+    }
+    out_bytes_written += written;
+  }
+
+  // Handle size differences
+  if (size > file_size) {
+    // Write additional data beyond original file size
+    if (fseek(file, file_size, SEEK_SET) != 0) {
+      ESP_LOGE(TAG, "Failed to seek to end for appending");
+      return ESP_ERR_INVALID_STATE;
+    }
+    size_t written = fwrite(data + file_size, 1, size - file_size, file);
+    if (written != (size - file_size)) {
+      ESP_LOGE(TAG, "Failed to write additional data");
+      return ESP_ERR_INVALID_STATE;
+    }
+    out_bytes_written += written;
+  } else if (size < file_size) {
+    // Truncate file to new size
+    if (ftruncate(fileno(file), size) != 0) {
+      ESP_LOGE(TAG, "Failed to truncate file to size %zu", size);
+      return ESP_ERR_INVALID_STATE;
+    }
+  }
+
+  // Flush to ensure data is written to storage
+  if (fflush(file) != 0) {
+    ESP_LOGE(TAG, "Failed to flush file after write");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  return ESP_OK;
+}
+
+bool LittleFSHandler::is_initialized_() const {
+  return this->initialized_;
+}
+
+
+
+

main/io/fs_handler.h

@@ -0,0 +1,95 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "esp_littlefs.h"
+#include "esp_err.h"
+#include <string>
+#include <vector>
+#include <map>
+#include <memory>
+#include "esp_log.h"
+#include <semaphore_guard.h>
+
+// Forward declaration
+class LittleFSHandler;
+
+class FSGuard {
+public:
+  FSGuard(LittleFSHandler* fs_handler, const std::string& relative_path, const char* flags);
+  ~FSGuard();
+
+  esp_err_t close();
+
+  FILE* get_file() {
+    return file_;
+  }
+
+  bool is_open() const {
+    return file_ != nullptr;
+  }
+
+private:
+  LittleFSHandler* fs_handler_ = nullptr;
+  FILE* file_;
+
+  // prevent copying and moving
+  FSGuard(const FSGuard&) = delete;
+  FSGuard& operator=(const FSGuard&) = delete;
+  FSGuard(FSGuard&& other) = delete;
+  FSGuard& operator=(FSGuard&& other) = delete;
+};
+
+//LittleFSHandler interface
+// All paths are relative to the mounted filesystem root
+// Implementations should handle initialization of the filesystem, and mounting if necessary
+// When destroyed, implementations should unmount the filesystem if necessary
+// All paths are relative to the mounted filesystem root, e.g. if mounted at /littlefs, and file is /data.txt, the full path is /littlefs/data.txt
+// File operations use standard C FILE* wrapped in FSGuard for RAII
+class LittleFSHandler {
+public:
+  LittleFSHandler();
+  ~LittleFSHandler();
+
+  esp_err_t init(std::string base_path);
+  esp_err_t init(const esp_vfs_littlefs_conf_t& config);
+  std::string get_base_path() const;
+  std::string get_full_path(const std::string& relative_path) const;
+  // File operations
+  esp_err_t write_file(const std::string& relative_path, const uint8_t* data, size_t size, size_t& out_bytes_written);
+  esp_err_t write_file(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written);
+  //
+  esp_err_t append_file(const std::string& relative_path, const uint8_t* data, size_t size, size_t& out_bytes_written);
+  esp_err_t append_file(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written);
+  //
+  esp_err_t read_file(const std::string& relative_path, const size_t max_size, uint8_t* out_data, size_t& out_size);
+  esp_err_t read_file(FILE* file, const size_t max_size, uint8_t* out_data, size_t& out_size);
+  //
+  esp_err_t delete_file(const std::string& relative_path);
+  //
+  bool file_exists(const std::string& relative_path);
+  esp_err_t get_file_size(const std::string& relative_path, size_t& out_size);
+  // Directory operations
+  esp_err_t create_directory(const std::string& relative_path);
+  esp_err_t list_directory(const std::string& relative_path, std::vector<std::string>& out_entries);
+
+protected:
+
+  esp_err_t open_file_(const std::string& relative_path, const char* flags, FILE*& out_file);
+  esp_err_t close_file_(FILE* file);
+
+  // uses standard C FILE* for file operations
+  esp_err_t write_if_different_(FILE* file, const uint8_t* data, size_t size);
+  esp_err_t write_if_different_(FILE* file, const uint8_t* data, size_t size, size_t& out_bytes_written);
+
+  friend class FSGuard;
+
+private:
+  //
+  bool is_initialized_() const;
+
+  SemaphoreHandle_t fs_mutex_ = nullptr;
+  bool initialized_ = false;
+  std::string base_path_;
+};
+
+

main/io/io.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+#include <memory>
+
+typedef bool(*FilterFunc)(const std::string& key);
+typedef void (*KeyValueProcessor)(void* arg, const std::string& key, const std::string& value);
+
+class KVStorageHandler {
+public:
+  virtual ~KVStorageHandler() = default;
+
+  virtual void init(const EventGroupHandle_t& system_event_group) = 0;
+
+  // Store a key-value pair
+  virtual void put(const std::string& key, const std::string& value) = 0;
+
+  // Retrieve a value by key, returns empty string if key not found
+  virtual std::string get(const std::string& key) const = 0;
+  virtual esp_err_t process_all(KeyValueProcessor processor, void* arg) const = 0;
+  virtual esp_err_t process_filtered(const std::string& key_prefix, KeyValueProcessor processor, void* arg) const = 0;
+  virtual esp_err_t process_filtered(FilterFunc filter_func, KeyValueProcessor processor, void* arg) const = 0;
+
+  // Delete a key-value pair
+  virtual void remove(const std::string& key) = 0;
+};

main/io/nvs_handler.cpp

@@ -0,0 +1,207 @@
+#include "common/constants.h"
+#include "io/nvs_handler.h"
+#include "nvs_flash.h"
+#include "string.h"
+#include "esp_log.h"
+
+#define TAG "NVSStorageHandler"
+
+NVSStorageHandler::NVSStorageHandler(
+  const char* name_space
+) : name_space(name_space) { }
+
+NVSStorageHandler::~NVSStorageHandler() {
+  if (this->nvsHandle != 0) {
+    nvs_close(this->nvsHandle);
+    this->nvsHandle = 0;
+  }
+}
+
+void NVSStorageHandler::init(const EventGroupHandle_t& system_event_group) {
+  esp_err_t err = nvs_flash_init();
+  if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+    ESP_LOGW(TAG, "NVS Flash init failed with %s, erasing and retrying...", esp_err_to_name(err));
+    nvs_flash_erase();
+    err = nvs_flash_init();
+  }
+  ESP_ERROR_CHECK(err);
+
+  err = nvs_open(this->name_space, NVS_READWRITE, &this->nvsHandle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) opening NVS handle!", esp_err_to_name(err));
+  } else {
+    if (system_event_group != nullptr) {
+      xEventGroupSetBits(system_event_group, STORAGE_READY_BIT);
+    }
+    ESP_LOGI(TAG, "NVS Storage initialized.");
+  }
+}
+
+void NVSStorageHandler::put(const std::string& key, const std::string& value) {
+  if (this->nvsHandle == 0) {
+    ESP_LOGE(TAG, "NVS handle is not initialized.");
+    return;
+  }
+
+  esp_err_t err = nvs_set_str(this->nvsHandle, key.c_str(), value.c_str());
+  if (err == ESP_ERR_NVS_NOT_ENOUGH_SPACE) {
+    ESP_LOGE(TAG, "NVS storage full! Cannot store key '%s'. Consider clearing old data.", key.c_str());
+    ESP_LOGI(TAG, "Attempting to erase and retry...");
+    // Try to commit pending changes first
+    nvs_commit(this->nvsHandle);
+    // Retry once
+    err = nvs_set_str(this->nvsHandle, key.c_str(), value.c_str());
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Retry failed: %s", esp_err_to_name(err));
+      return;
+    }
+  } else if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) setting key-value pair in NVS!", esp_err_to_name(err));
+    return;
+  }
+
+  // Commit successful write
+  err = nvs_commit(this->nvsHandle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) committing to NVS!", esp_err_to_name(err));
+  }
+}
+
+std::string NVSStorageHandler::get(const std::string& key) const {
+  if (this->nvsHandle == 0) {
+    ESP_LOGE(TAG, "NVS handle is not initialized.");
+    return "";
+  }
+
+  size_t required_size = 0;
+  esp_err_t err = nvs_get_str(this->nvsHandle, key.c_str(), nullptr, &required_size);
+  if (err == ESP_ERR_NVS_NOT_FOUND) {
+    ESP_LOGW(TAG, "Key %s not found in NVS.", key.c_str());
+    return "";
+  } else if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) getting size for key %s from NVS!", esp_err_to_name(err), key.c_str());
+    return "";
+  }
+
+  // Allocate string buffer with correct size (includes null terminator)
+  std::string value(required_size - 1, '\0');
+  err = nvs_get_str(this->nvsHandle, key.c_str(), &value[0], &required_size);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) getting value for key %s from NVS!", esp_err_to_name(err), key.c_str());
+    return "";
+  }
+
+  return value;
+}
+
+NVSIteratorGuard NVSStorageHandler::create_iterator() const {
+  nvs_iterator_t it = nullptr;
+  esp_err_t err = nvs_entry_find(NVS_DEFAULT_PART_NAME, this->name_space, NVS_TYPE_ANY, &it);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) creating NVS iterator!", esp_err_to_name(err));
+    return NVSIteratorGuard(nullptr, err);
+  }
+
+  return NVSIteratorGuard(it, ESP_OK);
+}
+
+esp_err_t NVSStorageHandler::process_all(KeyValueProcessor processor, void* arg) const {
+  NVSIteratorGuard iterator_guard = this->create_iterator();
+  if (!iterator_guard.is_valid()) {
+    return iterator_guard.get_error();
+  }
+  const nvs_iterator_t& it = iterator_guard.get_iterator();
+
+  for (; it != NULL; iterator_guard.advance_iter()) {
+    nvs_entry_info_t info;
+    esp_err_t err = nvs_entry_info(it, &info);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Error (%s) getting NVS entry info!", esp_err_to_name(err));
+      return err;
+    }
+    nvs_handle_t temp_handle;
+    err = nvs_open(this->name_space, NVS_READONLY, &temp_handle);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Error (%s) opening NVS handle for reading!", esp_err_to_name(err));
+      return err;
+    }
+
+    // call the processor with the key and value
+    std::string key_str = info.key;
+    processor(arg, key_str, this->get(key_str));
+  }
+  return ESP_OK;
+}
+esp_err_t NVSStorageHandler::process_filtered(const std::string& key_prefix, KeyValueProcessor processor, void* arg) const {
+  NVSIteratorGuard iterator_guard = this->create_iterator();
+  if (!iterator_guard.is_valid()) {
+    return iterator_guard.get_error();
+  }
+  const nvs_iterator_t& it = iterator_guard.get_iterator();
+
+  for (; it != NULL; iterator_guard.advance_iter()) {
+    nvs_entry_info_t info;
+    esp_err_t err = nvs_entry_info(it, &info);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Error (%s) getting NVS entry info!", esp_err_to_name(err));
+      return err;
+    }
+    // check if the key matches the prefix
+    if (strncmp(info.key, key_prefix.c_str(), key_prefix.length()) == 0) {
+      nvs_handle_t temp_handle;
+      err = nvs_open(this->name_space, NVS_READONLY, &temp_handle);
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Error (%s) opening NVS handle for reading!", esp_err_to_name(err));
+        return err;
+      }
+      // call the processor with the key and value
+      processor(arg, std::string(info.key), this->get(std::string(info.key)));
+    }
+  }
+  return ESP_OK;
+}
+
+esp_err_t NVSStorageHandler::process_filtered(FilterFunc filter_func, KeyValueProcessor processor, void* arg) const {
+  NVSIteratorGuard iterator_guard = this->create_iterator();
+  if (!iterator_guard.is_valid()) {
+    return iterator_guard.get_error();
+  }
+  const nvs_iterator_t& it = iterator_guard.get_iterator();
+
+  for (; it != NULL; iterator_guard.advance_iter()) {
+    nvs_entry_info_t info;
+    esp_err_t err = nvs_entry_info(it, &info);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Error (%s) getting NVS entry info!", esp_err_to_name(err));
+      return err;
+    }
+    // check if the key matches the filter function
+    std::string key_str(info.key);
+    if (filter_func(key_str)) {
+      nvs_handle_t temp_handle;
+      err = nvs_open(this->name_space, NVS_READONLY, &temp_handle);
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Error (%s) opening NVS handle for reading!", esp_err_to_name(err));
+        return err;
+      }
+      // call the processor with the key and value
+      processor(arg, key_str, this->get(key_str));
+    }
+  }
+  return ESP_OK;
+}
+
+void NVSStorageHandler::remove(const std::string& key) {
+  if (this->nvsHandle == 0) {
+    ESP_LOGE(TAG, "NVS handle is not initialized.");
+    return;
+  }
+
+  esp_err_t err = nvs_erase_key(this->nvsHandle, key.c_str());
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error (%s) deleting key %s from NVS!", esp_err_to_name(err), key.c_str());
+  } else {
+    nvs_commit(this->nvsHandle);
+    ESP_LOGI(TAG, "Key %s deleted from NVS.", key.c_str());
+  }
+}

main/io/nvs_handler.h

@@ -0,0 +1,70 @@
+#pragma once
+#include "io/io.h"
+#include "freertos/FreeRTOS.h"
+#include "nvs.h"
+
+struct NVSIteratorGuard {
+public:
+  ~NVSIteratorGuard() {
+    if (iterator) {
+      nvs_release_iterator(iterator);
+    }
+  }
+
+  // accessors to the iterator, the internal state should not be modified directly
+  // The iterator is advanced using advance_iter(), and is changed to nullptr on error or end
+  // Caller MUST NOT release the iterator manually nor call get_iterator after advance_iter
+  const nvs_iterator_t& get_iterator() const {
+    return iterator;
+  }
+
+  void advance_iter() {
+    if (iterator) {
+      // advance the iterator and update the internal state
+      esp_err_t err = nvs_entry_next(&iterator);
+      if (err != ESP_OK) {
+        error = err;
+        iterator = nullptr;
+      }
+    }
+  }
+
+  esp_err_t get_error() const {
+    return error;
+  }
+  bool is_valid() const {
+    return iterator != nullptr && error == ESP_OK;
+  }
+  friend class NVSStorageHandler;
+private:
+  NVSIteratorGuard(nvs_iterator_t it
+    , esp_err_t err
+  ) : iterator(it), error(err) { }
+  nvs_iterator_t iterator;
+  esp_err_t error;
+};
+
+class NVSStorageHandler : public KVStorageHandler {
+public:
+  NVSStorageHandler(
+    const char* name_space
+  );
+  ~NVSStorageHandler() override;
+
+  void init(const EventGroupHandle_t& system_event_group) override;
+
+  void put(const std::string& key, const std::string& value) override;
+
+  std::string get(const std::string& key) const override;
+  esp_err_t process_all(KeyValueProcessor processor, void* arg) const override;
+  esp_err_t process_filtered(const std::string& key_prefix, KeyValueProcessor processor, void* arg) const override;
+  esp_err_t process_filtered(FilterFunc filter_func, KeyValueProcessor processor, void* arg) const override;
+
+  void remove(const std::string& key) override;
+
+private:
+  NVSIteratorGuard create_iterator() const;
+
+  nvs_handle_t nvsHandle = 0;
+  const char* name_space;
+};

main/lv_conf.h

@@ -0,0 +1 @@
+// placeholder file to avoid build errors, the actual lv_conf.h will be injected by esp-idf during build

main/main.cpp

@@ -0,0 +1,197 @@
+#include <stdio.h>
+#include <inttypes.h>
+#include <stdexcept>
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_chip_info.h"
+#include "esp_flash.h"
+#include "esp_system.h"
+#include "esp_log.h"
+
+//
+#include "common/constants.h"
+#include "common/queue_defs.h"
+#include "io/nvs_handler.h"
+#include "io/fs_handler.h"
+#include "info/info.h"
+#include "display/eink_display_handler.h"
+#include "display/lvgl_handler.h"
+#include "ui/ui_handler.h"
+#include "ui/apps/registry.h"
+#include <tick/lv_tick.h>
+#include "esp_lvgl_port.h"
+#include "lvgl.h"
+#include "network.h"
+#include <esp_task_wdt.h>
+
+#include "lvgl.h"
+
+// nvs storage namespaces, 15 characters max
+#define DEFAULT_STORAGE_NAMESPACE "storage"
+#define TAG "Main"
+
+extern "C" void app_main(void);
+
+void init_queues(
+  QueueHandle_t& touch_queue,
+  EventGroupHandle_t& system_event_group,
+  EventGroupHandle_t& system_lifecycle_event_group
+);
+
+void app_main(void) {
+  display_chip_info();
+
+  QueueHandle_t touch_event_queue = NULL;
+  EventGroupHandle_t system_event_group = NULL, system_lifecycle_event_group = NULL;
+
+  init_queues(touch_event_queue, system_event_group, system_lifecycle_event_group);
+  if (touch_event_queue == NULL || system_event_group == NULL || system_lifecycle_event_group == NULL) {
+    ESP_LOGE("Main", "Failed to create one or more queues/event groups");
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return esp_restart();
+  }
+  ESP_LOGI(TAG, "Queues initialized.\n");
+
+  //
+  KVStorageHandler* kv_storage_handler = new NVSStorageHandler(
+    DEFAULT_STORAGE_NAMESPACE
+  );
+
+  auto fs_handler = std::make_shared<LittleFSHandler>();
+  esp_err_t fs_err = fs_handler->init("/littlefs");
+  if (fs_err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize LittleFS: %s", esp_err_to_name(fs_err));
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return esp_restart();
+  }
+
+  auto wifi_handler = std::make_unique<WifiHandler>(fs_handler);
+  NetworkHandler* network_handler = new NetworkHandler(std::move(wifi_handler));
+  EInkDisplayHandler* display_handler = new EInkDisplayHandler();
+  // Initialize display and touch
+  // display_handler->init_devices(system_event_group);
+  display_handler->init_devices();
+  ESP_LOGI(TAG, "E-Ink display handler initialized.\n");
+  // LVGL Handler
+  std::unique_ptr<EInkDisplayHandler> display_uptr(display_handler);
+  LVGLHandler lvgl_handler(std::move(display_uptr));
+  esp_err_t err = lvgl_handler.initLVGL(system_event_group);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize LVGL handler: %s", esp_err_to_name(err));
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return esp_restart();
+  }
+
+  //
+  kv_storage_handler->init(system_event_group);
+  network_handler->init(system_event_group);
+
+  //
+  ESP_LOGI(TAG, "Waiting for system to be ready...\n");
+  xEventGroupWaitBits(
+    system_event_group,
+    // DISPLAY_READY_BIT | STORAGE_READY_BIT | NETWORK_READY_BIT,
+    DISPLAY_READY_BIT,
+    // do not clear on exit, require explicit reset
+    pdFALSE,
+    pdTRUE,
+    portMAX_DELAY
+  );
+  ESP_LOGI(TAG, "System is ready. Starting main application...\n");
+
+  // DiscordAppDescriptor::instance();
+  UIHandler ui_handler;
+  err = ui_handler.init();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize UI handler: %s", esp_err_to_name(err));
+    vTaskDelay(5000 / portTICK_PERIOD_MS);
+    return esp_restart();
+  }
+  ESP_LOGI(TAG, "UI handler initialized.\n");
+
+  // Allow LVGL system to stabilize before creating objects
+  vTaskDelay(pdMS_TO_TICKS(100));
+
+  // wait for shutdown signal
+  ESP_LOGI(TAG, "Waiting for shutdown signal...\n");
+  EventBits_t bits = xEventGroupWaitBits(
+    system_lifecycle_event_group,
+    SYSTEM_SHUTDOWN_BIT | SYSTEM_RESTART_BIT,
+    // do not clear on exit, require explicit reset
+    pdFALSE,
+    pdFALSE,
+    portMAX_DELAY
+  );
+  ESP_LOGI(TAG, "Shutdown signal received. Cleaning up...\n");
+
+  // Show shutdown screen using the shutdown descriptor's app instance
+  // ShutdownApp* shutdown_app = dynamic_cast<ShutdownApp*>(shutdown_descriptor->get_app_instance());
+  // if (shutdown_app) {
+  //   ui_handler.switch_app(shutdown_app);
+  // }
+  vTaskDelay(1000 / portTICK_PERIOD_MS);  // Display shutdown message briefly
+
+  // Cleanup
+  // ui_handler.deinit();
+  // delete demo_descriptor;
+  // delete shutdown_descriptor;
+  // delete mtr_descriptor;
+
+  vEventGroupDelete(system_event_group);
+  vQueueDelete(touch_event_queue);
+  ESP_LOGI(TAG, "Cleanup complete.\n");
+
+  // handle shutdown or restart
+  if (bits & SYSTEM_SHUTDOWN_BIT) {
+    // if (shutdown_display_handler != nullptr) {
+    //   ESP_LOGI(TAG, "Calling display shutdown handler...\n");
+    //   shutdown_display_handler();
+    // } else {
+    //   ESP_LOGI(TAG, "No display shutdown handler to call.\n");
+    // }
+    ESP_LOGI(TAG, "System is shutting down.\n");
+    fflush(stdout);
+    // wait for start bit to be set again if future restart is desired, else expect manual power cycle
+    EventBits_t bits = xEventGroupWaitBits(
+      system_lifecycle_event_group,
+      SYSTEM_START_BIT,
+      pdFALSE,
+      pdFALSE,
+      portMAX_DELAY
+    );
+    if (bits & SYSTEM_START_BIT) {
+      ESP_LOGI(TAG, "SYSTEM_START_BIT received, restarting system.\n");
+    } else {
+      ESP_LOGW(TAG, "No restart signal received, waiting for manual power cycle.\n");
+      while (true) {
+        vTaskDelay(portMAX_DELAY);
+      }
+    }
+  } else if (bits & SYSTEM_RESTART_BIT) {
+    // if (restart_display_handler != nullptr) {
+    //   ESP_LOGI(TAG, "Calling display restart handler...\n");
+    //   restart_display_handler();
+    // } else {
+    //   ESP_LOGI(TAG, "No display restart handler to call.\n");
+    // }
+    ESP_LOGI(TAG, "System is restarting.\n");
+    fflush(stdout);
+  } else {
+    ESP_LOGW(TAG, "Unknown shutdown signal received. Restarting by default.\n");
+    fflush(stdout);
+  }
+
+  return esp_restart();
+}
+
+void init_queues(
+  QueueHandle_t& touch_queue,
+  EventGroupHandle_t& system_event_group,
+  EventGroupHandle_t& system_lifecycle_event_group
+) {
+  // Implementation of queue initialization
+  touch_queue = xQueueCreate(10, sizeof(touch_event_t));
+  system_event_group = xEventGroupCreate();
+  system_lifecycle_event_group = xEventGroupCreate();
+}

main/network/http_handler.cpp

@@ -0,0 +1,51 @@
+#include "network/http_handler.h"
+#include "esp_http_client.h"
+#include "esp_log.h"
+#include "string.h"
+
+HttpHandler::HttpHandler(const esp_http_client_config_t&& config, WifiHandler* wifiHandler)
+  : wifiHandler(wifiHandler) {
+  this->client = esp_http_client_init(&config);
+}
+
+HttpHandler::~HttpHandler() {
+  if (this->client) {
+    esp_http_client_cleanup(this->client);
+  }
+}
+
+esp_err_t HttpHandler::set_method(esp_http_client_method_t method) {
+  return esp_http_client_set_method(this->client, method);
+}
+
+esp_err_t HttpHandler::set_header(const char* header, const char* value) {
+  return esp_http_client_set_header(this->client, header, value);
+}
+
+esp_err_t HttpHandler::set_post_field(const char* field, size_t len) {
+  return esp_http_client_set_post_field(this->client, field, len);
+}
+
+esp_err_t HttpHandler::perform_request() {
+  return esp_http_client_perform(this->client);
+}
+
+void HttpHandler::get_body(
+  char*& buffer,
+  int& total_len
+) {
+  total_len = esp_http_client_get_content_length(this->client);
+  buffer = new char[total_len + 1]; // +1 for null-terminator
+  if (buffer) {
+    int read_len = esp_http_client_read(this->client, buffer, total_len);
+    if (read_len >= 0) {
+      buffer[read_len] = '\0'; // null-terminate
+    } else {
+      delete[] buffer;
+      buffer = nullptr;
+      total_len = 0;
+    }
+  } else {
+    total_len = 0;
+  }
+}

main/network/http_handler.h

@@ -0,0 +1,55 @@
+#pragma once
+#include <memory>
+#include "esp_http_client.h"
+#include "network/wifi_handler.h"
+
+// forward declare NetworkHandler to avoid circular include with network.h
+class NetworkHandler;
+
+// default config values for esp_http_client_config_t
+// disable Wmissing-field-initializers warning for these structs
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wmissing-field-initializers"
+static const inline esp_http_client_config_t DEFAULT_HTTP_CLIENT_CONFIG = {
+  .timeout_ms = 10000,
+};
+
+static const inline esp_http_client_config_t DEFAULT_HTTP_CLIENT_CONFIG_HTTPS = {
+  .transport_type = HTTP_TRANSPORT_OVER_SSL,
+  //
+  .use_global_ca_store = true,
+  .skip_cert_common_name_check = false,
+};
+#pragma GCC diagnostic pop
+
+// esp http client wrapper with automatic initialization and cleanup
+class HttpHandler {
+public:
+  ~HttpHandler();
+
+  esp_err_t set_method(esp_http_client_method_t method);
+  esp_err_t set_header(const char* header, const char* value);
+  esp_err_t set_post_field(const char* field, size_t len);
+  //
+  esp_err_t perform_request();
+  // buffer is allocated inside the method, caller must free it
+  void get_body(
+    char*& buffer,
+    int& total_len
+  );
+
+
+  // only NetworkHandler can create HttpHandler instances
+  friend class NetworkHandler;
+  // disable copy constructor and assignment operator
+  HttpHandler(const HttpHandler&) = delete;
+  HttpHandler& operator=(const HttpHandler&) = delete;
+
+private:
+  // private constructor, only NetworkHandler can create instances
+  HttpHandler(const esp_http_client_config_t&& config, WifiHandler* wifiHandler);
+
+  esp_http_client_handle_t client;
+  // backreference to WifiHandler to ensure WiFi is connected, DO NOT DELETE
+  WifiHandler* wifiHandler;
+};

main/network/network.cpp

@@ -0,0 +1,32 @@
+#include "esp_log.h"
+#include "network/network.h"
+#include "network/http_handler.h"
+#include "common/constants.h"
+
+NetworkHandler::NetworkHandler(
+  std::unique_ptr<WifiHandler> wifiHandler
+) : wifiHandler(std::move(wifiHandler)) { }
+
+NetworkHandler::~NetworkHandler() { }
+
+void NetworkHandler::init(EventGroupHandle_t system_event_group) {
+  if (this->initialized) {
+    ESP_LOGW("NetworkHandler", "Already initialized, skipping");
+    return;
+  }
+  this->wifiHandler->init();
+  this->initialized = true;
+  xEventGroupSetBits(
+    system_event_group,
+    NETWORK_READY_BIT
+  );
+}
+
+WifiHandler& NetworkHandler::get_wifi_handler() {
+  return *this->wifiHandler;
+}
+
+std::unique_ptr<HttpHandler> NetworkHandler::get_http_handler(const esp_http_client_config_t&& config) {
+  return std::unique_ptr<HttpHandler>(new HttpHandler(std::move(config), this->wifiHandler.get()));
+}
+

main/network/network.h

@@ -0,0 +1,27 @@
+#pragma once
+#include <memory>
+#include "freertos/FreeRTOS.h"
+#include "esp_system.h"
+#include "network/wifi_handler.h"
+#include "esp_http_client.h"
+
+// forward declare HttpHandler to avoid circular include with http_handler.h
+class HttpHandler;
+
+class NetworkHandler {
+public:
+  NetworkHandler(
+    std::unique_ptr<WifiHandler> wifiHandler
+  );
+  ~NetworkHandler();
+
+  void init(EventGroupHandle_t system_event_group);
+  WifiHandler& get_wifi_handler();
+  // factory method to create HttpHandler instances
+  std::unique_ptr<HttpHandler> get_http_handler(const esp_http_client_config_t&& config);
+
+
+private:
+  std::unique_ptr<WifiHandler> wifiHandler;
+  bool initialized = false;
+};

main/network/udp_client.cpp

@@ -0,0 +1,172 @@
+#include "udp_client.h"
+#include <cstring>
+#include <unistd.h>
+#include <fcntl.h>
+#include <errno.h>
+#include "esp_log.h"
+
+static const char* TAG = "UDPClient";
+
+UDPClient::UDPClient()
+    : sock_fd_(-1)
+    , remote_port_(0)
+    , configured_(false)
+    , initialized_(false) {
+    memset(&remote_addr_, 0, sizeof(remote_addr_));
+}
+
+UDPClient::~UDPClient() {
+    close();
+}
+
+esp_err_t UDPClient::init() {
+    if (initialized_) {
+        ESP_LOGW(TAG, "Already initialized");
+        return ESP_OK;
+    }
+
+    sock_fd_ = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
+    if (sock_fd_ < 0) {
+        ESP_LOGE(TAG, "Failed to create socket: errno %d", errno);
+        return ESP_FAIL;
+    }
+
+    // Set socket to non-blocking mode
+    esp_err_t err = set_nonblocking();
+    if (err != ESP_OK) {
+        ::close(sock_fd_);
+        sock_fd_ = -1;
+        return err;
+    }
+
+    initialized_ = true;
+    ESP_LOGI(TAG, "UDP client initialized (fd=%d)", sock_fd_);
+    return ESP_OK;
+}
+
+esp_err_t UDPClient::set_nonblocking() {
+    int flags = fcntl(sock_fd_, F_GETFL, 0);
+    if (flags < 0) {
+        ESP_LOGE(TAG, "Failed to get socket flags: errno %d", errno);
+        return ESP_FAIL;
+    }
+
+    if (fcntl(sock_fd_, F_SETFL, flags | O_NONBLOCK) < 0) {
+        ESP_LOGE(TAG, "Failed to set non-blocking mode: errno %d", errno);
+        return ESP_FAIL;
+    }
+
+    return ESP_OK;
+}
+
+esp_err_t UDPClient::configure(const std::string& ip, uint16_t port) {
+    if (ip.empty() || port == 0) {
+        ESP_LOGE(TAG, "Invalid IP or port");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    struct in_addr addr;
+    if (inet_pton(AF_INET, ip.c_str(), &addr) != 1) {
+        ESP_LOGE(TAG, "Invalid IP address format: %s", ip.c_str());
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    remote_addr_.sin_family = AF_INET;
+    remote_addr_.sin_port = htons(port);
+    remote_addr_.sin_addr = addr;
+
+    remote_ip_ = ip;
+    remote_port_ = port;
+    configured_ = true;
+
+    ESP_LOGI(TAG, "Configured endpoint: %s:%u", ip.c_str(), port);
+    return ESP_OK;
+}
+
+esp_err_t UDPClient::send_command(const std::string& command) {
+    if (!initialized_) {
+        ESP_LOGE(TAG, "Not initialized");
+        return ESP_FAIL;
+    }
+
+    if (!configured_) {
+        ESP_LOGE(TAG, "Endpoint not configured");
+        return ESP_FAIL;
+    }
+
+    ssize_t sent = sendto(sock_fd_, command.c_str(), command.length(), 0,
+                          (struct sockaddr*)&remote_addr_, sizeof(remote_addr_));
+
+    if (sent < 0) {
+        ESP_LOGE(TAG, "Failed to send command '%s': errno %d", command.c_str(), errno);
+        return ESP_FAIL;
+    }
+
+    ESP_LOGD(TAG, "Sent command: %s (%d bytes)", command.c_str(), (int)sent);
+    return ESP_OK;
+}
+
+esp_err_t UDPClient::receive_response(std::string& response, int timeout_ms) {
+    if (!initialized_) {
+        ESP_LOGE(TAG, "Not initialized");
+        return ESP_FAIL;
+    }
+
+    // Setup select() for timeout
+    fd_set read_fds;
+    FD_ZERO(&read_fds);
+    FD_SET(sock_fd_, &read_fds);
+
+    struct timeval timeout;
+    struct timeval* timeout_ptr = nullptr;
+
+    if (timeout_ms >= 0) {
+        timeout.tv_sec = timeout_ms / 1000;
+        timeout.tv_usec = (timeout_ms % 1000) * 1000;
+        timeout_ptr = &timeout;
+    }
+
+    int ret = select(sock_fd_ + 1, &read_fds, nullptr, nullptr, timeout_ptr);
+
+    if (ret < 0) {
+        ESP_LOGE(TAG, "select() failed: errno %d", errno);
+        return ESP_FAIL;
+    }
+
+    if (ret == 0) {
+        ESP_LOGD(TAG, "Receive timeout (%d ms)", timeout_ms);
+        return ESP_ERR_TIMEOUT;
+    }
+
+    // Data is available
+    char buffer[512];
+    struct sockaddr_in from_addr;
+    socklen_t from_len = sizeof(from_addr);
+
+    ssize_t received = recvfrom(sock_fd_, buffer, sizeof(buffer) - 1, 0,
+                                (struct sockaddr*)&from_addr, &from_len);
+
+    if (received < 0) {
+        ESP_LOGE(TAG, "recvfrom() failed: errno %d", errno);
+        return ESP_FAIL;
+    }
+
+    buffer[received] = '\0';
+    response = std::string(buffer, received);
+
+    ESP_LOGD(TAG, "Received response: %s (%d bytes)", response.c_str(), (int)received);
+    return ESP_OK;
+}
+
+void UDPClient::close() {
+    if (sock_fd_ >= 0) {
+        ::close(sock_fd_);
+        ESP_LOGI(TAG, "Socket closed");
+        sock_fd_ = -1;
+    }
+
+    initialized_ = false;
+    configured_ = false;
+    remote_ip_.clear();
+    remote_port_ = 0;
+}

main/network/udp_client.h

@@ -0,0 +1,83 @@
+#pragma once
+
+#include <string>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+#include "esp_err.h"
+
+/**
+ * @brief UDP client for sending commands and receiving responses
+ *
+ * Implements non-blocking UDP communication with configurable timeouts.
+ * Socket remains open for the lifetime of the instance.
+ */
+class UDPClient {
+public:
+    UDPClient();
+    ~UDPClient();
+
+    /**
+     * @brief Initialize UDP socket
+     * @return ESP_OK on success, error code otherwise
+     */
+    esp_err_t init();
+
+    /**
+     * @brief Configure remote endpoint
+     * @param ip Remote IP address (e.g., "192.168.50.201")
+     * @param port Remote port number (e.g., 4211)
+     * @return ESP_OK on success, ESP_ERR_INVALID_ARG if IP is invalid
+     */
+    esp_err_t configure(const std::string& ip, uint16_t port);
+
+    /**
+     * @brief Send command to remote endpoint
+     * @param command Command string to send (e.g., "TOGGLE", "STATUS", "MUTE", "UNMUTE")
+     * @return ESP_OK on success, ESP_FAIL if not configured or send failed
+     */
+    esp_err_t send_command(const std::string& command);
+
+    /**
+     * @brief Receive response from remote endpoint (non-blocking)
+     * @param response Output string for received data
+     * @param timeout_ms Timeout in milliseconds (0 = no wait, -1 = wait forever)
+     * @return ESP_OK on success, ESP_ERR_TIMEOUT on timeout, ESP_FAIL on error
+     */
+    esp_err_t receive_response(std::string& response, int timeout_ms = 1000);
+
+    /**
+     * @brief Check if client is configured with valid endpoint
+     * @return true if IP and port are configured
+     */
+    bool is_configured() const { return configured_; }
+
+    /**
+     * @brief Get current remote IP
+     */
+    std::string get_ip() const { return remote_ip_; }
+
+    /**
+     * @brief Get current remote port
+     */
+    uint16_t get_port() const { return remote_port_; }
+
+    /**
+     * @brief Close socket and reset configuration
+     */
+    void close();
+
+private:
+    int sock_fd_;                  // Socket file descriptor
+    struct sockaddr_in remote_addr_; // Remote endpoint address
+    std::string remote_ip_;         // Remote IP address
+    uint16_t remote_port_;          // Remote port number
+    bool configured_;               // Whether endpoint is configured
+    bool initialized_;              // Whether socket is initialized
+
+    /**
+     * @brief Set socket to non-blocking mode
+     * @return ESP_OK on success
+     */
+    esp_err_t set_nonblocking();
+};

main/network/wifi_handler.cpp

@@ -0,0 +1,541 @@
+#include "wifi_handler.h"
+#include "esp_wifi.h"
+#include "esp_event.h"
+#include "esp_netif.h"
+#include "freertos/event_groups.h"
+#include "esp_log.h"
+#include "freertos/semphr.h"
+#include "common/semaphore_guard.h"
+#include "cJSON.h"
+
+#define TAG "WifiHandler"
+#define WIFI_CRED_FILE_PATH "wifi_credentials.json"
+
+/*
+ * WiFi Credentials JSON Structure:
+ * {
+ *   "current_ssid": "MyWiFi",
+ *   "credentials": {
+ *     "MyWiFi": {
+ *       "password": "mypassword123"
+ *     },
+ *     "OtherNetwork": {
+ *       "password": "otherpass456"
+ *     }
+ *   }
+ * }
+ */
+
+WifiHandler::WifiHandler(
+  std::shared_ptr<LittleFSHandler> fs_handler_
+) : fs_handler_(std::move(fs_handler_)) {
+  this->s_wifi_event_group = xEventGroupCreate();
+  if (!this->s_wifi_event_group) {
+    ESP_LOGE(TAG, "Failed to create WiFi event group");
+  }
+  this->scan_mutex = xSemaphoreCreateMutex();
+  if (!this->scan_mutex) {
+    ESP_LOGE(TAG, "Failed to create scan mutex");
+  }
+  this->connection_mutex = xSemaphoreCreateMutex();
+  if (!this->connection_mutex) {
+    ESP_LOGE(TAG, "Failed to create connection mutex");
+  }
+  this->credential_mutex = xSemaphoreCreateMutex();
+  if (!this->credential_mutex) {
+    ESP_LOGE(TAG, "Failed to create credential mutex");
+  }
+  if (this->fs_handler_ == nullptr) {
+    ESP_LOGW(TAG, "FSHandler is null, WiFi credentials will not be stored");
+  } else {
+    esp_err_t err = this->fs_handler_->init("/littlefs");
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to initialize FSHandler: %s", esp_err_to_name(err));
+    }
+  }
+}
+
+WifiHandler::~WifiHandler() {
+  if (this->initialized) {
+    esp_wifi_stop();
+    // Check if it should be called
+    esp_wifi_deinit();
+    vEventGroupDelete(this->s_wifi_event_group);
+    if (!this->current_ssid.empty()) {
+      this->current_ssid.clear();
+    }
+    vSemaphoreDelete(this->scan_mutex);
+    vSemaphoreDelete(this->connection_mutex);
+    esp_event_handler_unregister(WIFI_EVENT, ESP_EVENT_ANY_ID, &WifiHandler::wifi_event_handler);
+    esp_event_handler_unregister(IP_EVENT, IP_EVENT_STA_GOT_IP, &WifiHandler::wifi_event_handler);
+    this->initialized = false;
+    //
+    this->fs_handler_ = nullptr;
+  }
+}
+
+esp_err_t WifiHandler::init() {
+  if (this->initialized) {
+    ESP_LOGW(TAG, "Already initialized, skipping");
+    return ESP_OK;
+  }
+  esp_err_t err;
+
+  // initialize TCP/IP stack and default event loop
+  err = esp_netif_init();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_netif_init failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  err = esp_event_loop_create_default();
+  if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
+    ESP_LOGE(TAG, "esp_event_loop_create_default failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // create default WiFi station
+  esp_netif_create_default_wifi_sta();
+
+  // init WiFi driver
+  wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+  err = esp_wifi_init(&cfg);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_wifi_init failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // register event handlers for WiFi and IP events
+  err = esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &WifiHandler::wifi_event_handler, this);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_event_handler_register failed: %s", esp_err_to_name(err));
+    return err;
+  }
+  err = esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &WifiHandler::wifi_event_handler, this);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_event_handler_register failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  err = esp_wifi_set_mode(WIFI_MODE_STA);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_wifi_set_mode failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  err = esp_wifi_start();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "esp_wifi_start failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // get WiFi credentials from KV storage if available
+  std::string ssid;
+  std::string password;
+  this->get_wifi_credentials(ssid, password);
+
+  // If KV storage didn't provide credentials, allow build-time injected values
+  // via compile-time defines BUILD_WIFI_SSID and BUILD_WIFI_PASSWORD.
+#if defined(BUILD_WIFI_SSID) and defined(BUILD_WIFI_PASSWORD)
+  if (ssid.empty()) {
+    ssid = std::string(BUILD_WIFI_SSID);
+    ESP_LOGI(TAG, "Using build-time injected WiFi SSID");
+  }
+  if (password.empty()) {
+    password = std::string(BUILD_WIFI_PASSWORD);
+    ESP_LOGI(TAG, "Using build-time injected WiFi password");
+  }
+#endif
+
+  if (!ssid.empty() && !password.empty()) {
+    ESP_LOGI(TAG, "Found stored WiFi credentials, connecting to SSID: %s", ssid.c_str());
+    err = this->connect(ssid, password);
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to connect to stored WiFi credentials: %s", esp_err_to_name(err));
+    }
+  } else {
+    ESP_LOGI(TAG, "No stored WiFi credentials found, not connecting");
+  }
+
+  initialized = true;
+  return ESP_OK;
+}
+
+esp_err_t WifiHandler::connect(const std::string& ssid, const std::string& password) {
+  SemaphoreGuard guard(this->connection_mutex);
+  // wait up to 5 seconds to take the mutex
+  if (!guard.take(5000 / portTICK_PERIOD_MS)) {
+    ESP_LOGE(TAG, "Failed to take connection mutex");
+    return ESP_FAIL;
+  }
+
+  expect_disconnected = false;
+  if (!this->current_ssid.empty()) {
+    this->current_ssid.clear();
+  }
+  this->current_ssid = ssid;
+  this->current_password = password;
+
+  //
+  wifi_config_t wifi_config = {};
+  strncpy((char*)wifi_config.sta.ssid, this->current_ssid.c_str(), sizeof(wifi_config.sta.ssid));
+  wifi_config.sta.ssid[sizeof(wifi_config.sta.ssid) - 1] = '\0';
+  strncpy((char*)wifi_config.sta.password, password.c_str(), sizeof(wifi_config.sta.password));
+  wifi_config.sta.password[sizeof(wifi_config.sta.password) - 1] = '\0';
+  // set auth mode to WPA2_PSK minimum
+  wifi_config.sta.threshold.authmode = WIFI_AUTH_WPA2_PSK;
+
+  ESP_LOGI(TAG, "Connecting to SSID: %s", this->current_ssid.c_str());
+  esp_err_t err = esp_wifi_set_config(wifi_interface_t::WIFI_IF_STA, &wifi_config);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to set WiFi config: %s", esp_err_to_name(err));
+    return err;
+  }
+  err = esp_wifi_connect();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initiate WiFi connection: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // Note: Credentials will be stored in the event handler after successful connection
+  // to avoid storing credentials for failed connection attempts
+
+  return ESP_OK;
+}
+
+esp_err_t WifiHandler::connect(const std::string& ssid) {
+  std::string stored_ssid;
+  std::string stored_password;
+  this->get_wifi_credentials(stored_ssid, stored_password);
+  if (stored_ssid.empty() || stored_ssid != ssid) {
+    ESP_LOGE(TAG, "No stored credentials for SSID: %s", ssid.c_str());
+    return ESP_FAIL;
+  }
+  esp_err_t err = this->connect(stored_ssid, stored_password);
+  return err;
+}
+
+esp_err_t WifiHandler::reconnect() {
+  if (this->current_ssid.empty()) {
+    ESP_LOGE(TAG, "No current SSID set, cannot reconnect");
+    return ESP_FAIL;
+  }
+  return this->connect(this->current_ssid);
+}
+
+void WifiHandler::disconnect() {
+  SemaphoreGuard guard(this->connection_mutex);
+  // wait up to 5 seconds to take the mutex
+  if (!guard.take(5000 / portTICK_PERIOD_MS)) {
+    ESP_LOGE(TAG, "Failed to take connection mutex");
+    return;
+  }
+
+  expect_disconnected = true;
+  esp_wifi_disconnect();
+  xEventGroupClearBits(
+    this->s_wifi_event_group,
+    WIFI_CONNECTED_BIT
+  );
+}
+
+esp_err_t WifiHandler::scan_networks(
+  wifi_ap_record_t*& ap_records,
+  uint16_t& ap_count
+) {
+  SemaphoreGuard guard(this->scan_mutex);
+  // wait up to 5 seconds to take the mutex
+  if (!guard.take(5000 / portTICK_PERIOD_MS)) {
+    ESP_LOGE(TAG, "Failed to take scan mutex");
+    return ESP_FAIL;
+  }
+  ap_records = nullptr;
+  ap_count = 0;
+  // start scan
+
+  esp_err_t err = esp_wifi_scan_start(nullptr, true); // block until done
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to start WiFi scan: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  // get number of APs found
+  uint16_t ap_count_local = 0;
+  err = esp_wifi_scan_get_ap_num(&ap_count_local);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to get number of APs found: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  wifi_ap_record_t* ap_records_local = new wifi_ap_record_t[ap_count_local];
+  err = esp_wifi_scan_get_ap_records(&ap_count_local, ap_records_local);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to get AP records: %s", esp_err_to_name(err));
+    delete[] ap_records_local;
+    return err;
+  }
+
+  ap_records = ap_records_local;
+  ap_count = ap_count_local;
+  return ESP_OK;
+}
+
+void WifiHandler::wifi_event_handler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data) {
+  WifiHandler* self = static_cast<WifiHandler*>(arg);
+  if (self == nullptr) {
+    ESP_LOGE(TAG, "wifi_event_handler received null WifiHandler pointer");
+    return;
+  }
+
+  switch (event_id) {
+    case WIFI_EVENT_STA_START:
+      // When the station starts, attempt to connect
+      ESP_LOGI(TAG, "WIFI_EVENT_STA_START");
+      if (!self->expect_disconnected && !self->current_ssid.empty()) {
+        ESP_LOGI(TAG, "Station started, attempting to connect to SSID: %s", self->current_ssid.c_str());
+        self->reconnect();
+      }
+      // set the event bit to indicate started
+      xEventGroupSetBits(
+        self->s_wifi_event_group,
+        WIFI_STARTED_BIT
+      );
+      break;
+    case WIFI_EVENT_STA_DISCONNECTED:
+      ESP_LOGI(TAG, "WIFI_EVENT_STA_DISCONNECTED");
+      if (!self->expect_disconnected) {
+        ESP_LOGI(TAG, "Unexpected disconnection, attempting to reconnect");
+        self->reconnect();
+      }
+      xEventGroupClearBits(
+        self->s_wifi_event_group,
+        WIFI_CONNECTED_BIT
+      );
+      break;
+    case IP_EVENT_STA_GOT_IP:
+    {
+      ip_event_got_ip_t* event = static_cast<ip_event_got_ip_t*>(event_data);
+      ESP_LOGI(TAG, "WIFI_EVENT_STA_GOT_IP: " IPSTR, IP2STR(&event->ip_info.ip));
+      xEventGroupSetBits(
+        self->s_wifi_event_group,
+        WIFI_CONNECTED_BIT
+      );
+      // Store credentials only after successful connection
+      if (!self->current_ssid.empty() && !self->current_password.empty()) {
+        self->store_wifi_credentials(self->current_ssid, self->current_password);
+      }
+      break;
+    }
+    default:
+      ESP_LOGW(TAG, "Unhandled WiFi event: %d", event_id);
+      break;
+  }
+}
+
+//
+// private methods
+//
+
+void WifiHandler::store_wifi_credentials(const std::string& ssid, const std::string& password) {
+  if (!fs_handler_) {
+    ESP_LOGW(TAG, "FSHandler not set, cannot store WiFi credentials");
+    return;
+  }
+  SemaphoreGuard guard(this->credential_mutex);
+  // wait up to 5 seconds to take the mutex
+  if (!guard.take(5000 / portTICK_PERIOD_MS)) {
+    ESP_LOGE(TAG, "Failed to take credential mutex");
+    return;
+  }
+
+  cJSON* json = nullptr;
+
+  // Try to read existing credentials file
+  if (fs_handler_->file_exists(WIFI_CRED_FILE_PATH)) {
+    // Read existing file
+    size_t file_size = 0;
+    esp_err_t err = fs_handler_->get_file_size(WIFI_CRED_FILE_PATH, file_size);
+    if (err == ESP_OK && file_size > 0) {
+      std::vector<uint8_t> file_data(file_size + 1); // +1 for null terminator
+      size_t bytes_read = 0;
+      err = fs_handler_->read_file(WIFI_CRED_FILE_PATH, file_size, file_data.data(), bytes_read);
+      if (err == ESP_OK) {
+        file_data[bytes_read] = '\0'; // Null terminate
+        json = cJSON_Parse(reinterpret_cast<const char*>(file_data.data()));
+        if (json == nullptr) {
+          ESP_LOGE(TAG, "Failed to parse existing WiFi credentials JSON, creating new");
+        }
+      }
+    }
+  }
+
+  // Create new JSON if parsing failed or file doesn't exist
+  if (json == nullptr) {
+    json = cJSON_CreateObject();
+  }
+
+  // Set current SSID
+  cJSON* current_ssid_item = cJSON_GetObjectItem(json, "current_ssid");
+  if (current_ssid_item != nullptr) {
+    cJSON_SetValuestring(current_ssid_item, ssid.c_str());
+  } else {
+    cJSON_AddStringToObject(json, "current_ssid", ssid.c_str());
+  }
+
+  // Get or create credentials object
+  cJSON* credentials = cJSON_GetObjectItem(json, "credentials");
+  if (credentials == nullptr || !cJSON_IsObject(credentials)) {
+    credentials = cJSON_CreateObject();
+    cJSON_AddItemToObject(json, "credentials", credentials);
+  }
+
+  // Limit stored credentials to prevent excessive file size (keep max 10 SSIDs)
+  int credential_count = cJSON_GetArraySize(credentials);
+  if (credential_count >= 10) {
+    ESP_LOGW(TAG, "Too many stored credentials (%d), keeping only current SSID", credential_count);
+    // Keep only the current SSID's credentials
+    cJSON* new_credentials = cJSON_CreateObject();
+    cJSON_ReplaceItemInObject(json, "credentials", new_credentials);
+    credentials = new_credentials;
+  }
+
+  // Remove existing entry for this SSID to update it
+  cJSON_DeleteItemFromObject(credentials, ssid.c_str());
+
+  // Create SSID object with password
+  cJSON* ssid_item = cJSON_CreateObject();
+  cJSON_AddStringToObject(ssid_item, "password", password.c_str());
+  cJSON_AddItemToObject(credentials, ssid.c_str(), ssid_item);
+
+  // Serialize and write to file
+  char* json_str = cJSON_PrintUnformatted(json);
+  if (json_str) {
+    size_t bytes_written = 0;
+    esp_err_t err = fs_handler_->write_file(
+      WIFI_CRED_FILE_PATH,
+      reinterpret_cast<const uint8_t*>(json_str),
+      strlen(json_str),
+      bytes_written
+    );
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to write WiFi credentials to file: %s", esp_err_to_name(err));
+    } else {
+      ESP_LOGI(TAG, "Stored WiFi credentials for SSID: %s", ssid.c_str());
+    }
+    cJSON_free(json_str);
+  } else {
+    ESP_LOGE(TAG, "Failed to serialize WiFi credentials JSON");
+  }
+  cJSON_Delete(json);
+}
+
+void WifiHandler::get_wifi_credentials(std::string& out_ssid, std::string& out_password) {
+  if (!fs_handler_) {
+    ESP_LOGW(TAG, "FSHandler not set, cannot get WiFi credentials");
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+
+  SemaphoreGuard guard(this->credential_mutex);
+  // wait up to 5 seconds to take the mutex
+  if (!guard.take(5000 / portTICK_PERIOD_MS)) {
+    ESP_LOGE(TAG, "Failed to take credential mutex");
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+
+  // Check if credentials file exists
+  if (!fs_handler_->file_exists(WIFI_CRED_FILE_PATH)) {
+    ESP_LOGD(TAG, "WiFi credentials file does not exist");
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+
+  // Read credentials file
+  size_t file_size = 0;
+  esp_err_t err = fs_handler_->get_file_size(WIFI_CRED_FILE_PATH, file_size);
+  if (err != ESP_OK || file_size == 0) {
+    ESP_LOGE(TAG, "Failed to get WiFi credentials file size");
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+
+  std::vector<uint8_t> file_data(file_size + 1); // +1 for null terminator
+  size_t bytes_read = 0;
+  err = fs_handler_->read_file(WIFI_CRED_FILE_PATH, file_size, file_data.data(), bytes_read);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to read WiFi credentials file: %s", esp_err_to_name(err));
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+  file_data[bytes_read] = '\0'; // Null terminate
+
+  // Parse JSON
+  cJSON* json = cJSON_Parse(reinterpret_cast<const char*>(file_data.data()));
+  if (json == nullptr) {
+    ESP_LOGE(TAG, "Failed to parse WiFi credentials JSON");
+    out_ssid = "";
+    out_password = "";
+    return;
+  }
+
+  // Get current SSID
+  cJSON* current_ssid_item = cJSON_GetObjectItem(json, "current_ssid");
+  if (current_ssid_item == nullptr || !cJSON_IsString(current_ssid_item)) {
+    ESP_LOGE(TAG, "WiFi credentials JSON does not contain valid 'current_ssid' field");
+    out_ssid = "";
+    out_password = "";
+    cJSON_Delete(json);
+    return;
+  }
+  out_ssid = current_ssid_item->valuestring;
+
+  // Get credentials object
+  cJSON* credentials = cJSON_GetObjectItem(json, "credentials");
+  if (credentials == nullptr || !cJSON_IsObject(credentials)) {
+    ESP_LOGE(TAG, "WiFi credentials JSON does not contain valid 'credentials' object");
+    out_ssid = "";
+    out_password = "";
+    cJSON_Delete(json);
+    return;
+  }
+
+  // Get SSID entry
+  cJSON* ssid_item = cJSON_GetObjectItem(credentials, out_ssid.c_str());
+  if (ssid_item == nullptr || !cJSON_IsObject(ssid_item)) {
+    ESP_LOGE(TAG, "WiFi credentials JSON does not contain entry for SSID: %s", out_ssid.c_str());
+    out_ssid = "";
+    out_password = "";
+    cJSON_Delete(json);
+    return;
+  }
+
+  // Get password
+  cJSON* password_item = cJSON_GetObjectItem(ssid_item, "password");
+  if (password_item == nullptr || !cJSON_IsString(password_item)) {
+    ESP_LOGE(TAG, "WiFi credentials JSON does not contain valid 'password' field for SSID: %s", out_ssid.c_str());
+    out_ssid = "";
+    out_password = "";
+    cJSON_Delete(json);
+    return;
+  }
+  out_password = password_item->valuestring;
+
+  cJSON_Delete(json);
+  ESP_LOGD(TAG, "Retrieved WiFi credentials for SSID: %s", out_ssid.c_str());
+}
+
+EventBits_t WifiHandler::wait_for_connection(TickType_t ticks_to_wait) {
+  return xEventGroupWaitBits(
+    s_wifi_event_group,
+    WIFI_CONNECTED_BIT,
+    pdFALSE,
+    pdTRUE,
+    ticks_to_wait
+  );
+}

main/network/wifi_handler.h

@@ -0,0 +1,60 @@
+#pragma once
+#include "freertos/FreeRTOS.h"
+#include "io/fs_handler.h"
+#include "esp_wifi.h"
+#include "freertos/event_groups.h"
+
+#define WIFI_STARTED_BIT   (1 << 0)
+#define WIFI_CONNECTED_BIT (1 << 1)
+
+
+class WifiHandler {
+public:
+  WifiHandler(
+    // this handler is used to store/retrieve WiFi credentials
+    // should have a unique namespace for WiFi credentials
+    // it will be owned by WifiHandler and deleted in its destructor
+    std::shared_ptr<LittleFSHandler> fs_handler_
+  );
+  ~WifiHandler();
+
+  esp_err_t init();
+  esp_err_t connect(const std::string& ssid, const std::string& password);
+  esp_err_t connect(const std::string& ssid); // connect using stored password
+  esp_err_t reconnect(); // reconnect to current SSID
+  void disconnect();
+  EventBits_t wait_for_connection(TickType_t ticks_to_wait);
+  // returns list of available networks, caller is responsible for freeing the returned memory
+  // returns nullptr if scan failed
+  esp_err_t scan_networks(
+    wifi_ap_record_t*& ap_records,
+    uint16_t& ap_count
+  );
+
+  static void wifi_event_handler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data);
+
+private:
+  // prevent copying
+  WifiHandler(const WifiHandler&) = delete;
+  WifiHandler& operator=(const WifiHandler&) = delete;
+  // prevent moving
+  WifiHandler(WifiHandler&& other) = delete;
+  WifiHandler& operator=(WifiHandler&& other) = delete;
+
+  void store_wifi_credentials(const std::string& ssid, const std::string& password);
+  void get_wifi_credentials(std::string& out_ssid, std::string& out_password);
+
+  bool initialized = false;
+  std::shared_ptr<LittleFSHandler> fs_handler_ = nullptr;
+  EventGroupHandle_t s_wifi_event_group = 0;
+  SemaphoreHandle_t scan_mutex = nullptr;
+  SemaphoreHandle_t connection_mutex = nullptr;
+  SemaphoreHandle_t credential_mutex = nullptr;
+  // current connected / preferred SSID
+  std::string current_ssid;
+  // current password (temporarily stored for successful connection event)
+  std::string current_password;
+  // prevent auto-reconnect on expected disconnection, e.g. when user calls disconnect()
+  // should be reset to false after connect()
+  bool expect_disconnected = false;
+};

main/ui/apps/app.h

@@ -0,0 +1,87 @@
+#pragma once
+
+#include "lvgl.h"
+#include "esp_err.h"
+#include <string>
+#include <memory>
+
+/**
+ * @brief Base class for all UI applications
+ *
+ * All UI applications (apps) must inherit from this class.
+ * Each app is responsible for managing its own widgets within
+ * the provided LVGL container. The UIHandler will manage the
+ * lifecycle of apps and event routing.
+ */
+class UIApp {
+public:
+  virtual ~UIApp() = default;
+
+  /**
+   * @brief Initialize the app with the given container
+   *
+   * The app should create all its widgets as children of the
+   * provided container. The container is already positioned
+   * between the header and navigation bar.
+   *
+   * @param container LVGL container object for this app
+   * @return ESP_OK on success, error code otherwise
+   */
+  virtual esp_err_t init(lv_obj_t* container) = 0;
+
+  /**
+   * @brief Deinitialize and clean up app resources
+   *
+   * The app should delete all widgets and release any resources.
+   * The container itself will be handled by UIHandler.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  virtual esp_err_t deinit(void) = 0;
+
+  /**
+   * @brief Get the display name of this app
+   *
+   * Used for logging and potentially showing in navigation.
+   *
+   * @return std::string app name
+   */
+  virtual std::string get_name(void) const = 0;
+
+  /**
+   * @brief Handle back button press
+   *
+   * Called when the back button is pressed.
+   * The app can choose to handle it (e.g., close a dialog)
+   * or return false to let UIHandler handle it (e.g., return to main screen).
+   *
+   * @return true if the event was handled, false otherwise
+   */
+  virtual bool on_back_button_pressed(void) {
+    return false; // default: not handled
+  }
+
+protected:
+  lv_obj_t* container_ = nullptr;  ///< LVGL container provided by UIHandler
+};
+
+class AppDescriptor {
+public:
+  virtual ~AppDescriptor() = default;
+  virtual void draw_icon(lv_obj_t* parent) = 0;
+
+  std::string get_name() const {
+    return name_;
+  }
+
+  UIApp* get_app_instance() const {
+    return app_instance_.get();
+  }
+
+protected:
+  AppDescriptor(std::string name, std::unique_ptr<UIApp> app_instance)
+    : name_(name), app_instance_(std::move(app_instance)) { }
+
+  std::string name_;
+  std::unique_ptr<UIApp> app_instance_;
+};

main/ui/apps/registry.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#include "ui/apps/app.h"
+#include <map>
+#include <string>
+#include "esp_log.h"
+#include <memory>
+
+class AppRegistry {
+public:
+  static AppRegistry& instance() {
+    static AppRegistry registry;
+    return registry;
+  }
+
+  void register_app(std::unique_ptr<AppDescriptor> app_descriptor) {
+    if (app_descriptors_.find(app_descriptor->get_name()) != app_descriptors_.end()) {
+      // App already registered
+      ESP_LOGW("AppRegistry", "App '%s' is already registered", app_descriptor->get_name().c_str());
+      return;
+    }
+    app_descriptors_.emplace(app_descriptor->get_name(), std::move(app_descriptor));
+  }
+
+  size_t size() const {
+    return app_descriptors_.size();
+  }
+
+  // iterators to access registered apps
+  auto begin() { return app_descriptors_.begin(); }
+  auto begin() const { return app_descriptors_.begin(); }
+  auto end() { return app_descriptors_.end(); }
+  auto end() const { return app_descriptors_.end(); }
+
+  // [] operator to get app by name
+  AppDescriptor* operator[](const std::string& name) {
+    auto it = app_descriptors_.find(name);
+    if (it != app_descriptors_.end()) {
+      return it->second.get();
+    }
+    return nullptr;
+  }
+
+private:
+  std::map<std::string, std::unique_ptr<AppDescriptor>> app_descriptors_ = {};
+
+  AppRegistry() = default;
+  // Disable copy and move semantics
+  AppRegistry(const AppRegistry&) = delete;
+  AppRegistry& operator=(const AppRegistry&) = delete;
+  AppRegistry(AppRegistry&&) = delete;
+  AppRegistry& operator=(AppRegistry&&) = delete;
+};

main/ui/events.cpp

@@ -0,0 +1,4 @@
+#include "events.h"
+
+// Define the event base
+ESP_EVENT_DEFINE_BASE(UI_EVENT_BASE);

main/ui/events.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "esp_event.h"
+#include "lvgl.h"
+
+ESP_EVENT_DECLARE_BASE(UI_EVENT_BASE);
+
+struct KeyboardEventData {
+  lv_obj_t* textarea; ///< The textarea that triggered the keyboard event, nullptr if not applicable or for hide event
+};
+
+enum EventId {
+  UI_EVENT_KEYBOARD_SHOWN = 1,   ///< Event ID for keyboard shown event
+  UI_EVENT_KEYBOARD_HIDDEN = 2   ///< Event ID for keyboard hidden event
+};

main/ui/interaction_handler.cpp

@@ -0,0 +1,159 @@
+#include "ui/interaction_handler.h"
+#include "ui/events.h"
+#include "esp_err.h"
+#include "esp_log.h"
+
+#define TAG "InteractionHandler"
+
+InteractionHandler::~InteractionHandler() {
+  esp_err_t err = deinit();
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Error during InteractionHandler deinit: %s", esp_err_to_name(err));
+  }
+}
+
+esp_err_t InteractionHandler::init(lv_obj_t* app_container) {
+  if (!app_container) {
+    ESP_LOGE(TAG, "Invalid argument: app_container is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+  app_container_ = app_container;
+  keyboard_ = lv_keyboard_create(app_container_);
+  lv_obj_add_flag(keyboard_, LV_OBJ_FLAG_HIDDEN); // start hidden
+  lv_obj_add_event_cb(
+    keyboard_,
+    [](lv_event_t* e) {
+      InteractionHandler* handler = static_cast<InteractionHandler*>(lv_event_get_user_data(e));
+      handler->on_keyboard_event_(e);
+    }
+  , LV_EVENT_ALL, this);
+
+  return ESP_OK;
+}
+
+esp_err_t InteractionHandler::deinit(void) {
+  if (keyboard_) {
+    lv_obj_del(keyboard_);
+    keyboard_ = nullptr;
+  }
+  return ESP_OK;
+}
+
+esp_err_t InteractionHandler::register_text_area_keyboard_support(lv_obj_t* text_area) {
+  if (!text_area) {
+    ESP_LOGE(TAG, "Invalid argument: text_area is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  lv_obj_add_event_cb(
+    text_area,
+    [](lv_event_t* e) {
+      lv_event_code_t code = lv_event_get_code(e);
+      if (code != LV_EVENT_FOCUSED) {
+        return;
+      }
+      InteractionHandler* handler = static_cast<InteractionHandler*>(lv_event_get_user_data(e));
+
+      esp_err_t err = handler->show_keyboard_for_textarea_(static_cast<lv_obj_t*>(lv_event_get_target(e)));
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to show keyboard: %s", esp_err_to_name(err));
+      }
+    }
+  , LV_EVENT_FOCUSED, this);
+
+  lv_obj_add_event_cb(
+    text_area,
+    [](lv_event_t* e) {
+      lv_event_code_t code = lv_event_get_code(e);
+      if (code != LV_EVENT_DEFOCUSED) {
+        return;
+      }
+      InteractionHandler* handler = static_cast<InteractionHandler*>(lv_event_get_user_data(e));
+
+      esp_err_t err = handler->hide_keyboard_();
+      if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to hide keyboard: %s", esp_err_to_name(err));
+      }
+    }
+  , LV_EVENT_DEFOCUSED, this);
+
+  return ESP_OK;
+}
+
+//
+// Private methods
+//
+
+void InteractionHandler::on_keyboard_event_(lv_event_t* e) {
+  lv_event_code_t code = lv_event_get_code(e);
+  if (code == LV_EVENT_READY || code == LV_EVENT_CANCEL) {
+    // Keyboard is cancelled
+    esp_err_t err = hide_keyboard_();
+    if (err != ESP_OK) {
+      ESP_LOGE(TAG, "Failed to hide keyboard: %s", esp_err_to_name(err));
+    }
+
+    if (focused_textarea_) {
+      lv_obj_clear_state(focused_textarea_, LV_STATE_FOCUSED);
+      lv_keyboard_set_textarea(keyboard_, nullptr);
+      focused_textarea_ = nullptr;
+    }
+  }
+}
+
+esp_err_t InteractionHandler::show_keyboard_for_textarea_(lv_obj_t* textarea) {
+  if (!keyboard_ || !textarea) {
+    ESP_LOGE(TAG, "Invalid state or argument in show_keyboard_for_textarea_");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  focused_textarea_ = textarea;
+  lv_keyboard_set_textarea(keyboard_, textarea);
+  lv_obj_clear_flag(keyboard_, LV_OBJ_FLAG_HIDDEN);
+  // emit keyboard shown event
+  KeyboardEventData event_data = {
+   .textarea = textarea
+  };
+  esp_err_t err = esp_event_post_to(
+    NULL,
+    UI_EVENT_BASE,
+    UI_EVENT_KEYBOARD_SHOWN,
+    &event_data,
+    sizeof(event_data),
+    portMAX_DELAY
+  );
+
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to post keyboard shown event: %s", esp_err_to_name(err));
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t InteractionHandler::hide_keyboard_(void) {
+  if (!keyboard_) {
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  lv_obj_add_flag(keyboard_, LV_OBJ_FLAG_HIDDEN);
+
+  // emit keyboard hidden event
+  KeyboardEventData event_data = {
+   .textarea = nullptr
+  };
+
+  esp_err_t err = esp_event_post_to(
+    NULL,
+    UI_EVENT_BASE,
+    UI_EVENT_KEYBOARD_HIDDEN,
+    &event_data,
+    sizeof(event_data),
+    portMAX_DELAY
+  );
+
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to post keyboard hidden event: %s", esp_err_to_name(err));
+  }
+
+  return ESP_OK;
+}

main/ui/interaction_handler.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include "esp_err.h"
+#include "lvgl.h"
+#include "ui/events.h"
+
+
+
+/**
+ * @brief Interaction Handler - manages user interactions
+ *
+ * This class is responsible for handling user inputs
+ * such as touch events, button presses, and gestures.
+ * It routes these interactions to the appropriate UI components
+ * or apps based on the current context. And it also handles the respective UI widgets.
+ *
+ * For example, it manages:
+ * Textarea focus and display of the on-screen keyboard
+ */
+class InteractionHandler {
+public:
+
+  InteractionHandler() = default;
+  ~InteractionHandler();
+
+  /**
+   * @brief Initialize the Interaction Handler
+   *
+   * Sets up necessary event listeners and state.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t init(lv_obj_t* app_container);
+
+  /**
+   * @brief Deinitialize the Interaction Handler
+   *
+   * Cleans up resources and event listeners.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t deinit(void);
+
+  /**
+   * @brief Add keyboard support to a textarea widget
+   *
+   * @param text_area Pointer to the textarea lvgl object
+   * @return esp_err_t ESP_OK on success, error code otherwise
+   */
+  esp_err_t register_text_area_keyboard_support(lv_obj_t* text_area);
+
+private:
+
+  // Event handler for keyboard show/hide events
+  // It should be registered with event callbacks of the keyboard object
+  void on_keyboard_event_(lv_event_t* e);
+
+  esp_err_t show_keyboard_for_textarea_(lv_obj_t* textarea);
+  esp_err_t hide_keyboard_(void);
+
+  // Pointers to key UI objects, owned by UIHandler
+  lv_obj_t* app_container_ = nullptr;
+  // owned keyboard object
+  lv_obj_t* keyboard_ = nullptr;
+  // Currently focused textarea, reference only
+  lv_obj_t* focused_textarea_ = nullptr;
+
+  InteractionHandler(const InteractionHandler&) = delete;
+  InteractionHandler& operator=(const InteractionHandler&) = delete;
+};

main/ui/root_layout.cpp

@@ -0,0 +1,249 @@
+#include "ui/root_layout.h"
+#include "ui/events.h"
+#include "esp_log.h"
+#include "esp_event.h"
+
+#define TAG "RootLayout"
+
+#define HEADER_HEIGHT 40
+#define NAV_BAR_HEIGHT 50
+
+RootLayout::~RootLayout() {
+  deinit();
+}
+
+esp_err_t RootLayout::init(lv_obj_t* parent, UIHandler* ui_handler) {
+
+  // Configure parent as flexbox column layout
+  lv_obj_set_flex_flow(parent, LV_FLEX_FLOW_COLUMN);
+  lv_obj_set_flex_align(parent, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_START);
+  lv_obj_set_style_pad_all(parent, 0, 0);
+  lv_obj_set_style_pad_gap(parent, 0, 0);
+  //
+  // Create header (top, fixed height)
+  header_obj_ = lv_obj_create(parent);
+  lv_obj_set_width(header_obj_, lv_pct(100));
+  lv_obj_set_height(header_obj_, HEADER_HEIGHT);
+  lv_obj_set_style_bg_color(header_obj_, lv_color_white(), 0);
+  lv_obj_set_style_border_width(header_obj_, 0, 0);
+  lv_obj_set_style_border_color(header_obj_, lv_color_black(), 0);
+  lv_obj_set_style_border_width(header_obj_, 1, LV_BORDER_SIDE_BOTTOM);
+  lv_obj_set_style_pad_all(header_obj_, 0, 0);
+  lv_obj_set_style_radius(header_obj_, 0, 0);
+  //
+  header_label_ = lv_label_create(header_obj_);
+  lv_label_set_text(header_label_, "App");
+  lv_obj_set_style_text_color(header_label_, lv_color_black(), 0);
+  lv_obj_align(header_label_, LV_ALIGN_LEFT_MID, 10, 0);
+  //
+  // Create app container (middle, flexible height)
+  app_container_ = lv_obj_create(parent);
+  lv_obj_set_width(app_container_, lv_pct(100));
+  lv_obj_set_flex_grow(app_container_, 1);
+  lv_obj_set_style_bg_color(app_container_, lv_color_white(), 0);
+  lv_obj_set_style_border_width(app_container_, 0, 0);
+  lv_obj_set_style_pad_all(app_container_, 0, 0);
+  lv_obj_set_style_radius(app_container_, 0, 0);
+
+  //
+  // Create navigation bar (bottom, fixed height)
+  nav_bar_obj_ = lv_obj_create(parent);
+  lv_obj_set_width(nav_bar_obj_, lv_pct(100));
+  lv_obj_set_height(nav_bar_obj_, NAV_BAR_HEIGHT);
+  lv_obj_set_style_bg_color(nav_bar_obj_, lv_color_white(), 0);
+  lv_obj_set_style_border_color(nav_bar_obj_, lv_color_black(), 0);
+  lv_obj_set_style_border_width(nav_bar_obj_, 1, LV_BORDER_SIDE_TOP);
+  lv_obj_set_style_pad_all(nav_bar_obj_, 5, 0);
+  lv_obj_set_style_radius(nav_bar_obj_, 0, 0);
+
+
+  // Create back button (aligned to start by flex layout)
+  back_button_ = lv_btn_create(nav_bar_obj_);
+  lv_obj_set_size(back_button_, 60, NAV_BAR_HEIGHT - 10);
+  lv_obj_set_style_bg_color(back_button_, lv_color_white(), 0);
+  lv_obj_add_flag(back_button_, LV_OBJ_FLAG_HIDDEN);
+  lv_obj_t* back_label = lv_label_create(back_button_);
+  lv_label_set_text(back_label, LV_SYMBOL_LEFT);
+
+  // Create home button (aligned to end by flex layout)
+  home_button_ = lv_btn_create(nav_bar_obj_);
+  lv_obj_set_size(home_button_, 60, NAV_BAR_HEIGHT - 10);
+  lv_obj_set_style_bg_color(home_button_, lv_color_white(), 0);
+  lv_obj_t* home_label = lv_label_create(home_button_);
+  lv_label_set_text(home_label, LV_SYMBOL_HOME);
+  lv_obj_set_style_text_color(home_label, lv_color_black(), 0);
+  lv_obj_align(home_label, LV_ALIGN_CENTER, 0, 0);
+
+  // Register keyboard event handler
+  esp_err_t err = esp_event_handler_instance_register(
+    UI_EVENT_BASE,
+    ESP_EVENT_ANY_ID,
+    [](void* handler_args, esp_event_base_t base, int32_t id, void* event_data) {
+      RootLayout* root_layout = static_cast<RootLayout*>(handler_args);
+      root_layout->on_keyboard_event_(handler_args, base, id, event_data);
+    },
+    this,
+    &keyboard_event_handler_instance_
+  );
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to register keyboard event handler: %s", esp_err_to_name(err));
+  }
+
+  ESP_LOGI(TAG, "Layout created with flexible design: Header=%d, NavBar=%d",
+    HEADER_HEIGHT, NAV_BAR_HEIGHT);
+
+  return ESP_OK;
+}
+
+esp_err_t RootLayout::deinit(void) {
+  // Unregister keyboard event handler
+  if (keyboard_event_handler_instance_) {
+    esp_event_handler_instance_unregister(
+      UI_EVENT_BASE,
+      ESP_EVENT_ANY_ID,
+      keyboard_event_handler_instance_
+    );
+    keyboard_event_handler_instance_ = nullptr;
+  }
+
+  header_obj_ = nullptr;
+  header_label_ = nullptr;
+  //
+  app_container_ = nullptr;
+  //
+  nav_bar_obj_ = nullptr;
+  back_button_ = nullptr;
+  home_button_ = nullptr;
+
+  return ESP_OK;
+}
+
+void RootLayout::hide_nav_bar(void) const {
+  if (nav_bar_obj_) {
+    lv_obj_add_flag(nav_bar_obj_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Navigation bar not initialized");
+  }
+}
+
+void RootLayout::show_nav_bar(void) const {
+  if (nav_bar_obj_) {
+    lv_obj_clear_flag(nav_bar_obj_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Navigation bar not initialized");
+  }
+}
+
+void RootLayout::show_back_button(void) const {
+  if (back_button_) {
+    lv_obj_clear_flag(back_button_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Back button not initialized");
+  }
+}
+
+void RootLayout::show_home_button(void) const {
+  if (home_button_) {
+    lv_obj_clear_flag(home_button_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Home button not found in navigation bar");
+  }
+}
+
+void RootLayout::hide_back_button(void) const {
+  if (back_button_) {
+    lv_obj_add_flag(back_button_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Back button not initialized");
+  }
+}
+
+void RootLayout::hide_home_button(void) const {
+  if (home_button_) {
+    lv_obj_add_flag(home_button_, LV_OBJ_FLAG_HIDDEN);
+  } else {
+    ESP_LOGW(TAG, "Home button not found in navigation bar");
+  }
+}
+
+esp_err_t RootLayout::register_back_button_callback(lv_event_cb_t callback, void* user_data, lv_event_dsc_t** out_event_dsc) const {
+  if (!back_button_) {
+    ESP_LOGE(TAG, "Back button not initialized");
+    return ESP_ERR_INVALID_STATE;
+  }
+  if (!callback) {
+    ESP_LOGE(TAG, "Invalid argument: callback is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+  if (out_event_dsc == nullptr) {
+    ESP_LOGE(TAG, "Invalid argument: out_event_dsc is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  *out_event_dsc = lv_obj_add_event_cb(back_button_, callback, LV_EVENT_CLICKED, user_data);
+
+  if (*out_event_dsc == nullptr) {
+    ESP_LOGE(TAG, "Failed to register back button callback");
+    return ESP_FAIL;
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t RootLayout::register_home_button_callback(lv_event_cb_t callback, void* user_data, lv_event_dsc_t** out_event_dsc) const {
+  if (!home_button_) {
+    ESP_LOGE(TAG, "Home button not found in navigation bar");
+    return ESP_ERR_NOT_FOUND;
+  }
+  if (!callback) {
+    ESP_LOGE(TAG, "Invalid argument: callback is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+  if (out_event_dsc == nullptr) {
+    ESP_LOGE(TAG, "Invalid argument: out_event_dsc is nullptr");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  *out_event_dsc = lv_obj_add_event_cb(home_button_, callback, LV_EVENT_CLICKED, user_data);
+
+  if (*out_event_dsc == nullptr) {
+    ESP_LOGE(TAG, "Failed to register home button callback");
+    return ESP_FAIL;
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t RootLayout::update_header(const std::string& title) const {
+  if (!header_label_) {
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  if (title.empty() == false) {
+    lv_label_set_text(header_label_, title.c_str());
+  } else {
+    lv_label_set_text(header_label_, "App");
+  }
+
+  return ESP_OK;
+}
+
+void RootLayout::on_keyboard_event_(void* handler_args, esp_event_base_t base, int32_t id, void* event_data) {
+  if (base != UI_EVENT_BASE) {
+    return;
+  }
+
+  switch (id) {
+    case UI_EVENT_KEYBOARD_SHOWN:
+      hide_nav_bar();
+      break;
+
+    case UI_EVENT_KEYBOARD_HIDDEN:
+      show_nav_bar();
+      break;
+
+    default:
+      ESP_LOGW(TAG, "Unknown keyboard event ID: %ld", id);
+      break;
+  }
+}

main/ui/root_layout.h

@@ -0,0 +1,126 @@
+#pragma once
+#include "esp_err.h"
+#include "esp_event.h"
+#include "lvgl.h"
+#include <string>
+
+// Forward declaration to avoid circular dependency
+class UIHandler;
+
+class RootLayout {
+public:
+  RootLayout() = default;
+  ~RootLayout();
+
+  /**
+   * @brief Initialize the root layout within the given parent object
+   *
+   * Sets up the header, app container, and navigation bar.
+   *
+   * @param parent Parent LVGL object to contain the layout
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t init(lv_obj_t* parent, UIHandler* ui_handler);
+
+  /**
+   * @brief Deinitialize the root layout
+   *
+   * Cleans up references to layout components.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t deinit(void);
+
+  /**
+   * @brief Show the back button in the navigation bar
+   */
+  void show_back_button(void) const;
+
+  /**
+   * @brief Hide the back button in the navigation bar
+   */
+  void hide_back_button(void) const;
+
+  /**
+   * @brief Show the home button in the navigation bar
+   */
+  void show_home_button(void) const;
+
+  /**
+   * @brief Hide the home button in the navigation bar
+   */
+  void hide_home_button(void) const;
+
+  /**
+   * @brief Show navigation bar
+   *
+   */
+  void show_nav_bar(void) const;
+
+  /**
+   * @brief Hide navigation bar
+   *
+   */
+  void hide_nav_bar(void) const;
+
+
+
+
+  /**
+   * @brief Register a callback for back button presses
+   *
+   *
+   * @param callback
+   * @param user_data
+   * @param out_event_dsc
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t register_back_button_callback(lv_event_cb_t callback, void* user_data, lv_event_dsc_t** out_event_dsc) const;
+
+  /**
+   * @brief Register a callback for home button presses
+   *
+   * @param callback
+   * @param user_data
+   * @param out_event_dsc
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t register_home_button_callback(lv_event_cb_t callback, void* user_data, lv_event_dsc_t** out_event_dsc) const;
+
+  /**
+   * @brief Update the header title text
+   *
+   * @param title New title text
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t update_header(const std::string& title) const;
+
+  /**
+   * @brief Get the app container object, which holds the active app's UI
+   * Caller can add/remove app UI elements to/from this container.
+   * Caller must not delete this object directly or edit its layout properties.
+   *
+   * @return lv_obj_t*
+   */
+  lv_obj_t* get_app_container() const {
+    return app_container_;
+  }
+
+private:
+
+  // Event handler for keyboard show/hide events
+  void on_keyboard_event_(void* handler_args, esp_event_base_t base, int32_t id, void* event_data);
+
+  // layout objects
+  // header
+  lv_obj_t* header_obj_ = nullptr;      ///< Header area object
+  lv_obj_t* header_label_ = nullptr;  ///< Header title label
+  // app container
+  lv_obj_t* app_container_ = nullptr;   ///< App container object
+  // navigation bar
+  lv_obj_t* nav_bar_obj_ = nullptr;     ///< Navigation bar object
+  lv_obj_t* back_button_ = nullptr;     ///< Back button object
+  lv_obj_t* home_button_ = nullptr;    ///< Home button object
+
+  esp_event_handler_instance_t keyboard_event_handler_instance_ = nullptr; ///< Event handler instance for keyboard events
+};

main/ui/ui_handler.cpp

@@ -0,0 +1,288 @@
+#include "ui/ui_handler.h"
+#include "esp_log.h"
+
+#define TAG "UIHandler"
+
+UIHandler::~UIHandler() {
+  deinit();
+}
+
+esp_err_t UIHandler::init(void) {
+  lv_obj_t* screen = lv_scr_act();
+  esp_err_t ret = ESP_OK;
+
+  // Create main screen layout
+  ret = create_main_screen_(screen);
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to create main screen layout");
+    return ret;
+  }
+
+  ret = interaction_handler_.init(root_layout_.get_app_container());
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize InteractionHandler");
+    return ret;
+  }
+
+  // Show the main screen
+  lv_scr_load(screen);
+
+  return ret;
+}
+
+esp_err_t UIHandler::deinit(void) {
+  // Deinitialize current app if any
+  if (active_descriptor_) {
+    UIApp* app = active_descriptor_->get_app_instance();
+    if (app) {
+      esp_err_t ret = app->deinit();
+      if (ret != ESP_OK) {
+        ESP_LOGE("UIHandler", "Failed to deinitialize current app");
+        return ret;
+      }
+    }
+    active_descriptor_ = nullptr;
+  }
+
+  // Destroy main screen layout
+  esp_err_t ret = destroy_main_screen_();
+  if (ret != ESP_OK) {
+    ESP_LOGE("UIHandler", "Failed to destroy main screen layout");
+    return ret;
+  }
+
+  // Deinitialize interaction handler
+  ret = interaction_handler_.deinit();
+  if (ret != ESP_OK) {
+    ESP_LOGE("UIHandler", "Failed to deinitialize InteractionHandler");
+    return ret;
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t UIHandler::switch_app(std::shared_ptr<AppDescriptor> app_descriptor) {
+  if (!app_descriptor) {
+    ESP_LOGE(TAG, "Invalid app descriptor");
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  esp_err_t ret = ESP_OK;
+
+  // Deinitialize current app if any
+  if (active_descriptor_) {
+    UIApp* current_app = active_descriptor_->get_app_instance();
+    if (current_app) {
+      ret = current_app->deinit();
+      if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to deinitialize current app");
+      }
+    }
+  }
+
+  // Clear the app container
+  lv_obj_t* app_container = root_layout_.get_app_container();
+  if (app_container) {
+    lv_obj_clean(app_container);
+  } else {
+    ESP_LOGE(TAG, "App container not available");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  // Set the new app as active
+  active_descriptor_ = app_descriptor;
+
+  // Initialize the new app
+  UIApp* new_app = active_descriptor_->get_app_instance();
+  if (!new_app) {
+    ESP_LOGE(TAG, "App instance not available");
+    active_descriptor_ = nullptr;
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  ret = new_app->init(app_container);
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize app: %s", new_app->get_name().c_str());
+    active_descriptor_ = nullptr;
+    return ret;
+  }
+
+  // Update header with app name
+  ret = update_header_title(new_app->get_name());
+  if (ret != ESP_OK) {
+    ESP_LOGW(TAG, "Failed to update header title");
+  }
+
+  // Show back button when in an app
+  root_layout_.show_back_button();
+
+  ESP_LOGI(TAG, "Switched to app: %s", new_app->get_name().c_str());
+
+  return ESP_OK;
+}
+
+esp_err_t UIHandler::show_shutdown_screen(const std::string& message) {
+  // Deinitialize current app if any
+  if (active_descriptor_) {
+    UIApp* app = active_descriptor_->get_app_instance();
+    if (app) {
+      app->deinit();
+    }
+    active_descriptor_ = nullptr;
+  }
+
+  // Clear the app container
+  lv_obj_t* app_container = root_layout_.get_app_container();
+  if (app_container) {
+    lv_obj_clean(app_container);
+
+    // Create a simple shutdown message screen
+    lv_obj_t* label = lv_label_create(app_container);
+    if (message.empty()) {
+      lv_label_set_text(label, "Shutting down...");
+    } else {
+      lv_label_set_text(label, message.c_str());
+    }
+    lv_obj_set_style_text_font(label, &lv_font_montserrat_14, 0);
+    lv_obj_center(label);
+  }
+
+  // Update header
+  update_header_title("System");
+
+  // Hide navigation buttons
+  root_layout_.hide_back_button();
+  root_layout_.hide_home_button();
+
+  ESP_LOGI(TAG, "Showing shutdown screen: %s", message.c_str());
+
+  return ESP_OK;
+}
+
+esp_err_t UIHandler::return_to_main_screen(void) {
+  esp_err_t ret = ESP_OK;
+
+  // Deinitialize current app if any
+  if (active_descriptor_) {
+    UIApp* app = active_descriptor_->get_app_instance();
+    if (app) {
+      ret = app->deinit();
+      if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to deinitialize app");
+        return ret;
+      }
+    }
+    active_descriptor_ = nullptr;
+  }
+
+  // Clear the app container
+  lv_obj_t* app_container = root_layout_.get_app_container();
+  if (app_container) {
+    lv_obj_clean(app_container);
+
+    // TODO: Display app launcher/home screen with app icons
+    // For now, just show a placeholder message
+    lv_obj_t* label = lv_label_create(app_container);
+    lv_label_set_text(label, "Home Screen\n\nApp icons will go here");
+    lv_obj_set_style_text_align(label, LV_TEXT_ALIGN_CENTER, 0);
+    lv_obj_center(label);
+  } else {
+    ESP_LOGE(TAG, "App container not available");
+    return ESP_ERR_INVALID_STATE;
+  }
+
+  // Update header
+  ret = update_header_title("Home");
+  if (ret != ESP_OK) {
+    ESP_LOGW(TAG, "Failed to update header title");
+  }
+
+  // Hide back button on home screen
+  root_layout_.hide_back_button();
+
+  ESP_LOGI(TAG, "Returned to main screen");
+
+  return ESP_OK;
+}
+
+esp_err_t UIHandler::update_header_title(const std::string& title) {
+  return root_layout_.update_header(title);
+}
+
+//
+// Private methods
+//
+
+void UIHandler::on_back_button_pressed_(void) {
+
+  if (active_descriptor_) {
+    UIApp* app = active_descriptor_->get_app_instance();
+    if (app) {
+      bool handled = app->on_back_button_pressed();
+      if (!handled) {
+        // App didn't handle it, return to main screen
+        return_to_main_screen();
+      }
+    }
+  } else {
+    ESP_LOGW(TAG, "Back button pressed but no active app");
+  }
+}
+
+esp_err_t UIHandler::create_main_screen_(lv_obj_t* parent) {
+  esp_err_t ret = ESP_OK;
+
+  // Initialize root layout
+  ret = root_layout_.init(parent, this);
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to initialize RootLayout");
+    return ret;
+  }
+
+  // Register back button callback
+  lv_event_dsc_t* back_event_dsc = nullptr;
+  ret = root_layout_.register_back_button_callback(
+    [](lv_event_t* e) {
+      UIHandler* ui_handler = static_cast<UIHandler*>(lv_event_get_user_data(e));
+      ui_handler->on_back_button_pressed_();
+    },
+    this,
+    &back_event_dsc
+  );
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to register back button callback");
+    return ret;
+  }
+
+  // Register home button callback
+  lv_event_dsc_t* home_event_dsc = nullptr;
+  ret = root_layout_.register_home_button_callback(
+    [](lv_event_t* e) {
+      UIHandler* ui_handler = static_cast<UIHandler*>(lv_event_get_user_data(e));
+      ui_handler->return_to_main_screen();
+    },
+    this,
+    &home_event_dsc
+  );
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to register home button callback");
+    return ret;
+  }
+
+  ESP_LOGI(TAG, "Main screen layout created successfully");
+
+  return ESP_OK;
+}
+
+esp_err_t UIHandler::destroy_main_screen_(void) {
+  esp_err_t ret = root_layout_.deinit();
+  if (ret != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to deinitialize RootLayout");
+    return ret;
+  }
+
+  ESP_LOGI(TAG, "Main screen layout destroyed successfully");
+  return ESP_OK;
+}
+
+

main/ui/ui_handler.h

@@ -0,0 +1,118 @@
+#pragma once
+
+#include "esp_err.h"
+#include "ui/apps/app.h"
+#include "ui/events.h"
+#include "ui/root_layout.h"
+#include "ui/interaction_handler.h"
+#include "lvgl.h"
+#include <memory>
+
+/**
+ * @brief UI Handler - manages app lifecycle and rendering
+ *
+ * The UIHandler manages:
+ * - Creation and destruction of UI apps
+ * - Switching between apps
+ * - Main screen layout (header, app container, navigation bar)
+ * - System event routing to active app
+ * - Displaying special screens (shutdown, etc.)
+ */
+class UIHandler {
+public:
+
+  UIHandler() = default;
+  ~UIHandler();
+
+  /**
+   * @brief Initialize the UI system with default layout
+   *
+   * Creates the main screen with:
+   * - Header area (top)
+   * - App container (middle)
+   * - Navigation bar (bottom)
+   *
+   * And display the main screen.
+   *
+   * And initializes the InteractionHandler, callbacks, etc.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t init(void);
+
+  /**
+   * @brief Deinitialize the UI system
+   *
+   * Cleans up the current app and destroys the main screen.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t deinit(void);
+
+  /**
+   * @brief Switch to a new app by its descriptor
+   *
+   * Deinitializes the current app (if any), initializes the new app,
+   * and updates the display. Holds shared ownership of the descriptor
+   * to ensure the app remains valid while active.
+   *
+   * @param app_descriptor Shared pointer to the app descriptor
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t switch_app(std::shared_ptr<AppDescriptor> app_descriptor);
+
+  /**
+   * @brief Display shutdown screen
+   *
+   * Shows a shutdown screen with a message. Typically called
+   * before the system enters deep sleep or powers off.
+   *
+   * @param message Optional message to display (e.g., "Shutting down...")
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t show_shutdown_screen(const std::string& message = "");
+
+  /**
+   * @brief Get the main screen object
+   *
+   * @return lv_obj_t* pointer to the main screen
+   */
+  lv_obj_t* get_main_screen(void) const {
+    return main_screen_;
+  }
+
+  esp_err_t update_header_title(const std::string& title);
+
+  /**
+   * @brief Return to main screen (deinit app and show app icons)
+   *
+   * Deinitializes the active app and displays the app icons
+   * in the navigation bar, returning to the home screen.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  esp_err_t return_to_main_screen(void);
+
+private:
+
+  // Handle back button press, route to active app if any
+  void on_back_button_pressed_(void);
+
+  // Helper to create the main screen layout
+  esp_err_t create_main_screen_(lv_obj_t* parent);
+
+  // Helper to destroy the main screen layout
+  esp_err_t destroy_main_screen_(void);
+
+  // delete copy constructor and assignment operator
+  // to prevent copying of the UIHandler instance
+  UIHandler(const UIHandler&) = delete;
+  UIHandler& operator=(const UIHandler&) = delete;
+
+
+  InteractionHandler interaction_handler_;  ///< Manages user interactions
+
+  lv_obj_t* main_screen_ = nullptr;    ///< Root screen
+  RootLayout root_layout_;            ///< Main screen layout manager
+  std::shared_ptr<AppDescriptor> active_descriptor_ = nullptr;  ///< Currently active app descriptor (shared ownership)
+};

main/ui/widgets/textarea.cpp

@@ -0,0 +1,10 @@
+#include "ui/widgets/textarea.h"
+
+lv_obj_t* textarea_create(lv_obj_t* parent) {
+  lv_obj_t* textarea = lv_textarea_create(parent);
+  // disable animations for cursor and selection for instant response
+  lv_obj_set_style_anim_time(textarea, 0, LV_PART_CURSOR | LV_STATE_FOCUSED);
+
+  return textarea;
+}
+

main/ui/widgets/textarea.h

@@ -0,0 +1,4 @@
+#pragma once
+#include "lvgl.h"
+
+lv_obj_t* textarea_create(lv_obj_t* parent);

partitions.csv

@@ -0,0 +1,12 @@
+# Name,   Type, SubType,  Offset,   Size,       Flags
+# NVS 256KB
+nvs,      data, nvs,      ,         0x40000,
+# OTA Data 8KB
+otadata,  data, ota,      ,         0x2000,
+# PHY Init 4KB
+phy_init, data, phy,      ,         0x1000,
+# OTA Partitions 10MB
+ota_0,    app,  ota_0,    ,         0xA00000,
+ota_1,    app,  ota_1,    ,         0xA00000,
+# LittleFS 11MB
+storage,  data, littlefs,     ,         0xB00000,

pytest_hello_world.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import hashlib
+import logging
+from typing import Callable
+
+import pytest
+from pytest_embedded_idf.dut import IdfDut
+from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_qemu.app import QemuApp
+from pytest_embedded_qemu.dut import QemuDut
+
+
+@pytest.mark.generic
+@idf_parametrize('target', ['supported_targets', 'preview_targets'], indirect=['target'])
+def test_hello_world(dut: IdfDut, log_minimum_free_heap_size: Callable[..., None]) -> None:
+    dut.expect('Hello world!')
+    log_minimum_free_heap_size()
+
+
+@pytest.mark.host_test
+@idf_parametrize('target', ['linux'], indirect=['target'])
+def test_hello_world_linux(dut: IdfDut) -> None:
+    dut.expect('Hello world!')
+
+
+@pytest.mark.host_test
+@pytest.mark.macos_shell
+@idf_parametrize('target', ['linux'], indirect=['target'])
+def test_hello_world_macos(dut: IdfDut) -> None:
+    dut.expect('Hello world!')
+
+
+def verify_elf_sha256_embedding(app: QemuApp, sha256_reported: str) -> None:
+    sha256 = hashlib.sha256()
+    with open(app.elf_file, 'rb') as f:
+        sha256.update(f.read())
+    sha256_expected = sha256.hexdigest()
+
+    logging.info(f'ELF file SHA256: {sha256_expected}')
+    logging.info(f'ELF file SHA256 (reported by the app): {sha256_reported}')
+
+    # the app reports only the first several hex characters of the SHA256, check that they match
+    if not sha256_expected.startswith(sha256_reported):
+        raise ValueError('ELF file SHA256 mismatch')
+
+
+@pytest.mark.host_test
+@pytest.mark.qemu
+@idf_parametrize('target', ['esp32', 'esp32c3'], indirect=['target'])
+def test_hello_world_host(app: QemuApp, dut: QemuDut) -> None:
+    sha256_reported = dut.expect(r'ELF file SHA256:\s+([a-f0-9]+)').group(1).decode('utf-8')
+    verify_elf_sha256_embedding(app, sha256_reported)
+
+    dut.expect('Hello world!')

wokwi.toml

@@ -0,0 +1,4 @@
+[wokwi]
+version = 1
+firmware = 'build/flasher_args.json'
+elf = "build/ink-board.elf"