Tab5 Home Assistant HMI Demo

This tutorial shows how to turn your Tab5 into a simple Home Assistant Human Machine Interface (HMI).

We`ll use several entities in this demo, mainly a temperature/humidity sensor (Unit ENV-Pro), a RGB light (Unit NeoHEX) and a IR Remote Climate entity.

For basic configurations in ESPHome (additional microcontrollers may required, in our case, we used Atom EchoS3R as host platform for our sensors, light and IR Remote climate):

• Unit ENV-Pro
• Unit NeoHEX
• IR Remote Climate

Preparations

• A Home Assistant host
• Install and enable the ESPHome Builder add-on in Home Assistant
• Ensure you have added above entities in your home assistant.

Open ESPHome Builder in Home Assistant, create an empty configuration file.

• Click NEW DEVICE button at the right bottom.

• Click CONTINUE

• Select Empty Configuration

• Fill a name (Optional)

• Click EDIT on the newly generated configuration

Then, copy the contents of tab5-ha-hmi.yaml to your configuration file.

Modify the network and api information if you need, like create a api key:

api:
  encryption:
    key: "Your_Encryption_Key"

Then, click Save and Install, select Manual download

After which it will generate the code and compile the project.

When compile is successful, select the Factory format to download the firmware.

Upload firmware

Open the browser and upload with ESPHome Web

Click CONNECT and select your device.

Then, click INSTALL and select the firmware previously downloaded. Hit INSTALL again, it will upload the firmware.

Upon successful upload, the device will reset and boot automatically.

HMI Integration

Once the device is booted, it will connect to the Wi-Fi network previously defined, and you should be able to discover the device in Settings -> Devices & services.

Click Add to add the Tab5 into your Home Assistant. The API encryption key may required for authentication.

Example dashboard of Tab5

Allow Tab5 to perform Home Assistant Action

When finishing integrating the device, you will likely see a issue that needed repair in Settings

Check the detail

The problem suggest that Tab5 is trying to access the Home Assistant entities and modify attributes, but Home Assistant stopped the action by default.

Solution：

Locate Tab5 in Settings -> Device & services -> ESPHome

Click the cog icon on top right corner, tick Allow the device to perform Home Assistant actions

Then, click Submit

That should give you the liberty to control entities in your configurations.

HMI Usage

Mainly the UI contents are organized by pages, there are 3 pages at the moment. The dashboard page display some simple information. Light page for specific light control, climate page allow you to control your air conditioner.

You will find these UI designs and interactions are similar with Home Assistant dashboard. Except to achieve this would cost more time on a embedded device using LVGL.

Click the Light icon button on the left sidebar, you will see a demo light.

Tap the icon button inside this card, you can toggle the light.

Tap the blank area in the card, a modal will open for more controls, for examples, the brightness and RGB color of the light

Click the Climate button on the left sidebar, there will be a demo air conditioner.

Tap the Spinbox + and - button, it will increase/decrease the target temperature of the AC. But this will not change the working state (On/Off/Cool...).

Tap the blank area of the Climate card, a modal will open and you can change working mode, fan mode and target temperature.

Configuration Modifications

This part shows how to modify the configurations, you may try adding your own Light/Climate entity into HMI. Please refer to the below links for more information.

• Remote light button Introduced how to add LVGL button and control the remote light.

• Toggle state icon button Advance version of Remote light, LVGL UI will change according to light state.

• Light brightness slider Introduced how to draw a LVGL Slider widget and bind the brightness of the light.

• Native API Component Introduced how to control entities through homeassistant.action, it also includes a RGB color demo

• Climate control Introduced how to create a LVGL Spinbox and control climate entities like Air Conditioner/Heater

• Home Assistant Text Sensor A special Text Sensor that was used to poll entities's states and attributes.

• Home Assistant Binary Sensor A special Binary Sensor that was used to poll the Binary Sensor's readings in Home Assistant

• Home Assistant Sensor A special sensor that was used to poll the Sensor's readings in Home Assistant.

Light

Below is an example of configuring a Light component.

In LVGL (These definitions can be found in tab5-lvgl.yaml), we draw some widgets like Icon Button, Slider and a customized Color Palette. Before you begin, make sure your light entity has been integrated into Home Assistant (make sure you can control the light within Home Assistant).

In main configuration file, there were serveral text_sensor defined:

text_sensor:
  - platform: homeassistant
    id: demo_light
    entity_id: light.unit_neo_hex_unit_neohex
    on_value:
      then:
        - lvgl.widget.update:
            id: xxx
            ...
        
        - lvgl.label.update:
            id: xxx
            ...

  - platform: homeassistant
    id: demo_light_brightness
    entity_id: light.unit_neo_hex_unit_neohex
    attribute: brightness
    on_value:
      - lvgl.slider.update:
          id: xxx
          ...

      - lvgl.label.update:
          id: xxx
          ...
  
  - platform: homeassistant
    id: demo_light_color
    entity_id: light.unit_neo_hex_unit_neohex
    attribute: rgb_color
    on_value:
      ...
  ...

By default, the text_sensor has a automation on_value, it was triggered when new values were ready from Home Assistant. We can write our lvgl actions for UI updates as the demo showed.

And LVGL UI could control the light through homeassistant.action within the event trigger:

# Use a icon button to toggle the light
  ...
- button:
    styles: card_sm_icon_btn
    id: demo_light_btn
    ...
    widgets:
      - label:
          id: demo_light_label
          ...
          text: "\U000F18DE"
          align: CENTER
    on_short_click:
      - homeassistant.action:
          action: light.toggle
          data:
            entity_id: light.unit_neo_hex_unit_neohex
  ...
# Use a slider to control light brightness
- slider:
    min_value: 0
    max_value: 255
    id: light_slider
    ...
    on_release:
      - homeassistant.action:
          action: light.turn_on
          data:
            entity_id: light.unit_neo_hex_unit_neohex
            brightness: !lambda return int(x);
      ...

Different LVGL support different triggers, you can refer to ESPHome - LVGL Widgets

Knowing the information above, if you wish to control your own Light:

• Update entity_id, corresponding attribute (if) in text_sensor. If you wish to update the LVGL at the same time, additional steps may required.

• Change the entity_id under homeassistant.action -> data node, in the LVGL event trigger. Make sure the Home Assistant action exist.

Sensor

The same is for Sensor entities, mainly it publish float states (of course there were others like ON/OFF). Therefore, in your configurations, if you want to know a specific sensor value, point out a entity_id:

sensor:
  ...
- platform: homeassistant
    id: cur_temp
    entity_id: sensor.temperature
    on_value:
      - lvgl.label.update:
          id: xxx
  
  - platform: homeassistant
    id: cur_humi
    entity_id: sensor.env_iv_kit_humidity
    on_value:
      - lvgl.label.update:
          id: xxx

  - platform: homeassistant
    id: cur_co2
    entity_id: sensor.env_iv_kit_co2_equivalent
    on_value:
      - lvgl.label.update:
          id: xxx
  ...

So Tab5 can access the sensor readings, on_value automation also provided for updating LVGL UI.

Should you wish to use other sensors, modify the entity_id.

Climate

For climate, you can find these text_sensor, and corresponding attributes of a climate entity.

text_sensor:
# AC Information
  - platform: homeassistant
    id: ac_state
    entity_id: climate.unit_neo_hex_central_ac
    on_value:
      - lvgl.label.update:
          id: xxx

      - lvgl.dropdown.update:
          id: xxx
    ...
  - platform: homeassistant
    id: ac_fan_mode
    entity_id: climate.unit_neo_hex_central_ac
    attribute: fan_mode
    on_value:
      - lvgl.label.update:
          id: xxx
      - lvgl.dropdown.update:
          id: xxx
    ...
  
  - platform: homeassistant
    id: ac_temp
    entity_id: climate.unit_neo_hex_central_ac
    attribute: temperature
    on_value:
      - lvgl.spinbox.update:
          id: xxx
    ...

As mentioned above, you can get these values and update your LVGL UI.

Use LVGL UI to control Climate component:

  ...
- arc:
  id: ac_arc
  adjustable: true
  ...
  # Prevent frequent use of 'on_value'
  # In case of performance issue
  on_release:
    - lambda: id(set_ac_temp)->execute(float(x) / 10.0f);
  ...

- dropdown:
id: ac_mode_dd
...
dir: TOP
selected_text: "Off"
options:
  - Heat_Cool
  - Heat
  - Cool
  - Dry
  - Only Fan
  - "Off" # In case conversions
on_change:
  ...
  - lambda: id(set_ac_state)->execute(x);

- dropdown:
  id: fan_mode_dd
  dir: TOP
  ...
  selected_text: "Auto"
  options:
    - High
    - Medium
    - Low
    - Auto
  on_change:
    ...
    - lambda: id(set_ac_fan_mode)->execute(x);

The control was encapsulated as a script, which was defined in tab5-scripts.yaml

 # This script was used on dropdown widget
  # to set ac state (ON/OFF/COOL/HEAT, etc)
  - id: set_ac_state
    parameters:
      ac_mode_idx: int
    then:
      - homeassistant.action:
          action: climate.set_hvac_mode
          data:
            entity_id: climate.unit_neo_hex_central_ac
            hvac_mode: !lambda return id(hvac_state_table)[ac_mode_idx];
  - id: set_ac_fan_mode
    parameters:
      ac_fan_mode_idx: int
    then:
      - homeassistant.action:
          action: climate.set_fan_mode
          data:
            entity_id: climate.unit_neo_hex_central_ac
            fan_mode: !lambda return id(fan_modes_table)[ac_fan_mode_idx];
  # This script was used on spinbox/arc widget
  # to set the temperature to climate entity
  # it doesn't turn on/off, use the dropdown instead
  - id: set_ac_temp
    parameters:
      temp_value: float
    then:
      - homeassistant.action:
          action: climate.set_temperature
          data:
            entity_id: climate.unit_neo_hex_central_ac
            temperature: !lambda return temp_value;

Change entity_id if you wish to adapt your climate component.