# CMF Watch Utils Full text of the documentation. Unofficial project, not affiliated with Nothing / CMF. # Community FMC projects, community discussions and places to share work or report problems. URL: https://cmf.arnv.dev/about/community/ FMC brings together people building tools, apps and watch faces for CMF devices. Code, design, documentation, research and device testing all contribute to the projects. | Place | What you will find | |---|---| | [FMC](https://fmc.tools) | The watch-face editor and gallery, app store and firmware downloads | | [FMC on GitHub](https://github.com/fmctools) | Project source, issues, pull requests and development discussions | | [FMC Community on Discord](https://discord.gg/KnAFruMabJ) | Community questions, project discussion and shared findings | | [r/CMFWatchMods on Reddit](https://www.reddit.com/r/CMFWatchMods/) | Watch modifications, project showcases and community discussion | ## Questions and problem reports For setup and common failures, start with [Troubleshooting](/getting-started/troubleshooting/). Discord and Reddit provide places to discuss experiments and ask the community. For a reproducible problem in CMF Watch Utils, open a [GitHub issue](https://github.com/fmctools/cmf-watch-utils/issues). Include the model, firmware version, operating system and steps that reproduce it. State whether it occurred in the browser, desktop QEMU or on a physical watch. Remove personal device identifiers, pairing keys and private notification content before sharing logs. Community advice and emulator results do not guarantee physical recovery after a failed update. ## Contributing The [contributor guide](/getting-started/contributing/) covers local setup and checks for documentation, Python tools and emulator work. Project-specific instructions live with each repository in the [FMC organization](https://github.com/fmctools). --- # Legal & attribution Licensing, third-party notices and the terms for the published artifacts. URL: https://cmf.arnv.dev/about/legal/ ## License This repository is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See [`LICENSE`](https://github.com/fmctools/cmf-watch-utils/blob/main/LICENSE). Rationale: the BLE/frame behaviour and watch-face upload flow were informed by, and in part ported from, the AGPL-3.0 licensed [`fmctools/fmc`](https://github.com/fmctools/fmc) project. Keeping the combined work under AGPL-3.0 is the simplest way to respect that license. The [FMC website](https://fmc.tools) provides the editor and community catalog; the repository links below identify the source used for attribution. ## Third-party attribution - [`fmctools/fmc`](https://github.com/fmctools/fmc) — independent watch-face editor and protocol reference (AGPL-3.0). Used for cross-checking frame headers, AES/CRC rules, WFDL layout and the upload handshake. - Nothing/CMF and the CMF Watch Pro 2 name are trademarks of their respective owners. This is an unofficial interoperability project and is not affiliated with or endorsed by Nothing. - Bad Apple is a copyrighted work. The proof-of-concept firmware image published under `dumps/binaries/` contains frames from it, which places redistribution of that image under the rights holder's terms. The case study itself describes the process only. ## Published artifacts The [data index](/dumps/) lists the artifacts available from this repository. - Stock firmware packages and selected application extracts are tracked under `dumps/binaries/` using Git LFS. - The rebuilt proof-of-concept image under `dumps/binaries/`, which contains third-party animation frames. - Manifests with sizes and hashes, and redacted notes. - [Product artwork and SKU metadata](/reference/watch-artwork/), with source URLs and image hashes. The following is intentionally excluded: - Additional vendor resource dumps beyond the reference packages and samples listed in the data index. - Captured personal data: MAC addresses, serial numbers, pairing secrets, authkeys, session keys, GPS tracks and notification contents. The repository license applies to the project code. Firmware and third-party media have their own terms. Locally obtained images are placed under `firmware/`; that path is gitignored. ## Safety and acceptable use These tools target research, interoperability, and hardware that is owned or authorised for testing. Bypassing ownership/account protections, attacking hardware that is not owned, and redistributing vendor firmware or copyrighted media fall outside the intended use. Firmware modification can permanently damage a device. No warranty is provided; see the AGPL-3.0 for the full disclaimer. ## Product artwork reference The [shared artwork inventory](/reference/watch-artwork/) contains vendor-owned Nothing X product images and a source/hash manifest. Those images retain their respective ownership and are not relicensed under the repository license. --- # Methodology How the formats and protocol were recovered, and how to reproduce or extend the work. URL: https://cmf.arnv.dev/about/methodology/ ## Approach 1. **Reversible experiments.** The same bytes are parsed and rebuilt before any change is made. 2. **Separate hypotheses from facts.** A decompiler comment is a hypothesis until a round-trip, a live reply, or a boot proves it. 3. **Application capture.** The official app is the reference client for frame layout, keys, retries and ordering. 4. **Rollback.** The image being replaced is saved, and the diff kept as small as possible. 5. **Personal data.** MAC addresses, serial numbers, pairing secrets and authkeys are stripped from this repository. ## Static analysis The shared [firmware analysis guide](/contributing/firmware-analysis/) covers Ghidra import, script exports and address conventions. Device references hold build-specific addresses and structures. Cross-reference command constants, strings and callers, then validate the interpretation against a byte-level check or observed behavior. Decompilation alone does not prove a hardware path. ## Dynamic analysis - BLE traffic was captured and replayed against the watch with a Python/Bleak client. - Shell/AT commands were used for identity, battery and sensor checks. - Watch Pro 2 stock OTA was verified in separate negotiation, transfer and post-reboot checks. - A successful full flash was accepted only after the watch rebooted and the new animation played on the UI. ## Emulated hardware Record the stock version, model, fixture and interaction. Compare the guest’s visible behaviour with register, serial or storage evidence. A synthesized sensor input can verify driver and app behaviour in QEMU. Report physical measurements and validation separately. ## Format recovery For each container: 1. The magic, header fields and table are located. 2. The smallest shipped object is decoded. 3. It is re-encoded and compared **byte-for-byte** with the original. 4. Only then is a field edited or a payload replaced. 5. The outer container CRC, entry CRCs and partition checksums are verified. The regression suite (`tooling/tests/selftest.py`) encodes this discipline. It requires a legitimate firmware image supplied locally. ## Cross-checking The public [`fmctools/fmc`](https://github.com/fmctools/fmc) project (AGPL-3.0) was used as an independent reference for the frame header, AES/CRC rules, `.wfdl` layout and the watch-face upload handshake. Where older assumptions differed, live-verified FMC behaviour took precedence. The watch-face uploader is a behavioural port, which is why this repository is AGPL-3.0. ## Reproducing a result - Offline: the selftest is run against a locally held firmware image, followed by `fwkit info/verify`. - BLE read-only: `ota-state`, `info` or explicitly read-only shell queries. - BLE OTA: check the package offline and exercise the protocol over loopback when possible. Retain the previous image. - Firmware OTA: the [AOTA OTA flow](/devices/cmf-watch-pro-2/protocol/ota/) is followed exactly; INIT2 is not reordered and the end acknowledgement is not skipped. --- # Device support and contributions Where to document a device and how to establish the scope of support. URL: https://cmf.arnv.dev/about/roadmap/ ## Device coverage | Model | Documented scope | |---|---| | [Watch Pro 2](/devices/cmf-watch-pro-2/) | Firmware and formats, stock BLE and OTA, desktop and browser emulation | | [Watch 3 Pro](/devices/cmf-watch-pro-3/) | Firmware and formats, desktop and browser emulation | | Other models | No device profile or verified workflow | ## Documentation structure | Area | Content | |---|---| | [Getting started](/getting-started/quickstart/) | First tasks and required tools | | [Tooling](/tooling/fwkit/) | Shared command line tools and file inputs | | [Emulator](/emulator/) | Browser and desktop workflows, virtual controls, and recovery limits | | Device pages | Per-build identifiers, formats, protocol details and results | | [Dumps](/dumps/) | Reference packages, checksums and supporting data | | [Methodology](/about/methodology/) | How to verify and document findings | ## Add or extend a device Identify the model, board and firmware version first. A device can have an offline format or emulator profile before it has a verified BLE route. State which part of a workflow was exercised and label the evidence as offline, emulated or physical. See the [contribution guide](https://github.com/fmctools/cmf-watch-utils/blob/main/CONTRIBUTING.md) for repository tests and how to submit changes. For watch-face work, record the model, package type, codec and the view used for verification. An import, a render and a physical upload are separate checks. Use the [Watch Pro 2 WFDL reference](/devices/cmf-watch-pro-2/formats/watchface/) or the [Watch 3 Pro face notes](/devices/cmf-watch-pro-3/formats/#watch-face-resources) for the relevant format. --- # Agent context A compact, factual briefing for AI coding agents working in this repository. URL: https://cmf.arnv.dev/ai/context/ For documentation changes, follow [Documentation guidelines](/ai/documentation/). ## Mission The scope of the project is open tooling and documentation for the **CMF Watch Pro 2** (`JX402`, Actions ATS3089C, firmware `1.0.0.73`). The project parses and rebuilds AOTA/SDFS/RES/STY/WFDL/AJS containers and talks to the watch over BLE (auth, shell/AT, watch faces, firmware OTA). It also runs Watch Pro 2 and Watch 3 Pro firmware in desktop and browser QEMU. ## Hard rules 1. **No device writes without explicit approval from the repository owner.** Read-only BLE commands are acceptable. Use known read-only AT queries. Physical OTA negotiation requires approval even when it sends no image bytes. 2. `Interceptor.attach` on Dart AOT (`libapp.so`) crashes the target and is therefore excluded. 3. Blanket termination of Python processes is excluded; termination applies only to the specific process that was started. 4. Follow AGENTS.md for binary handling, including its exception for published reference dumps under Git LFS. Never commit personal data: MAC, serial, secret, authkeys, session keys or logs containing device identifiers. 5. Preserve the stock CMF OTA sequence. INIT2 goes to the OTA characteristic and END requires acknowledgement. 6. Comments are added to code only on request. The surrounding style is matched. ## Repository map ```text src/cmf_watch_utils/ packaged CLI, stock BLE and Actions OTA src/cmf_watch_utils/emu/ model profiles, runner, H4 transport and recovery emulator/ QEMU machine, compatibility ROM, NAND reader and build recipe tests/ synthetic emulator and OTA checks tooling/src/fwkit/ image/AOTA, SDFS, RES, STY, AJS, WFDL, pictures, LZ4 tooling/tests/ selftest.py (needs a local firmware image) tooling/ghidra_scripts/ Ghidra analysis helpers tools/cmf_watch.py BLE CLI: scan/pair/info/AT/dials/OTA tools/ota_client.py full AOTA OTA client tools/spp_ota.py SPP/RFCOMM experiments tools/rfcomm.py RFCOMM helper tools/maputil.py address/offset helpers site/ Astro Starlight documentation dumps/ manifests, reference binaries via Git LFS and redacted notes ``` ## Environment - Python **3.12+**, uv workspace at the repo root. - `uv sync`; the CLI runs as `uv run fwkit ...` and tools as `uv run python tools/cmf_watch.py ...`. - Docs: `cd site; pnpm install; pnpm dev` / `pnpm build`. - Physical BLE and QEMU firmware integration were tested on Windows. Linux and macOS are emulator build targets. ## Established facts - AOTA: 0x400-byte header, 32-byte entries, LZMA chunks, nested partitions. - SDFS: `sdfs.bin`, 0x20-byte header, 32-byte entries, 0x40 alignment, `sum32` checksums. - `res_e.bin`: stock image **58,777,088 B**, named payloads 58,776,014 B; physical reservation **64 MiB**. Metadata/alignment is not free payload, and capacity outside the stock image is unverified for reuse. See [Storage](/devices/cmf-watch-pro-2/internals/storage/) and [Storage Explorer](/storage-explorer/watch-pro-2/). - App: `app.bin` at base `0x10000000`, Thumb-2, ACTH header. - BLE: MTU 23; frames are AES-CBC, fixed IV, CRC32-LE tail. - Auth: `authkey = sha256(r1||r2||secret)[:16]`, `session = sha256(nonce||authkey)[:16]`. - OTA: `0x9052` → `A052 01`; `0x9040` **on `...ff01`** → `A040`; watch pulls `A042`; answer `0x9042`; at `A041` send `0x9041 A5`. - Sending INIT2 on `CMD_W` first with a valid session can reboot the watch. - Watch-face update: delete + append is the reliable path. - `.ajs`: 240×240 JPEG frames, fps at `+0x07` (0 => 25); `9.ajs` is sport type 22, 8 s. - No proven universal recovery; bootloader is not in AOTA. ## Emulator and Actions OTA - Use the [browser emulator](/emulator/) to check firmware boot, watch faces, controls, sensors and sound. Use desktop QEMU for Bluetooth OTA and modeled recovery. The bundled Bad Apple demo uses playback timing, so use a custom firmware boot for browser tests that depend on guest timing. - Start with `uv run cmf-watch-utils emu profiles` and `emu preflight --image FILE`. The profiles are `wp2-stock`, `wp2-onboarding` and `wp3-stock`. Use the model-specific reference package and fixture directory. For a boot, provide the project-built ATS3089C QEMU, the matching compatibility ROM and local virtual flash. Use `emu prepare-fixtures` to create flash from the reference AOTA, pinned NAND ID file and Arm GDB, or import existing fixtures. - `emu ota` uses loopback H4 with an isolated controller. Use synthetic pairing data for stock. `emu pair-fixture` exports a paired NOR from a fresh stock guest. Negotiation is the default, and `--transfer` sends data to the guest. - `ota actions --image FILE` is offline without an address. An address enables physical negotiation and can enter the watch's update screen. Both an explicit address and `--flash` are required to transfer to hardware. The Actions client expects standalone app/SDFS AOTA with outer TEMP and no CMF trailer. - Report package preflight, guest boot, peer image validation and post-reset boot separately. Stock virtual OTA verified reset, TEMP read from captured virtual NAND, modeled install and boot. Actions verified guest validation. Crown + charger verified host-modeled stock rescue from a broken virtual app. These tests leave physical boot ROM, bootloader, recovery BLE and electrical failure modes unverified. - Boot testing needs no phone, root or host BLE adapter. The separate Nothing X lab used a local binding fixture. Keep virtual flash, device state and lab credentials out of commits and published logs. See [Emulator CLI](/emulator/), [Actions SDK OTA](/tooling/actions-ota/) and [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/). ## Watch 3 Pro Use [Watch 3 Pro firmware and formats](/devices/cmf-watch-pro-3/formats/) and [hardware and emulation](/devices/cmf-watch-pro-3/hardware/) for stock `1.0.1.77`. This profile uses board `jx402_08` and its own fixture directory. Browser results include stock passcode setup and raw optical measurement. Keep WP2 OTA and recovery results scoped to WP2. ## Known unknowns - ACTH checksum fields `+0x1C`/`+0x20` and `+0x0C = 0x62`. - `.sty` type-2 `+0x18` font/style encoding. - `album.cfg`, `.wfdl +0x17`, several SPP opcodes. - `0xA055` capacity byte vs. actual dial slots; side-loaded dial ids are not listed. - UART recovery path is unverified. ## Verification ```bash uv run fwkit verify dumps/binaries/firmware/JX402_V1.0.0.73.bin uv run fwkit info dumps/binaries/firmware/JX402_V1.0.0.73.bin uv run python tooling/tests/selftest.py dumps/binaries/firmware/JX402_V1.0.0.73.bin uv run --locked python -m unittest discover -s tests -v uv run --locked cmf-watch-utils emu profiles cd site; pnpm build ``` Format work proves a byte-identical round-trip before any edit. Protocol work starts offline or over loopback. Stock `--dry-run` and `--stop-after-a040` contact the physical watch and require approval. ## PII policy The placeholder MAC is `AA:BB:CC:DD:EE:FF`. Real MAC/serial/secret/authkey/GPS/notification data is absent from logs, screenshots, issues and commits. `tools/.watch_state.json` is gitignored and never published. ## Documentation evidence and current emulator scope Use current code and recorded results when changing support claims. Explain inputs before commands, define model-specific terms, and keep historical run sizes in the evidence archive. Troubleshooting belongs under Getting started; do not describe emulator recovery as a physical recovery procedure. Current fixture preparation generates stock texture indexes for both models. Watch 3 Pro has a verified small app/SDFS virtual OTA transfer, guest reset and host-modeled install. Automatic extraction from arbitrary WP3 NAND snapshots, physical recovery and full factory-test parity remain unverified. See the site's OTA and recovery page for the precise boundary. ## Documentation structure Setup and troubleshooting are shared under Getting started. Emulator guides cover both model profiles. Device sections separate task guides, format and hardware references, and verification status. Shared Ghidra instructions live in [Firmware analysis](/contributing/firmware-analysis/). Preserve existing page URLs and section anchors when consolidating material. --- # Documentation guidelines for agents Structure, evidence, writing and verification rules for changes to project documentation. URL: https://cmf.arnv.dev/ai/documentation/ These guidelines apply to the site, repository READMEs and help text in the emulator. Read `AGENTS.md` and the relevant code before editing. Keep publication separate from local review; a successful build is not approval to publish. ## Start with the reader's task Identify what the reader wants to do, what they already have and what they should see when finished. A first-time user may have only a browser or a downloaded file; they may not know what a repository, package or image means. Explain each term where it affects a choice. Keep browser use independent of developer setup. Stock browser previews include their starting files. Do not send users through cloning, firmware extraction or a toolchain installation unless their chosen task needs it. ## Put each topic in one place | Content | Location | |---|---| | Installation, first steps and common failures | Getting started | | Browser use, desktop boot and virtual updates | Emulator | | Model-specific guides, formats, hardware and verified results | The device section | | Command and option details | Tool reference | | Development setup and shared analysis methods | Contributing | | Licenses, attribution and reference downloads | Project information | A guide explains how to complete a task. A reference defines fields, commands or interfaces. A status page states what was verified. Link between them instead of copying their full contents. Shared workflows belong outside device sections; model-specific differences remain explicit. Do not add empty pages merely to make two model sections equally large. Preserve existing URLs and linked heading IDs. When consolidating a section, retain a useful entry point or anchor at the relevant replacement content. Check links from the emulator and repository READMEs as well as the sidebar. ## Establish technical claims Use current code, reproducible checks and recorded research. Record the model, firmware version, host and test boundary where those affect the result. Resolve contradictions against evidence before rewriting them as facts. - Distinguish offline package validation, application boot, update transfer, installation and post-restart behavior. - Distinguish desktop, browser and physical-watch results. Shared source alone does not establish identical behavior. - Distinguish simulated readings from stock calculations using raw samples. - Describe modeled recovery as modeled recovery. It cannot guarantee that a physical watch can be recovered or that firmware cannot brick it. - Label unknowns precisely. Do not turn a hypothesis into a supported feature, or retain an old failure as a current limitation after it has been resolved. Keep experimental sizes, transient errors and chronological milestones out of task guides unless they explain a current constraint. Preserve useful historical evidence in a clearly identified research or run record. ## Write complete procedures A procedure states prerequisites, inputs, steps, expected results and what to do if the result differs. Explain which folder to run commands from and which paths are placeholders. Use paths relative to the checkout where possible; quote paths containing spaces. Provide separate shell examples when syntax actually differs across Windows, Linux and macOS. Check option names, defaults and input formats against the CLI or UI. A `.bin` extension alone does not identify a firmware package, raw application or face. Explain the difference before asking the user to select a file. Identify commands that contact or modify a physical device before the command block. Never describe live OTA negotiation as an offline check. For recovery instructions, identify the required working connection and updater. Do not invent a button sequence, assume any custom firmware accepts stock packages, or imply that reinstalling firmware erases a faulty watch face. ## Language and examples Use descriptive headings such as “Load custom firmware” or “Pair a Watch Pro 2”. Use short, direct sentences with enough detail to complete the task. Define necessary technical terms rather than removing technical depth. | Do | Do not | |---|---| | Explain what a file contains and which input accepts it | Tell readers to “provide the necessary artifacts” | | State what passed and what remains untested | Claim “fully supported” from one successful boot | | Link FMC to [fmc.tools](https://fmc.tools) when introducing the service | Replace a source-attribution link with a product homepage | | Use `fmctools` for current GitHub repository links | Rely on the former organization redirect indefinitely | | Keep known-good defaults and describe optional overrides | Make users reconstruct bundled files to try the preview | | Describe current behavior and concrete outcomes | Narrate internal chats, abandoned plans or praise the workflow | Use the exact UI label when naming a control. Avoid unexplained acronyms, coaching language, promotional claims and vague phrases such as “just configure it”. First-person project language is suitable for introductions, while technical procedures should focus on the user's action and the system's response. ## Standalone research references A published research reference describes the device, format or protocol and its supporting evidence. It must make sense without a development session or a specific client implementation. Local test timelines, failed workstation connections, implementation handoffs and pending integration plans belong in development notes. Keep genuine unknowns, firmware/version boundaries and evidence quality explicit; state them as properties of the research rather than a report of the author's session. ## Privacy and publication Remove personal Bluetooth addresses, serial numbers, pairing keys, account data, notification content, GPS tracks and local usernames from public examples and logs. Use `AA:BB:CC:DD:EE:FF` when an address placeholder is needed. Follow repository rules for firmware and third-party assets; do not broaden or narrow those rules based on assumptions. Keep unresolved publication questions in the review notes rather than scattering internal approval commentary through docs. ## Review and verify 1. Read the page as a newcomer arriving from a search result, without the surrounding conversation. Check whether its purpose and prerequisites stand alone. 2. Walk through browser-only use, downloaded files, first pairing, a failed update and returning to stock wherever relevant. Record any missing choice or unexplained result. 3. Check commands against current help and implementation. Do not run physical writes merely to validate documentation without the required authorization. 4. Build the site with `pnpm build` from `site/`. Check internal routes and fragments, old incoming links, sidebar placement and search visibility. 5. For emulator help changes, check both generated model pages. Preview with local documentation links so unpublished routes can be reviewed. 6. Report what was actually checked. Separate prose review, code inspection, command execution and device tests. Keep unverified results explicit. --- # Agent task examples Copy-paste prompts that keep an AI agent inside the project's safety and verification rules. URL: https://cmf.arnv.dev/ai/prompts/ For documentation changes, follow [Documentation guidelines](/ai/documentation/). These examples supplement the repository’s `AGENTS.md`. Include the device model and firmware version in each task. ## System preamble Scope, device-write approval and data handling: > You are working in `cmf-watch-utils`, an unofficial CMF Watch research repo. Read > `AGENTS.md` and `site/src/content/docs/ai/context.md` first. Never flash, upload, delete or > change device settings without explicit approval. Follow AGENTS.md for binary assets > and its published-dumps exception. Never commit personal identifiers or keys. Prove format > work with byte-identical round-trips. Prefer read-only commands. Explain risky commands > before running them. ## parse or edit a container Container inspection and editing, with a round-trip proof ahead of any change: > Inspect `` with the appropriate `fwkit` command. Identify magic, header fields and > record sizes. Extract the smallest entry, decode it, re-encode it and compare byte-for-byte. > Only then make the requested edit. Report the exact command, byte sizes and any fields you > could not explain. Do not modify firmware under `firmware/` in place. ## add a CLI command Addition of a CLI subcommand following the existing parser/cmd_* pattern: > Add `` to `tooling/src/fwkit/cli.py` following the existing parser/cmd_* pattern. > Keep output stable and machine-readable where the command already is. Add a round-trip test > to `tooling/tests/selftest.py` that does not require redistributing vendor files. Run the > selftest against the local firmware image and report results. ## BLE debugging BLE investigation, read-only until a write is approved: > Use only read-only BLE commands until I approve a write. Start with `info` and > `ota-state --duration 5`. Ask before pairing or negotiating physical OTA. > Stock `--dry-run` and `--stop-after-a040` both contact the watch. Test INIT2 on > the OTA characteristic and END acknowledgement in QEMU first. ## emulator and OTA verification > Run `uv run cmf-watch-utils emu profiles` and preflight the package for the selected > profile. Use prepared virtual fixtures and an isolated H4 controller for OTA. > Keep the real watch disconnected from the test. Run Actions validation without > an address, or use `emu ota --protocol actions` for loopback. Report separately > whether the package passed, the guest validated the transfer, the guest rebooted, > and the installed app rendered. Label crown + charger results as host-modeled rescue. ## docs Documentation edits under the Astro content tree: > Edit the Astro content under `site/src/content/docs/`. Keep frontmatter `title` and > `description`. Use root-relative links with a trailing slash for internal pages. Do not include real device identifiers. Run > `pnpm build` in `site/` and fix broken links. > For browser emulator changes, build the standalone page with > `emulator/web/publish.py` and check the browser route for the affected model. ## Review checklist - [ ] No secrets, MAC, serial, authkeys or personal logs. - [ ] No firmware, vendor resources or copyrighted media added. - [ ] Format change has a round-trip proof. - [ ] I/O change has an offline or isolated virtual test path. Live negotiation is identified as such. - [ ] Stock CMF OTA order unchanged: `0x9052`, `0x9040` on OTA, `0x9042` pulls, `0x9041 A5` end. - [ ] `pnpm build` and the relevant Python checks pass. --- # Firmware analysis with Ghidra Import a reference application, run analysis scripts and record reproducible findings. URL: https://cmf.arnv.dev/contributing/firmware-analysis/ This workflow applies to the reference applications for Watch Pro 2 1.0.0.73 and Watch 3 Pro 1.0.1.77. Install Ghidra and its required JDK, then extract `app.bin` from the matching update using [fwkit](/tooling/fwkit/). Run commands from the repository root. Ghidra is not needed to run the emulator. ## Import `app.bin` is a raw Thumb-2 image mapped at **`0x10000000`**. The import uses the `ARM:LE:32:Cortex` processor with an image base of `0x10000000`. The ACTH header starts at file offset 0, so file offset `X` maps to address `0x10000000 + X`. ## Bundled scripts `tooling/ghidra_scripts/` contains helpers for repeatable exports: | Script | Purpose | |---|---| | `DumpApp.java` | Summary, entry points and header fields | | `CountFns.java` | Function count and address ranges | | `FuncAt.java` / `ListFnsInRange.java` | Function boundaries | | `Decompile.java` / `DecompileAt.java` / `DecompRange.java` | Export decompilation | | `Callers.java` / `CallersOf.java` / `RefsTo.java` / `Xrefs.java` | Call and data xrefs | | `FindImm.java` / `FindOps.java` / `SearchDecomp.java` | Immediate/opcode/text search | | `FindStrings.java` / `FindStrXrefs.java` | String tables and references | | `FindOta.java` / `OtaFns.java` / `OtaGraph.java` / `OtaHandlers.java` / `OtaReq.java` | OTA state-machine mapping | | `NameMap.java` / `ExportAnnotated.java` | Export names and annotated listings | ## Headless example These examples use Bash line continuation. In PowerShell, place each command on one line and invoke `analyzeHeadless.bat` from Ghidra’s `support` directory. Supply an extracted `app.bin` from the reference firmware. ```bash analyzeHeadless analysis-projects wp2 \ -import app.bin \ -processor ARM:LE:32:Cortex \ -loader BinaryLoader \ -loader-baseAddr 0x10000000 \ -scriptPath tooling/ghidra_scripts \ -postScript DumpApp.java \ -analysisTimeoutPerFile 900 ``` Create the `analysis-projects` directory before import. The project name `wp2` is arbitrary; use a separate project for each firmware build. This second example decompiles a function in Watch Pro 2 1.0.0.73: ```bash analyzeHeadless analysis-projects wp2 -process app.bin -noanalysis \ -scriptPath tooling/ghidra_scripts \ -postScript DecompileAt.java 0x101F4D70 ``` Exact argument order depends on the script; the Java file header lists its parameters. ## Conventions - Addresses in this documentation are virtual addresses (`0x10...`), not file offsets. - In Watch Pro 2 1.0.0.73, `0x101F4D70` is the BLE/AT group dispatcher; `0x10054CF4` is `system_app_launch`. - Watch 3 Pro application fields and reset vector are in its [firmware reference](/devices/cmf-watch-pro-3/formats/#application-image). - The Watch Pro 2 ACTH fields are referenced in [app.bin internals](/devices/cmf-watch-pro-2/internals/appbin/). - Decompiler output is a hypothesis, confirmed by a live reply or a byte-level round-trip. ## Reproducibility Ghidra versions differ in analysis quality, so the version, the script arguments and the SHA-256 of `app.bin` accompany a published finding. The firmware and the Ghidra project are kept outside source changes. Published reference binaries are listed separately in the [data index](/dumps/). --- # CMF Watch Pro 2 Device profile, verified capabilities and page map for the CMF Watch Pro 2 (JX402, Actions ATS3089C). URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/ import InteractiveTools from '../../../../components/InteractiveTools.astro'; The CMF Watch Pro 2 is the first device covered by this project. It runs the Actions ATS3089C platform on board `JX402`, uses reference firmware `1.0.0.73` in this documentation and exposes a BLE command service, a watch-face upload channel and an AOTA firmware update path. ## Profile | Property | Value | |---|---| | Model | CMF Watch Pro 2 | | Board | `jx402_01_3089c` | | SoC | Actions ATS3089C (Cortex-M based, Thumb-2) | | Firmware | `1.0.0.73` (AOTA version string `1.00_2509131556`) | | Application | `app.bin`, base address `0x10000000`, ACTH header | | Display | 466×466 panel. The 240×240 size applies to the AJS animations. | | Storage | Examined unit: 128 MiB NAND main storage and 4 MiB NOR; 10 MiB writable-file reservation | | BLE | MTU 23 observed; payload frames are AES-CBC encrypted with a CRC32-LE tail | ## Verified capabilities | Area | Result | |---|---| | Shell/AT channel | Status, identity, sensor and factory commands answered | | BLE authentication | Pairing, nonce exchange and session key derivation working | | AOTA parse and rebuild | Byte-identical rebuild of the stock image | | SDFS, RES, STY, WFDL, AJS | Parse, edit and rebuild with byte-identical round-trips | | Watch-face upload | Install and delete over BLE, verified on hardware | | AJS animation replacement | Custom animation played on the watch UI | | Full AOTA firmware OTA | Image transferred, committed and booted on the watch | The detailed result table, with the evidence behind each entry, is on the [status page](/devices/cmf-watch-pro-2/status/). ## Page map **Emulator** - [Emulator CLI](/emulator/) for profiles, fixture setup, boot tests and virtual OTA - [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/) for what the recovery model verifies **Protocol** - [BLE protocol](/devices/cmf-watch-pro-2/protocol/ble/) — frames, keys, characteristic layout, notification streams - [AOTA OTA flow](/devices/cmf-watch-pro-2/protocol/ota/) — the verified update sequence - [Actions SDK OTA](/tooling/actions-ota/) for firmware exposing the Actions service - [Shell / AT channel](/devices/cmf-watch-pro-2/protocol/shell/) — command family and pairing secret retrieval **Formats** - [AOTA container](/devices/cmf-watch-pro-2/formats/aota/) - [SDFS filesystem](/devices/cmf-watch-pro-2/formats/sdfs/) - [Watch faces & WFDL](/devices/cmf-watch-pro-2/formats/watchface/) - [UI style bundles](/devices/cmf-watch-pro-2/formats/style/) - [Picture codecs](/devices/cmf-watch-pro-2/formats/pictures/) - [AJS animations](/devices/cmf-watch-pro-2/formats/ajs/) **Internals** - [Hardware](/devices/cmf-watch-pro-2/internals/hardware/) - [Storage](/devices/cmf-watch-pro-2/internals/storage/) — NAND/NOR layout, writable capacity and verification limits - [Storage Explorer](/storage-explorer/watch-pro-2/) — interactive hierarchy and downloadable references - [app.bin internals](/devices/cmf-watch-pro-2/internals/appbin/) - [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/) **Guides** - [Firmware OTA flash](/devices/cmf-watch-pro-2/guides/ota-flash/) - [Dial editing & upload](/devices/cmf-watch-pro-2/guides/dial-editing/) - [Bad Apple case study](/devices/cmf-watch-pro-2/guides/bad-apple/) - [Ghidra workflow](/devices/cmf-watch-pro-2/guides/ghidra/) ## Boundaries The constants, offsets and BLE behaviour documented here belong to this firmware build. Other models and other builds are covered by separate sections; see the [roadmap](/about/roadmap/). Flashing risks and recovery limits are on the [limitations page](/devices/cmf-watch-pro-2/limitations/). --- # AJS animations The JPEG-frame animation format used for sport warm-ups, including frame records, tile tables and stock player behavior. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/ajs/ `.ajs` files live in `/NAND:E` inside `res_e.bin` and are played by the sport warm-up view. They are not menu entries or watch faces. ## Layout A `.ajs` is **not** a plain concatenation of JPEGs: each frame is preceded by a tile descriptor and the chain is driven by a length field, not marker scanning. There are 8 prelude bytes, then repeated records: ``` 0x00 u32 0 0x04 bytes 00 00 00 (0.73 files: 0x19 = 25 fps; 0 => 25) 0x07 u8 fps <-- not a version field record at p (first record p = 0x08): p+0x00 u16 size bytes after this field p+0x02 "JPEG" Allwinner tile descriptor magic p+0x06 u16 width (240) p+0x08 u16 height (240) p+0x0A u16 tile_width (240) p+0x0C u16 tile_height (240) p+0x0E u16 tile_count N (1 in every shipped file) p+0x10 N * (u16 offset, u16 length) offsets from the "JPEG" magic p+... tile JPEG streams (each FF D8 … FF D9) next record p' = p + 2 + size ``` For one tile the table is `(18, jpeg_len)`, the JPEG starts at `p+0x14` (file `0x1C` for the first frame), and `size = 14 + 4*N + sum(tile lengths)` (= `18 + jpeg_len` for `N=1`). File `+0x1A` is the first tile's JPEG length. There is no trailing record: the last frame ends at EOF. Tile offsets are relative to the descriptor magic, so a multi-tile frame is a normal table; the player computes `cols = ceil(width/tile_width)`, `rows = ceil(height/tile_height)` and blits every tile at `(col*tile_width, row*tile_height)`, clipped to the canvas. ## Tools First extract `res_e.bin` from the reference firmware and unpack its [SDFS filesystem](/devices/cmf-watch-pro-2/formats/sdfs/). In the example below, `work/res_e/9.ajs` is the stock warm-up animation for sport type 22. The output directories hold extracted frames and your rebuilt animation. ```bash uv run fwkit ajs-info work/res_e/9.ajs --frames uv run fwkit ajs-extract work/res_e/9.ajs work/ajs9 uv run fwkit ajs-repack work/ajs9 -o work/custom.ajs --fps 25 uv run fwkit ajs-set-frame work/custom.ajs 0 new_frame.jpg -o work/custom2.ajs ``` `ajs-extract` writes `NNNN.jpg` (or `NNNN_TT.jpg` for multi-tile frames). A matching repack is byte-identical for the shipped files. ## Warm-up mapping All 19 files are **sport warm-up animations**, not menu entries. The app table at `0x101ED708` (file `0x1ED708`) has 19 16-byte records: `[sport_type, seconds, category, ajs_index]`. | `.ajs` | sport type | seconds | category | |---|---|---|---| | 1 | 14 | 20 | 9 | | 2 | 15 | 20 | 9 | | 3 | 16 | 30 | 9 | | 4 | 17 | 30 | 9 | | 5 | 18 | 30 | 9 | | 6 | 19 | 30 | 9 | | 7 | 20 | 20 | 9 | | 8 | 21 | 20 | 9 | | 9 | 22 | 8 | 11 | | 10 | 23 | 30 | 9 | | 11 | 24 | 20 | 9 | | 12 | 25 | 30 | 9 | | 13 | 26 | 8 | 11 | | 14 | 27 | 8 | 11 | | 15 | 28 | 6 | 11 | | 16 | 29 | 6 | 11 | | 17 | 30 | 6 | 11 | | 18 | 31 | 20 | 11 | | 19 | 32 | 20 | 9 | Replacing `N.ajs` only changes the warm-up preview/animation for that sport; it does not add a dial or menu item. The warm-up timer in the table and the duration encoded in the animation are independent. ## Stock player Player (`simple_video_8` = open/parse, `simple_video_7` = timer tick, `simple_video_6` = rewind): 1. 0x16 bytes are read from offset 0, `"JPEG"` is required at `+0x0A`, width/height are parsed, and the fps byte is taken from prelude `+0x07`; 2. the seek goes to `0x0A` (descriptor start) and `size + 2` bytes are read; 3. every tile is decoded at `buffer + offset` with `length` bytes via the Allwinner JPEG decoder (`FUN_100ffcc4` → `FUN_100ffa70`); 4. the next `size` comes from the two bytes at `buffer[size]`. At EOF the short read yields 0, and `simple_video_6` seeks back to `0x08` to loop. `simple_video_9` creates `lv_timer_2(cb, 1000 / fps, ...)`; fps 0 is coerced to 25. Observed frame counts: 1.ajs = 500, 8.ajs = 500, 9.ajs = 1124, 16.ajs = 1397. Frames are ~1.5–4.9 KB each; all 19 shipped files use 240×240 with a single 240×240 tile. Payloads total 58,776,014 bytes inside the 58,777,088-byte `res_e.bin` image. The 1,074-byte difference includes filesystem metadata and alignment, not free payload space. Unlike `bt_watch.res` pictures, which have a 22-byte header with `"JPEG"` at `+0x04` and the same 14-byte tile descriptor after it, `.ajs` stores the descriptor after a 2-byte `size` field. ## Capacity The stock animation image is densely packed. When preserving its original length, a replacement must fit the space released by the original file, including the rebuilt filesystem table and alignment. The 64 MiB physical reservation is larger than the stock image, but that extra capacity is not verified as safely reusable. See [Storage](/devices/cmf-watch-pro-2/internals/storage/). Measure the encoded replacement and verify the rebuilt package; a clip's duration alone does not determine its size. The [SDFS reference](/devices/cmf-watch-pro-2/formats/sdfs/) documents the reference partition capacity. Replacing an animation changes an existing sport warm-up. Its display duration is controlled separately by the stock app's warm-up table. For a standalone video player, see the [source-built Bad Apple firmware](/devices/cmf-watch-pro-2/guides/bad-apple/). ## Pitfalls - Keep the 240×240 frame size. The player reads the frame rate from `+0x07` (0 means 25). - Trailing bytes are not added after the last record; the last frame ends at EOF. - Repacking goes through the toolkit rather than concatenating JPEGs; the record prelude and tile table must match what the player expects. - See [Legal and attribution](/about/legal/) before redistributing a modified image. --- # AOTA container Outer AOTA image, XML, LZMA chunks, TEMP, SDFS and rebuild recipes. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/aota/ Everything here was verified byte-for-byte against `JX402_V1.0.0.73.bin` (56,903,752 B) with `fwkit`. ## 1. Outer image ``` 0x000 header (0x400) 0x200 partition table (32-byte entries) 0x400 OTA XML ... partitions (0x200-aligned) ... AGPS blob (header[0x14], 0x200-aligned) ``` Header: | off | meaning | |---|---| | `0x00` | four-byte magic `AOTA` | | `0x04` | `crc32(file[0x08:0x400])` | | `0x08` | 16-bit header version (`0x0100` in the reference image) | | `0x0A` | 16-bit header size (`0x0400`) | | `0x0C` | partition count | | `0x14` | AGPS offset | | `0x18` | unknown (preserved as-is) | | `0x40` | version string (16 B) | | `0x60` | board name (16 B) | Table entry (32 B): `name[16] | offset(u32) | size(u32) | 0(u32) | crc32(u32)`. `crc32` is computed over the **stored** bytes of that partition. Known partitions: `TEMP.bin`, `res.bin`, `fonts.bin`, `res_e.bin`, `sdfs_k.bin`. ## 2. OTA XML `` = stored size, `` = decompressed size, `` = `crc32(decompressed)`. **Exception — TEMP.bin**: `file_size == orig_size == stored size` and `checksum = crc32(stored)`. TEMP is not a normal compressed partition; it is a nested AOTA container stored with the chunk header but with compression effectively bypassed (see below). ## 3. Chunked storage Non-TEMP partitions are stored as a sequence of chunks: ``` "LZMA" | u32 hdr_len=16 | u32 comp_size | u32 uncomp_size | XZ stream ``` - resource partitions: chunk size **0x8000** - `TEMP.bin`: chunk size **0x200000** - `lzma.compress(piece, format=FORMAT_XZ, preset=6)` reproduces the original sizes exactly. ## 4. Nested AOTA inside TEMP.bin `TEMP.bin` decompresses to a complete AOTA image (same header/table/XML layout) containing: | entry | offset | size | storage | |---|---|---|---| | `ota.xml` | 0x400 | 0x3B8 | raw | | `app.bin` | 0x800 | 0x25A080 | **raw** (`file_size == orig_size`) | | `sdfs.bin` | 0x25AA00 | 0x5FC0 | raw | `app.bin` is not LZMA-compressed when rebuilding the nested image — the updater accepts it raw and the original is raw. ## 5. SDFS filesystem Used inside `res.bin`, `sdfs_k.bin`, and the small tail blob of `app.bin`. ``` 0x00 "sdfs.bin" 0x08 u32 0 0x0C u32 count 0x10 u32 total_size 0x14 u32 0 0x18 u32 sum32(table) // entries region 0x1C u32 sum32(data) // file data region 0x20 entries[count] (32 B each) ``` Entry: `name[12] | offset(u32) | size(u32) | 0 | 0 | hash(u32)`. `hash = sum32(file data)` where `sum32` is the sum of little-endian u32 words mod 2^32 (trailing bytes that do not form a complete word are ignored). Data starts at `align(0x20 + count*32, 0x40)`; files are `0x40`-aligned. ## 6. RES resource files Header (0x14 B): | off | meaning | |---|---| | `0x00` | magic `RES\x19` | | `0x04` | flags/subtype; **low 16 == entry_count** | | `0x08` | 0x200 | | `0x0C` | 0 (strings) / 0x20000 (pictures) | | `0x10` | pool offset — **always `0x10 + count*16`** | Entries at `0x14`, 16 B each: `u16 len | u8 type | name[9] | u32 end_offset`. For string entries, the payload is `blob[end-len : end]` and includes the trailing NUL. Picture entries use aligned boundaries instead; see the [picture entry layout](/devices/cmf-watch-pro-2/formats/pictures/). Names are NUL-terminated within the 9-byte field. **Overlap quirk:** the pool starts at `0x10 + count*16`, i.e. 4 bytes before the natural end of the table (`0x14 + count*16`). The **last entry's `end_offset` is therefore not stored** — it would sit inside the pool. Its end is implicitly EOF. `fwkit` reproduces this exactly and round-trips `bt_watch.zht` / `bt_watch.eng` byte-identically. ### Picture resources (`bt_watch.res`, 6.6 MB, `0xC0000890`) 2192 entries, names `PIC1 … PIC2192`, **three payload types** in this reference build. Every entry is `u16 w | u16 h | body`; the firmware skips the 4-byte prefix and picks the decoder from `body`: | type | count | body | codec | output | |---|---|---|---|---| | `0x26` (38) | 358 | `"JPEG"` + 18-B hdr | baseline JFIF | `w*h*3` | | `0x05` (5) | 910 | raw **LZ4 block** | no frame/size header | `w*h*3` RGB888 | | `0x0E` (14) | 924 | raw **LZ4 block** | no frame/size header | `w*h*2` RGB565 LE | `0x26` payload (verified, `len == 22 + payload_len`): ``` +0x00 u16 width +0x08 u16 width +0x10 u16 tile_count (1) +0x02 u16 height +0x0A u16 height +0x12 u16 tile_offset (18) +0x04 "JPEG" +0x0C u16 tile_w +0x14 u16 tile_size (len-22) +0x0E u16 tile_h +0x16 baseline JPEG (FF D8 …) ``` The type byte is effectively the **pixel format** (5 ⇒ 3 bpp, 0x0E ⇒ 2 bpp), matching the `.sty` node's `bpp`. The frequent `1f 00 01 00` at the start of LZ4 bodies is stream data (a flat run), **not** a magic. Full details, verified decode of all 2,192 entries, and edit recipes: [Picture codecs](/devices/cmf-watch-pro-2/formats/pictures/). `.sty` image nodes point into this file by **1-based PIC index** (`node[0xC]`: 0x1F…0x890 = PIC31…PIC2192). ## 7. Patch recipes ### Resource string (verified) 1. `res.bin` unpacked → SDFS → `bt_watch.` → RES. 2. The string replaced (same length limit: `len` field). 3. RES rebuilt, SDFS rebuilt (sums/hashes recomputed), `res.bin` repacked (`0x8000` chunks), XML `//` updated, outer header + table CRC rebuilt. `fwkit edit-res IMG PART RESFILE KEY VALUE OUT` ### app.bin byte patch (verified) 1. `aota.parse(TEMP.bin)` → nested XML + parts. 2. `app.bin` patched at `addr - 0x10000000` (same length). 3. nested XML: `file_size = orig_size = len(app)`, `checksum = crc32(app)`. 4. `aota.build(...)` → nested image (header CRC recomputed). 5. outer TEMP: stored = `pack_chunks(nested, 0x200000)`. 6. outer XML TEMP: `file_size = orig_size = len(stored)`, `checksum = crc32(stored)`. 7. outer image rebuilt. `fwkit edit-app IMG ADDR HEX OUT` ## 8. Pitfalls - **`unpacked/app.bin` can be stale.** The real 0.73 app lives in the nested AOTA; extraction from the image under patch (`Image.app_image()`) is required. - **Two different app sizes exist**: 0.57 = `0x255080`, 0.73 = `0x25A080`. Their code addresses differ. - **TEMP XML is special** — using normal XML rules makes the updater reject the image. - **TEMP chunk size is 0x200000**, resources are 0x8000. Mixing them changes every compressed size and can break the header length check. - **Every checksum must be recomputed**: outer header CRC, per-entry stored CRC, XML checksums, SDFS sums/hashes. `fwkit` does all of them. - **RES entry `len` is per-entry**, so strings may grow or shrink; the pool is rebuilt and all `end_offset`s shift. The one invariant is the last entry (its end is EOF) and `pool == 0x10 + count*16`. - Pictures use three formats (see `pictures.md`); a size change requires rebuilding the picture table. Payload start is `end[i-1]` with 4-byte padding, **not** `end-len`. `bt_watch.res` is ~6.6 MB, so a full rebuild is cheap; re-compression uses raw LZ4 (no frame, no size prefix). - Resizing any partition changes its stored/chunked size; the XML `file_size`/`orig_size`/`checksum` for that partition is updated (as the SDK does). - **AGPS trailer** must be copied verbatim; it has no signature. - **Header 0x18 and app ACTH 0x1C/0x20 are not validated** — original values are preserved. - **Flashing is incremental** and slow (~44 KB/s, ~2 min for a resource patch). The `--pipeline 1` option is used; interrupting power during the `TEMP`/`res` write phase aborts the write. - **`AT+GETVERSION` is a compile-time constant**, not read from XML — changing the XML version does not change the reported version. - The application-literal edit was verified offline. The separate resource edit was exercised on hardware. --- # Picture codecs JPEG, raw LZ4, RGB888/RGB565 and all verified picture decoders. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/pictures/ The codecs below were verified against all 2,192 entries of `bt_watch.res` from Watch Pro 2 firmware 1.0.0.73. Every entry decodes; every `.sty` type-4 node's `w/h/bpp` matches the decoded image (0 mismatches). See the [AOTA reference](/devices/cmf-watch-pro-2/formats/aota/) for the firmware package containing this resource file. --- ## 1. Entry layout inside a `RES\x19` file The RES table (see `aota.md`) gives, for entry `i`: ``` u16 len # bytes of the stored payload, INCLUDING the 4-byte w/h prefix u8 type # 0x26 | 0x05 | 0x0E (pictures); text tables use their own type char name[9] # NUL padded, e.g. "PIC332" u32 end # absolute end offset of the payload (last entry's is NOT stored) ``` The payload of entry `i` starts at **`end[i-1]`** (the previous entry's `end`, or the pool offset `hdr[0x10]` for `i == 1`) — **not** at `end - len`. Entries are padded to a **4-byte boundary**, so `end[i] - end[i-1] == align4(len[i])` and there may be 0–3 filler bytes after the payload. This is exactly what the firmware does (`FUN_10187088` builds `p[i] = prev_end + 4`, `q[i] = len - 4`). Payload: ``` +0x00 u16 w +0x02 u16 h +0x04 body ... # format depends on type ``` The firmware **skips the 4-byte `w,h` prefix** (`+4`, `len-4`) and hands `body` to one of two decoders (`FUN_101878e4`): ```c if (*(u32*)body == 'JPEG') jpeg_decode(body, len-4, dst, 1, w, 0,0, w, h); else (*_DAT_00007090)(body, dst, len-4, dst_capacity); ``` `_DAT_00007090` is a RAM function pointer with the exact signature of `LZ4_decompress_safe(src, dst, compressedSize, dstCapacity)` — and it is LZ4: raw block, no frame header, no size prefix. --- ## 2. Type table | type | name | body format | output size | count in `bt_watch.res` | |---|---|---|---|---| | `0x26` (38) | `pic_jpeg` | `"JPEG"` + 18-byte header + baseline JFIF | `w*h*3` | 358 | | `0x05` (5) | `pic_lz4_888` | raw **LZ4 block** | `w*h*3` (RGB888) | 910 | | `0x0E` (14) | `pic_lz4_565` | raw **LZ4 block** | `w*h*2` (RGB565 LE) | 924 | So the RES `type` byte is the *pixel format*, not the codec family: both 5 and 14 are LZ4; only the bytes-per-pixel differs. This matches the `.sty` node's `bpp` field (2 ↔ type 0x0E, 3 ↔ type 0x05). ### 2.1 JPEG (`0x26`) ``` +0x00 u16 w +0x02 u16 h +0x04 "JPEG" (4A 50 45 47) +0x08 u16 width +0x0A u16 height +0x0C u16 tile_width +0x0E u16 tile_height +0x10 u16 tile_count N (1 for all 358 shipped JPEGs) +0x12 N * (u16 offset, u16 length) offsets from "JPEG" +... baseline JFIF (FF D8 FF E0 … FF D9) ``` For one tile the table is `(18, payload_len)` and the JPEG starts at body+0x16; `payload_len` is `len-22` (4-byte w/h prefix + 18-byte tile header). This is the same tile descriptor used by `.ajs`; the player decodes every tile and composites a grid. ### 2.2 LZ4 (`0x05`, `0x0E`) ``` +0x00 u16 w +0x02 u16 h +0x04 LZ4 block, raw (no magic, no 4-byte size, no frame checksum) ``` The decompressed length is **exactly `w*h*bpp`** (bpp 3 for type 5, 2 for type 0x0E). The decoder is given a destination buffer of that size by the caller; the LZ4 block must not overrun it. The vendor uses **LZ4 HC level 12**. `lz4.block.compress(data, store_size=False, mode="high_compression", compression=12)` reproduces every one of the 1,834 shipped LZ4 bodies **byte-for-byte**; `fwkit.lz4.compress` uses it (with a pure-Python fallback). Many images have a body that begins `1f 00 01 00` — that is *not* a header. It is a perfectly ordinary LZ4 token stream that expands to a run of the same byte (token `0x1f` = 1 literal + 19-byte match at offset 1), i.e. a flat colour region at the top-left. It is not stripped. Pixel layout (verified by rendering, see §5): * RGB888: `R,G,B` per pixel, top-down, row-major, no padding between rows. * RGB565: little-endian `u16`, `RRRRRGGGGGGBBBBB`, top-down. * No alpha channel; transparency comes from the `.sty` node / blit rules. --- ## 3. Firmware code path | address | role | |---|---| | `FUN_10187088` | opens `.sty`, `.res`, `.enG`; parses `RES\x19` headers; reads the 16-byte entries (from **0x10**, so the first 4 bytes of each "entry" are the previous `end`) and builds `off[]` (`prev_end+4`) and `len[]` (`len-4`) arrays at `ctx+0x34/0x38` and the second file's at `ctx+0x70/0x74` | | `FUN_101878e4` | type-4 loader: binary-searches `off[]/len[]` by picture index, seeks + reads, JPEG/LZ4 dispatch, cache/refcount | | `FUN_100FFCC4` | JPEG wrapper (`ezJPEG`-style decode into `w*h*3`) | | `*0x7090` | `LZ4_decompress_safe` (RAM pointer, set at boot) | | `FUN_101072f0` / `FUN_10107238` | seek / read on the RES file handle | The picture index used by the `.sty` node is **1-based**; node `pic_index == 1` is `PIC1`. --- ## 4. `logo.res` (boot logo, in `sdfs_k.bin`) `RES\x19`, 3 entries, all **type `0x0E`** (LZ4 RGB565), pool at `0x40`: | # | w×h | stored len | |---|---|---| | 1 | 222×132 | 6,278 | | 2 | 216×84 | 3,671 | | 3 | 220×148 | 5,106 | Same decoder; `logo.sty` (1 scene, 466×466) references them. --- ## 5. Verified round-trip / samples * All 2,192 `bt_watch.res` entries decode without error. * Decoded sizes: 358 × JPEG (`len == 22 + payload_len`), 910 × `w*h*3`, 924 × `w*h*2`. * Node cross-check: 1,342 node-referenced pictures — `w/h` and `bpp` match in 100 % of cases. * Rendered samples (host PNG; JPEG decode uses Pillow): `dumps/samples/pic333.png` shows the 72×72 Settings icon, `dumps/samples/pic335.png` = 120×120 trash-can button, `dumps/samples/pic332.png` = 466×466 yellow-on-blue test frame (RGB888). --- ## 6. Editing pictures (recipes) * **Replace with same size class:** the body is encoded directly. * type 5 → `fwkit.lz4.compress(img_rgb888)`. * type 0x0E → `fwkit.lz4.compress(rgb565_le)`. * These produce the vendor's HC-12 stream byte-for-byte. * The `w,h` in the 4-byte prefix stays identical to the `.sty` node, or the node is updated as well. * **Size changes are fine** — the RES table stores absolute `end` offsets and `len`; the whole file is rebuilt with `fwkit.res.build` (bytes after the edited entry shift, which the table absorbs). * **JPEG:** any baseline JFIF of the same `w×h` works; the tile table's offset/length entries are updated, or the header is regenerated with `picres.encode_jpeg_body(w, h, rgb, quality=85)`. After `"JPEG"` is the same 14-byte tile header used by `.ajs` (count at +0x10, table at +0x12). * The slice is `prev_end .. prev_end+len` (gap padding); `end-len` is never used. `fwkit` implements all of it (`fwkit/picres.py`, `fwkit/lz4.py`, `fwkit/png.py`): ```text uv run fwkit pic-list out/bt_watch.res uv run fwkit pic-decode out/bt_watch.res PIC335 icon.png uv run fwkit pic-set out/bt_watch.res PIC335 icon.png -o res_new.bin uv run fwkit edit-pic firmware.bin res.bin bt_watch.res PIC335 icon.png out.bin ``` `parse()`/`build()` of `bt_watch.res` and `logo.res` are byte-identical. Verified end-to-end: replacing `logo.res` PIC1 with an inverted PNG and rebuilding the whole image passes `fwkit verify`, and the picture decodes back correctly. `pic-set` now re-compresses with LZ4 HC 12, so an unchanged image reproduces the vendor body exactly; changed pixels still get a valid block and the RES table absorbs any size change. --- ## 7. Pitfalls 1. Entry start is `end[i-1]`, not `end[i]-len[i]` (4-byte padding). 2. The 4-byte `w,h` prefix is **inside** `len` but is skipped by the loader; `body` is not a standalone file. 3. `1f 00 01 00` at the start of many LZ4 bodies is data, not magic. 4. Type byte encodes bpp (5 ⇒ 3, 0x0E ⇒ 2); a mismatched node `bpp` makes the UI read past/short of the buffer. 5. The last RES entry has no stored `end`; it ends at EOF. 6. `bt_watch.res` lives inside `res.bin`, which is itself LZMA-chunked — decompression (`img.decompressed("res.bin")`) precedes `sdfs.parse`. 7. JPEG payload length must equal `len-22`; the firmware validates it. --- # SDFS filesystem The simple named-file filesystem used inside res_e and other AOTA partitions. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/sdfs/ SDFS is the filesystem used by the resource partitions. It is deliberately small: a header, a fixed-size entry table, then aligned file bodies. ## Layout ```text 0x00 magic "sdfs.bin" 0x08 u32 zero 0x0C u32 file count 0x10 u32 total image size 0x14 u32 zero 0x18 u32 checksum of the entry table 0x1C u32 checksum of the body 0x20 entries, 32 bytes each: name[12] | u32 offset | u32 size | u32 0 | u32 0 | u32 sum32(data) ``` File offsets are absolute inside the image and aligned to `0x40`. The checksum is a 32-bit word sum (`sum32`), not CRC32: the data is read as little-endian `u32` values, summed modulo 2^32; trailing bytes are ignored. ## Tools ```bash uv run fwkit sdfs-list work/res_e.bin uv run fwkit sdfs-extract work/res_e.bin work/res_e uv run fwkit sdfs-pack work/res_e work/res_e_new.bin ``` The following example replaces `9.ajs`, the stock warm-up animation for sport type 22, with a prepared animation at `work/9.ajs`. It writes a new firmware package to `out/custom.bin`. Create the output directory first. This changes the animation resource, not the app or its warm-up timer. Replacing one file inside an AOTA partition without unpacking everything: ```bash uv run fwkit edit-sdfs dumps/binaries/firmware/JX402_V1.0.0.73.bin res_e.bin 9.ajs work/9.ajs out/custom.bin ``` ## Fixed partition length The stock `res_e.bin` **image** is **58,777,088 bytes**. Its physical partition reservation is **64 MiB (67,108,864 bytes)**. These are different limits. Preserving the stock image length is the conservative repacking approach. Replacing a file can change the natural SDFS size; `fwkit.sdfs.pad_to(img, size)` pads to the requested length and refreshes the size and body checksum. Packer and SDK inspection do not establish a universal fixed-length rejection rule at the stock image size. Larger images have not been verified across the shipped updater, resource readers and recovery path. Do not change partition boundaries on the assumption that image padding is a partition table. ## Capacity The 19 stock animation payloads total **58,776,014 bytes**. The **1,074-byte** difference from the image length includes headers, directory entries and alignment; it is not freely allocatable payload. The **8,331,776 bytes** beyond the stock image remain inside the resource reservation and are unvalidated for reuse. Neither quantity enlarges the writable FAT filesystem. For partition ranges, stock image inventory and writable-storage measurements, see [Storage](/devices/cmf-watch-pro-2/internals/storage/). The interactive [Storage Explorer](/storage-explorer/watch-pro-2/) also provides per-file sizes, checksums and downloadable references. --- # Style bundles (.sty) Scene tables, node graphs, RES pools and loader behaviour. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/style/ The watch UI is **not** LVGL-XML - it is a small compiled scene format in `/NAND:A/bt_watch.sty`, paired at runtime with three other files: | file | role | |---|---| | `/NAND:A/bt_watch.sty` | scene table + node tree (this doc) | | `/NAND:A/bt_watch.res` | picture pool, `RES\x19` (see `pictures.md`) | | `/NAND:A/bt_watch.` | string pool, `RES\x19` | | `/NAND:K/logo.sty` | boot/power-off bundle (same format; 204 B, **1** scene 466x466, id `0x3632CB4E`, no scene data) | ## 0. Ids are opaque, not name hashes Scene and node ids are **builder-assigned 32-bit values**, not hashes of the source names: - there is **no 32-bit hash function** in `app.bin` (no FNV/SDBM/DJB2 constants; the loader only compares ids); - node ids often come in **sequential runs** - 481 of 2,382 top-level ids sit in 74 runs of 3 or more (up to 10, e.g. `0x4D2F8D80..0x4D2F8D87`), which is an allocator, not a hash; - ~30M candidates (fnv1a/fnv1/sdbm/djb2/java/bkdr/crc32 + md5/sha1/sha256 truncations, utf8/utf16le/utf16be, common prefixes/suffixes) matched **none** of the 181 scene ids and none of the real node ids (17 coincidental node hits only). That is why literal pools in `app.bin` contain opaque constants such as `0x5D695BF2` - they are scene ids read from the code, not pointers. **Authoring uses any unused u32, and an id referenced by `app.bin` is never renumbered.** ## 1. Loading path (0.73) ``` FUN_10184804(scene_id, out, sty_path, res_path, lang_path) └─ FUN_10184674(sty, res, lang, 1, 0) // cache by path └─ FUN_10187088(sty, res, lang) // main loader, 0xA8 ctx ├─ opens sty → ctx+0x00 (main) ├─ opens res → ctx+0x2C (RES\x19, picture pool) └─ opens lang → ctx+0x58 (RES\x19, strings) FUN_10186440(ctx, scene_id) // scene lookup (0x24 records) FUN_101848d4(ctx, ids[], out, sizes, n) // load N nodes by id └─ FUN_10187d90(node_list, count, id) FUN_101869e8(ctx, scene, &index, &offset) // walk a scene's items FUN_101866f8(ctx, scene, node_id) // find one item by id FUN_101878e4(ctx, node, refs) // image decoder FUN_10186dd4(ctx, node) // text loader ``` `FUN_10185134` / `FUN_10184f78` build the LVGL view tree from a scene (item -> widget, recursive for containers). `FUN_10187088` also has the alternative **RES album** branch (`"RES"` magic + `WFRes_AlbumReadPic`), used for pictures, not for `.sty` itself. ## 2. Container ``` 0x00 u32 scene_count (181 in 0.73) 0x04 u32 0 0x08 scene[scene_count] 36 B each ... (0x08 + count*36) node base (0x197C in 0.73) ... node records / scene blobs ``` Scene record (36 B): | off | meaning | |---|---| | `0x00` | u32 type = 0 | | `0x04` | u32 `0x01F6019A` = **u16 410 x u16 502** (design canvas) | | `0x08` | u32 0 | | `0x0C` | u8 alpha = 255, then 3 zero bytes | | `0x10` | u32 **top-level item count** | | `0x14` | u32 **first item offset** (relative to the node base; 0 = empty) | | `0x18` | u32 **scene id** | | `0x1C` | u32 `0x00010000` | | `0x20` | u32 0 | The 410x502 constant appears in every scene; it is the source design canvas, not the 466x466 round display. ## 3. Node records ```text +0x00 u32 type 1 = list/grid, 2 = text, 3 = container, 4 = image +0x04 u32 id +0x08 u32 next offset of the next record, RELATIVE to the node base (0 = end of chain / file) +0x0C ... type-specific ``` A record's size is `next - offset`. `next` jumps over a container's whole subtree, so the root chain is a depth-first serialization. Containers (types 1 and 3) hold their children **inline from `+0x24`**; children use the same `next` field, and the last child points at the parent's `next`. Maximum depth seen is 2 (children are only text/image nodes). 0.73 stats: **5,009 records** = 3,020 top-level + 1,989 nested, 2,587 unique ids. Type counts: image 2,630; text 2,305; container 68; list 6. Records are NOT all 12 bytes: text = 36 B (`0x24`), image = 40 B (`0x28`), containers = `0x24 + children`. ### Type 4 - image (40 B) ``` +0x0C u32 picture index (1-based into bt_watch.res) +0x10 u16 x | u16 y +0x14 u16 w | u16 h +0x18 u16 bytes_per_pixel (2 = RGB565, 3 = RGB888) +0x1A u16 format/alpha (0 or 1, sometimes 7) +0x1C u32 offset of the picture BODY inside bt_watch.res +0x20 u32 body length (0 for type-0x05 pictures) ``` `+0x1C`/`+0x20` are a build-time mirror of the `.res` layout: PIC333 is at `0x47EBC` (body), len 1646; PIC1260 at `0x230D10`, len 2847; PIC332 (type 5) at `0x45C20` with the length field left 0. The runtime decoder seeks through the RES entry table, not these fields, so they can go stale when `.res` is rebuilt. They are kept in sync in other firmware builds. `FUN_101878e4` allocates `w*h*bpp`, caches by `(ctx, id)` with a refcount and decodes from `ctx+0x2C` (the RES file); `FUN_10186f50` is the pool allocator/splitter. ### Type 2 - text (36 B) ``` +0x0C u32 text index into bt_watch. +0x10 u16 x | u16 y (0,0 = auto / laid out by parent) +0x14 u16 w | u16 h (0,0 = auto) +0x18 u32 style/format (24 distinct values: 32..548; packed, not fully identified - high bits 0x100/0x200 are common, low bits vary by label; likely font/alignment) +0x1C u32 colour 1 (0 or 0x00FFFFFF) +0x20 u32 colour 2 (0 or 0x00FFFFFF) ``` `FUN_10186dd4` reads the language file (`ctx+0x58`): 1. 16-byte header; **byte `+9` must be 2** - this is the `0x0200` field of a `RES\x19` file, so language files are ordinary RES pools. 2. seek `text_index * 16`, read a 16-B record `{u32 offset, u16 len, ...}` 3. seek `offset`, read `len + 1` bytes (NUL-terminated string). So text nodes hold **no strings** - only an index into `bt_watch.`. Translating the UI therefore only needs the `bt_watch.` files. ### Type 3 - container/page (68, size `0x24 + children`) ``` +0x0C u32 0 +0x10 u16 canvas w | u16 canvas h (410x502) +0x14 u32 0 +0x18 u32 alpha (255) +0x1C u32 child count +0x20 u32 first child offset (== self + 0x24) ``` Used for pages and repeated groups; e.g. scene 125's list has 6 image children, scene 90 has 12 containers of 10 children each. Verified: for all 68, walking `count` children from `+0x24` ends exactly at the parent's `next`. ### Type 1 - list/grid (6, size `0x24 + children`) ``` +0x0C u16 x | u16 y +0x10 u16 w | u16 h +0x14 u16 gap | u16 columns +0x18 u32 child count +0x1C u32 first child offset (== self + 0x24) +0x20 u32 background colour (BGRA, e.g. 0xBC93BCB0) ``` All 6 verified the same way. Scene 125 is a 220x220, gap 16, 2-column list of 6 animation frames (`PIC1534..PIC1539`, all sharing the list id); scenes 126 has three such lists. ## 4. Scene -> items Scene `+0x14` points at the first item, `+0x10` is the number of items; walk `next` from item to item. There are **no opcodes**: the first word of every item is its node type. Example (scene 88, single 204x96 image): ``` scene 88 id=5BBE3E12 410x502 group=1 alpha=255 items=1 data=0x1D63C image id=F9C614C6 pic=1260 204x96 bpp=2 res=0x230D10+0xB1F ``` ``` uv run fwkit sty-tree out/bt_watch.sty 125 scene 125 id=66977E99 410x502 group=1 alpha=255 items=1 data=0x2329C list id=79C22D30 xy=0,0 wh=220x220 cell=16/2 kids=6 image id=79C22D30 pic=1534 220x220 ... res=0x33A49C+0x1528 image id=79C22D30 pic=1535 ... # 6 frames ``` `sty-info` reports `records`, `top-level + nested` and unique ids; `sty-nodes` lists all 5,009 (nested ones are indented). ## 5. Authoring notes - **Ids**: any unused u32; duplicates are normal (the same id can be reused for variants and inside a list). The ids `app.bin` loads are preserved (e.g. `0x5D695BF2` for the pairing-failure dialog, builtin dial ids at `0x101F3D54`). - **In-place edits** (picture index, text index, x/y, colours, res offset/length) keep all sizes and offsets, so `fwkit`'s patch-in-place `build()` stays byte-identical outside the edited bytes. - **Adding a scene** (`sty.add_scene`, CLI `sty-add-scene`) copies a scene's whole top-level chain and appends it after the existing node block. Growing the table moves the node base by 36, but since every offset is **relative to that base**, the old block is copied verbatim; only the appended copy's `next`/container-child offsets are re-emitted (base-relative, with the root terminator kept at `0`). The new scene record is a copy with `count`, `data_offset` and `id` replaced. - The clone **reuses the source node ids** by default. That is legal (the same id already appears in many scenes), but a loader cache may hand a widget the earlier node. A new unused u32 is allocated for every cloned node, including nested children, with `fresh_ids=True` (CLI `--fresh-node-ids`). - A new scene is only displayed if the app knows its id. Either a literal in `app.bin` is patched (`app-scene-refs` finds it, `app-patch-scene` retargets it, or `edit-app` patches a known address) or an id the app already requests is reused. `add_scene` refuses to create a duplicate scene id unless `--force` is given. - **Deleting a scene** (`sty.remove_scene`, CLI `sty-del-scene`) drops the 36-byte table entry. The default rebuilds every surviving scene and drops unreachable records (`sty.compact`); `--keep-orphans` only removes the entry and shifts the node block, leaving dead records behind. The compactor copies shared records once per scene instead of deduplicating, so output is valid but not always minimal. - Type-1/3 children live *inside* the parent's byte range; a naive "walk the root chain" parser silently loses 1,989 nodes (fixed in `fwkit.sty` 0.73, which now parses them). ## 6. Pitfalls - **`0x0C` is not the table start.** `0x0C` is inside scene 0; the table starts at `0x08`. Reading from `0x0C` yields 410x502 as "w/h" and wrong ids. - Node `next` and scene `data_offset` are **relative to the node base**, while picture `pic_index` is 1-based and the image `+0x1C` offset is absolute in the `.res` file. Mixing these up silently produces garbage. - **The same node id can be reused for different variants** (e.g. `0xDEFBE0D9` appears 3x showing PIC333, PIC487 and PIC564). Retargeting uses `--from-pic` (or `all_matches=True`), never the id alone. - Image nodes store geometry that must agree with the picture payload's own `u16 w | u16 h` prefix (see `pictures.md`). A resized sprite is fixed in both the `.sty` node and the RES entry. - Text nodes index `bt_watch.`; an index past the table makes the loader log `read style file error` and return `-1`, and the widget silently falls back to no text. - `.sty` has no checksum/signature of its own - it lives in `res.bin` (SDFS hash) inside the AOTA image, so the AOTA/SDFS rules in `aota.md` apply. - `logo.sty` (in `sdfs_k.bin`) uses the same container; patching boot artwork requires rebuilding `sdfs_k.bin` + the outer AOTA. ## 7. Tooling (`fwkit`) These examples use files extracted from reference firmware 1.0.0.73. `out/bt_watch.sty` is the UI style bundle and `out/app_073.bin` is its application. The hexadecimal IDs refer to that build; inspect your own bundle before changing them. Each edit example is independent. ```text uv run fwkit sty-info out/bt_watch.sty --scenes uv run fwkit sty-nodes out/bt_watch.sty --type 4 uv run fwkit sty-tree out/bt_watch.sty 125 uv run fwkit sty-add-scene out/bt_watch.sty 125 0x76543210 -o out.sty --fresh-node-ids uv run fwkit sty-del-scene out.sty 0x76543210 -o trimmed.sty uv run fwkit sty-set-pic out/bt_watch.sty 0xDEFBE0D9 332 -o out.sty --from-pic 333 uv run fwkit app-scene-refs out/app_073.bin 0x5D695BF2 uv run fwkit app-patch-scene out/app_073.bin 0x5D695BF2 0x5D695BF3 -o out/app_new.bin uv run fwkit edit-sty-pic firmware.bin res.bin bt_watch.sty 0xDEFBE0D9 332 out.bin --from-pic 333 ``` Python API (`fwkit.sty`): ```python import fwkit.sty as sty blob = open("bt_watch.sty", "rb").read() s = sty.parse(blob) # .build() is byte-identical s.node(0xDEFBE0D9) # -> Node(type, id, xy, wh, children, ...) s.scene(125) # -> Scene(width, height, alpha, group, id, count) s.scene_nodes(125) # -> top-level Node list n.children # nested list/container children (depth 2) out = sty.set_pic_index(blob, 0xDEFBE0D9, 332, from_pic=333) out = sty.add_scene(blob, 125, 0x76543210) # append a cloned scene out = sty.add_scene(blob, 125, 0x76543210, fresh_ids=True) out = sty.add_scene(blob, 125, 0x76543210, index=0) # or insert in the table out = sty.remove_scene(blob, 0x76543210) # delete + compact out = sty.remove_scene(blob, 125, compact_nodes=False) # keep orphan records out = sty.compact(blob) # GC without deleting ``` Node records are patched **in place** (only changed bytes are written), so `.sty` edits never shift scene offsets or the node chain. Verified: a one-node retarget changes exactly the 1 byte of `pic_index` (333 -> 332) in the reference resource, with package checksums verified after rebuilding. Round-trip is byte-identical for `bt_watch.sty` and `logo.sty`; `selftest.py` checks it. --- # Watch faces and WFDL Watch-face storage, WFDL packages, resource trees and album configuration. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/formats/watchface/ Reverse-engineered from `WFManager.c`, `WfmPara.c`, `WFRes.c` and the string/address map of the 0.73 app. File formats below are the ones the firmware actually reads; field meanings marked `(?)` are inferred. ## 1. NAND layout | mount | partition | contents | |---|---|---| | `/NAND:A` | `res.bin` | `bt_watch.res`, `bt_watch.sty`, `bt_watch.`, fonts | | `/NAND:C` | `font` / `fonts.bin` | Shipped fonts, emoji and six `local*.wfc` built-in watch-face resources | | `/NAND:E` | `res_e.bin` | `1.ajs … 19.ajs` animations (SDFS) | | `/NAND:K` | `sdfs_k.bin` | `logo.res`, `logo.sty`, sounds, `admusic.dsp` | `res_e.bin` is a normal SDFS container with 19 entries named `N.ajs`; total 58,777,088 B. `fonts.bin` is included in the stock update. It is incorrect to describe the whole `/NAND:C` resource area as absent from OTA. User-uploaded faces and their manager paths are a separate concern from that shipped image. See [Storage](/devices/cmf-watch-pro-2/internals/storage/#filesystem-paths) for the verified mounted-filesystem mapping and [Storage Explorer](/storage-explorer/watch-pro-2/) for the stock file inventory. ## 2. Watch-face package (`*.wfdl` = FMC `.bin`) Produced by the phone app, written to `/NAND:C/`, parsed on-watch by `WFManager_Parser` (`0x100DC3C0`). Format cross-checked byte-for-byte against FMC's working editor/flasher (`freethinkel/fmc`, `docs/cmf-protocol.md`, `format/bin.ts`). ``` 0x00 36 B header 0x24 1 B root tag 0x20 0x25 u16 TLV tree length (LE) 0x27 ... TLV tree ... resources: [u32 hdr][u32 size][data] ... end-36 36 B footer = byte-identical copy of the header ``` Header: | off | meaning | verified on | |---|---|---| | `0x00` | CRC32 **raw** (poly 0xEDB88320, init 0, *no* final XOR) of `file[0x04 : 0x27+tree_len]` — i.e. header bytes 4..0x23 **plus** the root tag, u16 tree length and the whole TLV tree | wf1/wf2/wf3 | | `0x04` | u32 `1` (dial type / format version) | wf1/wf2/wf3 | | `0x08` | 15-byte NUL-padded dial name (`"Metric"`, `"Type"`, `"Classical"`) | wf1/wf2/wf3 | | `0x17` | u8 unknown — `0x0E`/`0x0A`/`0x08` in the samples (preview/style id?) | wf1/wf2/wf3 | | `0x18` | u32 = `file_size − 36`, i.e. offset of the 36-byte footer (tree + resources) | wf1/wf2/wf3 | | `0x1C` | u32 resources-section length | wf1/wf2/wf3 | | `0x20` | CRC32 **raw** of the resources section | wf1/wf2/wf3 | | `0x24` | root tag `0x20` | wf1/wf2/wf3 | | `0x25` | u16 TLV tree length | wf1/wf2/wf3 | `0x24 + 3 + tree_len` = start of the resources; `0x1C` bytes later the 36-byte footer begins; the footer at `file_size − 36` is a byte-identical copy of `header[0:36]` (checked on all three samples). The parser reads 0x24, then 3 bytes (`0x20` + `u16` tree length), and computes `0x27 + tree_len` as the TLV section size. Byte `+0x17` is the name-field tail it logs. TLV nodes: `[tag u8][len u16][value]`. | tag | meaning | |---|---| | `0x20` | root wrapper | | `0x21` / `0x22` | normal / always-on screen | | `0x01` | struct: `x u16, y u16, meta[14]` + optional image ref | | `0x02` | visibility bind | | `0x05` | pivot `flag, x u16, y u16` | | `0x08` | preview struct (`prefix[5]` + ref) | | `0x30` | image (static or pick-by-value) | | `0x60` | number (digit strip, `fmt 0x40` sibling) | | `0x70` | hand (rotating image) | | `0x80`/`0x81` | progress ring, procedural / image-clipped | | `0x5A`/`0x5B` | arc spec for the ring | | `0x48`/`0x68` | frame / group (auto-layout; skippable) | | `0x86` | 64-byte display name | | `0x28` | preview | `meta[14]`: `w u16, h u16, …, id at [9], sub [10], max u24 at [11..13]`. `meta[7] == 4` marks the widget accent-tintable at render time. `id` is the live-data source (0x01 hour, 0x0B minute, 0x19 steps, 0x1A HR, …). Resources: `[u32 hdr][u32 size][LZ4 block]`, `hdr = (cf & 0x1F) | (w << 10) | (h << 21)`, `size` u32 LE. Pixel formats: **4 = RGB565** (`w*h*2`), **5 = RGB565 + 8-bit alpha** (`w*h*3`), **13 = 4-bit alpha** (`w*h/2`), 14 = 8-bit alpha, 24 = BGRA8888, 28 = ETC2 RGBA8 (Pro 3), 1 = raw JPEG. Resource data is LZ4-compressed (`wfm lz4 dec failed`) with **no frame header and no size prefix**; `cf=1` JPEG is decode-only. All **180** resources across the three samples LZ4-decode to exactly `w*h*2`, `w*h*3` or `w*h/2`. All three real samples have `cf=4`, `cf=5` and `cf=13` resources; the decompressed size always equals `w*h*bpp` for the format above. Canvas is 466×466; the round look is artwork, not a clip. An image side above ~480 px can exhaust the watch's RAM while the face loads. ### 2.1 Real sample packages (pulled from the app cache) `/data/data/com.nothing.smartcenter/app_flutter/dial/market/dial_file/*_WatchFace.bin` are the `*.wfdl` packages the app uploads (same format, no wrapper). Copies: `watchfaces\wf{1,2,3}.bin`. | file | size | name | tree len | resources | cf counts | top tags | |---|---|---|---|---|---|---| | `wf1.bin` | 112,751 | `Metric` | 4,911 | 118 | 4×3, 5×115 | `0x30`×46, `0x60`×34, `0x68`×26, `0x70`×26, `0x02`×21, `0x85`×3, `0x28`×2 | | `wf2.bin` | 52,123 | `Type` | 935 | 36 | 4×2, 5×11, 13×23 | `0x30`×13, `0x60`×5, `0x28`×2, `0x21`/`0x22`/`0x86`×1 | | `wf3.bin` | 40,603 | `Classical` | 511 | 26 | 4×4, 5×22 | `0x70`×5, `0x30`×3, `0x28`×2, `0x21`/`0x22`/`0x68`/`0x60`/`0x86`×1 | For all three: `resources_end == file_size − 36` exactly, and `header[0:36] == footer`. `album.cfg` (also in `/NAND:C/`, 166 bytes = 0xA6) is the **current album dial config**; `WfmPara_LoadAlbum` (`0x100DED80`) reads exactly 0xA6 bytes and validates: | off | type | meaning | |---|---|---| | `0x6C` | u32 | magic `0xAC67BD45` | | `0x71` | u8 | style count — must be **non-zero** | | `0x72` | u16 | dial id | | `0x74` | u16 | x | | `0x76` | u16 | y | | `0x78` | u16 | colour (`RGB565`) | Invalid/missing file → defaults `x=0x60`, `y=0xB0`, `colour=0xFFFF`, and the manager logs `no album.cfg file,skip`. Bytes `0x00..0x6B` are not decoded yet (0x6C = 108 = 3×36 or 6×18 — most likely per-style layout records). The runtime copy uses a different layout: magic at `+0x00`, `+0x04` u8, `+0x05` u8, `+0x06` u16 id, `+0x08` x, `+0x0A` y, `+0x0C` colour (this is what the `0x9065` handler logs). Related paths (from the same code region): `%salbum%d.wfdl`, `%salbum0.cfdl`, `%saigc0.cfdl` with prefix `/NAND:/`. A built-in 0xA2-byte default `album.cfg` template is referenced at `0x3804BF4B` (an XIP/flash address, **not** inside `app.bin`) and is copied into the 166-byte buffer before parsing — it cannot be extracted from the OTA image. ### 2.2 Builder / compiler rules These are the rules a writer follows; `fwkit/wfdl.py` implements them and reproduces `wf1/wf2/wf3` **byte-identically**. - Tree = `0x20` + `u16(len(body))` + `body`, where `body` is the concatenation of the screen TLVs. Node = `[tag u8][len u16][payload]`. - Container payloads are the concatenation of child TLVs; they are kept **verbatim** when re-serialising (the parser also exposes them as `Node.children` for inspection). Leaves `0x02 0x40 0x48 0x5A 0x5B 0x5F` are never descended into. - Fixed-leaf widget payloads: `0x01` struct = `x i16, y i16, meta[14]` (18 B) then the ref tail at `+18` (payload must be ≥ 25 B); `0x08` preview struct = `prefix[5]` then the ref tail at `+5` (payload ≥ 12 B). Callers that ignore the tail still render fine. - Image refs are **absolute file offsets**, i.e. `36 + (3 + tree_len) + Σ(8 + stored_size)` of the preceding resources. - kind `0x01`: `[0x01][count u16][offset u32 × count]` - kind `0x61` / `0x71`: `[kind][count u16][first offset u32][block u16 × count]` where `block = stored_size + 8` and following frames are found by walking consecutive blocks (only the first offset is stored). - Because stored sizes are baked into the tree, **resizing any resource requires rewriting every ref tail after it**. Re-emitting an untouched package reuses the source tree byte-for-byte — vendor files contain oddities (e.g. a last block size that disagrees with the real size) that a from-scratch serialiser would silently "fix". - Header/footer: `0x00 = crc32raw(header[4:36] + tree)`, `0x18 = total − 36`, `0x1C = len(resources)`, `0x20 = crc32raw(resources)`, footer = `header[0:36]`. - Pixel payloads are **raw LZ4 blocks** (no size prefix): re-encoding uses a plain LZ4 block compressor; the decoder needs the size implied by `cf/w/h`, so it only has to be *valid*, not byte-identical. - `cf=5` layout is interleaved per pixel: `RGB565 LE` at `raw[i*3]`, alpha byte at `raw[i*3+2]`. `cf=13` packs two pixels per byte with the **high nibble for the even pixel** and `alpha = nibble * 17`. - Widget `x`/`y` are signed 16-bit. Hand value ids: `0x0A` hour, `0x0E` minute, `0x72` / `0x12` second. `fwkit` usage: ```python from fwkit import wfdl w = wfdl.parse(open("wf1.bin", "rb").read()) w.set_png(0, open("background.png", "rb").read()) # keeps cf, resizes open("wf1_new.bin", "wb").write(w.build()) ``` CLI: `wf-info`, `wf-res`, `wf-tree`, `wf-unpack`, `wf-set-res`, `wf-build`. ## 3. WFManager state (`0x100DD17C` + globals) ``` +0x00 u8 flags bit3/bit4 = slot A/B active +0x08 u8 count number of dials +0x09 u8 current index +0x0A u8 (?) +0x0B u8 type 1 = album/built-in (no file) +0x0C u32 current entry value +0x10 entry[count] stride 0x10 +0x00 u32 value +0x04 u8 type +0x06 char name[10] (or index into dial table) +0x30 ptr parsed dial buffer (from WFManager_Parser) +0x44 ptr LVGL object, slot A +0x48 ptr LVGL object, slot B +0x4C u8 flags ``` `WFManager_Load_ByIdx` (`0x100DD17C`): - `type == 1` → `album_wf_layout_create(ui, ctx, &entry.name)` (built-in album dial, no file I/O). - otherwise → open file, `WFManager_Parser`, create LVGL object, position at `0x1D2` (x?), set flag bit. `WFManager_Update` (`0x100DD5AC`) drives the carousel/selection and calls `album_wf_layout_create` for album styles. ## 4. BLE replace flow `WFManager_ReplaceWatchFaceForBle` (`0x100DE7A8`): 1. takes a mutex, logs `(param_1, param_2)`, 2. stores `+0xAC = param_1`, `+0xBC = param_2`, `+0x98 = 3`, 3. calls `FUN_100DC648()` (reload/parse), 4. allocates 0x10 bytes and schedules the UI update. The transfer itself is done by the `wewear` file-transfer commands (`wewear_new_h2d_wf_start`, `wewear_d2h_file_end`, …) which write the received data to `/NAND:C/` and then invoke the replace above. ### 4.1 Flashing from the host (verified) `tools/cmf_watch.py` drives the whole flow over BLE (see the [BLE protocol reference](/devices/cmf-watch-pro-2/protocol/ble/)): it authenticates with the stored authkey, reads `0xA055`, and streams the file the watch pulls in `0xC00` chunks. Appending uses `--old-id 0`. Finish `01` = activated, `0x0A` = stored but not activated (unknown id, `new_wf_id == old_wf_id`, or all slots full). Rebuilt watch faces using the corrected LZ4 encoder have rendered on hardware. See the compression constraints in §6. Slot management is delete + append, not replace: - `wf-delete --id --file ` sends a normal init2 with `new_wf_id = 0`. The firmware's manager enters its delete branch, removes the entry from `album.cfg` and the file from `/NAND:C`, and replies `finish: 01`. Verified on hardware; a following append reused the freed slot. - Replace (`old_wf_id != 0`, `new_wf_id` different) is unreliable — one returned `01` but left the dial unaddressable under both ids. `0x0A` with a non-zero `old_wf_id` means that id is not installed. - A dial can't replace itself (`new == old` → `0x0A`); re-flashing the same name without deleting first is refused. - Side-loaded ids are not in `0xA055`; the host keeps its own list of appended ids. ## 5. `.ajs` animation files (`/NAND:E`) Sport warm-up animations use a separate format from watch faces. The [AJS reference](/devices/cmf-watch-pro-2/formats/ajs/) contains the record layout, tile tables, sport mapping and editing commands. ## 6. Pitfalls - Watch-faces live on `/NAND:C`, which is **not part of the OTA image**; changing them needs BLE upload or on-device file access. - `WFManager_Parser` trusts the tree length (u16 at +0x25): a wrong value causes a short read and a failed load. The 36-byte footer must be a byte-identical copy of the header (the phone-side flasher also checks the name at `+0x08` equals the name at `len-28`). - Files are kept ≤ 32 MB and every image ≤ ~480 px per side; the firmware decodes all bitmaps at load and an oversized one boot-loops the watch. `wfdl.Watchface.build` enforces **480 px per side** and **32 MiB per package**, and `wf-set-res`/`wf-build` abort before writing; the API bypasses the check with `build(validate=False)` only when deliberate. - A widget's image-ref list must reference **consecutive** resource indices; the compiler enforces it and the firmware relies on it. - The tree stores absolute resource offsets and stored sizes. Swapping a bitmap for one of a different size without rewriting the ref tails makes the watch read the middle of the resource section — the dial loads but shows garbage/black. The rebuild goes through `fwkit`/`wfdl.build`, never by hand. - LZ4 blocks must obey the end-of-block rule: the last sequence is literals (≥5 bytes for inputs ≥13), and no match may start within the last 12 bytes or extend into the last 5. The watch's `LZ4_decompress_safe` fails the whole resource otherwise and the dial renders **pitch black**, even though the lenient decoder and the uploader's CRC checks accept it. Fixed in `fwkit.lz4.compress` (matches now stop at `n-5`); `tooling/tests/selftest.py` asserts it for both the vendor blocks and freshly compressed ones. The corrected encoder has been verified on hardware. - Resource editing preserves an existing widget graph. A newly constructed graph needs separate validation; a valid resource checksum does not establish that the firmware can load the layout. - `new_wf_id` is read signed: ids ≥ 0x80000000 are rejected. Capacity is 6 dials. - Only 6 slots: an append to a full watch is accepted at init2 and only refused at finish (`0x0A`, "stored but not activated"). - `album.cfg` is 166 bytes and validated by magic `0xAC67BD45` at `+0x6C` plus a non-zero style count at `+0x71`; a malformed file makes the manager fall back to "no album" (`no album.cfg file,skip`). - Watch-face IDs 1..6 are special-cased in `WfmCheck_CheckFast` (built-in dials). --- # Bad Apple on Watch Pro 2 The source-built Zephyr app and the earlier stock warm-up animation experiment. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/guides/bad-apple/ ## Source-built firmware The [Bad Apple project](https://github.com/fmctools/firmware-wp2-badapple) builds a Zephyr application with its own media assets. This is the version available as the **Bad Apple** boot preset in the [Watch Pro 2 browser emulator](/emulator/watch-pro-2/). It plays video and audio and uses the watch's touch and crown controls. The project repository contains the source, build instructions and a downloadable firmware package. ## Stock warm-up animation experiment An earlier test replaced a sport warm-up animation inside stock firmware. It verified that the stock application could play a rebuilt [AJS animation](/devices/cmf-watch-pro-2/formats/ajs/) after a Bluetooth firmware update. AJS stores JPEG frames and their playback rate. The watch selects a file from its sport table and uses a separate timer for the warm-up screen. The test used `9.ajs`, the file assigned to sport type 22 with an eight-second warm-up timer. A short, silent clip encoded at 240×240 and 25 fps fit that screen. Its frame bytes matched after extraction and rebuild, and playback was verified on the physical watch. The edit replaced one file in `res_e.bin`, the fixed-size resource partition that holds the stock warm-up animations. Because the stock partition is almost full, a replacement must fit in the space reclaimed by the removed file and the small amount of unused space. See the [SDFS capacity reference](/devices/cmf-watch-pro-2/formats/sdfs/#capacity) for the partition size and [AJS animations](/devices/cmf-watch-pro-2/formats/ajs/#tools) for commands to inspect or rebuild an animation. The [data index](/dumps/) identifies the archived stock-resource image. Read the [flashing limitations](/devices/cmf-watch-pro-2/limitations/) before using a firmware image on hardware. --- # Dial editing & upload Unpack a WFDL watch face, replace resources, rebuild and install it over BLE. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/guides/dial-editing/ ## Inspection ```bash uv run fwkit wf-info dumps/samples/watchfaces/wf1.bin --tree uv run fwkit wf-res dumps/samples/watchfaces/wf1.bin uv run fwkit wf-unpack dumps/samples/watchfaces/wf1.bin work/wf1 ``` `wf-unpack` writes `header.bin`, `tree.bin`, `resources/` (decoded PNGs) and raw LZ4 blocks unless `--no-png` is used. ## Editing For this sample, resource 0 is 270 × 270 pixels. Supply a replacement PNG at that size as `icon.png`, or edit the corresponding PNG from the unpacked resources. Replacing a single resource by index: ```bash uv run fwkit wf-set-res dumps/samples/watchfaces/wf1.bin 0 icon.png -o work/wf1_new.bin ``` Rebuilding from a directory of `NNN_*.png` replacements: ```bash uv run fwkit wf-build work/wf1 work/wf1_new.bin --resources work/new_pngs --name "My Dial" ``` The toolkit keeps the original compression format unless `--cf` is forced. Images stay inside the original dimensions; the watch does not scale arbitrary layouts. ## Virtual check Load `work/wf1_new.bin` into the [Watch Pro 2 browser emulator](/emulator/watch-pro-2/) using **Watch face** before trying the physical upload. ## Installation Current dials and slots are listed first: ```bash uv run python tools/cmf_watch.py wf-dials ``` A dry run: ```bash uv run python tools/cmf_watch.py wf-flash --file work/wf1_new.bin --dry-run ``` Appending to a free slot: ```bash uv run python tools/cmf_watch.py wf-flash --file work/wf1_new.bin ``` To update a face already installed, delete it and then append the new file. Direct replacement by ID has produced inconsistent results on hardware. Replace `FACE_ID` below with the ID recorded when that face was installed; do not guess an ID. Some side-loaded faces are missing from `wf-dials`. Deletion removes the installed face, so keep its original file. ```text uv run python tools/cmf_watch.py wf-delete --id FACE_ID --file work/wf1_new.bin uv run python tools/cmf_watch.py wf-flash --file work/wf1_new.bin ``` Check that the new face can actually be selected after upload. A successful transfer does not always mean the face was activated. For black screens or failed uploads, see [Troubleshooting](/getting-started/troubleshooting/). ## Known quirks - The upload handshake is `0x8052` → `0x9075` → watch pulls with `0xA064` → `0x9064` chunks → `0xA065` → `0x9065`. - A finish code of `0x0A` means stored but not activated: all slots full, or `--old-id` is stale. - `0xA055` byte 3 read `7` on the tested unit while the public FMC client hardcodes capacity `6`. Side-loaded dials are not reported in the `wf-dials` list, so an id map is kept separately. - The `.wfdl` header byte `+0x17` is not fully understood; it is preserved during hand-editing. --- # Watch Pro 2 analysis Reference addresses and entry points for analysing the Watch Pro 2 application. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/guides/ghidra/ ## Import Use the shared [Ghidra workflow](/contributing/firmware-analysis/#import) to import an extracted `app.bin`. Watch Pro 2 1.0.0.73 uses Thumb-2 code with an image base of `0x10000000`. File offset X maps to `0x10000000 + X`. ## Bundled scripts The [analysis script reference](/contributing/firmware-analysis/#bundled-scripts) lists the helpers in `tooling/ghidra_scripts/` and their purposes. ## Headless example The [headless commands](/contributing/firmware-analysis/#headless-example) cover import and function export, including Windows command syntax. ## Conventions For Watch Pro 2 1.0.0.73, `0x101F4D70` is the BLE/AT group dispatcher and `0x10054CF4` is `system_app_launch`. These are virtual addresses, not file offsets. See [app.bin internals](/devices/cmf-watch-pro-2/internals/appbin/) for ACTH fields and [BLE protocol](/devices/cmf-watch-pro-2/protocol/ble/) for dispatch and update functions. Do not reuse these addresses for another build. ## Reproducibility Record the image hash, Ghidra version, script arguments and evidence supporting each interpretation. The shared [reproducibility guidance](/contributing/firmware-analysis/#reproducibility) describes what belongs with a finding. --- # Flash an AOTA image Prepare, transfer and check a Watch Pro 2 firmware update with the stock BLE client. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/guides/ota-flash/ This guide uses the stock Watch Pro 2 Bluetooth update service, tested with board JX402 and reference firmware 1.0.0.73. Read the [flashing risks](/devices/cmf-watch-pro-2/limitations/) first. For custom firmware exposing the Actions service, use [Actions SDK OTA](/tooling/actions-ota/). For testing without a watch, use [virtual OTA](/emulator/ota-recovery/). ## Prepare the files and connection Complete [workspace setup](/getting-started/setup/) and run commands from the repository root. Keep an untouched, matching stock image on your computer. In these examples, `firmware/custom.bin` is the package you intend to install; replace that path with your file. Check it before connecting: ```text uv run fwkit verify firmware/custom.bin ``` This checks package integrity, not hardware compatibility. Start with a charged watch and stable power. Keep the computer awake and close to the watch. Turn off phone Bluetooth and close other watch clients to prevent competing connections. ## Pair and check the watch For your first connection, follow [pairing setup](/tooling/ble-tools/#pair-a-watch-pro-2). ```text uv run python tools/cmf_watch.py pair uv run python tools/cmf_watch.py info ``` Pairing exchanges credentials and saves them locally. If the watch was reset, the old credentials may no longer work. Check that `info` reports the expected watch before starting the update. ## Transfer the update This command sends firmware to the physical watch: ```text uv run python tools/ota_client.py --image firmware/custom.bin -v ``` Leave the connection and power undisturbed until the watch finishes installing and restarts. The watch requests the parts it needs; requests can jump between file offsets. The client's reported percentage is bytes served relative to the whole file and may finish below 100%. The client handles the final acknowledgement automatically. For protocol work, see [the stock OTA sequence](/devices/cmf-watch-pro-2/protocol/ota/). `--dry-run` and `--stop-after-a040` are diagnostic negotiation options: both connect and send commands to the watch, although neither sends firmware bytes. They are not offline file checks. ## Check the result After the watch restarts, check its About screen and the feature you changed. Reconnect and run `info` if the installed firmware still provides the stock service. A custom app may expose a different service, so its own instructions must explain subsequent updates. A completed transfer alone does not establish that the new app boots. Keep the log together with the exact firmware file used. If the watch returns to pairing, loses its display or cannot reconnect, follow [Troubleshooting](/getting-started/troubleshooting/). ## Restoring stock Identify the firmware currently running on the watch before choosing the updater: - If it still exposes the stock CMF service, follow this guide using the [Watch Pro 2 stock package](/dumps/#jx402_v10073bin-stock-factory-firmware) instead of your custom package. Repeat the file check, pairing, transfer and post-restart checks. - If it runs a custom app with Actions OTA, follow that app's restoration instructions and the [Actions client reference](/tooling/actions-ota/). Do not assume a full stock package is accepted by an app-only updater. - If it exposes neither service, these Bluetooth clients cannot restore it. See [failed-update troubleshooting](/getting-started/troubleshooting/#an-update-stopped-or-reported-failure). A raw `app.bin` is not a complete stock update package. For a downloaded custom app, use the author's model-specific packaging and installation instructions; renaming it does not turn it into an AOTA package. It can instead be tried through the emulator's [raw application input](/emulator/browser-guide/#load-custom-firmware). If a compatible update service remains available, use its update procedure with a known-good stock package for the same model. The older reconstructed 1.0.0.57 image in the data archive is not a verified hardware downgrade procedure. If the watch no longer exposes an update service, this client cannot establish a recovery connection. See [recovery limits](/devices/cmf-watch-pro-2/internals/recovery/). --- # app.bin internals Vector table, ACTH header, address map, OTA/UI/BLE functions and Ghidra pitfalls. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/internals/appbin/ Reverse-engineering notes for the application image that lives inside the `TEMP.bin` partition of `JX402_V1.0.0.73.bin`. All addresses are virtual (`load_base + file_offset`). Companion docs: `aota.md` (container/patch formats), `protocol.md` (wire protocol + AT registry), `watchface.md` (WFManager, `.wfdl`, `.ajs`). ## 1. Identity and extraction | item | value | |---|---| | file | `out/app_073.bin` (extracted from nested AOTA in `TEMP.bin`) | | size | `0x25A080` = 2,465,920 B | | crc32 | `0x1AA1663D` (== nested `ota.xml` ``) | | load base | **`0x10000000`** | | entry (reset) | `0x10105C59` | | header | `ACTHHTCA` (8 B magic), header size `0x200` | `TEMP.bin` is itself a complete AOTA archive whose only entries are `ota.xml` (at `0x400`, `0x3B8` B), `app.bin` (at `0x800`, **stored raw**, `file_size == orig_size`) and `sdfs.bin` (at `0x25AA00`, `0x5FC0` B, also raw). Load-base check: the Zephyr banner string sits at file `0x2515C0` (`0x102515C0`) and its pointer is stored at file `0x19C48C` as `0x102515C0`. The exported 0.57 image uses the same base, so `addr = 0x10000000 + file_offset`. The 0.57 image (`out/app_057.bin`, `0x255080`, crc32 `0x78AE6370`, entry `0x10102EC9`) is kept only for diffing; its addresses are not valid for the 0.73 image. ## 2. Vector table (file `0x200`) | idx | handler | |---|---| | 0 (SP) | `0x2FFB6740` | | 1 Reset | `0x10105C59` | | 2 NMI | `0x101BF2EB` | | 3–6 HardFault/MemManage/BusFault/UsageFault | `0x10105C2D` | | 11 SVCall | `0x1010556D` | | 12 DebugMon | `0x10105C2D` | | 14 PendSV | `0x101054D1` | | 15 SysTick | `0x100F9461` | | 16–79 IRQ | `0x10105615` (shared default) | Entries from index 80 on are not vector-table entries. ## 3. ACTH header | off | value (0.73) | meaning | |---|---|---| | `0x00` | `ACTHHTCA` | magic | | `0x08` | `0x10105C59` | entry | | `0x0C` | `0x62` (98) | unknown | | `0x14` | `0x10105C59` | entry again | | `0x18` | `0x259C3C` | payload size − `0xC` | | `0x1C` | `0xDCF84B50` | unknown checksum (not crc32/sum32) | | `0x20` | `0x7929C5D6` | unknown checksum (not crc32/sum32) | | `0x24` | `0x200` | header size | The image ends with a 128-byte `sdfs.bin` containing `sdfs.txt` and an embedded SDK build path. ## 4. Static analysis (Ghidra 12.1, Thumb LE) Project `proj073` (`wp2`), import at base `0x10000000` with `-processor ARM:LE:32:Cortex -loader BinaryLoader`. The pre-script `MarkVectors.java` seeds the 80 vector entries before analysis. | metric | value | |---|---| | functions | 8,869 | | code bytes | 1,297,446 | | highest code end | `0x10254FAC` | | strings | 9,296 | | funcs referencing strings | 2,883 | | renamed from `__FILE__` | 510 | | decompiled | 70 | Analysis initially left a ~9 KB hole at `0x100E88AE–0x100EAC84` (the `GETVERSION`/`GETGPSVERSION` handlers). `DisasRange.java` force-disassembles it and re-analysis recovers +927 functions. Outputs: `out/functions.txt`, `out/strings.txt`, `out/blocks.txt`, `out/function_map.tsv`, `out/decomp/*.c`, `out/string_xrefs.txt`. ### Subsystem counts (by source path evidence) bt 461 · ui 361 · kernel 264 · fs 119 · ota 115 · power 77 · audio 62 · sensor 39 ## 5. Key symbols (0.73) ### Startup / version | address | what | |---|---| | `0x10105C59` | reset | | `0x100F7374` | prints Firmware / res / System version | | `0x1005E728` | "JX APP Firmware Version" printf | | `0x10054CF4` | `system_app_launch` (logs `ota_fg`, `res_chk`, `ver_chk`) | | `0x10054DBC` | `system_app_launch_init` | | `0x1019C478` | Zephyr boot banner | `GETVERSION` / `GETGPSVERSION` handlers (found after recovering the 9 KB hole; both take `(ctx, has_data)` and reply through `FUN_100E895C`): | address | what | |---|---| | `0x100EA50C` | `GETVERSION` → `GETVERSION:%s,OK` / `GETVERSION,FAIL`; version text via `ux2sys_api_7(0x11, buf)` | | `0x100E8BD0` | `GETGPSVERSION` → `GETGPSVERSION:%d,OK` / `...FAIL`; value via `thunk_FUN_101978C0()` | | `0x100E895C` | response dispatcher: transport `0` → UART/print (`FUN_101BA194`), `1` → BLE (`FUN_100CB9E0`) | The command registry that dispatches these lives in the data region around `0x101F4D40` (Thumb pointers with bit 0 set, e.g. `0x100E7265`, `0x100E7F79`) and holds `(name, handler)` descriptors, including `0x100EA50D` next to `0x1022925F` ("GETVERSION"). The exact struct layout is still undecoded. ### wewear (phone protocol) | address | what | |---|---| | `0x100CBF84` | read thread; logs `head_id/ability_id/cmd_id/length_id` | | `0x100CC0C8` | connect | | `0x100CC2D4` | `wewear_ble_send_data` | | `0x100CC51C` | `wewear_app_init` | | `0x100EC400` | dispatcher (`invalid head_id`, `unkown cmd_id`) | | `0x100EB12C` | `wewear_d2h_file_end` | | `0x100D343C` | `REQ_VERSION` handler | | `0x100D2D5C` | `sync_watch_face_info` | | `0x100CD324` | `updata_send` progress | | `0x101B60F0` | `UpdataRecordData` | | `0x100EC5B8` | `wewear_ftp_app_init` | Frame header field names are confirmed by the log string at `0x10220D73`: `head_id, ability_id, cmd_id, length_id`. ### Watch-face manager | address | what | |---|---| | `0x100DC3C0` | `WFManager_Parser` | | `0x100DC4EC` | `_WFManager_DelFile` | | `0x100DC82C` | `WFManager_Unload` | | `0x100DCEF4` | `WFManager_UnoadThumbResource` | | `0x100DCFEC` | `WFManager_DelRubbish` | | `0x100DD17C` | `WFManager_Load_ByIdx` | | `0x100DD37C` | `WFManager_Reload` | | `0x100DD3E4` | `WFManager_SetCurrIdxForUi` | | `0x100DD5AC` | `WFManager_Update` | | `0x100DE020` | `WFManager_Init` | | `0x100DE7A8` | `WFManager_ReplaceWatchFaceForBle` | | `0x100DE80C` | `WFManager_DelIdxForUi` | | `0x102243F1` | string `WFManager_SetWatchFaceListForBle` (no direct xref) | | `0x1009A0A4` | `album_wf_layout_create` | | `0x1009A384/A4F0/A890/AB18` | album styles 1–4 | | `0x100B15DC` | logs `wf_idx: %d, %d` | ### OTA / upgrade | address | what | |---|---| | `0x10058438/0x10058508/0x10058544` | `OTA_UPG_FLAG` users | | `0x100585BC` | `OTA_UPG_TYPE` | | `0x1006B3A8/0x1006B3F8/0x1006B444` | `ota_view_init/_deinit/_safemode_set` | | `0x100CDCAC` | "ota app" (msgbox) | | `0x101566F0` | `ota_backend_bt_init` | | `0x10157278` | update OTA state | | `0x10157E84`, `0x10158390` | `ota file_cnt` | | `0x101581E8` | `ota_rx` thread | | `0x10158390` | `handle upgrade` | | `0x10159264` | OTA image progress | | `0x1015A164` | `ota_cfg` default init | | `0x1015A1F0` | `ota_cfg` file deinit | | `0x1015A238/0x1015A314` | `ota_manifest_cfg_files_update` | | `0x1015A66C/0x1015A6D0` | `OTA_INFO` | | `0x1015A6FC` | "ota.ota" | | `0x10244963` | string `wewear_ota_cmd_d2h_end` | ### UI / framework | address | what | |---|---| | `0x100D7488/0x100D77A8/0x100D7854` | `jx_msgbox_creater` variants | | `0x100D587C` | `ui_view_creater` | | `0x1018F4A0` | `lvgl_virtual_display_create` | ## 6. Patching recipe `app.bin` is raw inside the nested AOTA (no LZMA). Patching one or more contiguous bytes of code or data at virtual address `addr` follows this sequence: 1. `aota.parse(TEMP.bin)` → nested header, XML, parts. 2. Patch `app.bin` at `addr - 0x10000000` (same-length only). 3. Set nested XML for `app.bin`: `file_size = orig_size = len(app)`, `checksum = crc32(app)`. 4. Rebuild nested AOTA (`aota.build`, 0x200-aligned parts, AGPS empty) — this recomputes the header CRC. 5. Store back into TEMP: `pack_chunks(nested, 0x200000)` and set outer XML for `TEMP.bin` to `file_size = orig_size = len(stored)`, `checksum = crc32(stored)` (special case for TEMP). 6. Rebuild outer AOTA (res.bin etc. untouched). The SDK implements this as `Image.edit_app(addr, patch)` / `fwkit edit-app IMG ADDR HEX OUT`. Verified: patching 7 bytes at `0x102515C4` ("Booting" → "Patched") produces an image that passes `fwkit verify`, changes exactly 7 bytes of `app.bin`, and updates the nested checksum to `crc32(new_app)`. Caveats: - Fixed-length patches only; growing code requires relocating data and is not supported. - The literal edit above establishes the container rebuild and checksum result. The stock resource-patch boot exercised a separate partition. - `0x1C`/`0x20` in the ACTH header are not verified by the updater. ## 7. AT command registry 71 AT commands are dispatched from a 20-byte-record table at `0x101F4DA4` (names at `0x10229250`, handlers Thumb pointers). `GETVERSION = 0x100EA50C`, `GETGPSVERSION = 0x100E8BD0`; replies go through the transport switch `0x100E895C` (0 = UART, 1 = BLE). See the [BLE protocol reference](/devices/cmf-watch-pro-2/protocol/ble/). ## 8. RE pitfalls (Ghidra) - **The project directory has to exist** before `analyzeHeadless` runs. - The `.bat` wrapper ends in `pause`, so stdin is redirected from `< nul` to avoid the interactive wait. - `-processor ARM:LE:32:Cortex` means **Thumb little-endian** — correct for this image. - **Analysis skips unreferenced code.** A ~9 KB region at `0x100E88AE–0x100EAC84` (all AT handlers) produced no functions until `DisasRange.java` force-disassembled it. Function coverage is diffed against the code range before a symbol map is trusted. - Pointers to strings appear in **literal pools** at the end of the *previous* function; a hit does not mean the containing function is the handler. `getFunctionContaining(reference)` after analysis is the reliable form; a raw pointer scan is not. - `0x101F4DA4`-style tables are only referenced indirectly; the code consumer may load a base address from a different data structure. - The 0.57 and 0.73 images share the base but not addresses; the entry point (`0x10102EC9` vs `0x10105C59`) is the discriminator before a symbol is used. ## 9. Open questions - Meaning of ACTH `0x1C`/`0x20`, and of `0x0C = 0x62`. - `album.cfg` field offsets (166-byte struct); the `.wfdl` body is the FMC `.bin` TLV format (see `watchface.md`). - Whether the running firmware checksums `app.bin` at runtime. - `.sty` ids are opaque builder-assigned values; scene/node tree is mapped (see `style.md`); type 2 `+0x18` font/style encoding remains open. --- # Hardware notes SoC, RAM, flash, display, UART shell, factory mode and recovery notes. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/internals/hardware/ Findings for `JX402_V1.0.0.73` (CMF Watch Pro 2). Addresses are for the 0.73 `app.bin` (`0x10000000` base). ## 1. SoC / memory | item | finding | confidence | |---|---|---| | SoC | Actions ATS3089C, Zephyr RTOS, Thumb-2 | high | | core | Cortex-M class; exact core and clock not extracted | medium | | SRAM | `0x2FF00000..0x30000000` (~1 MB); reset SP `0x2FFB6740` | high | | PSRAM | window at `0x38000000`; refs up to `0x38FFF10A` (~16 MB address space), globals use low offsets | medium | | flash | Examined unit: FORESEE F35SQA001G NAND, 128 MiB main array; GD25LF32E NOR, 4 MiB | high | | storage | Writable FAT at `/NAND:`; resource SDFS at `/NAND:A`, `/NAND:C`, `/NAND:E` and `/NAND:K` | high | The app image is `0x25A080` (2,465,920 B). RAM globals at `0x3800_xxxx` and `0x3830_xxxx` are **not** in `app.bin`; the image is XIP/loaded at `0x10000000`. NAND exposes 123 MiB of logical storage; 5 MiB supports flash management. Only the 10 MiB `udisk` reservation is the writable file-storage volume in the verified layout. See [Storage](/devices/cmf-watch-pro-2/internals/storage/) for partition ranges, formatted capacity and evidence limits, or open [Storage Explorer](/storage-explorer/watch-pro-2/) to inspect the hierarchy. ## 2. Display / graphics | item | finding | |---|---| | panel | 466×466 display used by the stock UI; controller details require model-specific evidence | | refresh | Host rendering speed does not establish the physical panel refresh rate | | UI toolkit | LVGL 8.x (`lvgl/src/extra`, `lv_api_map.h`) | | 2D GPU | VeriSilicon **VGLite** | | media | hardware JPEG decoder (Allwinner `ezJPEG`-style) | | other | display engine (DE), GPU clock control | The UI is a compiled LVGL app; `.sty` only supplies scene geometry, text indices, picture indices and colours. ## 3. App model - Monolithic C/Zephyr `app.bin`; no dynamic loader, no Lua/JS/ELF/plugin engine in the image. - Apps are **views** in a registry of 24-byte entries starting near file offset `0x4b8`: `[name_ptr, 0, create_fn, 0, id_word, 0x01d201d2]`. `id_word` low 16 bits is the view id (`0x4e` about, `0x87` factory). - Stock firmware has no community app loader. Patched firmware and the [community app SDK](https://github.com/fmctools/cmf-watch-sdk) add a separate package-loading path. Its file-storage and RAM limits are distinct from the stock view registry. - Zephyr shell is present over `UART_0`: `devmem`, `kheap`, `dumpbuf`, `nand logic read/write`, `reboot`, `cpuload`. Physical UART pads are required; physical UART access has not been established by this project. ## 4. Hidden factory mode Trigger: **Settings -> About -> five rapid taps on the version row**. `FUN_100bf9bc` increments a counter when `FUN_101cb8a2(...) < 0x14d` (333 ms); after the fifth tap (`counter > 4`) it calls `FUN_101898bc(0x87, 0)`. Menu (`factory_test_view`, id `0x87`): - system comprehensive / semi-finished / finished-product tests - LCD, drawline, touch, sensor level/tilt, light-leak 1/2 - BIO, charge/NTC, battery voltage, MIC, key encoder, motor, speaker - light perception, GPS test - DUT test, AP mode, test record, device QR code - shipping mode, clear-user-data-and-power-off, exit factory mode Labels are inline UTF-8 in `app.bin` around `0x21a9fb..0x21ad97`; they are not in `bt_watch.`. Menu builder `FUN_10094a48`, click handler `FUN_10094800`, key handler `FUN_1009408c`. There are **no Wi-Fi/lwIP/TCP strings** in the app, so factory "AP mode" is not a Wi-Fi access point; it is likely a BLE/RF or PCBA test path. Shipping mode and clear-data can wipe settings; both are destructive and are only invoked deliberately. ## 5. JPEG animation playback `.ajs` files are `/NAND:E/N.ajs`, 240x240 JPEG frames. The prelude byte at `+0x07` is the frame rate (0 => 25). `simple_video_9` creates `lv_timer_2(cb, 1000/fps, ...)`, so shipped files play at 25 fps. All 19 are sport warm-up animations driven by the `0x101ED708` table; they are not menu entries (see the [animation mapping](/devices/cmf-watch-pro-2/formats/watchface/#5-ajs-animation-files-nande)). The stock animation image is densely packed, but its file length is smaller than the physical partition reservation. Extra reserved capacity is not verified as safely reusable. See [SDFS capacity](/devices/cmf-watch-pro-2/formats/sdfs/) and the [AJS format](/devices/cmf-watch-pro-2/formats/ajs/) for editing constraints. A replacement warm-up animation has played on hardware; that experiment is separate from the source-built [Bad Apple firmware](/devices/cmf-watch-pro-2/guides/bad-apple/). --- # Recovery & boot modes What is known about recovery, safe mode, OTA flags and the limits of unbricking. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/internals/recovery/ ## Physical recovery There is **no confirmed, button-only recovery path** for every failure mode on this watch. The app contains safe-mode and launch/retry logic, and OTA flags persist across reboots, but no unit has been deliberately bricked to prove a universal recovery sequence. An Actions OTA loading screen confirms the app exposed that update service in the tested state. It does not establish where boot-time recovery runs or whether the service survives a broken app. ## What QEMU recovery verifies Virtual tests cover stock OTA validation, reset and host-modeled installation, and stock restoration when the modeled crown and charger inputs are present. The [emulator recovery reference](/emulator/ota-recovery/) records the exact stages and command requirements. The guest starts through a compatibility ROM. The real bootloader and recovery partitions were not read back or executed. These tests cannot establish physical recovery when the application, bootloader, storage or power path is damaged. ## Evidence in the firmware The app references: - `system_app_launch` at `0x10054CF4` - safe mode at `0x10054C94` - launch init at `0x10054DBC` - checks for `/NAND:C/A/B/E/K` and `_res_file_check` - persistent OTA flags `OTA_UPG_FLAG` (`0x10058508`) and `OTA_UPG_TYPE` (`0x100585BC`) This suggests a software retry/safe-mode path if an update fails validation. It does not prove that a corrupt bootloader or an interrupted NAND write can be recovered without hardware. ## Factory test menu The watch has a hidden factory/test menu. Entering its shutdown/reset option cleared app data and pairing state on the tested unit. That is why a stale authkey can produce `A052` but no `A040`; re-pairing restores the OTA path. Factory-menu reset options can erase local settings and pairing state. ## UART / physical debug The app contains a UART shell (`nand logic read/write`, `devboot`, `reboot`, `cpuload`) on `UART_0`. Reaching it requires physical access to the debug pads and a USB-UART adapter. Physical access and recovery through this shell have not been verified. Its presence in the firmware is not proof that it can recover a damaged watch. ## Practical precautions Use the [flashing guide](/devices/cmf-watch-pro-2/guides/ota-flash/) for preparation and the [troubleshooting guide](/getting-started/troubleshooting/) for failed updates. Keep a known-good image, verify the candidate and establish that the app responds before retrying. A saved image alone does not provide a working recovery transport. ## Bootloop warning If the stock app never starts, its BLE update service may be unavailable. The virtual crown and charger test does not verify a physical recovery procedure. --- # Storage Verified NAND and NOR capacities, partitions, writable storage, firmware resources and remaining unknowns for Watch Pro 2. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/internals/storage/ import InteractiveTools from '../../../../../components/InteractiveTools.astro'; The examined Watch Pro 2 has **128 MiB of NAND main storage and a separate 4 MiB NOR chip**. Only part of that capacity is a writable filesystem for files. The rest holds firmware, resources, recorded history, diagnostics and flash management data. Storage Explorer shows the complete hierarchy, addresses and evidence. Download the reference as HTML, JSON, Markdown, SVG or PNG. The explorer runs without connecting to a watch. This reference covers board **JX402**, stock firmware **1.0.0.73**, verified chip geometry and saved device captures. The captured watch used patched firmware; its installed apps and personal data are excluded. Capture observations do not establish a factory-reset storage state. These numbers have not been verified for Watch 3 Pro or every Watch Pro 2 hardware revision. ## Capacity at a glance A MiB is 1,048,576 bytes. Partition capacity, image-file size, formatted file-data capacity and free space describe different things. | Layer | Capacity | Meaning | | --- | ---: | --- | | NAND main array | 128 MiB | Physical main storage on the NAND chip | | Logical NAND | 123 MiB | Address space exposed by the NAND driver | | NAND management difference | 5 MiB | Block mapping, update logs and allocation pool; not normal file storage | | NAND partition reservations | 112.5 MiB | Regions assigned by the active partition table | | Unpartitioned logical tail | 10.5 MiB | Within logical NAND, after the last partition | | NOR | 4 MiB | Separate chip containing boot code, application and configuration | The combined main capacity is **132 MiB**. The 123 MiB logical view is part of the 128 MiB NAND, not extra capacity. The chip also has **4 MiB of spare/OOB cells**, separate from its main array. OOB means out-of-band storage used for NAND metadata and error correction; it is excluded from all file budgets here. The older **116.5 MiB** figure adds NAND and NOR partition reservations. It is not the physical capacity and does not describe available space for apps. ## Explore the layout Storage Explorer has three linked views: the hierarchy in Explorer, a size-based map or list in the centre, and the selected region's details. Selecting a region in the map also reveals it in the hierarchy. Search finds partitions and stock resource files. **Files** detail exposes the resource inventory; **List** makes small entries easier to select. Areas follow byte sizes. Their placement is a visual arrangement, not a map of physical adjacency. Explicit ranges distinguish logical NAND offsets from physical NOR offsets. Endpoints in the structured download are exclusive: `[startByte, endByteExclusive)`. The downloads contain the same reviewed reference. HTML works offline, JSON includes stable IDs and parent/child links, and Markdown includes descriptions and evidence. The JSON Schema describes the structured format. SVG and PNG posters can show the current region or whole device. They contain no firmware images, raw dumps, installed-app files or personal configuration values. ## NAND partitions All starts below are offsets in **logical NAND**, not physical chip addresses. The active ACPT partition table passes CRC32 and contains nine NAND entries. ACPT is the Actions partition table that records each region's chip, file identifier, start and reserved size. | Partition | Start | Reservation | Purpose | | --- | --- | ---: | --- | | `fw0_temp` | `0x00000000` | 3.5 MiB | Temporary OTA update staging | | `sdfs_k` | `0x00380000` | 1 MiB | System resources, including boot and sound assets | | `dstorage` | `0x00480000` | 2 MiB | Settings and recorded sensor/activity history | | `font` | `0x00680000` | 12 MiB | Fonts, emoji and built-in watch-face resources | | `res_a` | `0x01280000` | 10 MiB | UI resources, styles and strings | | `res_b` | `0x01C80000` | 8 MiB | Resource partition not supplied by this stock update | | `res_e` | `0x02480000` | 64 MiB | Exercise animation resources | | `runtimel` | `0x06480000` | 2 MiB | Runtime diagnostics | | `udisk` | `0x06680000` | 10 MiB | Writable file storage | The partitions end at `0x07080000`. Logical NAND ends at `0x07B00000`. The intervening 10.5 MiB has no entry in the captured partition table. `res_b` has a known resource role. Its captured SDFS directory has zero entries, but its body checksum fails and the region is not entirely erased. It must not be described as a verified empty filesystem or available file space. Likewise, unmounted settings and log partitions can contain active data. ### Writable file storage `udisk` is the writable file-storage partition. Its ACPT file ID **40** matches the Actions SDK's `PARTITION_FILE_ID_UDISK`. The captured volume uses FAT16, a filesystem that tracks allocated space in clusters. | Captured format property | Value | | --- | ---: | | Partition capacity | 10,485,760 bytes / 10 MiB | | Sector size | 512 bytes | | Cluster size | 1,024 bytes | | FAT copies | 2, identical in the checked capture | | Format metadata | 59,392 bytes | | File-data capacity | 10,426,368 bytes / about 9.943 MiB | These are verified format properties, **not clean-stock free space**. Installed files, directories, allocation rounding and interrupted transfers all affect the free count. No factory-reset free-space measurement is established. The first runtime free-count cache held `0xFFFFFFFF`, meaning that the count was not yet known. The final format and allocation checks instead read the boot sector and both complete FATs. An unknown cached counter must not be interpreted as a capacity or free-space measurement. Allocation is rounded to clusters. A nonempty 64-byte file needs at least one 1,024-byte cluster on this volume; directories and temporary install files also consume space. App executable size, package size and RAM requirements are separate limits. Loader slot counts and package limits belong to the [community app SDK](https://github.com/fmctools/cmf-watch-sdk), not to the flash hardware, and can change between loader versions. The full FAT reconciliation accounted for all non-free clusters as reachable files/directories or an explicitly identified unreferenced chain. A partial package remained allocated without a live directory entry, consistent with an interrupted transfer. The capture did not establish which operation caused it. An allocated orphan chain is not free space; no repair was performed. Repeated observations also showed that assisted-GPS file growth can change free space independently of app installation. Subtracting app file sizes from a modified watch therefore does not produce a measured stock baseline. The emulator's generated FAT geometry differs from this captured physical volume. Emulator free-space numbers must not be used as the hardware's budget. ### Filesystem paths The captured mount list distinguishes writable file storage from resource containers. The stock path resolver chooses the longest matching prefix. | Mount | Backing region | Access through the mounted filesystem | | --- | --- | --- | | `/NAND:` | `udisk` | Writable FAT files | | `/NAND:A` | `res_a` | Resource SDFS | | `/NAND:B` | `res_b` | Resource SDFS | | `/NAND:C` | `font` | Fonts and built-in watch-face SDFS | | `/NAND:E` | `res_e` | Exercise animation SDFS | | `/NAND:K` | `sdfs_k` | System resource SDFS | Resource letters map to partition file IDs: A=10, B=11, C=12, E=14 and K=20. `/NAND:C` does not fall through to writable `/NAND:`. The inspected SDFS operations table lacks generic write, truncate, unlink, rename and directory creation operations. Separate upload, updater or raw-storage code can still modify resources; read-only mounted access is not a hardware write prohibition. `dstorage` and `runtimel` are accessed by partition-backed services, without ordinary filesystem mounts in the checked state. Mount listings alone cannot establish their usage or contents. ### Recorded history Stock code defines eleven typed reservations inside `dstorage`. The 396-byte descriptor table at CPU address `0x101F2C78` and its pointed object-size records match the captured application code. | Type | Purpose | Logical NAND start | Reserved bytes | | --- | --- | --- | ---: | | 0 | Primary settings object | `0x00480000` | 32,768 | | 1 | Secondary settings object | `0x00488000` | 24,576 | | 2 | Additional persistent state | `0x0048E000` | 8,192 | | 3 | Heart-rate history | `0x00490000` | 32,768 | | 4 | Blood-oxygen history | `0x00498000` | 16,384 | | 5 | Step/activity history | `0x0049C000` | 28,672 | | 6 | Sleep history | `0x004A3000` | 102,400 | | 7 | Workout summaries | `0x004BC000` | 61,440 | | 8 | Workout heart-rate history | `0x004CB000` | 442,368 | | 9 | GPS track history | `0x00537000` | 659,456 | | 10 | Stress history | `0x005D8000` | 16,384 | Together these cover **1,425,408 bytes**. The remaining **671,744 bytes (656 KiB)** are outside the decoded descriptors. Their purpose is unresolved. Reserved bytes are not populated-record counts, and individual record fields are not fully decoded. No personal readings or locations are included in the reference. ## NOR partitions NOR is a separate **4 MiB GD25LF32E** chip on the examined unit. The NAND is identified as **FORESEE F35SQA001G**. These identities come from active device identification and geometry, not from the chips chosen by the emulator. NOR offsets below are physical chip offsets. Its thirteen reservations are contiguous and bounded by `0x00400000`. | Partition | Start | Reserved bytes | Purpose | | --- | --- | ---: | --- | | `fw0_boot` | `0x00000000` | 4,096 | Primary bootloader | | `fw0_para` | `0x00001000` | 4,096 | Active partition table | | `fw1_boot` | `0x00002000` | 4,096 | Secondary bootloader reservation | | `fw1_para` | `0x00003000` | 4,096 | Secondary partition-table reservation | | `fw0_rec` | `0x00004000` | 131,072 | Recovery firmware | | `fw0_sys` | `0x00024000` | 3,452,928 | Main application firmware | | `reserved` | `0x0036F000` | 409,600 | Reserved interval | | `fw0_sdfs` | `0x003D3000` | 65,536 | Firmware resources | | `nvram_fa` (file ID 6) | `0x003E3000` | 4,096 | Factory configuration | | `nvram_fa` (file ID 7) | `0x003E4000` | 8,192 | Writable factory configuration | | `nvram_us` | `0x003E6000` | 8,192 | User configuration | | `logbuf` | `0x003E8000` | 16,384 | Diagnostic log buffer | | `coredump` | `0x003EC000` | 81,920 | Crash diagnostics | The captured primary bootloader and recovery images are **3,816** and **95,844** bytes, respectively. Both pass ACTH header and payload checksums; this validates their structure, not their identity as untouched stock images. The secondary boot and parameter reservations read entirely as `FF`. They are reservations, not verified working backup images. Configuration-store roles agree with SDK file IDs and driver lookups. The captured records pass their checked CRCs, but all property values are excluded. Crash storage contains a checksum-valid container with architecture and memory blocks; registers and memory contents are also excluded. Neither observation is a factory usage figure. The stock application file is **2,465,920 bytes**, leaving **987,008 bytes** between its packaged length and its NOR reservation. This arithmetic is not a verified append or patch budget: executable mappings, image checksums, RAM sections and updater/recovery constraints still apply. ### NOR address mappings On the examined device, CPU address `0x12000000` exposes a zero-offset NOR mapping with automatic CRC handling disabled. Its application and partition headers match the separately mapped live headers. Adding a physical NOR offset to `0x14000000` is incorrect for this capture: that alias already exposes the application mapping. No mapping registers were changed during verification. These are firmware-specific CPU mappings, not portable addresses for other boards. File offsets in the explorer are chip offsets, not CPU addresses. ## Stock resource images The stock package supplies five SDFS images plus the application image, with **136 named resource files** in total. Image lengths are not partition capacities. | Image | Partition | Stock image bytes | Named files | | --- | --- | ---: | ---: | | `res.bin` | `res_a` | 10,137,792 | 82 | | `fonts.bin` | `font` | 9,513,344 | 9 | | `res_e.bin` | `res_e` | 58,777,088 | 19 | | `sdfs_k.bin` | `sdfs_k` | 524,096 | 17 | | Nested `sdfs.bin` | `fw0_sdfs` | 24,512 | 9 | All named-file checksums in these stock images validate. `fonts.bin` contains shipped fonts, emoji and six `local*.wfc` watch-face resources. The corresponding resource area must not be described as wholly absent from firmware updates. The 64 MiB `res_e` reservation contains the **58,777,088-byte** stock image. Its 19 animation payloads total **58,776,014 bytes**. The **1,074-byte** difference includes headers, directory entries and alignment; it is not free payload space. The reservation extends **8,331,776 bytes** beyond the stock image. That capacity is not part of FAT and is not verified as safe to reuse. Preserving the stock image length remains the conservative repacking approach. Packer and SDK inspection do not establish a universal rejection rule at that exact length, but a larger resource image has not been verified across the shipped updater, consumers and recovery path. See the [SDFS format](/devices/cmf-watch-pro-2/formats/sdfs/) for encoding and tools. ## NAND block management and the unpartitioned tail The NAND driver exposes **984 logical blocks** out of **1,024 physical blocks**, each with 128 KiB of main data. The flash translation layer (FTL) maps logical blocks to physical blocks and manages updates. Its 40-block difference is 5 MiB. Two bounded runtime metadata captures accounted for those 40 blocks as: | Observed role | Blocks | Main capacity | | --- | ---: | ---: | | Update-log blocks | 8 | 1 MiB | | Allocation pool | 31 | 3.875 MiB | | Active zone table | 1 | 128 KiB | These counts describe the observed running state. Blocks can exchange roles; pool membership does not mean their pages are erased. The 5 MiB is not one contiguous logical tail. Raw physical contents, full OOB data and per-block health were not captured. Identifying a physical reader did not establish a safe invocation path over BLE. Separately, the complete **10.5 MiB logical tail** at `[0x07080000, 0x07B00000)` read as `FF` in both an independent tail scan and the full logical dump. This establishes erased-looking contents at those times, not ownership across versions or safe write/recovery behaviour. Extending the final partition to that endpoint would give a theoretical **20.5 MiB reservation before filesystem overhead**. This is an untested layout, not supported expansion. Changing a partition does not enlarge its existing FAT filesystem; migration, updater compatibility and interrupted-write recovery would need separate implementation and tests. ## Implications for apps and music Existing writable file storage is the established place for custom files. An app package includes headers and relocations in addition to its executable image. Persistent data, widgets, directories and temporary files add allocation cost. Budget against the installed loader/SDK version and actual filesystem, not total chip capacity. Music-file capacity alone does not establish playback support. A local player also needs file access, decoding, streaming buffers and a suitable lifecycle. A phone media-control API does not by itself provide local audio-file playback. Unused-looking resource, history or diagnostic reservations are not substitutes for writable storage. ## Evidence and remaining limits The reference was cross-checked on **21 November 2026** using active chip geometry, the CRC-valid 744-byte ACPT table, the stock update, complete logical NAND/NOR captures, filesystem allocation and driver/code analysis. The logical NAND dump covers **128,974,848 bytes**; NOR covers **4,194,304 bytes**. Saved capture hashes were rechecked before generating the explorer. Package and file checksums prove consistency, not publisher cryptographic authenticity. Captures span a running system and are not a simultaneous snapshot. Matching FAT copies and validated structures provide regional consistency evidence. The stock NAND read API can flush already-dirty runtime-log cache pages; this method must not be described as guaranteed zero-write acquisition. The reference does **not** establish clean-stock free space, destructive full-capacity testing, NAND bad-block health, raw physical/OOB contents, every configuration/history field, safe tail expansion or recovery after repartitioning. No flash, reset, filesystem repair or expansion was used to establish these findings. The [structured reference](/storage-explorer/watch-pro-2/downloads/wp2-storage-structure.v1.json) records byte sizes, explicit ranges, source descriptions and verification limits. Its [JSON Schema](/storage-explorer/watch-pro-2/downloads/wp2-storage-structure.schema.json) defines the fields. The editable generator and reviewed metadata live in `tools/storage_explorer/` in the repository; regenerating the viewer requires neither a raw dump nor access to a watch. --- # Firmware flashing risks and limitations What to check before flashing a CMF Watch Pro 2, what can fail, and what recovery options are verified. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/limitations/ A failed firmware update can leave the **CMF Watch Pro 2** unable to start. If the watch stops booting, its Bluetooth update service may become unavailable. There is no verified physical recovery procedure that covers every failure. ## Before flashing - **Match the model and board.** These hardware results apply to Watch Pro 2 board `JX402` (`jx402_01_3089c` in the update package), with stock firmware `1.0.0.73` as the reference. Use firmware explicitly built for your board. Watch 3 Pro uses a different package. - **Check the image.** For a downloaded firmware file, compare its SHA-256 with the publisher's checksum when available. The `fwkit verify` command checks the internal checksums of an AOTA firmware package. Those checks establish file integrity. Compatibility and successful boot require separate testing. - **Keep a matching stock image on your computer.** You can use it to restore stock if the watch still exposes a compatible Bluetooth update service. Keep a copy of the exact file you install so you can identify the build if something fails. - **Keep power and Bluetooth stable.** Start with the watch charged and the host awake. If using FMC on your phone, disconnect any competing watch client. Leave the update client connected until the watch finishes installing and restarts. Transfer time depends on the package and Bluetooth connection. See the [reference firmware downloads](/dumps/) and the [desktop flashing guide](/devices/cmf-watch-pro-2/guides/ota-flash/). ## If the update fails | What the watch does | What to check | |---|---| | Restarts into its usual interface | Check the firmware version and reconnect before retrying. If the watch was reset, pair it again because the previous Bluetooth credentials may be stale. | | Shows an update or recovery screen | Check whether your updater can still connect. A visible progress bar alone only confirms the screen is active. Recovery depends on which update service is available in that state. | | Stays black or repeatedly restarts | Stop repeated transfers. If the watch still connects, record its version and visible update services. If it remains unreachable, physical diagnosis or vendor service may be needed. | An interruption can happen while the watch receives the package or while it installs it. A failed transfer may leave the previous firmware working, but the outcome depends on the point of failure. The Watch Pro 2 AOTA packages documented here update the application and resources. They do not replace the bootloader, which is the code that starts the watch before the app. A stock package cannot repair an inaccessible or damaged bootloader through this path. See [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/). ## What the emulator can verify Use the [browser emulator](/emulator/watch-pro-2/) to check whether a supported firmware package boots and draws a usable screen. Desktop QEMU can also test Bluetooth transfer, guest validation, reboot and installation into virtual storage. Its crown-and-charger test restores a broken virtual app using the emulator's recovery model. Physical bootloader behaviour, recovery after power loss, and recovery with a broken Bluetooth service still require hardware evidence. [Virtual OTA and recovery](/emulator/ota-recovery/) ## Watch faces and firmware resources A watch-face upload is a separate operation from a firmware update. A malformed or oversized face can still prevent the stock interface from loading. The stock AOTA packages documented here leave the partition holding user-installed faces outside the update, so reinstalling firmware may leave the offending face in place. See [Watch-face editing and upload](/devices/cmf-watch-pro-2/guides/dial-editing/) for validation and upload guidance. Firmware resource partitions have fixed capacities. A replacement must fit the partition after rebuilding, including alignment and padding. See the [SDFS format and capacity reference](/devices/cmf-watch-pro-2/formats/sdfs/) when building or changing a package. The [storage reference](/devices/cmf-watch-pro-2/internals/storage/) distinguishes physical capacity, partition reservations and writable file storage. [Storage Explorer](/storage-explorer/watch-pro-2/) shows the verified layout. Unpartitioned or erased-looking regions are not verified expansion space. For help with connection failures, pairing screens and failed downloads, see [Troubleshooting](/getting-started/troubleshooting/). --- # BLE protocol Frame format, authentication, AES/CRC, shell commands, file upload and the OTA state machine. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/protocol/ble/ The watch exposes two framed command channels that share the same 11-byte header: - **BLE GATT** — used by Nothing X (`wewear` layer) - **SPP / UART** — AT commands and the SPP firmware upload path ## 1. Frame format The 11-byte header is **big-endian**. Payload fields are generally **little-endian** (FMC reads them with `DataView(..., true)`); the OTA A042/INIT payloads follow the same rule. ``` +0x00 u8 head_id = 0xF5 +0x01 u16 length payload length +0x03 u16 c1 command key high 16 (0xFFFF for system commands) +0x05 u16 chunk_count number of chunks for this command +0x07 u16 chunk_index 1-based index +0x09 u16 c2 command key low 16 +0x0B u8[] payload ``` The full command key is `(c1 << 16) | c2`; the firmware logs it as `head_id, c1, c2, length`. This is why system commands appear as `0xFFFF_9052` and ability commands as `_`. The reader (`FUN_100CBF84` for BLE, `FUN_100EC400` for SPP) reads the 11-byte header, byte-swaps the five u16 fields, and logs `head_id, ability_id, cmd_id, length_id`. The payload is read on demand with the requested `length`. For multi-chunk commands the receiver reassembles all `chunk_count` frames in order. Responses reuse the same buffer and set `c2 | 0xA000` (0x9052 → 0xA052, and so on). `chunk_count`/`chunk_index` are zeroed. Cross-checked against FMC's working Web-Bluetooth implementation (`freethinkel/fmc`, `ble-protocol.ts`): identical 11-byte header, big-endian, `chunk_index` 1-based, MTU 180. ## 2. Dispatch `FUN_100D343C` (BLE) dispatches in two stages: 1. `c1 == 0xFFFF` → switch on **c2** (system commands). 2. otherwise `c1` is an **ability id** and the handler switch is on that value (app-level messages such as time/health/UI). System cmds seen: `0x8004 0x8005 0x8006 0x8047 0x8049 0x804A 0x804B 0x804D 0x8051 0x8052 0x9052 0x9053 0x9055–0x9059 0x905C 0x905D 0x9066–0x9074 0x9076–0x907A 0x907F 0x9080 0x9083 0x908A 0x908B`. Ability ids seen: `0x53 0x54 0x56 0x57 0x58 0x5A–0x62 0x65 0x95 0x99 0x9A 0x9B 0x9F`. Notable handlers: | cmd | behavior | |---|---| | `0x8004` | `FUN_100D2E78()` | | `0x8005` | reads payload, 1-byte status reply, cmd 0x0000 in reply | | `0x8006` | reads payload, 4-byte reply | | `0x8047` | sets flags and copies payload (`FUN_100CC284`) | | `0x804B` | encrypted payload (see §3) | | `0x9052` | session/keepalive; reply status byte 0xC/2/10, may arm OTA | | `0x9053` | resets UI (`FUN_101D0A9E(0)`), reply 0x5A | | `0x9055–0x905D, 0x9066+` | per-command handlers, mostly notifications | Unknown cmd → log `unkown cmd_id:0x%04x`; invalid ability → log `invalid head_id: %04x`. ## 3. Payload checksum / encryption `FUN_101B605A(&len_out, data, len, cmd)` is used to append the payload tail: - append `crc32(data)` as 4 **little-endian** bytes, - pad to a 16-byte boundary, then AES-CBC encrypt (fixed IV `5051525354555657606162636465665a`, PKCS#7) with the session key. The verifier is the mirror image (`FUN_101B608C` → `FUN_100CCC0C`). **Plaintext commands** (CRC32 appended, no AES) are, per FMC (verified live): `0xFFFF8047` (pair request), `0xFFFF0048` (pair reply), `0xFFFF9064` (watch-face chunk data) and `0xFFFFA061` (auth failed — 6 bytes, not a block). Everything else is encrypted once a session key exists. The 0.73 static analysis of `FUN_100CCAB4` only flagged `0x804B`/`0x49` because those take the key-selection path; the plaintext set above is the better rule for tooling. Session key: `sha256(nonce || authkey)[:16]`, where `authkey` is `sha256(random1 || random2 || secret)[:16]` and `secret` comes from the shell channel (`AT GETSECRET` → `GETSECRET:<32 hex>,OK`). Matches the AES key recovered from the phone-side OTA capture. ## 4. SPP firmware upload path `FUN_100EC400` is the SPP dispatcher (same 11-byte header), opcodes: | cmd | handler | role | |---|---|---| | `0x8052` | `FUN_100EC358` | watch-face upload init 1, reply `0x52` (status 1 = ok) | | `0x905E` | `FUN_100EB344` | upload-flow handshake: zero 0x3C stack, `k_sem_give(ctx+0x50)`, **no reply** | | `0x905F` | `FUN_100EB50C` | SPP chunk write: append at `state+0xC`, check `chunk_index`, per-chunk CRC | | `0x9060` | `FUN_100EB218` | forward payload to a named file service (`FUN_100EAF48`), then reply `0x9060` status | | `0x9061` | — | unknown command log | | `0x9063` | `FUN_100EBAC4` | upload-flow handshake: `k_sem_give(ctx+0x50)`, **no reply** | | `0x9064` | `FUN_100EC19C` | **watch-face chunk data** → `FUN_101DAFE0(ctx+0x50)` | | `0x9065` | `FUN_100EB990` | **watch-face finish ack 2**, CRC verify; also writes `album.cfg` (see `watchface.md` §2.1) | | `0x9075` | `FUN_100EBE24` | **watch-face upload init 2** → `FUN_101DAFE0(ctx+0x50)` | `0x905F` enforces: `offset + len < 0xC01` per packet, sequential packet index (`byte[state+0x10] + 1 == chunk_index`), and per-packet checksum. Ghidra marks `0x9064`/`0x9075` as non-returning only because `FUN_101DAFE0` is mis-annotated; FMC's working client proves both return and are acknowledged. ### 4.1 Watch-face upload (verified end-to-end) Channel: `02f00000-…-ffe1` (write, **without response**) / `…-ffe2` (notify). Every step below — init1, init2, chunks, finish — goes over the **data** channel, not `fff1/fff2`. The watch **pulls** the data: 1. phone → `0x8052` payload `[0xA5]`; watch → `0x0052`, `[1]` = ok. 2. phone → `0x9075` 13-byte LE payload: `type=3 (u8) | old_wf_id (u32) | new_wf_id (u32) | size (u32)`. Watch → `0xA075`, `[1]` = ok. 3. watch → `0xA064` chunk request: `offset (u32 **BE**) | len (u32 **BE**) | percent (u8)`. Phone → `0x9064` with that raw slice (plaintext, CRC32 tail only). 4. watch → `0xA065` finish ack; phone → `0x9065` `[0xA5]`. `[1]` = activated (or deleted), `[0x0A]` = stored but not activated (unknown `old_wf_id`, `new_wf_id == old_wf_id`, or full slots). 5. watch may send `0xA055` installed-dial list on `ffe2` right after auth (**encrypted**, PKCS7): `4-byte header | n × u32 LE id | CRC32 LE`. Sample `01 02 03 07 | 45 01 00 00 | d0 3f 51 71 | dc 9c 4d 3a | 33 49 0f c2` = 3 ids (`325`, `1901150160`, `978164956`), header byte 2 = count, byte 3 = capacity (7 on this unit, FMC hardcodes 6). Side-loaded dials are **not** listed (the installed `0x338dbb59` was absent) — `0xA055` alone cannot tell whether a slot is free. Framing: encrypted payloads are split into `floor((180-11)/16)*16 - 5 = 155`-byte pieces, each `+CRC32` then AES-CBC (header stays plaintext); plaintext (`0x9064`, `0x8047`, `0x0048`, `0xA061`) is split into 160-byte pieces, each `+CRC32`. Header `count` = number of pieces, `index` starts at 1. **Watch→phone plaintext frames omit the CRC but still declare `plen` including it** (`0x0048` declares 52, sends 48): a parser that trusts `plen` desyncs and never sees `0xA055`. Slot rules (verified on hardware, 0.73): - `old_wf_id = 0` **appends** a new dial. Re-verified after a delete: the freed slot is reused and the append returns `finish: 01`. - `old_wf_id = ` with `new_wf_id = 0` **deletes** that dial. This is an undocumented protocol primitive (the firmware state machine has a delete branch; FMC only exposes delete in the watch UI). The data phase still runs — the uploaded bytes are only a filler. Verified: `wf-delete --id 0x407d3a27` returned `finish: 01`, the dial vanished, and a following append succeeded. - `new_wf_id == old_wf_id` is refused at finish (`0x0A`), so a "self-replace" is not possible; delete + append is the alternative. - A replace with a **different** `new_wf_id` is unreliable: one replace (`0x338dbb59` → `0x417d3bba`) returned `finish: 01`, but afterwards neither id was addressable (`0x0A` on both). Replace is therefore unsuitable for slot management, and `0x0A` indicates that the id is not installed. - `new_wf_id` is read **signed** — a negative id is rejected. FMC derives `id = 10000 + fnv1a(seed) % (0x7FFFFFFF - 10000)` to stay positive and above the stock ids (273–280). Capacity is 6 dials per FMC (a055 byte 3 says 7); a full watch only refuses at the very end (finish `0x0A`). `album.cfg` lives on `/NAND:C` and its entries are what `old_wf_id` is matched against; the ids of side-loaded dials are only known to the host (`a055` omits them), so the host keeps a local record of the dials it appended. Verified on hardware (0.73): 89,037-byte face, 29 chunk requests of `0xC00`, `finish: 01`, appended with `old_wf_id=0`, id `0x338dbb59`. An 86,884-byte 86 KB file with `old_wf_id=0x338dbb59`, `new_wf_id= 0x417d3bba` also returned `finish: 01` (see the replace caveat above). Tooling: `watools/cmf_watch.py wf-dials`, `wf-flash --file X [--old-id N] [--dry-run]` and `wf-delete --id N --file X`. Cross-check note: the 0.73 static analysis had labelled `0x9064`/ `0x9075` as reset/bootloader — wrong; FMC's live client shows both are the watch-face upload path. The SPP dispatcher labels do not match the BLE path's opcodes (`0x905F` is the SPP-only chunk write). ## 5. AT command registry A 71-entry table at `0x101F4DA4` (records 20 B, terminated by zeros): ``` +0x00 const char *name +0x04 const char *name (duplicate) +0x08 u32 0 +0x0C handler (Thumb pointer, bit0 set) +0x10 u32 0 ``` Name strings live at `0x10229250`–`0x10229600`. The group descriptor is at `0x101F4D84`: ``` 0x101F4D70..0x101F4D84 six code pointers (0x100E7264, 0x100E755C, 0x100E73C0, 0x100E7A9C, 0x100E7CE0, 0x100E7F78) 0x101F4D88 "AT" 0x101F4D8C "AT commands" 0x101F4D90 0x101F4D9C (→ 0) 0x101F4D94/98/9C 0 0x101F4DA0 0x101F4DA4 (→ command table) ``` The descriptor itself has **no direct xref**; only `0x101F4D70` is referenced (from `0x100E734C`/`0x100E7388`, a timer registration), so the shell walks this region by address arithmetic at runtime. The six pointers are read as the group's lifecycle callbacks (their exact role is unknown; the last one is also a todo-expiry timer callback). Handler signature is roughly `(frame_ctx, has_data)`. Replies go through `FUN_100E895C`, which selects transport: - `*0x100E8988 == 0` → UART/print (`FUN_101BA194`) - `*0x100E8988 == 1` → BLE send (`FUN_100CB9E0`) | name | handler | name | handler | |---|---|---|---| | GETVERSION | `0x100EA50C` | SETMOTOR | `0x100EA4A4` | | GETCAPACITY | `0x100EA458` | GETKEYSTATUS | `0x100EA408` | | GETENCODERSTATUS | `0x100EAC1C` | GETENCODERINIT | `0x100EA3BC` | | ENTERBTBQB | `0x100EA328` | GETGSENSOR | `0x100EA2C0` | | SETGPSSWITCH | `0x100EA254` | GETGPSSNR | `0x100EA1D4` | | GETCLOCKDRIFT | `0x100EA184` | SETNAME | `0x100EA080` | | GETNAME | `0x100EA024` | SETBTMAC | `0x100E9FC4` | | GETBTMAC | `0x100E9F48` | SETPID | `0x100E9EEC` | | GETPID | `0x100E9E8C` | SETSECRET | `0x100E9E30` | | GETSECRET | `0x100E9DD0` | SETGPIO | `0x100E9C7C` | | GETFLASH | `0x100E9C30` | LOOPSWITCH | `0x100EABA0` | | GETNTCTEMP | `0x100E9BE4` | SHUTDOWN | `0x100E9B98` | | ENTERFCCMODE | `0x100E9B38` | SETWAKELOCK | `0x100E9AC0` | | SETAPMODE | `0x100E9A34` | SETSN | `0x100E99D8` | | GETSN | `0x100E9978` | SHIPMODE | `0x100E9924` | | GETMCUCHIPID | `0x100E98C4` | REBOOT | `0x100E9878` | | GETSCREEN | `0x100E9834` | SETLPHOSTLUX | `0x100E97D8` | | SETLPALIGN | `0x100E9768` | GETLPALIGNSTATUS | `0x100E971C` | | GETLPSLAVELUX | `0x100E96D0` | SETKNOBTARGET | `0x100E9674` | | SETKNOBALIGN | `0x100E960C` | GETKNOBALIGN | `0x100E95BC` | | SETKONBDISPLACEMENT | `0x100E9554` | GETKONBDISPLACEMENT | `0x100E9504` | | SETKNOBREINIT | `0x100E94C0` | SETKNOBDUMP | `0x100E944C` | | SETLIMITCHARPERCENT | `0x100E93D4` | GETLIMITCHARPERCENT | `0x100E9374` | | ENTERFATE | `0x100E9338` | SETFHTESTSWITCH | `0x100E92D0` | | GETFHTESTRESULT | `0x100E927C` | CHECKCWALGO | `0x100E91F8` | | OPENCWALGO | `0x100E9184` | SETLCDSWITCH | `0x100E9104` | | SETLCDPAGE | `0x100E90A0` | SETLTLKBKSWITCH | `0x100E9020` | | GETLTLKBKDATA | `0x100E8FC0` | SETLTLKBESWITCH | `0x100E8F40` | | GETLTLKBEDATA | `0x100E8EF0` | SETBIOSWITCH | `0x100E8E70` | | GETBIODATA | `0x100E8E28` | SETKEYSWITCH | `0x100E8DA8` | | GETKEYRESULT | `0x100E8D48` | SETFACTSWITCH | `0x100E8CE4` | | GETBATLV | `0x100E8C9C` | SETLIGHTWITCH | `0x100E8C1C` | | GETGPSVERSION | `0x100E8BD0` | SETHR | `0x100E8B70` | | SETSPO2 | `0x100E8B0C` | SETHRV | `0x100E8AA8` | | SETADT | `0x100E8A44` | SETHRTEST | `0x100E89E0` | | SETBIOPERCENT | `0x100E8990` | | | `AT+GETVERSION` returns a **compile-time** version string (`ux2sys_api_7(0x11, buf)`), not data from the OTA XML. ## 6. OTA over BLE (AOTA path) The [OTA protocol reference](/devices/cmf-watch-pro-2/protocol/ota/) defines the characteristics, authentication, range requests and mandatory END acknowledgement. The watch requests byte ranges; the host serves those ranges rather than assuming a sequential transfer. The application-side functions below describe how the reference build handles that protocol. On-device side: | address | what | |---|---| | `0x101566F0` | `ota_backend_bt_init` | | `0x10157278` | state setter (old → new, callback at `+0xC`) | | `0x101581E8` | `ota_rx` thread | | `0x10158390` | upgrade state machine ("handle upgrade") | | `0x10159264` | progress init: `+0x228` total, `+0x22C` offset, `+0x230` start, `+0x238` percent, `+0x239` active | | `0x1015A164` | `ota_cfg` default init (0x233 B, magic `A1 A2 A3 A4`) | | `0x1015A66C` | `OTA_INFO` read (4-byte magic `A5 A5 A5 A5`) | `OTA_UPG_FLAG` / `OTA_UPG_TYPE` (`0x10058508`, `0x100585BC`) persist the "upgrade in progress" state so the watch re-enters the OTA UI after a reset. ### State machine (`FUN_10158390`, setter `FUN_10157278`) `FUN_10157278(ctx, new)` stores `new` at `ctx[0]` and calls the callback at `ctx[3]` with `(new, old)`. Values: | state | meaning | set at | |---|---|---| | 0 | idle / reset | start, and after a terminal result | | 1 | transferring (image accepted) | after the header/manifest check | | 2 | committed (reboot pending) | after `OTA_INFO` + manifest update + `FUN_101592d4` | | 3 | error / finished | any failure path, then `0` | Paths: 1. Validate `ota.ota` magic (`FUN_1015a6fc` reads it) and the image header (`FUN_10159fe8`). On mismatch → state 3 → 0. 2. Compare version/serial (`FUN_101d099c`, `FUN_101d09a0`, `FUN_101bf37a` on `+0x50`), check the `+0x2E6`/`+0x2E7` type bytes → state 3 on mismatch, else **state 1** and start the RX thread. 3. After all files are written: per-file size/CRC checks (`FUN_1015a600`, `FUN_1015a630`), `FUN_1015a66c` writes `OTA_INFO`, `FUN_1015a238` updates the manifest, `FUN_1015a1f0` closes it → **state 2** and `*(0x6d + DAT_10158e94) = 1` (reboot flag). 4. Reboot applies the update; failure paths call `FUN_101574a4` (cleanup) and return to **state 0**. `ota.ota` is a 0x233-byte (563) record, zeroed and stamped `A4 A3 A2 A1` at `+0x00`; the separate 4-byte `OTA_INFO` is `0` or `0xA5 A5 A5 A5`. ### 6.1 Read surfaces that do not exist All host-reachable paths were checked for a way to read `/NAND:C` files; none of them can: | surface | result | |---|---| | AT registry | no file commands at all — `GETFLASH` returns the flash size (`FUN_1011FC30`), `SETKNOBDUMP` posts a UI message via `ux2sys_api(0x5E)`, `ENTERFATEMODE` calls `FUN_100CC278` | | SPP `wewear` | `A042` is write-only; `wewear_ota_cmd_d2h_image_data_req` (`0x10156150`) means *the watch asks the phone* for the next image chunk; `FUN_10156948` is a flash write | | `logsrv` BLE service (`102030E1`, `_logsrv_init`) | log streaming only: TLV frames with `svc_id`/`cmd`, `stream_create`, and the strings `logsrv: log/tx/rx/stream …`. No path or filename is ever passed, so it cannot be turned into a file read | | FMC reference client | has no file-read opcode either (`ble-protocol.ts` only has `wfInit2 0x9075`, `wfChunkWrite 0x9064`, `wfFinishAck2 0x9065`) | Consequence: `album.cfg` and `.wfdl` files are only obtainable from a NAND dump / hardware read, or by flashing a patched app that exports them — zero-copy host access does not exist. ## 7. Pitfalls - The head byte is always `0xF5`; frames with other values are dropped. - **Byte order**: fields are big-endian on the wire but host-order in the dispatcher (the reader swaps in place first). Frames crafted from a script are written big-endian. - Response cmd = request cmd `| 0xA000`; the request value is not echoed. - `length` counts payload only (header is always 0x0B). - For `0x804B` and `cmd & 0x7FFF == 0x49`, the payload is AES-CBC with an extra 4-byte CRC and padding; a plain payload will be rejected. - The SPP file path (`0x905F`) requires strictly sequential `chunk_index` indices, starting from the state's current index. - `0x905E/0x9063/0x9064/0x9075` do **not** "return" in the decompiler only because they end in `k_sem_give` (mis-annotated as non-returning); they are upload-flow handshakes, not reset/bootloader. `0x905E`/`0x9063` send no reply at all. - There is **no device→host file read** in the SPP dispatcher: `wewear_d2h_*` only covers OTA image data. `album.cfg` (watch-side `/NAND:C`) therefore cannot be pulled over SPP — it has to be read from a NAND dump. - BLE `INIT2` (`0x9040`) must be written to the OTA characteristic `ff01`. Sending it on `CMD_W` with a valid session reboots the watch and drops the link. See [AOTA OTA flow](/devices/cmf-watch-pro-2/protocol/ota/). - The end of the data phase needs `0x9041` with payload `A5` when the watch reports `A041`; skipping it leaves the update staged, not committed. - Not every `0x905x` cmd has a handler in 0.73; unknown cmds log and are ignored. --- # AOTA OTA flow The verified BLE firmware-update sequence, including INIT2 placement and the end acknowledgement. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/protocol/ota/ This is the flow that actually committed a full AOTA image on hardware. It is the most failure-sensitive part of the project, and the order of the steps matters. ## Characteristics | Role | UUID | |---|---| | Command write | `0000fff2-0000-1000-8000-00805f9b34fb` (`CMD_W`) | | Command notify | `0000fff1-...` (`CMD_N`) | | OTA write | `02f00000-0000-0000-0000-00000000ff01` | | OTA notify | `02f00000-0000-0000-0000-00000000ff02` | | Shell write / notify | `77d4ff01-...` / `77d4ff02-...` | The watch **pulls** firmware data: after `A040` it sends `A042` requests and the host answers with `0x9042` frames on the OTA characteristic. ## Prerequisites 1. The watch is on the expected firmware and has enough battery. 2. Re-pairing has happened after any reset/factory-menu clear. A stale authkey can still produce `A052`, but `A040` will never arrive. 3. The AOTA image passes `fwkit verify`. 4. The relevant risks are documented on the [Limitations & risks](/devices/cmf-watch-pro-2/limitations/) page. ## Sequence ### 1. Reconnect and authenticate ```text 0x8049 A5 + device name -> 0x0049 0x804B A5 -> 0x004C nonce 0x804D A5 -> 0x0004 0x8004 time + UTC offset -> (optional) ``` Session key: `sha256(nonce || authkey)[:16]`, where `authkey = sha256(random1 || random2 || secret)[:16]`. The secret is read over the shell channel (`AT GETSECRET`). Frames after authentication are AES-CBC encrypted with the fixed IV `5051525354555657606162636465665a`, PKCS#7 padding, and a CRC32-LE tail. ### 2. INIT1 ```text CMD_W: FFFF 9052 A5 -> A052 01 ``` `01` means accepted. Any other value indicates a wrong session/pairing state, and the sequence ends there. ### 3. INIT2 — on the OTA characteristic ```text OTA (ff01): FFFF 9040 -> A040 01 ``` **INIT2 on `CMD_W` reboots the watch.** With a valid session it can drop the link before the data phase. Sent directly on `ff01` it returned `A040` in ~30 ms on the reference unit. The version argument is a 4-byte little-endian-ish build value from the app; `0100005a` worked for a `1.0.0.73`-based image. It is not the AOTA header's version string. ### 4. Data phase The watch sends `A042` on `ff02`. Decrypted body: ```text offset (u32 BE) | length (u32 BE) | progress/unknown (4 bytes) | 1 byte ``` For each request, the host answers with `ceil(length / 224)` frames of `0x9042` on `ff01`. Each frame is: ```text F5 | len(u16) | FFFF | count(u16) | index(u16) | 9042 | 224B plaintext firmware | crc32le(u32) ``` `index` starts at 1 and `count = ceil(length / 224)` **for that request**. The watch may request non-sequential offsets; the host serves exactly what it asks for, and a single linear pass is not implied. ### 5. Finish — the step that is easy to miss The watch can send `A041 01` **before** the final zero-length request. `A041` is the commit prompt, and the end acknowledgement is sent immediately: ```text CMD_W: FFFF 9041 A5 ``` Waiting only for `A042 offset=0 length=0` can miss it, because the notification may arrive after `A041`; the safe client handles both and sends `0x9041 A5` on either. Skipping this leaves the staged update uncommitted in testing. ## Verified run On the reference unit, the watch requested the changed resource ranges, reported `A041 01`, accepted END and rebooted into the updated application. The requested ranges can be smaller than the complete package, so a successful transfer need not report 100% of the image served. The [recorded OTA run](/dumps/#run-logs-and-traces) provides the historical evidence. ## Client usage Follow the [firmware flashing guide](/devices/cmf-watch-pro-2/guides/ota-flash/) for package checks, pairing and transfer commands. Negotiation alone can enter the update screen; it is not a purely offline check. For virtual testing, use [emulator OTA](/emulator/ota-recovery/). ## Common failures | Symptom | Likely cause | |---|---| | `A052` but never `A040` | stale authkey / pairing state, or INIT2 on the wrong characteristic | | Link drops right after INIT2 | INIT2 was sent on `CMD_W` with a valid session | | Transfer stops with `A041` and no commit | end acknowledgement `0x9041 A5` was not sent | | `no frames for Ns` | watch rebooted, aborted, or the host lost the connection | | Requests jump around | normal; the watch requests ranges, not a linear stream | For recovery steps after a disconnect or failed boot, see [Troubleshooting](/getting-started/troubleshooting/). --- # Shell / AT channel The debug shell, AT command family and pairing/secret retrieval. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/protocol/shell/ The watch exposes a debug shell over BLE UUIDs `77d4ff01-...` (write) and `77d4ff02-...` (notify). The payload is plain text, usually terminated by `\r\n`; replies end in `,OK` or an error string. ## Identity and status | Command | Example reply | |---|---| | `AT GETVERSION` | `GETVERSION:1.0.0.73,OK` | | `AT GETPID` | `GETPID:<8 hex digits>,OK` | | `AT GETSN` | `GETSN:,OK` | | `AT GETNAME` | `GETNAME:CMF Watch Pro 2-XXXX,OK` | | `AT GETBATLV` | `GETBATLV:3850mv,OK` | | `AT GETNTCTEMP` | `GETNTCTEMP:29,OK` | | `AT GETGSENSOR` | `GETGSENSOR:X=0.38 Y=0.01 Z=0.88,OK` | | `AT GETSECRET` | `GETSECRET:<32 hex>,OK` | `GETSECRET` returns the pairing secret used by the BLE auth derivation. It has the sensitivity of a password. This repository does not include any real value. ## Factory / debug commands The shell also exposes factory and debug entry points (`ENTERFATEMODE`, `SETKNOBDUMP`, `GETFLASH`, motor/sensor setters, etc.). The full registry and app addresses are in [BLE protocol](/devices/cmf-watch-pro-2/protocol/ble/) and [app.bin internals](/devices/cmf-watch-pro-2/internals/appbin/). Some factory-menu options are destructive to app state. In particular, a shutdown/reset option cleared pairing data on the reference unit, which invalidated the stored authkey. Re-pairing is required afterwards. ## Shell usage ```bash uv run python tools/cmf_watch.py at "AT GETVERSION" uv run python tools/cmf_watch.py info ``` The `info` command reads version, serial, name, PID, battery, temperature and the accelerometer. Serial and MAC are personal data; raw output does not belong in issues or commits. ## Notes - This text command channel is distinct from the encrypted CMF command frames. The client uses it to obtain the pairing secret before establishing its session. Command availability depends on the running firmware. - `AT GETFLASH` reports flash size, but there is no general file-read command. - Firmware contains a separate UART command registry (`nand logic read/write`, `devboot`, etc.). Physical access and recovery through that interface remain unverified. Do not assume these commands are available through the BLE AT channel. --- # Watch Pro 2 support and verification What has been verified on Watch Pro 2 hardware, in the emulator, and with offline tools. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-2/status/ The reference device is Watch Pro 2 board `JX402` with stock firmware `1.0.0.73`. Physical Bluetooth tests used Windows. Offline format checks and virtual tests have their own scope. | Workflow | Verified result | |---|---| | Bluetooth pairing and device queries | The stock watch paired, established an authenticated session, and answered version, battery and motion queries. [BLE tools](/tooling/ble-tools/) | | Watch-face upload | A rebuilt face rendered on a physical watch. Deleting an installed face and uploading its replacement freed and reused the slot. [Watch-face editing and upload](/devices/cmf-watch-pro-2/guides/dial-editing/) | | Firmware and resource tools | The reference AOTA image rebuilt byte-for-byte. SDFS, RES, STY, WFDL and AJS tools were checked on the documented stock formats. A modified warm-up animation also played on hardware. [Firmware toolkit](/tooling/fwkit/) · [Animation case study](/devices/cmf-watch-pro-2/guides/bad-apple/) | | Stock firmware update | A physical watch accepted a modified AOTA package, restarted and booted the updated resources. [Firmware flashing guide](/devices/cmf-watch-pro-2/guides/ota-flash/) | | Emulator boot | Stock and custom firmware draw on the virtual display. All six stock faces rendered in Windows QEMU and the browser. Bad Apple rendered in both, and Tilt Mouse booted on Windows. [Emulator](/emulator/) | | Virtual stock OTA | The guest accepted an update and restarted. The host read the staged package from virtual NAND, installed it with modeled recovery and booted the resulting app. [Virtual OTA and recovery](/emulator/ota-recovery/) | | Actions SDK OTA | Transfer and guest-reported validation passed in QEMU. Physical transfer with the published Actions client remains unverified. [Actions SDK OTA](/tooling/actions-ota/) | | Recovery | The QEMU model restored a broken virtual app and booted stock. The equivalent physical boot path remains unverified. [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/) | Read [Firmware flashing risks and limitations](/devices/cmf-watch-pro-2/limitations/) before installing firmware on a physical watch. Watch 3 Pro results are documented in its [device profile](/devices/cmf-watch-pro-3/). --- # CMF Watch 3 Pro Firmware identity, supported workflows and research for the CMF Watch 3 Pro. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/ import InteractiveTools from '../../../../components/InteractiveTools.astro'; | Field | Reference build | |---|---| | Product | CMF Watch 3 Pro | | Board in the update package | `jx402_08` | | Stock firmware | `1.0.1.77` | | Emulator profile | `wp3-stock` | ## Work with this model | Task | Start here | |---|---| | Try stock firmware in a browser | [Open Watch 3 Pro](/emulator/watch-pro-3/) | | Test a build or a watch face | [Emulator inputs and file types](/emulator/) | | Prepare and run desktop QEMU | [First boot](/emulator/first-boot/#watch-3-pro-storage) | | Inspect the stock update | [Firmware format](/devices/cmf-watch-pro-3/formats/) and the [reference image](/dumps/#jx402_w3pro_v10177bin-stock-firmware) | | Add a device model or parser | [Device documentation and contribution map](/about/roadmap/) | ## Documentation map - [Support and verification](/devices/cmf-watch-pro-3/status/) separates offline, desktop, browser and physical results. - [Firmware format](/devices/cmf-watch-pro-3/formats/) describes the update container and application layout. - [Watch faces](/devices/cmf-watch-pro-3/watch-faces/) covers textures and custom previews. - [Hardware and emulation](/devices/cmf-watch-pro-3/hardware/) describes the modeled device interfaces. - [Testing stock firmware](/devices/cmf-watch-pro-3/testing/) provides input, sensor and passcode checks. - [Virtual OTA](/emulator/ota-recovery/#watch-3-pro-update-coverage) describes the verified update stages and remaining recovery limits. ## Verification scope The browser starts with local setup complete. This does not establish Nothing X account pairing. Physical OTA and bootloader recovery remain unverified. --- # Firmware format The 1.0.1.77 update container, application layout and stock watch-face resources. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/formats/ ## Firmware package The `jx402_08` reference package is an outer AOTA containing a nested `TEMP.bin` AOTA. The stock package verifies at the container and file levels and rebuilds byte-for-byte. The seven extracted SDFS archives also rebuild byte-for-byte. This package supplies the application and resources. Bootloader, recovery and the boot-time partition table are outside the package. ```text uv run fwkit info dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin uv run fwkit verify dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin uv run fwkit unpack dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin work/wp3-aota ``` Run these offline from the checkout after [fetching the reference image](/dumps/#jx402_w3pro_v10177bin-stock-firmware). For the command reference see [fwkit](/tooling/fwkit/). Keep WP2 assumptions out of WP3 code unless the corresponding structures have been compared. The reference package has no trailing A-GPS data. Do not require the Watch Pro 2 trailer when inspecting this build. ## Application image | Field | Stock 1.0.1.77 | |---|---| | Format and architecture | ACTH, little-endian Thumb-2 | | Load address | `0x10000000` | | Vector table offset | `0x200` | | Application size | 2,871,936 bytes | | Initial stack pointer | `0x2ff9e340` | | Reset vector | `0x10114b2d` | In Ghidra, import the extracted app as a raw binary using `ARM:LE:32:Cortex` at the load address above. File offset `0x200` maps to `0x10000200`. Clear the Thumb bit when locating the reset instruction. The binary-analysis setup in the [Ghidra guide](/contributing/firmware-analysis/) is shared; its example function addresses are for Watch Pro 2. ## Watch-face resources The reference package contains seven stock faces in `res_d.bin`. Their texture formats, import workflow and rendering checks are covered in [Watch faces](/devices/cmf-watch-pro-3/watch-faces/). --- # Hardware and emulation Watch 3 Pro stock device interfaces, optical sampling and verification boundaries. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/hardware/ The stock application boots on this project's ATS3089C QEMU model. Desktop and browser builds share the machine implementation. The model supplies a compatibility ROM and a synthetic virtual flash map. Treat the interfaces below as evidence from stock 1.0.1.77 running against that model. | Area | Evidence and implementation | |---|---| | Boot and flash | Stock looks for an ACPT table at `0x11800000` and checks the CRC over the first 740 bytes of the 744-byte table. The native provisioner stages the WP3 resources using a WP2 stock NAND writer. This describes the virtual map. | | Display and input | Stock initializes the ICNA3312 display and CST820 touch path. QEMU models touch, crown press and both rotation directions. The graphics path combines stock JPEG, GPU and display-engine operations. | | Motion | The guest uses the LSM6DSO and STK8321 paths. The virtual controls supply acceleration and angular velocity. | | Light and position | Stock queries the ambient light driver and the SYN477xx GNSS path. The GNSS model serves the stock SPI2 startup exchange and synthetic NMEA fixes. The stock factory GPS screen displayed changes to the simulated coordinates. | | Haptics and audio | The model exposes the firmware's vibration timing and plays prepared stock sound samples. Browser vibration follows host support. Desktop microphone input can be passed to the guest where the host backend supports it. | ## GH3220 optical sensor The driver uses I²C address `0x14`. The bank selector and two register address bytes are distinct. The initial identity check reads `0xaa55` from register `0x0036` in bank 1. The trim handshake writes `0x0020`, then `0x0030` to `0x0700`, and polls bit 0 of `0x0718`. | Interface | Stock behaviour | |---|---| | GPIO 22 and status `0x0508` | Wear on and off use status bits `0x0400` and `0x0800`. The guest acknowledges status by writing set bits back. | | FIFO count `0x050a`, burst selector `0xaaaa` | The count is in 32-bit words. Each big-endian word carries a five-bit channel tag in bits 31–27 and a 24-bit ADC sample in bits 23–0. | | Channel selection | `0x0108` selects active slots. Slot configuration at `0x010a + slot × 0x1c` selects the phases included in a frame. | In raw-sample mode the emulator feeds a synthetic waveform into the FIFO and the firmware calculates both measurements. Stock showed both readings in browser and desktop histories. On desktop, stock reloaded the timestamped records from the same virtual NAND after a stock flush and a QEMU reset. Browser page-reload retention was not established. ## Test scope The [verification matrix](/devices/cmf-watch-pro-3/status/) records desktop, browser and physical limits separately. Use [Testing stock firmware](/devices/cmf-watch-pro-3/testing/) for repeatable control and measurement checks. These modeled interfaces do not establish physical sensor accuracy, radio behavior or bootloader recovery. --- # Watch 3 Pro support and verification Results for stock firmware 1.0.1.77, separated by offline, desktop, browser and physical testing. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/status/ These results apply to stock firmware **1.0.1.77**, board **jx402_08**. Desktop results below used Windows. A passing emulator test establishes behavior with simulated hardware, not physical device compatibility. ## Firmware and display | Area | Verified result | Limit | |---|---|---| | Package tools | Reference AOTA and seven SDFS archives rebuilt byte-for-byte. | Changes need their own checks; parser success does not prove boot. | | Stock boot | Desktop and browser reach the launcher and accept touch and crown input. | The emulator supplies a compatibility ROM and prepared storage. | | Browser storage | The hosted emulator completed an automatic save, restored it after closing and reopening the tab, and reached the stock UI. | Retention of specific passcodes and optical history was not part of this test. | | Stock faces | All seven normal stock faces and picker transitions were checked in Windows QEMU and the browser. | Always-on variants and every animation state were not covered. | | Custom app | Browser application and package imports booted test images; desktop booted an installed graphics test app. | Use an image built for the selected model. | | Passcodes | Browser tests covered numeric and gesture setup, off-wrist locking, rejected wrong entries and successful unlock. | Browser reload retention remains unverified. | ## Sensors, sound and factory tests | Area | Recorded result | Limit | |---|---|---| | Touch | Desktop drawing and touch-grid tests responded to simulated input. | Does not establish physical touch-controller timing. | | Crown | Desktop factory encoder test accepted presses and both rotation directions. | Full matched desktop/browser factory coverage is incomplete. | | Motion | Desktop level, tilt and gyro tests responded to supplied values. | No physical calibration or sensor-noise validation. | | Light | Desktop stock test displayed supplied lux and recorded a pass. | Shared controls alone do not establish identical browser results. | | GPS | Desktop stock factory screen updated between simulated coordinate pairs. | No satellite acquisition or radio test. | | Optical | Stock calculated heart rate and blood oxygen from raw synthetic samples and displayed history on desktop and browser. | Retention of optical history across a browser reload remains unverified. | | Speaker and microphone | Desktop speaker/aging tests captured non-silent output; Windows microphone capture supplied PCM to the guest. | No completed four-hour aging run or complete browser microphone parity. | | Motor | Desktop stock motor tests produced logged on/off transitions. | Browser vibration strength depends on the host device. | The factory screens include operator-selected PASS buttons. A manually selected PASS is not an independent hardware measurement. Full, partial and finished-unit sequences, manufacturing radio modes and extended aging still need complete runs. ## Updates and recovery A small app-and-resources package completed stock virtual Bluetooth transfer, validation and reboot. The host installed the captured payload into virtual flash, and the resulting app rendered. See [OTA coverage](/emulator/ota-recovery/#watch-3-pro-update-coverage) for the distinction between guest validation and the host installer. Full stock resource updates, interrupted-update recovery and automatic payload extraction from arbitrary Watch 3 Pro NAND snapshots remain unverified. Physical OTA, physical bootloader recovery and end-to-end Nothing X pairing are not established by these tests. Local setup that opens the watch face is not account pairing. --- # Testing stock firmware Repeatable Watch 3 Pro checks for inputs, simulated sensors and passcodes. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/testing/ Use stock 1.0.1.77 with profile `wp3-stock`. Start with the [browser emulator](/emulator/watch-pro-3/) or prepare desktop storage using [First boot](/emulator/first-boot/#watch-3-pro-storage). Keep each run's log and selected input values. The [status page](/devices/cmf-watch-pro-3/status/) distinguishes existing results from tests that still need coverage. ## Display and controls Open the app list with a short crown press. Scroll in both directions using the crown, then repeat using touch. Open an app and return to the face. Hold the face to open its picker and check the selected face after leaving the picker. For graphics changes, repeat with all seven stock faces. ## Simulated sensors The browser groups inputs under **Simulation**. The desktop viewer uses **Advanced**. Change one input at a time while the corresponding stock screen is measuring; merely changing a host control does not prove that stock read it. | Input | What to observe | |---|---| | Orientation and gyro | Level, tilt or angular values should follow the supplied motion. | | Ambient light | The light test should respond to a changed lux value. Lux measures illumination. | | GPS | Start a stock mode using the receiver, then compare the displayed fix with the supplied coordinates. | | Battery and charger | Set **Battery level** in the browser and compare it with the stock percentage. Toggle the charger separately and check the charging indicator. | | Optical samples | Enable raw samples and worn state, then start a stock measurement. | For optical tests in the browser, enable **Simulate optical sensor signals** and **Watch is worn** under **Optical sensors**. Open Heart rate or Blood oxygen and allow stock to calculate a result. Check the history screen separately. **Set measurement results** supplies values directly for display tests, which does not test the raw-sample calculation. See [optical interfaces](/devices/cmf-watch-pro-3/hardware/#gh3220-optical-sensor) for the driver-level behavior. ## Passcodes In stock **Settings → Passcode**, create a disposable numeric code or gesture. Enable off-wrist detection, return to the face with **Watch is worn** on, then turn it off. Verify that stock locks, rejects an incorrect entry and accepts the correct one. Repeat independently for the other passcode type. Browser reload persistence is a separate test, not part of this unlock check. ## Record failures Save the watch log before resetting. Include the exact interaction and whether sound or controls still worked after the display failed. Keep desktop and browser results separate. See [Troubleshooting](/getting-started/troubleshooting/) for connection, file and startup problems. Tests here run in virtual storage and do not require flashing a watch. --- # Watch faces Watch 3 Pro stock textures, custom face previews and checks for rendering changes. URL: https://cmf.arnv.dev/devices/cmf-watch-pro-3/watch-faces/ Watch 3 Pro reference firmware 1.0.1.77 contains seven stock `.wfc` faces in `res_d.bin` (file ID 13). These are distinct from the Watch Pro 2 WFDL examples. Select Watch 3 Pro when exporting or browsing community faces. ## Preview a face The [FMC catalog](https://fmc.tools) provides community faces. In the [browser emulator](/emulator/watch-pro-3/), open **FMC watch faces**, choose a face and select **Apply watch face**. For a file on your computer, stop the virtual watch, choose the file under **Watch face**, and start it again. Applying a face starts a new session with Duskscape replaced in virtual storage. **Hard reset to stock** restores the bundled starting state. For desktop, complete [First boot](/emulator/first-boot/#watch-3-pro-storage). List community faces with: ```text uv run cmf-watch-utils emu faces --profile wp3-stock ``` Add `--fmc-face ID` to your stock run command using an ID from that list, or add `--watch-face FILE` with your local file path. These preview operations modify virtual storage; they do not upload to a physical watch. ## Texture formats A face contains images used for backgrounds, numbers and hands. Some stock images store RGB565 color with a separate alpha channel for transparency. Others use ETC2/EAC block compression. The QEMU renderer decodes these formats when the stock application draws them. Vive Lite and BriqBot exercise ETC2/EAC decoding. CitrusDash exercises filtered alpha images and clipping, where drawing is restricted to a path. The generated `wfc-index.txt` identifies packed stock textures; keep it with the matching storage files. Missing or mismatched metadata can produce striped or corrupted images even when the face otherwise loads. ## Check a rendering change Compare both the stock picker preview and the selected face. They use different drawing paths. Check hands, digits, transparency and edges, then switch to another face and back. Record the firmware, runtime version, selected face and screenshot. All seven normal stock faces were checked on Windows and in the browser. Always-on variants and complete animation timing remain outside that result. A rendered preview does not establish that a face fits or installs on hardware. See [verification status](/devices/cmf-watch-pro-3/status/). --- # Data index Manifests, downloadable firmware images and redacted notes published with this project. URL: https://cmf.arnv.dev/dumps/ This section holds the artifacts behind the research: firmware images, manifests with hashes and structure, and redacted notes. ## Downloadable images The repository stores the images with Git LFS. Follow [Setup](/getting-started/setup/) to fetch a specific file, or use a direct download below. A tools-only checkout can leave the LFS files as pointers. ### `JX402_V1.0.0.73.bin` (stock factory firmware) - Size: 56,903,752 bytes - SHA-256: `30903fc8ce6db4f8860bb554366635db3d2bcbb2d43827b3b50fbbac22b59353` - Contents: the unmodified image shipped for the CMF Watch Pro 2 (`JX402`), firmware 1.0.0.73 - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/firmware/JX402_V1.0.0.73.bin) · [manifest](https://github.com/fmctools/cmf-watch-utils/blob/main/dumps/manifests/firmware-1.0.0.73.json) ### `JX402_w3pro_V1.0.1.77.bin` (stock firmware) - Board and version: `jx402_08`, `1.0.1.77` - Size: 45,069,312 bytes - SHA-256: `cf381188eb5fe26a14047a03697e68b58785bdcd01c4baf8703d4624650c6352` - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin) · [Device profile](/devices/cmf-watch-pro-3/) ```text git lfs pull --include=dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin --exclude="" ``` ### `JX402_V1.0.0.57.bin` (rollback target) - Size: 56,065,096 bytes - SHA-256: `cd4574f1f9fa31106e3a0490a12069adf5a99c59cf0e4d7f52d58be60cd55716` - Contents: firmware 1.0.0.57 for the same board, rebuilt from extracted parts - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/firmware/JX402_V1.0.0.57.bin) · [manifest](https://github.com/fmctools/cmf-watch-utils/blob/main/dumps/manifests/firmware-1.0.0.57.json) ### `JX402_V1.0.0.73_badapple9.bin` (rebuilt proof of concept) - Size: 54,117,960 bytes - SHA-256: `4933e593d14bef6f013db5f6d0a9760e36aaff63f052cf83a2dc54696ccff1ff` - Contents: historical stock animation experiment, replacing a sport warm-up in `res_e`. This is separate from the source-built [Bad Apple firmware](/devices/cmf-watch-pro-2/guides/bad-apple/). - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/firmware/JX402_V1.0.0.73_badapple9.bin) ### `app_073.bin` (application image for 1.0.0.73) - Size: 2,465,920 bytes - SHA-256: `30e7978c39d8fb79b825c7ebf69b4377d214e9cc6739a52f06dbb5ff7f13b490` - Contents: `app.bin`, extracted from the `TEMP` partition of the 1.0.0.73 image - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/app/app_073.bin) ### `app_057.bin` (application image for 1.0.0.57) - Size: 2,445,440 bytes - SHA-256: `26fbe34c10343949fec53575021e8ab559e33aff13b6efa9974a34ae33ca1399` - Contents: `app.bin`, extracted from the `TEMP` partition of the 1.0.0.57 image - [Download](https://media.githubusercontent.com/media/fmctools/cmf-watch-utils/main/dumps/binaries/app/app_057.bin) From an existing checkout, fetch just the application image: ```bash git lfs pull --include="dumps/binaries/app/app_073.bin" ``` The proof-of-concept image contains third-party animation frames. See [Legal and attribution](/about/legal/) for licensing and redistribution boundaries. ## Manifests [`manifests/firmware-1.0.0.73.json`](https://github.com/fmctools/cmf-watch-utils/blob/main/dumps/manifests/firmware-1.0.0.73.json) records the size, SHA-256, header fields and per-entry CRC status of the stock image, plus the published binaries. It serves as the reference for checking that a locally obtained image matches the structure the tooling was written against: ```bash 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 ``` ## Structural facts Stock image `1.00_2509131556`, board `jx402_01_3089c`, 56,903,752 bytes: | Entry | Offset | Stored | Raw | Notes | |---|---|---|---|---| | `ota.xml` | 0x400 | 1,832 | – | version and board metadata | | `TEMP.bin` | 0xC00 | 1,317,084 | 2,492,928 | contains `app.bin` | | `res.bin` | 0x142600 | 6,978,004 | 10,137,792 | RES string and picture pools | | `fonts.bin` | 0x7EA000 | 7,813,200 | 9,513,344 | fonts | | `res_e.bin` | 0xF5DA00 | 39,237,168 | 58,777,088 | SDFS with the `.ajs` animations | | `sdfs_k.bin` | 0x34C9200 | 310,872 | 524,096 | system data | Every partition is derivable from the image: ```bash uv run fwkit unpack dumps/binaries/firmware/JX402_V1.0.0.73.bin work/aota ``` ## Rollback target The `1.0.0.57` image is a reconstructed older reference for offline comparison. It is not a verified physical downgrade or recovery procedure. It carries the same board string (`jx402_01_3089c`) and the same partition layout as the `1.0.0.73` image, and its application reports `1.0.0.57`. | Property | Value | |---|---| | AOTA version string | `1.00_2408181820` | | Size | 56,065,096 bytes | | SHA-256 | `cd4574f1f9fa31106e3a0490a12069adf5a99c59cf0e4d7f52d58be60cd55716` | | Provenance | Rebuilt from the unpacked parts with `tooling/rebuild_aota.py`; the header CRC and every entry CRC match the recorded metadata, and the result is byte-identical to earlier local rebuilds of the same image | | Manifest | [`manifests/firmware-1.0.0.57.json`](https://github.com/fmctools/cmf-watch-utils/blob/main/dumps/manifests/firmware-1.0.0.57.json) | Two caveats apply. The image is a reconstruction from extracted parts rather than a vendor download, and the hardware downgrade remains unverified. Use the offline check below to inspect the archive. See [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/) for the limits of using an older image as a recovery target. ```bash uv run fwkit verify dumps/binaries/firmware/JX402_V1.0.0.57.bin ``` The version argument of INIT2 is a build value used by the updater, not the version string of the image. The value that worked for `1.0.0.73` is `0100005a`. ## Analysis output | Path | Contents | |---|---| | `analysis/functions.txt` | Every function found in `app.bin` with its address range | | `analysis/function_map.tsv` | Function list with the size and flags used during the analysis | | `analysis/strings.txt` | String table of the application image | | `analysis/string_xrefs.txt` | Cross-references from strings to code | | `analysis/blocks.txt` | Block inventory | | `analysis/decomp/` | 231 decompiled function listings produced by the Ghidra scripts | | `analysis/ghidra/` | Run logs of the Ghidra analysis sessions | These files carry the knowledge extracted from the application image. They are regenerated with the scripts under `tooling/ghidra_scripts/` against `dumps/binaries/app/app_073.bin`. ## Run logs and traces | Path | Contents | |---|---| | `logs/ota_badapple9.log` | The OTA client log of the successful transfer, up to the commit prompt | | `logs/ota_badapple9b.log` | The follow-up transfer that carried the end acknowledgement | | `logs/ota_py.log`, `logs/ota_mod.log`, `logs/ota_mod3.log`, `logs/ota_pwned.log` | Earlier attempts, including the failed ones | | `traces/sync_frames.json` | Captured notification frames used to map the protocol | Device identifiers, the pairing secret and the authkey are replaced with placeholders in every published log. The redaction tool is `tooling/redact.py`; it reads the identifiers from a local, git-ignored map (`internal/redactions.json`) so that the values themselves are never committed. ## Samples | Path | Contents | |---|---| | `samples/bt_watch.sty` | A STY scene bundle, extracted from the resource partition | | `samples/watchfaces/wf1.bin` | A WFDL watch-face package, the sample used in the dial editing guide | | `samples/*.png` | Pictures decoded from the picture resources, showing the codecs in output | ## Redacted notes - [`ota-flash-run.md`](https://github.com/fmctools/cmf-watch-utils/blob/main/dumps/ota-flash-run.md) — the shape of a successful flash log with device identifiers removed. ## Personal data The logs use placeholder identifiers. Keep raw captures and device-owned identifiers out of documentation changes. The firmware manifests identify builds with file hashes. --- # Watch emulator What the QEMU preview supports and where to start. URL: https://cmf.arnv.dev/emulator/ import InteractiveTools from '../../../components/InteractiveTools.astro'; The emulator runs stock CMF Watch Pro 2 and Watch 3 Pro firmware on your computer. Both profiles support custom application boots. Desktop virtual OTA has model-specific test coverage described in [OTA and recovery](/emulator/ota-recovery/). ## Browser preview For step-by-step instructions, start with [Use the browser emulator](/emulator/browser-guide/). Open either model in a recent desktop version of Chrome or Edge. Stock firmware starts automatically. Select the model name above the virtual watch to switch. - [Watch Pro 2](/emulator/watch-pro-2/) supports stock firmware, custom builds, the Bad Apple preset, and the FMC watch-face catalog. - [Watch 3 Pro](/emulator/watch-pro-3/) opens the stock watch face on firmware `1.0.1.77`, with the charger disconnected and the display kept awake. Use **Watch color** to switch cases or **Custom firmware** to load an AOTA with application and SDFS images or raw Watch 3 Pro files. Desktop QEMU can boot to first-time setup for QR testing. End-to-end Nothing X pairing remains unverified on Watch 3 Pro. ### Display, audio and inputs The first boot downloads the virtual storage and can take a moment. **Watch log** shows the guest's progress. **Motor log** shows when the virtual watch vibrates, including its duty cycle and frequency. On browsers that support vibration, **Watch vibration** replays the pulse timing on your phone after you interact with the page. Your phone controls the strength and feel of each pulse. Use the touchscreen and crown, change brightness, or simulate battery, motion, GPS and optical sensor readings. Stock starts at the highest manual brightness in the watch's own settings. The browser brightness slider adjusts the rendered display separately. The virtual speaker is on by default. If your browser blocks autoplay, tap or click the emulator to start audio. Use **Watch sound** under **Simulation → Config** to mute it. If the virtual watch runs slowly, audio stretches to keep pace while preserving pitch. The stock preview plays the built-in ACT sounds through the virtual speaker. You can preview a ringtone by changing the volume in the watch’s **Sounds** settings. Bluetooth call audio requires additional DSP support. **Battery level** sets the reported percentage in stock firmware. With a custom app, the slider changes the simulated battery voltage and the app decides how to report it. ### Watch faces and custom firmware **Simulation → Config** caches downloads and automatically saves the virtual watch's storage by default. Reopen the same setup to restore its last save. See [browser storage controls](/emulator/browser-guide/#save-data-in-the-browser) for the separate cache, settings and watch storage options. Choose **Display test** from **Boot preset** to run a bundled custom firmware. Press the crown to change the pattern’s color. **Hard reset to stock** discards the running session and boots stock again. Under **Custom firmware**, **Advanced boot files** lets you supply a different virtual NAND image or override the prepared base files. Use the camera button to save the circular display as a transparent PNG. Turn on **Include frame in screenshots** under **Display** to include the case. Open **FMC watch faces** to browse the [FMC](https://fmc.tools) catalog for the selected model. Search by title or creator and sort by newest, most downloaded, or most flashed. Choose a face, then select **Apply watch face** to install it at boot. Applying restarts a running watch. To use a local face file, stop the watch, select the file under **Watch face**, and start it again. To try your own build, select **Custom firmware**, then select an AOTA for the active model under **Firmware package**, or select the application and companion SDFS separately under **Raw application files**. On Watch Pro 2, select **Bad Apple** from **Boot preset** to run the bundled demo. For an example of a custom Zephyr application, see the [Bad Apple source](https://github.com/fmctools/firmware-wp2-badapple) and [case study](/devices/cmf-watch-pro-2/guides/bad-apple/). For Bluetooth OTA and recovery tests, use desktop QEMU. Both browser models offer the FMC firmware and watch-face catalogs. Watch Pro 2 also supports compatible FMC apps through **Apps firmware**. Use the share button to copy the catalog selections. Follow the [app and share guide](/emulator/browser-guide/#installable-apps-from-fmc). On phones and devices that report limited memory, the browser limits display updates to about 30 fps to reduce work. The watch firmware still runs in software, so boot times and animation speed depend on the host device. The bundled Bad Apple preset uses a clock setting tuned for playback. Use a custom firmware boot or desktop QEMU for tests that depend on guest timing. ### Watch 3 Pro passcodes and optical measurements In **Simulation → Optical sensors**, enable **Simulate optical sensor signals** and **Watch is worn**. Open **Heart rate** or **Blood oxygen** in the virtual watch to measure a repeating test pulse with the stock app. **Set measurement results** supplies values directly for UI tests. For a passcode test, open **Settings → Passcode** on the virtual watch and set a numeric or gesture passcode. With **Off-wrist detection** enabled, return to the face with **Watch is worn** on, then switch it off to lock. Enter the test passcode to unlock. Both flows are verified on the hosted preview. Use a disposable test code. Retention across a browser reload is unverified. ### Base firmware files The browser includes the stock files needed to boot. Use **Advanced boot files** when your test needs a different starting image. The emulator uses its bundled version for each file you leave out. | File | What it does | |---|---| | `app.bin` | Stock application used when booting stock. A custom app is selected through the main firmware inputs. | | `nor.bin` | The small flash image containing boot parameters and application partitions. Custom app and resource files are placed in this image. | | `nand-defaults.bin` | The larger flash image containing resources and settings. **Virtual NAND** supplies a replacement for this file. | | `compat.bin` | The emulator's compatibility ROM, which provides the services the watch app expects at boot. | | `nand-id.bin` | The chip identification table used by the NAND driver. | | `wfc-index.txt` | Texture information used to render stock watch faces. | | `stock-audio.bin` | Prepared stock ringtone, alarm and prompt samples for the virtual speaker. | ## Desktop emulator | Page | What you will do | |---|---| | [Installation](/emulator/installation/) | Install the command line tools, download the QEMU and ROM archives, and check the host libraries. | | [First boot](/emulator/first-boot/) | Create the virtual storage from the reference firmware, boot stock, and open the watch window. | | [OTA and recovery](/emulator/ota-recovery/) | Transfer an update over simulated Bluetooth and check the installed app after reboot. | Run `uv run cmf-watch-utils emu faces --search "LCD" --sort downloads` to browse FMC from the desktop CLI. Copy the face's `id` and add `--fmc-face ID` to your stock `emu run` command. For a file on your computer, use `--watch-face FILE`. These replace Activity Mood on Watch Pro 2 or Duskscape on Watch 3 Pro. For Watch 3 Pro, pass `--profile wp3-stock` to both `emu faces` and `emu run`. ## Profiles | Profile | Where the watch starts | |---|---| | `wp2-stock` | Stock firmware `1.0.0.73`, after language selection. Start here. | | `wp2-onboarding` | The same firmware, at first-time setup. | | `wp3-stock` | Watch 3 Pro stock `1.0.1.77`. Native fixtures can boot to first-time setup. | Use the Watch Pro 2 profiles only for board JX402. They share the same virtual hardware and use different starting storage. ## Scope The preview has booted stock, Bad Apple, and Tilt Mouse on Windows. Watch Pro 2 virtual recovery can restore a broken app in QEMU. Real-watch bootloader behavior, electrical faults, and recovery after power loss remain outside that test. See [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/). --- # Use the browser emulator Start a virtual watch, save its storage, load watch faces, firmware or apps, and share a setup. URL: https://cmf.arnv.dev/emulator/browser-guide/ import InteractiveTools from '../../../components/InteractiveTools.astro'; The browser emulator runs a virtual watch. Its controls and uploaded files change that virtual watch, not a physical watch nearby. Stock firmware and the files needed for the first boot are included. ## Start a watch 1. Open [Watch Pro 2](/emulator/watch-pro-2/) or [Watch 3 Pro](/emulator/watch-pro-3/) in a recent desktop Chrome or Edge. 2. Wait for the initial download and startup. **Watch log** shows progress. The stock watch face should appear without pairing with Nothing X. 3. Click and drag on the display to tap and swipe. Use the round crown control for a press and the adjacent scroll control for rotation. The model name above the watch switches to the other model's page. Choose the model your files were made for. If startup fails, follow [browser troubleshooting](/getting-started/troubleshooting/#the-browser-emulator-freezes-goes-black-or-has-broken-audio). ## Save data in the browser **Simulation → Config** separates three kinds of local storage: - **Cache downloads** keeps downloaded firmware, app packages, watch faces and emulator files for reuse. It is enabled by default. Clearing the download cache does not erase saved watch data. The cache is limited to 256 MB; older entries are removed as needed. - **Remember settings** retains simulation controls, sound and appearance choices separately for each watch model. It is enabled by default. Uploaded files must be selected again. - **Automatically save watch storage** preserves the virtual watch’s NOR and NAND flash, including settings, installed apps and history that its firmware has written. It is enabled by default and can be turned off. Saves are separated by model and the contents of the selected firmware, resources and apps; a different selection starts with its own storage. With automatic saving enabled, the emulator saves once stock is ready, after interactions settle and every 15 seconds while visible. It also attempts a save when the page becomes hidden, and finishes a save before **Stop**, model changes and firmware switches. Reopening the same firmware restores its saved storage automatically. **Save now** is an optional shortcut. The save status shows when the latest checkpoint finished. An abrupt tab closure, browser crash or power loss can interrupt a pending save; changes since the last completed checkpoint may be lost. This is a flash checkpoint, not a suspended CPU session: the watch boots again when reopened, and changes the firmware has not written to flash are not included. Cached files avoid repeat downloads. They do not eliminate firmware boot time, decompression or emulator startup. Switching models does not copy one model’s saved storage to the other. A share link contains selections, not your saved watch data or local uploads. **Protect saved data** asks your browser to keep this site's saves and downloads when disk space runs low. The browser may decline. Clearing site data still removes the files, even if the browser granted protection. **Clear saved data** has separate controls for downloaded files, remembered controls and all saved watch storage for the current model. Clearing saved watch storage does not interrupt the running watch; restart it to use fresh storage. **Hard reset to stock** discards the current saved state and starts a fresh stock watch. ## Simulate hardware inputs ### Battery The battery slider sets the percentage reported by supported stock firmware. This is a testing override, not a battery-discharge model. Custom firmware uses the simulated voltage and its own battery driver instead. ### Optical sensors Under **Optical sensors**, **Set measurement results** supplies the chosen heart-rate and blood-oxygen values directly. On Watch 3 Pro, turn on **Simulate optical sensor signals** and **Watch is worn** to send a repeating test pulse to the stock sensor driver. Open Heart rate or Blood oxygen on the watch and let the firmware calculate the result. Turn off signal simulation to enter exact values again. ### Orientation and rotation Under **Simulation → Orientation**, drag the small watch model or focus it and use the arrow keys. Its tilt sets the gravity readings supplied to the watch. On Watch 3 Pro, **Follow model movement** also produces gyroscope readings while the model rotates. These readings describe rotation speed in degrees per second, not the angle of the watch. They return to zero when movement stops, even if the watch remains tilted. Disable this option to enter constant X, Y and Z rotation rates for a sensor test. The model gesture controls tilt; manual Z input also allows tests of rotation around the face's perpendicular axis. ## Try a watch face A watch face changes the clock screen. It is different from a firmware package, which contains application code and possibly resources. 1. Open **FMC watch faces**. [FMC](https://fmc.tools) is the community watch-face catalog. 2. Search by name or author, or change the sort order. 3. Select a face and choose **Apply watch face**. The virtual watch restarts to load it; this restart is expected. 4. Check the selected face after startup. If the previous face is still selected, hold the watch display to open the stock face picker and inspect its choices. For a downloaded face, choose the file under **Watch face**, then use **Apply and restart** (or **Boot selection** if the watch has not started). Use a face intended for the selected model. A successful preview does not guarantee installation on hardware. ## Load custom firmware First read the download's description. The `.bin` extension alone does not tell you what a file contains. If the author does not identify its model and file type, ask before choosing an input. | Download | Input to use | |---|---| | AOTA firmware/update package | **Firmware package** | | Raw application, usually `app.bin` | **Raw application files → Application image** | | Companion resources, usually `sdfs.bin` | **Raw application files → Application resources**, alongside its matching app | | Watch face (`.wfdl`, `.wfc`, or a face distributed as `.bin`) | **Watch face** | | Prepared virtual NAND storage | **Advanced boot files → Virtual NAND**, only when the build's instructions require it | 1. Select **Custom firmware** under **Boot preset**. 2. Choose either the package or the raw application files. Clear selections from a previous experiment using the file input's remove control. 3. Keep bundled base files unless the build instructions explicitly require replacements. A normal custom-app preview does not require you to upload every file in **Advanced boot files**. 4. Choose **Apply and restart**, or **Boot selection** if the watch has not started. Check for the application's expected screen and inspect **Watch log** if it fails to start. Use application resources from the same build when supplied. An application may start but display missing or broken graphics if its resources do not match. For Watch Pro 2, the **Bad Apple** preset provides a ready-made example without building or downloading it yourself. This workflow loads the selected application into virtual storage and boots it. It does not test Bluetooth transfer or the update installer. Use [desktop OTA testing](/emulator/ota-recovery/) for those stages. ## Installable apps from FMC The [FMC app store](https://fmc.tools/apps) also distributes `.wp2app` packages. These are different from a raw `app.bin` or an AOTA firmware update. They need the matching patched Watch Pro 2 firmware and App Loader. Do not put them in **Application image** or **Firmware package**. 1. Select **Apps firmware** under **Boot preset**. 2. The compatible patched firmware and App Loader are selected automatically. Their names and versions appear above the app list. 3. Choose an app from **FMC apps** and click **Add selected app**, or select one or more local `.wp2app` files under **Add apps**. Up to eight apps fit in the loader's slots. Each selected file has a **Remove** control. 4. Choose **Apply and restart**, or **Boot selection** if the watch has not started. The browser downloads the firmware and loader, checks the packages, and installs them into virtual storage before booting. 5. Open **Apps** in the watch's menu and select an installed app. The browser prepares the virtual storage automatically. With automatic saving enabled, reopening the same firmware, loader and app selection restores the last saved storage. Catalog apps can be reselected from the session URL. **Apply and restart** keeps selected local files through that restart using temporary browser storage. An ordinary reload or a new tab still requires selecting local uploads again. This profile currently supports Watch Pro 2. Watch 3 Pro shows an unavailable message because no compatible patched firmware and loader are configured. The [CMF Watch SDK](https://github.com/fmctools/cmf-watch-sdk) describes app development. The [community apps repository](https://github.com/fmctools/apps) contains sources and publishing instructions. ### Share a configured session Opening a configured link starts the watch with those selections. Boot inputs are temporarily locked while loading, then become editable. Change the files or app list and choose **Apply and restart** to use the new selection. Catalog selections update the page URL. **Share session** copies a link to the selected firmware, loader, apps and watch face. Local uploads cannot be included; recipients must select those files themselves. The link recreates the boot configuration, not the running watch's memory or saved settings. The firmware catalog remains available while emulation runs. **Use selected firmware** restarts the virtual watch when necessary to apply the selection. Append FMC record IDs to the model page's URL: | Parameter | Selection | |---|---| | `watchface=` | A watch face for that model | | `firmware=` | One firmware catalog record | | `loader=` | One compatible App Loader record | | `app=` | An app; repeat this parameter for multiple apps | For example, `/emulator/watch-pro-2/?app=pyccglfsfijw463` loads Orbit and selects the compatible firmware and loader automatically. Add `&app=m00yj6hopd9a0zs` to include Sky Hop. Selections appear in the corresponding controls before startup. An explicit firmware or loader replaces that automatic selection and must be compatible with the apps. IDs refer to catalog records, not immutable releases: the files behind a record can change when its author updates it. Invalid IDs, incompatible models and unsupported combinations produce an error rather than silently booting stock. Firmware packages with resources that differ from the bundled base require matching virtual storage; selecting a catalog entry does not make every firmware version compatible. **Hard reset to stock** clears URL selections as well. ## Return to stock Save **Watch log** before discarding a failed experiment. **Hard reset to stock** returns the virtual watch to the bundled starting state; it can discard virtual settings and installed content. It does not restore a physical watch. For a screenshot, use the camera control. **Include frame in screenshots** under **Simulation → Display** controls whether the case appears in the image. --- # First boot Create the watch's virtual storage, boot stock firmware, and open the viewer. URL: https://cmf.arnv.dev/emulator/first-boot/ Complete [Installation](/emulator/installation/) first. The commands use paths relative to the checkout. On Windows, use `runtime/qemu-system-arm.exe` and add `--runtime-dir` with the path to your MSYS2 `ucrt64/bin` folder. On Ubuntu, use `--gdb gdb-multiarch`. ## Watch Pro 2 storage QEMU needs files that stand in for the watch's storage. They contain the app, its fonts and images, and the language setting. These prepared storage files are called **fixtures** in the CLI. Creating them only writes files on your computer; it does not connect to or modify a physical watch. The CLI uses the reference firmware to create these files on your computer. 1. Download the pinned SDK [NAND ID file](https://raw.githubusercontent.com/lvgl/lv_port_actions_technology/26f51e584940d5b141cd1d09d2629d69b595f579/action_technology_sdk/zephyr/tools/prebuilt/leopard/common/bin/nand_id_all.bin) and save it as `runtime/nand_id_all.bin`. It tells the stock driver which kind of flash chip the emulator presents. You only need that one SDK file. 2. Install an Arm debugger. On Windows, use an Arm GNU Toolchain distribution containing `arm-none-eabi-gdb.exe`. Add its `bin` folder to PATH or pass the full path in quotes after `--gdb`. Run `arm-none-eabi-gdb --version` to check it. The debugger is used here to start the storage setup inside QEMU. 3. Leave at least 250 MiB free on the drive. Run this from the checkout: ```text uv run cmf-watch-utils emu prepare-fixtures --fixtures fixtures --stock dumps/binaries/firmware/JX402_V1.0.0.73.bin --nand-id runtime/nand_id_all.bin --qemu runtime/qemu-system-arm --rom runtime/compat.bin --provisioner runtime --gdb arm-none-eabi-gdb ``` The command prints where it saved the storage files and logs. The `fixtures` folder should contain `nor.bin`, `nand-id.bin` and `nand-defaults.bin`, plus `wfc-index.txt` for stock texture decoding. Keep them together for future runs. If older fixtures show corrupted watch-face graphics, prepare a fresh directory with the current CLI to generate the texture index. ## Watch 3 Pro storage Fetch both stock packages from the [data index](/dumps/). Watch 3 Pro supplies the guest files. Watch Pro 2 supplies the virtual NAND writer. Use the same ROM, NAND ID file and debugger as above. ```text uv run cmf-watch-utils emu prepare-fixtures --profile wp3-stock --fixtures fixtures-wp3 --stock dumps/binaries/firmware/JX402_w3pro_V1.0.1.77.bin --provisioning-stock dumps/binaries/firmware/JX402_V1.0.0.73.bin --nand-id runtime/nand_id_all.bin --qemu runtime/qemu-system-arm --rom runtime/compat.bin --provisioner runtime --gdb arm-none-eabi-gdb ``` Add `--profile wp3-stock` and substitute `fixtures-wp3` for `fixtures` in the commands below. Keep `wfc-index.txt` beside the flash files. Native stock fixtures can show the language screen. The [browser preview](/emulator/watch-pro-3/) starts at the face. With the current desktop CLI, add `--watch-face-preview` to the Watch 3 Pro stock run for the same starting screen. This completes local setup for testing; it does not perform Nothing X account pairing. ## Headless boot First run without opening a window. This checks that the virtual watch starts and draws something: ```text uv run cmf-watch-utils emu run --fixtures fixtures --qemu runtime/qemu-system-arm --rom runtime/compat.bin --headless --output runs/first-boot ``` Look for `"panel_frame_captured": true` in the output. QEMU saves a screenshot as `runs/first-boot/frame.ppm` and its result as `report.json`. ## Open the viewer Run again with a new output folder: ```text uv run cmf-watch-utils emu run --fixtures fixtures --qemu runtime/qemu-system-arm --rom runtime/compat.bin --output runs/first-window ``` The window title shows the selected model. For the first-run language screen, repeat the storage preparation with `--profile wp2-onboarding`, then add that flag to your boot command. Every boot command needs a new output folder. Use a different name to keep older results. Windowed runs select an available speaker backend automatically. Use `--audio none` for a silent window. To record the speaker output to `audio.wav` without opening a window, run with `--headless --wav`. Add `--host-mic` to a windowed run to let guest microphone capture use your computer's default audio input. Capture starts when the guest starts recording and stops when it stops or restarts. The host audio backend and microphone permissions determine whether input samples are available. The guest receives silence when host capture is disabled or there are no samples ready. Use `--allow-reboot` to follow the stock firmware through a restart. The factory menu's DUT confirmation and Exit Factory actions both restart the watch. In stock firmware, **Advanced → Ambient light (lux)** sets the simulated ambient light (the range depends on the profile). In the browser, use **Simulation → Ambient light**. The factory light test displays the simulated value after you start the measurement. The vibration motor is not felt, but its drive is logged. Each change is a line in `motor.log` in the output folder: virtual milliseconds, duty in tenths of a percent and PWM frequency in hertz, with `0 0` meaning off. The window shows the current state next to the firmware version. ## Custom firmware Use `--app local/app.bin` to start an app you built. Add `--sdfs local/sdfs.bin` if it needs a matching resource archive. Use `--ota-image local/update.bin` to extract the app and resources from a supported update and boot them directly. That direct boot checks whether the app starts and renders. Use [OTA and recovery](/emulator/ota-recovery/) to test transfer and installation. ```text uv run cmf-watch-utils emu preflight --image local/update.bin ``` For Watch 3 Pro, add `--profile wp3-stock` to the preflight command too. Preflight means checking a package without running it. The command checks the target board, checksums, and whether the app and its resources fit. It only needs the Python workspace and the update file. Some factory packages include extra partitions. Use [fwkit](/tooling/fwkit/) to inspect those. ## Troubleshooting | What you see | What to check | |---|---| | Firmware hash mismatch or a tiny firmware file | Repeat step 2 in [Setup](/getting-started/setup/) to download the full reference image. | | `ats3089c-wp2` missing | Point `--qemu` at the executable from the preview archive. | | QEMU exits before boot | Rerun `emu doctor`. On Windows, check that `--runtime-dir` points to MSYS2's UCRT64 `bin` folder. | | Storage preparation fails | Check free space, the debugger path, and the numbered GDB, QEMU and UART logs in the reported folder. | | Headless works but the window fails | Install Tcl/Tk and pass `--wish` with the path to its executable if it is outside PATH. | --- # Installation Install the CMF Watch Utils CLI, the QEMU runtime, and the host libraries. URL: https://cmf.arnv.dev/emulator/installation/ QEMU runs the watch on your computer. The compatibility ROM in the shared archive starts the firmware. Both are required before you can create the watch's storage or boot the emulator. A **profile** selects the model and starting state. The **runtime** is the QEMU program that runs it; **fixtures** are files representing the watch’s storage. Installation prepares the tools, and the next page creates that storage. ## Workspace Follow [Setup](/getting-started/setup/) through step 2. That installs the CLI and puts the reference firmware at `dumps/binaries/firmware/JX402_V1.0.0.73.bin`. Keep your terminal open in the `cmf-watch-utils` folder. Run: ```text uv run cmf-watch-utils emu profiles ``` Use `wp2-stock` for Watch Pro 2, `wp2-onboarding` for its setup screens, or `wp3-stock` for Watch 3 Pro. See [Watch 3 Pro storage](/emulator/first-boot/#watch-3-pro-storage) for the additional package. ## Runtime archives Use a current checkout and matching runtime. The automatic stock texture index and Watch 3 Pro preview controls described here require the preview 9 generation or later. Older checkouts may lack these CLI options even with a newer QEMU binary. Download **two** archives from the same [preview release](https://github.com/fmctools/cmf-watch-utils/releases): - The archive named `cmf-emulator-windows-x64.tar.gz`, `cmf-emulator-linux-x64.tar.gz`, or `cmf-emulator-macos-arm64.tar.gz` for your computer. It contains the project's QEMU executable. Use a release that lists your model or build the current runtime from source. - `cmf-emulator-wp2-rom.tar.gz`. It contains `compat.bin`, which starts the virtual watch, and the small programs used to prepare and read its storage. On Windows, move the downloads into the checkout. Then run these commands in PowerShell to put the contents of both archives in one folder: ```powershell New-Item -ItemType Directory -Force runtime | Out-Null tar -xf cmf-emulator-windows-x64.tar.gz -C runtime --strip-components 1 tar -xf cmf-emulator-wp2-rom.tar.gz -C runtime --strip-components 1 Get-ChildItem runtime ``` Check that you see `qemu-system-arm.exe`, `compat.bin` and `provision-nand.elf`. On Linux or macOS, use `mkdir -p runtime` and substitute your host's archive in the first `tar` command. The QEMU executable on those hosts has no `.exe` suffix. If a release archive is unavailable, see the [source build instructions](https://github.com/fmctools/cmf-watch-utils/blob/main/emulator/README.md). ## Host dependencies ### Windows Install MSYS2 and open its **UCRT64** terminal. Run this command there, then switch back to PowerShell: ```bash pacman -S --needed mingw-w64-ucrt-x86_64-glib2 mingw-w64-ucrt-x86_64-pixman mingw-w64-ucrt-x86_64-dtc mingw-w64-ucrt-x86_64-libwinpthread mingw-w64-ucrt-x86_64-zlib mingw-w64-ucrt-x86_64-tk ``` UCRT64 is the MSYS2 environment used by the Windows runtime. Its terminal installs the libraries; the remaining examples run in PowerShell. The last package provides `wish.exe`, which opens the watch window. For `--runtime-dir`, use the `ucrt64/bin` folder from your MSYS2 installation. ### Arch Linux Install the runtime libraries, viewer and Arm debugger from the official repositories: ```bash sudo pacman -Syu --needed git git-lfs uv glib2 pixman dtc libpulse tk arm-none-eabi-gdb ``` `uv` manages the Python workspace. GLib, Pixman and `dtc` provide QEMU's native libraries; `libpulse` provides its audio client library. Tcl/Tk supplies the `wish` viewer. [Arm GDB](https://archlinux.org/packages/extra/x86_64/arm-none-eabi-gdb/) is used to prepare the virtual storage. Use the Linux x64 archive and the shared ROM archive. From the checkout: ```bash mkdir -p runtime tar -xf cmf-emulator-linux-x64.tar.gz -C runtime --strip-components 1 tar -xf cmf-emulator-wp2-rom.tar.gz -C runtime --strip-components 1 uv sync --locked uv run cmf-watch-utils emu doctor --qemu runtime/qemu-system-arm --rom runtime/compat.bin arm-none-eabi-gdb --version ``` In [First boot](/emulator/first-boot/), use `--qemu runtime/qemu-system-arm`, omit `--runtime-dir`, and keep `--gdb arm-none-eabi-gdb`. The viewer needs a graphical desktop; on Wayland, it also needs XWayland (`xorg-xwayland`). Audio playback needs a running PulseAudio server or PipeWire's PulseAudio compatibility service. The Linux archive is built and smoke-tested on Ubuntu 22.04. Arch has not had an end-to-end firmware boot test. If a rolling library update prevents the archive from loading, follow the [Arch source build instructions](https://github.com/fmctools/cmf-watch-utils/blob/main/emulator/README.md#arch-linux). The distribution's standard QEMU package does not include this watch model. ### Ubuntu and macOS | Host | Packages | Command differences | |---|---|---| | Ubuntu 22.04 x64 | Install `libglib2.0-0 libpixman-1-0 libfdt1 libpulse0 tk gdb-multiarch` with apt. | Remove `.exe` and `--runtime-dir`. Use `--gdb gdb-multiarch` when preparing storage. | | macOS ARM64 | Install `glib pixman dtc` with Homebrew. Install Tcl/Tk for the viewer and an Arm-capable GDB to prepare storage. | Remove `.exe` and `--runtime-dir`. Put `wish` on PATH or pass its path with `--wish`. Pass the debugger path with `--gdb`. | ## Verify the installation Run this check from the checkout. Apply the command differences above on Linux and macOS: ```text uv run cmf-watch-utils emu doctor --qemu runtime/qemu-system-arm.exe --rom runtime/compat.bin --runtime-dir "PATH_TO_UCRT64_BIN" ``` Replace `PATH_TO_UCRT64_BIN` with your actual MSYS2 `ucrt64/bin` directory; keep the quotation marks if the path contains spaces. Look for `"machine": "ats3089c-wp2"` and `"viewer_available": true`. If only the viewer is missing, you can still run the headless check in [First boot](/emulator/first-boot/). Next, [prepare the watch's storage and boot stock firmware](/emulator/first-boot/). --- # OTA and recovery Transfer a firmware update between virtual devices and check what happens after reboot. URL: https://cmf.arnv.dev/emulator/ota-recovery/ The commands below use Watch Pro 2. Start with [First boot](/emulator/first-boot/). Watch 3 Pro has a separately verified, narrower update test described below. This guide uses two local programs. QEMU runs the virtual watch. Netsim gives it a simulated Bluetooth radio so the OTA client can talk to it without a physical adapter. ## Simulated Bluetooth Find `netsimd` in the Android Emulator package. You can run this executable without creating an Android device or signing in to Nothing X. Open a new terminal and run: ```text netsimd --instance 70 --hci-port 17310 --no-cli-ui --no-web-ui ``` Leave that terminal open. Use port `17310` in both QEMU and the OTA client. If Netsim exits when the guest closes, start it again before the next test. ## Update protocols - **Stock CMF OTA** uses the original watch app. It needs a synthetic pairing secret before it will accept an OTA request. - **Actions OTA** works with a guest app exposing the Actions SDK OTA service. It uses a standalone AOTA file without a CMF trailer and skips stock pairing. See [Actions SDK OTA](/tooling/actions-ota/). Both protocols default to negotiation. The guest responds to the setup commands, and no firmware bytes are sent. Add `--transfer` to send the file to the virtual watch. ## Stock pairing Run the first command in the checkout. In a second terminal run the second command. It gives the guest a random test secret, saves its virtual storage to `local/paired-nor.bin`, and closes QEMU. These examples use the same paths as the first-boot walkthrough. On Windows, use `runtime/qemu-system-arm.exe` and add `--runtime-dir "PATH_TO_UCRT64_BIN"` when launching QEMU. ```text uv run cmf-watch-utils emu run --fixtures fixtures --qemu runtime/qemu-system-arm --rom runtime/compat.bin --headless --hci-port 17310 --qmp-port 17320 --seconds 120 --output runs/pairing uv run cmf-watch-utils emu pair-fixture --hci-port 17310 --qmp-port 17320 --output local/paired-nor.bin ``` Port `17320` is QEMU's local control connection. The CLI uses it to save the virtual storage. Keep the exported file local. For Watch 3 Pro, add `--profile wp3-stock` to both commands and use Watch 3 Pro fixtures. Start a new guest with `emu run --profile wp3-stock --nor local/paired-nor.bin` before negotiating OTA. The stock app loads the synthetic secret into its authentication state during boot. ## Watch Pro 2 stock update Run these commands in order, each in a separate terminal. Give the first command time to start, then start the recovery command before transferring. Replace `local/stock-protocol-update.bin` with a compatible app/SDFS update. ```text uv run cmf-watch-utils emu run --fixtures fixtures --qemu runtime/qemu-system-arm --rom runtime/compat.bin --nor local/paired-nor.bin --headless --allow-reboot --ota-snapshot --hci-port 17310 --qmp-port 17320 --seconds 450 --output runs/stage uv run cmf-watch-utils emu recover --fixtures fixtures --qemu runtime/qemu-system-arm --rom runtime/compat.bin --reader runtime --gdb arm-none-eabi-gdb --qmp-port 17320 --pending-nand runs/stage/nand-staged.bin --output runs/install uv run cmf-watch-utils emu ota --protocol stock --hci-port 17310 --image local/stock-protocol-update.bin --transfer --output runs/stock-transfer.json ``` The first command starts stock and saves its simulated NAND when stock asks to reboot. The second waits for that reboot, reads the staged update through the stock NAND driver, and writes a new `runs/install/nor.bin`. The third sends the update. Boot the new file with `emu run --nor runs/install/nor.bin` and a fresh output directory. A panel frame confirms that the installed app started and drew something. ## Watch 3 Pro modeled recovery Use `emu recover --profile wp3-stock` with Watch 3 Pro fixtures. The emulator can install an extracted `--pending-temp` payload when the supplied virtual NOR contains a valid pending OTA record. With `--crown-held --charger-connected`, it can restore the stock app and resources to a broken virtual NOR. Each operation writes a new NOR file that you can boot in QEMU. In the Watch 3 Pro OTA test, the stock app received an app/SDFS update over simulated Bluetooth, validated the TEMP payload and requested an OTA reboot. The test recovered the exact TEMP bytes from the NAND snapshot and passed them to the modeled installer along with the pending record captured from NOR. The installed app drew its test screen on the next boot. Automatic TEMP extraction with `emu recover --pending-nand` is currently available for Watch Pro 2. For Watch 3 Pro, use `--pending-temp` with an extracted payload. ## Verification and limits - In the Watch Pro 2 stock test, the guest accepted the update, rebooted, and started Bad Apple after the emulator installed the staged package. The recorded test used a QEMU-only package with an empty AGPS trailer. - In the Actions test, the guest accepted the image after transfer. Post-install boot is a separate check. - Crown + charger rescue is a separate model. Given a deliberately broken virtual app, `emu recover --fixtures fixtures --nor local/broken-nor.bin --crown-held --charger-connected --output runs/rescue` restores stock app and resource data. Boot the resulting `nor.bin` to check the restore. The emulator uses a replacement boot handoff. These tests do not establish whether a real watch will enter recovery with a broken app or recover after power loss or damage to its boot partitions. See [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/). ## Watch 3 Pro update coverage A desktop QEMU test transferred a small app-and-resources package through the stock Watch 3 Pro service. Stock validated the staged data, accepted the final acknowledgement and requested an OTA reboot. The test recovered the exact staged payload from the saved virtual NAND and checked it against the package. The host installer applied it to a new virtual flash image, and the installed application booted and drew its test screen. This establishes transfer, stock validation, reboot and modeled installation for that package. It does not establish full stock resource updates, interrupted updates, rollback, or execution of the physical bootloader. Automatic extraction from arbitrary Watch 3 Pro NAND snapshots remains unverified. The test supplied an already extracted payload through `emu recover --pending-temp`. Do not use the Watch Pro 2 `--pending-nand` walkthrough as a complete Watch 3 Pro procedure. Select `--profile wp3-stock` when using model-aware commands. --- # Contributing Set up a first contribution, choose the relevant checks, and prepare a pull request. URL: https://cmf.arnv.dev/getting-started/contributing/ You can work on the tools and documentation without owning a watch. Start with the type of change you want to make; firmware downloads and an emulator build are needed only for tests that use them. ## Choose your starting point | Change | Files | First check | |---|---|---| | Documentation | `site/src/content/docs/` | Preview the changed page locally. | | Firmware parsing or editing | `tooling/src/fwkit/` | Run command help, then test with the relevant input file. | | Command line or Bluetooth tools | `src/cmf_watch_utils/` | Run the Python tests without connecting a watch. | | Emulated hardware | `emulator/` | Build the native runtime and run its generated test program. | | Browser emulator controls | `emulator/web/` | Follow the browser development instructions in that directory's README. | The [repository contribution guide](https://github.com/fmctools/cmf-watch-utils/blob/main/CONTRIBUTING.md) contains build and test commands for emulator changes. The device pages hold model-specific formats and research; [methodology](/about/methodology/) explains how to distinguish an observation from an unverified hypothesis. ## Prepare a working copy Follow [Setup](/getting-started/setup/) to clone the repository. A checkout is that local copy; its root is the `cmf-watch-utils` directory containing `pyproject.toml` and `README.md`. If you do not have write access to the repository, create a fork on GitHub and use your fork's clone URL in the setup commands. A fork gives you a repository where you can push your branch. Create a branch before editing: ```text git switch -c docs/clarify-setup ``` Choose a name describing your change. Documentation-only work needs Git, Node.js and pnpm; you can skip `uv sync` and firmware downloads in Setup. ## Preview documentation Install Node.js 22.22 or later and pnpm 12. From the repository root: ```text cd site pnpm install --frozen-lockfile pnpm dev ``` Open the local URL printed in the terminal, normally `http://localhost:4321/`. Keep that terminal running while you edit. Changes to Markdown reload in the browser. To stop the server, press Ctrl+C in its terminal. The docs server serves the documentation. The separate WebAssembly emulator bundle is prepared by the emulator build workflow; starting Astro alone does not build the interactive watch pages. For a local watch session, follow [the browser build README](https://github.com/fmctools/cmf-watch-utils/blob/main/emulator/web/README.md). Before submitting a docs change, stop the preview and run this from `site/`: ```text pnpm build ``` A successful build checks that pages compile. Also follow the links and read the instructions in order; a build cannot tell whether a step makes sense to a new reader. ## Check a Python change From the repository root, after `uv sync --locked`: ```text uv run --locked python -m unittest discover -s tests -v ``` These tests use generated data and do not need a watch or stock firmware. For a format change, also run the relevant reference-image checks described in the [fwkit reference](/tooling/fwkit/). Download firmware only when needed. ## Submit the change Review `git diff` before committing. Exclude generated storage, pairing data, logs containing personal information and unrelated files. Push your branch to your fork or authorized repository, then open a pull request targeting `main`. Describe the behavior changed and the checks you actually ran. State any test that still needs a device or another operating system. For a reported problem, include its model, firmware and steps to reproduce it. [Troubleshooting](/getting-started/troubleshooting/) lists the information that helps distinguish setup problems from firmware or emulator failures. ## Firmware research [Memory layout and analysis](/contributing/firmware-analysis/) covers Ghidra imports and repeatable exports. [Research methodology](/about/methodology/) explains the evidence needed for format, protocol and emulator claims. Put build-specific findings in the corresponding device reference. For project discussion and community questions, see [Community](/about/community/). --- # Quick start Start the browser emulator, inspect firmware offline, or find a physical Watch Pro 2 over Bluetooth. URL: https://cmf.arnv.dev/getting-started/quickstart/ Choose the task you want to complete. Browser tasks need no watch, phone, account or command-line installation. Computer commands on this page require [Setup](/getting-started/setup/) first. | I want to… | Start here | What I need | |---|---|---| | Try a virtual watch | [Browser walkthrough](/emulator/browser-guide/#start-a-watch) | A browser; stock files are included | | Try an FMC or downloaded watch face | [Load a watch face](/emulator/browser-guide/#try-a-watch-face) | Choose a catalog face or a file for the selected model | | Run downloaded custom firmware | [Load firmware](/emulator/browser-guide/#load-custom-firmware) | A package, or an app and its matching resources | | Run the emulator on my computer | [Desktop installation](/emulator/installation/) → [First boot](/emulator/first-boot/) | Workspace, project QEMU runtime and virtual storage | | Connect my physical Watch Pro 2 | [Pairing](/tooling/ble-tools/#pair-a-watch-pro-2) | Workspace and computer Bluetooth | | Install firmware or return to stock | [Physical firmware update](/devices/cmf-watch-pro-2/guides/ota-flash/) | A compatible package and a working update service | | Test the update process without a watch | [Virtual OTA](/emulator/ota-recovery/) | Desktop emulator; loading a file in the browser is a different test | The examples below are for inspecting and editing files. They are not required to use the browser emulator. ## Inspect an image offline Complete [Setup](/getting-started/setup/) and fetch the stock image first. Run these commands from the repository root: ```text 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 ``` The first command lists the package contents. The second checks its integrity. The last writes extracted files to `work/aota` for inspection without changing the original package. ## Find a physical Watch Pro 2 Follow [pairing setup](/tooling/ble-tools/#pair-a-watch-pro-2) before authenticated queries. Start with a scan, then check the paired device: ```text 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 ``` ## Watch faces To try an existing face, use the [browser walkthrough](/emulator/browser-guide/#try-a-watch-face). For editing, follow [Dial editing](/devices/cmf-watch-pro-2/guides/dial-editing/), which explains the sample file, replacement images and physical upload steps. A watch-face upload is separate from a firmware update. ## Emulator and OTA checks After setup, list the available emulator profiles: ```text uv run cmf-watch-utils emu profiles ``` For a firmware package you already have, replace `local/update.bin` with its path: ```text uv run cmf-watch-utils emu preflight --image local/update.bin ``` This checks the package offline. For Watch 3 Pro, add `--profile wp3-stock`. Continue with [First boot](/emulator/first-boot/) to run it on desktop, or [OTA and recovery](/emulator/ota-recovery/) to test a virtual update. Physical flashing uses a separate [guide](/devices/cmf-watch-pro-2/guides/ota-flash/). --- # Requirements Minimum dependencies by task, from offline inspection to a virtual or physical OTA. URL: https://cmf.arnv.dev/getting-started/requirements/ The local command line tools use Git, uv and Python 3.12 or later. The browser emulator runs without a checkout. | Task | Additional requirements | |---|---| | Run stock firmware in the browser | Recent desktop Chrome or Edge and a connection for the initial download. No local tools required. | | List profiles or read command help | None beyond the workspace | | Inspect a firmware file or preflight an update | The local firmware file. Git LFS is optional if you use a direct download. | | Create emulator fixtures | Project QEMU, compatibility ROM bundle with the provisioner, Arm-capable GDB, exact stock package and pinned NAND ID table | | Boot firmware in QEMU | Project QEMU, compatibility ROM, host runtime libraries and prepared virtual flash fixtures | | Open the emulator window | Tcl/Tk `wish` in addition to the QEMU boot requirements | | Run virtual BLE OTA | Local H4 controller such as Netsim. Stock CMF OTA also needs a synthetic pairing fixture. | | Read staged TEMP from raw virtual NAND | Arm-capable GDB and reader files from the ROM bundle | | Talk to a physical watch | A Watch Pro 2 and a Bluetooth LE adapter supported by Bleak | | Build the documentation | Node.js 22.22 or later and pnpm 12 | The [emulator guide](/emulator/) lists OS-specific runtime packages and shows how to create the fixtures. A basic boot needs no Android emulator, Nothing X account, root access, or Bluetooth adapter. ## Physical watch The reference device is the CMF Watch Pro 2, board JX402, running stock `1.0.0.73`. Firmware builds and BLE behavior can differ. The tested physical host was Windows. Pairing state in `tools/.watch_state.json` is private. A watch connected to Nothing X may be unavailable to the host. See [BLE tools](/tooling/ble-tools/) for a read-only first check and [Limitations & risks](/devices/cmf-watch-pro-2/limitations/) before any live update. --- # Setup Install the workspace, verify the command line, and choose your next step. URL: https://cmf.arnv.dev/getting-started/setup/ This page installs the Python tools on your computer. To try the watch without installing tools, open the [browser emulator](/emulator/). For a documentation-only change, follow [Contributing](/getting-started/contributing/#preview-documentation). ## 1. Install the workspace Install Git and [uv](https://docs.astral.sh/uv/getting-started/installation/). The workspace uses Python 3.12 or later. Git downloads the source; `uv` installs Python dependencies into this project’s environment. `uv` can fetch a compatible Python when one is missing. Open a terminal in the directory where you want the checkout. On Arch Linux, install the workspace tools with `sudo pacman -Syu --needed git git-lfs uv`, then use the Linux commands below. The emulator's additional libraries are listed under [Arch Linux installation](/emulator/installation/#arch-linux). **Windows PowerShell** ```powershell $env:GIT_LFS_SKIP_SMUDGE = '1' git clone https://github.com/fmctools/cmf-watch-utils.git Remove-Item Env:GIT_LFS_SKIP_SMUDGE cd cmf-watch-utils uv sync --locked ``` **Linux or macOS** ```bash GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/fmctools/cmf-watch-utils.git cd cmf-watch-utils uv sync --locked ``` The `GIT_LFS_SKIP_SMUDGE` setting skips large firmware downloads during cloning. `uv sync --locked` installs the dependency versions recorded by the project. From the checkout, verify the tools: ```text uv run fwkit --help uv run cmf-watch-utils emu profiles ``` You should see the firmware toolkit help and `wp2-stock`, `wp2-onboarding` and `wp3-stock`. Keep running the following commands from the repository root unless a step says otherwise. The checkout also includes `scripts/install.ps1` and `scripts/install.sh`. Run them with `-Target .` or `.` respectively to install the current checkout. Use `-Firmware` or `--firmware` only when you also want the reference image. ## 2. Get the reference firmware if your task needs it Skip this section for documentation changes or the firmware-free Python tests. For container inspection or creating emulator storage files, install Git LFS and fetch the exact reference image: ```text git lfs install --local git lfs pull --include=dumps/binaries/firmware/JX402_V1.0.0.73.bin --exclude="" uv run fwkit info dumps/binaries/firmware/JX402_V1.0.0.73.bin ``` This fetches the Watch Pro 2 reference image. Fetch the [Watch 3 Pro image](/dumps/#jx402_w3pro_v10177bin-stock-firmware) as well for Watch 3 Pro fixture preparation. If `fwkit` sees a tiny text file instead, Git still has the LFS pointer. See [Dumps & data](/dumps/) for the direct download and checksum. Use a separate copy for edits. ## 3. Choose a task - **Inspect firmware** with the [quick start](/getting-started/quickstart/) and [fwkit reference](/tooling/fwkit/). - **Boot firmware without a watch** with the [emulator installation](/emulator/installation/). Use the browser for a stock boot with no local setup, or install desktop QEMU when you need local fixtures. - **Talk to your watch** with the [BLE tools](/tooling/ble-tools/). Start with `scan`. Pairing and OTA negotiation are live operations. - **Check an Actions OTA package** offline with the [Actions OTA guide](/tooling/actions-ota/). - **Build the docs** from `site/` with Node.js 22.22 or later and pnpm 12. Run `pnpm install --frozen-lockfile` and `pnpm build`. Use `pnpm dev` to preview. For help with connection failures, pairing screens and failed downloads, see [Troubleshooting](/getting-started/troubleshooting/). --- # Troubleshooting Help with pairing screens, failed updates, black displays, downloads and emulator setup. URL: https://cmf.arnv.dev/getting-started/troubleshooting/ Start with the section that matches what you see. Before trying another update, keep the firmware file and save the updater's log if it offers that option. Record the watch model and what happened just before the problem. ## The watch shows a pairing code after an update A pairing screen means the watch has reached its setup screen. It does not, by itself, mean the firmware is broken or that the update succeeded. An update or reset may have cleared the watch's connection to its companion app. 1. Let any update progress finish before changing connections. 2. Open Nothing X on your phone and use its add-device flow to set up the watch. Follow the prompts on the phone and watch. 3. If the app still lists the old connection but cannot reconnect, remove that saved device from the app and try adding it again. Removing a device or resetting it may discard settings; read the confirmation before proceeding. 4. After setup, open the watch's About screen and check its firmware version. Also check the feature you intended to install. If Nothing X rejects the code or setup returns to the pairing screen, save the exact error message. Check that the firmware was built for your watch model. Repeatedly flashing the same file is not a confirmed fix for a pairing failure. For **Watch Pro 2 desktop tools**, a reset can also invalidate the saved pairing credentials. Once the watch has finished restarting, disconnect phone clients and follow [pairing setup](/tooling/ble-tools/) before retrying a connection. This is separate from pairing in Nothing X. Physical Watch 3 Pro recovery has not been verified by this project. ## The updater cannot find or connect to the watch 1. Wake the watch and keep it close to the device running the updater. 2. Close other watch apps. When updating from a computer, turn phone Bluetooth off so the phone does not reconnect during the update. 3. Check that Bluetooth is enabled on the updating device. On a phone, grant the Bluetooth or nearby-device permissions requested by the app. 4. Try connecting again. If the watch was reset, repeat pairing using the instructions for your updater. A failure before firmware data is sent does not establish that the installed firmware changed. If the watch is still usable, check its version before deciding whether another update is needed. ## An update stopped or reported failure Keep the watch on stable power. Do not interrupt an installation that is still progressing on the watch. A transfer failure and an installation failure are different: one happens while sending the file, the other while applying it. If the watch returns to its normal screen, check the version and reconnect. Before retrying, confirm that the file matches your model and that its download is complete. Use the same updater's instructions rather than switching protocols based only on the appearance of a progress bar. If it stays on an update screen, repeatedly restarts or becomes unreachable, see [Watch Pro 2 flashing risks](/devices/cmf-watch-pro-2/limitations/) and [recovery limits](/devices/cmf-watch-pro-2/internals/recovery/). There is no verified button sequence that recovers every failed physical watch. The emulator's recovery controls are not instructions for recovering hardware. ## The screen went black after installing a watch face First check whether the watch is asleep: wake it using its normal controls. If it still connects to its companion app, try selecting a built-in watch face through the app, if that option is available. This is a diagnostic step, not a guaranteed recovery method. If the display remains black or the watch repeatedly restarts, stop uploading faces and record which file caused the problem. Oversized or malformed resources can prevent the interface from loading. On Watch Pro 2, a firmware update does not necessarily remove installed watch faces, so reinstalling stock firmware may leave the same problem in place. Do not use an unknown factory-menu option as a recovery shortcut. Some options erase data or shut down the watch. If no usable connection remains, vendor support or physical diagnosis may be needed. ## A downloaded firmware file cannot be opened A file downloaded with Git may be a small text pointer instead of the actual firmware. Follow [reference firmware setup](/getting-started/setup/#2-get-the-reference-firmware-if-your-task-needs-it) to download the binary through Git LFS. Compare the download's checksum with the [data index](/dumps/) before using it. A checksum is a value calculated from a file. A match confirms that your copy matches the published file; it does not establish compatibility with your watch. ## The desktop emulator does not start Use the project's QEMU release for your operating system. A general QEMU package does not include this watch model. Follow [installation](/emulator/installation/), then [first boot](/emulator/first-boot/) with the firmware and storage files for the selected model. Run commands from the repository folder after completing [setup](/getting-started/setup/). If a command reports a missing file, check its path and whether the file was actually downloaded. Save the error text before changing any files. ## The browser emulator freezes, goes black or has broken audio Close unused emulator tabs first; each running watch consumes memory and CPU. If the page still responds, save the Watch log before restarting. Test the stock preset to distinguish a problem with a custom image from one affecting the stock firmware too. Restarting or resetting the virtual watch can discard unsaved state. Audio may require clicking or tapping the page before the browser permits playback. Check **Watch sound** under **Simulation → Config** and whether the tab is muted. Slow emulation can also interrupt audio; a successful browser boot does not guarantee real-time playback on every device. ## The browser emulator opens without my saved watch state Open **Simulation → Config** and check **Automatically save watch storage**. Reopen the same model with the same firmware and app selection. Select any local uploads again. The status under the switch shows whether a save was restored or whether browser storage was unavailable. If the tab closed before the last checkpoint finished, the emulator restores the previous completed save. Clearing saved watch storage or resetting to stock can remove the checkpoint. See [Save data in the browser](/emulator/browser-guide/#save-data-in-the-browser). ## Reporting a problem Include the watch model, firmware version, updater or emulator version, operating system, and the steps that caused the problem. For browser issues, include the browser name and version. Describe what you expected and what appeared instead. Attach the relevant log after removing Bluetooth addresses, serial numbers, pairing keys, notifications and other personal information. State whether the problem occurred on a real watch, desktop QEMU or the browser emulator. --- # CMF Watch Utils Firmware tools, Bluetooth utilities and emulation for CMF watches. URL: https://cmf.arnv.dev/ import InteractiveTools from '../../components/InteractiveTools.astro'; CMF Watch Utils is an unofficial interoperability project. It provides an offline toolkit for the firmware containers used by CMF Watch devices, a Python client for the watch's BLE services, QEMU emulators for Watch Pro 2 and Watch 3 Pro, and the research notes behind them. The project is device-scoped: each supported model has its own section with its own protocol details, format notes and verified results. Shared tooling and general documentation live at the top level, so new devices can be added without duplicating the tools. :::caution[Risk] Firmware flashing can leave a watch unbootable, and no universal recovery path has been proven for every failure mode. The tooling exists for research, interoperability and hardware that is owned and whose loss is acceptable. The device section documents the specific risks. ::: ## Browser emulator Choose [Watch Pro 2](/emulator/watch-pro-2/) or [Watch 3 Pro](/emulator/watch-pro-3/) to boot stock firmware. Both open with prepared virtual storage and support touchscreen and crown inputs. See the [emulator overview](/emulator/) for custom firmware, watch faces and sensor controls. Use the [desktop emulator](/emulator/installation/) for model-specific virtual OTA and recovery tests without a watch, phone or Bluetooth adapter. ## Device support | Device | Firmware | State | Section | |---|---|---|---| | CMF Watch Pro 2 (`JX402`, Actions ATS3089C) | 1.0.0.73 | Hardware-tested tooling and QEMU preview | [Device pages](/devices/cmf-watch-pro-2/) | | CMF Watch 3 Pro (`jx402_08`) | 1.0.1.77 | Browser and desktop emulation, offline firmware inspection | [Device pages](/devices/cmf-watch-pro-3/) | | Other CMF Watch models | — | No verified profile | [Roadmap](/about/roadmap/) | ## Project contents | Area | Description | |---|---| | [Toolkit](/tooling/fwkit/) | `fwkit` — parse, rebuild and patch AOTA, SDFS, RES, STY, WFDL, AJS and picture containers offline | | [BLE tooling](/tooling/ble-tools/) | `cmf_watch.py`, `ota_client.py` — pairing, shell commands, watch-face upload, firmware OTA | | [Emulator](/emulator/) | Stock and custom firmware boot, virtual OTA and modeled recovery | | [Actions SDK OTA](/tooling/actions-ota/) | Separate BLE OTA client with offline validation and loopback testing | | Device research | [Watch Pro 2](/devices/cmf-watch-pro-2/) and [Watch 3 Pro](/devices/cmf-watch-pro-3/) | | [Dumps](/dumps/) | Firmware manifests, hashes and downloadable images | | [Agent context](/ai/context/) | A compact briefing for AI coding agents | ## Community Join [FMC Community on Discord](https://discord.gg/KnAFruMabJ) or [r/CMFWatchMods on Reddit](https://www.reddit.com/r/CMFWatchMods/) to discuss projects and share findings. The [community page](/about/community/) lists the project repositories and where to report problems. ## Contributing Start with the [contributor guide](/getting-started/contributing/) to choose a setup for documentation, Python tools or emulator development. Most initial checks need no watch or firmware download. ## Orientation - [Requirements](/getting-started/requirements/), [Setup](/getting-started/setup/) and [Quick start](/getting-started/quickstart/) cover the first steps. - [Methodology](/about/methodology/) describes how the formats were recovered and verified. - [Legal & attribution](/about/legal/) covers licensing, third-party notices and the terms for the published artifacts. --- # Watch artwork Official Nothing X artwork, factory color codes, source URLs and downloadable files for CMF watches. URL: https://cmf.arnv.dev/reference/watch-artwork/ import InteractiveTools from '../../../components/InteractiveTools.astro'; The Nothing X catalog contains artwork for Watch Pro, Watch Pro 2 and Watch 3 Pro. This reference groups identical images and records the product and factory color codes used to select them. The images show the factory cases, straps and colors listed in the product catalog. [Download the complete inventory (ZIP)](/reference/artwork/watch-artwork.zip) · [Download the machine-readable manifest (JSON)](/reference/artwork/inventory.json) ## Inventory The Nothing X 3.10.0 catalog has **26 watch SKU entries**, **31 image URLs** and **13 distinct image files**. Twelve images show watch appearances; the remaining image is a shared grey catalog image (`case.png`). Multiple SKU codes point to the same artwork, so the gallery shows each appearance once. The meaning of each SKU alias is not established. | Watch | Product ID | Appearance | Color codes (hex) | | --- | --- | --- | --- | | Watch 3 Pro | `335BBD62` | dark grey | `01`, `19`, `20` | | Watch 3 Pro | `335BBD62` | green | `25`, `26` | | Watch 3 Pro | `335BBD62` | light grey | `21`, `22` | | Watch 3 Pro | `335BBD62` | orange | `23`, `24` | | Watch Pro | `82D5BB72` | dark grey | `01`, `03` | | Watch Pro | `82D5BB72` | dark grey, ash-grey strap | `07`, `08` | | Watch Pro | `82D5BB72` | orange | `05`, `06` | | Watch Pro | `82D5BB72` | silver | `02`, `04` | | Watch Pro 2 | `34F72851` | blue | `15`, `16` | | Watch Pro 2 | `34F72851` | dark grey | `01`, `09`, `10` | | Watch Pro 2 | `34F72851` | light grey | `11`, `12` | | Watch Pro 2 | `34F72851` | orange | `13`, `14` | ## Image fields `globalImageUrl` contains the model/color watch artwork used in the gallery. Every watch SKU entry uses the same `steerImageUrl`, pointing to a grey `case.png`. It is a shared catalog asset rather than another watch appearance. Its exact use in the Nothing X interface has not been established. The gallery lists this asset once below the watch images, and the manifest preserves the original field names. ## Manifest and verification Each record contains the catalog model name, product ID (`modelId`), factory color code (`colorId`), catalog SKU key (`fastPairId`) and named image views. Each view has its source URL, local file path, byte length and SHA-256 digest. Files are stored once by hash and referenced by the catalog records that use them. The 13 image files retain their original PNG bytes; the recorded size and SHA-256 identify each file. These images describe factory appearances. Replacement straps or bezels can make a physical watch look different from its reported factory color. See [model and color identification](/reference/watch-identity/) for the advertisement layouts and the relationship between product IDs, color codes and catalog keys. ## Source and attribution The catalog metadata comes from the Nothing X 3.10.0 `DeviceInfoTable` product catalog; the source URLs are recorded for each image. Account records, device addresses, serial numbers, pairing secrets and location data are not part of this inventory. The artwork belongs to Nothing and its respective rights holders. The project license does not grant rights to third-party artwork. The included manifest preserves source attribution; see [legal and attribution](/about/legal/) for project licensing. --- # Watch model and color identification Product identifiers, factory color codes and advertisement layouts used by Nothing X for CMF watches. URL: https://cmf.arnv.dev/reference/watch-identity/ import InteractiveTools from '../../../components/InteractiveTools.astro'; CMF watches identify their product model and factory color in Bluetooth advertisements. Nothing X combines these values into a catalog key to select the corresponding product artwork. A factory color identifies a product variant; it does not describe replacement straps or bezels. ## Product identifiers A product ID contains four bytes. Its catalog representation is eight hexadecimal digits in the same byte order, with leading zeroes preserved. | Product ID | Watch | | --- | --- | | `82D5BB72` | Watch Pro | | `34F72851` | Watch Pro 2 | | `335BBD62` | Watch 3 Pro | The factory color is a separate byte, represented by two hexadecimal digits. The catalog key is the product ID followed by the color code. For example, `335BBD62` and `23` form `335BBD6223`, an orange Watch 3 Pro entry. The catalog calls this combined key `fastPairId`; it is a product/SKU identifier, not a unique identifier for an individual watch. The [artwork reference](/reference/watch-artwork/) lists the known color codes. Several codes can share the same image. Their individual regional or retail meanings have not been established. ## Advertisement normalization The field offsets below refer to the byte sequence reconstructed by Nothing X's watch parser, not the complete Bluetooth advertising packet. Android and Web Bluetooth expose manufacturer-specific data with the two-byte company identifier separated from its payload. In Nothing X 3.10.0: - Company ID `0x0CCB` (3275 decimal) uses the supplied payload unchanged. - For other company IDs passed to the watch parser, `2C BE` is prepended to the supplied payload before the fields are read. This second rule describes the parser's normalization branch; it does not mean that arbitrary manufacturers identify CMF watches. The parser also checks the watch marker and validates the embedded address through its vendor-address check. ## Advertisement layouts Nothing X uses a legacy layout for normalized data of at least 18 bytes, and a compact layout for 14-17 bytes. Shorter data does not contain the complete fields. | Field | Legacy layout | Compact layout | | --- | --- | --- | | Embedded Bluetooth address | Bytes 0-5 | Bytes 0-5 | | Watch marker | Bytes 6-11: `JX-IWD` | Bytes 6-7: `JX` | | Product ID | Bytes 12-15 | Bytes 8-11 | | Factory color code | Byte 16 | Byte 12 | | State | Byte 17 | Byte 13 | The address bytes are formatted in their existing order. The product and color bytes are converted to uppercase hexadecimal without reversing them. Nothing X exposes them as `PRODUCT_ID`, `COLOR_ID` and the combined `PRODUCT_COLOR_ID` / `FAST_PAIRED_ID`. The parser sets `IS_PAIRED` for state bytes `00`, `01` or `02`. This is the app's interpretation of an advertising state; it does not establish an authenticated GATT session. Advertised identity is not proof of device ownership. ## QR and shell identifiers The stock onboarding QR uses product field `P` and color field `C`. The QR color is decimal, whereas the catalog uses hexadecimal. For example, decimal `35` corresponds to catalog color `23`. Comparing the strings without this conversion can select the wrong SKU. Watch Pro 2 and Watch 3 Pro firmware analysis identifies the `APP_PID` property and the read-only `AT GETPID` query. Its response format is: ```text GETPID:34F72851,OK ``` This query reports the product ID only. It does not report the factory color. Shell-service availability and command support depend on the firmware; the query is separate from the encrypted control-channel authentication protocol. A shell reply may arrive over several Bluetooth notifications. ## Browser access Web Bluetooth distinguishes access to GATT services from access to advertisements. A successful connection alone does not provide the manufacturer-data color byte. Where supported, `BluetoothDevice.watchAdvertisements()` delivers advertisements for an authorized device. API support, permissions and the watch's advertising state determine whether those bytes are available. A missing advertisement or unknown color code leaves the factory color unknown. An advertised device name can help identify a model, but does not establish a factory color. A user-selected frame is a display preference, not detected hardware metadata or evidence that a firmware package is compatible. See the [Web Bluetooth specification](https://bluetooth.spec.whatwg.org/) and [BluetoothDevice API reference](https://developer.mozilla.org/en-US/docs/Web/API/BluetoothDevice) for the browser interfaces and availability. ## Evidence and scope The advertisement layouts and state handling come from Nothing X 3.10.0's `com.nothing.link.bluetooth.sdk.scan.parser.NothingWatchParser`, including `getTotalManufacture()` and `parser()`. `NtBlePlugin` consumes the resulting `PRODUCT_ID` and `COLOR_ID`; Flutter's `BluetoothHelper.getDeviceInfoByBluetoothDevice` resolves them against the `DeviceInfoTable` SKU catalog. The QR and `APP_PID` findings come from stock Watch Pro 2 and Watch 3 Pro firmware analysis. The artwork associations come from the Nothing X product catalog and its recorded image URLs. These findings establish the documented formats and known catalog mappings, not universal advertisement or shell-command availability across every firmware and browser. --- # Actions SDK OTA Select the Actions BLE OTA transport, validate packages offline, and interpret virtual and physical test results. URL: https://cmf.arnv.dev/tooling/actions-ota/ CMF Watch Utils supports two BLE OTA protocols for Watch Pro 2 firmware. The stock CMF client uses authenticated CMF frames and serves ranges requested by the stock app. The Actions SDK client uses its own service, packet framing and negotiation. Select the client based on the BLE service exposed by the running firmware. | Path | CLI | Transport | |---|---|---| | Stock CMF | `uv run python tools/ota_client.py` | Stock BLE command and OTA characteristics. See [AOTA OTA flow](/devices/cmf-watch-pro-2/protocol/ota/). | | Actions SDK | `uv run cmf-watch-utils ota actions` | Local package checks by default. An explicit address selects physical BLE. | | Emulator | `uv run cmf-watch-utils emu ota --protocol stock` or `--protocol actions` | Loopback H4 only. See [OTA and recovery](/emulator/ota-recovery/). | ## Offline validation ```bash uv run cmf-watch-utils ota actions --image local/actions-update.bin --output runs/actions-offline.json ``` With no address this checks the package and reports `offline_validated` without scanning or connecting. The client expects a standalone app/SDFS AOTA with an outer `TEMP.bin` and no CMF AGPS trailer. A stock download or an image that passed `fwkit verify` can still be incompatible with this transport. ## Negotiation and transfer | Role | UUID | |---|---| | Service | `e49a25f8-f69a-11e8-8eb2-f2801f1b9fd1` | | Acknowledged write | `e49a25e0-f69a-11e8-8eb2-f2801f1b9fd1` | | Notify | `e49a28e1-f69a-11e8-8eb2-f2801f1b9fd1` | On hardware, `--address` subscribes and negotiates, which can show the update screen even when no image bytes are sent. Treat negotiation as an OTA state change. Physical transfer requires both an explicit address and `--flash`. In QEMU, use `emu ota --protocol actions` and opt into data transfer with `--transfer`. The host requests an upgrade and negotiates the unit size. During transfer it serves the peer's requested offsets using acknowledged writes. It accepts a success result after serving data and receiving the peer's validation response. | Result | Evidence | |---|---| | `offline_validated` | Local package checks passed. | | `negotiated_only` | The peer accepted negotiation. No image bytes were sent. | | `watch_reported_image_valid` | The peer accepted the transferred image. Confirm installation separately by checking the reboot and running firmware. | The integrated client reached guest validation in desktop QEMU. The physical transfer and post-update boot remain unverified for this client. The Actions service and its update screen alone do not establish an app-independent recovery mode. See [Recovery & boot modes](/devices/cmf-watch-pro-2/internals/recovery/). --- # BLE tools Reference for cmf_watch.py and ota_client.py, the host-side tools that talk to the watch. URL: https://cmf.arnv.dev/tooling/ble-tools/ The stock scripts on this page target [Watch Pro 2](/devices/cmf-watch-pro-2/) and use [Bleak](https://github.com/hbldh/bleak). Physical tests ran on Windows. For the separate Actions SDK protocol, see [Actions SDK OTA](/tooling/actions-ota/). For OTA over a simulated radio, see [OTA and recovery](/emulator/ota-recovery/). ```bash uv run python tools/cmf_watch.py --help uv run python tools/ota_client.py --help ``` ## Pair a Watch Pro 2 Complete [Setup](/getting-started/setup/) first. Run these commands from the `cmf-watch-utils` folder with computer Bluetooth enabled. Wake the watch, keep it nearby and turn phone Bluetooth off so Nothing X does not take the connection. ```text uv run python tools/cmf_watch.py scan uv run python tools/cmf_watch.py pair uv run python tools/cmf_watch.py info ``` The scan should list the watch. Pairing should end with `saved state ->` and a local file path. `info` should then report device information. Check the identity before sending an update. The pairing output contains keys: do not share it unredacted. Here, `pair` establishes the tool's authenticated connection. It is not the Nothing X add-device flow, and a Windows Bluetooth pairing alone does not replace it. If the tool cannot find or connect to the watch, follow [connection troubleshooting](/getting-started/troubleshooting/#the-updater-cannot-find-or-connect-to-the-watch) before attempting an update. A watch reset can invalidate the saved credentials; repeat this pairing step after a reset. ## cmf_watch.py ### Read-only commands | Command | Purpose | |---|---| | `scan` | List nearby BLE advertisements | | `at ` | Query with a known read-only [AT command](/devices/cmf-watch-pro-2/protocol/shell/) | | `info` | Version, serial, name, PID, battery, temperature, accelerometer | | `sync` | Observe the notification stream for a while | | `workouts` | Dump the workout/sport configuration tables | | `specs` | Device specification strings | | `wf-dials` | List installed watch faces | | `ota-state` | Observe the OTA characteristic without writing firmware data | ### Write commands | Command | Purpose | |---|---| | `ota-init` | Send the OTA init frame and observe the reply | | `pair` | Full pairing exchange; writes the local auth state | | `wf-flash --file ` | Install a watch face (`--dry-run` prints the plan only) | | `wf-delete --id --file ` | Remove an installed face | | `ota-flash --image ` | Legacy OTA path used during the earlier experiments | | `ota-push`, `ota-arm`, `ota-dtry`, `ota-resume`, `ota-run` | Experiment variants used while the OTA flow was being mapped | ### Local state Pair once with `uv run python tools/cmf_watch.py pair` before authenticated commands. If the host cannot connect, disconnect Nothing X and rerun a scan. `tools/.watch_state.json` holds the pairing secret and authkey. It is gitignored. A stale authkey still produces an `A052` reply after INIT1, so `A052` alone does not prove the session is usable; the data phase only starts with a fresh pairing. ## ota_client.py Use this client for stock firmware updates. The `ota-*` commands in `cmf_watch.py` are research tools, not alternative recommended flashing procedures. See the [flashing guide](/devices/cmf-watch-pro-2/guides/ota-flash/) for the complete workflow. | Flag | Purpose | |---|---| | `--image ` | Firmware image to serve (defaults to the stock image under `firmware/`) | | `--version ` | 4-byte version argument of INIT2, for example `0100005a` | | `--stop-after-a040` | Stop once the watch acknowledges INIT2; no data is sent | | `--dry-run` | Connect, authenticate and stop after INIT1 acknowledgement. No firmware bytes sent. | | `--pace ` | Delay between write batches | | `--pipeline ` | Frames written concurrently per batch (default 4) | | `--idle-timeout ` | Abort after a period without requests (default 120 s) | | `-v` | Per-request logging | The client sends INIT1 on the command characteristic, INIT2 on the OTA characteristic, serves the ranges the watch requests, and acknowledges the end of the transfer. The device-specific details of that sequence are documented in the device section. ## Read-only sessions Use `scan`, `info`, `ota-state` and known read-only AT queries for diagnosis. Pairing and OTA negotiation use live protocol commands and can change device state. In particular, `--dry-run` and `--stop-after-a040` on the stock client are live BLE operations. --- # fwkit CLI Command reference for the offline firmware container toolkit. URL: https://cmf.arnv.dev/tooling/fwkit/ `fwkit` is the offline half of the project: it parses the firmware containers, rebuilds them byte-for-byte, and applies targeted edits. It never talks to a watch. ```bash uv run fwkit --help ``` In the reference tables, ``, `` and similar names are placeholders, not literal shell arguments. Replace each with your path, and quote paths with spaces. Use `uv run fwkit COMMAND --help` for a command’s complete arguments. ## AOTA container | Command | Purpose | |---|---| | `fwkit info ` | Header, entry table, per-entry sizes and CRC status | | `fwkit verify ` | Header CRC and every entry CRC | | `fwkit unpack ` | Header, `ota.xml`, AGPS trailer and each partition | | `fwkit pack ` | Rebuild an image from an unpacked directory | ## SDFS filesystem | Command | Purpose | |---|---| | `fwkit sdfs-list ` | File table of an SDFS partition | | `fwkit sdfs-extract ` | Extract all files | | `fwkit sdfs-pack ` | Rebuild from a directory | | `fwkit edit-sdfs ` | Replace one file inside a partition of an AOTA image | `fwkit.sdfs.pad_to(image, size)` rebuilds an SDFS image and pads it to the requested file length while refreshing `total_size` and the body checksum. This can preserve the stock image length; it does not resize the physical partition. See [SDFS capacity](/devices/cmf-watch-pro-2/formats/sdfs/#capacity) for the distinction between payload, image and partition sizes. ## RES strings and pictures | Command | Purpose | |---|---| | `fwkit res-list ` | Strings in a RES table | | `fwkit res-set -o ` | Replace one string | | `fwkit pic-list ` | Pictures and their codecs | | `fwkit pic-decode ` | Decode a picture to PNG | | `fwkit pic-set -o ` | Replace a picture from PNG | | `fwkit edit-res ` | Replace a string inside an AOTA image | | `fwkit edit-pic ` | Replace a picture inside an AOTA image | ## STY scene bundles | Command | Purpose | |---|---| | `fwkit sty-info ` | Header and scene table | | `fwkit sty-nodes ` | Nodes of the bundle | | `fwkit sty-tree ` | Node tree of one scene | | `fwkit sty-add-scene ...` | Add a scene with fresh node ids | | `fwkit sty-del-scene ...` | Remove a scene and compact records | | `fwkit sty-set-pic ...` | Repoint an image node at another picture | | `fwkit edit-sty-pic ...` | Repoint a node inside an AOTA image | ## AJS animations | Command | Purpose | |---|---| | `fwkit ajs-info ` | Record layout, frame count, fps and tiles | | `fwkit ajs-extract ` | Extract frames as JPEG | | `fwkit ajs-repack -o ` | Rebuild from JPEG frames | | `fwkit ajs-set-frame -o ` | Replace a single frame | ## WFDL watch faces | Command | Purpose | |---|---| | `fwkit wf-info ` | Package header and structure | | `fwkit wf-res ` | Resource list with indices | | `fwkit wf-tree ` | TLV node tree | | `fwkit wf-unpack ` | Header, tree, resources and raw LZ4 blocks | | `fwkit wf-set-res -o ` | Replace one resource from PNG | | `fwkit wf-build --resources ` | Rebuild, replacing `NNN_*.png` | ## app.bin | Command | Purpose | |---|---| | `fwkit act-info ` | ACTH header fields | | `fwkit app-scene-refs ` | Scene-id references in the app image | | `fwkit app-patch-scene ...` | Rewrite a scene-id literal and rebuild the header | | `fwkit edit-app ` | Patch bytes at a virtual address in `app.bin` and rebuild `TEMP` | ## Conventions - Check an unchanged rebuild against the original image before relying on a parser for a new firmware version. Byte-identical AOTA rebuilds were verified on the reference builds for [Watch Pro 2](/devices/cmf-watch-pro-2/formats/aota/) and [Watch 3 Pro](/devices/cmf-watch-pro-3/formats/). - Formats are documented per device in the device section; the layouts differ between firmware generations. - `tooling/tests/selftest.py` runs the round-trip checks: ```bash uv run python tooling/tests/selftest.py dumps/binaries/firmware/JX402_V1.0.0.73.bin ``` The selftest requires a firmware image supplied locally; the published dumps under `dumps/binaries/` work as well. ---