airgradient_esphome
ESPHome definition for an AirGradient DIY device to send data to HomeAssistant and AirGradient servers
Stars: 268
ESPHome yaml files for AirGradient devices to maintain the research and accuracy of AirGradient sensors, while also gaining the benefits of ESPHome/HomeAssistant for easy to use switches, buttons, configurations, and dashboards. Maintains the ability to also send data to the AirGradient Dashboard, which can also be disabled/removed to keep all data local.
README:
ESPHome yaml files for AirGradient devices to maintain the research and accuracy of AirGradient sensors, while also gaining the benefits of ESPHome/HomeAssistant for easy to use switches, buttons, configurations, and dashboards. Maintains the ability to also send data to the AirGradient Dashboard, which can also be disabled/removed to keep all data local.
- 5.0.0 is a major version upgrade as switching to esp-idf is not fully supported via OTA. Highly recommend doing one USB flash of 4.1.0 and later to the AirGradient ONE and OpenAir devices to reformat the storage to support esp-idf. Future updates can be done Over-The-Air without issue.
- It not done, the device is likely to reboot at some point and switch to the standby partition, returning to a version prior to 4.1.0
- Seeing an Old Firmware Version After Update? Here's Why & How to Fix It · Issue #1821 · Blackymas/NSPanel_HA_Blueprint
- Read/Write bootloader, partition table and any partition via OTA by angelnu · Pull Request #5535 · esphome/esphome
- Aware of errors in the logs stating
esp_task_wdt_reconfigure(615): Invalid arguments - 4.1.0 switches ONE and OpenAir models (based on ESP32) to the esp-idf framework, freeing up some memory and allowing other advanced features such as bluetooth_proxy and esp32_improv. If the previous Arduino framework is desired, change the board to
airgradient_esp32-c3_board-arduino.yaml - If attempting to add BT and BLE support, may need to remove the captive_portal package to free up enough space Issue #115
- Remove substitution line such as
config_version: 2.0.5from the main file, as this has been moved into the board package file - Updated to 4.0.0 versions, skipping 3.x to avoid confusion with current AirGradient official firmware
- Now defaulting to https for AirGradient API communication. If older devices (DIY and Pro models) go into constant reboots, switch to the api package
airgradient_api_d1_mini_insecure.yamlto revert to the original communication method
- Support for ESPHome 2025.2 and later due to changes to esp32_rmt_led_strip
- Added extended timeout for API upload on ONE and OpenAir models to reduce reboots
- Applied correction algorithms for PM2.5 provided by AirGradient
- Updated API upload to follow current structure including both raw and corrected values
- Moved config_version substitution into the board package so it can be updated without manual change to main config file. Please remove the line starting with
config_version:from your personal files - Split captive portal config to a separate package. Can be removed if not using the portal or if defining wifi networks in your config file, which results in a small memory savings
- Removed safe_mode package by default. Very few use cases for it
- Added commented out packages for extended_life configs to make it easier to enable if desired
- Added commented out package for SHT30 temp sensor in AG Pro file to make it easier to switch to if desired
- Added new sensor options for raw values for PM2.5, temp, and humidity in some device configurations, and added AirGradient provided correction algorithms to the standard sensors
- AG DIY Basic display config changed to same font as other models, downloading from gfonts instead of using local file
Many added features can be found in HomeAssistant by going to Settings>Devices and selecting the AirGradient device. Alternatively, add web_server: to the config file to enable a built-in web server on the AirGradient device (No recommended for devices based on the D1 Mini ESP8266)
-
Compact single page display by default with all relevant sensor readings
-
Display Contrast slider to dim the display
-
Enable different pages of information to be shown on the OLED display, or leave the default of a single page with all relevant information
-
Button to initiate a SenseAir S8 CO2 Calibration on demand
-
Switch to enable or disable SenseAir S8 CO2 sensor Automatic Baseline Calibration (ABC)
-
Button to view the current S8 ABC interval (confirm if ABC is disabled or enable, which defaults to every 7 days) View ESPHome logs to see the output of this button
-
Switch to disable LED output on AirGradient ONE model
-
Brightness slider to adjust intensity of AirGradient ONE LED
-
Switch to toggle display between Fahrenheit and Celsius and persist between reboots
-
Switch to enable or disable uploading to AirGradient Dashboard via API (Choose to keep data local or also send to AirGradient)
-
Utilize hardware configuration buttons on AirGradient Pro v3.7 and higher
- Short press (Less than 1 second) - Toggle between F and C on display
- Long press (More than 1 second, less than 5) - Trigger manual CO2 calibration
-
Leverage automation in HomeAssistant to turn on the "Blank" page and turn off all other pages to effectively disable the display output. Could also turn off the LED strip or set Brightness to 0 to eliminate output while still collecting sensor data
- In ESPHome web interface, click New Device. Give any name. Select any model of board, and click Skip on the final page to not install at this time. Click Edit on the new entry and replace with the contents of the .yaml file for your model.
- Alternatively, copy the .yaml file from the main folder for your model in this repo and place it in the
configfolder of your ESPHome. - Make any desired changes to the substitutions to name the devices for your use case
- Install to the device using one of the ESPHome options.
Note: by default ESPHome only syncs remote repositories that the packages are referencing once per day, so if changes are made to the repository, you may not get the updated config for up to 1 day after it is published. You can remove the contents of the folder config/.esphome/packages to force it to update sooner
Note: setting
add_mac_suffix: "true"allows for multiple devices on your network at the same time and report as unique entries even if yourname:field is duplicated, but it can cause ESPHome to not detect devices as Online after installing, since ESPHome is looking for only thename:field and the actual device name has the MAC address added to the endOne way to resolve this is to change
add_mac_suffix: "false"so the device name will match exactly. If you have multiple devices, make sure to change thename:field to be unique for each deviceAnother alternative is to add a static IP to the wifi configuration and configure ESPHome to ping the device by IP instead of hostname
Dashboard status light not working across subnets/zones · Issue #641 · esphome/issues (github.com)
Example for static IP
wifi: ssid: !secret wifi_ssid password: !secret wifi_password manual_ip: static_ip: 192.168.1.121 gateway: 192.168.1.1 subnet: 255.255.255.0 dns1: 192.168.1.1
Install a compiled file to your device all with just a browser and USB cable, no ESPHome install required.
Save the appropriate .bin file and go to https://web.esphome.io/ in your browser to connect your ESP device and send the .bin file to it
In some cases, the device may encounter errors using the web flash tool. Steps to put the device in a special boot flash mode can be found here: https://forum.airgradient.com/t/airgradient-one-not-working-after-flashing-with-arduino/1326/4
The full_config folder contains a single yaml file per model that contains the full standalone configuration, created by the esphome config command. This adds in all of the optional parameters, so is much longer than the minimum configuration, but the single file contains all needed information to be completely independent from this repo.
Copy the full config file to your personal ESPhome config file and customize as desired, then install to your device.
If some sensors are not showing valid readings after installing or upgrading, please remove the power cable from the device entirely for 5-10 seconds, then reconnect. Many issues are resolved with a full power reset, as the software reset does not fully clear some situations.
If all original sensors (PMS5003, Senseair S8, SHT4x) are connected, configuration files should be ready for use.
If some sensors are not installed, comment or remove the associated sections under packages:
The PMS5003 sensor by default collects readings every second. Since this device has a limited lifespan, it is possible to extend the life by collecting readings less frequently, although this could impact the accuracy of the readings collected, since there will not be constant airflow through the device when the fan shuts down. To collect readings every 2 minutes, change the line for the pms5003 sensor to sensor_pms5003_extended_life.yaml
See PMSX003 Particulate Matter Sensor — ESPHome for more information
To add your WiFi SSID and password, add your SSID and password information, per ESPHome specifications
wifi:
ssid: NachoWiFi
password: 123456123456By default, packages are referencing this GitHub repository, allowing you to do a new Install from ESPHome dashboard to get the latest modifications without downloading other files, but does require an Internet connection. If you wish to have more control over modifications or only reference local files, copy the packages folder to your local ESPHome folder in a packages subfolder and replace github://MallocArray/airgradient_esphome/packages with !include packages
# Example
board: github://MallocArray/airgradient_esphome/packages/sensor_s8.yaml
# becomes
board: !include packages/sensor_s8.yamlRather than download an individual package and update the reference to it, you may also use the Extend option to make minor modifications without editing the packages file. This only works for items with and id: defined
Example: adding this to the main file for your device will change the pin number in the config_button package, while maintaining all other settings defined in the package
binary_sensor: - id: !extend config_button pin: number: D7
It is also possible to copy the contents of a package file and paste it directly into your YAML file. Do note that sections cannot be duplicated, so if multiple sections like interval are pasted in, they must be combined into a single entry when using this method.
Several additional packages are available in the packages folder that can be added or removed as needed. See the Packages page for more information about available options.
MQTT support has been mentioned in the AirGradient forums several times. ESPHome supports this by adding a few lines to the main yaml file. Add the relevant information for your configuration. Read more about it here: https://esphome.io/components/mqtt.html
Several more features are planned to be added to this repo
- [ ] Explore options for disabling display/LED during certain times (May be differed to HomeAssistant Automation)
- [X] Standardize font on AirGradient Basic display to match Pro
For Tasks:
Click tags to check more tools for each tasksFor Jobs:
Alternative AI tools for airgradient_esphome
Similar Open Source Tools
airgradient_esphome
ESPHome yaml files for AirGradient devices to maintain the research and accuracy of AirGradient sensors, while also gaining the benefits of ESPHome/HomeAssistant for easy to use switches, buttons, configurations, and dashboards. Maintains the ability to also send data to the AirGradient Dashboard, which can also be disabled/removed to keep all data local.
AirSane
AirSane is a SANE frontend and scanner server that supports Apple's AirScan protocol. It automatically detects scanners and publishes them through mDNS. Acquired images can be transferred in JPEG, PNG, and PDF/raster format. The tool is intended to be used with AirScan/eSCL clients such as Apple's Image Capture, sane-airscan on Linux, and the eSCL client built into Windows 10 and 11. It provides a simple web interface and encodes images on-the-fly to keep memory/storage demands low, making it suitable for devices like Raspberry Pi. Authentication and secure communication are supported in conjunction with a proxy server like nginx. AirSane has been reverse-engineered from Apple's AirScanScanner client communication protocol and offers a range of installation and configuration options for different operating systems.
SlicerTotalSegmentator
TotalSegmentator is a 3D Slicer extension designed for fully automatic whole body CT segmentation using the 'TotalSegmentator' AI model. The computation time is less than one minute, making it efficient for research purposes. Users can set up GPU acceleration for faster segmentation. The tool provides a user-friendly interface for loading CT images, creating segmentations, and displaying results in 3D. Troubleshooting steps are available for common issues such as failed computation, GPU errors, and inaccurate segmentations. Contributions to the extension are welcome, following 3D Slicer contribution guidelines.
airbroke
Airbroke is an open-source error catcher tool designed for modern web applications. It provides a PostgreSQL-based backend with an Airbrake-compatible HTTP collector endpoint and a React-based frontend for error management. The tool focuses on simplicity, maintaining a small database footprint even under heavy data ingestion. Users can ask AI about issues, replay HTTP exceptions, and save/manage bookmarks for important occurrences. Airbroke supports multiple OAuth providers for secure user authentication and offers occurrence charts for better insights into error occurrences. The tool can be deployed in various ways, including building from source, using Docker images, deploying on Vercel, Render.com, Kubernetes with Helm, or Docker Compose. It requires Node.js, PostgreSQL, and specific system resources for deployment.
Minimalistic-Comfy-Wrapper-WebUI
Minimalistic Comfy Wrapper WebUI is a user interface extension for ComfyUI that provides an additional inference-focused UI. It dynamically adapts to workflows, allowing users to change node titles and refresh the UI. The tool ensures stability by storing data in the browser's local storage, supports working with the same workflows in Comfy and the webui, offers better queues management, prompt presets, batch support, a minimalist image editor, and mobile-friendly UI. Users can install it from the ComfyUI manager and customize node titles for input and output nodes. The tool is designed for users who prefer a simpler interface for inference tasks and want to work with ComfyUI workflows from a different perspective.
reai-ghidra
The RevEng.AI Ghidra Plugin by RevEng.ai allows users to interact with their API within Ghidra for Binary Code Similarity analysis to aid in Reverse Engineering stripped binaries. Users can upload binaries, rename functions above a confidence threshold, and view similar functions for a selected function.
ultimate-rvc
Ultimate RVC is an extension of AiCoverGen, offering new features and improvements for generating audio content using RVC. It is designed for users looking to integrate singing functionality into AI assistants/chatbots/vtubers, create character voices for songs or books, and train voice models. The tool provides easy setup, voice conversion enhancements, TTS functionality, voice model training suite, caching system, UI improvements, and support for custom configurations. It is available for local and Google Colab use, with a PyPI package for easy access. The tool also offers CLI usage and customization through environment variables.
jaison-core
J.A.I.son is a Python project designed for generating responses using various components and applications. It requires specific plugins like STT, T2T, TTSG, and TTSC to function properly. Users can customize responses, voice, and configurations. The project provides a Discord bot, Twitch events and chat integration, and VTube Studio Animation Hotkeyer. It also offers features for managing conversation history, training AI models, and monitoring conversations.
StableSwarmUI
StableSwarmUI is a modular Stable Diffusion web user interface that emphasizes making power tools easily accessible, high performance, and extensible. It is designed to be a one-stop-shop for all things Stable Diffusion, providing a wide range of features and capabilities to enhance the user experience.
blurt
Blurt is a Gnome shell extension that enables accurate speech-to-text input in Linux. It is based on the command line utility NoteWhispers and supports Gnome shell version 48. Users can transcribe speech using a local whisper.cpp installation or a whisper.cpp server. The extension allows for easy setup, start/stop of speech-to-text input with key bindings or icon click, and provides visual indicators during operation. It offers convenience by enabling speech input into any window that allows text input, with the transcribed text sent to the clipboard for easy pasting.
dockershrink
Dockershrink is an AI-powered Commandline Tool designed to help reduce the size of Docker images. It combines traditional Rule-based analysis with Generative AI techniques to optimize Image configurations. The tool supports NodeJS applications and aims to save costs on storage, data transfer, and build times while increasing developer productivity. By automatically applying advanced optimization techniques, Dockershrink simplifies the process for engineers and organizations, resulting in significant savings and efficiency improvements.
gpt-subtrans
GPT-Subtrans is an open-source subtitle translator that utilizes large language models (LLMs) as translation services. It supports translation between any language pairs that the language model supports. Note that GPT-Subtrans requires an active internet connection, as subtitles are sent to the provider's servers for translation, and their privacy policy applies.
aici
The Artificial Intelligence Controller Interface (AICI) lets you build Controllers that constrain and direct output of a Large Language Model (LLM) in real time. Controllers are flexible programs capable of implementing constrained decoding, dynamic editing of prompts and generated text, and coordinating execution across multiple, parallel generations. Controllers incorporate custom logic during the token-by-token decoding and maintain state during an LLM request. This allows diverse Controller strategies, from programmatic or query-based decoding to multi-agent conversations to execute efficiently in tight integration with the LLM itself.
vigenair
ViGenAiR is a tool that harnesses the power of Generative AI models on Google Cloud Platform to automatically transform long-form Video Ads into shorter variants, targeting different audiences. It generates video, image, and text assets for Demand Gen and YouTube video campaigns. Users can steer the model towards generating desired videos, conduct A/B testing, and benefit from various creative features. The tool offers benefits like diverse inventory, compelling video ads, creative excellence, user control, and performance insights. ViGenAiR works by analyzing video content, splitting it into coherent segments, and generating variants following Google's best practices for effective ads.
0chain
Züs is a high-performance cloud on a fast blockchain offering privacy and configurable uptime. It uses erasure code to distribute data between data and parity servers, allowing flexibility for IT managers to design for security and uptime. Users can easily share encrypted data with business partners through a proxy key sharing protocol. The ecosystem includes apps like Blimp for cloud migration, Vult for personal cloud storage, and Chalk for NFT artists. Other apps include Bolt for secure wallet and staking, Atlus for blockchain explorer, and Chimney for network participation. The QoS protocol challenges providers based on response time, while the privacy protocol enables secure data sharing. Züs supports hybrid and multi-cloud architectures, allowing users to improve regulatory compliance and security requirements.
reai-ida
RevEng.AI IDA Pro Plugin is a tool that integrates with the RevEng.AI platform to provide various features such as uploading binaries for analysis, downloading analysis logs, renaming function names, generating AI summaries, synchronizing functions between local analysis and the platform, and configuring plugin settings. Users can upload files for analysis, synchronize function names, rename functions, generate block summaries, and explain function behavior using this plugin. The tool requires IDA Pro v8.0 or later with Python 3.9 and higher. It relies on the 'reait' package for functionality.
For similar tasks
AirCasting
AirCasting is a platform for gathering, visualizing, and sharing environmental data. It aims to provide a central hub for environmental data, making it easier for people to access and use this information to make informed decisions about their environment.
airgradient_esphome
ESPHome yaml files for AirGradient devices to maintain the research and accuracy of AirGradient sensors, while also gaining the benefits of ESPHome/HomeAssistant for easy to use switches, buttons, configurations, and dashboards. Maintains the ability to also send data to the AirGradient Dashboard, which can also be disabled/removed to keep all data local.
AIR-1
AIR-1 is a compact sensor device designed for monitoring various environmental parameters such as gas levels, particulate matter, temperature, and humidity. It features multiple sensors for detecting gases like CO, alcohol, H2, NO2, NH3, CO2, as well as particulate matter, VOCs, NOx, and more. The device is designed with a focus on accuracy and efficient heat management in a small form factor, making it suitable for indoor air quality monitoring and environmental sensing applications.
xiaomi_airpurifier
This repository contains a custom component for Home Assistant that integrates various Xiaomi Mi Air Purifier and Xiaomi Mi Air Humidifier models. It provides detailed support for different devices, including power control, preset modes, child lock, LED control, favorite level adjustment, and various attributes monitoring. The custom component offers a more extensive range of supported devices compared to the official Home Assistant component, with additional features and device compatibility. Users can easily set up and configure their Xiaomi air purifiers and humidifiers within Home Assistant for enhanced control and monitoring.
AireLibre
AireLibre is a community response to the need for freely, collaboratively, and decentralized air quality information. It includes projects like Red Descentralizada de Aire Libre (ReDAL), Linka, Linka Firmware, LinkaBot, AQmap, and Android/iOS apps. Users can join the network with a sensor communicating with Linka. Materials and tools are needed to build a sensor. The initiative is decentralized and open for community collaboration. Users can extend or add projects to AireLibre. The license allows for creating personal networks. AireLibre is not for professional/industrial/scientific/military use, and the sensors are not calibrated in Switzerland.
air-quality-info
Air Quality Info is a PHP-based page that displays current PM10 and PM2.5 measurements from Sensor.Community-compatible devices. It features a clean interface, stores records in MySQL, renders graphs with ChartJS, supports multiple devices, offers locale support, and functions as a Progressive Web App. The project setup involves creating directory structures, setting permissions, and starting Docker containers. The admin dashboard is accessible at http://aqi.eco.localhost:8080/, while the Air Quality Info pages use a specific naming schema. The project is supported by Nettigo Air Monitor, Sensor.Community, and a forum thread in Polish.
homeassistant-midea-air-appliances-lan
This custom component for Home Assistant adds support for controlling Midea air conditioner and dehumidifier appliances via the local area network. It provides integration for various Midea appliances, allowing users to control settings such as humidity levels, fan speed, and more through Home Assistant. The component supports multiple protocols and entities for different appliance models, offering a comprehensive solution for managing Midea appliances on the local network.
For similar jobs
airgradient_esphome
ESPHome yaml files for AirGradient devices to maintain the research and accuracy of AirGradient sensors, while also gaining the benefits of ESPHome/HomeAssistant for easy to use switches, buttons, configurations, and dashboards. Maintains the ability to also send data to the AirGradient Dashboard, which can also be disabled/removed to keep all data local.






