Native AirPods® integration for KDE Plasma 6 powered by a modern, low-latency Rust backend.
- 🔋 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)
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# Clone the repository
git clone https://github.com/can1357/kAirPods.git
cd kAirPods
# Run the automated installer
./scripts/install.shThe installer will:
- ✅ Check all prerequisites and dependencies
- ✅ Add you to the
bluetoothgroup (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
| 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 |
Debian/Ubuntu
sudo apt install build-essential pkg-config libdbus-1-dev libbluetooth-devFedora
sudo dnf install gcc pkg-config dbus-devel bluez-libs-develArch Linux
sudo pacman -S base-devel pkgconf dbus bluez-libsFirst, pair your AirPods through KDE System Settings → Bluetooth
./scripts/install.sh- Right-click on your Plasma panel
- Select "Add Widgets"
- Search for "kAirPods"
- Drag to panel
Click the widget to see battery levels and control your AirPods
Service won't start / No devices detected
-
Check bluetooth group (installer handles this automatically):
groups | grep bluetooth -
Check service logs:
systemctl --user status kairpodsd journalctl --user -u kairpodsd -f
-
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:
-
Stop the service:
systemctl --user stop kairpodsd.service
-
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
-
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)
-
Create config file:
mkdir -p ~/.config/kairpods echo 'log_filter = "debug"' > ~/.config/kairpods/config.toml
-
Restart the service:
systemctl --user restart kairpodsd.service
-
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)
┌─────────────────────────┐
│ 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
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
GetDevices() → s- Returns JSON array of all connected AirPodsGetDevice(address: s) → s- Returns JSON state of specific deviceSendCommand(address: s, action: s, params: a{sv}) → b- Send commandsConnectDevice(address: s) → b- Connect to AirPodsDisconnectDevice(address: s) → b- Disconnect from AirPods
BatteryUpdated(address: s, battery: s)- Battery level changesNoiseControlChanged(address: s, mode: s)- Noise control changesDeviceConnected(address: s)- Connection eventsDeviceDisconnected(address: s)- Disconnection events
./scripts/install.sh --uninstallOr with curl:
curl -fsSL https://raw.githubusercontent.com/can1357/kAirPods/master/scripts/get.sh | bash -s -- --uninstallThis project is licensed under the GNU General Public License v3.0 or later.
See the LICENSE file for details.
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.