Skip to content

Commit e7d5b6e

Browse files
Fmstratjesserockz
Fmstrat
and
jesserockz
authored
[sen5x] Update Nox defaults and lint page (#5176)
Co-authored-by: Jesse Hills <[email protected]>
1 parent cb43850 commit e7d5b6e

File tree

1 file changed

+98
-75
lines changed

1 file changed

+98
-75
lines changed

‎content/components/sensor/sen5x.md

Lines changed: 98 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,13 @@ params:
77
image: sen54.jpg
88
---
99

10-
The `sen5x` sensor platform allows you to use your Sensirion [SEN50](https://sensirion.com/products/catalog/SEN50/), [SEN54](https://sensirion.com/products/catalog/SEN54/) and [SEN55](https://sensirion.com/products/catalog/SEN55/) Environmental sensor ([datasheet](https://sensirion.com/media/documents/6791EFA0/62A1F68F/Sensirion_Datasheet_Environmental_Node_SEN5x.pdf)) sensors with ESPHome.
10+
The `sen5x` sensor platform allows you to use your Sensirion
11+
[SEN50](https://sensirion.com/products/catalog/SEN50/),
12+
[SEN54](https://sensirion.com/products/catalog/SEN54/) and
13+
[SEN55](https://sensirion.com/products/catalog/SEN55/) Environmental sensor
14+
([datasheet](https://sensirion.com/media/documents/6791EFA0/62A1F68F/Sensirion_Datasheet_Environmental_Node_SEN5x.pdf))
15+
sensors with ESPHome.
16+
1117
The [I²C Bus](#i2c) is required to be set up in your configuration for this sensor to work.
1218
This sensor supports both UART and I²C communication. Only I²C communication is implemented in this component.
1319

@@ -19,156 +25,173 @@ sensor:
1925
- platform: sen5x
2026
id: sen54
2127
pm_1_0:
22-
name: " PM <1µm Weight concentration"
23-
id: pm_1_0
24-
accuracy_decimals: 1
28+
name: PM <1µm Weight concentration
2529
pm_2_5:
26-
name: " PM <2.5µm Weight concentration"
27-
id: pm_2_5
28-
accuracy_decimals: 1
30+
name: PM <2.5µm Weight concentration
2931
pm_4_0:
30-
name: " PM <4µm Weight concentration"
31-
id: pm_4_0
32-
accuracy_decimals: 1
32+
name: PM <4µm Weight concentration
3333
pm_10_0:
34-
name: " PM <10µm Weight concentration"
35-
id: pm_10_0
36-
accuracy_decimals: 1
34+
name: PM <10µm Weight concentration
3735
temperature:
38-
name: "Temperature"
39-
accuracy_decimals: 1
36+
name: Temperature
4037
humidity:
41-
name: "Humidity"
42-
accuracy_decimals: 0
38+
name: Humidity
4339
voc:
44-
name: "VOC"
45-
algorithm_tuning:
46-
index_offset: 100
47-
learning_time_offset_hours: 12
48-
learning_time_gain_hours: 12
49-
gating_max_duration_minutes: 180
50-
std_initial: 50
51-
gain_factor: 230
52-
temperature_compensation:
53-
offset: 0
54-
normalized_offset_slope: 0
55-
time_constant: 0
56-
acceleration_mode: low
57-
store_baseline: true
58-
address: 0x69
59-
update_interval: 10s
40+
name: VOC
41+
nox:
42+
name: NOX
6043
```
6144
6245
## Configuration variables
6346
64-
- **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm. Readings in µg/m³.
47+
- **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm.
48+
Readings in µg/m³.
6549
6650
- All options from [Sensor](#config-sensor).
6751
68-
- **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm. Readings in µg/m³.
52+
- **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm.
53+
Readings in µg/m³.
6954
7055
- All options from [Sensor](#config-sensor).
7156
72-
- **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm. Readings in µg/m³.
57+
- **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm.
58+
Readings in µg/m³.
7359
7460
- All options from [Sensor](#config-sensor).
7561
76-
- **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm. Readings in µg/m³.
62+
- **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm.
63+
Readings in µg/m³.
7764
7865
- All options from [Sensor](#config-sensor).
7966
8067
- **auto_cleaning_interval** (*Optional*): Reads/Writes the interval in seconds of the periodic fan-cleaning.
8168
82-
- **temperature** (*Optional*): Temperature.Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models.
69+
- **temperature** (*Optional*): Temperature.Note only available with Sen54 or Sen55. The sensor will be ignored on
70+
unsupported models.
8371
8472
- All options from [Sensor](#config-sensor).
8573
86-
- **humidity** (*Optional*): Relative Humidity. Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models.
74+
- **humidity** (*Optional*): Relative Humidity. Note only available with Sen54 or Sen55. The sensor will be ignored on
75+
unsupported models.
8776
8877
- All options from [Sensor](#config-sensor).
8978
90-
- **voc** (*Optional*): VOC Index. Note only available with Sen54 or Sen55. The sensor will be ignored on unsupported models.
91-
92-
- **algorithm_tuning** (*Optional*): The VOC algorithm can be customized by tuning 6 different parameters. For more details see [Engineering Guidelines for SEN5x](https://sensirion.com/media/documents/25AB572C/62B463AA/Sensirion_Engineering_Guidelines_SEN5x.pdf)
93-
94-
- **index_offset** (*Optional*): VOC index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
95-
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hour
96-
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
97-
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Zero disables the gating. Allowed values are in range 0..3000. The default value is 180 minutes
98-
- **std_initial** (*Optional*): Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-todevice variations. Allowed values are in range 10..5000. The default value is 50.
99-
- **gain_factor** (*Optional*): Gain factor to amplify or to attenuate the VOC index output. Allowed values are in range 1..1000. The default value is 230.
79+
- **voc** (*Optional*): VOC Index. Note only available with Sen54 or Sen55. The sensor will be ignored on
80+
unsupported models.
81+
82+
- **algorithm_tuning** (*Optional*): The VOC algorithm can be customized by tuning 6 different parameters.
83+
For more details see [Engineering Guidelines for SEN5x](https://sensirion.com/media/documents/25AB572C/62B463AA/Sensirion_Engineering_Guidelines_SEN5x.pdf)
84+
85+
- **index_offset** (*Optional*): VOC index representing typical (average) conditions.
86+
Allowed values are in range 1..250. The default value is 100.
87+
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the VOC algorithm offset from the
88+
history in hours. Past events will be forgotten after about twice the learning time.
89+
Allowed values are in range 1..1000. The default value is 12 hour
90+
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the VOC algorithm gain from the history
91+
in hours. Past events will be forgotten after about twice the learning time.
92+
Allowed values are in range 1..1000. The default value is 12 hours.
93+
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator
94+
during high VOC index signal). Zero disables the gating. Allowed values are in range 0..3000.
95+
The default value is 180 minutes
96+
- **std_initial** (*Optional*): Initial estimate for standard deviation. Lower value boosts events during
97+
initial learning period, but may result in larger device-to-device variations.
98+
Allowed values are in range 10..5000. The default value is 50.
99+
- **gain_factor** (*Optional*): Gain factor to amplify or to attenuate the VOC index output.
100+
Allowed values are in range 1..1000. The default value is 230.
100101
101102
- All other options from [Sensor](#config-sensor).
102103
103104
- **nox** (*Optional*): NOx Index. Note: Only available with Sen55. The sensor will be ignored on unsupported models.
104105
105-
- **algorithm_tuning** (*Optional*): The NOx algorithm can be customized by tuning 5 different parameters.For more details see [Engineering Guidelines for SEN5x](https://sensirion.com/media/documents/25AB572C/62B463AA/Sensirion_Engineering_Guidelines_SEN5x.pdf)
106-
107-
- **index_offset** (*Optional*): NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
108-
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hour
109-
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the NOx algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
110-
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Zero disables the gating. Allowed values are in range 0..3000. The default value is 180 minutes
111-
- **std_initial** (*Optional*): The initial estimate for standard deviation parameter has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 50.
112-
- **gain_factor** (*Optional*): Gain factor to amplify or to attenuate the VOC index output. Allowed values are in range 1..1000. The default value is 230.
106+
- **algorithm_tuning** (*Optional*): The NOx algorithm can be customized by tuning 5 different parameters.
107+
For more details see [Engineering Guidelines for SEN5x](https://sensirion.com/media/documents/25AB572C/62B463AA/Sensirion_Engineering_Guidelines_SEN5x.pdf)
108+
109+
- **index_offset** (*Optional*): NOx index representing typical (average) conditions.
110+
Allowed values are in range 1..250. The default value is 1.
111+
- **learning_time_offset_hours** (*Optional*): Time constant to estimate the NOx algorithm offset from the
112+
history in hours. Past events will be forgotten after about twice the learning time. The default value is 12 hour
113+
- **learning_time_gain_hours** (*Optional*): Time constant to estimate the NOx algorithm gain from the history
114+
in hours. Past events will be forgotten after about twice the learning time.
115+
Allowed values are in range 1..1000. The default value is 12 hours.
116+
- **gating_max_duration_minutes** (*Optional*): Maximum duration of gating in minutes (freeze of estimator
117+
during high NOx index signal). Zero disables the gating. Allowed values are in range 0..3000.
118+
The default value is 720 minutes
119+
- **std_initial** (*Optional*): The initial estimate for standard deviation parameter has no impact
120+
for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command.
121+
This parameter must always be set to 50.
122+
- **gain_factor** (*Optional*): Gain factor to amplify or to attenuate the VOC index output.
123+
Allowed values are in range 1..1000. The default value is 230.
113124
114125
- All other options from [Sensor](#config-sensor).
115126
116-
- **store_baseline** (*Optional*, boolean): Stores and retrieves the baseline VOC and NOx information for quicker startups. Defaults to `true`
117-
- **temperature_compensation** (*Optional*): These parameters allow to compensate temperature effects of the design-in at customer side by applying a custom temperature offset to the ambient temperature.
127+
- **store_baseline** (*Optional*, boolean): Stores and retrieves the baseline VOC and NOx information for
128+
quicker startups. Defaults to `true`
129+
- **temperature_compensation** (*Optional*): These parameters allow to compensate temperature effects of the
130+
design-in at customer side by applying a custom temperature offset to the ambient temperature.
118131

119132
The compensated ambient temperature is calculated as follows:
120133

121134
```c++
122135
T_Ambient_Compensated = T_Ambient + (slope * T_Ambient) + offset
123136
```
124137

125-
Where slope and offset are the values set with this command, smoothed with the specified time constant. The time constant is how fast the slope and offset are applied. After the specified value in seconds, 63% of the new slope and offset are applied.
126-
More details about the tuning of these parameters are included in the application note [Temperature Acceleration and Compensation Instructions for SEN5x.](https://sensirion.com/media/documents/9B9DE2A7/61E957EB/Sensirion_Temperature_Acceleration_and_Compensation_Instructions_SEN.pdf)
138+
Where slope and offset are the values set with this command, smoothed with the specified time constant.
139+
The time constant is how fast the slope and offset are applied. After the specified value in seconds,
140+
63% of the new slope and offset are applied.
141+
More details about the tuning of these parameters are included in the application note
142+
[Temperature Acceleration and Compensation Instructions for SEN5x.](https://sensirion.com/media/documents/9B9DE2A7/61E957EB/Sensirion_Temperature_Acceleration_and_Compensation_Instructions_SEN.pdf)
127143

128144
- **offset** (*Optional*): Temperature offset [°C]. Defaults to `0`
129145
- **normalized_offset_slope** (*Optional*): Normalized temperature offset slope. Defaults to `0`
130146
- **time_constant** (*Optional*): Time constant in seconds. Defaults to `0`
131147

132148
- **acceleration_mode** (*Optional*): Allowed value are `low`, `medium` and `high`. (default is `low` )
133149

134-
By default, the RH/T acceleration algorithm is optimized for a sensor which is positioned in free air. If the sensor is integrated into another device, the ambient RH/T output values might not be optimal due to different thermal behavior.
135-
This parameter can be used to adapt the RH/T acceleration behavior for the actual use-case, leading in an improvement of the ambient RH/T output accuracy. There is a limited set of different modes available.
136-
Medium and high accelerations are particularly indicated for air quality monitors which are subjected to large temperature changes. Low acceleration is advised for stationary devices not subject to large variations in temperature
150+
By default, the RH/T acceleration algorithm is optimized for a sensor which is positioned in free air.
151+
If the sensor is integrated into another device, the ambient RH/T output values might not be optimal
152+
due to different thermal behavior.
153+
This parameter can be used to adapt the RH/T acceleration behavior for the actual use-case, leading in an
154+
improvement of the ambient RH/T output accuracy. There is a limited set of different modes available.
155+
Medium and high accelerations are particularly indicated for air quality monitors which are subjected to large
156+
temperature changes. Low acceleration is advised for stationary devices not subject to large variations in temperature.
137157

138158
- **address** (*Optional*, int): Manually specify the I²C address of the sensor.
139159
Defaults to `0x69`.
140160

141-
{{< note >}}
142-
The sensor needs about a minute "warm-up". The VOC and NOx gas index algorithm needs a number of samples before the values stabilize.
143-
144-
{{< /note >}}
161+
> [!NOTE]
162+
> The sensor needs about a minute "warm-up". The VOC and NOx gas index algorithm needs a
163+
> number of samples before the values stabilize.
145164

146165
## Wiring
147166

148167
The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.25mm pitch. The cable needs this connector:
149168

150169
{{< img src="jst6pin.png" alt="Image" width="50.0%" class="align-center" >}}
151170

152-
To force the sensor into I²C mode, the SEL pin (Interface Select pin no.5) must be shorted to ground (pin no.2). Pin 6 is not used.
171+
To force the sensor into I²C mode, the SEL pin (Interface Select pin no.5) must be shorted to ground (pin no.2).
172+
Pin 6 is not used.
153173

154174
For better stability, the SDA and SCL lines require suitable pull-up resistors.
155175

156176
## Automatic Cleaning
157177

158-
When the module is in Measurement-Mode an automatic fan-cleaning procedure will be triggered periodically following a defined cleaning interval. This will accelerate the fan to maximum speed for 10 seconds to blow out the accumulated dust inside the fan.
178+
When the module is in Measurement-Mode an automatic fan-cleaning procedure will be triggered periodically following
179+
a defined cleaning interval. This will accelerate the fan to maximum speed for 10 seconds
180+
to blow out the accumulated dust inside the fan.
159181

160182
- Measurement values are not updated while the fan-cleaning is running.
161183
- The cleaning interval is set to 604,800 seconds (i.e., 168 hours or 1 week).
162184
- The interval can be configured using the Set Automatic Cleaning Interval command.
163185
- Set the interval to 0 to disable the automatic cleaning.
164186
- A sensor reset, resets the cleaning interval to its default value
165-
- If the sensor is switched off, the time counter is reset to 0. Make sure to trigger a cleaning cycle at least every week if the sensor is switched off and on periodically (e.g., once per day).
187+
- If the sensor is switched off, the time counter is reset to 0. Make sure to trigger a cleaning cycle at least
188+
every week if the sensor is switched off and on periodically (e.g., once per day).
166189
- The cleaning procedure can also be started manually with the `start_autoclean_fan` Action
167190

168-
The Sen5x sensor has an automatic fan-cleaning which will accelerate the built-in fan to maximum speed for 10 seconds in order to blow out the dust accumulated inside the fan.
169-
The default automatic-cleaning interval is 168 hours (1 week) of uninterrupted use. Switching off the sensor resets this time counter.
170-
171-
{{< anchor "start_autoclean_fan_action" >}}
191+
The Sen5x sensor has an automatic fan-cleaning which will accelerate the built-in fan to maximum speed for 10
192+
seconds in order to blow out the dust accumulated inside the fan.
193+
The default automatic-cleaning interval is 168 hours (1 week) of uninterrupted use. Switching off the sensor resets
194+
this time counter.
172195

173196
## `sen5x.start_fan_autoclean` Action
174197

0 commit comments

Comments
 (0)