Environment - AHT1x/AHT2x/DHT20/AM2301B

.

Plugin details

Type: Environment

Name: AHT1x/AHT2x/DHT20/AM2301B

Status ESP32: COLLECTION A COLLECTION G CLIMATE NEOPIXEL

Status ESP8266: COLLECTION A CLIMATE

GitHub: P105_AHT.ino

Maintainer: sakinit tonhuisman

Used libraries: .

Datasheet: http://www.aosong.com/en/products-40.html http://www.aosong.com/en/products-32.html http://www.aosong.com/en/products-60.html

Description

The AHT10/AHT15/AHT20/AHT21/DHT20/AM2301B sensors provide Temperature and Humidity measurements (factory calibrated), via an I2C bus connection.

Warning

  • The AHT10 and AHT15 devices do sometimes not ‘play nice’ when there are also other I2C devices on the same bus (many complaints can be found on the internet). NB: This may be hardware-, vendor-, or chip-revision-specific.

Because of this peculiarity, other sensors may be more appropriate, like the AHT20/AHT21 also supported by this plugin, or Environment - BMx280, Environment - BME68x, Environment - SI7021/HTU21D, Environment - DHT12 (I2C), Environment - AM2320, Environment - SHT3x or Environment - HDC1000/HDC1008/HDC1010/HDC1050/HDC1080 (I2C).

This plugin tries to avoid such situations (I2C bus lock) by (soft) resetting the sensor if it doesn’t respond for some time.

This plugin also supports the DHT20 and AM2301B sensors, as these are just AHT20 sensors with a specific housing.

Settings

../_images/P105_DeviceConfiguration.png

  • Name: The name for this task, should be unique.

  • Enabled: Allows to enable/disable the device.

I2C Options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the I2C Bus page

  • I2C Address: The address the device is using. The AHT10 sensor allows to select a secondary address by pulling the AO (sometimes marked as A0) pin to high (3.3V) to select the secondary address. That address should then be selected here too. The AHT20/AHT21 based sensors only support a single I2C address, so it will be forced to the default address.

Device Settings

If the plugin is configured for Sensor model AHT1x and other devices configured in a task use the I2C bus, a warning is displayed (see example below) that combining them with this device may cause issues on the I2C bus, resulting in all I2C devices no longer working as intended. This may occur immediately, or only after some time, like 10 minutes or an hour.

../_images/P105_DeviceWarning.png

  • Sensor model Selection of the connected type of hardware. (AHT2x based sensors have a slightly different intialization.)

Available options:

../_images/P105_SensorModelOptions.png

  • AHT1x AHT10/AHT15. These sensor models should better be avoided, as it doesn’t always work with other devices on the same I2C bus.

  • AHT20 An more modern version of the sensor. Use this option also when connecting a DHT20 or AM2301B sensor.

  • AHT21 An more modern version of the sensor, very similar to the AHT20, in a more compact chip package.

When selecting the AHT1x Sensor model, an extra option is made available:

../_images/P105_AHT10_alt_init.png

  • AHT10 Alternative initialization: Some AHT10 clone sensors do not seem to like the regular AHT10/AHT15 initialization sequence. They do however accept a soft reset command. By enabling this checkbox, only the soft reset is sent to the device. Only available for AHT1x devices.

  • Temperature offset Depending on the sensor and the location of the sensor, it may be required to apply some temperature compensation. This can be set in steps of 0.1 degree. This also applies a compensation to the Humidity reading.

Data Acquisition

This group of settings are standard available configuration items.

  • Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.

  • Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.

  • Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)


  • Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

../_images/Task_config_page_Controllers_section.png

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

  • Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.

  • Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.

  • Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).

  • Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.


  • Interval By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.

Values

The names for the values are initially set to a default name, but can be changed if desired. Also, a formula can be entered to re-calculate the value before display/sending to a controller, and the number of decimals can be changed, for Temperature, usually 1 decimal is enough to be displayed (value will be rounded).

Change log

Changed in version 2.0: … changed 2024/12/21 Add temperature offset

changed 2024-12-03 Add alternative initialization option

added 2021-08-01 Moved from ESPEasy PluginPlayground to the main repository.