Skip to content

About

Reverse engineered tooling and documentation for custom firmware and connection workflow for CMF Watch Pro 2

Resources

Contributing

Stars

37 stars

Watchers

1 watching

Forks

Repository files navigation

CMF Watch Utils

CMF Watch Utils

Tooling and documentation for CMF Watch Pro 2 and Watch 3 Pro — firmware container toolkit, BLE tooling, a QEMU emulator preview and reverse-engineering notes.

Docs CMF Watch Pro 2 CI Pages AGPL-3.0 Stars Forks

Read the documentation · llms.txt · Arnav Kumar · arnv.dev


Warning

Unofficial interoperability project. Not affiliated with or endorsed by Nothing / CMF.

Firmware modification can permanently damage a device — read the limitations before flashing anything.

What it does

Area Result
AOTA / SDFS / RES / STY / WFDL / AJS parse and rebuild verified offline, byte-identical round-trips
BLE authentication, shell/AT, watch-face upload verified on hardware
Stock CMF firmware OTA verified on hardware and over virtual BLE
Actions SDK OTA offline validation and full virtual transfer through image acceptance
Watch Pro 2 QEMU stock, onboarding, Bad Apple and Tilt Mouse booted to the panel on Windows
Watch 3 Pro QEMU stock 1.0.1.77 boots in the browser and on desktop. See the device profile.
Watch Pro 2 virtual recovery stock OTA reset and staged install booted Bad Apple. Modeled crown + charger restored stock after app corruption

Bad Apple firmware is an example of building a custom Zephyr app for this watch. The Bad Apple case study explains how the player fits the watch's storage and memory.

Install

Install Git and uv. The workspace uses Python 3.12 or later. Use the commands for your shell in the setup guide to clone without large downloads, then run:

uv sync --locked
uv run cmf-watch-utils emu profiles

The requirements table shows which optional dependencies each task needs. Git LFS is needed only for fetching the firmware through Git. The downloads below also have direct links.

Contents

Use

Download the reference firmware using the setup guide before running the offline examples. Run commands from the repository root. info requires pairing; start with scan and follow the BLE guide.

# offline: parse and verify a firmware image
uv run fwkit info   dumps/binaries/firmware/JX402_V1.0.0.73.bin
uv run fwkit verify dumps/binaries/firmware/JX402_V1.0.0.73.bin
uv run fwkit unpack dumps/binaries/firmware/JX402_V1.0.0.73.bin work/aota

# BLE, read-only first
uv run python tools/cmf_watch.py scan
uv run python tools/cmf_watch.py info
uv run python tools/cmf_watch.py ota-state --duration 5

Emulator and Actions OTA

uv run cmf-watch-utils emu profiles
uv run cmf-watch-utils emu preflight --image local/update.bin
uv run cmf-watch-utils ota actions --image local/actions-update.bin

These commands run offline. The profiles are wp2-stock and wp2-onboarding for Watch Pro 2 stock 1.0.0.73, and wp3-stock for Watch 3 Pro stock 1.0.1.77. Booting needs the project QEMU build, its compatibility ROM, host runtime libraries and prepared local NOR/NAND fixtures with a NAND ID sidecar. Use emu prepare-fixtures to generate these locally from the stock package and pinned NAND ID table with an Arm-capable GDB. The interactive viewer also needs Tcl/Tk wish. Virtual BLE OTA needs a loopback H4 controller such as Netsim. Ordinary emulator use needs no watch, phone or BLE adapter.

The stock OTA client remains at tools/ota_client.py. Actions OTA uses a separate service and expects a standalone app/SDFS AOTA with an outer TEMP.bin and no CMF trailer. An explicit BLE address enables negotiation on hardware, which can show the update screen. Physical transfer also requires --flash. The emu ota command stays on loopback.

The verified recovery flow used QEMU's compatibility ROM and a host model to check the OTA reset, install staged app/SDFS data and restore a broken virtual app. The physical boot chain and real crown + charger recovery remain unverified. The Windows runtime was tested. Linux and macOS are build targets whose runtime integration remains unverified.

Downloads

Open the browser emulator for Watch Pro 2 or Watch 3 Pro. Both cache downloads and restore saved watch storage by default. The browser guide covers FMC catalogs, supported apps, share links and reset controls. For native builds, see the emulator build guide.

