Zepp Theme

文字盤 API リファレンス

Zepp OS の文字盤から何が取れて、どう叩いて、何が出てくるかをまとめたもの。

項目はすべて「取れる値 / 叩き方 / 出てくるもの」の 3 点セットで書いてある。 「出てくるもの」は Amazfit Balance 実機(Zepp OS 3.0 / API 3.7)で実際に出た値。 実機で確かめていないものには「エミュ」と書いてある。

#値を取る 2 つの経路

hmSensor hmUI.data_type
読み方 hmSensor.createSensor(hmSensor.id.X).プロパティ ウィジェットの type に指定する
JS から読めるか 読める(整形・計算できる) 読めない(システムが勝手に描く)
更新 自前(タイマー or イベント) 自動
向き 自分で描画を作りたいとき 現在気温・湿度・UV など hmSensor に無い値

以下は特記しない限り hmSensor の話。

const sensor = hmSensor.createSensor(hmSensor.id.STEP)

createSensor は機種によっては null を返す。 使う前に確認すること。

const id = hmSensor.id.BPRESSURE
const s = id === undefined ? null : hmSensor.createSensor(id)
if (s) { /* 使う */ }

#時刻と日付

取れる値 — 日時、曜日、12/24 時間制。旧暦は日本語環境では取れない。

const time = hmSensor.createSensor(hmSensor.id.TIME)
time.year, time.month, time.day
time.hour, time.minute, time.second
time.utc            // ミリ秒
time.week           // 1〜7。起点が不明なので曜日計算には使わない
time.is24Hour       // 24 時間表示かどうか

出てくるもの

year 2026  month 11  day 16
hour 14  minute 19  second 47
utc 1794838787903
week 1
is24Hour true

曜日は week ではなく year / month / day から計算するほうが確実 (起点がドキュメントに無い)。Sakamoto 法の実装が hello-balance2 にある。

#旧暦(使えない)

time.lunar_year, time.lunar_month, time.lunar_day
time.lunar_solar_term     // 二十四節気
time.lunar_festival, time.solar_festival
time.getLunarMonthCalendar()

出てくるもの

lunar_year        "INVALID"
lunar_month       "INVALID"
lunar_day         "INVALID"
lunar_solar_term  "INVALID"
getLunarMonthCalendar()  {"day_count":30,"lunar_days_array":["","",…]}

プロパティとしては存在するが、実機でもエミュレーターでも中身は INVALID。 時計の言語が中国語なら入るのかもしれないが、確かめていない。


#体の値

#心拍

取れる値 — 現在値、安静時心拍、当日の推移、最高記録。

const heart = hmSensor.createSensor(hmSensor.id.HEART)
heart.current          // 測定していなければ 0
heart.last             // 最後に測れた値
heart.rest             // 安静時心拍
heart.today            // 0 時からの配列
heart.getMaxRecord()   // 最高記録

出てくるもの

current 0        ← その瞬間に測っていなければ 0
last    75
rest    62
today   [92, 86, 80, 90, 96, 97, …]
getMaxRecord()  {"time":0,"time_zone":8,"hr_value":87}

rest と today はドキュメントに無いが実機で値が入る。

#ストレス

const stress = hmSensor.createSensor(hmSensor.id.STRESS)
stress.current
stress.time
stress.getAllDayStress()     // 1 日ぶん(分単位の配列)
stress.getHourAverage()      // 24 個
stress.getDailyAverage()     // 7 個
stress.get7DayHourAverage()  // 7 日 × 24

出てくるもの

current 32
getHourAverage()   [0,0,0,0,0,0,0,0,0,0,60,0,0,80,0,0,0,0,0,90,0,0,0,0]   ← エミュ
getDailyAverage()  [0,60,0,80,0,0,90]                                      ← エミュ

履歴系はすべてドキュメントに無い。グラフを描くのに使える。 startSingleEvaluation() もあるが、これは計測を始めるので読み取りではない。

#血中酸素(SpO2)

const spo2 = hmSensor.createSensor(hmSensor.id.SPO2)
spo2.current
spo2.hourAvgOfDay    // 24 個
spo2.getRecordData() // [{time, spo2}, …]
spo2.getLastRecord() // {spo2, time}

出てくるもの

