hapbeat-python-sdk 0.1.0__tar.gz

hapbeat_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hapbeat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hapbeat_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: hapbeat-python-sdk
+Version: 0.1.0
+Summary: Python SDK for driving Hapbeat haptic devices over Wi-Fi UDP
+Author-email: Hapbeat <yus988@hapbeat.com>
+License: MIT
+Project-URL: Homepage, https://devtools.hapbeat.com/
+Project-URL: Documentation, https://devtools.hapbeat.com/docs/sdk-integration/
+Project-URL: Repository, https://github.com/hapbeat/hapbeat-python-sdk
+Project-URL: Issues, https://github.com/hapbeat/hapbeat-python-sdk/issues
+Keywords: hapbeat,haptics,udp,osc,vr,research,psychopy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: osc
+Requires-Dist: python-osc>=1.8; extra == "osc"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Hapbeat Python SDK
+
+Drive [Hapbeat](https://hapbeat.com) haptic devices from Python over Wi-Fi UDP.
+For researchers (PsychoPy / Jupyter / ROS), media artists, and anyone
+prototyping haptics in Python.
+
+> **📚 Docs**: <https://devtools.hapbeat.com/docs/sdk-integration/>
+
+A script can drive Hapbeat with a few lines. The fire side (`play` / `stop`)
+and the tuning side (`EventMap`) are kept orthogonal and linked only by
+event id.
+
+## Install
+
+```bash
+pip install hapbeat-python-sdk        # core (zero dependencies, stdlib socket only)
+pip install "hapbeat-python-sdk[osc]"   # + generic OSC bridge (TouchOSC / Max / TD)
+```
+
+With **pipx** you get the `hapbeat` CLI (including the launchpad below) in an
+isolated environment: `pipx install hapbeat-python-sdk`. Note that pipx does *not* make
+`import hapbeat` available to your own scripts — for the `examples/` use a
+normal `pip install` in a venv.
+
+## Try everything from one page (launchpad)
+
+```bash
+hapbeat launchpad          # opens http://127.0.0.1:7100 in your browser
+```
+
+A single local web page to fire events, run a metronome, a breathing pacer,
+or send Morse — start and stop them live, no per-example launching. It serves
+a tiny stdlib HTTP server that relays button presses to the device over UDP
+(browsers can't send UDP directly). Works great with `pipx install hapbeat-python-sdk`.
+
+## Quick start
+
+```python
+import hapbeat
+
+hb = hapbeat.connect(app_name="MyExperiment")  # opens UDP broadcast + keep-alive
+hb.play("impact.hit", gain=0.3)   # fire event "impact.hit" at gain 0.3
+hb.play("impact.hit")             # gain omitted -> kit baseline intensity
+hb.stop("impact.hit")
+hb.stop_all()
+hb.close()
+```
+
+or as a context manager:
+
+```python
+with hapbeat.connect(app_name="MyExperiment") as hb:
+    hb.play("impact.hit")
+```
+
+`"impact.hit"` must be an event id present in the **kit deployed to the
+device** (via [Hapbeat Studio](https://devtools.hapbeat.com)). The SDK sends
+the *instruction*; the waveform lives in the kit on the device.
+
+## Discovery
+
+```python
+for dev in hb.discover(timeout=1.5):
+    print(dev.ip, dev.address, dev.firmware_version)
+```
+
+## EventMap — the tuning side (optional)
+
+Keep per-event default gains in one place and let `play("id")` resolve them,
+so firing code never hard-codes intensities:
+
+```python
+em = hapbeat.EventMap.from_manifest("my-kit/my-kit-manifest.json")
+hb = hapbeat.connect(event_map=em)
+hb.play("impact.hit")        # uses the kit manifest's intensity for this event
+```
+
+`EventMap` reads the kit manifest (schema 2.0.0) `intensity` as the baseline
+gain. You can also build one by hand: `EventMap.from_dict({"impact.hit": 0.5})`.
+
+### Haptic file — add targeting on top of the kit
+
+The Studio-generated manifest holds kit content (intensity / clip), but not
+app-side concerns like **which device/body part** an event goes to. Put those
+in a *haptic file* (an EventMap overlay that references the kit), so `play(id)`
+resolves the target without the caller passing it:
+
+```json
+// haptics.json
+{
+  "kit": "kits/my-kit",
+  "events": {
+    "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
+    "rain.loop":  { "target": "*/back" }
+  }
+}
+```
+
+```python
+hb = hapbeat.connect(app_name="MyApp", haptics="haptics.json")
+hb.play("impact.hit")     # goes to player_1/chest at gain 0.8 — from the file
+```
+
+## Two playback modes: command and clip
+
+The same `play(id)` call branches on the manifest:
+
+| Manifest bucket | Mode | What happens |
+|---|---|---|
+| `events` | **command** | the SDK sends a PLAY; the **device** plays its installed clip |
+| `stream_events` | **clip** | the SDK reads the WAV from the kit's `stream-clips/` and **streams** it over UDP |
+
+Put the kit inside your project and call events by id — the per-event details
+(intensity, loop, command vs clip, which WAV) live in the kit, not your code:
+
+```
+my-app/
+  app.py
+  kits/my-kit/
+    my-kit-manifest.json     # the "haptic file" -> EventMap
+    install-clips/           # command clips (flashed to the device via Studio)
+    stream-clips/*.wav       # clip-mode WAVs the SDK streams
+```
+
+```python
+import hapbeat
+hb = hapbeat.connect(app_name="MyApp", kit="kits/my-kit")
+hb.play("impact.hit")     # command -> device plays its installed clip
+hb.play("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
+hb.stop("rain.loop")      # ends the active stream
+```
+
+You can also stream an ad-hoc PCM16 buffer (e.g. a synthesized stereo cue where
+L/R amplitude conveys direction):
+
+```python
+hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2)
+```
+
+Author clips as **16 kHz mono PCM16** (the device plays at 16 kHz; the SDK does
+not resample). A full runnable example is in
+[examples/clip_project/](examples/clip_project/).
+
+## Generic OSC bridge
+
+Any OSC tool (TouchOSC, Max/MSP, TouchDesigner, a DAW) can drive Hapbeat
+without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain]`:
+
+```bash
+hapbeat osc-bridge --listen 7702
+```
+
+See [docs/osc.md](docs/osc.md) for the address spec.
+
+## CLI
+
+```bash
+hapbeat scan                       # list devices on the LAN
+hapbeat play impact.hit --gain 0.3
+hapbeat stop-all
+hapbeat launchpad                  # browser UI for all of the above
+```
+
+## Examples
+
+Ready-to-run sample applications live in [examples/](examples/):
+a psychophysics experiment, a breathing pacer, a haptic metronome,
+a live trigger pad, a task-completion notifier, and a Morse transmitter.
+Each is a single stdlib-only file — see [examples/README.md](examples/README.md).
+
+## For AI coding agents
+
+Working with Claude / Cursor / Copilot? Hand your agent [AGENTS.md](AGENTS.md) —
+a single self-contained file with the SDK's model, API, project layout, and
+pitfalls. One file is enough to get the whole picture.
+
+> Use the Hapbeat Python SDK. Read `AGENTS.md` and follow its API and best practices.
+
+## License
+
+MIT © Hapbeat

hapbeat_python_sdk-0.1.0/README.md

@@ -0,0 +1,181 @@
+# Hapbeat Python SDK
+
+Drive [Hapbeat](https://hapbeat.com) haptic devices from Python over Wi-Fi UDP.
+For researchers (PsychoPy / Jupyter / ROS), media artists, and anyone
+prototyping haptics in Python.
+
+> **📚 Docs**: <https://devtools.hapbeat.com/docs/sdk-integration/>
+
+A script can drive Hapbeat with a few lines. The fire side (`play` / `stop`)
+and the tuning side (`EventMap`) are kept orthogonal and linked only by
+event id.
+
+## Install
+
+```bash
+pip install hapbeat-python-sdk        # core (zero dependencies, stdlib socket only)
+pip install "hapbeat-python-sdk[osc]"   # + generic OSC bridge (TouchOSC / Max / TD)
+```
+
+With **pipx** you get the `hapbeat` CLI (including the launchpad below) in an
+isolated environment: `pipx install hapbeat-python-sdk`. Note that pipx does *not* make
+`import hapbeat` available to your own scripts — for the `examples/` use a
+normal `pip install` in a venv.
+
+## Try everything from one page (launchpad)
+
+```bash
+hapbeat launchpad          # opens http://127.0.0.1:7100 in your browser
+```
+
+A single local web page to fire events, run a metronome, a breathing pacer,
+or send Morse — start and stop them live, no per-example launching. It serves
+a tiny stdlib HTTP server that relays button presses to the device over UDP
+(browsers can't send UDP directly). Works great with `pipx install hapbeat-python-sdk`.
+
+## Quick start
+
+```python
+import hapbeat
+
+hb = hapbeat.connect(app_name="MyExperiment")  # opens UDP broadcast + keep-alive
+hb.play("impact.hit", gain=0.3)   # fire event "impact.hit" at gain 0.3
+hb.play("impact.hit")             # gain omitted -> kit baseline intensity
+hb.stop("impact.hit")
+hb.stop_all()
+hb.close()
+```
+
+or as a context manager:
+
+```python
+with hapbeat.connect(app_name="MyExperiment") as hb:
+    hb.play("impact.hit")
+```
+
+`"impact.hit"` must be an event id present in the **kit deployed to the
+device** (via [Hapbeat Studio](https://devtools.hapbeat.com)). The SDK sends
+the *instruction*; the waveform lives in the kit on the device.
+
+## Discovery
+
+```python
+for dev in hb.discover(timeout=1.5):
+    print(dev.ip, dev.address, dev.firmware_version)
+```
+
+## EventMap — the tuning side (optional)
+
+Keep per-event default gains in one place and let `play("id")` resolve them,
+so firing code never hard-codes intensities:
+
+```python
+em = hapbeat.EventMap.from_manifest("my-kit/my-kit-manifest.json")
+hb = hapbeat.connect(event_map=em)
+hb.play("impact.hit")        # uses the kit manifest's intensity for this event
+```
+
+`EventMap` reads the kit manifest (schema 2.0.0) `intensity` as the baseline
+gain. You can also build one by hand: `EventMap.from_dict({"impact.hit": 0.5})`.
+
+### Haptic file — add targeting on top of the kit
+
+The Studio-generated manifest holds kit content (intensity / clip), but not
+app-side concerns like **which device/body part** an event goes to. Put those
+in a *haptic file* (an EventMap overlay that references the kit), so `play(id)`
+resolves the target without the caller passing it:
+
+```json
+// haptics.json
+{
+  "kit": "kits/my-kit",
+  "events": {
+    "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
+    "rain.loop":  { "target": "*/back" }
+  }
+}
+```
+
+```python
+hb = hapbeat.connect(app_name="MyApp", haptics="haptics.json")
+hb.play("impact.hit")     # goes to player_1/chest at gain 0.8 — from the file
+```
+
+## Two playback modes: command and clip
+
+The same `play(id)` call branches on the manifest:
+
+| Manifest bucket | Mode | What happens |
+|---|---|---|
+| `events` | **command** | the SDK sends a PLAY; the **device** plays its installed clip |
+| `stream_events` | **clip** | the SDK reads the WAV from the kit's `stream-clips/` and **streams** it over UDP |
+
+Put the kit inside your project and call events by id — the per-event details
+(intensity, loop, command vs clip, which WAV) live in the kit, not your code:
+
+```
+my-app/
+  app.py
+  kits/my-kit/
+    my-kit-manifest.json     # the "haptic file" -> EventMap
+    install-clips/           # command clips (flashed to the device via Studio)
+    stream-clips/*.wav       # clip-mode WAVs the SDK streams
+```
+
+```python
+import hapbeat
+hb = hapbeat.connect(app_name="MyApp", kit="kits/my-kit")
+hb.play("impact.hit")     # command -> device plays its installed clip
+hb.play("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
+hb.stop("rain.loop")      # ends the active stream
+```
+
+You can also stream an ad-hoc PCM16 buffer (e.g. a synthesized stereo cue where
+L/R amplitude conveys direction):
+
+```python
+hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2)
+```
+
+Author clips as **16 kHz mono PCM16** (the device plays at 16 kHz; the SDK does
+not resample). A full runnable example is in
+[examples/clip_project/](examples/clip_project/).
+
+## Generic OSC bridge
+
+Any OSC tool (TouchOSC, Max/MSP, TouchDesigner, a DAW) can drive Hapbeat
+without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain]`:
+
+```bash
+hapbeat osc-bridge --listen 7702
+```
+
+See [docs/osc.md](docs/osc.md) for the address spec.
+
+## CLI
+
+```bash
+hapbeat scan                       # list devices on the LAN
+hapbeat play impact.hit --gain 0.3
+hapbeat stop-all
+hapbeat launchpad                  # browser UI for all of the above
+```
+
+## Examples
+
+Ready-to-run sample applications live in [examples/](examples/):
+a psychophysics experiment, a breathing pacer, a haptic metronome,
+a live trigger pad, a task-completion notifier, and a Morse transmitter.
+Each is a single stdlib-only file — see [examples/README.md](examples/README.md).
+
+## For AI coding agents
+
+Working with Claude / Cursor / Copilot? Hand your agent [AGENTS.md](AGENTS.md) —
+a single self-contained file with the SDK's model, API, project layout, and
+pitfalls. One file is enough to get the whole picture.
+
+> Use the Hapbeat Python SDK. Read `AGENTS.md` and follow its API and best practices.
+
+## License
+
+MIT © Hapbeat

hapbeat_python_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name (pip/pipx). The import package stays `import hapbeat`.
+name = "hapbeat-python-sdk"
+version = "0.1.0"
+description = "Python SDK for driving Hapbeat haptic devices over Wi-Fi UDP"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Hapbeat", email = "yus988@hapbeat.com" }]
+keywords = ["hapbeat", "haptics", "udp", "osc", "vr", "research", "psychopy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia",
+    "Topic :: Scientific/Engineering :: Human Machine Interfaces",
+    "Topic :: System :: Hardware",
+]
+# Core level-1 has zero runtime dependencies — stdlib socket only.
+dependencies = []
+
+[project.optional-dependencies]
+# Generic OSC bridge (TouchOSC / Max / TouchDesigner / DAWs).
+osc = ["python-osc>=1.8"]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://devtools.hapbeat.com/"
+Documentation = "https://devtools.hapbeat.com/docs/sdk-integration/"
+Repository = "https://github.com/hapbeat/hapbeat-python-sdk"
+Issues = "https://github.com/hapbeat/hapbeat-python-sdk/issues"
+
+[project.scripts]
+hapbeat = "hapbeat.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

hapbeat_python_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hapbeat_python_sdk-0.1.0/src/hapbeat/__init__.py

@@ -0,0 +1,49 @@
+"""Hapbeat SDK for Python — drive Hapbeat haptic devices over Wi-Fi UDP.
+
+Quick start::
+
+    import hapbeat
+
+    hb = hapbeat.connect(app_name="MyExperiment")
+    hb.play("impact.hit", gain=0.3)
+    hb.stop_all()
+    hb.close()
+
+The fire side (``play``/``stop``) and the tuning side (:class:`EventMap`) are
+kept orthogonal and linked only by event id, matching the Hapbeat Unity SDK.
+"""
+
+from __future__ import annotations
+
+from . import protocol
+from .client import DEFAULT_BROADCAST, DEFAULT_PORT, UdpClient
+from .clip import ClipStreamer
+from .eventmap import EventDef, EventMap
+from .hapbeat import Device, Hapbeat, connect
+from .wav import WavPcm, read_wav_pcm16
+
+try:  # populated from installed package metadata
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("hapbeat-python-sdk")
+    except PackageNotFoundError:  # running from a source checkout
+        __version__ = "0.1.0+local"
+except ImportError:  # pragma: no cover
+    __version__ = "0.1.0+local"
+
+__all__ = [
+    "connect",
+    "Hapbeat",
+    "Device",
+    "EventMap",
+    "EventDef",
+    "ClipStreamer",
+    "WavPcm",
+    "read_wav_pcm16",
+    "UdpClient",
+    "protocol",
+    "DEFAULT_PORT",
+    "DEFAULT_BROADCAST",
+    "__version__",
+]

hapbeat_python_sdk-0.1.0/src/hapbeat/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m hapbeat``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

hapbeat_python_sdk-0.1.0/src/hapbeat/cli.py

@@ -0,0 +1,124 @@
+"""``hapbeat`` command-line interface.
+
+Examples::
+
+    hapbeat scan
+    hapbeat play impact.hit --gain 0.3
+    hapbeat stop impact.hit
+    hapbeat stop-all
+    hapbeat osc-bridge --listen 7702
+    hapbeat launchpad
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .eventmap import EventMap
+from .hapbeat import connect
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--port", type=int, default=7700, help="UDP port (default 7700)")
+    p.add_argument("--target", default="", help="device address; empty = all (broadcast)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hapbeat", description="Drive Hapbeat devices.")
+    parser.add_argument("--version", action="version", version=f"hapbeat {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_play = sub.add_parser("play", help="play an event by id")
+    p_play.add_argument("event_id")
+    p_play.add_argument("--gain", type=float, default=None, help="0..1 (default: kit baseline)")
+    _add_common(p_play)
+
+    p_stop = sub.add_parser("stop", help="stop one event id")
+    p_stop.add_argument("event_id")
+    _add_common(p_stop)
+
+    p_stop_all = sub.add_parser("stop-all", help="stop everything")
+    _add_common(p_stop_all)
+
+    p_ping = sub.add_parser("ping", help="broadcast a keep-alive ping")
+    _add_common(p_ping)
+
+    p_scan = sub.add_parser("scan", help="discover devices on the LAN")
+    p_scan.add_argument("--timeout", type=float, default=1.5)
+    _add_common(p_scan)
+
+    p_osc = sub.add_parser("osc-bridge", help="relay /hapbeat/* OSC to devices")
+    p_osc.add_argument("--listen", type=int, default=7702, help="OSC listen port (default 7702)")
+    p_osc.add_argument("--haptics", default=None,
+                       help="haptic file (overlay) so OSC events route command/clip + use per-event targets")
+    p_osc.add_argument("--kit", default=None,
+                       help="kit folder (alternative to --haptics; intensity/clip only, no targeting)")
+    _add_common(p_osc)
+
+    p_lp = sub.add_parser(
+        "launchpad",
+        help="serve a local web page to try features from the browser",
+    )
+    p_lp.add_argument("--host", default="127.0.0.1", help="HTTP bind host (default 127.0.0.1)")
+    p_lp.add_argument("--http-port", type=int, default=7100, help="HTTP port (default 7100)")
+    p_lp.add_argument("--no-open", action="store_true", help="do not open a browser")
+    _add_common(p_lp)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "osc-bridge":
+        from .osc import OscBridge
+
+        event_map = None
+        if args.haptics:
+            event_map = EventMap.from_file(args.haptics)
+        elif args.kit:
+            event_map = EventMap.from_kit(args.kit)
+        hb = connect(port=args.port, app_name="hapbeat-osc",
+                     default_target=args.target, event_map=event_map)
+        try:
+            mode = "command+clip" if event_map else "command only"
+            print(f"OSC bridge: listening on :{args.listen}, relaying to UDP {args.port} ({mode})")
+            OscBridge(hb, listen_port=args.listen).serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            hb.close()
+        return 0
+
+    if args.command == "launchpad":
+        from .launchpad import serve
+
+        return serve(host=args.host, port=args.http_port, udp_port=args.port,
+                     target=args.target, open_browser=not args.no_open)
+
+    hb = connect(port=args.port, default_target=getattr(args, "target", ""), keepalive=False)
+    try:
+        if args.command == "play":
+            ok = hb.play(args.event_id, args.gain)
+            print(f"play {args.event_id} gain={args.gain if args.gain is not None else 'baseline'} -> {'sent' if ok else 'FAILED'}")
+        elif args.command == "stop":
+            print("sent" if hb.stop(args.event_id) else "FAILED")
+        elif args.command == "stop-all":
+            print("sent" if hb.stop_all() else "FAILED")
+        elif args.command == "ping":
+            print("sent" if hb.ping() else "FAILED")
+        elif args.command == "scan":
+            devices = hb.discover(timeout=args.timeout)
+            if not devices:
+                print("no devices replied")
+            for d in devices:
+                print(f"{d.ip:<16} {d.address or '?':<20} {d.name or '?':<16} fw={d.firmware_version or '?'}")
+    finally:
+        hb.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())