something-x-dev 1.3.0.dev6__tar.gz → 1.5.0.dev8__tar.gz

something_x_dev-1.5.0.dev8/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: something-x-dev
+Version: 1.5.0.dev8
+Summary: Something X device manager for Omarchy / Linux
+Author: Raphael
+License: MIT
+Keywords: nothing,bluetooth,gtk4,linux,omarchy,ear
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyGObject>=3.42
+Requires-Dist: dbus-python>=1.3
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Something X
+
+**A Linux-native companion app for Nothing and CMF Bluetooth devices.**  
+Built for [Omarchy](https://omarchy.org) · GTK4 · Pure black · JetBrains Mono · Nothing Red
+
+[![PyPI](https://img.shields.io/pypi/v/something-x?color=red)](https://pypi.org/project/something-x/)
+[![AUR](https://img.shields.io/aur/version/something-x?color=red)](https://aur.archlinux.org/packages/something-x)
+[![License: MIT](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Linux-lightgrey)](https://github.com/SoaOaoS/something-x)
+
+</div>
+
+---
+
+## Features
+
+| | Feature | Details |
+|---|---|---|
+| 🎧 | **Earbud visual** | Cairo-rendered glowing battery rings for L / R / Case, live updates |
+| 🔇 | **ANC control** | Off · Noise Cancellation · Transparency over real RFCOMM protocol |
+| 🎵 | **EQ presets** | Balanced · More Bass · More Treble · Voice |
+| 🔊 | **Volume slider** | Direct PulseAudio / PipeWire A2DP sink control via `pactl` |
+| 💾 | **Per-device profiles** | ANC + EQ saved per device address, restored automatically on reconnect |
+| 🔋 | **Battery notifications** | Desktop alerts at 20 %, 15 %, 10 %, and 5 % per earbud and case |
+| 🔗 | **Auto-connect RFCOMM** | Connects to the device protocol as soon as BlueZ reports it paired |
+| 🏃 | **Background mode** | Closing the window keeps the app running; relaunch to reopen |
+| 💻 | **CLI** | Control your earbuds from the terminal without opening the GUI |
+| 📱 | **Device discovery** | BlueZ D-Bus scan with Nothing / CMF devices highlighted |
+| ℹ️ | **Device info** | Firmware version and serial number read over RFCOMM |
+
+---
+
+## Device support
+
+| Device | Battery | ANC | EQ | Volume | Firmware |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Nothing Ear (1) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (2) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (a) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (stick) | ✅ | — | ✅ | ✅ | ✅ |
+| CMF Buds / Buds Pro | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Phone (1/2) | ✅ | — | — | — | — |
+| Other Bluetooth devices | ✅* | — | — | ✅ | — |
+
+<sub>* via BlueZ `Battery1` interface · RFCOMM features require an active connection</sub>
+
+---
+
+## Installation
+
+### Arch / Omarchy (recommended)
+
+Install system dependencies first:
+
+```bash
+sudo pacman -S python-gobject python-dbus python-cairo gtk4 libadwaita
+```
+
+Then install from **AUR**:
+
+```bash
+yay -S something-x
+# or: paru -S something-x
+```
+
+Or via **pip**:
+
+```bash
+pip install something-x
+```
+
+### Other distros
+
+<details>
+<summary>Ubuntu 24.04+</summary>
+
+```bash
+sudo apt install python3-gi python3-dbus python3-cairo gir1.2-gtk-4.0 gir1.2-adw-1
+pip install something-x
+```
+
+</details>
+
+<details>
+<summary>Fedora 39+</summary>
+
+```bash
+sudo dnf install python3-gobject python3-dbus python3-cairo gtk4 libadwaita
+pip install something-x
+```
+
+</details>
+
+<details>
+<summary>NixOS</summary>
+
+```bash
+nix run github:SoaOaoS/something-x
+```
+
+A `flake.nix` is included for reproducible builds.
+
+</details>
+
+### Run from source
+
+```bash
+git clone https://github.com/SoaOaoS/something-x
+cd something-x
+pip install -e .
+something-x
+```
+
+---
+
+## Usage
+
+### GUI
+
+```bash
+something-x
+```
+
+1. **Splash** — animated intro, main window appears after ~2 s
+2. **Home** — lists all paired Bluetooth devices; Nothing / CMF devices get a `NOTHING` badge
+3. **Scan** — tap `SCAN FOR DEVICES` to run a 30 s BlueZ discovery
+4. **Device page** — tap a card to open controls:
+   - Battery rings (L / R / Case) update in real time
+   - ANC and EQ apply immediately over RFCOMM and are saved to your profile
+   - Volume slider drives the A2DP sink via `pactl`
+   - Firmware version and serial number appear after RFCOMM connects
+5. **Close** — hides to background; run `something-x` again to reopen
+
+### CLI
+
+Control your earbuds without opening the GUI:
+
+```bash
+# Battery levels
+something-x --battery
+
+# ANC mode
+something-x --anc off
+something-x --anc on
+something-x --anc transparency
+
+# EQ preset
+something-x --eq balanced
+something-x --eq bass
+something-x --eq treble
+something-x --eq voice
+
+# Combine
+something-x --anc on --eq bass
+
+# Target a specific device by address
+something-x --device AA:BB:CC:DD:EE:FF --battery
+```
+
+---
+
+## Development releases
+
+The `develop` branch publishes pre-release builds to PyPI automatically as `something-x-dev`:
+
+```bash
+pip install something-x-dev
+something-x-dev
+```
+
+Dev builds use version numbers like `1.3.0.dev42`. Not for production use.
+
+---
+
+## Releases & versioning
+
+Pushing to `main` triggers automatic versioning, a GitHub Release, a PyPI publish, and an AUR update — all from Conventional Commits:
+
+| Commit prefix | Version bump |
+|---|---|
+| `feat!:` / `BREAKING CHANGE:` | Major `x.0.0` |
+| `feat:` | Minor `1.x.0` |
+| `fix:` / `perf:` / `refactor:` | Patch `1.0.x` |
+| `docs:` / `chore:` / `style:` / `ci:` / `test:` | No release |
+
+---
+
+## Architecture
+
+```
+nothing_app/
+├── application.py   Adw.Application — lifecycle, CSS, CLI arg handling, background mode
+├── window.py        AdwNavigationView — home ↔ device routing, RFCOMM auto-connect manager
+├── bluetooth.py     BlueZ D-Bus manager — device discovery, connect/disconnect signals
+├── protocol.py      Nothing Ear 0x55 RFCOMM protocol (reverse-engineered from APK)
+├── profiles.py      Per-device ANC/EQ persistence (~/.config/something-x/profiles.json)
+├── splash.py        Animated splash screen (Cairo, typewriter, ripple rings)
+├── data/
+│   └── style.css    Glass-morphism CSS theme
+└── pages/
+    ├── home.py      Device list + scan button
+    └── device.py    ANC / EQ / volume / settings + Cairo earbud visual
+```
+
+### Protocol
+
+Frame format: `[SOF=0x55][ctrl:2 LE][cmd:2 LE][len:2 LE][FSN:1][payload][CRC16:2 LE]`
+
+All outgoing frames use `ctrl=0x0160` with CRC16-ARC. The device silently drops SET commands if any frame in the session was sent without CRC.
+
+Enable raw frame logging:
+
+```bash
+SOMETHING_X_DEBUG=1 something-x
+```
+
+---
+
+## Contributing
+
+The RFCOMM protocol in [`nothing_app/protocol.py`](nothing_app/protocol.py) is reverse-engineered from the official Android APK. If your device uses different command IDs, channels, or ANC values, patches are very welcome — please include the raw RFCOMM dump (`SOMETHING_X_DEBUG=1`) in your issue or PR.
+
+---
+
+## License
+
+[MIT](LICENSE)

something_x_dev-1.5.0.dev8/README.md

@@ -0,0 +1,229 @@
+<div align="center">
+
+# Something X
+
+**A Linux-native companion app for Nothing and CMF Bluetooth devices.**  
+Built for [Omarchy](https://omarchy.org) · GTK4 · Pure black · JetBrains Mono · Nothing Red
+
+[![PyPI](https://img.shields.io/pypi/v/something-x?color=red)](https://pypi.org/project/something-x/)
+[![AUR](https://img.shields.io/aur/version/something-x?color=red)](https://aur.archlinux.org/packages/something-x)
+[![License: MIT](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Linux-lightgrey)](https://github.com/SoaOaoS/something-x)
+
+</div>
+
+---
+
+## Features
+
+| | Feature | Details |
+|---|---|---|
+| 🎧 | **Earbud visual** | Cairo-rendered glowing battery rings for L / R / Case, live updates |
+| 🔇 | **ANC control** | Off · Noise Cancellation · Transparency over real RFCOMM protocol |
+| 🎵 | **EQ presets** | Balanced · More Bass · More Treble · Voice |
+| 🔊 | **Volume slider** | Direct PulseAudio / PipeWire A2DP sink control via `pactl` |
+| 💾 | **Per-device profiles** | ANC + EQ saved per device address, restored automatically on reconnect |
+| 🔋 | **Battery notifications** | Desktop alerts at 20 %, 15 %, 10 %, and 5 % per earbud and case |
+| 🔗 | **Auto-connect RFCOMM** | Connects to the device protocol as soon as BlueZ reports it paired |
+| 🏃 | **Background mode** | Closing the window keeps the app running; relaunch to reopen |
+| 💻 | **CLI** | Control your earbuds from the terminal without opening the GUI |
+| 📱 | **Device discovery** | BlueZ D-Bus scan with Nothing / CMF devices highlighted |
+| ℹ️ | **Device info** | Firmware version and serial number read over RFCOMM |
+
+---
+
+## Device support
+
+| Device | Battery | ANC | EQ | Volume | Firmware |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Nothing Ear (1) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (2) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (a) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Ear (stick) | ✅ | — | ✅ | ✅ | ✅ |
+| CMF Buds / Buds Pro | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Nothing Phone (1/2) | ✅ | — | — | — | — |
+| Other Bluetooth devices | ✅* | — | — | ✅ | — |
+
+<sub>* via BlueZ `Battery1` interface · RFCOMM features require an active connection</sub>
+
+---
+
+## Installation
+
+### Arch / Omarchy (recommended)
+
+Install system dependencies first:
+
+```bash
+sudo pacman -S python-gobject python-dbus python-cairo gtk4 libadwaita
+```
+
+Then install from **AUR**:
+
+```bash
+yay -S something-x
+# or: paru -S something-x
+```
+
+Or via **pip**:
+
+```bash
+pip install something-x
+```
+
+### Other distros
+
+<details>
+<summary>Ubuntu 24.04+</summary>
+
+```bash
+sudo apt install python3-gi python3-dbus python3-cairo gir1.2-gtk-4.0 gir1.2-adw-1
+pip install something-x
+```
+
+</details>
+
+<details>
+<summary>Fedora 39+</summary>
+
+```bash
+sudo dnf install python3-gobject python3-dbus python3-cairo gtk4 libadwaita
+pip install something-x
+```
+
+</details>
+
+<details>
+<summary>NixOS</summary>
+
+```bash
+nix run github:SoaOaoS/something-x
+```
+
+A `flake.nix` is included for reproducible builds.
+
+</details>
+
+### Run from source
+
+```bash
+git clone https://github.com/SoaOaoS/something-x
+cd something-x
+pip install -e .
+something-x
+```
+
+---
+
+## Usage
+
+### GUI
+
+```bash
+something-x
+```
+
+1. **Splash** — animated intro, main window appears after ~2 s
+2. **Home** — lists all paired Bluetooth devices; Nothing / CMF devices get a `NOTHING` badge
+3. **Scan** — tap `SCAN FOR DEVICES` to run a 30 s BlueZ discovery
+4. **Device page** — tap a card to open controls:
+   - Battery rings (L / R / Case) update in real time
+   - ANC and EQ apply immediately over RFCOMM and are saved to your profile
+   - Volume slider drives the A2DP sink via `pactl`
+   - Firmware version and serial number appear after RFCOMM connects
+5. **Close** — hides to background; run `something-x` again to reopen
+
+### CLI
+
+Control your earbuds without opening the GUI:
+
+```bash
+# Battery levels
+something-x --battery
+
+# ANC mode
+something-x --anc off
+something-x --anc on
+something-x --anc transparency
+
+# EQ preset
+something-x --eq balanced
+something-x --eq bass
+something-x --eq treble
+something-x --eq voice
+
+# Combine
+something-x --anc on --eq bass
+
+# Target a specific device by address
+something-x --device AA:BB:CC:DD:EE:FF --battery
+```
+
+---
+
+## Development releases
+
+The `develop` branch publishes pre-release builds to PyPI automatically as `something-x-dev`:
+
+```bash
+pip install something-x-dev
+something-x-dev
+```
+
+Dev builds use version numbers like `1.3.0.dev42`. Not for production use.
+
+---
+
+## Releases & versioning
+
+Pushing to `main` triggers automatic versioning, a GitHub Release, a PyPI publish, and an AUR update — all from Conventional Commits:
+
+| Commit prefix | Version bump |
+|---|---|
+| `feat!:` / `BREAKING CHANGE:` | Major `x.0.0` |
+| `feat:` | Minor `1.x.0` |
+| `fix:` / `perf:` / `refactor:` | Patch `1.0.x` |
+| `docs:` / `chore:` / `style:` / `ci:` / `test:` | No release |
+
+---
+
+## Architecture
+
+```
+nothing_app/
+├── application.py   Adw.Application — lifecycle, CSS, CLI arg handling, background mode
+├── window.py        AdwNavigationView — home ↔ device routing, RFCOMM auto-connect manager
+├── bluetooth.py     BlueZ D-Bus manager — device discovery, connect/disconnect signals
+├── protocol.py      Nothing Ear 0x55 RFCOMM protocol (reverse-engineered from APK)
+├── profiles.py      Per-device ANC/EQ persistence (~/.config/something-x/profiles.json)
+├── splash.py        Animated splash screen (Cairo, typewriter, ripple rings)
+├── data/
+│   └── style.css    Glass-morphism CSS theme
+└── pages/
+    ├── home.py      Device list + scan button
+    └── device.py    ANC / EQ / volume / settings + Cairo earbud visual
+```
+
+### Protocol
+
+Frame format: `[SOF=0x55][ctrl:2 LE][cmd:2 LE][len:2 LE][FSN:1][payload][CRC16:2 LE]`
+
+All outgoing frames use `ctrl=0x0160` with CRC16-ARC. The device silently drops SET commands if any frame in the session was sent without CRC.
+
+Enable raw frame logging:
+
+```bash
+SOMETHING_X_DEBUG=1 something-x
+```
+
+---
+
+## Contributing
+
+The RFCOMM protocol in [`nothing_app/protocol.py`](nothing_app/protocol.py) is reverse-engineered from the official Android APK. If your device uses different command IDs, channels, or ANC values, patches are very welcome — please include the raw RFCOMM dump (`SOMETHING_X_DEBUG=1`) in your issue or PR.
+
+---
+
+## License
+
+[MIT](LICENSE)

{something_x_dev-1.3.0.dev6 → something_x_dev-1.5.0.dev8}/nothing_app/pages/device.py

@@ -93,19 +93,24 @@ class EarbudVisual(Gtk.DrawingArea):
         self._left = -1
         self._right = -1
         self._case = -1
+        self._left_wearing = False
+        self._right_wearing = False
 
-    def update(self, left: int, right: int, case: int):
+    def update(
+        self, left: int, right: int, case: int, left_wearing: bool = False, right_wearing: bool = False
+    ):
         self._left, self._right, self._case = left, right, case
+        self._left_wearing, self._right_wearing = left_wearing, right_wearing
         self.queue_draw()
 
     def _draw(self, _area, cr, width, height):
         cx = width / 2
         cy = height / 2 - 8
-        self._draw_bud(cr, cx - 92, cy, self._left, "L")
-        self._draw_bud(cr, cx + 92, cy, self._right, "R")
+        self._draw_bud(cr, cx - 92, cy, self._left, "L", self._left_wearing)
+        self._draw_bud(cr, cx + 92, cy, self._right, "R", self._right_wearing)
         self._draw_case(cr, cx, cy + 54, self._case)
 
-    def _draw_bud(self, cr, cx, cy, pct, label):
+    def _draw_bud(self, cr, cx, cy, pct, label, wearing: bool = False):
         R = 42
         r = 29
         bc = _battery_color(pct) if pct >= 0 else (0.18, 0.18, 0.18)
@@ -166,12 +171,27 @@ class EarbudVisual(Gtk.DrawingArea):
         cr.move_to(cx - te.width / 2 - te.x_bearing, cy - te.height / 2 - te.y_bearing)
         cr.show_text(text)
 
+        # in-ear indicator dot (always rendered; glows red when wearing)
+        dot_y = cy + R + 8
+        if wearing:
+            rg = cairo.RadialGradient(cx, dot_y, 0, cx, dot_y, 9)
+            rg.add_color_stop_rgba(0, 0.87, 0.18, 0.18, 0.30)
+            rg.add_color_stop_rgba(1, 0.87, 0.18, 0.18, 0.0)
+            cr.set_source(rg)
+            cr.arc(cx, dot_y, 9, 0, 2 * math.pi)
+            cr.fill()
+            cr.set_source_rgba(0.87, 0.18, 0.18, 0.9)
+        else:
+            cr.set_source_rgba(1.0, 1.0, 1.0, 0.07)
+        cr.arc(cx, dot_y, 3, 0, 2 * math.pi)
+        cr.fill()
+
         # L / R label below
         cr.set_source_rgba(1.0, 1.0, 1.0, 0.20)
         cr.select_font_face(_MONO, cairo.FontSlant.NORMAL, cairo.FontWeight.BOLD)
         cr.set_font_size(9)
         te = cr.text_extents(label)
-        cr.move_to(cx - te.width / 2 - te.x_bearing, cy + R + 17)
+        cr.move_to(cx - te.width / 2 - te.x_bearing, cy + R + 20)
         cr.show_text(label)
 
     def _draw_case(self, cr, cx, cy, pct):
@@ -508,7 +528,13 @@ class DevicePage(Gtk.Box):
 
     def _on_state_changed(self, dev: NothingDevice):
         state = dev.state
-        self._visual.update(state.left_battery, state.right_battery, state.case_battery)
+        self._visual.update(
+            state.left_battery,
+            state.right_battery,
+            state.case_battery,
+            state.left_wearing,
+            state.right_wearing,
+        )
         self._sync_anc_ui(state.anc_mode)
         self._sync_eq_ui(state.eq_preset)
         self._updating_ui = True

{something_x_dev-1.3.0.dev6 → something_x_dev-1.5.0.dev8}/nothing_app/protocol.py

@@ -417,6 +417,8 @@ class NothingDevice(GObject.Object):
             GLib.timeout_add(3000, self._activation_fallback)
         elif cmd_id == _CMD_SET_ACTIVATED:
             _log(f"[RX INFO] activation ACK payload={payload.hex()}")
+            if not self._activated:
+                GLib.timeout_add(2000, self._poll_earphone_status)
             self._activated = True
             from . import profiles
 
@@ -433,8 +435,15 @@ class NothingDevice(GObject.Object):
             changed = self._parse_battery(payload)
         elif cmd_id in (_CMD_NOISE_RED, _EVT_NOISE_RED):
             changed = self._parse_anc(payload)
-        elif cmd_id in (_CMD_EARPHONE, _EVT_STATUS):
+        elif cmd_id == _CMD_EARPHONE:
             changed = self._parse_earphone_status(payload)
+        elif cmd_id == _EVT_STATUS:
+            # The pushed event only carries accurate data for the bud that
+            # changed; the other entries are stale placeholders. Use it purely
+            # as a trigger and re-query for a fresh full snapshot.
+            if _DEBUG:
+                _log(f"[protocol] EVT_STATUS {payload.hex()} → re-query GET_EARPHONE")
+            self._x55_send(_CMD_EARPHONE)
         elif cmd_id == _CMD_HOST_VERSION:
             ver = payload.decode(errors="replace").strip("\x00").strip()
             if ver and ver != self.state.firmware_version:
@@ -512,26 +521,29 @@ class NothingDevice(GObject.Object):
         return changed
 
     def _parse_earphone_status(self, payload: bytes) -> bool:
-        # payload: [count:1][type:1][val:1]...
-        # EarphoneStatus.java: bit2=inEar, bit7=isConnect, bit0=inCase/caseOpen
-        # type: 2=left, 3=right, 4=case
+        # payload: [count:1][type:1][val:1]...  (only GET responses reach here;
+        # they are a fresh full snapshot, unlike the EVT push frames)
+        # EarphoneStatus.java: bit0=inCase, bit2=inEar, bit7=isConnect
+        # type: 2=left, 3=right, 4=case, 5=tws, 6=stereo
         if len(payload) < 3:
             return False
         count = payload[0]
         changed = False
+        if _DEBUG:
+            _log(f"[protocol] earphone raw={payload.hex()}")
         for i in range(1, 1 + count * 2, 2):
             if i + 1 >= len(payload):
                 break
             etype = payload[i]
             val = payload[i + 1]
+            if etype not in (2, 3):
+                continue
             in_ear = bool(val & 0x04)
-            connected = bool(val & 0x80)
-            wearing = in_ear and connected
-            if etype == 2 and wearing != self.state.left_wearing:
-                self.state.left_wearing = wearing
+            if etype == 2 and in_ear != self.state.left_wearing:
+                self.state.left_wearing = in_ear
                 changed = True
-            elif etype == 3 and wearing != self.state.right_wearing:
-                self.state.right_wearing = wearing
+            elif etype == 3 and in_ear != self.state.right_wearing:
+                self.state.right_wearing = in_ear
                 changed = True
         if changed:
             _log(f"[protocol] wearing L={self.state.left_wearing} R={self.state.right_wearing}")
@@ -632,10 +644,20 @@ class NothingDevice(GObject.Object):
                 ).start()
                 break
 
+    def _poll_earphone_status(self):
+        # The firmware only computes a fresh per-bud snapshot when asked; the
+        # pushed EVT frames carry stale placeholder entries for the bud that
+        # didn't change. Polling keeps both buds' wearing state accurate.
+        if not self._rfcomm_connected:
+            return False
+        self._x55_send(_CMD_EARPHONE)
+        return True
+
     def _activation_fallback(self):
         if not self._activated and self._rfcomm_connected:
             _log("[protocol] activation ACK not received within 3s — sending GET queries")
             self._activated = True
+            GLib.timeout_add(2000, self._poll_earphone_status)
             self._x55_send(_CMD_BATTERY)
             self._x55_send(_CMD_NOISE_RED, bytes([0x03]))
             self._x55_send(_CMD_EARPHONE)

{something_x_dev-1.3.0.dev6 → something_x_dev-1.5.0.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "something-x-dev"
-version = "1.3.0.dev6"
+version = "1.5.0.dev8"
 description     = "Something X device manager for Omarchy / Linux"
 readme          = "README.md"
 license         = { text = "MIT" }