The openHASP Custom Component simplifies synchronization of objects on one or more openHASP plates with Home Assistant entities.

You need to download it and install it in Home Assistant manually.

Installation~

  1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
  2. If you do not have a custom_components directory there, you need to create it.
  3. In the custom_components directory create a new folder called openhasp.
  4. Download all the files from the custom_components/openhasp/ directory in this repository.
  5. Place the files you downloaded in the new directory you created.
  6. Edit your configuration.yaml file add an entry similar to the example below.
  7. Restart Home Assistant

Using your Home Assustant configuration directory as a starting point you should now also have this:

custom_components/openhasp/__init__.py
custom_components/openhasp/common.py
custom_components/openhasp/const.py
custom_components/openhasp/light.json
custom_components/openhasp/manifest.json
custom_components/openhasp/services.yaml

  Note

We call plate any device running openHASP in your system.

Make sure you have your plates connected to the network and each of them has a unique MQTT topic. Static DHCP or fixed IP are not needed as communication only happes through MQTT.

Configuration~

Example~

To add an openHASP plate to your installation with a sample configuration, upload a pages.jsonl file with the folowing content to your plate first:

{"page":1,"id":1,"obj":"btn","x":0,"y":0,"w":240,"h":30,"text":"openHASP","value_font":22,"bg_color":"#2C3E50","text_color":"#FFFFFF","radius":0,"border_side":0}
{"page":1,"id":2,"obj":"btn","x":10,"y":40,"w":105,"h":90,"toggle":true,"text":"\uE335","text_font":26,"mode":"break","align":1}
{"page":1,"id":3,"obj":"dropdown","x":10,"y":130,"w":160,"h":30,"options":"Apples\nBananas\nOranges\nMelon"}

{"page":0,"id":1,"obj":"label","x":175,"y":5,"h":30,"w":62,"text":"00.0°C","align":2,"bg_color":"#2C3E50","text_color":"#FFFFFF"}

Assuming your plate's configured MQTT topic is plate35, you can add the following to your configuration.yaml file:

openhasp:
  plate_my_room:
    topic: "hasp/plate35"
    path: "/config/openhasp/pages_my_room.jsonl"
    idle_brightness: 35
    objects:
      - obj: "p0b1"  # temperature label on all pages
        properties:
          "text": '{{ states("sensor.my_room_temperature") }}°C'
      - obj: "p1b2"  # light-switch toggle button
        properties:
          "val": '{{ 1 if states("light.my_room") == "on" else 0 }}'
          "text": '{{ "\uE6E8" if is_state("light.my_room", "on") else "\uE335" | e }}'
        event:
          "up":
            - service: homeassistant.toggle
              entity_id: "light.my_room"
      - obj: "p1b3"  # dropdown
        event:
          "changed":
            - service: persistent_notification.create
              data:
                message: I like {{ text }}

Variable definitions~

openhasp: (Required)
The platform identifier. Required once in the configuration, this will activate the custom component.

plate_my_room: (Required)
Your plate identifier. For each plate in your sytem, such an entry is required, has to be unique.

topic: (string) (Required)
The MQTT topic your plate is configured with.

path: (path) (Optional)
Path to a pages.jsonl file containing design for this plate, to be loaded on Home Assistant start and on plate availability (becoming online).
Note: Don't upload any pages.jsonl file to the plate's flash memory at all! This assumes your plate pages are empty at boot. Checkout the services section for requirements to use this.

idle_brightness: (int) (Optional)
The brightness of the screen when idle (before long idle). Numeric value between 1 and 255. Default 25.

objects: (Optional)
Definition of the objects reacting to changes in Home Assistant, or generating events for Home Assistant.

obj: (string) (Required)
The object identifier which we want to integrate with Home Assistant. Its name has the form pXbY where X represents the page where the object is located, and Y represents the id of the object on that page.

properties: (Optional)
List containing the properties of the object which we want to modify based on changes occurring in Home Assistant. In the example above text property gets updated whenever sensor.my_room_temperature changes.

event: (Optional)
List containing the events generated by the object when touched on the screen. These are object-specific and can be observed accurately with an MQTT client. Each event defines a list of services which will be processed in order (like actions list in an automation).

In the example above, when object p1b2 (which is a toggle button) generates the on event, light.my_room will be turned on by the service call light.turn_on as specified in the event config. And similarily when off event comes through MQTT, the light will be turned off by the corresponding service call.

  Note

Any variable coming from the MQTT message can be used between curly brackets and passed to the service call. In the example above when object p1b3 (which is a dropdown selector) generates the changed event, a persistent notification will appear in Home Assistant's Lovelace interface containing the selected text from the object, which was passed over from the MQTT message. See object events for more types of generated events.

Configuration tips~

Multiple plates~

If you have multiple plates you can add them all using different plate identifiers. Their configured topics have to be unique too:

openhasp:
  plate_my_room_1:
    topic: "hasp/plate1"
    objects:
      ...
  plate_my_room_2:
    topic: "hasp/plate2"
    objects:
      ...
  plate_my_room_3:
    topic: "hasp/plate3"
    objects:
      ...

Split configuration~

You can use Home Assistant's split configuration to help better organizing your config files.

Instead of keeping the configuration of all openHASP plates in Home Assistant's main config file, you can keep openHASP config separately, by adding only this to configuration.yaml:

openhasp: !include openhasp.yaml

After this, you can move your openHASP configuration starting with plate_my_room: level to your separate openhasp.yaml file and restart Home Assistant.

Moreover, if you have multiple plates, you can keep each one in a separate config file, to achieve this, make it like:

openhasp: !include_dir_merge_named openhasp_configs/

Create a directory openhasp_configs right near configuration.yaml, and put in it all your plates configuration (only with plate_my_room: level) in separate yaml files and restart Home Assistant.

This component implements some specific services to make interactions with the plate even more comfortable.

Services~

openhasp.wakeup
Wakes up the display when an external event has occurred, like a presence or a PIR motion sensor.

openhasp.next_page
Changes plate to the next page.

openhasp.prev_page
Changes plate to the previous page.

openhasp.change_page
Changes plate directly to the specified page number.

openhasp.clear_page
Clears the contents of the specified page number. If page number not specified, clears all the pages.

openhasp.load_pages
Loads new design from pages.jsonl file from full path.
The file must be located in an authorised location defined by allowlist_external_dirs (in case of hassio /config/ is the directory where Home Assistant's configuration.yaml resides, so in case of a subdirectory called openhasp the full path would be e.g. /config/openhasp/pages.jsonl, and you need to add /config/openhasp/ to your allowlist_external_dirs).

  Warning

The contents of the file are loaded line by line thus "page":X has to be defined for each object.
Unless you clear the page first, the objects will be updated.

Check out the example automations for further information on how to use the services within Home Assistant.