Zepp Theme

対象デバイス

ここで配っている文字盤は 480x480 の丸形 Amazfit 機を対象にしている。 targets のキーを 480x480-round にしているのはそのため。

実機で確認しているのは Amazfit Balance(無印)。

ペアリング中の端末の deviceSource は、Zepp アプリが .zpk を取りに来るときの リクエストに付いてくる(?userid=...&deviceSource=...) (Zepp アプリがリクエストのクエリに付けてくる)。 app.json の platforms にその値が無いとインストールできない。

#対応している機種

app.json の targets.480x480-round.platforms に入れている値。

機種 コードネーム deviceSource API Level
Amazfit Balance Monaco / MonacoWN / MonacoW 8519936 / 8519937 / 8519939 1.0〜3.7
Amazfit Balance 2 Lyon / LyonWN / LyonW 9568512 / 9568513 / 9568515 1.0〜5.0

API Level は公式ドキュメントの表と Zeus の定義で食い違う。 ビルドツールが見て いるのは Zeus の方なので、Balance 2 は 5.0 として扱ってよい。詳細は下記。

どちらも画面は丸形 480x480 で、レイアウトはそのまま共用できる。 CPU プラットフォームは別物(Monaco 系と Lyon 系)なので、zeus build が出す .zab の中には .zpk が 2 つ入る。どちらを配るかは .zab に入っている manifest.json を見れば分かる。

名前に *WN / *W が付くものは地域違い。全部書いておけばリージョンを気にしなくてよい。

#増やしたい場合

同じ 480x480 丸形なら、下記も platforms に足すだけで対象にできる(未検証)。

機種 deviceSource API Level
Amazfit Balance 2 XT 10486016 / 10486017 / 10486019 1.0〜5.0
Amazfit Balance Ultra 11075840 / 11075841 / 11092224 / 11092225 1.0〜5.0
Amazfit Balance 3 11141376 / 11141377 / 11141379 1.0〜5.0
Amazfit Balance 3 Ti 11145472 / 11145473 / 11145475 1.0〜5.0

この他に Cheetah Pro / T-Rex 3 / T-Rex Ultra 2 / Active Max / GTR 3 Pro なども 480x480 丸形。値は Zeus CLI のデバイス定義か公式のデバイス一覧で確認する。

node -e 'const d=require(process.env.ZU+"/config/device.js");
for (const e of Object.values(d.getDeviceConf().deviceTargets))
  if (e.screen?.width===480 && e.screen?.type==="r")
    console.log(e.deviceName.padEnd(24), (e.platforms||[]).map(p=>p.deviceSource).join(","))'

(ZU は @zeppos/zeus-cli/private-modules/zeppos-app-utils/dist のパス)

#設計上の値

  • designWidth: 480(px() の基準幅。実機と 1:1 になるので座標をそのまま書ける)
  • 中心座標: (240, 240)
  • 外周リングを描くなら半径 232 前後(端から 2px のセーフエリアを考慮して 238 以下)
  • プレビュー / cover 画像: 324x324
  • icon.png は任意サイズで置けば、ビルド時に 324 へ自動リサイズされる

#Amazfit Balance 2 の詳細

Zeus CLI 1.9.3 が内部に持つデバイス定義(zeus create 実行時にサーバーから更新される) と、公式のデバイス一覧の両方で確認した値。

Zeus のデバイス定義は ~/.zepp/.zeus_devices にキャッシュされる(expiredTime 付きの JSON、103 機種)。devices 配列の各要素が deviceSource 単位のメタ情報で、 以下はそこから取った生の値。

#基本情報

項目 値
製品名 Amazfit Balance 2
内部コードネーム Lyon
型番 A2429(Lyon / LyonWN)、A2430(LyonW)
画面形状 丸形(shape: "round" / st: "r")
解像度 480 x 480
Zepp OS バージョン 6.0
API Level 5.0
対応 API Level 範囲 min 1.0 / max 5.0
SoC MCU / メーカー ZPS(Zepp 自社)※初代 Balance は SOC / NXP
物理キー数 2
文字盤プレビュー画像 324 x 324
アイコン iconSize: 248
SecondaryWidget 対応 あり
NFC / 音声 両方あり
差分 OTA supportDiff: true
センサー等の capabilities gps / magnetometer / gyroscope / accelerometer / altimeter

