um-smart-hub 0.1.0__tar.gz

um_smart_hub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Trentini
+
+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.

um_smart_hub-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: um-smart-hub
+Version: 0.1.0
+Summary: Python library and CLI for the UM Smart USB Hub
+Author: Matt Trentini
+Author-email: Matt Trentini <matthew.trentini@planetinnovation.com.au>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: httpx2>=2.16.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.29.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# um-smart-hub
+
+Python library and `hub` CLI for the
+[UM Smart USB Hub](https://github.com/UnexpectedMaker/um_smart_usb_hub_6).
+Requires Python 3.14+; uses httpx2 and Typer.
+
+## CLI
+
+From this directory, run `uv run hub ...`. To install the CLI from PyPI:
+
+```sh
+uv tool install um-smart-hub
+```
+
+To install from a local checkout instead, use `uv tool install .`.
+
+```sh
+hub on 1        # turn port 1 on
+hub off 1       # turn port 1 off
+hub toggle 1    # read the current power state and flip it once
+hub toggle 1 5  # flip immediately, then every 5 seconds until Ctrl+C
+hub --host http://192.168.2.124 on 1
+hub info                  # hub identity, supplies, sensors and hardware health
+hub status                # all six ports
+hub status 6              # one port's details and next scheduled action
+hub identify 6            # flash the port's LED without changing power
+hub watch                 # refresh all port statuses every second
+hub watch 6 --interval 0.5 # monitor one port until Ctrl+C
+hub info --json
+hub status 6 --json
+hub watch 6 --json        # one JSON snapshot per line
+```
+
+The default address is `http://usb-hub.local`. Override it with `--host` (before
+any command) or `HUB_HOST`. If mDNS doesn't resolve from WSL, use the IP address.
+Looping mode prints a start message rather than each transition. Ctrl+C stops
+without switching the port off or restoring its original state.
+
+`info` and `status` emit human-readable tables by default. `watch` refreshes a
+table in an interactive terminal, or prints successive tables when redirected.
+`--json` uses the library's normalized, unit-labelled fields, not raw firmware
+field names: `info` and single-port `status` emit an object; all-port `status`
+emits an array. Each `watch --json` line is one object (selected port) or array
+(all ports). Diagnostics and the Ctrl+C message go to stderr, keeping stdout
+machine-readable.
+
+## Python library
+
+Install into another uv project:
+
+```sh
+uv add um-smart-hub
+```
+
+For local development, use `uv add /absolute/path/to/hub` instead.
+
+```python
+from smart_hub import Hub
+
+hub = Hub()  # defaults to http://usb-hub.local
+# hub = Hub("http://192.168.2.124")
+hub.on(6)
+hub.off(6)
+enabled = hub.toggle(6)  # a synchronous, single flip; returns the new bool state
+```
+
+`on`, `off`, and single-flip `toggle` are blocking calls returning the confirmed
+power state. Synchronous operations close their HTTP clients; `Hub` itself
+needs no explicit cleanup or context manager.
+
+### Information, status and identification
+
+```python
+from smart_hub import Hub, HubInfo, PortStatus
+
+hub = Hub()
+info: HubInfo = hub.info()
+ports: list[PortStatus] = hub.ports()
+port: PortStatus = hub.status(6)
+print(info.firmware, info.temperature_c, info.main_5v)
+print(port.enabled, port.occupied, port.current_ma, port.next_action)
+hub.identify(6)  # flashes the LED; does not change power
+```
+
+`HubInfo`, `PortStatus` and `ScheduledAction` are frozen dataclasses. They are
+snapshots, not live views; fetch again to refresh them. Use
+`dataclasses.asdict(snapshot)` for a JSON-compatible dictionary.
+
+- `enabled` means the firmware's switch state, not proof that a 5 V supply or
+  current is present. Check `HubInfo.main_5v` separately.
+- Absent port monitors yield `None` for `voltage_v`, `current_ma` and `power_mw`.
+  Real zero readings remain `0.0`.
+- Invalid environment readings yield `None` for `temperature_c` and
+  `humidity_percent`; an unsynced clock yields `None` for `time_iso`.
+- `power_mode` is available from `status(port)`, but is `None` in `ports()` and
+  all-port watches because the bulk endpoint doesn't supply it.
+- `next_action` is a `ScheduledAction` or `None`. It exposes `delay_seconds`,
+  `enabled` (the action's target state), `local_time` and `entry_index`.
+  `schedule_count` counts active entries; full schedule editing isn't included.
+
+### Asynchronous monitoring
+
+`watch(port=None, interval=1.0)` is an asynchronous iterator. It fetches
+immediately, waits between polls, and yields a fresh `PortStatus` for one port or
+a `list[PortStatus]` for all ports. It never changes power.
+
+```python
+import asyncio
+from contextlib import aclosing
+from smart_hub import Hub
+
+
+async def monitor():
+    hub = Hub()
+    async with aclosing(hub.watch(6, interval=0.5)) as snapshots:
+        async for port in snapshots:
+            print(port.voltage_v, port.current_ma, port.fault)
+            # Break when your application is finished monitoring.
+
+
+asyncio.run(monitor())
+```
+
+The iterator holds one async HTTP client. Cancellation closes it and propagates
+normally. Use `aclosing` as above when you may break out early, so the client is
+closed immediately. Polling errors propagate; there are no automatic retries.
+Watch intervals must be finite and strictly positive.
+
+### Asynchronous toggling
+
+Supplying an interval to `toggle` returns a coroutine instead. It uses an asynchronous HTTP
+client and `asyncio.sleep`, so it doesn't block other asyncio tasks:
+
+```python
+import asyncio
+from smart_hub import Hub
+
+
+async def main():
+    hub = Hub()
+    await hub.toggle(6, 2)  # flip immediately, then every 2 seconds indefinitely
+
+
+asyncio.run(main())
+```
+
+Inside an existing async application, cancel the task when finished:
+
+```python
+from contextlib import suppress
+
+task = asyncio.create_task(hub.toggle(6, 2))
+# ... other application work ...
+task.cancel()
+with suppress(asyncio.CancelledError):
+    await task
+```
+
+Cancellation propagates normally and doesn't send a final power command. If a
+request is interrupted in flight, it may already have reached the hub.
+
+Ports are numbered 1–6. Toggle intervals must be finite and non-negative; zero
+means no intentional delay. Invalid arguments raise `ValueError`; HTTP failures
+propagate as `httpx2.HTTPError`. Power writes check the hub's reported state,
+raising `RuntimeError` if it doesn't match; `identify` checks the acknowledgement.
+CLI errors exit with code 1. Existing hub schedules remain active and can
+independently change port power.
+
+### API choice
+
+`hub.on(6)` keeps a small, direct API. `hub[6].on()` would be useful if a retained
+port object exposed several operations or measurements, but isn't implemented:
+maintaining two equivalent interfaces isn't worthwhile for the current scope.
+
+## Development
+
+```sh
+uv sync --locked
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked ty check
+uv run --locked python -m unittest discover -s tests -v
+uv build
+```
+
+Ruff and ty are uv development dependencies. Ruff checks lint, import ordering,
+Python modernization, and formatting; ty checks the library, CLI, and tests
+using Python 3.14. To apply Ruff's safe fixes and formatting locally:
+
+```sh
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+`.github/workflows/ci.yml` runs lint, formatting, types, and regression checks on
+pull requests and pushes to `main`. The release workflow calls the same CI
+workflow before building distributions, so publishing cannot bypass those
+checks. No pre-commit hook is required.
+
+Distribution name: `um-smart-hub`; import package: `smart_hub`; CLI command: `hub`.
+The CLI delegates all hub controls to the library.
+
+## Releases and PyPI publishing
+
+`.github/workflows/release.yml` runs when a `v*` tag is **pushed**. It first calls
+the shared CI workflow to run Ruff, ty, and the regression suite on Python 3.14
+with locked dependencies. It then checks that the tag exactly matches `v` plus
+`[project].version`, builds a wheel and source distribution, and checks their
+metadata with Twine. A separate job publishes those artifacts to PyPI using
+Trusted Publishing. Only after publishing succeeds does it create a GitHub
+release with generated notes and attach the same distributions.
+
+Publishing uses short-lived GitHub OIDC credentials, not a stored PyPI API token.
+Only the publishing job has `id-token: write`; only the GitHub release job has
+`contents: write`. Actions are pinned to commit hashes.
+
+### One-time setup before the first release
+
+1. The PyPI distribution name is **`um-smart-hub`** (`[project].name` in
+   `pyproject.toml`). The explicit build-backend `module-name = "smart_hub"`
+   keeps the import package independent of the distribution name. The CLI
+   remains `hub`.
+2. In this repository's GitHub settings, create an environment named **`pypi`**.
+   Restrict deployments to release tags (`v*`); requiring reviewer approval is
+   recommended.
+3. In your [PyPI publishing settings](https://pypi.org/manage/account/publishing/),
+   add a **pending Trusted Publisher** for `um-smart-hub`:
+
+   | Setting | Value |
+   |---|---|
+   | PyPI project | `um-smart-hub` |
+   | Owner | `mattytrentini` |
+   | Repository | `um-smart-hub` |
+   | Workflow filename | `release.yml` |
+   | Environment | `pypi` |
+
+   For an existing PyPI project you own, add the same publisher in that project's
+   publishing settings instead. A pending publisher creates a new project on the
+   first successful upload; it **does not reserve its name** in advance. See the
+   [PyPI setup guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+4. Commit and push the workflow, package metadata, and lockfile before pushing
+   a release tag.
+
+### Creating a release
+
+For an initial `0.1.0` release, after completing the setup above:
+
+```sh
+uv version 0.1.0
+uv lock
+# Commit any name/version/lockfile changes, then push the release commit.
+git push origin main
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+Use a new package version and matching tag for each subsequent release. Creating
+a local tag alone does not publish anything. Never reuse a version already
+uploaded to PyPI. The workflow deliberately has no manual-dispatch trigger.

um_smart_hub-0.1.0/README.md

@@ -0,0 +1,259 @@
+# um-smart-hub
+
+Python library and `hub` CLI for the
+[UM Smart USB Hub](https://github.com/UnexpectedMaker/um_smart_usb_hub_6).
+Requires Python 3.14+; uses httpx2 and Typer.
+
+## CLI
+
+From this directory, run `uv run hub ...`. To install the CLI from PyPI:
+
+```sh
+uv tool install um-smart-hub
+```
+
+To install from a local checkout instead, use `uv tool install .`.
+
+```sh
+hub on 1        # turn port 1 on
+hub off 1       # turn port 1 off
+hub toggle 1    # read the current power state and flip it once
+hub toggle 1 5  # flip immediately, then every 5 seconds until Ctrl+C
+hub --host http://192.168.2.124 on 1
+hub info                  # hub identity, supplies, sensors and hardware health
+hub status                # all six ports
+hub status 6              # one port's details and next scheduled action
+hub identify 6            # flash the port's LED without changing power
+hub watch                 # refresh all port statuses every second
+hub watch 6 --interval 0.5 # monitor one port until Ctrl+C
+hub info --json
+hub status 6 --json
+hub watch 6 --json        # one JSON snapshot per line
+```
+
+The default address is `http://usb-hub.local`. Override it with `--host` (before
+any command) or `HUB_HOST`. If mDNS doesn't resolve from WSL, use the IP address.
+Looping mode prints a start message rather than each transition. Ctrl+C stops
+without switching the port off or restoring its original state.
+
+`info` and `status` emit human-readable tables by default. `watch` refreshes a
+table in an interactive terminal, or prints successive tables when redirected.
+`--json` uses the library's normalized, unit-labelled fields, not raw firmware
+field names: `info` and single-port `status` emit an object; all-port `status`
+emits an array. Each `watch --json` line is one object (selected port) or array
+(all ports). Diagnostics and the Ctrl+C message go to stderr, keeping stdout
+machine-readable.
+
+## Python library
+
+Install into another uv project:
+
+```sh
+uv add um-smart-hub
+```
+
+For local development, use `uv add /absolute/path/to/hub` instead.
+
+```python
+from smart_hub import Hub
+
+hub = Hub()  # defaults to http://usb-hub.local
+# hub = Hub("http://192.168.2.124")
+hub.on(6)
+hub.off(6)
+enabled = hub.toggle(6)  # a synchronous, single flip; returns the new bool state
+```
+
+`on`, `off`, and single-flip `toggle` are blocking calls returning the confirmed
+power state. Synchronous operations close their HTTP clients; `Hub` itself
+needs no explicit cleanup or context manager.
+
+### Information, status and identification
+
+```python
+from smart_hub import Hub, HubInfo, PortStatus
+
+hub = Hub()
+info: HubInfo = hub.info()
+ports: list[PortStatus] = hub.ports()
+port: PortStatus = hub.status(6)
+print(info.firmware, info.temperature_c, info.main_5v)
+print(port.enabled, port.occupied, port.current_ma, port.next_action)
+hub.identify(6)  # flashes the LED; does not change power
+```
+
+`HubInfo`, `PortStatus` and `ScheduledAction` are frozen dataclasses. They are
+snapshots, not live views; fetch again to refresh them. Use
+`dataclasses.asdict(snapshot)` for a JSON-compatible dictionary.
+
+- `enabled` means the firmware's switch state, not proof that a 5 V supply or
+  current is present. Check `HubInfo.main_5v` separately.
+- Absent port monitors yield `None` for `voltage_v`, `current_ma` and `power_mw`.
+  Real zero readings remain `0.0`.
+- Invalid environment readings yield `None` for `temperature_c` and
+  `humidity_percent`; an unsynced clock yields `None` for `time_iso`.
+- `power_mode` is available from `status(port)`, but is `None` in `ports()` and
+  all-port watches because the bulk endpoint doesn't supply it.
+- `next_action` is a `ScheduledAction` or `None`. It exposes `delay_seconds`,
+  `enabled` (the action's target state), `local_time` and `entry_index`.
+  `schedule_count` counts active entries; full schedule editing isn't included.
+
+### Asynchronous monitoring
+
+`watch(port=None, interval=1.0)` is an asynchronous iterator. It fetches
+immediately, waits between polls, and yields a fresh `PortStatus` for one port or
+a `list[PortStatus]` for all ports. It never changes power.
+
+```python
+import asyncio
+from contextlib import aclosing
+from smart_hub import Hub
+
+
+async def monitor():
+    hub = Hub()
+    async with aclosing(hub.watch(6, interval=0.5)) as snapshots:
+        async for port in snapshots:
+            print(port.voltage_v, port.current_ma, port.fault)
+            # Break when your application is finished monitoring.
+
+
+asyncio.run(monitor())
+```
+
+The iterator holds one async HTTP client. Cancellation closes it and propagates
+normally. Use `aclosing` as above when you may break out early, so the client is
+closed immediately. Polling errors propagate; there are no automatic retries.
+Watch intervals must be finite and strictly positive.
+
+### Asynchronous toggling
+
+Supplying an interval to `toggle` returns a coroutine instead. It uses an asynchronous HTTP
+client and `asyncio.sleep`, so it doesn't block other asyncio tasks:
+
+```python
+import asyncio
+from smart_hub import Hub
+
+
+async def main():
+    hub = Hub()
+    await hub.toggle(6, 2)  # flip immediately, then every 2 seconds indefinitely
+
+
+asyncio.run(main())
+```
+
+Inside an existing async application, cancel the task when finished:
+
+```python
+from contextlib import suppress
+
+task = asyncio.create_task(hub.toggle(6, 2))
+# ... other application work ...
+task.cancel()
+with suppress(asyncio.CancelledError):
+    await task
+```
+
+Cancellation propagates normally and doesn't send a final power command. If a
+request is interrupted in flight, it may already have reached the hub.
+
+Ports are numbered 1–6. Toggle intervals must be finite and non-negative; zero
+means no intentional delay. Invalid arguments raise `ValueError`; HTTP failures
+propagate as `httpx2.HTTPError`. Power writes check the hub's reported state,
+raising `RuntimeError` if it doesn't match; `identify` checks the acknowledgement.
+CLI errors exit with code 1. Existing hub schedules remain active and can
+independently change port power.
+
+### API choice
+
+`hub.on(6)` keeps a small, direct API. `hub[6].on()` would be useful if a retained
+port object exposed several operations or measurements, but isn't implemented:
+maintaining two equivalent interfaces isn't worthwhile for the current scope.
+
+## Development
+
+```sh
+uv sync --locked
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked ty check
+uv run --locked python -m unittest discover -s tests -v
+uv build
+```
+
+Ruff and ty are uv development dependencies. Ruff checks lint, import ordering,
+Python modernization, and formatting; ty checks the library, CLI, and tests
+using Python 3.14. To apply Ruff's safe fixes and formatting locally:
+
+```sh
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+`.github/workflows/ci.yml` runs lint, formatting, types, and regression checks on
+pull requests and pushes to `main`. The release workflow calls the same CI
+workflow before building distributions, so publishing cannot bypass those
+checks. No pre-commit hook is required.
+
+Distribution name: `um-smart-hub`; import package: `smart_hub`; CLI command: `hub`.
+The CLI delegates all hub controls to the library.
+
+## Releases and PyPI publishing
+
+`.github/workflows/release.yml` runs when a `v*` tag is **pushed**. It first calls
+the shared CI workflow to run Ruff, ty, and the regression suite on Python 3.14
+with locked dependencies. It then checks that the tag exactly matches `v` plus
+`[project].version`, builds a wheel and source distribution, and checks their
+metadata with Twine. A separate job publishes those artifacts to PyPI using
+Trusted Publishing. Only after publishing succeeds does it create a GitHub
+release with generated notes and attach the same distributions.
+
+Publishing uses short-lived GitHub OIDC credentials, not a stored PyPI API token.
+Only the publishing job has `id-token: write`; only the GitHub release job has
+`contents: write`. Actions are pinned to commit hashes.
+
+### One-time setup before the first release
+
+1. The PyPI distribution name is **`um-smart-hub`** (`[project].name` in
+   `pyproject.toml`). The explicit build-backend `module-name = "smart_hub"`
+   keeps the import package independent of the distribution name. The CLI
+   remains `hub`.
+2. In this repository's GitHub settings, create an environment named **`pypi`**.
+   Restrict deployments to release tags (`v*`); requiring reviewer approval is
+   recommended.
+3. In your [PyPI publishing settings](https://pypi.org/manage/account/publishing/),
+   add a **pending Trusted Publisher** for `um-smart-hub`:
+
+   | Setting | Value |
+   |---|---|
+   | PyPI project | `um-smart-hub` |
+   | Owner | `mattytrentini` |
+   | Repository | `um-smart-hub` |
+   | Workflow filename | `release.yml` |
+   | Environment | `pypi` |
+
+   For an existing PyPI project you own, add the same publisher in that project's
+   publishing settings instead. A pending publisher creates a new project on the
+   first successful upload; it **does not reserve its name** in advance. See the
+   [PyPI setup guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+4. Commit and push the workflow, package metadata, and lockfile before pushing
+   a release tag.
+
+### Creating a release
+
+For an initial `0.1.0` release, after completing the setup above:
+
+```sh
+uv version 0.1.0
+uv lock
+# Commit any name/version/lockfile changes, then push the release commit.
+git push origin main
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+Use a new package version and matching tag for each subsequent release. Creating
+a local tag alone does not publish anything. Never reuse a version already
+uploaded to PyPI. The workflow deliberately has no manual-dispatch trigger.

um_smart_hub-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "um-smart-hub"
+version = "0.1.0"
+description = "Python library and CLI for the UM Smart USB Hub"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx2>=2.16.0",
+    "rich>=15.0.0",
+    "typer>=0.29.0",
+]
+
+[[project.authors]]
+name = "Matt Trentini"
+email = "matthew.trentini@planetinnovation.com.au"
+
+[project.scripts]
+hub = "smart_hub.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.12.8,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "smart_hub"
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.17.4",
+    "ty>=0.0.100",
+]

um_smart_hub-0.1.0/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[project]
+name = "um-smart-hub"
+version = "0.1.0"
+description = "Python library and CLI for the UM Smart USB Hub"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Matt Trentini", email = "matthew.trentini@planetinnovation.com.au" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx2>=2.16.0",
+    "rich>=15.0.0",
+    "typer>=0.29.0",
+]
+
+[project.scripts]
+hub = "smart_hub.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.12.8,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "smart_hub"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.17.4",
+    "ty>=0.0.100",
+]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP"]
+
+[tool.ty.environment]
+python-version = "3.14"

