User guide

Controlling The Device

Info Screen - hold any button for 2 s
Settings Menu - hold any two buttons together for 5 s

Firmware v2.2.1 and below:

Info Screen - hold any button for 2 s
Settings Menu - hold any button for 5 s

Home Assistant

You can configure most of the settings directly in Home Assistant.

To get to the device's page in Home Assistant, click settings in the left side bar, then open Devices & Services, move to the Devices tab and click on the name you gave your Home Buttons during setup.

Home Assistant Device Page

Configure Button Icons

In the Controls card, enter the name of the icon, that you want to be shown on the e-paper display. Icons will be updated next time you press a button or on the next sensor update interval.

You can choose any of the Material Design Icons. Enter the icon name in the label field in the format mdi:{icon name}. For example, mdi:lightbulb-auto-outline.

Icons are downloaded from a Github repository. For that purpose an internet connection is required. Once downloaded, the icons are stored permanently on the device. If you do not wish to have Home Buttons connected to the internet, you can set up the icons once and then disable internet access.

Configure Button Actions

To configure button actions, click "+" on the Automations card, select one of the buttons and set up an automation with Home Assistant's editor.

Home Assistant Triggers

The expected delay from a button being pressed to the automation being triggered is around 1 second (depending on your network).

Configure Button Actions

To configure button actions, click "+" on the Automations card, select one of the buttons and set up an automation with Home Assistant's editor.

Home Assistant Triggers

The expected delay from a button being pressed to the automation being triggered is around 1 second (depending on your network).

Configure Sensor Publish Interval

The device uses deep sleep to preserve battery. It wakes up every few minutes to measure temperature and humidity and publish the data to MQTT topics. You can set the publishing interval with a slider on the Controls card. The range is from 5 to 60 minutes. The default is 30 minutes.

Be aware, that this setting greatly impacts the battery life. The advertised battery life of 1-2 years is achievable with the interval set to 30 minutes (the default) or greater.

Settings Menu

Open the Settings Menu by holding any two buttons together for 5 seconds. The menu will show the following options:

- Setup
- Wi-Fi Setup
- Restart
- Close settings menu

Restart triggers publishing MQTT discovery message and icon download. The first time after a restart, Wi-Fi connection will take a few seconds longer.

Device Info

You can see details of you device like software version, hardware revision and IP address in the Device Info menu. To access it, hold for 2 seconds.

Factory Reset

To perform a factory reset, hold for 10 seconds. Home Buttons will restart and all user settings will be reset to default. You will have to set up the device again.

Info Screen

Info screen displays current temperature, humidity and battery percentage.

"Info Screen

Bring it up by pressing any button for 2 seconds. Home Buttons will automatically revert to showing button labels after 30 seconds. Or do that manually by pressing any button again.

Setup

Setup allows you to change connection settings and button labels. Home Buttons establishes a web interface accessible within the network it is already connected to.

Begin setup by going to Settings Menu and pressing . Home Buttons will display instructions for connecting to a web interface. Scan the QR code or enter the local IP into a web browser.

Setup Page

Change Wi-Fi settings

Click Configure WiFi to change Wi-Fi connection settings. Select a network, enter the password and click save. Wait a few seconds and then press any button to exit setup. Home Buttons will connect to the newly selected Wi-Fi network.

Change MQTT settings & Button labels

Click Setup to change MQTT settings or button labels. A page with the following parameters will open:

Device Name - Name of your device as it will appear in Home Assistant.
MQTT Server - IP address of your MQTT broker. Usually the same as IP of your Home Assistant server.
MQTT Port - Port used by MQTT broker. The default is usually 1883.
MQTT User - MQTT user name (can be empty if not required by broker).
MQTT Password - MQTT password (can be empty if not required by broker).
Base Topic - MQTT topic that will be prepended to all topics used by Home Buttons. The default is homebuttons.
Discovery Prefix - Home Assistant parameter for MQTT discovery. The default is homeassistant. Leave that unchanged if you haven't modified Home Assistant's configuration.
Static IP - Optional. IP of Home Buttons. Must be outside the DHCP address range of your router.
Gateway - Optional. The IP address of your router.
Subnet Mask Optional. Usually 255.255.255.0.
Primary DNS Server - If left empty, Gateway IP will be used.
Secondary DNS Server - If left empty, 1.1.1.1 will be used.
Button {1-4} Label - Label that will be displayed next to each button.
Temperature Unit - Either C - Celsius or F - Fahrenheit.

When done, click Save. Device will exit the setup and display button labels.

If MQTT connection is not successful, MQTT error will be displayed and Home Buttons will return to welcome screen. You can start the setup again by pressing any button. Please make sure to enter correct MQTT parameters.

Wi-Fi Setup

If Home Buttons becomes inaccessible on the local network due to changed Wi-Fi settings, you can restart the Wi-Fi setup at any time.

