hapbeat-helper 0.1.2__tar.gz

hapbeat_helper-0.1.2/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_helper-0.1.2/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: hapbeat-helper
+Version: 0.1.2
+Summary: Local daemon bridging Hapbeat Studio (web) to Hapbeat devices
+Author-email: Hapbeat <yus988@hapbeat.com>
+License: MIT
+Project-URL: Homepage, https://devtools.hapbeat.com/
+Project-URL: Repository, https://github.com/hapbeat/hapbeat-helper
+Project-URL: Issues, https://github.com/hapbeat/hapbeat-helper/issues
+Keywords: hapbeat,haptics,studio,websocket,mdns,iot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12
+Requires-Dist: zeroconf>=0.131
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Provides-Extra: normalize
+Dynamic: license-file
+
+# hapbeat-helper
+
+Local daemon that bridges **Hapbeat Studio** (Web SPA at `https://devtools.hapbeat.com`)
+to Hapbeat hardware on the local network.
+
+The browser cannot do mDNS, UDP broadcast, or raw TCP sockets directly.
+`hapbeat-helper` runs in the background, exposes a WebSocket on
+`ws://localhost:7703`, and relays Studio requests to the devices using
+UDP (port 7700) and TCP (port 7701).
+
+```
+Studio (https://devtools.hapbeat.com)
+        │  ws://localhost:7703 (JSON)
+        ▼
+hapbeat-helper (this daemon)
+        │  UDP 7700 (PLAY / STOP / PING / streaming)
+        │  TCP 7701 (config / kit deploy)
+        │  mDNS (_hapbeat._udp.local.)
+        ▼
+   Hapbeat devices
+```
+
+## Install
+
+`hapbeat-helper` is distributed as a Python CLI that runs in its own
+isolated environment. The recommended installer is **pipx** — it puts
+each Python tool in a separate venv and exposes the entry point on your
+PATH, so you don't need to think about Python versions or dependency
+conflicts.
+
+### Step 1 — Install pipx (once per machine)
+
+#### macOS
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+#### Windows
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+# Close and reopen your terminal so the new PATH takes effect.
+pipx --version    # should print the version
+```
+
+> **Windows tip:** if `pipx` is still "not recognized" after reopening
+> the shell, use `py -m pipx ...` for everything below (it works
+> identically). The bare `pipx` command becomes available once
+> `%APPDATA%\Python\Python3xx\Scripts` is on your `Path`.
+>
+> **OneDrive / cloud-synced home directory:** if your `C:\Users\<you>\`
+> is synced by OneDrive, pipx may fail with `WinError 448 — untrusted
+> mount point`. Move pipx out of the synced tree by setting these
+> environment variables (User scope) and reopening the shell:
+>
+> ```powershell
+> [Environment]::SetEnvironmentVariable('PIPX_HOME',    'C:\pipx\home', 'User')
+> [Environment]::SetEnvironmentVariable('PIPX_BIN_DIR', 'C:\pipx\bin',  'User')
+> ```
+
+### Step 2 — Install hapbeat-helper
+
+Once pipx is on your PATH:
+
+```bash
+pipx install hapbeat-helper
+```
+
+That's it. `hapbeat-helper` will be available in any new terminal.
+
+### Local development (from a clone of this repo)
+
+```bash
+# editable install via pipx (changes in src/ are picked up live)
+pipx install -e .
+
+# or — preferred during active dev — a plain venv:
+python -m venv .venv
+# macOS:
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/hapbeat-helper start
+# Windows:
+.venv\Scripts\pip install -e ".[dev]"
+.venv\Scripts\hapbeat-helper start
+```
+
+### Updating
+
+```bash
+pipx upgrade hapbeat-helper
+```
+
+If you installed editable from a clone (`pipx install -e .` or
+`pip install -e ".[dev]"`), updates are automatic — just `git pull` and
+restart the daemon. The Python package picks up changes in `src/` on
+the next process start.
+
+> **WS protocol mismatch?** When Studio reports
+> `ERROR: unknown type: <message>` in the log drawer, your helper is
+> older than the Studio build. `git pull && restart` (or `pipx upgrade`).
+
+### Uninstalling
+
+```bash
+pipx uninstall hapbeat-helper
+```
+
+## Run
+
+### Option A — Auto-start service (recommended)
+
+Register hapbeat-helper as an OS-level service so it starts automatically
+every time you log in. After this one-time setup you never need to open a
+terminal again:
+
+```bash
+hapbeat-helper install-service
+```
+
+To check the registration state:
+
+```bash
+hapbeat-helper service-status
+```
+
+To remove the auto-start registration:
+
+```bash
+hapbeat-helper uninstall-service
+```
+
+Platform notes:
+- **macOS** — creates `~/Library/LaunchAgents/com.hapbeat.helper.plist` (launchd)
+- **Windows** — drops a hidden VBS shim into the Startup folder (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\hapbeat-helper.vbs`) that launches the daemon at login with no console window. stdout/stderr → `%LOCALAPPDATA%\hapbeat-helper\hapbeat-helper.log`
+
+### Option B — Foreground (dev / debug)
+
+```bash
+hapbeat-helper start
+```
+
+Then open https://devtools.hapbeat.com — Studio will connect automatically.
+
+Press `Ctrl+C` to stop.
+
+### Other commands
+
+```bash
+hapbeat-helper status      # check whether a daemon is reachable on 7703
+hapbeat-helper version     # print version
+hapbeat-helper config show # show config path
+```
+
+## Verify
+
+Quick smoke test using `websocat`:
+
+```bash
+echo '{"type":"ping","payload":{}}' | websocat ws://localhost:7703
+echo '{"type":"list_devices","payload":{}}' | websocat ws://localhost:7703
+```
+
+## Troubleshooting
+
+- **Studio reports "Helper 未接続"** — run `hapbeat-helper install-service` (once)
+  or start manually with `hapbeat-helper start`.
+- **Browser cannot connect to `ws://localhost:7703` from HTTPS Studio** —
+  Chrome and Edge allow this by default. Firefox requires
+  `network.websocket.allowInsecureFromHTTPS = true` in `about:config`.
+- **No devices found** — confirm the Hapbeat devices and this PC are on the
+  same Wi-Fi network. Some hotspot/AP modes block UDP broadcast and mDNS.
+- **Port 7700 / 7703 already in use** — stop any running `hapbeat-manager`
+  (it owns the same ports). The two cannot run at the same time.
+- **Windows: `pipx install` fails with `WinError 448 — untrusted mount
+  point`** — your home directory is under OneDrive (or another reparse
+  point). pipx finished installing the package but cannot finalize the
+  shim under `~/.local/bin/`. Either run `hapbeat-helper.exe` from that
+  path directly, or relocate pipx outside the synced tree:
+
+  ```powershell
+  [Environment]::SetEnvironmentVariable('PIPX_HOME',    'C:\pipx\home', 'User')
+  [Environment]::SetEnvironmentVariable('PIPX_BIN_DIR', 'C:\pipx\bin',  'User')
+  # Reopen the shell, then:
+  py -m pipx ensurepath
+  py -m pipx install hapbeat-helper
+  ```
+- **`pipx` not recognized after `pip install --user pipx`** — the user
+  Scripts dir is not on `Path` yet. Run `py -m pipx ensurepath` and open
+  a new terminal. As a fallback, every `pipx X` call also works as
+  `py -m pipx X`.
+
+## License
+
+MIT