current 0     ← 測定直後でなければ 0
getRecordData()  [{"time":1794835187,"spo2":90},{"time":1794835547,"spo2":93},…]   ← エミュ
getLastRecord()  {"spo2":0,"time":0}

#体温

const temp = hmSensor.createSensor(hmSensor.id.BODY_TEMP)
temp.current                 // 0.01℃ 単位
temp.getAlldayTempValue()    // 1 日ぶんの配列

出てくるもの

current 3443      ← 34.43℃。手首の皮膚温

単位は 0.01℃。ドキュメントには単位の記載が無い。name は thermometer。

#睡眠

const sleep = hmSensor.createSensor(hmSensor.id.SLEEP)
sleep.getBasicInfo()        // {score, deepMin, startTime, endTime}
sleep.getSleepStageData()   // [{model, start, stop}, …]
sleep.getSleepStageModel()  // model の対応表
sleep.getSleepHrData()      // 睡眠中の心拍
sleep.getTotalTime()        // 分
sleep.isSleeping()
sleep.getShortSleep()       // 仮眠
sleep.get7DaysSleepData()   // 7 日ぶん

出てくるもの(エミュ)

getBasicInfo()       {"score":80,"deepMin":90,"startTime":25,"endTime":625}
getSleepStageModel() {"WAKE_STAGE":7,"REM_STAGE":8,"LIGHT_STAGE":4,"DEEP_STAGE":5}
getTotalTime()       549
getShortSleep()      [{"length":60,"start":701,"stop":761}, …]
get7DaysSleepData()  [null,null,null,null,{"averageHR":59,"score":80,…},null,{…}]

startTime / endTime は 0 時からの分。get7DaysSleepData() の 1 日は {averageHR, score, startTime, endTime, totalTime, sleepTime, wakeTime, remTime, lightSleepTime, deepSleepTime, stageDataArray, shortDataArray}。 getShortSleep() と get7DaysSleepData() はドキュメントに無い。


#運動

#歩数・カロリー・距離・立ち上がり

hmSensor.createSensor(hmSensor.id.STEP).current      // 歩数
hmSensor.createSensor(hmSensor.id.STEP).target       // 目標
hmSensor.createSensor(hmSensor.id.CALORIE).current   // kcal
hmSensor.createSensor(hmSensor.id.DISTANCE).current  // 距離(target なし)
hmSensor.createSensor(hmSensor.id.STAND).current     // 立った時間
hmSensor.createSensor(hmSensor.id.FAT_BURRING).current  // 脂肪燃焼(分)

出てくるもの(エミュ)

STEP      current 300    target 3000
CALORIE   current 300    target 200
DISTANCE  current 0

FAT_BURRING(綴り間違い)と FAT_BURNING は同じ id 19 を指す。どちらでも同じ。

#PAI

const pai = hmSensor.createSensor(hmSensor.id.PAI)
pai.dailypai, pai.totalpai
pai.prepai0 … pai.prepai6   // 過去 7 日
pai.prepai                  // 配列でも取れる(ドキュメントに無い)

#スポーツ

const sport = hmSensor.createSensor(hmSensor.id.SPORT)
sport.hrmax              // 最大心拍
sport.vo2max
sport.trainingLoad, sport.recoveryTime
sport.getHrZone()        // 心拍ゾーン
sport.getSportState()
sport.getSportRecord()

出てくるもの

hrmax 195
vo2max 0      trainingLoad 0     recoveryTime 0     ← 運動記録が無い端末では 0
getHrZone()   {"type":1,"rest":60,"range":[100,120,140,160,180,200]}   ← エミュ

getHrZone() の range は心拍ゾーンの境界。ドキュメントに無い。


#環境

#天気

取れる値 — 現在気温、当日の最高/最低、5 日予報、日の出入り、月の出入り。

const weather = hmSensor.createSensor(hmSensor.id.WEATHER)
weather.current, weather.high, weather.low
const f = weather.getForecastWeather()
f.cityName
f.forecastData.data[i]      // {high, low, index}
f.tideData.data[i].sunrise  // {hour, minute}
f.tideData.data[i].sunset
f.tideData.data[i].moonrise
f.tideData.data[i].moonset

出てくるもの

