kAirPods

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

---

✨ 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):

bash groups | grep bluetooth

1. Check service logs:

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

1. 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: bash systemctl --user stop kairpodsd.service

2. Start in debug mode: ```bash # 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 ```

1. Reproduce the issue:
2. Put your AirPods in your ears (or just open the case)
3. Wait about 30 seconds for the handshake and first battery message
4. 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: bash mkdir -p ~/.config/kairpods echo 'log_filter = "debug"' > ~/.config/kairpods/config.toml

2. Restart the service: bash systemctl --user restart kairpodsd.service

3. View logs: bash 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.