liebherr2mqtt

Liebherr SmartDevice HomeAPI → MQTT bridge, with Home Assistant style discovery.
Brings a connected Liebherr fridge or freezer into Jeedom, Home Assistant, or anything else that speaks MQTT Discovery — in real time, without polling the cloud.

Why

Liebherr appliances fitted with a SmartDeviceBox are cloud-only in practice. The box does contain a LocalAPI, but Liebherr disables it remotely on consumer appliances — it is only enabled on the SmartModule of their professional ranges. The remaining option is the official SmartDevice HomeAPI, published in beta in April 2025.

Home Assistant has had a first-class integration for it since 2026.3. Jeedom has nothing. This bridge fills that gap, and works for any MQTT-Discovery consumer.

It is built on pyliebherrhomeapi, the library behind Home Assistant's official liebherr integration, rather than on a hand-rolled HTTP client — so it inherits that project's data model, error taxonomy and SSE reconnection logic.

Features

• Real-time, no polling. State changes arrive as a push over Server-Sent Events (/v1/sse/devices/{id}/controls). Liebherr rate-limits the HomeAPI and has been known to block calling IP addresses; this bridge simply does not hammer it. A single full re-read every 15 minutes (configurable, and disableable) acts as a safety net.
• Auto-discovery. Entities appear on their own in Jeedom or Home Assistant, grouped as one device, with proper units, ranges and icons.
• Reconnection-proof. Discovery, states and command subscriptions are replayed on every MQTT (re)connection. This is the failure mode that silently breaks a lot of home-made bridges: with a non-persistent session the broker drops your subscriptions on any disconnect, and a bridge that only subscribes at startup keeps publishing states while quietly ignoring every command.
• Last Will. If the container dies, the appliance's online indicator flips to off by itself.
• Only what your appliance actually has. Entities are built from the controls the device declares, not from a hard-coded model list.

Supported controls

Multi-zone appliances get one entity per zone, suffixed with the zone position.

❌ Door state and door alarms are not available. They are not part of the HomeAPI — the mobile app reads them from a separate, undocumented internal API.

Getting an API key

In the SmartDevice mobile app:

Settings → Become a beta tester → Activate the HomeAPI interface → Generate a new key

⚠️ The key can only be copied once. Copy it before leaving that screen.

Running it

Docker

docker run -d \
  --name liebherr2mqtt \
  --restart unless-stopped \
  -e LIEBHERR_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e MQTT_HOST=192.168.1.10 \
  -e MQTT_USER=mqttuser \
  -e MQTT_PASSWORD=mqttpassword \
  ghcr.io/ripleyxlr8/liebherr2mqtt:latest

Unraid

Install it from Community Applications — open the Apps tab and search for liebherr2mqtt. Every setting is a field in the UI, and the API key field is masked.

The CA template lives in ripleyXLR8/unraid-templates, which is the repository Community Applications indexes.

Configuration

Everything can be set through environment variables, or through a /config/liebherr2mqtt.conf file (see liebherr2mqtt.conf.template). Environment variables win over the file, and the file is entirely optional.

Topics

liebherr/<device>/availability              online | offline
liebherr/<device>/<entity>/state            current value    (retained)
liebherr/<device>/<entity>/set              command
homeassistant/<component>/liebherr_<device>/<entity>/config   discovery (retained)

Jeedom notes

Install the MQTT Discovery plugin, point it at your broker, and the appliance shows up on its own. Two traps worth knowing:

• ⚠️ Add liebherr to the plugin's "data topics" setting. The plugin checks that the root of a discovery message's state topic is in that list, and silently ignores the message otherwise — it merely records the unknown root in discovered_data_topics. Nothing appears, and nothing explains why.
• The plugin renames a command after the discovery device_class, which is why the setpoint here deliberately carries no device_class: it would be created as a second command named "Temperature" instead of "Setpoint".

Home Assistant notes

If you use Home Assistant, prefer its official liebherr integration — it talks to the same API directly, with no broker in between. This bridge is for everything else.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or supported by Liebherr. "Liebherr", "SmartDevice", "BioFresh", "SuperCool" and "SuperFrost" are trademarks of their respective owners.