um_smart_hub-0.1.0/src/smart_hub/__init__.py

@@ -0,0 +1,172 @@
+"""Typed hub snapshots, port identification, and synchronous/async controls."""
+
+import asyncio
+import math
+from collections.abc import AsyncGenerator, Coroutine
+from typing import Any, overload
+
+import httpx2
+
+from .models import HubInfo, PortStatus, ScheduledAction
+
+__all__ = ["Hub", "HubInfo", "PortStatus", "ScheduledAction"]
+
+
+def _validate_port(port: int) -> None:
+    if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 6:
+        raise ValueError("port must be an integer from 1 to 6")
+
+
+def _confirmed(response: httpx2.Response, port: int, enabled: bool) -> bool:
+    response.raise_for_status()
+    # Firmware can silently ignore a write and still return HTTP 200.
+    actual = response.json()["ports"][port - 1]["enabled"]
+    if actual is not enabled:
+        raise RuntimeError(f"port {port} reports enabled={actual}, expected {enabled}")
+    return actual
+
+
+class Hub:
+    """Control a hub at base_url (default http://usb-hub.local).
+
+    HTTP failures raise httpx2.HTTPError. Rejected state changes raise RuntimeError.
+    Clients are scoped to each operation; watch holds one until its iterator closes.
+    """
+
+    def __init__(self, base_url: str = "http://usb-hub.local") -> None:
+        self.base_url = base_url
+
+    def info(self) -> HubInfo:
+        """Fetch an immutable hub-wide snapshot, not a live view."""
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            response = client.get("/api/hub")
+            response.raise_for_status()
+            return HubInfo.from_api(response.json())
+
+    def ports(self) -> list[PortStatus]:
+        """Fetch all port snapshots; bulk data does not include power modes."""
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            response = client.get("/api/ports")
+            response.raise_for_status()
+            return [PortStatus.from_api(data) for data in response.json()["ports"]]
+
+    def status(self, port: int) -> PortStatus:
+        """Fetch one immutable port snapshot, including its power mode."""
+        _validate_port(port)
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            response = client.get(f"/api/ports/{port}")
+            response.raise_for_status()
+            return PortStatus.from_api(response.json())
+
+    def identify(self, port: int) -> None:
+        """Flash a port's identification LED without changing its power state."""
+        _validate_port(port)
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            response = client.post("/api/identify", params={"n": port})
+            response.raise_for_status()
+            if response.json().get("ok") is not True:
+                raise RuntimeError(f"port {port} identification was not acknowledged")
+
+    @overload
+    def watch(self, port: int, interval: float = 1.0) -> AsyncGenerator[PortStatus]: ...
+
+    @overload
+    def watch(
+        self, port: None = None, interval: float = 1.0
+    ) -> AsyncGenerator[list[PortStatus]]: ...
+
+    def watch(
+        self, port: int | None = None, interval: float = 1.0
+    ) -> AsyncGenerator[PortStatus | list[PortStatus]]:
+        """Poll fresh snapshots immediately, then sleep interval between polls.
+
+        One async client lives for the iterator's lifetime. Cancellation and HTTP
+        errors propagate and close it without changing power. Close the iterator
+        with aclose() (or contextlib.aclosing) when stopping consumption early.
+        Each yielded value is a separate snapshot, not an updating live view;
+        all-port snapshots omit power modes just like ports().
+        """
+        if port is not None:
+            _validate_port(port)
+        if not math.isfinite(interval) or interval <= 0:
+            raise ValueError("interval must be finite and strictly positive")
+        return self._watch_loop(port, interval)
+
+    async def _watch_loop(
+        self, port: int | None, interval: float
+    ) -> AsyncGenerator[PortStatus | list[PortStatus]]:
+        """Keep a single read-only client until cancellation or iterator closure."""
+        path = "/api/ports" if port is None else f"/api/ports/{port}"
+        async with httpx2.AsyncClient(base_url=self.base_url, timeout=5.0) as client:
+            while True:
+                response = await client.get(path)
+                response.raise_for_status()
+                data = response.json()
+                if port is None:
+                    yield [PortStatus.from_api(item) for item in data["ports"]]
+                else:
+                    yield PortStatus.from_api(data)
+                await asyncio.sleep(interval)
+
+    def _set(self, port: int, enabled: bool) -> bool:
+        _validate_port(port)
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            return _confirmed(
+                client.post("/api/port", params={"n": port, "on": int(enabled)}),
+                port,
+                enabled,
+            )
+
+    def on(self, port: int) -> bool:
+        """Turn port on and return its confirmed power state (True)."""
+        return self._set(port, True)
+
+    def off(self, port: int) -> bool:
+        """Turn port off and return its confirmed power state (False)."""
+        return self._set(port, False)
+
+    @overload
+    def toggle(self, port: int, seconds: None = None) -> bool: ...
+
+    @overload
+    def toggle(self, port: int, seconds: float) -> Coroutine[Any, Any, None]: ...
+
+    def toggle(
+        self, port: int, seconds: float | None = None
+    ) -> bool | Coroutine[Any, Any, None]:
+        """Flip once synchronously, or return an async loop when seconds is given.
+
+        The loop flips immediately, then waits seconds between changes. Cancel
+        its task to stop; cancellation never deliberately changes the final state.
+        A request interrupted in flight may already have reached the hub.
+        """
+        _validate_port(port)
+        if seconds is not None:
+            if not math.isfinite(seconds) or seconds < 0:
+                raise ValueError("seconds must be finite and non-negative")
+            return self._toggle_loop(port, seconds)
+        with httpx2.Client(base_url=self.base_url, timeout=5.0) as client:
+            response = client.get(f"/api/ports/{port}")
+            response.raise_for_status()
+            enabled = not response.json()["enabled"]
+            return _confirmed(
+                client.post("/api/port", params={"n": port, "on": int(enabled)}),
+                port,
+                enabled,
+            )
+
+    async def _toggle_loop(self, port: int, seconds: float) -> None:
+        async with httpx2.AsyncClient(base_url=self.base_url, timeout=5.0) as client:
+            response = await client.get(f"/api/ports/{port}")
+            response.raise_for_status()
+            enabled = not response.json()["enabled"]
+            while True:
+                _confirmed(
+                    await client.post(
+                        "/api/port", params={"n": port, "on": int(enabled)}
+                    ),
+                    port,
+                    enabled,
+                )
+                await asyncio.sleep(seconds)
+                enabled = not enabled