current 13    high 20    low 12
cityName (現在地の地名)
forecastData.data[0]  {"high":20,"low":12,"index":…}
sunrise 6:17    sunset 16:34
moonrise 11:45  moonset 22:11

エミュレーターでは current / high / low が undefined になる。実機では入る。 日の出入りが取れるので、昼夜で配色を変えるといったことができる。

現在の天気コード・湿度・UV は hmSensor には無い。hmUI.data_type を使う (→ 表示できる値)。

#気圧・高度

const baro = hmSensor.createSensor(hmSensor.id.BARO)
baro.pressure   // hPa
baro.altitude   // m

出てくるもの

pressure 1021    altitude 82

エミュレーターでは両方 undefined。 実機でだけ値が入る。 COMPASS 側にも pressure / altitude がある。

#方位

const compass = hmSensor.createSensor(hmSensor.id.COMPASS)
compass.direction           // "N" など。未校正だと "--"
compass.direction_angle     // 角度
compass.calibration_status  // 校正済みか
compass.mode

出てくるもの

direction "--"    direction_angle 0    calibration_status false

コンパスを使うには校正が要る。文字盤から校正はできない。

#加速度・ジャイロ・GPS

const acc = hmSensor.createSensor(hmSensor.id.ACCELERATOR)  // name は "acc"
acc.x, acc.y, acc.z, acc.mode

const gyro = hmSensor.createSensor(hmSensor.id.GYRO)
gyro.x, gyro.y, gyro.z

const gps = hmSensor.createSensor(hmSensor.id.GPS)
gps.latitude    // {direction, degrees, minutes, seconds}
gps.longitude
gps.pos_status

いずれも文字盤が動いているだけでは 0。start() が要るが、これは読み取りではない ので、消費電力と権限に注意すること。


#端末の状態

#バッテリー

const bat = hmSensor.createSensor(hmSensor.id.BATTERY)
bat.current   // %
bat.charge    // 充電中か
bat.status

出てくるもの(エミュ)

current 88    charge 1    status 0

#画面と AOD

const screen = hmSensor.createSensor(hmSensor.id.SCREEN)   // name は "jsScreen"
screen.status      // 点灯状態
screen.aod_mode    // AOD かどうか
screen.light       // 明るさ

出てくるもの

status 1    aod_mode false    light 4

aod_mode はドキュメントに無い。AOD の出し分けは本来 show_level を使うが、 こちらでも判定できる可能性がある(AOD 中に true になるかは未確認)。

#装着状態

hmSensor.createSensor(hmSensor.id.WEAR).current
// 0:未装着 1:装着中 2:運動中 3:不明

出てくるもの — 1(装着中)

#音楽

const music = hmSensor.createSensor(hmSensor.id.MUSIC)
music.title, music.artist, music.isPlaying

エミュレーター(Balance)では createSensor が null。実機では作れる。

#バイブの設定

const vib = hmSensor.createSensor(hmSensor.id.VIBRATE)
vib.strength, vib.intensity, vib.scene
vib.motorenable, vib.crowneffecton

読むだけなら安全。start() / stop() は実際に振動する。


#設定と端末情報

hmSetting は createSensor が要らない。そのまま呼ぶ。

#端末情報

hmSetting.getDeviceInfo()

出てくるもの(実機)

{
  "width": 480, "height": 480, "screenShape": 1,
  "deviceName": "Amazfit Balance",
  "deviceSource": 8519939,
  "keyNumber": 2, "keyType": "normal_21",
  "productId": 121, "productVer": 257, "skuId": 257,
  "pixelFormat": "PIXEL_FORMAT_RGB565",
  "hasNFC": false, "hasMic": false, "hasCrown": false,
  "hasBuzzer": false, "hasSpeaker": false,
  "uuid": "(端末ごとの固有値)"
}

deviceSource が取れるので、1 つの文字盤で機種ごとに分岐できる。 ドキュメントに載っているのは width / height / screenShape / deviceName くらい。

#システム情報

hmSetting.getSystemInfo()   // {osVersion, sdkVersion, minAPI, hwVersion, algoVersion}
hmSetting.getDiskInfo()     // {total, free, app, watchface, watchfaceInSystem, music, system}
hmSetting.getSystemMode()   // おやすみ・シアター・省電力など
hmSetting.getDisplayInfo()  // 画面と手首上げ・常時表示の設定
hmSetting.getOTAState()