Open Settings Menu by holding any two buttons together for 5 s and press . Wi-Fi hotspot will be established and connection instructions will be displayed.

Home Buttons will establish a Wi-Fi hotspot. Connect to it by scanning the QR code on the display or manually connecting to Wi-Fi network and entering the password.

The Wi-Fi password is password123.
After connecting to Home Buttons Wi-Fi with your device, a captive portal will pop up automatically. If it doesn't, open the web browser and navigate to any web page. You will be redirected to the captive portal.
Click Configure WiFi and wait a few seconds for a list of networks to appear.
Select your network, enter the password and click Save.

Home Buttons will disable the hotspot and connect to your Wi-Fi network in a few seconds. Wi-Fi CONNECTED will appear on display.

If connection is not successful, Wi-Fi error will be displayed and Home Buttons will return to welcome screen. You can start Wi-Fi setup again by pressing any button. Please make sure to enter the password correctly.

Display a Custom Message

A custom message can be shown on the e-paper display by inputting it in the Show Message field on the device page in Home Assistant.

You can also use the Show Message entity in automations:

action:
  - device_id: 966128a1b5d43dd1b22424cd0a77d44c
    domain: text
    entity_id: text.home_buttons_265cbf_show_message
    type: set_value
    value: "Test \n Message"

Message will not be wrapped automatically. You must include line breaks \n manually.

Alternatively, you can display a message by publishing a retained payload to the {base_topic}/{device_name}/cmd/disp_msg topic. The message will be displayed when the device wakes up on button press or sensor publish. You can clear the message by pressing any button.

Example Home Assistant publish service call YAML:

service: mqtt.publish
data:
  topic: homebuttons/HB Mini 123/cmd/disp_msg
  payload: "Line 1\nLine 2"
  retain: true

mosquitto_pub example:

mosquitto_pub -h <broker_host> -t <topic> -m $'Line 1\nLine 2'

Schedule Wakeup

You can schedule the next wakeup using the Schedule Wakeup entity. This is useful if you are changing labels dynamically based on state of other devices.

For example: If some action you trigger with a button press is not instant, but takes some time to complete, you can schedule the next wakeup after the action is completed. This way the label will be updated sooner, instead of having to wait for the next sensor publish wakeup.

Example Home Assistant automation YAML:

alias: schedule test
description: ""
mode: single

# Change button label immediately on press
trigger:
  - platform: device
    domain: mqtt
    device_id: 966128a1b5d43dd1b22424cd0a77d44c
    type: button_short_press
    subtype: button_3
    discovery_id: HBTNS-2301-001-265CBF button_3
condition: []
action:
  - device_id: 966128a1b5d43dd1b22424cd0a77d44c
    domain: text
    entity_id: text.home_buttons_265cbf_button_3_label
    type: set_value
    value: _OPENING...

# Schedule next wakeup after 15 seconds
  - device_id: 966128a1b5d43dd1b22424cd0a77d44c
    domain: number
    entity_id: number.home_buttons_265cbf_schedule_wakeup
    type: set_value
    value: 15

# Simulate some action that takes 10 seconds
  - delay:
      hours: 0
      minutes: 0
      seconds: 10
      milliseconds: 0

# Change button label after action is completed
  - device_id: 966128a1b5d43dd1b22424cd0a77d44c
    domain: text
    entity_id: text.home_buttons_265cbf_button_3_label
    type: set_value
    value: _OPENED

You can also schedule wakeup by publishing a message to the {base_topic}/{device_name}/cmd/schedule_wakeup topic. The message payload should be the number of seconds to wait before the next wakeup. The minimum value is 5 seconds.

Set labels dynamically

You can set button labels dynamically from Home Assistant automations or by publishing a MQTT message.

Home Assistant

Use a text.set_value service call to set the label of a button. The entity ID is text.{device_name}_button_{button_number}_label.

service: text.set_value
data:
  value: "mdi:dog"
target:
  entity_id: text.my_buttons_button_1_label

You can use templates to set the label based on the state of other entities:

service: text.set_value
data:
  value: >
    {% set current_time = states("sensor.time") %}
    {% if current_time < "12:00" %}
      mdi:dog
    {% else %}
      mdi:cat
    {% endif %}
target:
  entity_id: text.my_buttons_button_1_label

You must use this service call. Device actions do not support templates.

MQTT

Publish a message to the {base_topic}/{device_name}/cmd/button_{button_number}_label topic. The message payload should be the label you want to set. The label will be updated on the next wakeup.

Opening The Case

If you need to remove or replace the battery, or perform a manual firmware upgrade, you have to open the case. The back cover can stay mounted to the wall during the procedure.

Open the back cover by pressing the tab on the bottom of the device.
Replace the back cover by aligning it first at the top and then pressing it down until it clicks.

Replace back cover