zepp-os-communication

name	zepp-os-communication
description	Use when sending data between a Zepp OS device app and its phone side service, making HTTP/fetch requests, downloading or transferring files to the watch, or talking to external BLE peripherals.

Zepp OS Communication

Context: Device App ↔ Side Service (over Bluetooth) + Side Service networking API_LEVEL: 2.0+ (ZML layer is the modern norm on 3.0/4.0 samples) Prereq: the four runtime contexts — see zepp-os-fundamentals.

Overview

The watch has no direct internet. The device app (watch) and the side service (companion JS on the phone) talk over Bluetooth, exchanging binary only — you serialize yourself. Three layers sit on top of that transport; pick one and use it on both sides.

Which API on which side (the core confusion)

	Device App (watch)	Side Service (phone)
Raw transport	@zos/ble — send / addListener	messaging.peerSocket — send / addListener('message')
Data form	ArrayBuffer only	ArrayBuffer only
HTTP / fetch	❌ not available	✅ here only

fetch lives only in the side service. Calling it from the device app is the #1 mistake.

Three layers (choose one)

1. Raw — @zos/ble (device) + messaging (side). Maximum control, you hand-roll JSON↔Buffer. Verbose.
2. MessageBuilder [shared/message.js + shared/message-side.js] — older helper: messageBuilder.request().then(), .on('call'), .call(), .on('request', ctx => ctx.response()). Requires a polyfill import and manual connect()/disConnect() (disconnect in onDestroy or you leak).
3. ZML — @zeppos/zml (recommended; used in current samples). Wrap App/Page/AppSideService and get request/response for free. Use this unless you have a reason not to.

ZML quickstart (recommended)

// app.js — device
import { BaseApp } from "@zeppos/zml/base-app";
App(BaseApp({ globalData: {}, onCreate() {}, onDestroy() {} }));

// page/.../index.js — device: request → side, await response
import { BasePage } from "@zeppos/zml/base-page";
Page(BasePage({
  build() { /* ... */ this.fetchData(); },
  fetchData() {
    this.request({ method: "GET_DATA" })
      .then((data) => { const { result } = data; /* render with @zos/ui */ })
      .catch((e) => {});
  },
}));

// app-side/index.js — side: handle request, fetch, reply via res(err, data)
import { BaseSideService } from "@zeppos/zml/base-side";
AppSideService(BaseSideService({
  onInit() {},
  onRequest(req, res) {
    if (req.method === "GET_DATA") {
      fetch({ url: "https://api.example.com/x", method: "GET" })
        .then((r) => { const body = typeof r.body === "string" ? JSON.parse(r.body) : r.body;
                       res(null, { result: body }); })
        .catch(() => res(null, { result: "ERROR" }));
    }
  },
  onDestroy() {},
}));

Push from side → device: this.call(data) on the side, receive with this.onCall(data) on the device.

fetch (side service only)

• GET shorthand: await fetch('https://…'). Full form: fetch({ url, method, headers, body }) — only those 4 keys.
• res.body may be a JSON string on some devices — always guard: typeof body === 'string' ? JSON.parse(body) : body.

Files

• Download a network file to the phone [side]: network.downloader.downloadFile({ url, timeout, headers, filePath }) → DownloadTask with onProgress/onSuccess/onFail/onComplete. Defaults to data://download/.
• Send a file phone → watch [side→device]: side transferFile.getOutbox().enqueueFile(path, params); device transferFile.getInbox().getNextFile(). Listen to progress/change (readyState === 'transferred' | 'error'). See references/transfer-file-*.md.

External BLE peripherals

Talking to a third-party BLE device (not the phone) uses @zos/ble central/master APIs (mstStartScan, mstConnect, mstBuildProfile, mstReadCharacteristic, mstWriteCharacteristic, …). That is separate from device↔phone messaging. Full API: references/ble-device.md.

Common Mistakes

• fetch() in the device app → not available. Do it in the side service, return via res()/response.
• Mixing layers (raw messaging on one side, ZML on the other) → they won't talk. Same layer on both ends.
• Using @zos/ble on the side service or messaging on the device → swapped APIs. Device = @zos/ble, side = messaging.
• Forgetting to call res(err, data) in ZML onRequest → the device request() promise never resolves.
• Not handling res.body as a possible string → JSON.parse errors on some models.
• Manual MessageBuilder without disConnect() in onDestroy → memory leak.
• Sending JS objects over the raw layer → only ArrayBuffer is supported; serialize first.
• Persisting config? that's settings-storage, shared between side service and settings app — see zepp-os-settings-storage, not this skill.

File transfer checklist (side→device)

Progress:

• Side: obtain the file path (e.g. network.downloader.downloadFile({...}) → data://download/).
• Side: transferFile.getOutbox().enqueueFile(path, params).
• Side: listen to progress / change to track readyState.
• Device: on the inbox change/file event, transferFile.getInbox().getNextFile().
• Device: handle readyState === 'transferred' (success) vs 'error'. See references/transfer-file-side.md / transfer-file-device.md.

Reference

• references/messagebuilder.md — MessageBuilder end-to-end
• references/zml.md — ZML request/call helpers
• references/messaging-side.md · references/fetch.md · references/download-file.md
• references/transfer-file-side.md · references/transfer-file-device.md
• references/ble-device.md — @zos/ble index (split: connection · scan · profile · characteristic · descriptor)
• Example: examples/zml-request-response.md