Skip to Content
🚀 We just launched! Please star us on Github!
DocumentationExtensionsDevice Integrations

Device Integrations

Device plugins connect Smart Panel to external smart home platforms and protocols. Each plugin handles device discovery, state synchronization, and command execution — mapping external devices into Smart Panel’s device → channel → property hierarchy.

Most device plugins discover and create devices automatically. You typically only need to provide connection details (host, token, etc.) in the Admin UI under Config → Plugins and the plugin handles the rest.


Available Integrations

PluginProtocolDiscoveryDescription
Home AssistantWebSocketAutomaticImports devices and entities from a Home Assistant instance. Bidirectional real-time sync — state changes and commands flow both ways instantly. Requires a long-lived access token.
Homey SHSLocal API / Socket.IOManual server, automatic device inventoryConnects to Homey Self-Hosted Server for reviewed adoption, real-time synchronization, availability reconciliation, and supported controls. Basic reads/session behavior were verified on SHS 13.4.0; the complete local matrix passed on SHS 13.4.1 over HTTP.
ModbusModbus TCP / RTU over TCPManualReads and switches wired I/O modules (digital inputs, relays, analog inputs, valves) through Modbus TCP devices and RS485 gateways. Built-in templates for known boards, or define the registers yourself.
Shelly NGmDNS / RPCAutomaticDiscovers and controls Shelly Next-Generation devices (Plus, Pro, BLU series) on the local network. No cloud dependency — all communication stays local.
Shelly v1HTTP / CoAPAutomaticSupport for first-generation Shelly devices using the original HTTP and CoAP APIs.
WLEDHTTPAutomaticControls WLED-based LED strips and lights discovered on the local network.
Zigbee2MQTTMQTTAutomaticIntegrates Zigbee devices through a Zigbee2MQTT bridge. Imports all paired devices with their channels and properties.
Third-PartyHTTP RESTManualGeneric API for custom devices. Any application or service can register devices and exchange state data over standard HTTP endpoints. Works with any language or platform.
reTerminalLinux sysfsAutomaticNative hardware integration for SeeedStudio reTerminal (CM4 and DM). Reads built-in sensors (light, accelerometer, CPU temp) and controls LEDs, buzzer, and buttons.

How Plugins Work

All device plugins follow the same pattern:

  1. Discovery — the plugin finds devices on the network (or they are created manually)
  2. Mapping — external device structures are mapped to Smart Panel’s device → channel → property model
  3. Sync — property values are synchronized in real time (via polling, WebSocket, or push)
  4. Commands — actions from the panel display are forwarded to the actual device

Devices created by plugins appear in the Devices section of the admin UI and can be assigned to Spaces, used in Scenes, and displayed on Pages.


Configuration

Each plugin is configured through the Admin UI under Config → Plugins, or via config.yaml. The available settings depend on the specific plugin — typically connection details like host addresses, API tokens, or polling intervals.

Plugins with automatic discovery require minimal configuration — often just enabling the plugin is enough. Homey requires a manual local server URL and API key before its device inventory becomes available. Third-party devices are created individually.

Zigbee2MQTT: value freshness

Virtual devices (for example a virtual thermostat built from radio sensors) and automations only use values that are fresh. Smart Panel treats every message a Zigbee device sends through the bridge as proof that the device is alive, so a sensor that reports the same temperature for hours stays fresh as long as it keeps reporting.

Zigbee2MQTT can provide extra information that makes this more accurate. Smart Panel uses it when it is available and falls back to safe defaults when it isn’t:

Zigbee2MQTT settingWhat it gives Smart PanelWithout it
advanced.last_seen: ISO_8601 (recommended)Every value is timed by the moment the device actually spoke. After a Smart Panel or bridge restart, values of sleeping battery devices keep their real age, so they are usable right away as long as that age is within the freshness limit of the virtual device or automation using them.Values replayed at startup are shown but stay non-fresh until each device reports again (see the startup note below for the limits of this). How long that takes depends on when the device next sends a message.
device_options.retain: true (MQTT connection)The broker keeps each device’s last state, so Smart Panel receives it as soon as it connects, even when Zigbee2MQTT was already running. Combined with last_seen, those values keep their real age.If Smart Panel starts while Zigbee2MQTT is already running, it learns a sleeping device’s state only when that device next reports. If Zigbee2MQTT starts while Smart Panel is connected, Zigbee2MQTT publishes its cached states itself (cache_state_send_on_startup), so retain is not needed for that case. The WebSocket connection receives a snapshot either way.
advanced.cache_state: falsePer-value freshness: a value whose sensor stops reporting goes stale even if the device still reports other values, such as battery.Freshness is per device. Leave cache_state enabled if other consumers of your bridge (for example Home Assistant) rely on full-state messages.
# Zigbee2MQTT configuration.yaml advanced: last_seen: ISO_8601 device_options: retain: true

Smart Panel logs a warning when it connects to a bridge that has last_seen disabled.

Without a usable last_seen, Smart Panel cannot tell a replayed state from a new report by its content. It treats messages as replays while Zigbee2MQTT is still publishing after it connects or the bridge comes online: until no message has arrived for 5 seconds, and at most for 60 seconds. This is a heuristic, not a guarantee. A cached state that reaches Smart Panel after that (possible on a very large network, a slow bridge start, or a delayed connection) is treated as a new report, so that value counts as fresh although the device did not report it.

Enabling last_seen avoids this for every message that carries a valid one, because the value is then timed by the device’s report instead of its arrival. That age is only as accurate as the Zigbee2MQTT host’s clock. A last_seen slightly ahead of Smart Panel’s clock (up to a minute) is treated as the arrival time, so with a gateway clock running ahead an older value can look fresh. Smart Panel ignores a last_seen that is missing, invalid, zero (a device Zigbee2MQTT has never heard from) or more than a minute ahead; such messages fall back to the heuristic above. Keep the clocks of both machines synchronised (NTP).

If you cannot enable last_seen and want to reduce the risk:

  • MQTT connection: set advanced.cache_state_send_on_startup: false, so Zigbee2MQTT does not publish its cached states at startup.
  • WebSocket connection: the Zigbee2MQTT frontend sends a snapshot of all device states whenever Smart Panel connects, regardless of that setting, and no setting turns it off. It is sent right after connecting, so it normally arrives inside the window, but a delayed delivery can still miss it. Use last_seen (or the MQTT connection) if you need the stronger behaviour.

A device that only reports on change and has no periodic reporting configured sends nothing while its value is stable, so its values will eventually be considered stale. Where the device supports it, configure periodic reporting in Zigbee2MQTT with a maximum interval shorter than the freshness limit of the virtual device or automation using it. Some devices (for example the Xiaomi WSDCGQ11LM) do not accept a reporting configuration and report on their own schedule.


What’s Next?

Last updated on