Troubleshooting & FAQ

This guide covers common issues you might encounter when using the Aranet CLI, TUI, GUI, or library, along with solutions and workarounds.

Quick Diagnostics

Run the built-in diagnostic tool to check your system:

aranet doctor

This will check:

• Bluetooth adapter status
• Required permissions
• Known device connectivity
• Configuration validity

---

Bluetooth Issues

Device not found during scan

Symptoms: aranet scan returns no devices or times out.

Solutions:

1. Ensure the device is in range - Aranet devices have a Bluetooth range of approximately 10 meters (33 feet).

2. Check if the device is paired with another app - Some devices only allow one active connection. Close the official Aranet Home app or disconnect from other Bluetooth managers.

3. Restart Bluetooth on your system:

macOS

# Turn Bluetooth off and on
blueutil --power 0 && sleep 2 && blueutil --power 1

Linux

# Restart Bluetooth service
sudo systemctl restart bluetooth

Windows

# Restart Bluetooth service
Restart-Service bthserv

4. Increase scan duration:

aranet scan --timeout 30

5. Try passive scanning (doesn’t require active Bluetooth queries):

aranet scan --passive

Connection drops or times out

Symptoms: Commands fail with “connection timeout” or “device disconnected” errors.

Solutions:

1. Move closer to the device - Bluetooth Low Energy signal strength varies.

2. Check for interference - WiFi routers, microwaves, and other 2.4GHz devices can interfere.

3. Retry with longer timeout:

aranet read <ADDRESS> --timeout 60

4. Check device battery - Low battery can affect Bluetooth transmission power. Use:

aranet info <ADDRESS>

5. Reset the device connection:

# Disconnect and reconnect to the device
aranet read <ADDRESS>

“Permission denied” or “Access denied” errors

Symptoms: Bluetooth operations fail with permission errors.

macOS

macOS requires Bluetooth permission for terminal applications.

1. Open System Settings → Privacy & Security → Bluetooth
2. Ensure your terminal app (Terminal, iTerm2, etc.) is listed and enabled
3. If not listed, run aranet scan once - macOS should prompt for permission
4. Restart your terminal after granting permission

Linux

Linux requires either root access or proper group membership.

Option 1: Add user to bluetooth group

sudo usermod -aG bluetooth $USER
# Log out and back in for changes to take effect

Option 2: Grant capabilities to the binary

sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which aranet)

Option 3: Configure D-Bus policy Create /etc/dbus-1/system.d/aranet.conf:

<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Policy//EN"
  "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <policy user="YOUR_USERNAME">
    <allow own="org.bluez"/>
    <allow send_destination="org.bluez"/>
    <allow send_interface="org.bluez.GattCharacteristic1"/>
    <allow send_interface="org.bluez.GattDescriptor1"/>
    <allow send_interface="org.freedesktop.DBus.ObjectManager"/>
    <allow send_interface="org.freedesktop.DBus.Properties"/>
  </policy>
</busconfig>

Windows

Windows typically doesn’t require special permissions for Bluetooth, but:

1. Run as Administrator if you encounter issues
2. Check Windows Bluetooth settings - ensure Bluetooth is enabled
3. Update Bluetooth drivers via Device Manager

---

Installation Issues

Homebrew installation fails

Try these solutions in order:

1. Update Homebrew:

brew update
brew upgrade

2. Re-tap the repository:

brew untap cameronrye/aranet
brew tap cameronrye/aranet
brew install aranet

3. Install from source instead:

brew install --build-from-source aranet

4. Check for conflicts:

brew doctor

Cargo build fails with btleplug errors

Common causes and solutions:

On Linux - missing D-Bus development files:

# Debian/Ubuntu
sudo apt install libdbus-1-dev pkg-config

# Fedora/RHEL
sudo dnf install dbus-devel pkgconfig

# Arch
sudo pacman -S dbus pkgconf

On macOS - missing Xcode tools:

xcode-select --install

Outdated Rust toolchain:

rustup update stable

Shell completions not working

Generate and install completions for your shell:

Bash

aranet completions bash > ~/.local/share/bash-completion/completions/aranet
# Or for system-wide:
sudo aranet completions bash > /etc/bash_completion.d/aranet

Zsh

aranet completions zsh > ~/.zsh/completions/_aranet
# Add to ~/.zshrc if not present:
# fpath=(~/.zsh/completions $fpath)
# autoload -Uz compinit && compinit

Fish

aranet completions fish > ~/.config/fish/completions/aranet.fish

PowerShell

aranet completions powershell >> $PROFILE

Restart your shell after installing completions.

---

Data & Export Issues

History download is slow or incomplete

Aranet devices can store weeks of data. Large downloads take time due to BLE bandwidth limitations.

Tips for faster downloads:

1. Use incremental sync - only download new data:

aranet sync <ADDRESS>

2. Filter by date range:

aranet history <ADDRESS> --since 2026-01-01 --until 2026-01-15

3. Limit the number of records:

aranet history <ADDRESS> --limit 1000

4. Download to local database for future queries:

# Sync downloads history to the local SQLite database
aranet sync <ADDRESS>

# Query cached data without connecting to device
aranet cache history <ADDRESS>

CSV export has wrong encoding or format

Specify the output format explicitly:

# Standard CSV with headers
aranet history <ADDRESS> --format csv > data.csv

# JSON for programmatic use
aranet history <ADDRESS> --format json > data.json

# Plain text (default)
aranet history <ADDRESS> --format text

For Excel compatibility: Open the CSV file in Excel. If characters display incorrectly, use Excel’s “Get Data from Text/CSV” import feature and select UTF-8 encoding.

Timestamps appear wrong

Aranet devices store timestamps in UTC. The CLI converts to your local timezone by default.

If timestamps appear incorrect:

1. Verify your system timezone is set correctly
2. Check device interval - history timestamps are calculated from the device’s current time minus intervals
3. Use JSON output for precise timestamp inspection:

aranet history <ADDRESS> --format json

If device time is significantly wrong, you may need to reconfigure the device using the official Aranet Home app.

---

TUI & GUI Issues

TUI display is garbled or colors are wrong

Check your terminal compatibility:

1. Use a modern terminal - The TUI requires 256-color or truecolor support. Recommended: iTerm2, Alacritty, Windows Terminal, Kitty.

2. Set TERM environment variable:

export TERM=xterm-256color
aranet tui

3. Force basic mode:

aranet tui --style basic

4. Disable Unicode if symbols don’t render:

aranet tui --ascii

GUI won’t start or crashes on launch

Common solutions:

1. Check system requirements:

   • macOS 11.0+ (Big Sur or later)
   • Windows 10 version 1903+
   • Linux with GTK 3.24+

2. On macOS - verify app permissions:

   • Open System Settings → Privacy & Security
   • Check Bluetooth and Accessibility permissions

3. Try launching from terminal to see error messages:

# macOS
/Applications/Aranet.app/Contents/MacOS/aranet-gui

# Linux
aranet-gui --debug

4. Reset GUI settings:

rm -rf ~/.config/aranet-gui

System tray icon not appearing

Linux users: System tray support varies by desktop environment.

• GNOME: Install the AppIndicator extension
• KDE: Should work out of the box
• i3/Sway: Use a status bar with tray support (e.g., Waybar, i3bar with i3blocks)

macOS users: The menu bar icon should appear automatically. If not, check System Settings → Control Center → Menu Bar Only.

---

Frequently Asked Questions

Which devices are supported?

Currently supported devices:

Device	Sensors	Status
Aranet4	CO2, Temperature, Humidity, Pressure	Full support
Aranet2	Temperature, Humidity	Full support
AranetRn+	Radon, Temperature, Pressure, Humidity	Full support
Aranet Radiation	Dose Rate, Total Dose	Full support

Not yet supported: Aranet PRO base station, Aranet Cloud integration.

Can I use multiple devices simultaneously?

Yes! The CLI, TUI, and GUI all support multiple devices.

CLI - Read from multiple devices:

aranet read -d living-room -d bedroom -d office

TUI - Monitor multiple devices:

aranet tui --devices living-room,bedroom,office
# Or monitor all aliased devices:
aranet tui --all

Set up aliases for easy access:

aranet alias set living-room AA:BB:CC:DD:EE:FF
aranet alias set bedroom 11:22:33:44:55:66
aranet alias list

How do I integrate with Home Assistant?

Use the aranet-service daemon to expose a REST API:

# Start the service
aranet-service --port 8080

# The API is now available at http://localhost:8080
# GET /devices - List all devices
# GET /devices/:id/current - Get current readings
# GET /devices/:id/history - Get historical data

Then configure Home Assistant to poll the REST API using the RESTful sensor integration.

What are the CO2 color thresholds?

The Aranet4 uses the following thresholds (configurable on the device):

Level	CO2 Range	Color	Meaning
Good	< 1000 ppm	Green	Air quality is good
Warning	1000-1400 ppm	Amber	Consider ventilating
Poor	> 1400 ppm	Red	Ventilation needed

These thresholds can be customized:

aranet set <ADDRESS> --co2-warning 800 --co2-alarm 1200

Is this project affiliated with Aranet/SAF Tehnika?

No. This is an independent, community-driven open-source project. It is not affiliated with, endorsed by, or sponsored by Aranet or SAF Tehnika JSC.

Aranet is a trademark of SAF Tehnika JSC. This project communicates with Aranet devices using their documented Bluetooth Low Energy protocol.

---

Still Having Issues?

If you’ve tried the solutions above and still have problems:

1. Check existing issues on GitHub Issues
2. Open a new issue with:
   • Your OS and version
   • Output of aranet doctor
   • Steps to reproduce the problem
   • Full error message
3. Join the discussion on GitHub Discussions for general questions

Tip

Include the --debug flag when running commands to get more detailed output for bug reports:

aranet --debug scan