VakaOS/Readme.md

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.