hyperheadset 0.1.0__tar.gz

hyperheadset-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: hyperheadset
+Version: 0.1.0
+Summary: Astro A50 base station HID stats client
+Author: Hyper
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hidapi>=0.14.0
+
+# Hyperheadset
+
+A small Python CLI and library for reading live status data from the Astro
+A50 base station over HID.
+
+This started as a side project because I wanted to see battery %, dock
+state, and sidetone levels without running the official Astro software
+in the background. That turned into reverse-engineering the HID
+protocol... which turned into this.
+
+It talks directly to the base station, parses the response frames, and
+exposes the useful bits in a clean way.
+
+---
+
+## What it can do
+Right now it focuses on reading states.
+
+- Read battery percentage + charging state
+- Detect whether the headset is docked / powered
+- Read sidetone slider values (active + saved)
+- Output as JSON (compact or pretty)
+- CSV logging
+- Watch mode (with change detection)
+- Filter specific fields (`--fields`)
+- List matching HID devices
+- Usable as both a CLI tool and a Python module
+
+## Install
+
+Not on PyPI (yet).
+
+Local install:
+
+```bash
+pip install .
+```
+
+Editable dev install:
+
+```bash
+pip install -e .
+```
+
+## CLI Usage
+
+Default snapshot:
+
+```bash
+hyperheadset
+```
+
+Some common flags:
+
+- Battery only → `--battery`
+- JSON output → `--json`
+- Pretty JSON → `--json --p`
+- Watch mode → `--watch`
+- Only show changes (watch mode) → `--changes-only`
+- List matching HID devices → `--device-list`
+
+### Examples
+
+Watch only sidetone, and only print when it changes:
+``` bash
+hyperheadset --fields sidetone --watch --changes-only
+```
+
+Log everything to CSV every 2 seconds:
+``` bash
+hyperheadset --csv --watch --interval 2 > log.csv
+```
+
+Pretty JSON snapshot without timestamp:
+``` bash
+hyperheadset --json --p --no-timestamp
+```
+
+## Python Usage
+You can also use it directly in code:
+
+```python
+from hyperheadset import AstroA50Client, SliderType
+
+client = AstroA50Client()
+
+battery = client.getBatteryStatus()
+print(battery.chargePercent, battery.isCharging)
+
+sidetone = client.getSliderValue(SliderType.sidetone)
+print(sidetone)
+```
+
+Snapshot helper:
+```python
+snap = client.getSnapshot(battery=True, headset=True, sidetone=True)
+print(snap)
+```
+
+
+
+## Requirements
+- Python 3.10+
+- `hidapi` bindings (`pip install hidapi`)
+- Astro A50 base station connected over USB
+- OS must expose the device as a standard HID interface
+
+If your OS doesn't see it as HID, this won't work. No custom drivers
+included here.
+
+## Scope (and what this is *not*)
+
+This project focuses on:
+
+- Reading device state
+- Protocol framing
+- Simple query commands
+
+It's **not**:
+- A replacement for the official Astro software
+- A firmware updater
+- An EQ editor
+
+Write/set commands *might* be added later, but only after making sure
+they're safe. Bricking a headset is not on the roadmap.
+
+## Credits / Prior Work
+Huge credit to the [eh-fifty](https://github.com/tdryer/eh-fifty) project by Tom Dryer.
+
+That project documents and reverse-engineers large parts of the Astro
+A50 USB/HID protocol. I studied their research to understand the framing
+and command structure, then re-implemented what I needed in a smaller
+codebase focused purely on stats and queries.
+
+No source code from [eh-fifty](https://github.com/tdryer/eh-fifty) is included here but their work made
+this possible.
+
+If you want broader device coverage or deeper protocol exploration,
+definitely check that repository out.
+
+
+## License
+
+MIT
+
+
+## Disclaimer
+
+Not affiliated with or endorsed by Astro, Logitech, or the eh-fifty
+project authors.

hyperheadset-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Hyperheadset
+
+A small Python CLI and library for reading live status data from the Astro
+A50 base station over HID.
+
+This started as a side project because I wanted to see battery %, dock
+state, and sidetone levels without running the official Astro software
+in the background. That turned into reverse-engineering the HID
+protocol... which turned into this.
+
+It talks directly to the base station, parses the response frames, and
+exposes the useful bits in a clean way.
+
+---
+
+## What it can do
+Right now it focuses on reading states.
+
+- Read battery percentage + charging state
+- Detect whether the headset is docked / powered
+- Read sidetone slider values (active + saved)
+- Output as JSON (compact or pretty)
+- CSV logging
+- Watch mode (with change detection)
+- Filter specific fields (`--fields`)
+- List matching HID devices
+- Usable as both a CLI tool and a Python module
+
+## Install
+
+Not on PyPI (yet).
+
+Local install:
+
+```bash
+pip install .
+```
+
+Editable dev install:
+
+```bash
+pip install -e .
+```
+
+## CLI Usage
+
+Default snapshot:
+
+```bash
+hyperheadset
+```
+
+Some common flags:
+
+- Battery only → `--battery`
+- JSON output → `--json`
+- Pretty JSON → `--json --p`
+- Watch mode → `--watch`
+- Only show changes (watch mode) → `--changes-only`
+- List matching HID devices → `--device-list`
+
+### Examples
+
+Watch only sidetone, and only print when it changes:
+``` bash
+hyperheadset --fields sidetone --watch --changes-only
+```
+
+Log everything to CSV every 2 seconds:
+``` bash
+hyperheadset --csv --watch --interval 2 > log.csv
+```
+
+Pretty JSON snapshot without timestamp:
+``` bash
+hyperheadset --json --p --no-timestamp
+```
+
+## Python Usage
+You can also use it directly in code:
+
+```python
+from hyperheadset import AstroA50Client, SliderType
+
+client = AstroA50Client()
+
+battery = client.getBatteryStatus()
+print(battery.chargePercent, battery.isCharging)
+
+sidetone = client.getSliderValue(SliderType.sidetone)
+print(sidetone)
+```
+
+Snapshot helper:
+```python
+snap = client.getSnapshot(battery=True, headset=True, sidetone=True)
+print(snap)
+```
+
+
+
+## Requirements
+- Python 3.10+
+- `hidapi` bindings (`pip install hidapi`)
+- Astro A50 base station connected over USB
+- OS must expose the device as a standard HID interface
+
+If your OS doesn't see it as HID, this won't work. No custom drivers
+included here.
+
+## Scope (and what this is *not*)
+
+This project focuses on:
+
+- Reading device state
+- Protocol framing
+- Simple query commands
+
+It's **not**:
+- A replacement for the official Astro software
+- A firmware updater
+- An EQ editor
+
+Write/set commands *might* be added later, but only after making sure
+they're safe. Bricking a headset is not on the roadmap.
+
+## Credits / Prior Work
+Huge credit to the [eh-fifty](https://github.com/tdryer/eh-fifty) project by Tom Dryer.
+
+That project documents and reverse-engineers large parts of the Astro
+A50 USB/HID protocol. I studied their research to understand the framing
+and command structure, then re-implemented what I needed in a smaller
+codebase focused purely on stats and queries.
+
+No source code from [eh-fifty](https://github.com/tdryer/eh-fifty) is included here but their work made
+this possible.
+
+If you want broader device coverage or deeper protocol exploration,
+definitely check that repository out.
+
+
+## License
+
+MIT
+
+
+## Disclaimer
+
+Not affiliated with or endorsed by Astro, Logitech, or the eh-fifty
+project authors.

hyperheadset-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperheadset"
+version = "0.1.0"
+description = "Astro A50 base station HID stats client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Hyper" }]
+dependencies = [
+  "hidapi>=0.14.0"
+]
+
+[project.scripts]
+hyperheadset = "hyperheadset.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

hyperheadset-0.1.0/setup.cfg

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

hyperheadset-0.1.0/src/hyperheadset/__init__.py

@@ -0,0 +1,11 @@
+from .client import AstroA50Client
+from .enums import Command, SliderType
+from .models import BatteryStatus, HeadsetStatus
+
+__all__ = [
+    "AstroA50Client",
+    "Command",
+    "SliderType",
+    "BatteryStatus",
+    "HeadsetStatus",
+]

hyperheadset-0.1.0/src/hyperheadset/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

hyperheadset-0.1.0/src/hyperheadset/cli.py

@@ -0,0 +1,206 @@
+import argparse
+import csv
+import json
+import sys
+import time
+from importlib.metadata import version as packageVersion
+from typing import Any, Dict, Optional, Set
+
+import hid
+
+from .client import AstroA50Client
+
+#*Helpers
+def _stableSignatureForChangeDetection(snapshot: Dict[str, Any]) -> str:
+    comparable = dict(snapshot)
+    comparable.pop("timestamp", None)
+    return json.dumps(comparable, sort_keys=True, separators=(",", ":"))
+
+
+def _printSnapshot(snapshot: Dict[str, Any], asJson: bool, prettyJson: bool, asCsv: bool, csvWriter: Optional[csv.DictWriter]) -> None:
+    if asCsv:
+        row: Dict[str, Any] = {}
+
+        if "timestamp" in snapshot:
+            row["timestamp"] = snapshot["timestamp"]
+
+        battery = snapshot.get("battery")
+        if isinstance(battery, dict):
+            row["batteryChargePercent"] = battery.get("chargePercent")
+            row["batteryIsCharging"] = battery.get("isCharging")
+
+        headset = snapshot.get("headset")
+        if isinstance(headset, dict):
+            row["headsetIsDocked"] = headset.get("isDocked")
+            row["headsetIsOn"] = headset.get("isOn")
+
+        sidetone = snapshot.get("sidetone")
+        if isinstance(sidetone, dict):
+            row["sidetoneActivePercent"] = sidetone.get("activePercent")
+            row["sidetoneSavedPercent"] = sidetone.get("savedPercent")
+
+        if csvWriter is None:
+            raise RuntimeError("csvWriter is None in CSV mode")
+
+        csvWriter.writerow(row)
+        sys.stdout.flush()
+        return
+
+    if asJson:
+        if prettyJson:
+            print(json.dumps(snapshot, indent=2, sort_keys=True))
+        else:
+            print(json.dumps(snapshot, separators=(",", ":"), sort_keys=True))
+        return
+
+    #*Human Readable
+    battery = snapshot.get("battery")
+    if isinstance(battery, dict):
+        print(f"Battery: {battery.get('chargePercent')}% charging={battery.get('isCharging')}")
+
+    headset = snapshot.get("headset")
+    if isinstance(headset, dict):
+        print(f"Headset: docked={headset.get('isDocked')} on={headset.get('isOn')}")
+
+    sidetone = snapshot.get("sidetone")
+    if isinstance(sidetone, dict):
+        print(f"Sidetone: active={sidetone.get('activePercent')}% saved={sidetone.get('savedPercent')}%")
+
+
+def _printDeviceList(vendorId: int) -> int:
+    devices = [d for d in hid.enumerate() if d.get("vendor_id") == vendorId]
+
+    if not devices:
+        print(f"No HID devices found for vendor_id=0x{vendorId:04X}")
+        return 1
+
+    for i, device in enumerate(devices, start=1):
+        print(
+            f"[{i}] "
+            f"vendor=0x{vendorId:04X} "
+            f"product=0x{int(device.get('product_id')):04X} "
+            f"mfg={device.get('manufacturer_string')!r} "
+            f"product={device.get('product_string')!r} "
+            f"path={device.get('path')!r}"
+        )
+
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="hyperheadset", description="Hyper's headset tooling: Astro A50 base station stats via HID")
+
+    #?Meta
+    parser.add_argument("--version", action="store_true")
+    parser.add_argument("--device-list", action="store_true")
+    parser.add_argument("--vendor-id", type=lambda s: int(s, 0), default=0x9886)
+
+    #?Field selection
+    parser.add_argument("--battery", action="store_true")
+    parser.add_argument("--headset", action="store_true")
+    parser.add_argument("--sidetone", action="store_true")
+    parser.add_argument("--fields", type=str, default="")
+
+    #?Output
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--p", action="store_true", help="Pretty JSON")
+    parser.add_argument("--csv", action="store_true")
+    parser.add_argument("--no-timestamp", action="store_true")
+
+    #?Watch
+    parser.add_argument("--watch", action="store_true")
+    parser.add_argument("--changes-only", action="store_true")
+    parser.add_argument("--interval", type=float, default=2.0)
+    parser.add_argument("--count", type=int, default=0)
+
+    args = parser.parse_args()
+
+    #?version
+    if args.version:
+        print(packageVersion("hyperheadset"))
+        return 0
+
+    vendorId = int(args.vendor_id)
+
+    if args.device_list:
+        return _printDeviceList(vendorId)
+
+    if args.interval <= 0:
+        raise SystemExit("--interval must be > 0")
+
+    intervalSeconds = max(args.interval, 0.25)
+
+    allowedFields: Set[str] = {"battery", "headset", "sidetone"}
+
+    if args.fields.strip():
+        requested = {x.strip().lower() for x in args.fields.split(",") if x.strip()}
+        unknown = requested - allowedFields
+        if unknown:
+            raise SystemExit(f"Unknown fields: {', '.join(sorted(unknown))}")
+
+        includeBattery = "battery" in requested
+        includeHeadset = "headset" in requested
+        includeSidetone = "sidetone" in requested
+    else:
+        includeBattery = args.battery
+        includeHeadset = args.headset
+        includeSidetone = args.sidetone
+
+        if not (includeBattery or includeHeadset or includeSidetone):
+            includeBattery = True
+            includeHeadset = True
+
+    asCsv = bool(args.csv)
+    asJson = bool(args.json) and not asCsv
+    prettyJson = bool(args.p)
+    includeTimestamp = not args.no_timestamp
+
+    csvWriter: Optional[csv.DictWriter] = None
+    if asCsv:
+        fieldnames = [
+            "timestamp",
+            "batteryChargePercent",
+            "batteryIsCharging",
+            "headsetIsDocked",
+            "headsetIsOn",
+            "sidetoneActivePercent",
+            "sidetoneSavedPercent"
+        ]
+        csvWriter = csv.DictWriter(sys.stdout, fieldnames=fieldnames)
+        csvWriter.writeheader()
+
+    lastSignature: Optional[str] = None
+
+    with AstroA50Client(vendorId=vendorId) as client:
+
+        def emitOnce() -> bool:
+            nonlocal lastSignature
+
+            snapshot = client.getSnapshot(battery=includeBattery, headset=includeHeadset, sidetone=includeSidetone, includeTimestamp=includeTimestamp)
+
+            if args.watch and args.changes_only:
+                sig = _stableSignatureForChangeDetection(snapshot)
+                if sig == lastSignature:
+                    return False
+                lastSignature = sig
+
+            _printSnapshot(snapshot, asJson, prettyJson, asCsv, csvWriter)
+            return True
+
+        if args.watch:
+            emitted = 0
+            try:
+                while True:
+                    if emitOnce():
+                        emitted += 1
+                        if args.count and emitted >= args.count:
+                            return 0
+                    time.sleep(intervalSeconds)
+            except KeyboardInterrupt:
+                if not asCsv:
+                    print("\nStopped.")
+                return 0
+
+        emitOnce()
+        return 0
+    return 0

hyperheadset-0.1.0/src/hyperheadset/client.py

@@ -0,0 +1,229 @@
+import time
+from typing import Any, Dict, Optional, Sequence
+
+import hid
+
+from .enums import Command, SliderType
+from .models import BatteryStatus, HeadsetStatus
+
+
+class AstroA50Client:
+    """
+    Minimal HID client for Astro A50 base station.
+    """
+
+    def __init__(self, vendorId: int = 0x9886, reportLengths: Sequence[int] = (64, 65), commandDelaySeconds: float = 0.08) -> None:
+        self.vendorId = vendorId
+        self.reportLengths = tuple(int(value) for value in reportLengths)
+        self.commandDelaySeconds = float(commandDelaySeconds)
+        self.lastGoodBatteryStatus: Optional[BatteryStatus] = None
+
+    def __enter__(self) -> "AstroA50Client":
+        return self
+
+    def __exit__(self, excType, exc, tb) -> bool:
+        #TODO not implemented, may do one day
+        return False
+
+    #?HID Helpers
+    def _findDevicePath(self) -> bytes:
+        devices = [device for device in hid.enumerate() if device.get("vendor_id") == self.vendorId]
+        if not devices:
+            raise RuntimeError("Astro A50 HID interface not found (driver should be 'USB Input Device').")
+        return devices[0]["path"]
+
+    def _buildRequestFrame(self, commandId: int, payloadBytes: Optional[Sequence[int]], reportLength: int) -> bytes:
+        
+        frameBytes = [0x02, commandId & 0xFF, 0x00]
+
+        if payloadBytes:
+            frameBytes[2] = len(payloadBytes) & 0xFF
+            frameBytes.extend([(value & 0xFF) for value in payloadBytes])
+
+        if reportLength == 65:
+            paddedBody = frameBytes + [0] * (64 - len(frameBytes))
+            return bytes([0x00]) + bytes(paddedBody)
+
+        paddedBody = frameBytes + [0] * (reportLength - len(frameBytes))
+        return bytes(paddedBody)
+
+    def _normalizeResponseFrame(self, responseFrame: bytes) -> bytes:
+        if (responseFrame and responseFrame[0] == 0x00 and len(responseFrame) > 1 and responseFrame[1] == 0x02):
+            return responseFrame[1:]
+        return responseFrame
+
+    def _extractPayload(self, responseFrame: bytes) -> Optional[bytes]:
+        if len(responseFrame) < 3:
+            return None
+
+        frameStartByte = responseFrame[0]
+        statusCodeByte = responseFrame[1]
+
+        if frameStartByte != 0x02 or statusCodeByte != 0x02:
+            return None
+
+        payloadLength = responseFrame[2]
+        payloadLength = min(payloadLength, max(0, len(responseFrame) - 3))
+        return responseFrame[3 : 3 + payloadLength]
+
+    def _sendCommandOnce(self, devicePath: bytes, commandId: int, payloadBytes: Optional[Sequence[int]]) -> Optional[bytes]:
+        for reportLength in self.reportLengths:
+            deviceHandle = hid.device()
+            try:
+                deviceHandle.open_path(devicePath)
+                deviceHandle.set_nonblocking(0)
+
+                requestFrame = self._buildRequestFrame(commandId, payloadBytes, reportLength)
+
+                try:
+                    deviceHandle.send_feature_report(requestFrame)
+                    time.sleep(0.03)
+                    featureResponse = deviceHandle.get_feature_report(0, reportLength)
+                    if featureResponse:
+                        return self._normalizeResponseFrame(bytes(featureResponse))
+                except OSError:
+                    pass
+
+                try:
+                    deviceHandle.write(requestFrame)
+                    interruptResponse = deviceHandle.read(reportLength, timeout_ms=250)
+                    if interruptResponse:
+                        return self._normalizeResponseFrame(bytes(interruptResponse))
+                except OSError:
+                    pass
+
+            finally:
+                try:
+                    deviceHandle.close()
+                except Exception:
+                    pass
+
+        return None
+
+    def _query(self, commandId: int, payloadBytes: Optional[Sequence[int]] = None, retries: int = 4) -> bytes:
+        devicePath = self._findDevicePath()
+        lastError: Optional[Exception] = None
+
+        for _ in range(int(retries)):
+            try:
+                responseFrame = self._sendCommandOnce(devicePath, int(commandId), payloadBytes)
+                if responseFrame:
+                    payloadFromDevice = self._extractPayload(responseFrame)
+                    if payloadFromDevice is not None:
+                        time.sleep(self.commandDelaySeconds)
+                        return payloadFromDevice
+            except Exception as error:
+                lastError = error
+
+            time.sleep(0.06)
+
+        raise RuntimeError(f"No valid response for cmd 0x{int(commandId):02X}") from lastError
+
+    #*Main Public API
+    def getBatteryStatus(self, retries: int = 6) -> BatteryStatus:
+        """
+        Battery payload is 1 byte:
+          isCharging = bool(byte & 0x80)
+          percent    = byte & 0x7F
+        """
+        for _ in range(int(retries)):
+            payloadBytes = self._query(Command.getBatteryStatus)
+
+            if len(payloadBytes) >= 1:
+                statusByte = payloadBytes[0]
+                batteryStatus = BatteryStatus(isCharging=bool(statusByte & 0x80), chargePercent=int(statusByte & 0x7F))
+
+                if 0 <= batteryStatus.chargePercent <= 100:
+                    self.lastGoodBatteryStatus = batteryStatus
+                    return batteryStatus
+
+            time.sleep(0.05)
+
+        if self.lastGoodBatteryStatus is not None:
+            return self.lastGoodBatteryStatus
+
+        raise RuntimeError("Could not read a sane battery value")
+
+    def getHeadsetStatus(self) -> HeadsetStatus:
+        payloadBytes = self._query(Command.getHeadsetStatus)
+        if len(payloadBytes) < 1:
+            raise RuntimeError(f"Unexpected headset status payload: {payloadBytes!r}")
+
+        statusByte = payloadBytes[0]
+        return HeadsetStatus(isDocked=bool(statusByte & 0x01), isOn=bool(statusByte & 0x02))
+
+    def getSliderValue(self, sliderType: int | SliderType, saved: bool = False) -> int:
+        """
+        Expects payload like:
+          [0x68, sliderType, activeValue, savedValue]
+        """
+        sliderId = int(sliderType) & 0xFF
+        payloadBytes = self._query(Command.getSliderValue, [sliderId])
+
+        if (len(payloadBytes) < 4 or payloadBytes[0] != int(Command.getSliderValue) or payloadBytes[1] != sliderId):
+            raise RuntimeError(f"Unexpected slider payload: {payloadBytes!r}")
+
+        valueIndex = 2 + int(saved)
+        return int(payloadBytes[valueIndex])
+
+    def getActiveEqPreset(self) -> int:
+        payloadBytes = self._query(Command.getActiveEqPreset)
+        if not payloadBytes:
+            raise RuntimeError(f"Unexpected EQ payload: {payloadBytes!r}")
+        return int(payloadBytes[0])
+
+    def getBalance(self) -> int:
+        payloadBytes = self._query(Command.getBalance)
+        if not payloadBytes:
+            raise RuntimeError(f"Unexpected balance payload: {payloadBytes!r}")
+        return int(payloadBytes[0])
+
+    def getDefaultBalance(self, saved: bool = False) -> int:
+        payloadBytes = self._query(Command.getDefaultBalance, [int(saved)])
+        if not payloadBytes:
+            raise RuntimeError(f"Unexpected default balance payload: {payloadBytes!r}")
+        return int(payloadBytes[0])
+
+    def getAlertVolume(self, saved: bool = False) -> int:
+        payloadBytes = self._query(Command.getAlertVolume, [int(saved)])
+        if not payloadBytes:
+            raise RuntimeError(f"Unexpected alert volume payload: {payloadBytes!r}")
+        return int(payloadBytes[0])
+
+    def getMicEq(self, saved: bool = False) -> int:
+        payloadBytes = self._query(Command.getMicEq, [int(saved)])
+        if not payloadBytes:
+            raise RuntimeError(f"Unexpected mic EQ payload: {payloadBytes!r}")
+        return int(payloadBytes[0])
+
+    def getNoiseGateMode(self, saved: bool = False) -> int:
+        """
+        Payload like: [0x6A, activeMode, savedMode]
+        """
+        payloadBytes = self._query(Command.getNoiseGateMode)
+
+        if len(payloadBytes) < 3 or payloadBytes[0] != int(Command.getNoiseGateMode):
+            raise RuntimeError(f"Unexpected noise gate payload: {payloadBytes!r}")
+
+        return int(payloadBytes[1 + int(saved)])
+
+    def getSnapshot(self, battery: bool = True, headset: bool = True, sidetone: bool = False, includeTimestamp: bool = True) -> Dict[str, Any]:
+        snapshot: Dict[str, Any] = {}
+
+        if includeTimestamp:
+            snapshot["timestamp"] = time.time()
+
+        if battery:
+            batteryStatus = self.getBatteryStatus()
+            snapshot["battery"] = {"isCharging": batteryStatus.isCharging, "chargePercent": batteryStatus.chargePercent}
+
+        if headset:
+            headsetStatus = self.getHeadsetStatus()
+            snapshot["headset"] = {"isDocked": headsetStatus.isDocked, "isOn": headsetStatus.isOn}
+
+        if sidetone:
+            sidetoneActive = self.getSliderValue(SliderType.sidetone, saved=False)
+            sidetoneSaved = self.getSliderValue(SliderType.sidetone, saved=True)
+            snapshot["sidetone"] = {"activePercent": int(sidetoneActive), "savedPercent": int(sidetoneSaved)}
+
+        return snapshot

hyperheadset-0.1.0/src/hyperheadset/enums.py

@@ -0,0 +1,22 @@
+from enum import IntEnum
+
+
+class Command(IntEnum):
+    getHeadsetStatus = 0x54
+    getSliderValue = 0x68
+    getNoiseGateMode = 0x6A
+    getActiveEqPreset = 0x6C
+    getBalance = 0x72
+    getDefaultBalance = 0x77
+    getAlertVolume = 0x7A
+    getMicEq = 0x7B
+    getBatteryStatus = 0x7C
+
+
+class SliderType(IntEnum):
+    streamMic = 0x00
+    streamChat = 0x01
+    streamGame = 0x02
+    streamAux = 0x03
+    mic = 0x04
+    sidetone = 0x05

hyperheadset-0.1.0/src/hyperheadset/models.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BatteryStatus:
+    isCharging: bool
+    chargePercent: int
+
+
+@dataclass(frozen=True)
+class HeadsetStatus:
+    isDocked: bool
+    isOn: bool

hyperheadset-0.1.0/src/hyperheadset.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: hyperheadset
+Version: 0.1.0
+Summary: Astro A50 base station HID stats client
+Author: Hyper
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hidapi>=0.14.0
+
+# Hyperheadset
+
+A small Python CLI and library for reading live status data from the Astro
+A50 base station over HID.
+
+This started as a side project because I wanted to see battery %, dock
+state, and sidetone levels without running the official Astro software
+in the background. That turned into reverse-engineering the HID
+protocol... which turned into this.
+
+It talks directly to the base station, parses the response frames, and
+exposes the useful bits in a clean way.
+
+---
+
+## What it can do
+Right now it focuses on reading states.
+
+- Read battery percentage + charging state
+- Detect whether the headset is docked / powered
+- Read sidetone slider values (active + saved)
+- Output as JSON (compact or pretty)
+- CSV logging
+- Watch mode (with change detection)
+- Filter specific fields (`--fields`)
+- List matching HID devices
+- Usable as both a CLI tool and a Python module
+
+## Install
+
+Not on PyPI (yet).
+
+Local install:
+
+```bash
+pip install .
+```
+
+Editable dev install:
+
+```bash
+pip install -e .
+```
+
+## CLI Usage
+
+Default snapshot:
+
+```bash
+hyperheadset
+```
+
+Some common flags:
+
+- Battery only → `--battery`
+- JSON output → `--json`
+- Pretty JSON → `--json --p`
+- Watch mode → `--watch`
+- Only show changes (watch mode) → `--changes-only`
+- List matching HID devices → `--device-list`
+
+### Examples
+
+Watch only sidetone, and only print when it changes:
+``` bash
+hyperheadset --fields sidetone --watch --changes-only
+```
+
+Log everything to CSV every 2 seconds:
+``` bash
+hyperheadset --csv --watch --interval 2 > log.csv
+```
+
+Pretty JSON snapshot without timestamp:
+``` bash
+hyperheadset --json --p --no-timestamp
+```
+
+## Python Usage
+You can also use it directly in code:
+
+```python
+from hyperheadset import AstroA50Client, SliderType
+
+client = AstroA50Client()
+
+battery = client.getBatteryStatus()
+print(battery.chargePercent, battery.isCharging)
+
+sidetone = client.getSliderValue(SliderType.sidetone)
+print(sidetone)
+```
+
+Snapshot helper:
+```python
+snap = client.getSnapshot(battery=True, headset=True, sidetone=True)
+print(snap)
+```
+
+
+
+## Requirements
+- Python 3.10+
+- `hidapi` bindings (`pip install hidapi`)
+- Astro A50 base station connected over USB
+- OS must expose the device as a standard HID interface
+
+If your OS doesn't see it as HID, this won't work. No custom drivers
+included here.
+
+## Scope (and what this is *not*)
+
+This project focuses on:
+
+- Reading device state
+- Protocol framing
+- Simple query commands
+
+It's **not**:
+- A replacement for the official Astro software
+- A firmware updater
+- An EQ editor
+
+Write/set commands *might* be added later, but only after making sure
+they're safe. Bricking a headset is not on the roadmap.
+
+## Credits / Prior Work
+Huge credit to the [eh-fifty](https://github.com/tdryer/eh-fifty) project by Tom Dryer.
+
+That project documents and reverse-engineers large parts of the Astro
+A50 USB/HID protocol. I studied their research to understand the framing
+and command structure, then re-implemented what I needed in a smaller
+codebase focused purely on stats and queries.
+
+No source code from [eh-fifty](https://github.com/tdryer/eh-fifty) is included here but their work made
+this possible.
+
+If you want broader device coverage or deeper protocol exploration,
+definitely check that repository out.
+
+
+## License
+
+MIT
+
+
+## Disclaimer
+
+Not affiliated with or endorsed by Astro, Logitech, or the eh-fifty
+project authors.

hyperheadset-0.1.0/src/hyperheadset.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/hyperheadset/__init__.py
+src/hyperheadset/__main__.py
+src/hyperheadset/cli.py
+src/hyperheadset/client.py
+src/hyperheadset/enums.py
+src/hyperheadset/models.py
+src/hyperheadset.egg-info/PKG-INFO
+src/hyperheadset.egg-info/SOURCES.txt
+src/hyperheadset.egg-info/dependency_links.txt
+src/hyperheadset.egg-info/entry_points.txt
+src/hyperheadset.egg-info/requires.txt
+src/hyperheadset.egg-info/top_level.txt

hyperheadset-0.1.0/src/hyperheadset.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyperheadset-0.1.0/src/hyperheadset.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hyperheadset = hyperheadset.cli:main

hyperheadset-0.1.0/src/hyperheadset.egg-info/requires.txt

@@ -0,0 +1 @@
+hidapi>=0.14.0

hyperheadset-0.1.0/src/hyperheadset.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyperheadset