HOS Overview

HOS (Haptique OS) is a home and building automation operating system that runs as a Node/Express/Electron server on the local network. It manages devices — lights, AV equipment, HVAC systems, security hardware, robot vacuums — through a driver-based architecture. The server is the central hub:

• Drivers run as OS-managed local packages or external WebSocket processes to control physical devices
• Mobile apps connect via REST API and SSE for device control and live state updates
• External tools connect via Socket.IO for real-time protocol events

HOS can run as an Electron desktop app (for local use) or as a headless Docker container (for rack or home-server deployments).

---

The Driver Ecosystem

Drivers are the extension points for HOS. Every device integration — a smart bulb, a TV, a thermostat — is a driver.

Key characteristics:

• Drivers are standalone processes — they run separately from the HOS server, so a driver crash cannot take down the hub
• OS-local uploaded drivers can be written in JavaScript, Python, or Lua and communicate through newline-delimited JSON over stdin/stdout
• External SDK drivers can be written in TypeScript/Node, Python, native binaries, or any runtime that can open the /driver WebSocket connection
• Raw TypeScript is an authoring format only for OS-local packages; uploadable packages must contain compiled .js for JavaScript drivers
• Each driver has a driverKey (e.g., PHILIPS_HUE, SONOS, APPLE_TV) and usually an instanceId; local packages get this from the manifest, while external drivers register it over WebSocket
• Drivers discover devices on the local network or protocol bus and report them to HOS via DEVICE_DISCOVERED events
• HOS stores device state centrally — drivers push STATE_UPDATE events when device state changes
• The server sends ACTION commands to drivers when users (via mobile app or voice) trigger device actions
• This bidirectional communication forms the core control loop

The Integration Manager upload flow accepts ZIP packages containing one *.driver.json manifest plus one .py, .lua, or .js implementation. The manifest feeds the integration listing, setup form, logical-device UI, command catalog, and runtime launch metadata.

---

Device Discovery and Control Flow

Driver Process                    HOS Server                     Mobile App
     |                                |                              |
     |-- register or manifest load --->|                              |
     |<- runtime/session ready --------|                              |
     |                                |                              |
     |-- DEVICE_DISCOVERED ---------->|                              |
     |                                |-- SSE: device added -------->|
     |                                |                              |
     |-- STATE_UPDATE --------------->|                              |
     |                                |-- SSE: state changed ------->|
     |                                |                              |
     |                                |<- POST /devices/:id/command -|
     |<- ACTION { command, data } ----|                              |
     |                                |                              |
     |-- ACTION_RESULT -------------->|                              |
     |                                |-- SSE: action result ------->|

Step by step:

1. OS-local package driver is launched by DriverManager, or an external driver opens ws://host:DRIVER_WS_PORT/driver
2. Local package metadata comes from *.driver.json; external WebSocket drivers send driver.register with driverKey, instanceId, and protocolVersion
3. Server acknowledges or marks the local runtime as ready
4. Driver discovers devices on its protocol (e.g., scans Zigbee network) and sends DEVICE_DISCOVERED for each
5. HOS stores device records and broadcasts an SSE event to connected mobile apps
6. Driver continuously sends STATE_UPDATE as devices change state (power on/off, brightness changes, etc.)
7. Mobile user taps a control — REST POST to /app/os/devices/:id/command
8. HOS ActionDispatcher routes the command to the correct local process or driver WebSocket session
9. Driver executes the physical command and sends ACTION_RESULT + STATE_UPDATE back to HOS
10. HOS fans the state change out via SSE to all connected clients

---

Supported Device Domains

HOS natively supports five primary device domains. The domain list is extensible — any driver can introduce new device types.

Domain	Description
Lighting	Smart bulbs, switches, and dimmers. Supports on/off, brightness (0–100%), color temperature, and RGB color. Integrations include Philips Hue, Zigbee2MQTT, KNX, and more.
AV / Media	Televisions, AV receivers, streaming players, and soundbars. Supports input switching, volume, transport controls (play/pause/skip), and source selection. Integrations include Apple TV, Denon, Yamaha, Sonos, Plex.
Climate	Thermostats, HVAC systems, and fans. Supports target temperature, mode (heat/cool/auto/off), fan speed, and humidity reporting.
Security	Smart locks, cameras, motion sensors, and contact sensors. Supports lock/unlock commands, arm/disarm, and live event streams.
Robot Vacuums	Robotic vacuum cleaners and mops. Supports start, stop, dock, zone cleaning, and status reporting.

---

The SDK

@haptique/driver-sdk provides:

• HosDriver — TypeScript class that wraps the WebSocket protocol for driver authors (npm install @haptique/driver-sdk)
• Complete developer guides — Getting Started, Driver Lifecycle, Driver Architecture, Domain Reference, Entity Type Reference, Troubleshooting
• Sample drivers for each of the 5 domains above

If you are building a new driver integration, start with Getting Started. The SDK is designed so that an external developer with no HOS internals knowledge can go from zero to a working driver in a single session.

---

AI Driver Builder MCP

The AI Driver Builder can generate a complete driver package — manifest + implementation + README — from a plain-language description of the device protocol. It targets the OS Integration Manager package flow and supports python, lua, and first-class local javascript drivers.

---

Key Concepts Glossary

Term	Definition
Driver	A standalone process that bridges HOS to a device protocol (Zigbee, Z-Wave, HTTP, proprietary). Runs as an OS-local package or connects externally over WebSocket.
Device	A logical entity in HOS representing one controllable physical unit (e.g., "Living Room Lamp").
Action	A command sent from the server to a driver (e.g., turn_on, set_brightness, set_input). Actions are driver-specific.
State	The current runtime snapshot of a device: { power, brightness, volume, input, playback, extras, updatedAt }. Stored in DeviceStateManager.
ActionDispatcher	The routing layer that takes (deviceId, action, data) from an HTTP controller and delivers an ACTION message to the correct local driver process or WebSocket session.
DriverWSServer	The raw WebSocket server listening on DRIVER_WS_PORT/driver that manages external driver connections and sessions.
JavaScriptDriverProcess	OS-local runtime wrapper that launches .js drivers with Node and exchanges newline-delimited JSON over stdin/stdout.
DeviceStateManager	In-memory store of per-device state snapshots, updated by driver STATE_UPDATE events and queried for SSE initial snapshots.

---

What's Next

• Getting Started — Run your first driver in 10 minutes
• Driver Architecture — Full command flow and connection model
• API Reference — REST endpoints, SSE events, and WebSocket protocol
• AI Driver Builder MCP — Generate driver packages with AI assistance