Mastro OS has two separate firmware targets: an ESP-IDF/LVGL Time Bank watch for the Waveshare ESP32-S3-Touch-AMOLED-1.8 V2, and an InfiniTime-based SilverCare watch for the original Pine64 PineTime. Firmware packages are not interchangeable. Waveshare remains the only physically verified profile; PineTime 0.1.11 still needs physical validation.
Copyright (C) 2026 Mastro OS contributors. Original Mastro OS work is licensed
under GNU GPL version 3 only (GPL-3.0-only); see LICENSE.
Third-party code, icons, fonts and reference material retain their own terms;
see THIRD_PARTY_NOTICES.md for scope, attribution and
firmware distribution requirements. The separate Silver Bank app is not
licensed by this repository.
Commercial use is allowed, but distributed GPL-covered derivatives must retain the GPL and provide the required matching source. There is no warranty.
| Area | Verified | Still required |
|---|---|---|
| PineTime 0.1.11 candidate | ARM build, package checks and local SHA-256 verification | Physical installation, sensor accuracy, battery life and BLE radio tests |
| Native desktop simulator | Actual watch C++/LVGL rendering, navigation, save-failure handling and sanitizer/browser regression checks | Real MCU timing, sensor behavior, flash power-loss safety and radio validation |
| Silver Bank companion | Local 1.6 app receiver tests, responsive browser checks and Xcode iPhone-simulator build/startup | Real iPhone/watch data delivery, signing for physical installation and backend integration |
Simulator readings and mocked Bluetooth packets are test inputs, not evidence of a connected physical watch. The native iPhone simulator does not support watch-to-phone BLE testing.
- Waveshare ESP32-S3-Touch-AMOLED-1.8 V2
- ESP32-S3 with 16 MB flash and 8 MB octal PSRAM
- 368 x 448 CO5300 QSPI AMOLED
- CST816S/CST820-compatible capacitive touch controller
- PCF85063 real-time clock
- TCA9554 peripheral reset and power control
The firmware performs profile-specific flash and PSRAM preflight checks before initializing board peripherals. See BOARD_SUPPORT.md for verified and planned targets. Do not flash another model under the Waveshare profile.
See targets/pinetime/README.md for the independent build and installation workflow. The Mastro face uses real controller data. SilverCare automatically starts a stopped heart sensor on entry, stops its own measurement after 60 seconds or on exit, and refreshes real steps every 500 ms. Fixed-size labels prevent dynamic text from shifting the layout.
The launcher now uses six colorful circular icons per page in a staggered layout, with existing swipe paging and native app actions. It is Mastro's own design, not Apple software or artwork.
The Mastro Analog face has luminous, California-style, and Solar Dial modes adapted from the supplied photo references. Long-press cycles modes; the lower corners on circular modes control a local three-minute timer and real sensor/device readings. Weather and UV remain unavailable. See the implementation and assumptions and offline face preview. This is not identical Apple Watch software or a pixel-exact native replica.
Version 0.1.11 saves the selected analog face to LittleFS and restores it after navigation and restart. Failed saves preserve the last good choice and show NOT SAVED; temporary-file replacement avoids truncating the saved record. It retains refreshed RTC-backed hands, time-driven Solar lighting, restored icons, native circular arcs, bounded entry motion, and care-session fixes. Phone time-sync is still required for absolute accuracy; Solar estimates remain fixed to Hong Kong. The native desktop simulator imports the actual C++/LVGL launcher, watch faces, and SilverCare with hardware mocks and automated sanitizer/browser gates. "Silverware" was not found as a separate app; this tests SilverCare.
The current local OTA artifact is targets/pinetime/output/mastro-os-pinetime-0.1.11-dfu.zip, with SHA256SUMS beside it. Generated output is ignored by Git and is not included in the GitHub source checkout. Install the ZIP intact through a compatible Bluetooth OTA client, then validate the image on the watch. The charging cradle supplies power only. Never use ESP32 flashing scripts or raw BIN/HEX files on a sealed PineTime.
The source also fixes motion-service notification guards: connection handle zero is valid, disconnected devices are rejected before packet allocation, and allocation failure is handled. This additional BLE fix is not in the previously built local 0.1.11 ZIP; rebuild and verify the firmware before testing it on hardware. The companion's periodic step reads avoid relying on that notification fix.
Check-in and Help are local only; delivery to a family member or emergency service is not implemented. preview/pinetime.html uses simulated values, not a live watch connection. Build verification does not establish physical sensor accuracy or battery life.
The companion project is Silver Bank. Its new local 1.6 app implementation is maintained in a separate Silver_bank checkout, not inside Mastro OS. Updating this OS repository does not publish the companion app's local changes.
- Pairing requires explicit consent in the installed native mobile app.
- While connected in the foreground, battery and steps are read automatically, with a 15-second refresh fallback. Heart rate uses notifications from the watch's active measurement session; stale values are cleared rather than treating cached reads as new measurements.
- Readings include watch identity and the phone's receipt time, not a verified sensor-acquisition timestamp. Disconnect or account changes clear visible session data.
- Reconnection attempts are bounded and session-only. Background execution and continuous unattended delivery are not guaranteed.
- These session readings are not uploaded to the backend. They do not sync time credits, deliver Help/check-in events, remotely start sensors or certify medical measurements.
The app's native startup and formatting have been checked with Xcode's iPhone simulator, but successful physical Bluetooth transmission and connection stability remain unverified. A real iPhone and PineTime are required for that acceptance test.
- Live RTC-backed watch face with date, weekday, weather and Solar Dial data
- Touch gestures between the watch face, launcher and Control Center
- Registry-driven app grid with a native Time Bank entry
- Pixel-art Time Bank screen with an offline balance, bounded ledger history and 15-minute credit/debit actions
- Development BLE health-event service requiring encrypted access, with a bounded acknowledgement-based outbox; phone/backend delivery still requires end-to-end validation
- Capability-aware health glyph that stays muted when no pulse sensor is fitted
- Hardware brightness control with idle dimming and display sleep
- Functional Wi-Fi, time-format, synchronization, torch and theater controls
- On-watch Wi-Fi credential entry and persistent settings
- SNTP synchronization with RTC persistence
- Hong Kong time and location defaults
- Network-backed weather refresh
- GUI task watchdog and hardware startup checks
- Factory flash backup and verified restore tooling
- Reproducible release packaging with SHA-256 checksums
Most launcher entries currently open reusable app-shell views rather than complete phone, health, navigation or messaging services. Settings, watch-face data, navigation and Control Center hardware actions are the primary implemented workflows.
The ESP32 Time Bank starts with a four-hour demonstration balance, not an authoritative community balance. Its health drivers currently return unsupported and do not fabricate readings. See TIME_BANK.md and HEALTH_SYNC.md.
main.c- hardware preflight and firmware startuphal/- AMOLED, touch and RTC hardware abstractionhal/watch_board.h- board adapter contract for additional ESP32 watchesui/- LVGL screens, gestures and display lifecycleapps/- launcher application registryservices/time_bank.*- pure offline balance and bounded ledger logicservices/health_telemetry.*- versioned health packets and replay-safe outboxservices/health_ble_service.*- encrypted NimBLE transport used by the phone appui/screens/screen_time_bank.*- icon-only pixel Time Bank interfaceutils/- Wi-Fi, time, weather and settings servicesastronomy/- Solar Dial calculations and host testsscripts/- tests, safe flashing, restore and release packagingHARDWARE.md- board-specific build and flashing requirementsBOARD_SUPPORT.md- verified targets and port acceptance requirementstargets/pinetime/- pinned InfiniTime overlay, macOS build scripts and sealed-watch OTA guidancesimulator/- native C++/LVGL desktop runtime, hardware mocks and automated regression checkspreview/- offline watch previews; values are simulated, not received over Bluetoothdocs/- watch-face behavior, visual references and implementation assumptionsSECURITY.md- security posture, limitations and secret handlingTIME_BANK.md- ledger semantics, visual language and synchronization boundaryHEALTH_SYNC.md- watch-to-app health protocol, deployment and safety boundary
The scripts expect ESP-IDF 5.5.5 at ~/esp/esp-idf-v5.5.5 by default.
./scripts/test.shThis runs host tests for Solar Dial, possible-collapse logic, local check-in, Time Bank, and health telemetry, followed by a complete ESP-IDF firmware build. These logic tests do not certify collapse detection or clinical measurements. To build manually:
source "$HOME/esp/esp-idf-v5.5.5/export.sh"
idf.py -D WATCH_BOARD=waveshare_amoled_1_8_v2 reconfigure buildESP-IDF compiles the ESP32 C sources with warnings enabled and provides type and link validation for that target. PineTime has its own ARM build. The HTML previews use browser JavaScript and a bundled Lucide library. The simulator has its own Node package and browser-test dependencies; there is no root web-app package or TypeScript configuration. Do not install app tooling at the firmware root or copy the Silver Bank app into this repository.
For PineTime build/OTA instructions, use the target guide. For native simulation setup and test commands, use the simulator guide. The offline face preview can be opened directly without a development server; it is a visual reference, not firmware emulation.
Read HARDWARE.md before connecting the board. The recommended first-flash command is:
./scripts/flash_safe.sh /dev/cu.usbmodemXXXXThe script verifies the ESP32-S3, backs up the complete 16 MB factory flash, verifies that backup and flashes using ESP-IDF's generated arguments. This board requires a DIO ROM image header and a watchdog reset after flashing; forcing QIO in a merged image can prevent boot.
To restore a verified factory image:
./scripts/restore_factory.sh backups/factory-TIMESTAMP.bin /dev/cu.usbmodemXXXX --yes./scripts/package_release.shGenerated binaries and checksums are written to release/. Publish those files through GitHub Releases rather than committing them to the source tree.
Read SECURITY.md before entering real network credentials or sharing a flash backup. The current development configuration stores the Wi-Fi SSID and password in NVS without flash encryption. Anyone with physical access to the watch or a complete flash backup may be able to recover them.
Wi-Fi driver persistence is RAM-only, HTTPS redirects are rejected, and Settings provides a long-press Hold Erase action for decommissioning. The firmware does not accept compile-time Wi-Fi credentials because those remain recoverable from distributed binaries. Logical deletion cannot defeat forensic recovery from unencrypted flash.
Weather requests use HTTPS with ESP-IDF's trusted certificate bundle. SNTP time
sync is not cryptographically authenticated and must not be treated as a trusted
time source for security decisions. Secure boot, flash encryption and signed OTA
are not implemented for the ESP32 target. Its health characteristics require BLE
encryption; bonding alone does not establish account-level device enrollment.
Authenticated storage and backend acknowledgements are companion requirements,
not proof that the watch is connected to a working service.
services/silvercare_companion_protocol.h defines the transport-neutral v1
snapshot expected by the SilverCare phone app. See HEALTH_SYNC.md for the
implemented health-event transport and its remaining hardware limitations.
Release SHA-256 files detect accidental corruption but do not prove who created
an image.
Do not commit credentials, distribute files from backups/, or present launcher
app shells as connected phone, health or emergency services.
Mastro OS is an experimental hardware project, not a commercial wearable, medical device or safety-critical system. Display, touch, RTC, Wi-Fi, brightness, navigation and release workflows have been exercised on the target board, but physical hardware revisions and third-party services can change behavior.