hass-smartbox

Home Assistant integration for Haverland (and other brands) heating smartboxes.

Installation

Using HACS (Recommended)

1. Add this repository to your custom repositories
2. Search for and install "Smartbox" in HACS.
3. Restart Home Assistant.

Manually Copy Files

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 (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called smartbox.
4. Download all the files from the custom_components/smartbox/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant

Finally

Configuration

You will need the following items of information:

• Name of your reseller
• Your username and password used for the mobile app/web app.

If there is an issue during the process or authentication, the errors will be displayed.

Additional Options

You can also specify the following options (although they have reasonable defaults)

Consumption history options

We are currently getting the consumption of device through the API and we inject it in statistics and TotalConsumption sensor

• start : we will get the last 3 years of consumption and set the option to auto.
• auto : every hour, we get the last 24 hours.
• off : stop the automatic collect. We will still update the sensor every hour.

Reseller logo

By default, each sensor has in own icon depends on the type of the sensor. You can activate this option to display the logo of the reseller instead.

Timedelta between update power

If you have a Dedicated energy monitor, we get the current power each 60 seconds by default. You can update this time with this option.

Note

Be carefull with this option, reduce the number little by little to see if any instability occurs.

Websocket transport

Status updates arrive over one of two transports (see the library's api-notes.md "Transports — socket_io vs ws_user"):

• ws_user (the vendor web apps' channel): ONE connection for the whole account. Its server-side proxy PINGs keep the session supervised — the periodic "Server has stopped communicating" aborts of the legacy transport disappear. The server cuts the socket at the access token's 4-hour expiry (~4-second outage while it reconnects with a fresh token); that is the steady state, by design.
• socket_io (legacy): a separate connection per device, used automatically when the account's API host does not serve ws_user (only api-lhz is verified to). Setup probes the endpoint once and falls back transparently on a deterministic rejection; transient probe trouble (a 5xx-ing or unreachable host) retries via the normal ConfigEntryNotReady retry instead — a transport verdict is never inferred from transient trouble. The active transport is visible in Settings → Devices → diagnostics as runtime_data.transport.

The transport is chosen by SMARTBOX_WS_BACKEND in custom_components/smartbox/const.py — set it to "socket_io" to force the legacy per-device connections.

Features

Heaters (climate)

Heater node types (htr, acm and htr_mod) are modelled as Home Assistant Climate entities.

• htr and acm (accumulator) nodes
  • Supported modes: 'manual' and 'auto'
  • Supported presets: 'home' and 'away'
• htr_mod
  • Supported modes: 'manual', 'auto', 'self_learn' and 'presence'
  • Supported presets: 'comfort', 'eco', 'frost', 'schedule', 'self_learn' and 'activity'

Every heater also exposes the 'away' and 'boost' presets (boost where the device supports it) and the OFF HVAC mode. The modes and presets for htr_mod heaters are mapped as follows:

htr_mod mode	htr_mod selected_temp	HA HVAC mode	HA preset
manual	comfort	HEAT	COMFORT
	eco	HEAT	ECO
	ice	HEAT	FROST
auto	*	AUTO	SCHEDULE
self_learn	*	AUTO	SELF_LEARN
presence	*	AUTO	ACTIVITY

The target temperature step is 0.5 °C / 1.0 °F. On the fw-1.9 htr family, the maximum target temperature is clamped to the node's max_stemp_limit when the device advertises one.

Node availability

Heaters the box reports as unreachable (node-level sync_status: "lost") show as Unavailable on all of their entities, so a heater whose power is cut is visible at a glance. Entities come back as Available shortly after the node answers again.

Sensors

• Temperature (current)
• Power (including PMO dedicated energy monitors)
• Duty cycle (htr nodes)
• Total consumption (energy, with recorder statistics import - see Consumption)
• Charge level (acm nodes)
• Boost end time (timestamp)
• Schedule (enum, per heater node)
• RTC clock drift (box-level, refreshed every 5 minutes)

Binary sensor

One box-level connectivity sensor (per-node connectivity is shown through the climate entities' availability instead).

Switches

• Box level: away mode, "no power limit"
• Per node: window mode, true radiant, boost, child lock (keypad lockout), maximum temperature limit (remembers the last non-zero limit across Home Assistant restarts)

Numbers

• Box power limit (0 = no limit, max 60000)
• Per node: boost temperature, boost duration, away offset, maximum temperature, and programme temperatures (frost / eco / comfort, where the device reports them)

Selects

• Per node: radiator priority (low / medium / high, fw-1.9 family only) — the device takes it into account itself when enforcing the box power limit

Dedicated energy monitor

The PMO devices are available including the power limit entity.

Consumption

The smartbox API is only giving the hourly consumption from a start and an end period of time. You can't have real time consumption of a device and this consumption is always increasing.

At every beginning of an hour, during around 15/20 minutes, the API do not provide data for the current hour. So we always get a period of two hour to have at least some data, and get the most recent one to not have drop of consumption.

Every 15 minutes, we are updating data sensor with the most recent data. You are able to see the consumption directly into the history graph of the sensor.

But to be sure we ensure the right data to the right hour, we also get the last 24 hours and upsert these data into statistics to avoid time difference and some data drop.

Tip

If you don't want to upsert these 24 hours, you have to set the option to off.

History

The first time we create a config entry (or when the option of the config entry is set to start) we get the last 3 years of consumption. As it is not possible to add it directly to the sensor data, we insert it into the statistics of the sensor. So it let the energy dashboard working with the current and back history.

Tip

If you want to reset all the data, you have to set the option to start.

FAQ

There is negative consumption in the energy dashboard

There might be a huge negative consumption in your energy dashboard. The consumption history should deal with it. But sometimes it didn't work. You have two options:

• Settings the option to start : it will force load all data.
• Go to , select the total consumption entity, outliers and patch the negative value with 0.

My Reseller is not present in the list

If you can't see your reseller which is using a smartbox you have to do an Reseller Github issue.

Debugging

Diagnostics

If there is an error and raise an issue in Github issue, please attach the diagnostics of the entry :

• Go on
• Click on the three dots of the config entry
• Download diagnostics

System health

You can see if all the smartbox component are available here

Logs

Debug logging can be enabled by increasing the log level for the smartbox custom component and the underlying smartbox python module in the Home Assistant configuration.yaml:

 logger:
   ...
   logs:
     custom_components.smartbox: debug
     smartbox: debug
   ...

Warning

Currently logs might include credentials, so please be careful when sharing excerpts from logs

See the Home Assistant logger docs for how to view the actual logs. Please file a Github issue with any problems.

Note

The initial version of this integration was made by graham33 but it was not maintained.

Support

Ajtudela

Delmael