kairpodsd

Crates.iokairpodsd
lib.rskairpodsd
version0.2.2
created_at2025-12-06 16:28:24.194864+00
updated_at2025-12-06 16:28:24.194864+00
descriptionD-Bus service for AirPods management in KDE Plasma
homepagehttps://github.com/can1357/kAirPods
repositoryhttps://github.com/can1357/kAirPods
max_upload_size
id1970394
size224,459
Can Bölük (can1357)

documentation

https://github.com/can1357/kAirPods

README

kAirPods

License: GPL v3 KDE Plasma 6 CI Rust

Native AirPods® integration for KDE Plasma 6 powered by a modern, low-latency Rust backend.

kAirPods panel widget showing battery levels and controls

✨ Features

  • 🔋 Real-time battery monitoring for AirPods, AirPods Max, case, and individual earbuds
  • 🔇 Noise control switching between ANC, Transparency, and Off modes
  • 👂 Ear detection status and control
  • ⏯️ Auto play/pause - Automatically pauses media when AirPods are removed and resumes when reinserted
  • 🎨 Native Plasma integration with theme-aware panel widget
  • ⚡ Zero-lag Bluetooth L2CAP communication for instant updates
  • 🔧 System-wide D-Bus service architecture (no root required)

🚀 Quick Install

One-liner install (recommended)

curl -fsSL https://raw.githubusercontent.com/can1357/kAirPods/master/scripts/get.sh | bash

# With options:
curl -fsSL https://raw.githubusercontent.com/can1357/kAirPods/master/scripts/get.sh | bash -s -- --verbose --debug

Manual install

# Clone the repository
git clone https://github.com/can1357/kAirPods.git
cd kAirPods

# Run the automated installer
./scripts/install.sh

The installer will:

  • ✅ Check all prerequisites and dependencies
  • ✅ Add you to the bluetooth group (if it exists)
  • ✅ Build the Rust service in release mode
  • ✅ Install all components system-wide
  • ✅ Start the service via systemd
  • ✅ Guide you through adding the widget

📋 Prerequisites

Component Minimum Version Notes
KDE Plasma 6.0 Required for widget support
Rust toolchain 1.88+ Install Rust
BlueZ 5.50+ Bluetooth stack (package: bluez or bluez-libs)
Linux Kernel 5.10+ L2CAP socket support
systemd 247+ User services support
D-Bus 1.12+ IPC communication

📦 Development Packages

Debian/Ubuntu 
sudo apt install build-essential pkg-config libdbus-1-dev libbluetooth-dev
Fedora 
sudo dnf install gcc pkg-config dbus-devel bluez-libs-devel
Arch Linux 
sudo pacman -S base-devel pkgconf dbus bluez-libs

🎯 Getting Started

1️⃣ Pair Your AirPods

First, pair your AirPods through KDE System Settings → Bluetooth

2️⃣ Install kAirPods

./scripts/install.sh

3️⃣ Add the Widget

  • Right-click on your Plasma panel
  • Select "Add Widgets"
  • Search for "kAirPods"
  • Drag to panel

4️⃣ Enjoy!

Click the widget to see battery levels and control your AirPods

🛠️ Troubleshooting

Service won't start / No devices detected

  1. Check bluetooth group (installer handles this automatically):

    groups | grep bluetooth

  2. Check service logs:

    systemctl --user status kairpodsd
journalctl --user -u kairpodsd -f

  3. Ensure AirPods are paired via KDE Bluetooth settings first

Permission denied errors
  • The installer automatically adds you to the bluetooth group
  • If you still have issues, try: sudo setcap 'cap_net_raw,cap_net_admin+eip' $(command -v kairpodsd)
Widget not showing up
  • Restart plasmashell: systemctl --user restart plasma-plasmashell
  • Or simply log out and back in
Battery not showing / Debug logging

If your AirPods connect but battery information is missing, enable debug logging to help diagnose the issue:

Method 1: Running manually with debug output

  1. Stop the service:

    systemctl --user stop kairpodsd.service

  2. Start in debug mode:

    # Shows general debug info and all Bluetooth packets
RUST_LOG=kairpodsd=debug,kairpodsd::bluetooth::l2cap=trace kairpodsd

# Or use the full path if needed
RUST_LOG=kairpodsd=debug,kairpodsd::bluetooth::l2cap=trace /usr/bin/kairpodsd

  3. Reproduce the issue:

    • Put your AirPods in your ears (or just open the case)
    • Wait about 30 seconds for the handshake and first battery message
    • Copy the terminal output (you can redact MAC addresses like AA:BB:CC:DD:EE:FF)

Method 2: Using systemd with debug config

  1. Create config file:

    mkdir -p ~/.config/kairpods
echo 'log_filter = "debug"' > ~/.config/kairpods/config.toml

  2. Restart the service:

    systemctl --user restart kairpodsd.service

  3. View logs:

    journalctl --user -u kairpodsd.service -b --no-pager

The debug output will show:

  • Connection handshake details
  • All Bluetooth packet exchanges
  • Battery update messages (or lack thereof)
  • Any parsing errors or protocol issues

Common causes for missing battery info:

  • BlueZ experimental features not enabled (installer handles this automatically)
  • Enhanced Retransmission Mode (ERTM) disabled
  • Outdated BlueZ version (need ≥ 5.50)

🏗️ Architecture

                             ┌─────────────────────────┐
                             │      Plasma Widget      │
                             │  (Kirigami / QML UI)    │
                             └───────────▲─────────────┘
                                         │  D-Bus IPC
                                         │
┌───────────────────────┐   manages   ┌──▼────────────────┐
│   plasmashell (GUI)   │◀────────────│   kairpodsd       │
│  + panel & widgets    │  systemd-u  │  (Rust service)   │
└───────────────────────┘             └──┬────────────────┘
                                         │  Bluetooth L2CAP
                                         │
                                   ┌─────▼───────┐
                                   │  AirPods    │
                                   └─────────────┘
  • Backend: High-performance Rust service (kairpodsd) with direct L2CAP access
  • Frontend: QML Plasmoid with Kirigami components
  • IPC: D-Bus interface at org.kairpods.manager

🔌 D-Bus API

For developers and power users:

# List connected devices
busctl --user call org.kairpods /org/kairpods/manager \
    org.kairpods.manager GetDevices

# Control noise mode
busctl --user call org.kairpods /org/kairpods/manager \
    org.kairpods.manager SendCommand ssa{sv} "AA:BB:CC:DD:EE:FF" "set_noise_mode" 1 "value" s "anc"
Full API Reference

Methods

  • GetDevices() → s - Returns JSON array of all connected AirPods
  • GetDevice(address: s) → s - Returns JSON state of specific device
  • SendCommand(address: s, action: s, params: a{sv}) → b - Send commands
  • ConnectDevice(address: s) → b - Connect to AirPods
  • DisconnectDevice(address: s) → b - Disconnect from AirPods

Signals

  • BatteryUpdated(address: s, battery: s) - Battery level changes
  • NoiseControlChanged(address: s, mode: s) - Noise control changes
  • DeviceConnected(address: s) - Connection events
  • DeviceDisconnected(address: s) - Disconnection events

🗑️ Uninstalling

./scripts/install.sh --uninstall

Or with curl:

curl -fsSL https://raw.githubusercontent.com/can1357/kAirPods/master/scripts/get.sh | bash -s -- --uninstall

📄 License

This project is licensed under the GNU General Public License v3.0 or later.
See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For more details on manual installation, advanced configuration, or packaging for distributions, see INSTALL.md.

Commit count: 0

cargo fmt