open-smartwatch/open-smartwatch-os

<explanation>

1. Identify the project type and purpose

- This repository is the firmware and toolchain for an open‑source smartwatch OS (“open‑smartwatch-os”), plus a host‑side emulator.

- Key indicators:

• In README: build instructions using PlatformIO and CMake (for emulator).

• File tree: “src/”, “include/”, “lib/”, and “platformio.ini” for embedded firmware; “emulator/” and “CMakeLists.txt” for host emulator; “scripts/” for asset pre‑build; “data/” and “docs/” for sample apps and documentation.

2. Analyze the file structure

- Top‑level directories:

• include/: public headers for OS HAL, devices, services, UI, Lua bindings, and assets

• src/: implementation of HAL, drivers, OS core, animations, apps, services, Lua integration

• lib/: bundled third‑party libraries (Lua interpreter, graphics, sensors)

• emulator/: host emulator code reimplementing Arduino/ESP32 APIs, plus unit/UI tests

• scripts/: Python and shell scripts to generate code from assets, capture screenshots

• data/: sample Lua scripts and libraries for watch apps

• platformio.ini & CMakeLists.txt: build configurations

- Patterns:

• Firmware uses a layered architecture: HAL → Drivers → OS Core → Services → Applications

• Emulator is a parallel CMake project that fakes hardware layers using SDL2/ImGUI

• Scripts preprocess assets (images, maps) into C headers, plugged into include/assets and src/assets

3. Examine the README for additional insights

- The README describes two build flows:

• Firmware: PlatformIO for multiple watch hardware variants

• Emulator: CMake + SDL2 for rapid UI and unit/UI test development

- It mentions key components:

• Lua scripting support via SWIG

• Screen server feature for screenshots

• OS console commands via serial

- Testing: unit/UI tests in emulator/src/tests

4. How to create the system design diagram

a. Main components

1. Development Environment

- PlatformIO CLI/VSCode, Python/requirements.txt, SWIG, git-lfs

2. Build System

- PlatformIO build pipeline (platformio.ini, scripts/prebuild_*.py)

- CMake build for emulator (CMakeLists.txt)

3. Firmware Image (runs on ESP32/watch hardware)

- Hardware Abstraction Layer (include/hal + src/hal)

- Device Drivers (include/devices + src/devices)

- Core OS Services (include/services + src/services + OswServiceManager)

- UI Framework (include/osw_ui + src/osw_ui)

- Lua Runtime (lib/LUA + include/osw_lua + SWIG bindings)

- Applications (C/C++ apps in src/apps and data/lua/apps)

- Assets (images, fonts, maps injected via include/assets and scripts)

4. Emulator (runs on host)

- Emulated Arduino/ESP32 APIs (emulator/include + emulator/src)

- Third‑party libs: SDL2, ImGUI, ArduinoJson, Jzon

- Emulator main binary (build via CMake)

- Unit/UI Test Harness (emulator/src/tests)

5. External Services

- Serial console over USB (OswServiceTaskConsole)

- BLE, Wi-Fi, Webserver services (OswServiceTaskBLEServer, OswServiceTaskWebserver)

- ScreenServer (RAW_SCREEN_SERVER)

b. Relationships and interactions

- Build System → (generates) → Firmware Image → (flashed to) → Watch Hardware

- Firmware Image ↔ Hardware (via HAL & Drivers)

- Firmware Image ↔ Developer (via Serial console, BLE, Wi‑Fi)

- Emulator build → Emulator binary → (runs on) → Host OS

- Emulator simulates HAL & Drivers, so Firmware Image can run unmodified in emulator

- Scripts → (preprocess) → Assets/C headers → (compiled into) → Firmware

c. Architectural patterns/design principles

- Layered architecture: clear separation HAL ↔ Drivers ↔ Core ↔ Services ↔ Apps

- Plugin‑style Applications: each app implements a common interface (OswAppV1/V2)

- Service‑oriented: individual OswServiceTask* components managed by OswServiceManager

- Cross‑platform abstraction: same OS core runs on hardware and in emulator

d. Key technologies/frameworks/libraries

- Embedded: ESP32, PlatformIO, Arduino‑style HAL, SWIG for Lua

- Host emulator: SDL2, ImGUI, ArduinoJson, Jzon, utest

- Asset pipeline: Python scripts, shell scripts, ImageMagick for screenshots

- C++17, CMake for emulator; C/C++ for firmware

5. Guidelines for tailoring the diagram

- Emphasize the two runtime targets:

1. Firmware on Watch Hardware

2. Emulator on Host

- Draw them side by side, sharing the “OS Core” block to show reuse

- For firmware:

• Show PlatformIO build invoking scripts → compiles include/, src/, lib/ → firmware.bin

• Show the hardware block (ESP32 SoC, sensors, display, buttons) with arrows to HAL/Drivers

• Show services (BLE, Wi‑Fi, console) as separate blocks contacting external devices

• Show Lua scripts loaded at runtime via osw_lua

- For emulator:

• Show CMake build → emulator.run

• Show SDL2/ImGUI feeding input/display to the OS core

• Show test harness invoking unitTests/uiTests in emulator

6. Diagram elements

- Clear labels: e.g., “HAL”, “Device Drivers”, “OS Core Services”, “Applications”, “Emulator API”

- Directional arrows:

• From Build System → Firmware/Emulator binaries

• From Firmware → Hardware (and vice versa)

• From Emulator → Host OS libs

• From Apps → OS Core → Drivers → Hardware

- Color coding/shapes:

• Rectangles for software components

• Cylinders for data (configuration, assets)

• Clouds for external services (BLE, Wi‑Fi)

• Dashed boundary boxes around “Firmware Target” and “Emulator Target”

7. Emphasis

- Capture all layers: build, OS core, services, apps, emulator

- Don’t over‑abstract—preserve HAL vs Drivers vs Services vs Apps separation

- Include asset pipeline and test harness as first‑class parts of the system

</explanation>