How wisilicalumos/ha-lumos works
1. This repository is a Home Assistant custom integration for Lumos Smart Lighting by WiSilica. Its architectural boundary is clear: Home Assistant talks to the Lumos cloud API, not directly to local devices or a local bridge.
2. The integration lives entirely under custom_components/lumos, which is the standard Home Assistant plugin layout. manifest.json defines it as a custom integration, and the top-level hacs.json plus GitHub workflows show it is packaged for HACS distribution and validated with Home Assistant tooling.
3. Configuration is entry-based, not YAML-based. config_flow.py handles onboarding through Home Assistant’s UI, including the cloud API base URL and account credentials. The README indicates multi-account support, so each config entry represents an independent Lumos account.
4. api.py is the cloud boundary. It is the layer that authenticates with the Lumos backend, retrieves devices/state, and sends control commands. All device control ultimately passes through this module.
5. coordinator.py is the state synchronization core. It likely uses Home Assistant’s data update coordinator pattern to poll the cloud on a fixed interval, refresh device snapshots, and distribute that shared state to all entities. The README’s 30-second sync and configurable polling interval are implemented here or through this layer.
6. Device capability modeling is centralized in device_capabilities.py. This file maps Lumos deviceType values to supported features such as on/off, brightness, RGB, and color temperature. Unknown types are intentionally surfaced via warnings so the integration can be extended without breaking existing devices.
7. light.py is the primary entity platform and represents controllable lighting devices in Home Assistant. Based on the README, it supports brightness, RGB, and tunable-white behavior depending on the capability record for each device.
8. cover.py, binary_sensor.py, and sensor.py indicate additional entity surfaces beyond lights. These platforms likely expose device state, availability, or specialized controls/telemetry where Lumos device models require it. They are separate because Home Assistant treats each entity class as a distinct UI/control surface.
9. The main runtime flow is:
- user adds the integration in Home Assistant,
- config_flow.py creates a config entry,
- api.py authenticates against the Lumos cloud,
- coordinator.py polls and refreshes device data,
- the platform modules create/update entities from that shared dataset,
- user actions in Home Assistant call back through api.py to the cloud.
10. State reconciliation is cloud-poll driven. The README explicitly mentions optimistic updates: the UI updates immediately after a command, then the next coordinator refresh reconciles the entity state with the cloud. That design balances responsiveness with eventual consistency.
11. There is a clear distinction between “command accepted” and “device physically updated.” The README notes the Lumos cloud can accept a command even when the mesh network is the real delivery path. Architecturally, that means the integration only controls and observes the cloud layer; it does not own the downstream mesh delivery guarantees.
12. translations/, strings.json, and the brand assets under brand/brands support Home Assistant’s UI and integration branding. These files are not part of the control path, but they matter for the setup/options experience and marketplace presentation.
13. In diagram terms, the important nodes are: Home Assistant core, Lumos config flow, shared coordinator, Lumos cloud API, and the entity platforms. The main data edge is periodic polling from cloud to coordinator to entities, with command edges flowing from entities back to the cloud.
14. This is a pure integration repository, not an application server or local device daemon. The key architectural decision is that it relies on Home Assistant’s async integration framework and external SaaS/cloud connectivity, with no local broker, message queue, or hardware driver layer in the repo.
Main entry points: coordinator.py Coordinator · device_capabilities.py Capabilities · api.py Cloud API · __init__.py Integration Init
Components 16
Home Assistant
Runtime and integration host
- Home Assistant Core · Hosts the custom integration runtime and entity framework
Lumos Integration
Custom integration under custom_components/lumos
- Config Flow · UI-based setup and account onboarding
custom_components/lumos/config_flow.py - Integration Init · Config-entry startup and wiring for each account
custom_components/lumos/__init__.py - Coordinator · Shared polling and state distribution layer
custom_components/lumos/coordinator.py - Cloud API · Authenticates, fetches devices, and sends commands to Lumos cloud
custom_components/lumos/api.py - Capabilities · Maps Lumos device types to supported features
custom_components/lumos/device_capabilities.py - Lights · Primary lighting entities with brightness and color support
custom_components/lumos/light.py - Covers · Cover-style entities for supported Lumos devices
custom_components/lumos/cover.py - Binary Sensors · Boolean state surfaces for device conditions and availability
custom_components/lumos/binary_sensor.py - Sensors · Telemetry and status entities
custom_components/lumos/sensor.py - Manifest · Declares the Home Assistant custom integration
custom_components/lumos/manifest.json - Strings · Localized setup and entity text
custom_components/lumos/strings.json - Branding · Brand and logo assets for UI presentation
custom_components/lumos/brand - Translations · Localized strings for the integration UI
custom_components/lumos/translations/en.json
Packaging
HACS and validation support
- HACS Pack · HACS metadata and repository packaging
hacs.json - Validation · GitHub workflows for HACS and Home Assistant checks
.github/workflows/hacs.yml
Connections 21
- Home Assistant Core → Config Flow: starts setup · Home Assistant launches the config flow
- Config Flow → Integration Init: creates entry · A successful flow creates a config entry
- Integration Init → Cloud API: builds client · Startup wires the cloud API client for the account
- Integration Init → Coordinator: starts coordinator · Config entry startup creates the shared refresh layer
- Coordinator → Cloud API: polls cloud · Coordinator refreshes device data from Lumos cloud
- Coordinator → Capabilities: classifies devices · Device snapshots are interpreted through capability mapping
- Capabilities → Lights: enables features · Capability records decide light feature support
- Capabilities → Covers: enables features · Capability records decide cover support
- Capabilities → Binary Sensors: enables features · Capability records decide binary sensor support
- Capabilities → Sensors: enables features · Capability records decide sensor support
- Coordinator → Lights: updates state · Entities read the shared coordinator snapshot
- Coordinator → Covers: updates state · Entities read the shared coordinator snapshot
- Coordinator → Binary Sensors: updates state · Entities read the shared coordinator snapshot
- Coordinator → Sensors: updates state · Entities read the shared coordinator snapshot
- Lights → Cloud API: sends commands · User actions are forwarded to the Lumos backend
- Covers → Cloud API: sends commands · Supported cover actions are forwarded to the cloud
- Home Assistant Core → Manifest: loads metadata · Home Assistant discovers the integration through its manifest
- Home Assistant Core → Translations: shows UI text · Home Assistant uses localized strings in setup and entities
- Home Assistant Core → Branding: shows branding · Brand assets support integration presentation
- HACS Pack → Validation: validated by · Packaging is checked by repository workflows
- Manifest → HACS Pack: published with · The integration is distributed as a HACS package