From a52d8f7de47cab4f5f4162403ad49ad144b59347 Mon Sep 17 00:00:00 2001 From: codex-bot Date: Wed, 9 Sep 2026 17:52:23 +0100 Subject: [PATCH] README: document actual app (was stale hello-world copy) --- README.md | 242 +++++++++++------------------------------------------- 1 file changed, 46 insertions(+), 196 deletions(-) diff --git a/README.md b/README.md index 3fe2b80..0e7d302 100644 --- a/README.md +++ b/README.md @@ -1,209 +1,59 @@ -# Xiaomi Vela Hello World for Watch S4 +# CALCULATOR — round-screen calculator for Xiaomi Watch S4 -This is the smallest practical Xiaomi Vela JS watch application. It shows two centered lines on a round black screen: +A calculator laid out for the circular display: tapered key rows that follow the +chord of the round screen, large touch targets, high-contrast keys (#3a3a3e on #000). +Supports chained operations, percent, sign toggle, decimals, and divide-by-zero +error recovery. + +**Status: WORKING ON WATCH** (user-confirmed through v1.2; layout improved through 1.6). + +## Usage + +- Tap keys to compute; `AC` clears all +- `%` divides the display by 100 (plain semantics — 200+10% = 200.1) +- Back button exits (no onBackPress interception — intercepted back made the + button feel dead on a single-page app) +- Crown does nothing (unsupported API on Vela); the original crown-selection + scheme was abandoned for a directly-tappable list layout + +## Round-screen layout (the interesting part) + +- Short viewport (~300px) so rows never exceed the circle chord +- NO vertical margins on list-items (spacing baked into height — CSS/JS drift bug) +- Top/bottom spacer items so first/last keys can center in the viewport +- Focus = round((scrollY + KEYS_H/2 − ITEM_H/2 − PAD)/ITEM_H); re-centered after + every press via scrollTo +- Geometry + contrast assertions live in `tests/visual.cjs` (parses the .ux) + +## Project layout ```text -Hello World! -Xiaomi Watch S4 +src/ +├── app.ux, manifest.json # com.example.hellovela identity (preserved for updates) +├── common/icon.png # 192×192 circular icon +└── pages/index/index.ux # keys list + display + state machine +tests/ +├── page.cjs # state machine: driven via press(key) sequences +└── visual.cjs # parsed-from-source geometry/contrast contracts ``` -It compiles entirely from a Linux terminal. Xiaomi AIoT-IDE is not required. - -## 1. What you need - -- A 64-bit Linux system -- Node.js and npm -- OpenSSL, but only if you want a signed release package -- Internet access for the first `npm install` - -Node.js 20 LTS is a conservative choice. The included project has also been build-tested with Node.js 24 and npm 11. - -On Ubuntu or Debian, install the basic tools: - -```bash -sudo apt update -sudo apt install -y curl openssl -``` - -Install Node.js using your preferred package manager or a version manager such as `nvm`. Confirm that it works: - -```bash -node --version -npm --version -``` - -## 2. Understand the tiny project - -```text -xiaomi-vela-s4-hello-world/ -├── package.json -├── README.md -├── sign/ -└── src/ - ├── app.ux - ├── manifest.json - ├── common/ - │ ├── icon.png - │ └── icon.svg - └── pages/ - └── index/ - └── index.ux -``` - -- `package.json` installs Xiaomi's command-line build tool and defines the build commands. -- `src/manifest.json` defines the package, icon, watch target, design width, and start page. -- `src/app.ux` contains application lifecycle hooks. -- `src/pages/index/index.ux` contains the UI and its styles. -- `sign/` is where release certificate files go. Keep private keys private. - -Vela `.ux` files resemble small single-file web components. A page may contain `template`, `style`, and `script` blocks. This Hello World page needs only `template` and `style`. - -## 3. Compile a debug RPK without Xiaomi's IDE - -Open a terminal in the project folder and run: - -```bash -npm install -npm run build -``` - -The important output is created under `dist/` and ends in `.debug.rpk`: - -```bash -find dist -maxdepth 1 -type f -name '*.rpk' -print -``` - -The `build/` directory contains intermediate generated files. You normally do not edit either `build/` or `dist/`. - -To include a separate source map while debugging: - -```bash -npm run build:source-map -``` - -To see every compiler option supported by your installed toolkit: - -```bash -npm run help -``` - -## 4. Create a signed release RPK - -The release builder expects these two files: - -```text -sign/private.pem -sign/certificate.pem -``` - -Generate a local development certificate from the project root: - -```bash -openssl req \ - -newkey rsa:2048 \ - -nodes \ - -keyout sign/private.pem \ - -x509 \ - -days 3650 \ - -out sign/certificate.pem \ - -subj '/CN=Hello Vela Development/O=Example/C=US' -``` - -Then compile the release package: +## Build & test ```bash +npm ci npm run release -find dist -maxdepth 1 -type f -name '*.release.*.rpk' -print +node tests/page.cjs +node tests/visual.cjs ``` -Do not commit or share `sign/private.pem`. If a companion Android application communicates with the watch app, Xiaomi's wearable integration may require matching signing identity; changing certificates later can also prevent an update from being accepted as the same app. +## Install -## 5. Change the app +Side-load via AstroBox. Releases: +https://gitea.oimcloud.myaddr.tools/codex-bot/vela-calculator -Edit `src/pages/index/index.ux`. For example, replace: +## Bug history worth knowing (all caught by the stale-test TDD pass) -```xml -Hello World! -``` - -with: - -```xml -My first app -``` - -Then rebuild: - -```bash -npm run build -``` - -When publishing an update, increase `versionCode` in `src/manifest.json`. Also update `versionName` when you want the visible version string to change. - -## 6. Important Vela rules - -- A template must have exactly one root element. -- Visible text must be inside a `` component. -- Vela uses flex layout, but its CSS support is smaller than a browser's CSS support. -- Package names should use reverse-domain form, such as `com.yourname.hello`. -- `designWidth: 480` lets Vela scale the 480-pixel design to the physical display. -- APIs such as sensors, storage, network, or vibration must usually be declared in the manifest's `features` array before use. This Hello World app requests no APIs. - -## 7. Installing on a real Watch S4 - -Compilation and installation are separate. The terminal workflow above reliably creates the `.rpk`; transferring it to a physical watch depends on the exact Watch S4 model, firmware region, Mi Fitness version, and whether developer or debugging access is enabled for that firmware. - -Do not treat the `.rpk` as an Android APK, and do not flash random firmware. Use Xiaomi's supported wearable deployment route for your device/account. Some retail or global firmware builds do not expose the same development or sideload controls as Chinese developer setups. - -## 8. Troubleshooting - -### `aiot: command not found` - -Always run the local tool through npm: - -```bash -npm install -npm run build -``` - -Do not rely on a global `aiot` installation. - -### Dependency installation fails - -Clear only this project's installed dependencies and retry: - -```bash -rm -rf node_modules -npm install -``` - -If you use a company proxy, configure npm for that proxy instead of disabling TLS verification. - -### No `.rpk` appears - -Read the first compiler error, then verify: - -```bash -npx aiot build -h -find src -maxdepth 4 -type f -print -``` - -The required files are `src/manifest.json`, `src/app.ux`, and the routed page component. - -### Release build says signing files are missing - -Run the OpenSSL command in section 4 and confirm: - -```bash -test -s sign/private.pem && test -s sign/certificate.pem && echo 'Signing files exist' -``` - -## Official references - -- Xiaomi Vela JS documentation: -- Project structure: -- Manifest configuration: -- Compiler parameters: -- UI introduction: - -The project intentionally uses only the public `aiot-toolkit` command-line package. It does not require Xiaomi AIoT-IDE. +- `fresh` never initialized → first digit appended to '0' ('01') +- `=` with no pending op zeroed the display +- Operators didn't auto-evaluate pending ops (2+3×4 gave 12, not 20) +- Repeated `=` didn't re-apply the last op (2+3== gave 5, not 11)