um_smart_hub-0.1.0/src/smart_hub/cli.py

@@ -0,0 +1,274 @@
+"""Typer entry point; all hub interaction is implemented by Hub."""
+
+import asyncio
+import json
+from collections.abc import Callable, Coroutine, Generator
+from contextlib import aclosing, contextmanager
+from dataclasses import asdict
+from typing import Annotated, Any
+
+import httpx2
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+from rich.text import Text
+
+from smart_hub import Hub, HubInfo, PortStatus
+
+app = typer.Typer(add_completion=False, no_args_is_help=True)
+Port = Annotated[int, typer.Argument(min=1, max=6, help="Port number (1-6).")]
+OptionalPort = Annotated[
+    int | None, typer.Argument(min=1, max=6, help="Port number; omit for all ports.")
+]
+JsonOutput = Annotated[
+    bool, typer.Option("--json", help="Output JSON instead of a table.")
+]
+console = Console(markup=False, highlight=False, emoji=False)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    host: Annotated[
+        str, typer.Option(envvar="HUB_HOST", help="Hub base URL.")
+    ] = "http://usb-hub.local",
+) -> None:
+    """Control the UM Smart USB Hub's ports."""
+    ctx.obj = Hub(host)
+
+
+@contextmanager
+def _errors() -> Generator[None]:
+    try:
+        yield
+    except KeyboardInterrupt:
+        typer.echo("stopped", err=True)
+    except (httpx2.HTTPError, RuntimeError, ValueError) as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from error
+
+
+def _run(port: int, action: Callable[[], bool | Coroutine[Any, Any, None]]) -> None:
+    with _errors():
+        result = action()
+        if isinstance(result, bool):
+            typer.echo(f"port {port} {'on' if result else 'off'}")
+        else:
+            asyncio.run(result)
+
+
+def _json(snapshot: HubInfo | PortStatus | list[PortStatus]) -> None:
+    data = (
+        [asdict(port) for port in snapshot]
+        if isinstance(snapshot, list)
+        else asdict(snapshot)
+    )
+    typer.echo(json.dumps(data, allow_nan=False))
+
+
+def _value(value: object, unit: str = "") -> str:
+    if value is None:
+        return "unavailable"
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    return f"{value}{unit}"
+
+
+def _info_table(snapshot: HubInfo) -> Table:
+    table = Table(title=Text(snapshot.name), show_header=False)
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+    rows = [
+        ("Firmware", snapshot.firmware),
+        ("Uptime", _value(snapshot.uptime_seconds, " s")),
+        ("Reset reason", snapshot.reset_reason),
+        (
+            "Main / upstream 5 V",
+            f"{_value(snapshot.main_5v)} / {_value(snapshot.upstream_5v)}",
+        ),
+        ("Total current", _value(snapshot.total_current_ma, " mA")),
+        ("Total power", _value(snapshot.total_power_mw, " mW")),
+        ("Temperature", _value(snapshot.temperature_c, " °C")),
+        ("Humidity", _value(snapshot.humidity_percent, " %")),
+        ("Clock synced", _value(snapshot.clock_synced)),
+        ("Time", _value(snapshot.time_iso)),
+        ("UTC offset", _value(snapshot.utc_offset_hours, " h")),
+        ("Network connected", _value(snapshot.network_connected)),
+        ("IP address", snapshot.ip_address),
+        ("Hostname", snapshot.hostname),
+        ("WiFi SSID", snapshot.ssid),
+        ("WiFi RSSI", _value(snapshot.rssi_dbm, " dBm")),
+        ("Expander present", _value(snapshot.expander_present)),
+        (
+            "Current monitors present",
+            f"{_value(snapshot.current_monitor_1_present)} / {_value(snapshot.current_monitor_2_present)}",
+        ),
+        ("Environment sensor present", _value(snapshot.environment_sensor_present)),
+        (
+            "Free heap / largest block",
+            f"{snapshot.heap_free_bytes} / {snapshot.heap_largest_block_bytes} bytes",
+        ),
+        (
+            "Ports enabled / occupied / faulted",
+            f"{snapshot.ports_enabled} / {snapshot.ports_occupied} / {snapshot.ports_faulted} of {snapshot.port_count}",
+        ),
+    ]
+    for label, value in rows:
+        table.add_row(label, value)
+    return table
+
+
+def _next_action(port: PortStatus) -> str:
+    action = port.next_action
+    if action is None:
+        return "—"
+    return f"{'on' if action.enabled else 'off'} {action.local_time} ({action.delay_seconds}s)"
+
+
+def _status_table(snapshot: PortStatus | list[PortStatus]) -> Table:
+    if isinstance(snapshot, PortStatus):
+        table = Table(title=f"Port {snapshot.number}", show_header=False)
+        table.add_column("Field", style="bold")
+        table.add_column("Value")
+        rows = [
+            ("Name", snapshot.name or "—"),
+            ("Enabled", _value(snapshot.enabled)),
+            ("Device present", _value(snapshot.occupied)),
+            ("Fault", _value(snapshot.fault)),
+            ("LED state", snapshot.led_state),
+            ("Monitor present", _value(snapshot.monitor_present)),
+            ("Voltage", _value(snapshot.voltage_v, " V")),
+            ("Current", _value(snapshot.current_ma, " mA")),
+            ("Power", _value(snapshot.power_mw, " mW")),
+            ("Power mode", _value(snapshot.power_mode)),
+            ("Active schedule entries", str(snapshot.schedule_count)),
+            ("Next action", _next_action(snapshot)),
+        ]
+        for label, value in rows:
+            table.add_row(label, value)
+        return table
+    table = Table(title="Ports — enabled is a switch state, not a supply check")
+    for column in (
+        "Port",
+        "Name",
+        "Enabled",
+        "Device",
+        "Fault",
+        "V",
+        "mA",
+        "mW",
+        "Next",
+    ):
+        table.add_column(column)
+    for port in snapshot:
+        table.add_row(
+            str(port.number),
+            port.name or "—",
+            _value(port.enabled),
+            _value(port.occupied),
+            _value(port.fault),
+            *(
+                _value(value) if value is not None else "—"
+                for value in (port.voltage_v, port.current_ma, port.power_mw)
+            ),
+            _next_action(port),
+        )
+    table.caption = "Device = plugged in; — measurement = unavailable"
+    return table
+
+
+@app.command()
+def info(ctx: typer.Context, json_output: JsonOutput = False) -> None:
+    """Show hub identity, supply, sensors, network and hardware health."""
+    with _errors():
+        snapshot = ctx.obj.info()
+        if json_output:
+            _json(snapshot)
+        else:
+            console.print(_info_table(snapshot), markup=False)
+
+
+@app.command()
+def status(
+    ctx: typer.Context, port: OptionalPort = None, json_output: JsonOutput = False
+) -> None:
+    """Show one port's details, or a table of all ports."""
+    with _errors():
+        snapshot = ctx.obj.ports() if port is None else ctx.obj.status(port)
+        if json_output:
+            _json(snapshot)
+        else:
+            console.print(_status_table(snapshot), markup=False)
+
+
+@app.command()
+def identify(ctx: typer.Context, port: Port) -> None:
+    """Flash PORT's LED without switching its power."""
+    with _errors():
+        ctx.obj.identify(port)
+        typer.echo(f"identifying port {port}")
+
+
+async def _watch(
+    hub: Hub, port: int | None, interval: float, json_output: bool
+) -> None:
+    async with aclosing(hub.watch(port, interval=interval)) as snapshots:
+        if not json_output and console.is_terminal:
+            with Live(console=console, auto_refresh=False) as live:
+                async for snapshot in snapshots:
+                    live.update(_status_table(snapshot), refresh=True)
+        else:
+            async for snapshot in snapshots:
+                if json_output:
+                    _json(snapshot)
+                else:
+                    console.print(_status_table(snapshot), markup=False)
+
+
+@app.command()
+def watch(
+    ctx: typer.Context,
+    port: OptionalPort = None,
+    interval: Annotated[
+        float,
+        typer.Option(min=0, help="Polling interval in seconds; must be positive."),
+    ] = 1.0,
+    json_output: JsonOutput = False,
+) -> None:
+    """Monitor port status until Ctrl+C. --json emits one snapshot per line.
+
+    Monitoring is read-only. Omit PORT to watch all ports.
+    """
+    with _errors():
+        asyncio.run(_watch(ctx.obj, port, interval, json_output))
+
+
+@app.command()
+def on(ctx: typer.Context, port: Port) -> None:
+    """Turn PORT on."""
+    _run(port, lambda: ctx.obj.on(port))
+
+
+@app.command()
+def off(ctx: typer.Context, port: Port) -> None:
+    """Turn PORT off."""
+    _run(port, lambda: ctx.obj.off(port))
+
+
+@app.command()
+def toggle(
+    ctx: typer.Context,
+    port: Port,
+    seconds: Annotated[
+        float | None,
+        typer.Argument(min=0, help="Toggle again every SECONDS until Ctrl+C."),
+    ] = None,
+) -> None:
+    """Flip PORT's power. With SECONDS, keep flipping until Ctrl+C.
+
+    Ctrl+C leaves the port in whatever state it was in.
+    """
+    if seconds is not None:
+        typer.echo(f"toggling port {port} every {seconds:g} seconds; Ctrl+C to stop")
+    _run(port, lambda: ctx.obj.toggle(port, seconds))

