Initial commit

docs/architecture.md

@@ -0,0 +1,77 @@
+# Architecture
+
+## Core Crates
+
+### ui
+
+Shared UI layer used by both firmware and simulator.
+
+Responsibilities:
+
+- application views
+- layout logic
+- widget composition
+- UI state
+- event abstraction
+
+The goal is to keep most UI logic portable between simulator and hardware.
+
+
+### firmware
+
+The firmware crate targets **PineTime hardware**.
+
+Responsibilities:
+
+- hardware initialization
+- display driver integration
+- BLE stack integration
+- input and touch handling
+- power management
+- system services
+
+
+### simulator
+
+Desktop environment used for development.
+
+Responsibilities:
+
+- run UI without hardware
+- simulate events and inputs
+- allow rapid UI iteration
+- reduce flashing cycles
+
+
+## Rendering Model
+
+The expected rendering stack is:
+
+```
+     ratatui
+        ↓
+    mousefood
+        ↓
+ embedded-graphics
+        ↓
+  display driver
+```
+
+Simulator rendering will use a different backend but share the UI layer.
+
+
+## Simulator Role
+
+The simulator exists to improve development speed.
+
+It should help with:
+
+- UI development
+- event testing
+- application logic
+
+However:
+
+Simulator correctness does **not guarantee hardware correctness**.
+
+Timing, memory limits, BLE behavior, and display performance must still be tested on the real device.

docs/development.md

@@ -0,0 +1,107 @@
+# Development
+
+Two modes exist:
+
+- simulator development
+- device firmware development
+
+
+# Simulator Development Mode
+
+Used for rapid iteration.
+
+Typical loop:
+
+
+edit code
+run simulator
+inspect UI behavior
+repeat
+
+
+Use this mode for:
+
+- layout development
+- UI interaction
+- application logic
+
+Simulator behavior may differ from hardware.
+
+---
+
+# Device Firmware Mode
+
+Used when testing on the PineTime.
+
+Typical loop:
+
+
+cargo build
+generate firmware image
+package OTA update
+upload to watch
+reboot device
+verify behavior
+
+
+Testing on hardware is necessary for:
+
+- BLE
+- memory limits
+- timing behavior
+- display performance
+
+---
+
+# OTA Packaging
+
+The intended artifact chain is:
+
+
+cargo build
+→ firmware ELF
+→ binary image
+→ OTA zip package
+→ upload via companion app
+
+
+Exact tooling may evolve as the project stabilizes.
+
+---
+
+# OTA Verification
+
+The PineTime bootloader uses a verification model.
+
+Steps:
+
+1. firmware installed to secondary slot
+2. bootloader boots new firmware once
+3. firmware runs in **unconfirmed state**
+4. firmware must confirm itself
+5. bootloader marks it permanent
+
+If confirmation does not happen:
+
+
+reboot → previous firmware restored
+
+
+---
+
+# Safety Guidelines
+
+Bootloader safety:
+
+- never overwrite bootloader memory
+- treat bootloader as protected space
+
+Firmware safety:
+
+- avoid breaking both firmware slots
+- always test new firmware as unconfirmed
+
+Development discipline:
+
+- simulator success is not sufficient
+- always validate hardware behavior

docs/hardware.md

@@ -0,0 +1,72 @@
+# Hardware
+
+Current target: **PineTime smartwatch**.
+
+PineTime is an open hardware smartwatch designed by Pine64.
+
+It is capable of running fully custom firmware.
+
+
+## Core Specifications
+
+Main hardware components include:
+
+- Nordic **nRF52832** MCU (ARM Cortex-M4F)
+- 64 KB RAM
+- 512 KB internal flash
+- additional **4 MB SPI NOR flash** for assets
+- Bluetooth Low Energy support
+
+The CPU runs at **64 MHz** and includes a floating-point unit.
+
+## Display
+
+PineTime includes:
+
+- 1.3 inch IPS display
+- resolution **240×240**
+- **ST7789 display controller**
+- capacitive touchscreen controller
+
+The display is connected through SPI.
+
+## Sensors
+
+The device contains several sensors and peripherals:
+
+- BMA421 accelerometer
+- HRS3300 heart rate sensor
+- vibration motor
+- capacitive touchscreen
+
+These are typically connected over I²C.
+
+
+## Battery
+
+PineTime uses a small Li-Po battery around **170-180 mAh** capacity.
+
+Battery life depends heavily on firmware design and BLE usage.
+
+
+## Development Constraints
+
+Important constraints for firmware design:
+
+- very limited RAM (64 KB)
+- limited internal flash (512 KB)
+- firmware must run entirely from internal flash
+- external flash cannot execute code
+
+The external flash is mainly used for:
+
+- fonts
+- assets
+- large UI resources.
+
+
+## Future Hardware Support
+
+Vaka OS is designed primarily for PineTime.
+
+Portability may be considered later but is **not a primary goal** during early development.

docs/roadmap.md

@@ -0,0 +1,15 @@
+# Roadmap
+
+- [ ] establish workspace structure
+- [ ] basic rendering pipeline
+- [ ] simulator UI testing
+- [ ] display driver integration
+- [ ] input and touch handling
+- [ ] basic BLE functionality
+- [ ] OTA artifact packaging
+- [ ] Gadgetbridge compatibility experiments
+- [ ] stable OTA workflow
+- [ ] firmware verification logic
+- [ ] improved simulator fidelity
+- [ ] device services architecture
+