matterbridge-litetouch 1.0.0

package/LICENSE

@@ -0,0 +1,123 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only distribute the software
+according to Distribution License and make changes or new works
+based on the software according to Changes and New Works License.
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software. Your license to distribute
+covers distributing the software with changes and new works
+permitted by Changes and New Works License.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the
+benefit of public knowledge, personal study, private entertainment,
+hobby projects, amateur pursuits, or religious observance, without
+any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health organization,
+environmental protection organization, or government institution
+is use for a permitted purpose regardless of the source of funding
+or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law.
+These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately.
+If your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for
+the software under these terms.
+
+**Use** means anything you do with the software requiring
+one of your licenses.

package/README.md

@@ -0,0 +1,214 @@
+# Matterbridge Litetouch 2000
+
+A [Matterbridge](https://github.com/Luligu/matterbridge) plugin that exposes Litetouch 2000 lighting loads as Matter devices.
+
+This allows you to control your Litetouch lighting system from any Matter-compatible ecosystem:
+- Apple Home (HomeKit)
+- Google Home
+- Amazon Alexa
+- Home Assistant
+- Hubitat Elevation
+- And more...
+
+## Features
+
+- **Dimmers**: Full brightness control with on/off and level adjustment
+- **Switches**: On/off control for relay loads
+- **Status Polling**: Automatically polls loads to detect changes from wall keypads
+- **Priority Queue**: User commands are prioritized over polling for responsive control
+- **Apple Home Optimized**: Includes workaround for Apple Home's command sequencing to prevent brightness flash when turning on dimmers
+
+## Requirements
+
+- Raspberry Pi (or similar Linux system) with Node.js 18+
+- USB-to-serial adapter connected to your Litetouch CCU
+- Litetouch 2000 with Standard or Compact CCU (not compatible with 5000LC)
+
+## Hardware Setup
+
+### Serial Cable
+
+You need a serial cable between the USB-serial adapter and the Litetouch CCU. Use an RJ45-to-RS232 adapter with the following pinout:
+
+| RJ45 Pin | RS232 Signal |
+|----------|--------------|
+| 2        | TX           |
+| 3        | RX           |
+| 5        | GND          |
+| 7 & 8    | Bridge together on CCU side only |
+
+Bridging pins 7 & 8 on the CCU side enables polling mode.
+
+### Identify Serial Port
+
+After connecting the USB-serial adapter, find the device path:
+
+```bash
+ls -la /dev/ttyUSB*
+# or
+ls -la /dev/serial/by-id/
+```
+
+## Installation
+
+### 1. Install Matterbridge
+
+```bash
+sudo npm install -g matterbridge
+```
+
+### 2. Install This Plugin
+
+Install globally alongside Matterbridge:
+```bash
+# Clone the repository
+git clone https://github.com/signal15/matterbridge-litetouch.git
+cd matterbridge-litetouch
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Install globally (must use sudo since matterbridge runs as root)
+sudo npm install -g .
+```
+
+Then register with Matterbridge:
+```bash
+sudo matterbridge -add matterbridge-litetouch
+```
+
+### Updating the Plugin
+
+After making changes or pulling updates:
+```bash
+cd matterbridge-litetouch
+npm run build
+sudo cp -r dist/* /usr/lib/node_modules/matterbridge-litetouch/dist/
+sudo systemctl restart matterbridge
+```
+
+### 3. Configure the Plugin
+
+**Note:** The Matterbridge web UI does not support the array-of-objects format needed for load configuration. Edit the config file directly:
+
+```bash
+sudo nano /root/.matterbridge/matterbridge-litetouch.config.json
+```
+
+After editing, restart matterbridge:
+```bash
+sudo systemctl restart matterbridge
+```
+
+Configuration options:
+
+- **Serial Port**: Path to your USB-serial device (e.g., `/dev/ttyUSB0`)
+- **Baud Rate**: Usually 9600 (default)
+- **Polling Interval**: Time between status polls in milliseconds (default: 2000)
+- **Dimmers**: List of dimmer load addresses with friendly names
+- **Switches**: List of relay load addresses with friendly names
+
+### Example Configuration
+
+```json
+{
+  "name": "Litetouch 2000",
+  "serialPort": "/dev/ttyUSB0",
+  "baudRate": 9600,
+  "pollingInterval": 2000,
+  "commandTimeout": 1000,
+  "dimmers": [
+    { "address": "01-1", "name": "Living Room Main" },
+    { "address": "01-2", "name": "Living Room Accent" },
+    { "address": "02-1", "name": "Kitchen" },
+    { "address": "03-4", "name": "Master Bedroom" }
+  ],
+  "switches": [
+    { "address": "05-1", "name": "Garage" },
+    { "address": "05-2", "name": "Porch Light" }
+  ],
+  "debug": false
+}
+```
+
+## Load Addressing
+
+Litetouch loads are addressed as `MM-O` where:
+- `MM` = Module number (1-99)
+- `O` = Output number on that module (1-6 typically)
+
+Example addresses: `01-1`, `03-4`, `10-6`
+
+To find your load addresses, refer to your Litetouch programming documentation or use the Litetouch Designer software.
+
+## Starting Matterbridge
+
+```bash
+matterbridge
+```
+
+For production use, set up Matterbridge as a systemd service:
+
+```bash
+sudo matterbridge -service install
+sudo systemctl enable matterbridge
+sudo systemctl start matterbridge
+```
+
+## Commissioning to Your Ecosystem
+
+1. Start Matterbridge and wait for it to initialize
+2. Open the Matterbridge web UI and note the QR code or pairing code
+3. In your Matter controller app (Apple Home, Google Home, etc.):
+   - Choose "Add Accessory" or "Set up device"
+   - Scan the QR code or enter the pairing code
+4. The Litetouch loads will appear as individual light/switch devices
+
+### Hubitat-Specific Instructions
+
+1. Go to **Devices** → **Add Device** → **Matter**
+2. Use the Hubitat mobile app to scan the QR code
+3. Devices will appear automatically in your device list
+
+## Troubleshooting
+
+### Serial Port Access
+
+If you get permission errors, add your user to the dialout group:
+```bash
+sudo usermod -a -G dialout $USER
+# Log out and back in for changes to take effect
+```
+
+### Debug Logging
+
+Enable debug mode in the plugin configuration to see detailed serial communication logs.
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Serial port not found" | Check USB connection and port path |
+| "Permission denied" | Add user to dialout group |
+| "No response from CCU" | Verify cable pinout and baud rate |
+| "Devices not updating" | Check that polling is running in logs |
+
+## Protocol Reference
+
+The Litetouch 2000 uses an ASCII protocol over RS-232:
+
+- **Query load**: ` 18 MM-O` → Response: `R 18 MM-O LLL`
+- **Set level**: ` 10 MM-O LLL`
+  - For relays: `LLL` = `000` (off) or `001` (on)
+  - For dimmers: `LLL` = `000`-`250`
+
+Commands are terminated with carriage return (`\r`).
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) - Free for personal and noncommercial use.
+
+## Credits
+
+Based on the original [Vera Litetouch plugin](https://github.com/signal15/vera-litetouch-2000) by signal15.

package/config.schema.json

@@ -0,0 +1,95 @@
+{
+  "title": "Litetouch 2000 Configuration",
+  "description": "Configure your Litetouch 2000 lighting system connection and loads",
+  "type": "object",
+  "properties": {
+    "name": {
+      "title": "Plugin Name",
+      "description": "Name displayed in Matterbridge",
+      "type": "string",
+      "default": "Litetouch 2000"
+    },
+    "serialPort": {
+      "title": "Serial Port",
+      "description": "Path to the USB-serial device (e.g., /dev/ttyUSB0)",
+      "type": "string",
+      "default": "/dev/ttyUSB0"
+    },
+    "baudRate": {
+      "title": "Baud Rate",
+      "description": "Serial port baud rate",
+      "type": "integer",
+      "default": 9600,
+      "enum": [9600, 19200, 38400, 57600, 115200]
+    },
+    "pollingInterval": {
+      "title": "Polling Interval (ms)",
+      "description": "Time between polling each load for status updates (minimum 500ms)",
+      "type": "integer",
+      "default": 2000,
+      "minimum": 500,
+      "maximum": 10000
+    },
+    "commandTimeout": {
+      "title": "Command Timeout (ms)",
+      "description": "How long to wait for a response before timing out",
+      "type": "integer",
+      "default": 1000,
+      "minimum": 250,
+      "maximum": 5000
+    },
+    "dimmers": {
+      "title": "Dimmer Loads",
+      "description": "List of dimmer module-output addresses (e.g., 01-1, 03-4)",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "title": "Address",
+            "description": "Module-output address (e.g., 01-1)",
+            "type": "string",
+            "pattern": "^\\d{1,2}-\\d{1,2}$"
+          },
+          "name": {
+            "title": "Name",
+            "description": "Friendly name for this load",
+            "type": "string"
+          }
+        },
+        "required": ["address", "name"]
+      },
+      "default": []
+    },
+    "switches": {
+      "title": "Relay/Switch Loads",
+      "description": "List of relay/switch module-output addresses (e.g., 02-3, 05-6)",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "title": "Address",
+            "description": "Module-output address (e.g., 02-3)",
+            "type": "string",
+            "pattern": "^\\d{1,2}-\\d{1,2}$"
+          },
+          "name": {
+            "title": "Name",
+            "description": "Friendly name for this load",
+            "type": "string"
+          }
+        },
+        "required": ["address", "name"]
+      },
+      "default": []
+    },
+    "debug": {
+      "title": "Debug Logging",
+      "description": "Enable verbose debug logging",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": ["serialPort", "dimmers", "switches"]
+}

