Metadata-Version: 2.4
Name: wasptool
Version: 0.1.0a1
Summary: Talk to a wasp-os smart watch over Bluetooth: update, set the time, notify
License-Expression: LGPL-3.0-or-later
Requires-Dist: bleak>=3.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/wasp-os/wasp-os
Project-URL: Source, https://github.com/wasp-os/wasp-os/tree/master/tools/wasptool
Project-URL: Issues, https://github.com/wasp-os/wasp-os/issues
Description-Content-Type: text/markdown

# wasptool

Talk to a [wasp-os](https://github.com/wasp-os/wasp-os) smart watch over
Bluetooth: update its firmware, set its clock, send it notifications, copy
files to and from it, or open a MicroPython prompt on it. It runs on
Linux, macOS and Windows, and needs nothing but Python and
[bleak](https://github.com/hbldh/bleak).

## Install

From a wasp-os checkout:

```sh
uv tool install ./tools/wasptool
```

## Use

```sh
wasptool scan                       # the watches in range
wasptool info                       # version, battery, memory, ...
wasptool info --json                # the same, for scripts
wasptool rtc                        # how far off is the watch's clock?
wasptool rtc set                    # set it to this computer's time
wasptool notify "Build" "Passed"    # show a notification
wasptool alarm                      # the alarms
wasptool alarm set 7:30 --days weekdays   # add one, or change the one at 7:30
wasptool alarm unset 7:30           # remove it ("all" removes them all)
wasptool face                       # the watch faces, * marks the one in use
wasptool face PixelClock            # use another one
wasptool update                     # update to the latest build, after asking
wasptool update --check             # only show what's new
wasptool ota micropython.zip        # update the firmware from a file
wasptool push apps/snake.py         # copy a file to the watch
wasptool pull alarms.txt            # and back
wasptool eval "print(wasp.watch.battery.voltage_mv())"
wasptool exec script.py
wasptool console                    # a MicroPython prompt (Ctrl-X exits)
wasptool reset [--bootloader]
```

With more than one watch around, pick one with `--device NAME` or
`--device ADDRESS`. Connecting is retried (`--retries`, 3 by default):
some radios, especially ones shared with Wi-Fi, fail the first attempt
now and again.

`update` gets the builds published on https://wasp-os.x14.nl/ (see
`tools/publish.py`), checks the firmware's sha256 against `releases.json`
and installs it like `ota`. Use `--url` for another site.

Commands exit with status 0 on success and 1 on failure; `eval` and
`exec` also exit with 1 when the code raises, with the traceback on
stderr.

## How it works

The watch's console is the Nordic UART Service. wasptool runs Python on it
through MicroPython's raw REPL, using raw-paste mode for flow control
where the firmware has it (MicroPython 1.14 and later), and paced writes
where it does not. Firmware updates use Nordic's legacy DFU protocol,
which the PineTime bootloader speaks.
