Initial commit

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