The short answer
Yes. AmazHA, a Home Assistant app for Amazfit watches, runs on 25 Zepp OS models and controls lights, climate, covers, locks, media, scenes and more from your wrist. There is no official Home Assistant app for Zepp OS. The watch talks to your phone over Bluetooth, the phone talks to Home Assistant, and at home your local address is all it needs.
| At a glance | |
|---|---|
| Watches | 25 Amazfit models with Zepp OS, square and round |
| Device types | 17, each with its own control screen |
| Connection | Watch ↔ phone over Bluetooth, phone ↔ Home Assistant over HTTP |
| Addresses | Local URL at home, optional Remote URL away |
| Token | An administrator’s long-lived access token, kept on the phone |
| Refresh | Every 8 seconds while the app is open |
| Devices on the watch | Up to 100; a few dozen stay fast |
| Widget on the watch face | Up to four devices |
| Watch data into Home Assistant | 18 optional sensors, through the Mobile App integration |
| Price model | Free demo, then a one-time unlock, no subscription |
How a Zepp OS watch talks to Home Assistant
The watch never talks to Home Assistant itself: your phone does it. A Zepp OS watch app cannot make web requests, so AmazHA is built in two halves. One runs on the watch and draws the screens. The other runs on your phone inside the Zepp app, and it is the only part that speaks to your Home Assistant server.
Watch ↔ phone over Bluetooth, phone ↔ Home Assistant over HTTP
When you open a room on the watch, the watch asks the phone over Bluetooth. The phone calls Home Assistant’s REST API with your address and token, slims the answer down to what the watch needs, and sends that back. When you tap a light, the same path runs the other way: the watch tells the phone, and the phone calls the service in Home Assistant.
Two consequences follow from this design:
- Only what you chose reaches the watch. The phone loads the devices you switched on in the settings and nothing else, which keeps the Bluetooth traffic small.
- The watch screen does not depend on where the data comes from. The free demo and your real home use the same screens; only the source changes.
What never reaches the watch
Your Home Assistant address and your long-lived access token stay on the phone. The watch receives device names, states and the values it shows, and nothing else. The token is sent only to your Home Assistant server, and once it is saved the phone settings show dots instead of the token itself. AmazHA has no accounts, no analytics and no developer server that stores anything about you or your home.
Why the phone has to be nearby, and why the watch needs no Wi-Fi
The watch reaches Home Assistant through the phone, so the phone has to be within Bluetooth range, with Bluetooth on and the Zepp app running in the background. The watch itself needs no Wi-Fi and no mobile data: Bluetooth to the phone is its only link.
The phone, in turn, needs to reach your server. At home that is your local network. Away from home it needs a remote address, and if you never use the watch outside your home you never need one.
Local first, remote when away
You can enter two addresses: a Local URL (LAN), such as http://192.168.1.50:8123 (an example), and a Remote URL for when you are out. Either field can stay empty. With both set, AmazHA prefers the local one and switches to the remote one on its own when the local one does not answer. One token serves both. The remote access article compares Home Assistant Cloud, VPNs and your own domain.
What you can control from your wrist
AmazHA handles 17 device types from Home Assistant, and each one gets its own control screen. The home shows your areas, named as in Home Assistant; a room shows its devices grouped by type; a tap on a tile opens the full controls. Lights, switches and fans also have a switch right on their tile, and scenes, scripts, automations and buttons run from theirs.
| Device type | Home Assistant domains | What the watch screen does |
|---|---|---|
| Light | light |
Brightness slider; the crown changes it in 4% steps. A light that cannot dim gets a plain on/off dial |
| Switch | switch |
One big on/off control |
| Fan | fan |
Speed slider and power button; fans without speed settings get the on/off control alone |
| Climate | climate |
Target temperature on a dial, half a degree per crown step; Off, Heat, Cool and Auto modes |
| Cover | cover |
Open, Stop, Close, plus a position slider and the crown when the cover supports positions |
| Lock | lock |
Locks with one tap; unlocking asks for a second tap to confirm |
| Alarm | alarm_control_panel |
Arm in the modes your panel supports (home, away); disarming asks for your code on a keypad |
| Media | media_player |
Play, pause, previous and next, a volume slider (the crown sets the volume) and power, when the player supports them |
| Vacuum | vacuum |
Start, pause, stop and send it back to its dock |
| Scene | scene |
Runs with one tap |
| Script | script |
Runs with one tap |
| Automation | automation |
Triggers with one tap |
| Button | button, input_button |
Presses with one tap |
| Select | select, input_select |
The list of options; tap one to choose it |
| Sensor | sensor |
The current value in large type; sensors without a class show as text (a mailbox state, a bin day) |
| Camera | camera |
A still image fetched by the phone, with Refresh and Live |
| Tracker | device_tracker, person |
Read-only: home, away or the zone, with last update and battery when Home Assistant has them |
Sensors are filtered to the classes that make sense on a watch: temperature, humidity, power, energy, battery, air quality, illuminance, pressure and similar. Diagnostic sensors such as signal strength or voltage, and timestamps, are left out on purpose.
Changes are optimistic: the tile flips the moment you tap it, the call goes to Home Assistant in the background, and the next refresh corrects the screen if Home Assistant disagrees.
Which watches work
AmazHA runs on 25 Amazfit models with Zepp OS, with layouts for square and round screens. On round watches the titles are centred and the lists use the whole glass.
| Shape | Models |
|---|---|
| Square | Active, Active 2, Bip 6, Bip Max, Cheetah Square, GTS 4 |
| Round | Active 2, Active 2 Golf, Active 3 Premium, Active Max, Balance, Balance 2, Balance 2 XT, Balance 3, Balance 3 Ti, Balance Ultra, Cheetah 2 Pro, Cheetah 2 Ultra, Cheetah Pro, Cheetah Round, Falcon, GTR 4, T-Rex 3, T-Rex 3 Pro, T-Rex Ultra, T-Rex Ultra 2 |
Three watches are left out by design. The Active Edge and the Bip 5 have screens too small for the layout, and the T-Rex 2 does not have enough memory. Older Zepp OS models below API level 3.0 are out of scope. For a yes or no line per model, see which Amazfit watches work with Home Assistant.
The quickest check is the store itself: in the Zepp app, open the App Store and search for AmazHA. If your watch is paired and supported, you can install it and try the demo.
What you need before you start
You need four things: a Home Assistant server your phone can reach, an administrator’s long-lived access token, the Zepp app, and your watch paired with it.
| Requirement | Why |
|---|---|
| Home Assistant reachable from the phone | The phone makes every request. At home the local address is enough |
| A long-lived access token from an administrator | AmazHA reads your areas through the template API, which Home Assistant reserves for administrators |
| The Zepp app on Android or iPhone | AmazHA’s settings and its phone half live inside it |
| A supported watch, paired over Bluetooth | The watch reaches the phone the same way the Zepp app already does |
Nothing has to be installed in Home Assistant to control your devices: AmazHA uses the REST API every Home Assistant server has. The token is created in Home Assistant under your profile, in the Security tab; the long-lived access token article explains the steps and why a regular user’s token is not enough.
Setup in six steps
The whole setup takes a few minutes, and the first two steps cost nothing. Each step has a short video tutorial.
1. Install AmazHA
In the Zepp app on your phone, open the App Store, tap the search icon and type AmazHA. Open AmazHA — Home Assistant Companion App and tap Install: it goes straight to your watch. Then, on the watch, open the list of apps and tap AmazHA. (Install AmazHA)
2. Try the demo
AmazHA opens on a demo home with rooms and devices. Every screen works on sample data, with no time limit: open a room, flip a switch, turn the crown on a light. It is the honest way to see how the app feels on your own watch before you pay anything. (Get around the watch)
3. Unlock it once
On the watch, tap the orange Demo mode · no license banner at the top of the home. The watch shows a 5-digit code. On your phone, open kzl.io/code in the browser, enter the code, tap Continue and complete the payment. The watch shows Purchase Successful! and goes back to the app by itself. More on this below. (Unlock the full version)
4. Connect Home Assistant
In the Zepp app, go to Profile › your watch › Apps › AmazHA › Settings and tap Home Assistant. Enter Local URL (LAN), and Remote URL if you want the watch away from home. Paste the token into Long-lived access token and tap Connect. With one address the result reads Connected; with both, it shows LAN and Remote separately. (Connect Home Assistant, step 4 onwards)
5. Choose your devices
In the AmazHA settings, tap Devices. Your rooms are there, and every device starts hidden: open a room and switch on what you use. Long lists such as Other, where devices without a room go, have a Search box; Show all and Hide all act only on the devices that match. People and phones have their own area, Trackers. (Choose your devices)
6. Open AmazHA on the watch
Your rooms and devices appear on the watch. From now on the watch starts with your last data at once and refreshes it from Home Assistant while the app is open.
Make it yours
Everything that changes how the watch looks is set in the phone settings, and the watch picks it up from there.
Favorites and Favorites as home
In Devices › Favorites, switch on Show on watch and pick any device from any room, even one you have not enabled in its room. Reorder favorites sets their order. Favorites then appears first on the watch home. Switch on Use Favorites as homepage and the watch home becomes that list alone, and only those devices are loaded. The areas come back when you turn it off. (Favorites & energy, step 4)
The energy panel
In Devices › Energy, switch on Show Energy panel and pick a sensor for each role you have, such as Grid power (signed), solar, battery, and today’s use and cost. Only sensors that fit the role are listed. The watch home gets an Energy area with the grid power right now, importing or exporting, then solar, battery and today’s totals. (Favorites & energy)
Home chips, room order and room icons
Under Appearance › Home chips, each of the three chips at the top of the home can count lights, switches, covers, climate, media, locks, cameras or trackers, or show the alarm, your energy, or nothing. Home layout sets the order of the areas, and a tap on a room’s icon picks another one. Inside Devices, a room with temperature or humidity sensors lets you choose which sensor feeds that room’s chips, so a device’s internal reading does not win over the room sensor. (Make it yours)
Custom names
Long Home Assistant names rarely fit a watch tile. In Devices, every device the watch shows has a pencil after its name: tap the name and type a new one in Name on the watch, up to 32 characters. The watch uses it on every screen and on the widget, while Home Assistant keeps its own name. Restore original name goes back to it. The names live on the phone and survive Reset cache. (Custom names & the widget)
Text size, card size, vibration and screen timeout
In Preferences:
- Font size makes every text on the watch bigger: 110%, 120% or 130%. It applies from the next time you open AmazHA on the watch.
- Card size enlarges the home’s area cards and the device tiles: 115%, 130% or 145%.
- Vibrate on actions gives a short tick when you tap a device, run an action or turn the crown on a control screen. It is off by default.
- Screen timeout sets how long the screen stays on while AmazHA is open: 30 seconds, 1 minute, 5 minutes or Never, the default. Never also ignores lowering your wrist, which is handy but heavier on the battery.
The watch’s language follows its own system language; Language in the settings changes only the settings page. (Preferences)
The widget on the watch face
The widget puts up to four of your devices on the watch’s shortcut cards, one tap away without opening the app. It is part of the full version; in the free version it offers the unlock instead.
To set it up, open Devices › Widget on watch in the phone settings and tap up to four devices, in the order you want them: left to right, top to bottom. Then, on the watch, swipe right from the watch face to the shortcut cards, tap Edit and add AmazHA. Until you open the app once, the widget says Open AmazHA; after that your devices are there. (Custom names & the widget, step 4)
What a tap on the widget does depends on the device:
| Device on the widget | A tap |
|---|---|
| Light, switch, fan | Turns it on or off; the widget shows the new state |
| Scene, script, button, automation | Runs it |
| Anything else (a lock, a cover, a sensor, a camera) | Opens its own screen in AmazHA, where a lock still asks you to confirm |
If a command does not go through, the screen says why, with Retry and Open AmazHA; Retry never runs an action twice. The widget’s header always says how old its states are, such as AmazHA · 1 min ago. It turns grey while the watch is offline, or once its states are 12 hours old, and a tap then opens the app, which brings it up to date. Changes you make on the phone reach the widget the next time you open AmazHA.
One practical note: on the newer watches, an AmazHA update installed while the widget is on the watch face keeps part of the old version running until the watch restarts. The home then shows Restart the watch until you do.
Your watch’s data in Home Assistant
AmazHA also works the other way round: it can send 18 readings from your watch to Home Assistant as sensor entities. They arrive through Home Assistant’s own Mobile App integration, as one device with its sensors, named sensor.<prefix>_<key>.
The readings cover activity (steps, distance, calories, standing hours, intensive minutes, PAI), health (heart rate, resting heart rate, SpO2, stress, body temperature, sleep score, sleep duration, sleep state), environment (air pressure, altitude) and the device (watch battery, wear state). All of them start off, and you switch on only the ones you want, under Watch sensors › Send to Home Assistant.
The watch sends its data every time you open AmazHA. For updates with the app closed, set Update every (1 to 6 minutes) and allow Background activity when the watch asks; the phone has to be nearby for each update. In Home Assistant you find the watch under Settings › Devices & services › Mobile App. The watch sensors article has the full table and automation examples. (Watch sensors)
Limits worth knowing
A watch app that goes through the phone has a few limits by design, and it is better to know them before you buy.
| Limit | What it means in practice |
|---|---|
| The phone must be nearby | No Bluetooth link to the phone, no control. The watch shows Offline · No answer from the phone |
| States refresh while the app is open | Every 8 seconds, so a change made elsewhere shows up within a few seconds. When the app is closed, nothing is refreshed |
| No push from Home Assistant | The watch asks for states; Home Assistant cannot send notifications or updates to the watch through AmazHA |
| 100 devices at most | A few dozen stay fast. The Devices screen recommends 40 or fewer per area: on some watches an area with 70 or more can run out of memory and leave the screen black |
| Away from home needs a remote address | Only if you want to use it outside; the local address covers home |
| Background sensor updates | Need the Background activity permission and the phone in range; otherwise the watch sends its data when you open the app |
| Zepp OS only | A Wear OS version is in development, with no date |
The first two rows explain most surprises. If you leave the phone in another room and walk out of Bluetooth range, the watch keeps showing your last data but cannot change anything. And if a light changes while AmazHA is closed, the watch shows the new state the next time you open it.
When something goes wrong
When something does not work, the watch says what it is, and each message has one usual cause. This table follows the troubleshooting tutorial, which has a step for each message.
| The watch says | Cause | Fix |
|---|---|---|
| No devices selected | Every device starts hidden | Switch on the devices you want in Devices, in the AmazHA settings (step 1) |
| Offline · No answer from the phone | The watch cannot reach your phone | Keep the phone nearby, with Bluetooth on and the Zepp app running (step 2) |
| Offline · Home Assistant unreachable | The phone cannot reach Home Assistant | Open your address in the phone’s browser: it must work from where the phone is, and away from home it needs HTTPS with a valid certificate (step 3) |
| Wrong address | The address answers, but it is not the Home Assistant API | Use only the server address, with nothing after it (no /lovelace) (step 4) |
| Admin token needed | The token belongs to a user without administrator rights | Create a new long-lived token as an administrator and paste it in (step 5) |
| Check the token | The token has a character no token has, usually from a shortened copy (…) | Copy it again, all of it, and paste it (step 6) |
| The watch is slow or restarts | Too many devices | Keep the selection small: a few dozen stay fast, 100 is the limit (step 7) |
| Demo mode · no license | The app is not unlocked | Tap the banner and unlock it (Unlock the full version) |
| Demo mode · Set your HA server in the phone app | Unlocked, but no server set yet | Enter your address and token under Home Assistant in the settings (Connect Home Assistant) |
| Restart the watch | An update installed while the widget was on the watch face | Restart the watch |
Under an Offline banner the watch adds Retrying every 8s, so you do not have to do anything once the cause is gone, and a small code line underneath that tells support exactly what failed. A photo of the watch is the most useful thing to send.
If nothing on the list fits, open Preferences, tap Reset cache, then Tap again to confirm. It clears the cached data on the watch and the phone and keeps your connection, devices and licence; then reopen AmazHA on the watch (step 8). If that does not help either, the Support form in the settings sends a report with your message. It never includes your Home Assistant address, your token or your device names.
A worked example: green test, empty watch
A common first-day report: Connect turns green, but the watch shows nothing. Two causes cover almost every case. Either no device is switched on yet, and the watch says No devices selected, or the token belongs to a user who is not an administrator, and the watch says Admin token needed. The second one surprises people because the connection test reads states successfully; it is the area lookup, through the template API, that Home Assistant refuses to a regular user. A new token created while signed in as an administrator fixes it.
Unlocking the full version
The unlock is a one-time payment made from the watch, through KiezelPay: no account, no subscription, no ads. It connects AmazHA to your own Home Assistant, local and remote, and turns on the watch sensors and the widget. Until then the app is a demo on sample data, and nothing reaches a real server.
- On the watch, tap the orange Demo mode · no license banner. The watch shows a 5-digit code.
- On your phone, open kzl.io/code in the browser.
- Type the code and tap Continue.
- Pay once, by card or PayPal. It is a lifetime licence.
- The watch shows Purchase Successful! and goes back to the app by itself.
The Unlock the full version tutorial shows each screen, and the pricing section on the home page lists what each version includes.