Add Nothing X share codec and device read commands

- share.py: decode/encode Nothing X "Advanced equaliser profile" QR
  payloads (gzip+base64, 8 bands of gain/frequency/Q + name). Verified
  with exact binary round-trip against two real QR samples.
- protocol.py: REQUEST_COMMANDS and query_raw() to read device settings.
- CLI --read {anc,eq,custom-eq,advanced-eq,battery,firmware,serial} to
  dump the raw device response, so we can learn the on-wire advanced-EQ
  format needed to apply imported profiles.
- Tests for the share codec.

https://claude.ai/code/session_014KrpftzUgVFGFXVUU3DUTT

Author: claude

src/nothing_ear/app.py

@@ -47,6 +47,11 @@ def _build_parser() -> argparse.ArgumentParser:
         "--raw",
         help="Send a raw hex control frame and exit (for protocol testing).",
     )
+    parser.add_argument(
+        "--read",
+        choices=["anc", "eq", "custom-eq", "advanced-eq", "battery", "firmware", "serial"],
+        help="Read a setting from the device and print the raw response (no GUI).",
+    )
     parser.add_argument(
         "--address",
         help="Device MAC address (auto-detected if omitted).",
@@ -101,6 +106,10 @@ def main() -> int:
         from .cli import cmd_raw
 
         return cmd_raw(args.address, args.raw, args.channel)
+    if args.read is not None:
+        from .cli import cmd_read
+
+        return cmd_read(args.address, args.read, args.channel)
 
     return _run_gui(args.mock)
 

src/nothing_ear/bluetooth/protocol.py

@@ -30,6 +30,16 @@
 CMD_ANC_STATUS = 0xC01E
 CMD_EQ = 0xF010
 
+REQUEST_COMMANDS = {
+    "anc": 0xC01E,
+    "eq": 0xC01F,
+    "custom-eq": 0xC044,
+    "advanced-eq": 0xC04C,
+    "battery": 0xC007,
+    "firmware": 0xC042,
+    "serial": 0xC006,
+}
+
 
 class ANCMode(Enum):
     HIGH = "high"
@@ -174,3 +184,13 @@ def query_anc(self) -> ANCMode | None:
         if len(resp) > ANC_RESPONSE_MODE_INDEX:
             return _ANC_BY_VALUE.get(resp[ANC_RESPONSE_MODE_INDEX])
         return None
+
+    def query_raw(self, command: int, payload: bytes = b"") -> bytes:
+        if self._sock is None:
+            raise RuntimeError("Not connected. Call connect() first.")
+        self._sock.sendall(build_frame(command, payload, self._next_fsn()))
+        self._sock.settimeout(2.0)
+        try:
+            return self._sock.recv(512)
+        except TimeoutError:
+            return b""

src/nothing_ear/bluetooth/share.py

@@ -0,0 +1,66 @@
+"""Nothing X "Advanced equaliser profile" share codec.
+
+A shared profile (the content of a Nothing X EQ QR code) is gzip + base64 of:
+
+    0x00 | band_bytes_len(1) | bands | 0x01 | name_len(1) | name (ASCII)
+
+Each band is three little-endian float32 values: gain (dB), frequency (Hz), Q.
+This lets us import and export Nothing-X-compatible profiles.
+
+Decoded and verified against real Nothing X QR samples.
+"""
+
+from __future__ import annotations
+
+import base64
+import gzip
+import struct
+from dataclasses import dataclass
+
+_BAND_SIZE = 12
+
+
+@dataclass(frozen=True)
+class EqBand:
+    gain: float
+    frequency: float
+    q: float
+
+
+@dataclass(frozen=True)
+class AdvancedEqProfile:
+    name: str
+    bands: list[EqBand]
+
+
+def decode_binary(raw: bytes) -> AdvancedEqProfile:
+    band_len = raw[1]
+    count = band_len // _BAND_SIZE
+    bands = []
+    offset = 2
+    for _ in range(count):
+        gain, frequency, q = struct.unpack_from("<3f", raw, offset)
+        bands.append(EqBand(gain, frequency, q))
+        offset += _BAND_SIZE
+    name_len = raw[offset + 1]
+    name = raw[offset + 2 : offset + 2 + name_len].decode("ascii", errors="replace")
+    return AdvancedEqProfile(name=name, bands=bands)
+
+
+def encode_binary(profile: AdvancedEqProfile) -> bytes:
+    body = bytes([0x00, len(profile.bands) * _BAND_SIZE])
+    for band in profile.bands:
+        body += struct.pack("<3f", band.gain, band.frequency, band.q)
+    name = profile.name.encode("ascii", errors="replace")
+    body += bytes([0x01, len(name)]) + name
+    return body
+
+
+def decode_profile(code: str) -> AdvancedEqProfile:
+    raw = gzip.decompress(base64.b64decode(code))
+    return decode_binary(raw)
+
+
+def encode_profile(profile: AdvancedEqProfile) -> str:
+    raw = encode_binary(profile)
+    return base64.b64encode(gzip.compress(raw)).decode("ascii")

src/nothing_ear/cli.py

@@ -108,6 +108,28 @@ def cmd_eq(address: str | None, preset: str, channel: int) -> int:
     return 0
 
 
+def cmd_read(address: str | None, name: str, channel: int) -> int:
+    addr = _resolve_address(address)
+    if addr is None:
+        return 1
+
+    from .bluetooth.protocol import REQUEST_COMMANDS, NothingController
+
+    command = REQUEST_COMMANDS[name]
+    try:
+        with NothingController(addr, channel=channel) as ctrl:
+            resp = ctrl.query_raw(command)
+    except OSError as exc:
+        print(f"RFCOMM connection on channel {channel} failed: {exc}")
+        return 1
+    if not resp:
+        print(f"{name}: no response (command 0x{command:04x})")
+        return 1
+    print(f"{name} (request 0x{command:04x}) response:")
+    print(resp.hex())
+    return 0
+
+
 def cmd_raw(address: str | None, hex_frame: str, channel: int) -> int:
     addr = _resolve_address(address)
     if addr is None:

tests/test_share.py

@@ -0,0 +1,47 @@
+"""Tests for the Nothing X share codec, verified against real QR samples."""
+
+import base64
+import gzip
+
+from nothing_ear.bluetooth.share import (
+    decode_binary,
+    decode_profile,
+    encode_binary,
+    encode_profile,
+)
+
+D_TUNE = (
+    "H4sIAAAAAAAAE2NIYGBgsGdgEHBKS3sGpBn2MzCccDI2/mwPEe93TktjcwCzG3RcZs28CRJ"
+    "nYCiwdmVg2AAUb9jPoFDrOmtmpwNYb8NuV7g5NYVuZ8/42DGyueiWlOalAgBsFv0DagAAAA=="
+)
+BALANCED_BASS = (
+    "H4sIAAAAAAAAAGNIYGA44MDA8MHx7JkztlC2U8McZ3sGBgcgu8r5zh59IPsAEP9yTktbBhF"
+    "vWO4SmSkCZC9wYHDwc82zrrcH60145TprpiSQDQQJWW72m2faM/I6JeYk5iWnpig4JRYXAw"
+    "ClSEOdcQAAAA=="
+)
+
+
+def test_decode_real_profiles():
+    d = decode_profile(D_TUNE)
+    assert d.name == "D-tune"
+    assert len(d.bands) == 8
+    assert round(d.bands[0].gain, 2) == 0.5
+    assert round(d.bands[0].frequency) == 36
+    assert round(d.bands[0].q, 1) == 1.8
+
+    b = decode_profile(BALANCED_BASS)
+    assert b.name == "Balanced Bass"
+    assert round(b.bands[0].gain) == 6
+    assert round(b.bands[0].frequency) == 30
+
+
+def test_binary_roundtrip_is_exact():
+    for code in (D_TUNE, BALANCED_BASS):
+        raw = gzip.decompress(base64.b64decode(code))
+        assert encode_binary(decode_binary(raw)) == raw
+
+
+def test_code_roundtrip():
+    for code in (D_TUNE, BALANCED_BASS):
+        profile = decode_profile(code)
+        assert decode_profile(encode_profile(profile)) == profile