136 lines
2.8 KiB
Markdown
136 lines
2.8 KiB
Markdown
# Vaka OS
|
||
|
||
> **WARNING**
|
||
> Vaka OS is an early-stage experimental firmware project.
|
||
> It is currently **beta / experimental software** and may be unsafe to run on real hardware.
|
||
> Installing experimental firmware can **brick your device**, **break OTA**, or require **SWD recovery**.
|
||
> Proceed only if you understand the risks.
|
||
|
||
Vaka OS is a Rust-first firmware project primarily targeting the **PineTime smartwatch**.
|
||
The project focuses on experimenting with a modern Rust embedded stack and a shared UI system that can run both on device and in a desktop simulator.
|
||
|
||
The primary goals are:
|
||
|
||
- Full Rust control over the firmware stack
|
||
- A simulator-driven development workflow
|
||
- A UI architecture reusable between firmware and simulator
|
||
- Safe OTA experimentation using a dual-firmware verification model
|
||
|
||
## Workspace Layout
|
||
```
|
||
crates/
|
||
firmware/
|
||
simulator/
|
||
ui/
|
||
|
||
docs/
|
||
Readme.md
|
||
Cargo.toml
|
||
```
|
||
|
||
### crates
|
||
|
||
- **firmware** – firmware running on the watch
|
||
- **simulator** – desktop environment for development
|
||
- **ui** – shared UI code usable by firmware and simulator
|
||
|
||
See **docs/architecture.md**.
|
||
|
||
### docs
|
||
|
||
Supporting documentation.
|
||
|
||
## Development Modes
|
||
|
||
Vaka OS supports two workflows.
|
||
|
||
### Simulator / Development Mode
|
||
|
||
Used for fast iteration without flashing the device.
|
||
|
||
Typical loop:
|
||
|
||
|
||
edit code
|
||
run simulator
|
||
test behavior
|
||
repeat
|
||
|
||
|
||
Used for:
|
||
|
||
- UI layout
|
||
- interaction logic
|
||
- application experimentation
|
||
|
||
Simulator success **does not guarantee hardware success**.
|
||
|
||
|
||
### Device Mode (Build and Upload)
|
||
|
||
Used when testing on the actual PineTime hardware.
|
||
|
||
Typical loop:
|
||
|
||
- build firmware
|
||
- package OTA update
|
||
- upload to watch
|
||
- boot firmware
|
||
- verify behavior
|
||
|
||
See **docs/development.md**.
|
||
|
||
|
||
## Dual Firmware Verification Model
|
||
|
||
PineTime firmware updates typically follow a **dual-slot update model**.
|
||
|
||
The device contains two firmware areas:
|
||
|
||
- slot A → currently running firmware
|
||
- slot B → new firmware update
|
||
|
||
Typical OTA update process:
|
||
|
||
1. New firmware is uploaded to the **inactive slot**
|
||
2. Bootloader boots the new firmware **once**
|
||
3. Firmware runs in **unconfirmed state**
|
||
4. User manually verifies functionality
|
||
5. Firmware confirms itself
|
||
6. Bootloader marks it as the new permanent firmware
|
||
|
||
If firmware **fails to confirm**:
|
||
|
||
|
||
reboot → bootloader restores previous firmware
|
||
|
||
|
||
This provides protection against broken updates.
|
||
|
||
Vaka OS intends to use a workflow compatible with this behavior.
|
||
|
||
|
||
## OTA Safety Rules
|
||
|
||
Important development rules:
|
||
|
||
- Never overwrite the bootloader
|
||
- Always test new firmware as **unconfirmed**
|
||
- Keep a working firmware available
|
||
- Do not assume simulator success equals hardware safety
|
||
|
||
## Documentation
|
||
|
||
See:
|
||
|
||
- docs/architecture.md
|
||
- docs/development.md
|
||
- docs/hardware.md
|
||
- docs/roadmap.md
|
||
|
||
|
||
## Project Status
|
||
|
||
Early project setup and architecture exploration.
|
||
|