Nothing Ear

A command-line tool to check battery levels of Nothing Ear wireless earbuds via Bluetooth.

Features

• Real-time battery level monitoring for case and earbuds
• Human-readable and JSON output formats
• Automatic retry logic for connection reliability
• Auto-scan for Nothing Ear devices by name (no MAC address needed)
• Linux support with Bluetooth

Installation

Cargo Install (Recommended)

Install directly from crates.io:

cargo install nothing-ear

This will download and compile the latest version and install it to ~/.cargo/bin/nothing-ear.

Debian/Ubuntu (.deb Package)

Download and install the pre-built Debian package:

# Download the latest release from GitHub Releases
wget https://github.com/pedrordgs/nothing-ear/releases/latest/download/nothing-ear_0.1.3_x86_64-unknown-linux-gnu.deb

# Install the package
sudo dpkg -i nothing-ear_0.1.3_x86_64-unknown-linux-gnu.deb

From Source

Ensure you have Rust 1.70+ installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and build:

git clone https://github.com/pedrordgs/nothing-ear.git
cd nothing-ear
cargo build --release
sudo cp target/release/nothing-ear /usr/local/bin/

Dependencies

• Linux: bluetoothd (BlueZ), libbluetooth-dev
• Rust: 1.70+ with Cargo

Ubuntu/Debian

sudo apt update
sudo apt install bluetooth bluez libbluetooth-dev

Fedora

sudo dnf install bluez bluez-libs bluez-libs-devel

Arch Linux

sudo pacman -S bluez bluez-libs

Usage

Basic Usage

nothing-ear --device AA:BB:CC:DD:EE:FF

Options

• --device, -d <MAC>: Bluetooth MAC address of earbuds (optional, auto-scans if not provided)
• --json, -j: Output in JSON format
• --retries <N>: Number of retry attempts (default: 3)
• --monitor, -m: Monitor mode - continuously check every 30 seconds
• --help, -h: Show help
• --version, -V: Show version

Examples

Auto-scan (no MAC address needed)

$ nothing-ear
Scanning for Nothing Ear device...
Device: 00:11:22:33:44:55
Case:  85%
Left:  90%
Right: 80%

Human-readable output

$ nothing-ear --device 00:11:22:33:44:55
Device: 00:11:22:33:44:55
Case:  85%
Left:  90%
Right: 80%

JSON output

$ nothing-ear --json --device 00:11:22:33:44:55
{
  "device_address": "00:11:22:33:44:55",
  "timestamp": 1705420800,
  "battery_levels": {
    "case": {
      "percentage": 85,
      "is_charging": true
    },
    "left": {
      "percentage": 90,
      "is_charging": false,
      "is_connected": true
    },
    "right": {
      "percentage": 80,
      "is_charging": false,
      "is_connected": true
    }
  },
  "all_connected": true
}

Monitor mode

$ nothing-ear --device 00:11:22:33:44:55 --monitor

Bluetooth Setup

1. Ensure Bluetooth is enabled:

   sudo systemctl start bluetooth
   sudo systemctl enable bluetooth
   

2. Run without device address to auto-scan:

   nothing-ear
   

   The tool will automatically find and connect to your Nothing Ear device.

3. Or manually find your earbuds MAC address:

   bluetoothctl scan on
   # Look for "Nothing Ear" device
   

4. Pair if necessary:

   bluetoothctl pair AA:BB:CC:DD:EE:FF
   bluetoothctl trust AA:BB:CC:DD:EE:FF
   

Troubleshooting

Connection Issues

"Connection refused"

• Ensure earbuds are in range (<10m)
• Check if earbuds are awake (open case)
• Verify MAC address is correct

"Permission denied"

• Run with sudo if Bluetooth permissions are restricted
• Check user is in bluetooth group: sudo usermod -a -G bluetooth $USER

"Invalid MAC address"

• Format must be XX:XX:XX:XX:XX:XX
• Use uppercase or lowercase hex digits

Device Issues

"Parse error"

• Firmware may be incompatible
• Try resetting earbuds (put in case, hold buttons)

"Device not found"

• Confirm MAC with bluetoothctl devices (if using --device)
• Try running without --device to auto-scan
• Try power cycling earbuds
• Ensure earbuds are in pairing mode if not yet paired

General Tips

• Keep earbuds case open during connection
• Avoid interference from other Bluetooth devices
• Update system Bluetooth stack if issues persist

Development

Building

cargo build
cargo test
cargo run -- --help

Testing

Run unit tests:

cargo test

Run integration tests:

cargo test --test cli_integration

Code Coverage

cargo tarpaulin --ignore-tests

License

MIT License - see LICENSE file.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

Guidelines

• Follow Rust best practices
• Add tests for new features
• Update documentation
• Use conventional commits