Airler

Airler keeps your Mac in sync with the air you breathe. This lightweight, location-aware menu bar app pulls live air-quality intelligence from the Airly platform and turns it into a calming dashboard that is always one click away. See the city’s current CAQI score, spot trends at a glance with adaptive colors, and dive into pollutant-level details without breaking your flow.

Why Airler

• Always-on awareness: A persistent status-bar icon keeps high-level air quality data within reach, even when the app window is closed.
• Hyper-local insights: Automatic location detection (rounded for accuracy) ensures the measurements you see match the air around you.
• Actionable clarity: Color-coded CAQI values, plain-language advice, and pollutant highlights help you decide when to open a window or stay inside.
• Built for macOS: Native Xamarin.Mac experience, smooth animations, and Notification Center widget groundwork for future releases.

Feature Highlights

• Menu bar popover with live CAQI, description, and guidance that color-shifts across safe, warning, and critical thresholds.
• One-tap “More” view exposing particulate matter (PM1, PM2.5, PM10), humidity, pressure, and temperature in beautifully laid-out tiles.
• Automatic refresh every hour (or on demand) via the dedicated refresh control.
• Seamless Airly API integration handled through a simple environment file—no manual secrets inside the codebase.

Prerequisites

• macOS with Xamarin.Mac tooling (Visual Studio for Mac 2019+ or msbuild with Xamarin workloads installed).
• .NET/Mono tooling capable of targeting Xamarin.Mac v2.0 (ships with Visual Studio for Mac).
• An Airly API key. You can request a key at developer.airly.org.
• Access to location services on the device for best results (Airler gracefully falls back if permission is denied).

Installation

1. Clone or download the repository to your Mac.
2. Restore NuGet packages (AirlyNet, Newtonsoft.Json, etc.):

   nuget restore Airler.sln

3. Create your environment file in the home directory (details below) so the app can authenticate with Airly.
4. Build the solution:
   • Using Visual Studio for Mac: Open Airler.sln, select the Airler project, and build/run.
   • Using the command line:

     msbuild Airler.sln /t:Build /p:Configuration=Release

     The compiled .app bundle will be in Airler/bin/Release.
5. Launch Airler (from Visual Studio or by opening the .app bundle). Grant location permission when prompted to enable hyper-local readings.

Environment Configuration (~/air.env)

Airler expects a simple environment file in your home directory so secrets stay out of source control.

1. Create a file named air.env at the root of your user directory:

   touch ~/air.env

2. Add your Airly key:

   echo "AIRLY_API_KEY=your_airly_key_here" >> ~/air.env

3. Restart Airler after updating the file so the key is reloaded on startup.

If the key is missing, the app will still launch but will log a warning and skip air-quality calls.

Using Airler

• Click the Airler icon in the macOS menu bar to open the popover.
• Track the current CAQI score, headline, and advice—color accents reflect normal, warning, or critical air conditions.
• Press the More button to reveal pollutant tiles. Each tile displays the current value, a progress indicator, and a tooltip.
• Use the Refresh button if you need the latest measurement between the automatic hourly updates.
• Dismiss the popover by clicking outside it or pressing the menu bar icon again. The app continues monitoring in the background.

Troubleshooting

• No data appears: Confirm that location services are enabled and the AIRLY_API_KEY value is present in ~/air.env.
• Build failures about Xamarin targets: Make sure the Xamarin.Mac workload is installed with your IDE or Mono setup.
• Location permission denied: Re-enable access in System Preferences → Security & Privacy → Privacy → Location Services.

Roadmap & Contributions

The project includes an Airler.Widget target that lays the groundwork for a Today Widget extension. Contributions, issue reports, and suggestions that help refine the breathing experience are welcome—feel free to open a pull request or share feedback.