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:
pip install .
Editable dev install:
pip install -e .
CLI Usage
Default snapshot:
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:
hyperheadset --fields sidetone --watch --changes-only
Log everything to CSV every 2 seconds:
hyperheadset --csv --watch --interval 2 > log.csv
Pretty JSON snapshot without timestamp:
hyperheadset --json --p --no-timestamp
Python Usage
You can also use it directly in code:
from hyperheadset import AstroA50Client, SliderType
client = AstroA50Client()
battery = client.getBatteryStatus()
print(battery.chargePercent, battery.isCharging)
sidetone = client.getSliderValue(SliderType.sidetone)
print(sidetone)
Snapshot helper:
snap = client.getSnapshot(battery=True, headset=True, sidetone=True)
print(snap)
Requirements
- Python 3.10+
hidapibindings (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 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 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.
Metadata
Release files for hyperheadset 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hyperheadset-0.1.1.tar.gz | 9.3 kB | With provenance | Details for hyperheadset-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hyperheadset-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for hyperheadset-0.1.1-py3-none-any.whl |
Total release size: 18.2 kB
Release files / hyperheadset-0.1.1.tar.gz
| Download URL | hyperheadset-0.1.1.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e6725776652126e20da576f6f95eadd8c03edf8cbaa51b2baa4b687327d9d371
|
|
BLAKE2b-256 checksum How to use checksums |
d03e2a86cf212a9647c676573317f4c6ccaa13f3b3371a3e643909af0e6eedba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 13, 2026.
Transparency logRelease files / hyperheadset-0.1.1-py3-none-any.whl
| Download URL | hyperheadset-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c07095b9e739236c5cbf70c94d589e87f137c6fc08719030476c29ff0aa3c00
|
|
BLAKE2b-256 checksum How to use checksums |
29c8ca33e861e5390547d38292ddcdabc245f1a609426beef54143076aba967c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 13, 2026.
Transparency logSecurity for hyperheadset 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hyperheadset-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.