| name | zepp-os-device-system |
| description | Use when handling watch-side hardware input or system info in a Zepp OS device app - reading physical buttons or digital crown, detecting wrist-raise / wrist-motion / gestures, showing a toast or a modal / confirm dialog, reading screen shape or device info, reading the user's system preferences (12h/24h time format, units, language, mode), loading i18n .po files, referencing asset image paths, or using EventBus / log / assets / px helpers and stringToBuffer / bufferToString (string ↔ ArrayBuffer). Use even when the task sounds generic ("show a confirm dialog", "read the language setting", "convert a string to a buffer") - Zepp OS has its own @zos/interaction, @zos/settings, @zos/device, @zos/i18n, @zos/utils APIs. Do not use for sensor / health data (zepp-os-sensors), page navigation (zepp-os-navigation-lifecycle), persistent storage (zepp-os-settings-storage), drawing UI widgets (zepp-os-ui), watchface rendering (zepp-os-watchface), or declaring permissions in app.json (zepp-os-fundamentals). |
Zepp OS Device System & Utilities
Context: Device App + Watchface (watch-side).
API_LEVEL: 2.0+.
Prereq: permissions in app.json — see zepp-os-fundamentals.
Overview
A grab-bag of small but essential watch-side modules: query the device, react to hardware input, read the user's system preferences, localize, and use core helpers.
| Module | What it's for |
|---|
@zos/device | device info: getDeviceInfo() (width/height/screenShape), getDiskInfo() |
@zos/interaction | hardware input + toast/modal |
@zos/settings | the user's system preferences (units, formats, language, mode) |
@zos/i18n | localized strings from .po files |
@zos/user | getProfile() (data:user.info), addHealthData() (data:user.health) |
@zos/display | brightness / display settings |
@zos/utils | EventBus, log, assets, px, stringToBuffer/bufferToString |
Device info
import { getDeviceInfo, SCREEN_SHAPE_SQUARE } from '@zos/device'
const { width, height, screenShape, deviceName } = getDeviceInfo()
if (screenShape === SCREEN_SHAPE_SQUARE) { }
Use screenShape/width for runtime layout decisions (alongside px() — see zepp-os-ui).
Hardware input (@zos/interaction)
- Physical buttons:
onKey / offKey.
- Digital crown:
onDigitalCrown / offDigitalCrown.
- Gestures:
onGesture / offGesture — e.g. intercept a right-swipe gesture.
- Wrist motion:
onWristMotion [≥3.0].
- Feedback:
showToast({ content }), createModal(...).
(Haptics live in @zos/sensor Vibrator — see zepp-os-sensors.)
System preferences (@zos/settings)
Read what the user has configured system-wide: getLanguage, getTimeFormat, getDateFormat, getDistanceUnit, getTemperatureUnit, getWeightUnit, getSystemMode, getSystemInfo, getSleepTarget, getWeightTarget. Respect these instead of hard-coding (e.g. 12h vs 24h, km vs mi).
Internationalization (@zos/i18n)
import { getText } from '@zos/i18n'
const label = getText('appName')
.po files can be placed at app-level (i18n/<locale>.po) or per-module (page/i18n/, app-side/i18n/, setting/i18n/<locale>.po); defaultLanguage is set in app.json (see zepp-os-fundamentals). The active device language is read via @zos/settings getLanguage (above).
Utilities (@zos/utils)
EventBus — in-app publish/subscribe to decouple modules.log.getLogger(name) — structured logging (logger.log/warn/debug/error/info).assets(path) — resolve a resource path under the active target's assets/.px(n) — scale from designWidth (core of screen adaptation, see zepp-os-ui).stringToBuffer / bufferToString [≥4.0] — convert for the binary messaging layer (see zepp-os-communication).
Common Mistakes
- Hard-coding 24h time or metric units → read
@zos/settings (getTimeFormat, getDistanceUnit, …) and follow the user's choice.
- Hard-coding visible strings → use
@zos/i18n getText + .po files.
- Assuming
vibrate is in @zos/interaction → it's the Vibrator sensor in @zos/sensor.
- Re-implementing pub/sub or buffer conversion → use
@zos/utils EventBus and stringToBuffer/bufferToString.
- Forgetting
data:os.device.info for getDeviceInfo().
- Forgetting user-data permissions →
getProfile() needs data:user.info; addHealthData() needs data:user.health.
.po file template
# page/i18n/en-US.po (filename = locale, e.g. en-US, zh-CN)
msgid "appName"
msgstr "My App"
msgid "calories"
msgstr "Calories"
Look up with getText('appName'). Set defaultLanguage in app.json; place .po files app-level (i18n/<locale>.po) or per-module (page/i18n/, setting/i18n/).
Reference