hapbeat_helper-0.1.2/README.md

@@ -0,0 +1,197 @@
+# hapbeat-helper
+
+Local daemon that bridges **Hapbeat Studio** (Web SPA at `https://devtools.hapbeat.com`)
+to Hapbeat hardware on the local network.
+
+The browser cannot do mDNS, UDP broadcast, or raw TCP sockets directly.
+`hapbeat-helper` runs in the background, exposes a WebSocket on
+`ws://localhost:7703`, and relays Studio requests to the devices using
+UDP (port 7700) and TCP (port 7701).
+
+```
+Studio (https://devtools.hapbeat.com)
+        │  ws://localhost:7703 (JSON)
+        ▼
+hapbeat-helper (this daemon)
+        │  UDP 7700 (PLAY / STOP / PING / streaming)
+        │  TCP 7701 (config / kit deploy)
+        │  mDNS (_hapbeat._udp.local.)
+        ▼
+   Hapbeat devices
+```
+
+## Install
+
+`hapbeat-helper` is distributed as a Python CLI that runs in its own
+isolated environment. The recommended installer is **pipx** — it puts
+each Python tool in a separate venv and exposes the entry point on your
+PATH, so you don't need to think about Python versions or dependency
+conflicts.
+
+### Step 1 — Install pipx (once per machine)
+
+#### macOS
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+#### Windows
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+# Close and reopen your terminal so the new PATH takes effect.
+pipx --version    # should print the version
+```
+
+> **Windows tip:** if `pipx` is still "not recognized" after reopening
+> the shell, use `py -m pipx ...` for everything below (it works
+> identically). The bare `pipx` command becomes available once
+> `%APPDATA%\Python\Python3xx\Scripts` is on your `Path`.
+>
+> **OneDrive / cloud-synced home directory:** if your `C:\Users\<you>\`
+> is synced by OneDrive, pipx may fail with `WinError 448 — untrusted
+> mount point`. Move pipx out of the synced tree by setting these
+> environment variables (User scope) and reopening the shell:
+>
+> ```powershell
+> [Environment]::SetEnvironmentVariable('PIPX_HOME',    'C:\pipx\home', 'User')
+> [Environment]::SetEnvironmentVariable('PIPX_BIN_DIR', 'C:\pipx\bin',  'User')
+> ```
+
+### Step 2 — Install hapbeat-helper
+
+Once pipx is on your PATH:
+
+```bash
+pipx install hapbeat-helper
+```
+
+That's it. `hapbeat-helper` will be available in any new terminal.
+
+### Local development (from a clone of this repo)
+
+```bash
+# editable install via pipx (changes in src/ are picked up live)
+pipx install -e .
+
+# or — preferred during active dev — a plain venv:
+python -m venv .venv
+# macOS:
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/hapbeat-helper start
+# Windows:
+.venv\Scripts\pip install -e ".[dev]"
+.venv\Scripts\hapbeat-helper start
+```
+
+### Updating
+
+```bash
+pipx upgrade hapbeat-helper
+```
+
+If you installed editable from a clone (`pipx install -e .` or
+`pip install -e ".[dev]"`), updates are automatic — just `git pull` and
+restart the daemon. The Python package picks up changes in `src/` on
+the next process start.
+
+> **WS protocol mismatch?** When Studio reports
+> `ERROR: unknown type: <message>` in the log drawer, your helper is
+> older than the Studio build. `git pull && restart` (or `pipx upgrade`).
+
+### Uninstalling
+
+```bash
+pipx uninstall hapbeat-helper
+```
+
+## Run
+
+### Option A — Auto-start service (recommended)
+
+Register hapbeat-helper as an OS-level service so it starts automatically
+every time you log in. After this one-time setup you never need to open a
+terminal again:
+
+```bash
+hapbeat-helper install-service
+```
+
+To check the registration state:
+
+```bash
+hapbeat-helper service-status
+```
+
+To remove the auto-start registration:
+
+```bash
+hapbeat-helper uninstall-service
+```
+
+Platform notes:
+- **macOS** — creates `~/Library/LaunchAgents/com.hapbeat.helper.plist` (launchd)
+- **Windows** — drops a hidden VBS shim into the Startup folder (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\hapbeat-helper.vbs`) that launches the daemon at login with no console window. stdout/stderr → `%LOCALAPPDATA%\hapbeat-helper\hapbeat-helper.log`
+
+### Option B — Foreground (dev / debug)
+
+```bash
+hapbeat-helper start
+```
+
+Then open https://devtools.hapbeat.com — Studio will connect automatically.
+
+Press `Ctrl+C` to stop.
+
+### Other commands
+
+```bash
+hapbeat-helper status      # check whether a daemon is reachable on 7703
+hapbeat-helper version     # print version
+hapbeat-helper config show # show config path
+```
+
+## Verify
+
+Quick smoke test using `websocat`:
+
+```bash
+echo '{"type":"ping","payload":{}}' | websocat ws://localhost:7703
+echo '{"type":"list_devices","payload":{}}' | websocat ws://localhost:7703
+```
+
+## Troubleshooting
+
+- **Studio reports "Helper 未接続"** — run `hapbeat-helper install-service` (once)
+  or start manually with `hapbeat-helper start`.
+- **Browser cannot connect to `ws://localhost:7703` from HTTPS Studio** —
+  Chrome and Edge allow this by default. Firefox requires
+  `network.websocket.allowInsecureFromHTTPS = true` in `about:config`.
+- **No devices found** — confirm the Hapbeat devices and this PC are on the
+  same Wi-Fi network. Some hotspot/AP modes block UDP broadcast and mDNS.
+- **Port 7700 / 7703 already in use** — stop any running `hapbeat-manager`
+  (it owns the same ports). The two cannot run at the same time.
+- **Windows: `pipx install` fails with `WinError 448 — untrusted mount
+  point`** — your home directory is under OneDrive (or another reparse
+  point). pipx finished installing the package but cannot finalize the
+  shim under `~/.local/bin/`. Either run `hapbeat-helper.exe` from that
+  path directly, or relocate pipx outside the synced tree:
+
+  ```powershell
+  [Environment]::SetEnvironmentVariable('PIPX_HOME',    'C:\pipx\home', 'User')
+  [Environment]::SetEnvironmentVariable('PIPX_BIN_DIR', 'C:\pipx\bin',  'User')
+  # Reopen the shell, then:
+  py -m pipx ensurepath
+  py -m pipx install hapbeat-helper
+  ```
+- **`pipx` not recognized after `pip install --user pipx`** — the user
+  Scripts dir is not on `Path` yet. Run `py -m pipx ensurepath` and open
+  a new terminal. As a fallback, every `pipx X` call also works as
+  `py -m pipx X`.
+
+## License
+
+MIT

