AirDash

Display AirGradient air quality measurements in your macOS menu bar

Features

• Real-time temperature, PM2.5, humidity, and CO2 levels in your menu bar
• Auto-refresh every 60 seconds (configurable)
• Clean, minimal menu bar interface
• Background daemon mode with automatic installation
• Native macOS app using AppKit

Requirements

• macOS 11 (Big Sur) or later
• Apple Silicon (M1/M2/M3/M4)
• AirGradient sensor with API access

Installation

Option 1: Download DMG (Recommended)

1. Download the latest DMG from Releases
2. Open AirDash-{version}-arm64.dmg
3. Drag AirDash.app to the Applications folder
4. Launch AirDash from Applications
5. On first launch, it automatically installs itself as a background service

Option 2: Standalone Binary

1. Download the latest release from Releases
2. Extract the archive:

   tar -xzf airdash_{version}_darwin_arm64.tar.gz

3. Run the binary:

   ./airdash

Option 3: Build from Source

git clone https://github.com/ljagiello/airdash.git
cd airdash
go build
./airdash

Requirements: Go 1.25.4+ and Xcode Command Line Tools

Configuration

Create ~/.airdash/config.yaml:

# Required: Your AirGradient API token
token: your-secret-token-here

# Optional: Specific location ID (0 = all locations, default)
locationId: 0

# Optional: Update interval in seconds (default: 60)
interval: 60

# Optional: Temperature unit - "C" or "F" (default: "C")
tempUnit: F

Getting Your API Token

1. Log in to AirGradient Dashboard
2. Navigate to Settings → API
3. Generate a new API token
4. Copy the token to your config.yaml

Configuration Options

Option	Type	Default	Description
token	string	required	Your AirGradient API token
locationId	int	0	Specific sensor location (0 = all)
interval	int	60	Update interval in seconds
tempUnit	string	"C"	Temperature unit: "C" or "F"

Usage

DMG Installation

1. First Launch: After dragging to Applications and launching, AirDash automatically installs itself as a background service
2. Background Operation: The app runs continuously in the background, fetching air quality data
3. No GUI Required: Once installed, the daemon runs headlessly - no menu bar needed
4. Automatic Startup: Starts automatically when you log in

Standalone Binary

1. Run once: ./airdash - runs in GUI mode with menu bar
2. Install daemon: ./airdash install - sets up automatic background service
3. Uninstall: ./airdash uninstall - removes background service

Troubleshooting

No measurements showing

Check your configuration:

• Verify ~/.airdash/config.yaml exists with a valid API token
• Ensure locationId matches your sensor (or use 0 for all sensors)

Check the logs:

# View recent logs
log show --predicate 'process == "airdash"' --last 5m

# View with more detail
log show --predicate 'process == "airdash"' --info --last 1h

Common issues:

• Invalid or expired API token
• Sensor offline or not reporting data
• Network connectivity issues

App won't open or shows security warning

If you see a security warning:

1. Right-click the app and select Open
2. Click Open in the security dialog
3. Alternatively: System Settings → Privacy & Security → Allow

HTTP/API Errors

If you see HTTP errors in logs:

• Check your internet connection
• Verify AirGradient API status at https://status.airgradient.com
• Confirm your API token is valid and hasn't expired
• Try accessing the API directly:

  curl "https://api.airgradient.com/public/api/v1/locations/measures/current?token=YOUR_TOKEN"

App crashes or freezes

• Ensure you're on macOS 11 or later
• Check for updates: Releases
• Report issues with crash logs: GitHub Issues

Daemon not starting or stopping unexpectedly

Check daemon status:

launchctl list | grep airdash

View daemon logs:

# View recent logs
tail -50 ~/Library/Logs/airdash.log

# View errors
tail -50 ~/Library/Logs/airdash.error.log

# Monitor logs in real-time
tail -f ~/Library/Logs/airdash.log

Manually restart daemon:

launchctl stop com.github.ljagiello.airdash
launchctl start com.github.ljagiello.airdash

Reinstall daemon:

./airdash uninstall
./airdash install

Common daemon issues:

• Config file missing or invalid - check ~/.airdash/config.yaml
• API token expired - update your token in config
• Network connectivity issues - check internet connection
• Binary moved or deleted - reinstall daemon

Development

Local Development

# Clone the repository
git clone https://github.com/ljagiello/airdash.git
cd airdash

# Install dependencies
go mod download

# Build locally
go build -o airdash .

# Run
./airdash

Running Tests with Coverage

go test -v -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

API

AirDash uses the AirGradient Public API v1.

Endpoints used:

• GET /locations/measures/current - All locations
• GET /locations/{locationId}/measures/current - Specific location

Contributing

Contributions are welcome! Please read CODE_OF_CONDUCT.md before contributing.

Guidelines:

• Write tests for new features
• Run golangci-lint run before submitting
• Follow existing code style
• Update documentation as needed

License

See LICENSE file for details.

Acknowledgments

• Built with DarwinKit for macOS AppKit bindings
• Air quality data from AirGradient
• Logo design inspired by air quality monitoring