Elements Overview
Elements are implementations of a specific input, output or compute functionality that corresponds to a specific functionality like Sensors, Displays, Light, I/O control and internal control logic. Elements are implemented in the HomeDing library as Components that can be controlled using setup configuration and runtime actions.
There is a Element Sheet availabe as table data.
The following element implementations are available in the current version of the HomeDing library.
Input Elements
Input Elements are used to create an action based on a specific input signal like digital HIGH/LOW or analog signals or values from sensors like movement detectors.
Digital Input Element (digitalin)
The DigitalInElement is used to capture digital input signal and create actions based on level changes. This can e.g. be used to capture actively from buttons and switches but also some sensors offer a digital output as a 0 / 1 value.
Digital Signal Element (digitalsignal)
The DigitalSignalElement is used to handle digital input with short time level changes that might be missed when using the DigitalInput Element. On a changing input a pulse value is created with a defined duration.
Analog Element (analog)
The AnalogElement is used to capture the voltage level from the Analog Input pin with the integrated ADC and to emit corresponding events. It also handles some of the often occurring problems around capturing analog values.
Rotary Element (rotary)
The RotaryElement is used to capture increments and decrements for values using a rotary encoder.
Display Touch Element (touch)
The Display Touch Elements enables detecting touch events by touching a specific area on a display.
Sensor Elements
The sensor elements implement the adoption to a very specific sensor or sensor family. They share some common implementation to allow gathering values on a regular basis and updating other elements or even other boards by sending actions with the current value.
DHT Element (dht)
The DHT Element allows retrieving temperature and humidity values from the DHT11, DHT22 and AM2302 sensors and creates actions when new values are available.
AM2320 Element (am2320)
The AM2320Element allows retrieving temperature and humidity values and creates actions when new values are available.
AHT20 Element (aht20)
The AHT20Element allows retrieving temperature and humidity values from the AHT20 sensors from aosong.
Dallas Element (dallas)
The DallasElement allows retrieving temperature values from DS18B20 aka. Dallas Temperature sensors and creates actions when new values are available.
BME680 Element (bme680)
The BME680Element implements reading the 4 sensor values from a BME680 environment air sensor chip. This sensor can capture temperature, humidity, air pressure and air resistance.
PMS Element (pms)
The PMSElement allows using the laser based air particle and pollution sensor PMS5003 from plantower to report the number of micro particles in the air.
BMP280 Element (bmp280)
The BMP280 Element supports the BMP280 sensor chips for air temperature and air absolute barometric pressure.
BL0937 Element (bl0937)
The BL0937Element has been implemented to support single phase energy monitoring using BL0937, HLW8012 or HJL-01 chips that are used in some retail plugs and switches.
SCD4x Element for CO2 Sensors (scd4x)
The SCD40 and SCD41 sensors from sensirion are available on breakout boards to meassure the CO2 in the air by providing values in ppm units.
More detailed information on sensor implementation can be found in sensor Elements implementation.
Output and Actor Elements
PWMOut Element (pwmout)
The PWMOutElement is used to create a variable PWM signal at the specified output pin. This can be used to drive a LED or a servo motor.
Digital Output Element (digitalout)
The DigitalOutElement is used with the GPIO pins of the board to create a digital output level based on actions sent to the element. This can e.g. be used to switch a LED or relay on/off.
RFCodes Element (rfcodes)
The RFCodes Element is used for sending and receiving RF signals to switching and dimming devices using RF protocols like 433 or 315 MHz.
Single Light Elements
To control a simple light or bulb the Switch Element and Value Element can be used to control on/off and the brightness of LEDs using PWM Out Element or DigitalOut Element.
To control lights, bulbs and LED stripes with colors the following special light elements can be used.
There are special elements to control specific chips or using the PWM capabilities. The Color Element can be used to create a light color value of your choice.
Light Element (light)
The LightElement is used as a base class to control a light by WRGB Value and Brightness. It can control up to 4 PWM GPIO output pins directly for WRGB lights. It is used as a base class for other light elements using a specific chip or protocol.
MY9291 Element (my9291)
The MY9291Element implements the protocol to control the Taiwan Mingyang MY9291 LED driver chip that can be found in some bulbs. It can control 3 or 4 channels of PWM output with a high PWM frequency typically used for RGB and WRGB bulbs.
Color Element (color)
The Color Element allows controlling a color value for a light emitting element using color notations in the xRRGGBB or xWWRRGGBB format and brightness 0…100. A special Web UI is available.
Multiple Light Elements
For LED stripes the Stripe Element provides the base functionality to control a series of LEDs with individual color values and a overall brightness.
The stripes can be controlled from the following elements implementing the specific protocols:
Neopixel board for ESP-01 (neo)
The neo board is a very specific adapter to drive a Neopixel based stripe, wheel or array using a ESP-01 board. The ESP-01 boards are available with ESP8266 and ESP32-C3 chips.
APA102 Element (apa102)
The APA102 Element implements using LED Stripes and LED panels based on the apa102 chip and protocol and provides some color animations and transitions.
P9813 Element (p9813)
The P9813Element implements the protocol to control the P9813 LED driver chip also known as Groove chainable LED.
Light Sensors
Light Sensors enable retrieving the intensity and other parameters from environmental light.
BH1750 Element (bh1750)
The BH1750Element allows retrieving the environment light intensity from BH1750 Ambient Light based sensors using the i2c bus for communication
Logic, Data and Calculation Elements
Button Element (button)
The ButtonElement allows detecting multiple button press gestures like single short click, double click and long press.
Switch Element (switch)
The SwitchElement switches a boolean output value and is used to toggle the state of a boolean values to on/off values by a single action.
Value Element (value)
The ValueElement combines receiving modifying actions for a numeric integer value and sending actions on changing the value. This can also be used as a base class for more specific elements like the switch or calc element.
Menu Element (menu)
The MenuElement allows controlling multiple values or switches by using joystick inputs and rotary encoder.
Log Element (log)
The LogElement enables storing timestamp based values e.g. from a sensor into a local file to be analyzed or displayed later by the Web UI.
Logic elements implement using on/off values expressed as 1/0 values. See Calc Abstract Element
AND Element (and)
The AND Element combines multiple logic input values to a single output value. The output value will be true only when all input values are true.
OR Element (or)
The OR Element combines multiple logic input values to a single output value. The output value will be true only when at least one of the input values is true.
ADD Element (add)
The ADD Element sums up multiple input values to create a single output value.
Map Element (map)
The MapElement creates actions based on an in-bound value and range definitions.
Reference Element (reference)
The ReferenceElement allows creating actions by comparing an incoming value with a reference value.
Scene Element (scene)
The Scene Element sends a series of actions triggered by a single incoming action. They can be send out step by step using a defined delay or by actions.
Select Element (select)
The SelectElement is used to choose one of many options with keys and a values. When selecting one of the options a key action and a value action is dispatched.
Display Elements
The HomeDing library supports local attached displays but also works fine without a local display.
Display SSD1306 Element (display/ssd1306)
The DisplaySSD1306 Element allows connecting a pixel based OLED display based on a SSD1306 chip.
Display LCD Element (display/lcd)
The DisplayLCD Element implements the display using Monochrome LCDs based on HD44780 chips. The display is connected by using the PCF8574 I2C chip to control the direct input lines of the display.
DisplayMAX7219 Element (display/max7219)
The DisplayMAX7219 Element implements a larger display by using LED 8x8 led displays matrixes based on MAX7219 controller chips.
Display SSD1306 Element (display/ssd1306)
The DisplaySSD1306 Element allows connecting a pixel based OLED display based on a SSD1306 chip.
Display SH1106 Element (display/sh1106)
The DisplaySH1106 Element allows connecting a pixel based OLED display based on a SH1106 chip.
Display Item Elements
On the displays several Elements can be used to display data, text and visuals:
DisplayText Element (display/text)
The DisplayTextElement allows sending a pure text value to the display and show it at a specified position as text including a prefix and postfix. The value can be changed by using an action.
DisplayCircle Element (display/circle)
The DisplayCircle Element allows showing a circle with a stroke and fill color. This can be used to visualize a boolean value on the display and show it at a specified position as a shallow or filled circle. The value can be changed by using an action.
DisplayLine Element (display/line)
The DisplayLineElement enables drawing a simple fixed line on a display supporting pixel based graphics.
DisplayRect Element (display/rect)
The DisplayRect Element allows showing a rectangular with a stroke and fill color. This can be used to visualize a boolean value on the display and show it at a specified position as a shallow or filled rectangle. The value can be changed by using an action.
More detailed information on displays and related elements can be found in displays.
One Value Display Elements
These Elements can be used to display a single value.
DisplayMAX7219 Element (max7219)
The DisplayMAX7219 Element implements a larger display by using LED 8x8 led displays matrixes based on MAX7219 controller chips.
TM1637 Element (tm1637)
The TM1637 is a chip that allows using 7-segment displays up to 6 digits.
Time related Elements
Time Element (time)
The time element creates actions with the current local time as value.
DSTime Element (dstime)
The DSTime Element gets the local time from a DS3231 chip that contains a high accurate clock running independently from the main board and processor.
NTPTime Element (ntptime)
The NTPTimeElement can retrieve the local time from an external NTP server using the ntp protocol on the internet.
Schedule Element (schedule)
The ScheduleElement creates on and off events based on the current local time.
Alarm Element (alarm)
The AlarmElement creates a single action when reaching a defined time of day. This can be used e.g. for wakeup signals.
Timer Element (timer)
The TimerElement creates events based on a one-time or cyclic timing pattern.
More detailed information on time element and time related implementation can be found in time elements implementation.
System Elements
Device Element (device)
The DeviceElement allows configuration of the behavior at the device level and conbfigures features offered by the board class.
OTA Element (ota)
The OTA Element allows to upload new firmware using the wireless network - Over The Air (OTA). The update doesn’t work in safemode.
Simple Service Discovery Protocol (SSDP) Element (ssdp)
The SSDPElement allows specifying the properties to send SSDP messages to the local network so the device can be discovered by Plug & Play Services.
Network Elements
Things based on the HomeDing library are network connected by default as they integrate a web server and web services.
The Network Elements extend the base functionality to connect to other devices and services over the network using different protocols. Service elements interact with services to get or publish data using actions.
Remote Element (remote)
The Remote Element allows sending actions over the network to other elements in HomeDing devices using http GET requests.
MQTT Element (mqtt)
The MQTTElement enables publishing values to a MQTT Sever using the mqtt protocol.
WeatherFeed Element (weatherfeed)
The WeatherFeedElement pulls information on the weather forecasts for a specific location from the internet and dispatches actions with specific data items.
Storage related Elements
SD Card Element (sd)
The SDElement uses the SPI bus to connect a SD card and makes the files available for reading and writing in the /sd folder.
SD MMC card Element (sdmmc)
The SDMMCElement implements access to the file system on a SDMMC card on ESP32 processors and boards.
Audio related Elements
The Audio Elements can be used to create / control audio related devices and chips.
Tone Element (audio/tone)
The Tone Element allows creating sound using the Arduino tone function.
Radio Element (audio/radio)
The Radio Element allows to control FM radio chips that are connected to the board via i2c bus. The Radio Element is part of the Radio Example.
Audio Element (audio/audio)
The Audio Element enables audio streaming and audio processing in a background task. The Audio Element is part of the WebRadio Example.
Other Elements
You can find some more elements in the examples folder.
These implementations are for special purpose or are still experimental cases but are published already maybe with some restricted functionality. These element are part of the DevDing example and Probe example.
Diag Element (diag)
The DiagElement offers web endpoints to get access to internal operating data and additional diagnose information.
INA219 Element (ina219)
The INA219 is a current and voltage sensor that uses the I2C bus for communication that can measure voltages up to 26V and current in various ranges.
INA226 Element (ina226)
The INA226 is a current and voltage sensor that uses the I2C bus for communication that can measure voltages up to 26V on high-side or low-side and current in various ranges .
Web UI Elements
The elements starting with a web prefix in their name are only known to the Web UI implementation but are not part of the firmware- The intention is to enrich and customize the Web UI dashboard with elements like presets and macros.
WebButton Element (webbutton)
The WebButton Element adds a button the Web UI of the board and allows sending actions directly from the web UI without a corresponding active element in the device.