How To Extract Health Data from Amazfit Smartwatches to a Web Server

[MyoungXUE]

Intro

First, let me introduce why we chose this topic.

1. The Zepp OS Mini Program architecture is slightly complex and involves many concepts. I have always hoped to create a special topic to explain it all at once.
2. Many developers have been concerned about how to extract health data to their own server.

So, I combined the above two ideas and prepared this workshop. I believe the content will be very rich.

At the end of the beginning, I will introduce today's expected harvest.

1. Fully understand the architecture and communication relationship of Zepp OS Mini Program
2. Demonstrate a complete Mini Program example, get sleep data, and send it to a Web Server

Architecture

I redraw the architecture diagram of the Mini Program. Our main purpose of this workshop is to understand this picture.

The complete Mini Program includes Device App, Settings App and Side Service.

• Device App
  • The Device App runs on a watch device
  • The operating system of the watch device is Zepp OS
  • The Device App can call the widget API to draw UI and call a series of sensors to obtain data
• Settings App(optional)
  • Settings App runs in the Zepp App on mobile devices
  • Settings App draws UI by calling render function
• Side Service(optional)
  • Side Service runs in the Zepp App on mobile devices
  • Side Service can communicate with external servers through Fetch API

Communication Relationship

Let's sort out the communication relationship together. BLE and SettingsStorage are more complex, and we will explain them separately.

BLE

BLE is used for communication between Device App and Side Service. The underlying BLE API is not user-friendly, so we provide the MessageBuilder library.

The part of MessageBuilder can refer to this document, and the todo-list Mini Program example. That's not our focus today.

• https://docs.zepp.com/docs/guides/best-practice/bluetooth-communication/
• https://github.com/zepp-health/zeppos-samples/tree/main/application/1.0/todo-list

Today, we will introduce ZML. ZML is a more user-friendly Bluetooth communication library. Just last week, ZML supported API_LEVEL 2.0, making it possible to use the ZML communication API on more devices. Now we can use it on GTR4 running Zepp OS v2.

We use this.request method to send messages in Device App and onRequest to receive messages in Side Service.

And we use this.call method to send messages in Side Service and onCall to receive messages in Device App.

Settings Storage

Communication between Settings App and Side Service relies on Settings Storage.

To facilitate the display of data relationships, two Settings Storage are drawn in the figure, which are actually the same thing.

The API of Settings Storage is very simple, use setItem to set data and getItem to get the value.

So when we use setItem to set data in the Settings App, how do Side Service respond to data changes?

• Settings App -> Side Service (the red line)
  1. Use addListener API in Side Service to register callback function to listen to data changes in Settings Storage
  2. Use setItem to change data in the Settings App and trigger the registered callback function

When we use setItem to set data in the Side Service, automatically call Settings App build lifecycle, redraw UI.

• Side Service -> Settings App (the blue line)
  1. Use setItem to change data in the Side Service
  2. Settings Storage detects that data has changed, automatically triggers the re-rendering of the Settings App, and executes the build lifecycle again

Full Example: post-health-data

https://github.com/zepp-health/zeppos-samples/tree/main/application/2.0/post-health-data

The logic of the post-health-data Mini Program is very simple. The Device App obtains sleep information and posts data to a Web Server.

The same logic is also implemented in the Settings App.

The server code is in the /Server directory, using Node.js implementation, the database uses MongoDB, a free Altas service.

Although the Mini Program looks very simple, it includes all the communication links mentioned above.

Action 1: Get Sleep Data

In this action, call the Sleep sensor, obtain data, and use the TEXT widget for drawing UI.

getSleepData() {
  if (!this.state.sleepInstance) {
    this.state.sleepInstance = new Sleep();
    this.state.timeInstance = new Time();
  }

  const info = this.state.sleepInstance.getInfo();

  this.state.sleepData = {
        ...info,
        utc: this.state.timeInstance.getTime(),
      };

  const { score, deepTime, startTime, endTime, totalTime, utc } =
    this.state.sleepData;
  const text = `utc: ${utc}\nscore: ${score}\ndeepTime: ${deepTime}\nstartTime: ${startTime}\nendTime: ${endTime}\ntotalTime: ${totalTime}`;

  if (!this.state.textWidget) {
    this.state.textWidget = createWidget(widget.TEXT, {
      x: (DEVICE_WIDTH - px(400)) / 2,
      y: px(48),
      w: px(400),
      h: px(200),
      text_size: px(22),
      align_h: align.CENTER_H,
      align_v: align.CENTER_V,
      text,
      color: 0xffffff,
    });
  } else {
    this.state.textWidget.setProperty(prop.TEXT, text);
  }
}

Action 2: Post Data

When we click the post data button, sleep data is sent from the Device App to the Side Service and post to the server.

We use the this.request method in the Device App to post messages to the Side Service.

// Device App
postSleepData() {
  console.log("device app post");

  this.request({
    type: "UPLOAD",
    params: {
      ...this.state.sleepData,
    },
  }).then((data) => {
    const { message } = data;

    showToast({ content: `UPLOAD ${message}` });
  });
},

Use the onRequest method in Side-service to receive information, and then request the web server interface through FetchAPI.