hapbeat_helper-0.1.2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hapbeat-helper"
+version = "0.1.2"
+description = "Local daemon bridging Hapbeat Studio (web) to Hapbeat devices"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Hapbeat", email = "yus988@hapbeat.com" }]
+keywords = ["hapbeat", "haptics", "studio", "websocket", "mdns", "iot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "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 :: Software Development :: Embedded Systems",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "websockets>=12",
+    "zeroconf>=0.131",
+]
+
+[project.urls]
+Homepage = "https://devtools.hapbeat.com/"
+Repository = "https://github.com/hapbeat/hapbeat-helper"
+Issues = "https://github.com/hapbeat/hapbeat-helper/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+# Pack/Kit normalization (ffmpeg subprocess needed at runtime)
+normalize = []
+
+[project.scripts]
+hapbeat-helper = "hapbeat_helper.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

hapbeat_helper-0.1.2/setup.cfg

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

hapbeat_helper-0.1.2/src/hapbeat_helper/__init__.py

@@ -0,0 +1,10 @@
+"""hapbeat-helper — local daemon bridging Studio (web) to Hapbeat devices."""
+
+try:
+    # Generated by scripts/gen_version.py (gitignored).
+    # Present in local dev installs; absent in PyPI releases.
+    from hapbeat_helper._version import __version__
+except ImportError:
+    # Fallback: release version embedded at publish time.
+    # Keep this in sync with pyproject.toml [project] version.
+    __version__ = "0.1.2"

hapbeat_helper-0.1.2/src/hapbeat_helper/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m hapbeat_helper` to invoke the CLI."""
+
+from hapbeat_helper.cli import main
+
+if __name__ == "__main__":
+    main()