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:

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:

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:

node --version
npm --version

2. Understand the tiny project

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:

npm install
npm run build

The important output is created under dist/ and ends in .debug.rpk:

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:

npm run build:source-map

To see every compiler option supported by your installed toolkit:

npm run help

4. Create a signed release RPK

The release builder expects these two files:

sign/private.pem
sign/certificate.pem

Generate a local development certificate from the project root:

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:

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:

<text class="hello">Hello World!</text>

with:

<text class="hello">My first app</text>

Then rebuild:

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:

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:

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:

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:

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.