AirGradient Monitor Analyzer

This tool automatically fetches data from AirGradient monitors, analyzes it for abnormalities, and updates a Google Sheet with the results. It's designed to run as a GitHub Actions workflow on a daily schedule.

Features

• Fetches data from AirGradient API for 100+ monitors
• Analyzes data for:
  • Zero readings
  • Abnormal values (outside expected ranges)
  • Significant fluctuations
  • Online/offline status changes
• Updates Google Sheets with:
  • Daily detailed data
  • Current status overview
  • Monthly summaries
• Runs automatically every day
• Processes monitors in parallel for efficiency
• Color-coded status indicators

Setup Instructions

1. Create a GitHub Repository

1. Create a new GitHub repository (can be private)

2. Add the files from this folder to your repository using one of these methods:

   Method A: Using GitHub Web Interface

   • Go to your new GitHub repository
   • Click "Add file" > "Upload files"
   • Drag and drop all files from the airgradient-monitor folder
   • Make sure to maintain the folder structure (especially the .github/workflows folder)
   • Click "Commit changes"

   Method B: Using Git Command Line

   • Clone your new repository:

     git clone https://github.com/your-username/your-repo-name.git
     cd your-repo-name
     

   • Copy all files from the airgradient-monitor folder to this directory
   • Add, commit, and push the files:

     git add .
     git commit -m "Add AirGradient monitor analyzer"
     git push origin main
     

   Important: Make sure the .github/workflows directory is included, as this contains the workflow file that runs the script automatically.

3. Verify the workflow file is properly uploaded:

   • Go to the "Actions" tab in your GitHub repository
   • You should see the "Monitor Data Analysis" workflow listed
   • If you don't see it, check that the file .github/workflows/monitor-analysis.yml exists in your repository
   • If needed, create the .github/workflows directory manually and upload the monitor-analysis.yml file there

2. Set Up Google Sheets API

1. Create a Google Cloud project:

   • Go to Google Cloud Console
   • Create a new project
   • Enable the Google Sheets API and Google Drive API

2. Set up OAuth 2.0 credentials (for local development):

   • In your Google Cloud project, go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "Desktop app" as the application type
   • Give it a name like "AirGradient Monitor Analyzer"
   • Click "Create"
   • Download the credentials JSON file and save it as credentials.json in your project directory

3. Create a service account (for GitHub Actions):

   • In your Google Cloud project, go to "IAM & Admin" > "Service Accounts"
   • Click "Create Service Account"
   • Give it a name like "AirGradient Monitor Analyzer"
   • Grant it the "Editor" role
   • Click "Create Key" (JSON format)
   • Download the JSON credentials file (you'll need this for GitHub Secrets)
   • Share your Google Sheet with the service account email (giving it edit access)

4. Create a Google Sheet:

   • Create a new Google Sheet
   • Make note of the Sheet ID from the URL (the long string between /d/ and /edit in the URL)

3. Configure Your Local Environment

1. Create a config.json file in your project directory based on the sample-config.json template:

   {
     "AIRGRADIENT_TOKEN": "your_airgradient_api_token_here",
     "GOOGLE_SHEET_ID": "your_google_sheet_id_here",
     "LOCATION_IDS": "*"
   }

   Note: Setting LOCATION_IDS to "*" will automatically process all monitors available in your AirGradient account. New monitors will be automatically included without any configuration changes.

2. Run the test configuration script to verify your setup:

   python test_config.py
   

   • The first time you run this, it will open a browser window asking you to authorize the application
   • After authorization, it will save a token.json file with your OAuth tokens
   • This token.json file will be used for local development only

Note: The system uses OAuth2 authentication for local development and service account authentication for GitHub Actions. This hybrid approach provides the best experience for both scenarios.

4. Configure GitHub Secrets

Add the following secrets to your GitHub repository:

1. Go to your repository on GitHub

2. Click on "Settings" > "Secrets and variables" > "Actions"

3. Click on "New repository secret"

4. Add each of these secrets:

   • AIRGRADIENT_TOKEN:

     • Name: AIRGRADIENT_TOKEN
     • Value: Your AirGradient API token
     • Click "Add secret"

   • GOOGLE_SHEETS_CREDENTIALS:

     • Name: GOOGLE_SHEETS_CREDENTIALS
     • Value: The entire JSON content of the service account credentials file
       • Open the downloaded JSON credentials file in a text editor
       • Copy the entire content (including the curly braces)
       • Paste it as the secret value
     • Click "Add secret"

   • GOOGLE_SHEET_ID:

     • Name: GOOGLE_SHEET_ID
     • Value: The ID of your Google Sheet
       • This is the long string in the URL between /d/ and /edit
       • Example: For URL https://docs.google.com/spreadsheets/d/1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t/edit
       • The ID is 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t
     • Click "Add secret"

   • LOCATION_IDS (optional - only if you want to override the default):

     • Name: LOCATION_IDS
     • Value: A JSON array of specific monitor location IDs, e.g., [123, 456, 789]
     • Note: By default, the workflow is configured to process all monitors automatically
     • Click "Add secret"

5. Run the Workflow

The workflow will run automatically at 1 AM UTC daily. You can also run it manually:

1. Go to the "Actions" tab in your GitHub repository
2. Select the "Monitor Data Analysis" workflow
3. Click "Run workflow"

Google Sheet Structure

The script will automatically create and update the following sheets:

1. Daily Data: Historical log of all readings and analysis

   • One row per monitor per day
   • Includes all sensor readings and analysis results

2. Current Status: Overview of all monitors' current state

   • Color-coded status indicators
   • Quick view of which monitors have issues

3. Monthly Sheets: Auto-generated for each month (e.g., "June 2025")

   • Daily summaries for each monitor
   • Aggregated statistics

Maintenance

Adding New Monitors

The system is configured to automatically detect and include all monitors in your AirGradient account. When you set LOCATION_IDS to "*" (recommended), new monitors will be automatically included without any configuration changes.

If you prefer to specify exact monitors:

1. Update the LOCATION_IDS secret in your GitHub repository with specific location IDs as a JSON array, e.g., [81455, 81456, 88657]

Troubleshooting

If the workflow fails:

1. Check the workflow run logs in the GitHub Actions tab
2. Verify that all secrets are correctly configured
3. If you get authentication errors:
   • For local development: The OAuth token may have expired. Run the test_config.py script locally to generate a new token.json
   • For GitHub Actions: Make sure the GOOGLE_SHEETS_CREDENTIALS secret contains valid service account credentials and the Google Sheet is shared with the service account email

For Non-Technical Users

As a non-technical user, you only need to:

1. Open the Google Sheet to view the data
2. Check the "Current Status" sheet for a quick overview
3. Explore the "Daily Data" sheet for historical data
4. View monthly summaries in the monthly sheets

The data will update automatically every day. If you need to trigger an update manually, ask your technical contact to run the workflow from the GitHub Actions tab.