Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 codex-bot
|
a52d8f7de4 |
@@ -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
|
||||
<text class="hello">Hello World!</text>
|
||||
```
|
||||
|
||||
with:
|
||||
|
||||
```xml
|
||||
<text class="hello">My first app</text>
|
||||
```
|
||||
|
||||
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 `<text>` 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: <https://iot.mi.com/vela/quickapp/en/>
|
||||
- Project structure: <https://iot.mi.com/vela/quickapp/zh/guide/start/project-overview.html>
|
||||
- Manifest configuration: <https://iot.mi.com/vela/quickapp/zh/guide/framework/manifest.html>
|
||||
- Compiler parameters: <https://iot.mi.com/vela/quickapp/zh/guide/start/toolkit-params.html>
|
||||
- UI introduction: <https://iot.mi.com/vela/quickapp/zh/guide/start/user-interface.html>
|
||||
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user