文字盤 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