Skip to main content

Hyperheadset

PyPI Python License

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+
  • 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 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)

Source distribution for hyperheadset 0.1.1
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)

Table of built distributions (wheels) for hyperheadset 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page