Registry / devops / homebridge-websocket-dti

homebridge-websocket-dti

library1.0.0jsnpmunverified

A Homebridge plugin that exposes a WebSocket API for controlling and monitoring HomeKit accessories from external services like Node-RED. Version 1.0.0 (current) allows adding, removing, getting, and setting accessories via JSON messages over WebSocket. Requires Node.js ^18.20.4 || ^20.15.1 || ^22 and Homebridge ^1.6.0 || ^2.0.0. Key differentiator: enables real-time integration with Node-RED and other WebSocket clients without additional hardware bridges, similar to homebridge-mqtt but using WebSocket protocol instead of MQTT.

devops

npm install homebridge-websocket-dti

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HOMEBRIDGE-WEBSOCK

homebridge-websocket-dti

devopsjavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export

✓ const HomebridgeWebSocket = require('homebridge-websocket-dti')

✗ import HomebridgeWebSocket from 'homebridge-websocket-dti'

ESM-only since v3? No. This plugin uses CommonJS; no default export exists. Use require().

Platform class

✓ const HomebridgeWebSocket = require('homebridge-websocket-dti'); const platform = new HomebridgeWebSocket(log, config, api)

Instantiate with Homebridge API. The plugin exports a constructor function that Homebridge calls automatically.

WebSocket API message structure

✓ const msg = JSON.stringify({topic: 'add', payload: {name: 'lamp', service: 'Switch'}}); ws.send(msg)

✗ const msg = {topic: 'add', payload: {name: 'lamp'}}; ws.send(msg)

Must send JSON string. Object serialization is automatic only in some libraries; always stringify.

Installation, configuration, and a WebSocket client example that adds a switch and toggles it on.

// 1. Install Homebridge and plugin // sudo npm install -g homebridge homebridge-websocket-dti // 2. Add platform to ~/.homebridge/config.json // { // "platforms": [{ // "platform": "websocket", // "name": "websocket", // "port": 4050 // }] // } // 3. Start Homebridge and connect via WebSocket const WebSocket = require('ws'); const ws = new WebSocket('ws://127.0.0.1:4050'); ws.on('open', () => { // Add a new switch accessory ws.send(JSON.stringify({topic: 'add', payload: {name: 'flex_lamp', service: 'Switch'}})); // Set On characteristic to true ws.send(JSON.stringify({topic: 'setValue', payload: {name: 'flex_lamp', characteristic: 'On', value: true}})); // Get all accessories ws.send(JSON.stringify({topic: 'get', payload: {name: 'all'}})); }); ws.on('message', (data) => { const msg = JSON.parse(data); console.log('Received:', msg); // Handle responses, callbacks, etc. }); // Requirements: Node.js 18.20.4+, Homebridge 1.6.0+ or 2.0.0+

Debug

Known issues

gotchaThe WebSocket API expects JSON strings; sending plain objects will fail silently.

fix

Always use JSON.stringify() before ws.send()

affects: >=1.0.0

gotchaAccessories added via this plugin are only visible through this plugin, not from other Homebridge plugins like homebridge-mqtt. See homebridge-mqtt issue #8.

fix

Use only one integration method per accessory; do not mix WebSocket and MQTT for the same accessory name.

affects: >=1.0.0

gotchaWhen the plugin sends a 'get' topic (input to client), the client must respond with a callback within 1 second or the request times out.

fix

Implement a response handler that sends a callback message matching the accessory name and characteristic within one second.

affects: >=1.0.0

deprecatedThe callback topic uses 'name' and 'characteristic' in payload; future versions may use 'aid' and 'iid' (Accessory ID and Instance ID) as per HomeKit spec.

fix

Design your client to handle both naming schemes, or wait for plugin update.

affects: >=1.0.0

gotchaPort 4050 is the default; ensure it is not already in use or blocked by a firewall.

fix

Change the port in config.json or open port 4050 in firewall.

affects: >=1.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE :::4050

Port 4050 is already used by another process or instance of the plugin.

fix

Change port in config.json to an unused port (e.g., 4051).

WebSocket connection to 'ws://127.0.0.1:4050' failed: Connection refused

Homebridge is not running or the plugin is not loaded correctly.

fix

Ensure Homebridge is started and the platform is configured (check ~/.homebridge/config.json).

TypeError: Cannot read properties of undefined (reading 'Characteristic')

Invalid characteristic name sent in setValue or callback, or plugin expects a different casing.

fix

Use correct characteristic names: 'On', 'Brightness', 'CurrentTemperature', etc. Check Homebridge documentation.

UnhandledPromiseRejectionWarning: TimeoutError: callback not received

Client did not send a callback response within 1 second after receiving a 'get' topic.

fix

Ensure your WebSocket client sends a callback message immediately upon receiving a 'get' with matching name and characteristic.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/cylon147/homebridge-websocket-DTI ↗

packagehomebridge-websocket-dti ↗

homepagehttps://github.com/cylon147/homebridge-websocket-DTI#readme ↗