LHA

LHA (Light Home Automation) is a lightweight, single‑process engine written entirely in Lua that orchestrates home‑automation devices and services through a unified Web of Things (WoT) interface. At its core, the engine hosts a scheduler, an HTTP server powered by luajls, and a logging subsystem that persists property changes in time‑stamped files. This design keeps the runtime footprint under 5 MB, enabling deployment on resource‑constrained hardware such as Raspberry Pi or WD MyCloud, while still supporting full Windows and Linux distributions.

The application exposes a Thing Description JSON API that conforms to the W3C WoT specification, allowing any compliant client—be it a browser, mobile app, or another automation framework—to discover and interact with devices. LHA bridges the gap between heterogeneous protocols (ZigBee via ConBee, Z‑Wave JS, Hue) by providing a unified extension system where each protocol is wrapped in a Lua module. This abstraction lets developers write cross‑protocol automations without worrying about the underlying communication stack.

• Language: Lua 5.4 (embedded interpreter)
• HTTP Server: luajls – a minimal yet extensible Lua‑based web server that serves the WoT API and static assets.
• Scheduler: Lua coroutine‑based event loop that triggers scripts, timers, and device property updates.
• Persistence: Simple file‑based logging; each property change is appended to a CSV‑style log, enabling historical queries without a full database.
• Front‑end: Vue.js 2 for dynamic dashboards, Blockly for visual scripting, and Chart.js/Moment.js for data visualization.
• Extensions: JSON‑defined mapping files that declare device capabilities, property types, and command endpoints. New extensions are loaded at runtime without recompilation.

• Protocol Interoperability: Lua modules for ConBee, Hue Bridge, and Z‑Wave JS.
• Script Engine: Users can author Lua scripts or Blockly blocks that react to property changes, schedule tasks, or trigger external services (e.g., SMS, HTTP callbacks).
• Thing Description API: Full WoT TD support – discovery, read/write operations, event subscriptions.
• Webhooks & Callbacks: HTTP endpoints that external services can POST to, enabling bidirectional integration.
• Extensibility: Developers can add new protocol adapters or custom UI components by extending the JSON mapping and placing Lua modules in the extensions directory.

LHA is a self‑contained binary; no external dependencies or package managers are required. For containerized deployments, the official release can be wrapped in a minimal Docker image (Alpine or Ubuntu slim). The engine runs as a single process, making it straightforward to scale horizontally by deploying multiple instances behind a reverse proxy that handles load balancing and WebSocket connections. For high‑availability, the file‑based log can be mounted on a shared filesystem or streamed to an external time‑series database if required.

• Plugin System: Add new device types by creating a JSON descriptor and an optional Lua module.
• Webhooks: Expose custom endpoints via the HTTP server; scripts can trigger outbound HTTP requests.
• Custom UI: Vue.js components can be injected into the web interface, allowing developers to build tailored dashboards or kiosk displays.
• Lua Extensions: Write reusable modules that expose functions to scripts, enabling complex logic (e.g., fuzzy matching, state machines) without cluttering the core engine.

The configuration is declarative: a handful of JSON files define devices, extensions, and scripts. Comprehensive documentation covers the WoT TD format, extension schema, and scripting guidelines. The community is active on GitHub, where pull requests for new device adapters or UI components are quickly reviewed. The lightweight nature of LHA also means that debugging can be done locally with a simple lua lha.lua command, and the entire runtime is introspectable via the built‑in HTTP API.

• Home Lab Automation: Quickly prototype ZigBee/Z‑Wave integrations on a Raspberry Pi.
• Edge IoT Gateways: Run LHA on an embedded Linux box to aggregate data from multiple protocols and expose a unified REST API.
• Custom Dashboards: Build kiosk‑style displays with Vue.js for monitoring temperature, power consumption, or security events.
• Rapid Prototyping: Use Blockly to assemble automations without deep Lua knowledge, then export the script for production use.

• Zero Dependencies: A single binary keeps deployment simple and secure.
• Protocol Agnostic: Unified API abstracts away ZigBee, Z‑Wave, and Hue complexities.
• Extensible Lua Core: Developers can extend functionality without modifying the engine itself.
• Performance & Footprint: Lightweight runtime ensures low latency on modest hardware.
• Open Licensing: MIT‑licensed core and Lua open source, giving full freedom to customize or embed LHA in proprietary systems.