Sensor Element Implementation

Many Element implementations for sensors require the same functionality regarding timing and using properties and actions. The abstract SensorElement offers a base class that the specific Element implementations can derive from.

These sensor elements enable reading values from a sensor chip on a specific time interval. When new values could be retrieved these are emitted to other elements using actions.

On the board of the device in the Web UI the actual sensor values are shown as well.

The HomeDing library supports a collection of common sensor chips:

Analog Element supports reading analog values from the input pins having a ADC converter functionality.
Dallas Element supports the DS18B20 aka. Dallas Temperature sensor.
DHT Element supports the DHT11, DHT22 and AM2302 temperature+humidity sensors.
AM2320 Element supports the AM2302 temperature+humidity sensor.
SHT20 Element supports the SHT2x high precision temperature and humidity sensors.
BMP280 Element supports the BMP280 temperature and absolute barometric pressure sensor.
BMP680 Element supports the BME680 temperature, humidity, pressure and gas resistance sensor.
PMS Element supports the PMS5003 sensor by plantdata to count micro particles in the air.
INA219 Element using the INA219 power consumption chip.
INA226 Element using the INA219 power consumption chip.
SCD4x Element supports the scd4x CO2 Sensors.

Common Sensor Implementation

To simplify the implementation of sensors like these there is a special Element with some common functionality available. It is used as a base class for Elements that implement the data exchange with a special sensor chip.

Using a sensor often requires to get data probes on a regular basis e.g. every minute or every 5 minutes. Waiting for the next timeslot to take a probe is implemented by defining the readtime property on any element configuration.

Only the 2 functions GetProbe() and SendValues() need to be implemented instead of the loop() function.

Element Configuration

From the base Sensor Element implementation the following properties are available for configuration:

readTime – Time between 2 probes being fetched from the sensor. Default value is 1m.

resendTime – The current values of the probe are resent after this specified time even when not changing.

warmupTime – This time is waited after powering the sensor on the first start or after a reset before the first data is fetched. The default time is set to 3 seconds.

restart – This property can be set to true to enable an automated restart when the sensor was not responding data.

From the base element implementation the following properties are available for configuration:

title – Caption text for the element. Used by the element specific cards on the dash boards.

description – A line of text that gives a short description of the device used in the web UI.

room – The location of the device.

loglevel – This property holds the element specific log level. The default value is LOGGER_LEVEL_ERR == 1.

startup – This property can be used to start the element using a different initialization phase. Possible values are “sys”, “net”, “time”. See The Startup sequence.

Get Sensor Data

bool GetProbe(&values);

When deriving from the SensorElement class the GetProbe(&values) function will be called when time has come.

This function will be called similar to the loop() function as long as it returns false to indicate that retrieving the data has not been completed. This may be required when reading a sensor includes waiting for the sensor being available or data being transmitted to the board.

When returning true the data retrieval is assumed to be completed. The data has to be returned by using the passed string parameter.

When returning true and an empty string back it is assumed that the sensor cannot be reached and this will end the current data retrieval.

Sending Actions With Sensor Data

void SendValues(&values);

The SendValues() function will be called with the latest retrieved data and when actions are defined the sensor specific element will send them out.

The state of the element also needs to be updated.

Detect non changing values

The data returned by the GetProbe() function will be compared against the last retrieved values. If there is no difference no action will be sent immediately.

Resend values after some time

When data from the sensor has not changed it may be necessary to trigger the actions from time to tome e.g. to inform remote elements about the actual values.

By specifying the resendtime property the resent values are sent even when not changed.