package/dist/commandQueue.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Command queue with priority handling for Litetouch serial communication.
+ * User-initiated commands (on/off, dimming) take priority over background polling.
+ */
+export declare enum CommandPriority {
+    HIGH = 0,// User-initiated commands (on/off, set level)
+    NORMAL = 1
+}
+export interface QueuedCommand {
+    command: string;
+    priority: CommandPriority;
+    resolve: (response: string | null) => void;
+    reject: (error: Error) => void;
+    timestamp: number;
+}
+export declare class CommandQueue {
+    private queue;
+    private processing;
+    private processCallback;
+    /**
+     * Set the callback that processes commands (sends to serial port)
+     */
+    setProcessor(callback: (cmd: QueuedCommand) => Promise<string | null>): void;
+    /**
+     * Add a command to the queue with specified priority.
+     * High priority commands are inserted before normal priority ones.
+     */
+    enqueue(command: string, priority?: CommandPriority): Promise<string | null>;
+    /**
+     * Add a high-priority command (user action)
+     */
+    enqueueHighPriority(command: string): Promise<string | null>;
+    /**
+     * Add a normal-priority command (polling)
+     */
+    enqueuePolling(command: string): Promise<string | null>;
+    /**
+     * Process the next command in the queue
+     */
+    private processNext;
+    /**
+     * Get the current queue length
+     */
+    get length(): number;
+    /**
+     * Check if currently processing a command
+     */
+    get isProcessing(): boolean;
+    /**
+     * Clear all pending commands (used during shutdown)
+     */
+    clear(): void;
+    /**
+     * Remove all polling commands from the queue (useful when user commands come in)
+     */
+    clearPollingCommands(): void;
+}
+//# sourceMappingURL=commandQueue.d.ts.map

