watchface_patch_local
Patch a local watchface on a Divoom device by editing metadata fields or uploading a new backdrop image or clock bundle.
Instructions
Patch local dial via Device/PatchLocalClockInfo with precheck. Defaults to POST /divoom_api (JSON only) for pure metadata edits. Prefer ItemPatchList (per-index field diff) — DO NOT include item_id inside patch.* unless the user explicitly asks to rename a slot, since the firmware will overwrite the device-side item_id and break menu/config bindings. When dialAssetsPath is set, switches to multipart POST /patch_local_clock: first JSON part (Device/PatchLocalClockInfo, optional DialAssets), second part single JPEG/WebP dial backdrop or clock_bg.tar.gz bundle. Element slots inside the tarball must be JPEG, WebP, or PNG (validated by firmware wf_validate_bundle_slot_image_file). Use ItemPatchList[].patch.bundle_image= to bind a tar leaf to that slot's img_addr; supplying ItemList alone is a full-table replace and should be avoided unless the row count actually changes. Pointer fixes (131/132/233 = DIVOOM_CLOCK_DISP_SUPPORT_*_POINT_IMAGE): shared square x/y/w/h, w×w PNGs, center rotation; ref ClockId 60012; transp 100; hier 0/1/2 only — docs/tool-examples.md §5b. Avoid duplicate image-backed disp rows (NET_PIC family); docs/disp-usage.md. Multipart framing: watchface_upload_file description and resources/skill-quick-reference.md.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | Optional per-call target override. If omitted, environment variables are used. | |
| clockId | No | ||
| useCurrentDisplayClock | No | ||
| deviceImageUrl | No | ||
| devicePreviewImageUrl | No | ||
| devicePreviewImageUrl2 | No | ||
| setColorList | No | ||
| itemList | No | ||
| itemIdList | No | ||
| itemPatchList | No | ||
| itemPatchByRoleList | No | ||
| dialAssetsPath | No | Optional second multipart part. Either a single JPEG/WebP dial backdrop (`clock_bg.jpg|webp`, validated by divoom_watchface_replace_clock_dial_bg_validate_saved_file) or a `clock_bg.tar.gz` bundle. The tarball may contain `clock_bg.jpg|webp` plus the leaves listed by `ItemPatchList[].patch.bundle_image`. Element leaves inside the tar may be JPEG/WebP/PNG (PNG is element-only; backdrop must be JPEG/WebP). When set, the tool POSTs `/patch_local_clock` with the firmware-strict multipart layout. | |
| filePartName | No | Multipart field name for dialAssetsPath part. Default is current UTC ms timestamp. | |
| fileName | No | Multipart filename header for dialAssetsPath. Defaults to basename(dialAssetsPath). |