// Side Service
AppSideService(
  BaseSideService({
    async onRequest(req, res) {
      const { type, params } = req;

      if (type === "UPLOAD") {
        console.log(params);

        settings.settingsStorage.setItem("sleepData", JSON.stringify(params));

        const result = await this.postData();

        res(null, result);
    },
    async postData() {
      console.log("service postData");

      const res = await fetch({
        url: "http://localhost:4080/sleep",
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: settings.settingsStorage.getItem("sleepData"),
      });

      console.log(JSON.stringify(res.body));

      return res.body;
    },
  })
);

Action 3: Request Sleep Data From Device App

After clicking the button, the Settings App starts a request to the Device App to obtain sleep data.

How to implement this feature? Settings App cannot communicate directly with Device App. Here we need to use Side Service to connect the two.

First, use addListener to listen to Settings Storage in the Side Service, then initiate an action in the Settings App to change the value of Settings Storage, In this way, you can respond to this action in the Side Service.

We use this.call to communicate with Device App in the callback of the Side Service addListener function.

// Side Service
AppSideService(
  onInit() {
    settings.settingsStorage.addListener(
      "change",
      async ({ key, newValue, oldValue }) => {
        if (key === "REQUEST_ACTION") {
          this.call({ type: "SETTINGS_APP_REQUEST_DATA" });
        }
      }
    )
  }
)

// Settings App
requestData(props) {
  const current = props.settingsStorage.getItem("REQUEST_ACTION");

  props.settingsStorage.setItem("REQUEST_ACTION", !current);
},

// Device App
Page(
  BasePage({   
    onCall(data) {
      console.log("data", data);
      this.responseCall(data);
    },
    responseCall(data) {
      const { type = "" } = data;

      if (type === "SETTINGS_APP_REQUEST_DATA") {
        this.getSleepData();

        this.request({
          type: "UPLOAD_DATA_SIDE_SERVICE",
          params: {
            ...this.state.sleepData,
          },
        }).then((data) => {
          const { message } = data;

          showToast({ content: `UPLOAD_DATA_SIDE_SERVICE ${message}` });
        });
      }
    },
  })
);

Action 4: Post Data To Web Service

After clicking the button, the Settings App starts a request to the Side Service to upload sleep data.

The principle is the same as Action 3. The Side Service uses addListener to listen to Settings Storage. The value of Settings Storage is modified in the Settings App. To distinguish the behavior, we change the name of the key this time.

// Settings App
postData(props) {
  const current = props.settingsStorage.getItem("POST_ACTION");

  props.settingsStorage.setItem("POST_ACTION", !current);
},

// Side Service
onInit() {
  settings.settingsStorage.addListener(
    "change",
    async ({ key, newValue, oldValue }) => {
      if (key === "REQUEST_ACTION") {
        this.call({ type: "SETTINGS_APP_REQUEST_DATA" });
      } else if (key === "POST_ACTION") {
        this.postData();
      }
    }
  );
},

So far, we have practiced all communication ways. This example is simple enough and I believe it will be understood soon.

Some tips for reporting health data

1. Currently, most health-related sensor data supports obtaining data for the same day. You can use the API to wake up the Mini Program at a scheduled time, obtain and report data
   • Alarm API
   • setLaunchAppTimeout
2. If you need to continuously report data, your Mini Program needs to run continuously and can not exit.

[Mphil99]

Great share!

[fume113]

hello, im having problem and i dont know how to solve, the error is

info [DEBUG-8:18:14 PM.619] I>0>14.208 quickjs- SBEngine current filepath: /app.js
info [DEBUG-8:18:14 PM.805] I>0>14.394 quickjs- SBEngine Mini Program Error TypeError: cannot read property 'setTimeout' of undefined
info [DEBUG-8:18:14 PM.810] I>0>14.399 quickjs- SBEngine error stack at (/storage/data/js_apps/00006899/app.js:38)
I>0>14.400 quickjs- S
info [DEBUG-8:18:14 PM.811] I>0>14.400 quickjs- SBEngine error stack at (/storage/data/js_apps/00006899/app.js:785)
info [DEBUG-8:18:14 PM.811] I>0>14.400 quickjs- SBEngine error stack

im trying to find "setTimeout" but there is no setTimeout in program
i used ZML 0.0.9

any idea?

[MyoungXUE]

Thank you for your feedback, I will adjust the problem code.

[fume113]

sorry for bothering but thank you for help, ill be waiting...

[MyoungXUE]

I know where the problem is. @zeppos/zml is the npm dependency of the project and needs to be installed. Please use the 'npm i command in the app.json directory of the project to install it.

Please refer to this document for details https://docs.zepp.com/docs/guides/tools/npm/#install-npm

[fume113]

thank you for your answer, ill try it <3

[fume113]

its working, thank you so much

[miguelavh]

Great work!! One question, is It possible to uplpad data with app-service every minute, instead button click?

Thank you

[shuraman69]

Any update? Did you resolve it? How? 🙌

[shuraman69]

@miguelavh

[miguelavh]

Yeah It works, I have follow this example and all works... https://gitlab.aiursoft.cn/anduin/sleepagent/