#⚠ API Level は公式ドキュメントの表と食い違う

出典 Zepp OS API_LEVEL
Zeus のデバイス定義(~/.zepp/.zeus_devices、2025-05-12 更新) 6.0 5.0
公式デバイス一覧ページ 5.0 4.2

ビルドツールが見ているのは前者なので API_LEVEL 5.0 として扱ってよい。 ドキュメントのページ側が Zepp OS 6 への更新前の値のまま。 Zeus のキャッシュでは Balance 2 / 2 XT / 3 / 3 Ti / Balance Ultra / Cheetah 2 Ultra / Cheetah 2 Pro / T-Rex 3 / 3 Pro / T-Rex Ultra 2 / T-Rex Dual Solar / Active 3 Premium がまとめて apiLevel: 5.0 になっている (103 機種中 39 エントリ)。

実機側の API_LEVEL は Zepp アプリから確認できる (→ https://docs.zepp.com/docs/guides/tools/zepp-app/#query-the-device-api-level)。 ファームウェアが Zepp OS 6 に上がっていない個体では 4.2 のままなので、 配布するものに 5.0 の API を使うなら実機の値を見ておく。

#deviceSource

app.json の targets.<key>.platforms に書く値。

name deviceSource 備考
Lyon 9568512 中国本土版
LyonWN 9568513
LyonW 9568515

全部書いておけばリージョンを気にしなくてよい。

configVersion: "v3" なら deviceSource の代わりに形状と幅で指定することもできる:

"platforms": [{ "st": "r", "sr": "w480" }]

ただしこれだと丸形 480x480 の他機種(Balance / Balance 3 / Balance Ultra / Cheetah 2 Ultra / T-Rex Ultra 2 / Active Max / T-Rex 3 / T-Rex 3 Pro (48mm) / Cheetah Pro / GTR 3 Pro)も対象に含まれる。Balance 2 だけに絞るなら deviceSource を明示する。

#近い機種(参考)

Zeus のデバイス定義から。どれも 480x480 丸形・プレビュー 324x324。

機種 コードネーム API Level deviceSource
Amazfit Balance Monaco / MonacoWN / MonacoW 3.7 8519936* / 8519937 / 8519939
Amazfit Balance 2 Lyon / LyonWN / LyonW 5.0 9568512* / 9568513 / 9568515
Amazfit Balance 2 XT Warsaw / WarsawWN / WarsawW 5.0 10486016* / 10486017 / 10486019
Amazfit Balance 3 Dublin / DublinWN / DublinW 5.0 11141376* / 11141377 / 11141379
Amazfit Balance 3 Ti DublinTi / DublinTiWN / DublinTiW 5.0 11145472* / 11145473 / 11145475
Amazfit Balance Ultra Oslo / OsloWN 5.0 11075840* / 11075841
Amazfit Balance Ultra (3S) Oslo3S / OsloWN3S 5.0 11092224* / 11092225
Amazfit Cheetah 2 Ultra Munich3S / MunichWN3S 5.0 9978112* / 9978113

* は中国本土版。 公式デバイス一覧ページ側では Balance 3 / Balance Ultra が 4.4、Balance 2 が 4.2 と 古い値のままで、Balance 2 XT と Balance 3 Ti はそもそも載っていない。

補足: デバイス定義の iconSize は 248 だが、文字盤のビルドで実際に使われるのは previewSize 由来の 324([RESIZE] Succeed resize icon.png to target size 324)。

#使える API

API_LEVEL 5.0 なので、型定義(@zeppos/device-types 4.0.0 = 最大 4.2)に入っている API は全部使える。一覧は「API 一覧」にまとめてある。

#出典