Aurora Alert App

A macOS menu bar app that monitors NOAA space weather data and alerts you when aurora borealis may be visible in Massachusetts.

Quick Start

1. Run the app: uv run python main.py
2. Click the menu bar icon → "Open Config"
3. Configure your email settings (see Gmail setup below)
4. Click "Test Email" to verify it works

Menu Bar Icons

Icon	Meaning
🟢	Quiet (G0-G1) - No aurora expected
🟡	Moderate (G2) - Possible in far north
🔴	Alert! (G3+) - May be visible in MA
⚪	Error fetching data
⚙️	Setup required

Gmail App Password Setup

Gmail requires an "App Password" for SMTP access. Regular passwords won't work.

Step 1: Enable 2-Step Verification

1. Go to Google Account Security
2. Under "Signing in to Google", click 2-Step Verification
3. Follow the prompts to enable it (if not already enabled)

Step 2: Generate App Password

1. Go to App Passwords
2. You may need to sign in again
3. At the bottom, click Select app → choose Mail
4. Click Select device → choose Mac
5. Click Generate
6. You'll see a 16-character password (like abcd efgh ijkl mnop)
7. Copy this password - you won't be able to see it again!

Step 3: Configure the App

1. Click the Aurora menu bar icon → Open Config
2. Edit the email section:

email:
  enabled: true
  smtp_host: smtp.gmail.com
  smtp_port: 587
  username: your-email@gmail.com
  password: abcdefghijklmnop  # Paste your 16-char App Password (spaces optional)
  to: your-email@gmail.com    # Where to send alerts

3. Save the file
4. Click Test Email to verify

Troubleshooting Gmail

"Username and Password not accepted"

• Make sure you're using an App Password, not your regular Google password
• App Passwords are exactly 16 characters
• 2-Step Verification must be enabled first

"Application-specific password required"

• You're using your regular password instead of an App Password
• Generate a new App Password following the steps above

Configuration Options

Edit ~/.auroraapp/config.yaml:

# When to alert (G1=Minor, G2=Moderate, G3=Strong, G4=Severe, G5=Extreme)
threshold: G3

# How often to check NOAA (minutes)
poll_interval: 15

# Minimum hours between alerts (unless storm escalates)
alert_cooldown_hours: 6

# Email settings
email:
  enabled: true
  smtp_host: smtp.gmail.com
  smtp_port: 587
  username: you@gmail.com
  password: your-app-password
  to: you@gmail.com

# Desktop notifications
notifications:
  enabled: true
  sound: true  # Play sound with notification

Alert Thresholds

For Massachusetts (latitude ~42°N), you typically need strong storms:

Level	Kp Index	Visibility in MA
G1	5	Very unlikely, even in dark skies
G2	6	Possible on horizon with dark skies
G3	7	Good chance with dark skies (recommended threshold)
G4	8	Likely visible, worth the drive
G5	9	Rare, definitely visible

Auto-Start at Login

Option 1: Login Items

1. System Settings → General → Login Items
2. Click + and add the run.sh script

Option 2: launchd (recommended)

Create ~/Library/LaunchAgents/com.auroraapp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.auroraapp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/YOUR_USERNAME/.auroraapp/run.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Replace YOUR_USERNAME with your actual username, then:

launchctl load ~/Library/LaunchAgents/com.auroraapp.plist

Troubleshooting

Gray icon (⚪)

• Check your internet connection
• Click menu → View Logs for error details
• NOAA service may be temporarily down (try again later)

No notifications appearing

1. System Settings → Notifications → Script Editor → Allow
2. Verify notifications.enabled: true in config

Email not sending

1. Click "Test Email" to see if it works
2. Check View Logs for error messages
3. Verify Gmail App Password is correct (see setup above)

Useful Links

• NOAA Aurora Forecast - Real-time aurora map
• NOAA Space Weather - Full space weather dashboard
• Clear Dark Sky - Cloud cover forecasts