出てくるもの(実機)

getSystemInfo()  {"osVersion":"4","sdkVersion":"3.7","minAPI":"2.0",
                  "hwVersion":"…","algoVersion":"18.10.91.06"}
getSystemMode()  {"DND":false,"sleep":false,"theater":false,"systemLock":false,
                  "lowTemperature":false,"powerSaving":false,"ultraPowerSaving":false,
                  "button":false,"accessibleSwitch":false}
getDisplayInfo() {"screen":{"status":1,"duration":10},
                  "wrist":{"speed":0,"model":2,"startTime":480,"stopTime":1320},
                  "standby":{"style":1,"model":0,"startTime":480,"stopTime":1320}}

osVersion は OS のバージョンではない(Zepp OS 3.0 の実機が "4" を返す)。 API Level と一致するのは sdkVersion のほう。

getSystemMode() / getDisplayInfo() / getDiskInfo() / getOTAState() は どれもドキュメントに無いが、実機で動く。

#ユーザーと単位

hmSetting.getUserData()         // {age, height, weight, gender, nickName, region, birth, …}
hmSetting.getLanguage()
hmSetting.getTimeFormat()       // 1 = 24 時間
hmSetting.getDateFormat()
hmSetting.getWeightUnit(), getMileageUnit(), getTemperatureUnit()
hmSetting.getBrightness()
hmSetting.getScreenAutoBright()
hmSetting.getScreenType()       // APP / WATCHFACE / SETTINGS / AOD

set*(setBrightness など)もあるが、文字盤から端末設定を書き換えないこと。

#アプリ情報

hmApp.getPackageInfo()

出てくるもの(抜粋)

{
  "name": "API Probe", "appId": 8800003, "type": "watchface",
  "version": "1.0.0", "versionCode": 1,
  "rootPath": "/storage/data/js_watchfaces",
  "appPath": "00864703",
  "assets": "/storage/data/js_watchfaces/00864703/assets",
  "userPath": "/storage/data/js_watchfaces/data/00864703",
  "designWidth": 480,
  "mode": "development",
  "expiredTime": 172800
}

zeus dev で入れたものは mode: "development" と expiredTime(48 時間)が付く。 .zpk を配信して入れたものには付かない。


#更新のしかた

// 1 秒ごとに読みに行く(確実)
this.timer = timer.createTimer(0, 1000, () => this.refresh(), {})
timer.stopTimer(this.timer)   // onDestroy で止める

// 変化イベント(対応しているセンサーのみ)
step.addEventListener(hmSensor.event.CHANGE, () => { /* … */ })
heart.addEventListener(hmSensor.event.LAST, cb)
heart.addEventListener(hmSensor.event.CURRENT, cb)

CHANGE が使えるのは CALORIE / DISTANCE / STAND / SPO2 / STRESS / FAT_BURRING / STEP / BATTERY / MUSIC / WEAR。それ以外はタイマーで読みに行く。 addEventListener したものは onDestroy で removeEventListener すること。

timer.createTimer は引数が 4 つ(option を省略できない)。


#使えるかどうか

初代 Balance 実機 Balance エミュ Balance 2 エミュ
作れたセンサー 31 / 36 26 / 36 28 / 36
作れないもの SUN WIND PRESS BUZZER GLUCOSE 左に加えて WORLD_CLOCK MUSIC BPRESSURE BODY_COMPOSITION SOUND 左とほぼ同じ

エミュレーターで null だから実機で使えない、とは限らない。 WORLD_CLOCK / MUSIC / BPRESSURE / BODY_COMPOSITION / SOUND は 実機でだけ作れた。逆に GLUCOSE は Balance 2 エミュレーターでだけ作れた。

checkAvailable() はどのセンサーでも false を返したので、可用性の判定には使えない。

実機に無い API もある。

実機 Balance 2 エミュ
hmSetting.getFontSizeInfo() × ○
hmApp.getProfile() × ○
timer.createSysTimer × ○

公開されていない API は OS 更新で黙って消える可能性がある。使う前に typeof で 確認し、無ければ代替を出すこと。

const v = typeof s.rest === 'undefined' ? '--' : s.rest

#出典