vela-calculator/README.md

# Xiaomi Vela Hello World for Watch S4

This is the smallest practical Xiaomi Vela JS watch application. It shows two centered lines on a round black screen:

```text
Hello World!
Xiaomi Watch S4
```

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:

```bash
npm run release
find dist -maxdepth 1 -type f -name '*.release.*.rpk' -print
```

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.

## 5. Change the app

Edit `src/pages/index/index.ux`. For example, replace:

```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.