zepplin

Zepplin is a free (as-in freedom) implementation of Zepp OS development tools, thus replacing Zepp Simulator and Zepp CLI.

Zepplin is still under development. While most of the features are already available, they still may be refactored or deprecated over the time until the stable API has been created.

Zepplin comes with seperate packages focusing on different aspects of Zepp OS development:

• api ─ Login with Zepp accounts, get user information, connect to Zepp Developer Bridge and so on
• emulator ─ Download and emulate Zepp OS firmware images on QEMU, so you can run mini-apps and test watchfaces
• webview ─ JavaScript code to provide Side Service and Settings UI APIs

Find more information in repository wiki.

The name "zepplin" is a pun on the words "zeppelin" (an airship) and "zepp". :P

Installation

python -m pip install .

Motivation

Zepp OS is a proprietary operating system (based on FreeRTOS) created by Zepp Health made for low-end affordable wearable devices. Devices that run Zepp OS are released & sold under Amazfit brand. Xiaomi also made an exception for once to put Zepp OS on their Smart Band 7 model (which I currently have) but that's an another story.

Thankfully, Zepp Health lets and encourages developers to build apps (or called as "mini-apps" by them) for wearable devices that run Zepp OS, so that means that I can get the most of my smart band even though it is sold for just a few bucks, so knowing that made me happy.

However, wish I could say the same for the developer experience, because after trying to make a simple app for my smart band, I noticed a lot of issues, for example their documentation just explains APIs with a few of words and nothing more about how/when it does work, which is a bummer. Also, since not every Zepp OS powered device receives the latest released Zepp OS version always, it causes a lot of breaking changes in the API, and that not only makes the development harder, it also makes the distribution painful. And to inspect the bugs/logs, (because the smart band don't give feedback on the coding errors other than a bugged yellow screen) it is required to use Zepp's own mobile app, which it is not possible for me because I'm using Xiaomi's product, not Amazfit's, so they don't acknowledge Xiaomi's only Zepp OS device due to their arrangements with Xiaomi. (even Xiaomi hides or doesn't share the fact that it runs Zepp OS.)

Even if I could own an Amazfit device to pair with Zepp app, I don't want to use the app anyway, because I'm already using Gadgetbridge to manage my smart band, so I can get the full control of my data, without relying on proprietary apps that connect to the cloud.

So I wanted to see if I can re-make the Zepp OS tools, to make developing the apps easier, uncovering and documenting every detail that I could find about Zepp OS, not having to depend on Zepp mobile app and making it fully free & open source, so everyone can benefit from it. And here it is.

Eventually and hopefully, Zepplin will become a one-stop place to build, package, run and debug Zepp OS mini-apps.

Devices equipped with Zepp OS are usually more affordable and easier to buy for most underdeveloped countries, however, if you are looking for a privacy & free (as-in freedom) focused watch, Zepp OS is not of them, so you can check out Bangle.js or AsteroidOS if you are interested.

License

Zepplin is licensed under GNU AGPL v3 (or later).

Disclaimer & Acknowledgements

Zepplin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

Zepplin is a clean-room implementation of Zepp OS tools; it doesn't directly depend, use, incorporate, inherit from any proprietary source code owned by Zepp Health. Some of Zepp OS tools such as the CLI are officially exists on the NPM, and tarballs are already public, so there were no sophisticated attempts to examine it.

Zepplin intends to publicly document all protocols and schemas about Zepp OS and its tools as much as possible, so it can be useful for people who would like to work with Zepp OS, thus while if it is not directly intended, it may naturally cause exposing some details which are intended by Zepp Health to be not known to public. Since Zepplin is an alternative for official Zepp OS tools, some parts of it may require communicating with Zepp Health servers, however in any case, it doesn't attempt to use Zepp services or/and endpoints in a malicious intent.

This project is not supported, sponsored, affiliated, approved, or endorsed in any way with Zepp Health. "Zepp OS" is an product of Zepp Health.

zmake is a project that allows packaging Zepp OS apps, which influenced me to make Zepplin. And in fact, Zepplin adopts some code from zmake (which is licensed under GPLv3), especially for the generation of TGA images.