LifeSmart Local Mode#

Overview#

Local mode allows LifeSmart hubs to operate over a direct LAN TCP connection, bypassing cloud connectivity entirely. Instead of the OAPI/WebSocket cloud path, the integration uses LifeSmartLocalTCPClient — a persistent TCP socket client — to communicate with the hub over a custom binary protocol.

The two integration modes are selected in config_flow.py via a CONN_CLASS_LOCAL_PUSH vs CONN_CLASS_CLOUD_PUSH choice 1. Local mode follows a simpler, single-step configuration flow compared to cloud mode.

Setup: Required Configuration Fields#

Local mode requires four fields 2:

During setup, validate_local_input() creates a temporary LifeSmartLocalTCPClient and calls check_login(), which opens a TCP connection (5 s timeout) and verifies credentials. ConfigEntryAuthFailed is raised for bad credentials; ConfigEntryNotReady for network timeouts or OS errors.

Multi-Hub Configuration#

Each hub is a separate Home Assistant config entry, titled "Local Hub (<host>)". There is no limit on entries; repeat the configuration flow for each hub. Each entry maintains its own independent LifeSmartLocalTCPClient instance and background async_connect task 3.

Connection Lifecycle#

async_connect() is the main loop, running as a background HA task:

1. TCP connect — asyncio.open_connection with a 5 s timeout.
2. Login — sends a build_login_packet and parses the ret field. On failure, sets disconnected = True and aborts.
3. Load devices (loading stage) — sends build_get_config_packet, parses the eps dict into self.devices, and sets the device_ready asyncio.Event 4.
4. Live push (loaded stage) — receives _schg state-change pushes. Supports both the 6-part (agt/me/ep/<devid>/m/<idx>) and legacy 5-part (agt/ep/<devid>/m/<idx>) path formats 5.
5. Reconnect — on any socket error, sleeps 5 s and retries from step 1 6.

get_all_device_async() waits on the device_ready event (default 10 s timeout) before returning the device list.

Idle Timeout & Heartbeat#

IDLE_TIMEOUT = 65.0 seconds. During the loaded stage, if no data arrives within this window, a build_get_config_packet is sent as a heartbeat probe. A write failure breaks the loop and triggers reconnect. During login or loading stages, an idle timeout is treated as a hard error and forces immediate reconnect 7.

Protocol Encoding (protocol.py)#

Packets are built by LifeSmartPacketFactory and decoded by LifeSmartProtocol, both in core/protocol.py.

• _pack_value recursively serializes Python objects to binary using type markers (0x02/0x03 booleans, 0x13 enums, 0x12 dicts/lists). enum: prefixed strings are resolved first via REVERSE_KEY_MAPPING (named keys → byte id), then via int(key) for numeric ids like "enum:91".
• decode handles both uncompressed (GL00 header) and gzip-compressed (ZZ00) packets.
• Key packet builders: build_login_packet, build_get_config_packet, build_epset_packet / build_multi_epset_packet for device control.

Known Issue: Numeric Enum ID Regression (Fixed in PR #120)#

A regression in _pack_value caused numeric enum ids like "enum:91" (used in build_get_config_packet) to be sent as the literal UTF-8 string "enum:91" instead of the correct 0x13 + int binary encoding. The local gateway rejected this with err: 'ENADF1:<node>/me/ep:enum:91', causing hub.py:246 to abort with ConfigEntryNotReady 8.

Because login packets use no numeric enum ids, the connection appeared to authenticate successfully — only the subsequent get_config round-trip failed. This was the root cause behind issues #117 and #119.

Fix (merged 2026-06-01): PR #120 added a numeric fallback inside the enum: branch of _pack_value. Versions after v25.07.30 contain the regression; upgrade to the patched build (commit 502e5ac or later) to resolve it.

Unsupported Operations in Local Mode#

The following raise PlatformNotReady because the local TCP protocol has no equivalent API 9:

• Scene list queries
• Room list queries
• IR remote list queries

Hub list queries return only the single connected hub 10.

Key Files#