# 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.