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
2.2 KiB
2.2 KiB
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,.rpkrelease 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-JSaiot releasewith signed RPK — works on the S4. Generichap-toolkitdid not. - Critical fix: every
.uxpage must contain<script>export default {}</script>; a bare/static page throwsCannot read properties of undefined (reading 'data')at launch. - Screen: 466×466 physical → set
config.designWidthto 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 (thecrownrotationchangedevent is HarmonyOS-only). - Template directives:
for="{{ v in list }}"(withtid),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.