zepp-os-background-scheduling

name	zepp-os-background-scheduling
description	Use when running Zepp OS code in the background or scheduling something for later - an app-service that runs independently of the foreground page (@zos/app-service, for tallying activity all day, etc.), waking the app at a wall-clock time or recurring schedule (@zos/alarm, "wake up at 8am every morning"), running a callback every N ms even when the screen is off (@zos/timer createSysTimer), posting a notification to the watch notification center (@zos/notification, "push a notification when the timer finishes"), or reacting to system events like sleep / shutdown / wake (app-event module). Use even when the wording is generic ("run later", "send a notification", "schedule a one-off task in 10 minutes", "run all day in the background") - this is the right skill for any deferred or background execution on the watch. Do not use for sending data from the phone side service to the watch (zepp-os-communication).
compatibility	Zepp OS Device App + App Service (both on the watch). Requires API_LEVEL >=3.0 for app-service/alarm/notification; createSysTimer requires >=4.0. Declare the app-service module and permissions in app.json.

Zepp OS Background & Scheduling

Context: Device App + App Service (both on the watch). API_LEVEL: [≥3.0] for app-service/alarm/notification; createSysTimer is [≥4.0]. Prereq: declaring the app-service module + permissions in app.json — see zepp-os-fundamentals.

Overview

Four tools, each for a different "later":

Need	Tool	Permission	Level
Run logic in the background, independent of the foreground page	@zos/app-service	device:os.bg_service	[≥3.0]
Wake the app at a wall-clock time (survives app exit)	@zos/alarm	device:os.alarm	[≥3.0]
Run a callback every N ms, even when the screen is off	@zos/timer createSysTimer	—	[≥4.0]
Post a notification to the watch's notification center	@zos/notification	device:os.notification	[≥3.0]

App Service — the background runtime

Configured via module.app-service in app.json. Runs separately from any page.

import { start, stop, getAllAppServices, exit } from '@zos/app-service'
start({
  file: 'app-service/my-service',
  param: 'optional',
  complete_func: ({ result }) => console.log(result),
})                                                            // launch from a page
getAllAppServices()                                       // query running services
// inside the service:
exit()                                                    // stop self, foreground page unaffected

Use it for work that must continue when the page closes (data sync, polling, long timers).

Timers — two different things, don't confuse them

• JS setTimeout/setInterval — only while the JS context is alive; dies when the page/screen sleeps.
• @zos/timer createSysTimer(periodic, periodMs, cb, arg) / stopTimer [≥4.0] — system-level; registered in an app service it keeps firing regardless of screen state. Use this for reliable background intervals. stopTimer(id) cancels it.

import { createSysTimer } from '@zos/timer'
const id = createSysTimer(true, 10000, () => {/* every 10s, even screen-off */})

Alarms — wake the app at a time

@zos/alarm sets persistent alarms that wake a Mini Program page at a wall-clock time, surviving app exit.

import { set, cancel, REPEAT_DAY } from '@zos/alarm'
const id = set({ url: 'pages/index.js', time: 1699999999, repeat_type: REPEAT_DAY })
cancel(id)

Repeat constants: REPEAT_ONCE/MINUTE/HOUR/DAY/WEEK/MONTH/YEAR; weekday WEEK_MON…WEEK_SUN. List with getAllAlarms().

Notifications

@zos/notification notify(option) posts to the Watch Notification Center; cancel removes it. Permission device:os.notification.

Common Mistakes

• Relying on setInterval for background work → it stops when the screen sleeps. Use createSysTimer in an app service.
• Skipping permissions → device:os.bg_service (service), device:os.alarm (alarm), device:os.notification (notify) must be in app.json.
• Confusing alarm with timers → alarm wakes the app at a clock time and persists across exit; timers only run while something is alive.
• Not declaring module.app-service in app.json → start() has nothing to launch (see zepp-os-fundamentals).
• Doing heavy background work on the phone side → these are watch-side APIs; phone networking is the side service (zepp-os-communication).

App Service setup

Progress:

• app.json: declare module.app-service (entry file under app-service/) and add device:os.bg_service permission.
• From a page, launch with start({ file: 'app-service/<name>', param, complete_func }).
• Inside the service, do the background work; for reliable intervals use createSysTimer [≥4.0], not setInterval.
• Stop cleanly: exit() from inside the service, or stop() from a page; inspect with getAllAppServices().
• Keep it light — heavy/network work belongs in the phone side service (zepp-os-communication), not here.

Reference

• references/app-service.md · app-service-guide.md · system-event.md
• references/alarm.md · timer.md · notification.md
• Signatures: npm @zeppos/device-types