The repository stores images with Git LFS. Use Git LFS to fetch them from a checkout or download individual files below.

File Size SHA-256 (first 16) Description
JX402_V1.0.0.73.bin 56.9 MB 30903fc8ce6db4f8 Stock factory firmware, 1.0.0.73
JX402_V1.0.0.57.bin 56.1 MB cd4574f1f9fa3110 Reconstructed older firmware; physical downgrade unverified
JX402_V1.0.0.73_badapple9.bin 54.1 MB 4933e593d14bef6f Rebuilt image with the animation proof of concept
app_073.bin 2.4 MB 30e7978c39d8fb79 app.bin from the 1.0.0.73 image
app_057.bin 2.4 MB 26fbe34c10343949 app.bin from the 1.0.0.57 image

Manifests with full hashes and per-entry CRC status: firmware-1.0.0.73.json · firmware-1.0.0.57.json

Layout

tooling/src/fwkit/       format toolkit (AOTA, SDFS, RES, STY, AJS, WFDL, pictures, LZ4)
tooling/tests/           selftest.py, needs a firmware image
tooling/ghidra_scripts/  Ghidra analysis helpers
tooling/redact.py        removes device identifiers from logs before publishing
src/cmf_watch_utils/     packaged BLE, OTA and emulator CLI
src/cmf_watch_utils/emu/ model profiles, QEMU runner, viewer and recovery model
emulator/                QEMU machine, compatibility ROM, NAND reader and build recipe
tests/                   synthetic protocol and emulator checks
tools/cmf_watch.py       existing BLE CLI entry point
tools/ota_client.py      existing stock CMF OTA entry point
tools/spp_ota.py         SPP / RFCOMM experiments
tools/rfcomm.py          RFCOMM helper
tools/maputil.py         address and offset helpers
tools/legacy/            the original standalone unpack, decompress and xref scripts
tools/experiments/       one-off probes that established the pairing and OTA behaviour
site/                    Astro Starlight documentation site
dumps/                   firmware images, analysis output, logs, traces and samples

The documentation is organised per device, so new models can be added without duplicating the tooling:

site/src/content/docs/
  index.mdx               project home and device matrix
  about/                  project-wide documentation
  getting-started/        host setup and first steps
  tooling/                fwkit, BLE and Actions OTA references
  emulator/               browser and desktop setup, virtual OTA and limits
  devices/<model>/        protocol, formats, internals and guides for one device
  ai/                     agent-facing briefings
  dumps/                  manifests and downloadable images

Documentation

cd site
pnpm install --frozen-lockfile
pnpm dev

Run these commands with Node.js 22.22 or later and pnpm 12. The local preview is at http://localhost:4321/. The published site is https://cmf.arnv.dev/.

Key pages:

For AI agents: /llms.txt lists every page, and /llms-full.txt contains the full text.

Stock OTA protocol requirements

These rules describe the stock CMF protocol.

  1. INIT2 (0x9040) is written to the OTA characteristic ...ff01. Sending it on CMD_W with a valid session can reboot the watch and drop the link.
  2. The watch pulls data; the exact ranges it requests are served. Offsets are not monotonic.
  3. On 0xA041, 0x9041 with payload A5 is sent. Without that end acknowledgement the update stays staged and is never committed.

Testing

uv run --locked python -m unittest discover -s tests -v
uv run python tooling/tests/selftest.py dumps/binaries/firmware/JX402_V1.0.0.73.bin
cd site
pnpm build

Star History

Star History Chart

Contributors

See the contributing guide for local setup, emulator smoke tests, and what to include in a pull request.

Contributors

See the full contributor graph.

Attribution

  • Arnav Kumar — arnv.dev
  • The watch-face upload behaviour was informed by the AGPL-3.0 fmctools/fmc project.
  • Bad Apple is a copyrighted work; no animation frames are published in the documentation. The proof-of-concept image contains them, so the redistribution terms of that work apply to that file.

License

AGPL-3.0. See LICENSE and Legal & attribution.

About

Reverse engineered tooling and documentation for custom firmware and connection workflow for CMF Watch Pro 2

Resources

Contributing

Stars

37 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages