An introduction to development on Mi band 7

4 min readNov 20, 2023

It seems like the Mi Band 7 is a special one, different from all the other bands by Xiaomi. It’s the only one that allows for custom apps to be written and installed by the user.

This was something I didn’t know when buying the smartwatch and it was an amazing revelation when I found some apps on the internet.

Coding and installing the apps is not a complicated process and it does not require any modification to the band, unfortunately, it is plagued by a complete lack of official documentation or development tools.
Most of the resources I found on my quest to make a simple app on the band are not in English, many are incomplete or lack proper documentation.

After many hours of research, I was able to create an app to see the bus timetable, if you want to check out the app that I built here is the GitHub repository: https://github.com/mettiuss/bus

I write this article to help everyone starting on their journey to create an app for the mi band 7, I’ll show you how to create a simple Hello World app and I’ll illustrate the best tools for compiling, previewing and installing the app.

Coding the app

App.js e App.json

The app.json file gives information about the app that we are building, here is a link to the official documentation for more details:
https://docs.zepp.com/docs/1.0/reference/app-json/

{
  "configVersion": "v2",
  "app": {
    "appIdType": 0,
    "appType": "app",
    "version": {
      "code": 1,
      "name": "1.0.0"
    },
    "appId": 20001,
    "appName": "Hello", //The name of the app
    "icon": "icon.png", //The icon that must be placed in assets/l66/icon.png
    "vender": "matteo", //Your username
    "description": "Hello World app" //A description
  },
  "permissions": [],
  "runtime": {
    "apiVersion": {
      "compatible": "1.0.0",
      "target": "1.0.1",
      "minVersion": "1.0.0"
    }
  },
  "i18n": {
    "en-US": {
      "name": "Hello" //Repeat the name
    }
  },
  "defaultLanguage": "en-US",
  "debug": false,
  "targets": {
  "l66": {
    "module": {
      "page": {
        "pages": ["page/index.page"], // Here import your pages files
        "window": {
          "navigationBarBackgroundColor": "#ffffff",
          "navigationBarTextStyle": "black",
          "navigationBarTitleText": "Hello",
          "backgroundColor": "#eeeeee",
          "backgroundTextStyle": "light"
        }
      }
    },
    "platforms": [ //default for mi band 7
      { "name": "l66", "deviceSource": 260 },
      { "name": "l66w", "deviceSource": 261 },
      { "name": "l66_1", "deviceSource": 262 },
      { "name": "l66w_2", "deviceSource": 263 },
      { "name": "l66_3", "deviceSource": 264 },
      { "name": "l66_4", "deviceSource": 265 },
      { "name": "l66_5", "deviceSource": 266 }
    ],
    "designWidth": 192 //default for mi band 7
    }
  },
  "packageInfo": {
    "mode": "production",
    "timeStamp": 1648534836,
    "expiredTime": 172800,
    "zpm": "2.1.49"
  }
}

The app.js file initializes the app and shouldn’t be modified

try {
  (() => {
    var currentApp = __$$hmAppManager$$__.currentApp;
    try {
      currentApp.app = DeviceRuntimeCore.App({
        globalData: {},
        onCreate(e) {},
        onShow(e) {},
        onHide(e) {},
        onDestory(e) {},
        onError(e) {},
        onPageNotFound(e) {},
        onUnhandledRejection(e) {},
      });
    } catch (e) {
      console.log(e);
    }
    currentApp.app.__globals__ = {
      lang: new DeviceRuntimeCore.HmUtils.Lang(DeviceRuntimeCore.HmUtils.getLanguage()),
      px: DeviceRuntimeCore.HmUtils.getPx(192),
    };
  })();
} catch (e) {
   console.log(e);
}

Index.page

Now, we can finally dive into writing the code for our app. It can be really helpful to check out the official documentation as well as look at the code of other apps:
https://docs.zepp.com/docs/1.0/reference/device-app-api/global/
https://github.com/mettiuss/bus
https://github.com/melianmiko/SmartBand7-Drafts

Page({
  build() {
  const { width: DEVICE_WIDTH, height: DEVICE_HEIGHT } = hmSetting.getDeviceInfo();
  
  hmUI.setLayerScrolling(false);
  
  hmUI.createWidget(hmUI.widget.TEXT, {
      x: 0,
      y: 0,
      w: DEVICE_WIDTH,
      h: DEVICE_HEIGHT,
      color: 0xffffff,
      text_size: 28,
      text: 'Hello World',
      align_h: hmUI.align.CENTER_H,
      align_v: hmUI.align.CENTER_V,
    });
  },
  onInit() {},
  onDestroy() {},
});

Note that not every API from the ZeppOS documentation is implemented in the Mi Band 7: custom apps can’t run in background, can’t access your phone, your notifications or the Internet.

Compiling

There are multiple ways of compiling the code, including one that uses the official compiler for Zepp apps, but the easiest way is using zmake by melianmiko.

To use the compiler we need to create a zmake.json file and then we can follow the instructions on the GitHub page to use the program.

{
  "def_format": "TGA-RLP",
  "auto_rgba": true,
  "target_dir_override": "",
  "encode_mode": "dialog",
  "package_extension": "bin",
  "overrides": {},
  "esbuild": true,
  "esbuild_params": "--bundle",
  "with_uglifyjs": false,
  "uglifyjs_params": "",
  "with_zepp_preview": false,
  "add_preview_asset": false,
  "with_adb": false,
  "adb_path": "/storage/emulated/0/Android/data/com.xiaomi.hm.health/files/watch_skin_local",
  "post_build_script": "",
  "common_files": [],
  "with_zeus_compat": true,
  "zeus_target": "mi-band7",
  "zeus_platforms": [
    {
      "name": "amazfit-band7",
      "deviceSource": 253
    },
    {
      "name": "amazfit-band7-w",
      "deviceSource": 254
    }
  ]
}

Preview

Visualizing the changes while we code is helpful given the fact that the documentation cannot always be trusted.

To do so we can use ZeppPlayer by melianmiko, after having compiled with zmake we can open ZeppPlayer, select the correct folder and we can see a preview of our code that will update whenever we make a change and recompile.

Installation

The last step is installing the app on the Mi Band, you can do so with a third-party app https://play.google.com/store/apps/details?id=asn.ark.miband7

After having downloaded the app press on the ☰ icon at the bottom and then on “Install your watch face”, here you can select the compiled bin file (you can find it in dist/hello.bin) and then press on “Add watch face”.

Different methods

There is a different, newer, way of installing and testing the apps which uses a modified version of the Amazfit Zepp app.
This approach requires you to restore the band and pair it with the app, but it gives you access to some of the official development tools. Here is an article to learn more:
https://mmk.pw/en/posts/mi-band-7-with-zepp/

Credits

I’d like to give credit to melianmiko which I’ve mentioned multiple times in this article, he gave the community many tools to help with the development process.
https://mmk.pw/en/