package/dist/commandQueue.js

@@ -0,0 +1,122 @@
+/**
+ * Command queue with priority handling for Litetouch serial communication.
+ * User-initiated commands (on/off, dimming) take priority over background polling.
+ */
+export var CommandPriority;
+(function (CommandPriority) {
+    CommandPriority[CommandPriority["HIGH"] = 0] = "HIGH";
+    CommandPriority[CommandPriority["NORMAL"] = 1] = "NORMAL";
+})(CommandPriority || (CommandPriority = {}));
+export class CommandQueue {
+    queue = [];
+    processing = false;
+    processCallback = null;
+    /**
+     * Set the callback that processes commands (sends to serial port)
+     */
+    setProcessor(callback) {
+        this.processCallback = callback;
+    }
+    /**
+     * Add a command to the queue with specified priority.
+     * High priority commands are inserted before normal priority ones.
+     */
+    async enqueue(command, priority = CommandPriority.NORMAL) {
+        return new Promise((resolve, reject) => {
+            const queuedCmd = {
+                command,
+                priority,
+                resolve,
+                reject,
+                timestamp: Date.now(),
+            };
+            // Insert based on priority
+            if (priority === CommandPriority.HIGH) {
+                // Find the first normal priority command and insert before it
+                const insertIndex = this.queue.findIndex(cmd => cmd.priority === CommandPriority.NORMAL);
+                if (insertIndex === -1) {
+                    this.queue.push(queuedCmd);
+                }
+                else {
+                    this.queue.splice(insertIndex, 0, queuedCmd);
+                }
+            }
+            else {
+                this.queue.push(queuedCmd);
+            }
+            // Start processing if not already running
+            this.processNext();
+        });
+    }
+    /**
+     * Add a high-priority command (user action)
+     */
+    async enqueueHighPriority(command) {
+        return this.enqueue(command, CommandPriority.HIGH);
+    }
+    /**
+     * Add a normal-priority command (polling)
+     */
+    async enqueuePolling(command) {
+        return this.enqueue(command, CommandPriority.NORMAL);
+    }
+    /**
+     * Process the next command in the queue
+     */
+    async processNext() {
+        if (this.processing || this.queue.length === 0 || !this.processCallback) {
+            return;
+        }
+        this.processing = true;
+        const cmd = this.queue.shift();
+        try {
+            const response = await this.processCallback(cmd);
+            cmd.resolve(response);
+        }
+        catch (error) {
+            cmd.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.processing = false;
+            // Process next command if queue is not empty
+            if (this.queue.length > 0) {
+                // Use setImmediate to prevent stack overflow on large queues
+                setImmediate(() => this.processNext());
+            }
+        }
+    }
+    /**
+     * Get the current queue length
+     */
+    get length() {
+        return this.queue.length;
+    }
+    /**
+     * Check if currently processing a command
+     */
+    get isProcessing() {
+        return this.processing;
+    }
+    /**
+     * Clear all pending commands (used during shutdown)
+     */
+    clear() {
+        for (const cmd of this.queue) {
+            cmd.reject(new Error('Queue cleared'));
+        }
+        this.queue = [];
+    }
+    /**
+     * Remove all polling commands from the queue (useful when user commands come in)
+     */
+    clearPollingCommands() {
+        this.queue = this.queue.filter(cmd => {
+            if (cmd.priority === CommandPriority.NORMAL) {
+                cmd.reject(new Error('Polling command cancelled'));
+                return false;
+            }
+            return true;
+        });
+    }
+}
+//# sourceMappingURL=commandQueue.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Matterbridge Plugin for Litetouch 2000 Lighting System
+ *
+ * Exposes Litetouch dimmers and switches as Matter devices that can be
+ * controlled from any Matter-compatible ecosystem (Apple Home, Google Home,
+ * Amazon Alexa, Home Assistant, Hubitat, etc.)
+ */
+import { MatterbridgeDynamicPlatform, PlatformConfig, PlatformMatterbridge } from 'matterbridge';
+import { AnsiLogger } from 'matterbridge/logger';
+/**
+ * Factory function to create the Litetouch platform
+ * This is the entry point for Matterbridge
+ */
+export default function createPlatform(matterbridge: PlatformMatterbridge, log: AnsiLogger, config: PlatformConfig): MatterbridgeDynamicPlatform;
+export { LitetouchPlatform } from './platform.js';
+export { LitetouchConnection } from './litetouchConnection.js';
+export { CommandQueue, CommandPriority } from './commandQueue.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Matterbridge Plugin for Litetouch 2000 Lighting System
+ *
+ * Exposes Litetouch dimmers and switches as Matter devices that can be
+ * controlled from any Matter-compatible ecosystem (Apple Home, Google Home,
+ * Amazon Alexa, Home Assistant, Hubitat, etc.)
+ */
+import { LitetouchPlatform } from './platform.js';
+/**
+ * Factory function to create the Litetouch platform
+ * This is the entry point for Matterbridge
+ */
+export default function createPlatform(matterbridge, log, config) {
+    return new LitetouchPlatform(matterbridge, log, config);
+}
+// Re-export the platform class for advanced usage
+export { LitetouchPlatform } from './platform.js';
+export { LitetouchConnection } from './litetouchConnection.js';
+export { CommandQueue, CommandPriority } from './commandQueue.js';
+//# sourceMappingURL=index.js.map