codex-bot
5ba2f24a6e
- SKILL.md: toolchain, project structure, round-screen layout, TDD harness, input/crown findings, per-app notes - references: gitea-publish workflow, S4 session log, historical nyan-watch notes - README: overview + key facts
31 lines
2.2 KiB
Markdown
31 lines
2.2 KiB
Markdown
# Vela Quick App Development
|
||
|
||
A developer skill and knowledge base for building **VelaJS quick apps** for Xiaomi watches — specifically the **Xiaomi Watch S4 41mm** (466×466 round AMOLED).
|
||
|
||
This repo documents everything learned while building working third-party apps for the S4: the working toolchain, the gotchas that caused black-screen crashes, the round-screen layout math, the input-event reality (including the crown question), and the TDD harness used to test `.ux` page logic without a device.
|
||
|
||
## Contents
|
||
|
||
- **`SKILL.md`** — the main skill: workflow discipline, project structure, build toolchain, confirmed observations, round-screen layout, TDD technique, input/crown findings, and per-app notes.
|
||
- **`references/gitea-publish.md`** — how the built apps are published to self-hosted Gitea (repo creation, `.rpk` release assets, issues).
|
||
- **`references/watch-s4-session-log.md`** — chronological debugging log from the S4 dev session.
|
||
- **`references/nyan-watch-example.md`** — historical notes from early failed experiments (superseded; kept for reference).
|
||
|
||
## The apps built with this skill
|
||
|
||
| Repo | App | Package |
|
||
|---|---|---|
|
||
| `vela-sundial` | Solar-path dial watch face | `com.ilias.sundial` |
|
||
| `vela-snake` | Snake game | `com.ilias.snake` |
|
||
| `vela-calculator` | Round-screen calculator | `com.example.hellovela` |
|
||
|
||
## Key facts (tl;dr)
|
||
|
||
- **Toolchain:** `aiot-toolkit` (2.0.5), plain-JS `aiot release` with signed RPK — works on the S4. Generic `hap-toolkit` did not.
|
||
- **Critical fix:** every `.ux` page must contain `<script>export default {}</script>`; a bare/static page throws `Cannot read properties of undefined (reading 'data')` at launch.
|
||
- **Screen:** 466×466 physical → set `config.designWidth` to **466** (not the 480 default) or layout renders ~3% undersized/off-center.
|
||
- **Input:** `click`, `longpress`, `touchstart/move/end`, `swipe`, `onBackPress()`. **Crown rotation is NOT exposed** on Vela (the `crownrotationchanged` event is HarmonyOS-only).
|
||
- **Template directives:** `for="{{ v in list }}"` (with `tid`), `if`/`elif`/`else`, `show`.
|
||
|
||
This is a living document — treat it as notes with provenance, not as a spec. Claims that say "unverified" or "not confirmed" mean exactly that.
|