Wear OS tiles and watch faces¶
wearSurface manages tiles, watch faces and complications on a Wear OS emulator.
Enable it with setToolEnabled (see Dynamic Tools). Like ambient, it
refuses any device not confirmed to be a watch and changes nothing.
Tiles¶
Call listTileProviders with no other argument to get the installed tile providers. Then pass one
provider’s component (<package>/<service>) to a tile action:
{
"name": "wearSurface",
"arguments": {
"action": "showTile",
"component": "com.google.android.contacts/com.google.android.wearable.contacts.tiles.FavoriteContactsTileService"
}
}
action |
Arguments | success: true means |
|---|---|---|
listTileProviders |
none | providers lists the installed tile providers (it may be empty) |
addTile |
component |
The tile is in the carousel at index (it may already have been there) |
removeTile |
component |
The tile was removed or was not there; the watch does not say which |
showTile |
component or index |
An observe after a 3 s settle shows a tile container in the foreground Wear system UI |
The watch reports success for an index with no tile and for removing an absent tile. Only
showTile checks the screen. Its verified: true means AutoMobile saw a tile container in the
foreground Wear system UI. addTile and removeTile always return verified: false.
| Result field | Content |
|---|---|
requested |
The request as sent |
broadcastResult |
code, data and a typed outcome: added, removed, showRequested, providerNotFound, missingComponent, indexRequired, unrecognizedOperation or unknown |
index |
The tile’s index, when known |
reason |
Why the action failed |
- Indexes shift: AutoMobile inserts a new tile at index 0, which pushes the others along. Prefer
showTilewithcomponent, which looks up the current index right before showing. That lookup adds the tile when it is missing;indexResolutionholds its reply. showTilesucceeds when any tile is visible, including a tile already on screen. A watch face alone cannot verify a tile, even if its clock changes. Verification confirms a visible tile, not its identity or requested index.- Use
observeto read the tile’s content andswipeOnleft or right to move through the carousel. - Each
providersentry hascomponent(pass it ascomponent),packageNameandclassName. addTile, andshowTilewithcomponent, first check the component against the installed tile providers. An unknown component fails with an error naming the valid components, and AutoMobile sends nothing. The.Serviceshort form of a listed provider also works.providerNotFoundinbroadcastResultmeans the watch refused a listed provider, for example one disabled since the check. RunlistTileProvidersagain.unrecognizedOperationmeans this Wear OS build does not accept the debug broadcasts.- The tool is unverified on a physical device, so check
broadcastResultwhen a result surprises you.
Read the watch faces¶
wearSurface with "action": "watchFace" (no other arguments) reads the watch faces without
changing anything:
{
"success": true,
"action": "watchFace",
"available": true,
"activeFace": { "package": "com.google.wear.offhand", "favoriteId": 1, "fallback": false },
"favorites": [
{
"favoriteId": 1,
"package": "com.google.wear.offhand",
"slots": [
{ "slot": 11, "type": 1, "provider": null },
{
"slot": 12,
"type": 3,
"provider": "com.google.android.clockwork.sysui/com.google.android.clockwork.sysui.experiences.complications.providers.DayAndDateProviderService"
}
]
}
],
"ambient": false,
"message": "Active watch face com.google.wear.offhand (favorite 1); 1 favorite(s)."
}
activeFace.fallback: truemeans the classic fallback face, which has no complication slots.favoriteslists every saved favorite. Each slot has itsslotid, complication datatypeandprovider(<package>/<class>, ornullwhen the slot is empty). The active favorite’s slots are the live configuration; the other favorites show their saved slots.ambientis the watch face’s own ambient flag, the same reading theambienttool uses. It is absent when the watch does not report it.available: false(withsuccess: falseand areason) means the watch reported no readable watch faces; nothing is thrown. A failed adb command returns an error instead.watchFacedoes not render a preview. Useobserveor a screenshot to see the face.
Set watch faces and complications¶
Name a resource-only (Watch Face Format) face by its bare package (com.google.wear.offhand) and a
classic face as <package>/<class>. Never pass <package>/_placeholder_. Complication types are
the androidx type ints (SHORT_TEXT = 3, RANGED_VALUE = 5). The provider is the data source
service as <package>/<service>.
{
"name": "wearSurface",
"arguments": {
"action": "setComplication",
"watchFace": "com.google.wear.offhand",
"slot": 11,
"type": 5,
"provider": "com.google.android.clockwork.sysui/com.google.android.clockwork.sysui.experiences.complications.providers.BatteryProviderService"
}
}
action |
Arguments | success: true means |
|---|---|---|
setWatchFace |
watchFace |
The face is the active one, with the reply’s favorite id |
unsetWatchFace |
none | The face active before setWatchFace is active again |
setComplication |
watchFace, slot, type, provider |
The active face’s slot shows that provider with that type |
unsetComplication |
watchFace, slot, provider |
The active face’s slot is empty |
The watch accepts a request before applying it. Each action therefore reads dumpsys wear_service
back for up to about 5 s. It sets applied: true (and verified: true) only when the change shows
there.
| Result field | Content |
|---|---|
requested |
The request as sent |
broadcastResult |
code, data, accepted, favoriteId |
favoriteId |
The favorite the watch used |
readback |
The last readback: activeFace, favorites and ambient, as watchFace reports them |
error, reason |
A typed error and its explanation, on failure |
change |
setComplication/unsetComplication only: unchanged when the slot already showed the request, applied when the broadcast changed it, absent when the slot could not be read first |
error |
Meaning and what to do |
|---|---|
provider_not_found |
provider is not a complication data source on the device; nothing was sent. reason names the installed ones |
unsupported_type |
Accepted but ignored: the slot kept its previous provider and type, so the provider does not support type. Pass a type the data source declares |
not_applied |
Accepted but the slot does not show the request (and changed to something else), or the readback was unreadable |
face_not_installed |
No such face package (or class): check the name |
slot_out_of_range |
The face has no such slot, or it is not the active face: setWatchFace first |
invalid_face_id |
A _placeholder_ class: pass a resource-only face as its bare package |
unsupported_face |
The fallback face has no slots: set another face first |
debug_surface_disabled |
The debug receiver is off on this build: enable developer options and retry |
watch_face_not_switched |
unsetWatchFace with nothing to revert |
missing_argument |
The watch rejected the extras it was sent |
unknown_reply |
A reply this release does not know: check broadcastResult |
- Slots belong to the active face, so set the face before its complications. List its slot ids
with
watchFace(the active favorite’sslots). setComplicationchecksprovideragainst the device’s complication data sources before sending. It cannot checktypefirst, because the device does not list each source’s supported types. An unsupported type comes back asunsupported_typeafter the readback.- The tool is unverified on a physical device.