um_smart_hub-0.1.0/src/smart_hub/models.py

@@ -0,0 +1,144 @@
+"""Immutable snapshots decoded from the hub's REST API."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ScheduledAction:
+    """The next scheduled action at the instant a snapshot was fetched."""
+
+    delay_seconds: int
+    enabled: bool
+    local_time: str
+    entry_index: int
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> ScheduledAction:
+        """Decode the API's next-action object without schedule entry details."""
+        return cls(
+            delay_seconds=data["in_s"],
+            enabled=data["on"],
+            local_time=data["at"],
+            entry_index=data["entry"],
+        )
+
+
+@dataclass(frozen=True)
+class PortStatus:
+    """One immutable port snapshot; unavailable readings are None, not zero."""
+
+    number: int
+    name: str
+    enabled: bool
+    occupied: bool
+    fault: bool
+    led_state: str
+    monitor_present: bool
+    voltage_v: float | None
+    current_ma: float | None
+    power_mw: float | None
+    power_mode: str | None
+    schedule_count: int
+    next_action: ScheduledAction | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> PortStatus:
+        """Decode either port endpoint; bulk snapshots omit power_mode."""
+        monitor = data["monitor"]
+        schedule = data["schedule"]
+        next_action = schedule["next"]
+        return cls(
+            number=data["n"],
+            name=data["name"],
+            enabled=data["enabled"],
+            occupied=data["occupied"],
+            fault=data["fault"],
+            led_state=data["state"],
+            monitor_present=monitor,
+            voltage_v=float(data["volts"]) if monitor else None,
+            current_ma=float(data["ma"]) if monitor else None,
+            power_mw=float(data["mw"]) if monitor else None,
+            power_mode=data.get("power_mode"),
+            schedule_count=schedule["count"],
+            next_action=(
+                ScheduledAction.from_api(next_action)
+                if next_action is not None
+                else None
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class HubInfo:
+    """Immutable hub-wide snapshot, with invalid sensor and clock data absent."""
+
+    name: str
+    firmware: str
+    uptime_seconds: int
+    reset_reason: str
+    main_5v: bool
+    upstream_5v: bool
+    total_current_ma: float
+    total_power_mw: float
+    temperature_c: float | None
+    humidity_percent: float | None
+    clock_synced: bool
+    time_iso: str | None
+    utc_offset_hours: float
+    network_connected: bool
+    ip_address: str
+    ssid: str
+    rssi_dbm: int
+    hostname: str
+    expander_present: bool
+    current_monitor_1_present: bool
+    current_monitor_2_present: bool
+    environment_sensor_present: bool
+    heap_free_bytes: int
+    heap_largest_block_bytes: int
+    port_count: int
+    ports_enabled: int
+    ports_occupied: int
+    ports_faulted: int
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> HubInfo:
+        """Normalize /api/hub, retaining only currently valid measurements."""
+        power = data["power"]
+        sensors = data["sensors"]
+        clock = data["clock"]
+        network = data["network"]
+        devices = data["devices"]
+        memory = data["memory"]
+        ports = data["ports_summary"]
+        return cls(
+            name=data["name"],
+            firmware=data["fw"],
+            uptime_seconds=data["uptime_s"],
+            reset_reason=data["reset_reason"],
+            main_5v=power["main_5v"],
+            upstream_5v=power["upstream_5v"],
+            total_current_ma=float(power["total_ma"]),
+            total_power_mw=float(power["total_mw"]),
+            temperature_c=float(sensors["temp_c"]) if sensors["valid"] else None,
+            humidity_percent=float(sensors["humidity"]) if sensors["valid"] else None,
+            clock_synced=clock["synced"],
+            time_iso=clock["iso"] if clock["synced"] else None,
+            utc_offset_hours=float(clock["utc_offset"]),
+            network_connected=network["connected"],
+            ip_address=network["ip"],
+            ssid=network["ssid"],
+            rssi_dbm=network["rssi"],
+            hostname=network["hostname"],
+            expander_present=devices["expander"],
+            current_monitor_1_present=devices["ina_1"],
+            current_monitor_2_present=devices["ina_2"],
+            environment_sensor_present=devices["aht20"],
+            heap_free_bytes=memory["heap_free"],
+            heap_largest_block_bytes=memory["heap_max_block"],
+            port_count=ports["count"],
+            ports_enabled=ports["powered"],
+            ports_occupied=ports["occupied"],
+            ports_faulted=ports["faulted"],
+        )