You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Breaking Changes
In the 2.x release of these configurations, some breaking changes are introduced
* See previous 1.x release breaking changes if coming from earlier versions
* Changed `name_add_mac_suffix` to false by default. This will no longer add the MAC address to the end of the device name. Assists ESPHome in properly detecting new device as Online without a static IP. Can be changed to `true` if desired. Ensure all devices have unique `name:` fields if `false`.
* Changed the variable names in the `substitutions:` section to have them match the ESPHome parameters they are used with.
* Changed to `config_version:` substitution name for a shorter name
* Disabled Upload to AirGradient Dashboard by default, but able to flip the switch in HomeAssistant to enable if desired
## Changes
* Added Display Contrast slider to dim the display
* Added device_class to the PMSx005 sensors to have them properly reflect in the HomeKit integration if supported ([Forum Link](https://forum.airgradient.com/t/airgradient-one-customized-mallocarray-esphome-display/1328/7?u=mallocarray))
* Added optional Factory Reset switch that is disabled by default. Can be enabled in HomeAssistant and used if desired
* Added optional `diagnostic.yaml` package with extra sensors about the ESP device itself, including temperature and free
* Added optional `sensor_bme680.yaml` package to support the BME680 module if desired
* Added `dashboard_import` to assist discovery of new devices installed with the pre-compiled .bin files
Copy file name to clipboardExpand all lines: README.md
+52-24Lines changed: 52 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,18 +4,29 @@ ESPHome yaml files for AirGradient devices to maintain the research and accuracy
4
4
5
5
## Breaking Changes
6
6
7
-
In the 1.x release of these configurations, some breaking changes are introduced
7
+
In the 2.x release of these configurations, some breaking changes are introduced
8
8
9
-
* The devicename has been shortened from "airgradient-*" to "ag-". This matches the Friendly Name convention and results in a shorter overall devicename. You may keep yours at the longer full name if desired, but for the Open Air, the name became longer than allowed
10
-
* Substitution entry for "friendly_devicename" has been renamed to "friendly_devicename" to better match it's use case instead of the legacy use
11
-
* The name of the CO2 sensor has been changed to just "CO2" from the previous "Senseair S8 CO2" to shorten overall sensor name length and match other sensors that are named for what they are measuring and not the name of the sensor itself. This will result in a new sensor registered to your device in HomeAssistant and the previous one will be "Unavailable". You may need to update any graphs or other dashboard entries with the new CO2 entry
12
-
* New switch added to enable/disable Automatic Background Calibration of the Senseair S8 CO2 sensor. If previously disabled, on the first install of the 1.x config, it will be enabled again. Disable after installation if desired.
9
+
* See previous 1.x release breaking changes if coming from earlier versions
10
+
* Changed `name_add_mac_suffix` to false by default. This will no longer add the MAC address to the end of the device name. Assists ESPHome in properly detecting new device as Online without a static IP. Can be changed to `true` if desired. Ensure all devices have unique `name:` fields if `false`.
11
+
* Changed the variable names in the `substitutions:` section to have them match the ESPHome parameters they are used with.
12
+
* Changed to `config_version:` substitution name for a shorter name
13
+
* Disabled Upload to AirGradient Dashboard by default, but able to flip the switch in HomeAssistant to enable if desired
14
+
15
+
## Changes
16
+
17
+
* Added Display Contrast slider to dim the display
18
+
* Added device_class to the PMSx005 sensors to have them properly reflect in the HomeKit integration if supported ([Forum Link](https://forum.airgradient.com/t/airgradient-one-customized-mallocarray-esphome-display/1328/7?u=mallocarray))
19
+
* Added optional Factory Reset switch that is disabled by default. Can be enabled in HomeAssistant and used if desired
20
+
* Added optional `diagnostic.yaml` package with extra sensors about the ESP device itself, including temperature and free
21
+
* Added optional `sensor_bme680.yaml` package to support the BME680 module if desired
22
+
* Added `dashboard_import` to assist discovery of new devices installed with the pre-compiled .bin files
13
23
14
24
## Features
15
25
16
26
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)
17
27
18
28
- Compact single page display by default with all relevant sensor readings
29
+
- Display Contrast slider to dim the display
19
30
- Enable different pages of information to be shown on the OLED display, or leave the default of a single page with all relevant information
20
31
21
32
@@ -52,9 +63,9 @@ Copy the .yaml file from the main folder for your model and place it in the `con
52
63
53
64
> 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
54
65
55
-
> Note: setting `add_mac_suffix: "true"` allows for multiple devices on your network at the same time and report as unique entries, but it can cause ESPHome to not detect devices as Online after installing, since ESPHome is looking for only the `devicename:` field and the actual device name has the MAC address added to the end.
66
+
> Note: setting `add_mac_suffix: "true"` allows for multiple devices on your network at the same time and report as unique entries even if your `name:` field is duplicated, but it can cause ESPHome to not detect devices as Online after installing, since ESPHome is looking for only the `name:` field and the actual device name has the MAC address added to the end
56
67
>
57
-
> One way to resolve this is to change `add_mac_suffix: "false"` so the devicename will match exactly. If you have multiple devices, make sure to change the `devicename: `field to be unique for each device
68
+
> One 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 the `name: `field to be unique for each device
58
69
>
59
70
> Another alternative is to add a static IP to the wifi configuration and configure ESPHome to ping the device by IP instead of hostname
60
71
>
@@ -73,12 +84,6 @@ Copy the .yaml file from the main folder for your model and place it in the `con
73
84
> dns1: 192.168.1.1
74
85
> ```
75
86
76
-
#### Using local packages
77
-
78
-
By 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 and replace `github://MallocArray/airgradient_esphome/packages` with `!include packages`
Install a compiled file to your device all with just a browser and USB cable, no ESPHome install required.
@@ -90,8 +95,6 @@ Save the appropriate .bin file and go to [https://web.esphome.io/](https://web.e
90
95
91
96
### Full YAML file
92
97
93
-
Configuration files reference other packages files, making for a very modular configuration, but requires looking at multiple files to see the entire picture.
94
-
95
98
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.
96
99
97
100
Copy the full config file to your personal ESPhome config file and customize as desired, then install to your device.
@@ -101,7 +104,7 @@ Copy the full config file to your personal ESPhome config file and customize as
101
104
If all original sensors (PMS5003, Senseair S8, SHT4x) are connected, configuration files should be ready
102
105
If some sensors are not installed, comment or remove the associated sections under `packages:`
103
106
104
-
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 `pm_2.5: !include packages/sensor_pms5003_extended_life.yaml`
107
+
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`
105
108
106
109
> See [PMSX003 Particulate Matter Sensor — ESPHome](https://esphome.io/components/sensor/pmsx003.html#sensor-longevity) for more information
107
110
@@ -113,9 +116,35 @@ wifi:
113
116
password: 123456123456
114
117
```
115
118
116
-
To modify other components, download the modify the associated packages file and modify as desired and update the packages reference to use the !include method mentioned in the Installation section. You may also use the [Extend](https://esphome.io/guides/configuration-types.html#extend) option to make minor modifications without editing the packages file.
119
+
## Modification
120
+
121
+
#### Using local packages
117
122
118
-
Several packages are available in the `packages` folder that can be added or removed as needed. For example, the display package includes configuration for multiple pages of information that can be enabled or disabled, or you may wish to change to the package that has a single page to avoid extra switches in HomeAssistant or if you know you won't be using the other pages and want to save on flash memory space.
123
+
By 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`
Rather than download an individual package and update the reference to it, you may also use the [Extend](https://esphome.io/guides/configuration-types.html#extend) option to make minor modifications without editing the packages file. This only works for items with and `id:` defined
135
+
136
+
> 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
137
+
>
138
+
> ```
139
+
> binary_sensor:
140
+
> - id: !extend config_button
141
+
> pin:
142
+
> number: D7
143
+
> ```
144
+
145
+
#### Adding other packages
146
+
147
+
Several additional packages are available in the `packages` folder that can be added or removed as needed. For example, the display package includes configuration for multiple pages of information that can be enabled or disabled, or you may wish to change to the package that has a single page to avoid extra switches in HomeAssistant or if you know you won't be using the other pages and want to save on flash memory space.
119
148
120
149
## Additional Information
121
150
@@ -126,15 +155,14 @@ MQTT support has been mentioned in the AirGradient forums several times. ESPHom
126
155
127
156
Several more features are planned to be added to this repo
128
157
129
-
- [ ] Support for Open Air without CO2 sensor
158
+
- [ ] Support for Open Air without CO2 sensor (Model: O-1PPT)
130
159
- [ ] Explore options for disabling display/LED during certain times (May be differed to HomeAssistant Automations)
131
160
- [ ] Standardize font on AirGradient Basic display to match Pro
132
161
- [ ] Reduce number of fonts used in the multi_page package
133
162
- [ ] Open Sans displays a consistent height, but some characters, such as F and 0 are mismatched, the left side is double line thick while right is single line
134
163
- [ ] Poppins Light is consistent thickness, but numbers are taller than letters, giving a mismatched height
135
164
- [ ] Add GitHub actions to automatically build updated .bin files as needed
136
-
137
-
* [ ] Add support for esp32_improv and improv_serial
- [X] Add support for esp32_improv and improv_serial (improv_serial not supported with this board and used pins. esp32_improv uses 30% of available flash memory and is nearly full)
Copy file name to clipboardExpand all lines: packages/airgradient_d1_mini_board.yaml
+12-5Lines changed: 12 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,13 @@
1
1
2
2
esphome:
3
-
name: "${devicename}"
4
-
friendly_name: "${friendly_devicename}"
5
-
name_add_mac_suffix: ${add_mac_suffix} # Set to false if you don't want part of the MAC address in the name
3
+
name: "${name}"
4
+
friendly_name: "${friendly_name}"
5
+
name_add_mac_suffix: ${name_add_mac_suffix} # Set to false if you don't want part of the MAC address in the name
6
+
6
7
project:
7
8
name: mallocarray.airgradient
8
-
version: "$ag_esphome_config_version"
9
-
min_version: 2023.7.0
9
+
version: "$config_version"
10
+
min_version: 2023.12.0
10
11
11
12
esp8266:
12
13
board: d1_mini
@@ -41,3 +42,9 @@ i2c:
41
42
sda: D2
42
43
scl: D1
43
44
frequency: 400kHz # 400kHz eliminates warnings about components taking a long time other than SGP40 component: https://github.com/esphome/issues/issues/4717
Copy file name to clipboardExpand all lines: packages/airgradient_esp32-c3_board.yaml
+16-5Lines changed: 16 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,21 @@
1
1
2
2
esphome:
3
-
name: "${devicename}"
4
-
friendly_name: "${friendly_devicename}"
5
-
name_add_mac_suffix: ${add_mac_suffix} # Set to false if you don't want part of the MAC address in the name
3
+
name: "${name}"
4
+
friendly_name: "${friendly_name}"
5
+
name_add_mac_suffix: ${name_add_mac_suffix} # Set to false if you don't want part of the MAC address in the name
6
+
6
7
project:
7
8
name: mallocarray.airgradient
8
-
version: "$ag_esphome_config_version"
9
-
min_version: 2023.7.0
9
+
version: "$config_version"
10
+
11
+
min_version: 2023.12.0
10
12
11
13
esp32:
12
14
board: esp32-c3-devkitm-1
13
15
16
+
# esp32_improv: # Uses around 30% of available flash space due to loading BLE stack
17
+
# authorizer: none
18
+
14
19
# Enable logging
15
20
# https://esphome.io/components/logger.html
16
21
logger:
@@ -41,3 +46,9 @@ i2c:
41
46
sda: GPIO7 # Pin 21
42
47
scl: GPIO6 # Pin 20
43
48
frequency: 400kHz # 400kHz eliminates warnings about components taking a long time other than SGP40 component: https://github.com/esphome/issues/issues/4717
0 commit comments