@bobfrankston/lxlan 0.1.8 → 0.1.9

package/.hintrc

@@ -0,0 +1,20 @@
+{
+  "extends": [
+    "development"
+  ],
+  "browserslist": [
+    "defaults",
+    "not ie 11",
+    "not ios_saf <= 15.8"
+  ],
+  "hints": {
+    "compat-api/html": [
+      "default",
+      {
+        "ignore": [
+          "meta[name=theme-color]"
+        ]
+      }
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,159 @@
+# @bobfrankston/lxlan
+
+Core LIFX LAN protocol library. Transport-agnostic implementation of the LIFX LAN protocol for controlling LIFX devices over local networks.
+
+## Purpose
+
+This package provides the **protocol-level implementation** for LIFX device control. It knows:
+- ✅ LIFX protocol messages (SetPower, SetColor, GetState, etc.)
+- ✅ Message encoding/decoding (binary packet format)
+- ✅ Device state management (power, color, label, etc.)
+- ✅ Event emission patterns (device discovery, state updates)
+
+It does **NOT** know:
+- ❌ How to send UDP packets (no Node.js dgram)
+- ❌ How to open WebSockets (no browser APIs)
+- ❌ Any specific transport implementation
+
+## Architecture Factoring
+
+```
+┌─────────────────────────────────────────────────┐
+│  Application (your code)                        │
+├─────────────────────────────────────────────────┤
+│  @bobfrankston/lxlan (this package)             │
+│  • LxClient - device discovery & management     │
+│  • LxDevice - individual device control         │
+│  • LxProtocol - message encode/decode           │
+│  • LxTransport - INTERFACE ONLY                 │
+├─────────────────────────────────────────────────┤
+│  Transport Implementation (pick one):           │
+│  • @bobfrankston/lxlan-node     → rmfudp        │
+│  • @bobfrankston/lxlan-browser  → httpudp-client│
+└─────────────────────────────────────────────────┘
+```
+
+## Transport Abstraction
+
+The package exports `LxTransport` interface that must be implemented by transport layers:
+
+```typescript
+export interface LxTransport {
+  bind(): Promise<void>;
+  close(): void;
+  send(ip: string, port: number, data: Buffer): void;
+  broadcast(data: Buffer, port: number, addresses: string[]): void;
+  onMessage(handler: (data: Buffer, rinfo: RemoteInfo) => void): void;
+  onError(handler: (err: Error) => void): void;
+}
+```
+
+**Implementations:**
+- **Node.js**: `@bobfrankston/lxlan-node` provides `rmfudp`-based transport
+- **Browser**: `@bobfrankston/lxlan-browser` provides `httpudp-client`-based transport
+
+## Installation
+
+This package is typically installed as a dependency of the platform-specific wrappers:
+
+```bash
+# For Node.js projects
+npm install @bobfrankston/lxlan-node
+
+# For browser projects
+npm install @bobfrankston/lxlan-browser
+```
+
+Direct usage (if providing your own transport):
+
+```bash
+npm install @bobfrankston/lxlan
+```
+
+## Direct Usage (Advanced)
+
+If you're implementing your own transport:
+
+```typescript
+import { LxClient } from '@bobfrankston/lxlan';
+import { MyCustomTransport } from './my-transport';
+
+const transport = new MyCustomTransport();
+const client = new LxClient({ transport });
+
+await client.start();
+
+client.on('device', (device) => {
+  console.log('Found:', device.label);
+  device.setPower(true);
+  device.setColor({ h: 120, s: 100, b: 50 });
+});
+```
+
+## Features
+
+- 🎯 Full LIFX LAN protocol support
+- 🔍 Automatic device discovery
+- 🎨 Color control (HSB, RGB, Kelvin)
+- 💡 Power control
+- 📊 Device state caching
+- 📡 Event-driven architecture
+- 🔄 Automatic retry with configurable timeouts
+- 📝 Comprehensive device info (firmware, WiFi, uptime)
+
+## Device Control
+
+```typescript
+// Power control
+device.setPower(true);
+device.setPower(false);
+
+// Color control
+device.setColor({ h: 180, s: 100, b: 75 });      // HSB
+device.setColor({ r: 255, g: 0, b: 0 });         // RGB
+device.setColor({ kelvin: 3500 });               // White temperature
+
+// Get comprehensive device info
+device.getDeviceInfo();  // Triggers 'deviceInfo' event
+
+// State queries
+console.log(device.label, device.power, device.color);
+```
+
+## Events
+
+```typescript
+client.on('device', (device) => {
+  // New device discovered
+});
+
+client.on('state', (device) => {
+  // Device state updated
+});
+
+client.on('deviceInfo', (device) => {
+  // Complete device info received (firmware, signal, uptime)
+  console.log(device.firmwareVersion, device.signal, device.uptime);
+});
+```
+
+## Dependencies
+
+- `@bobfrankston/colorlib` - Color space conversions (HSB ↔ RGB ↔ Kelvin)
+
+## Related Packages
+
+- **[@bobfrankston/lxlan-node](../lxlan-node)** - Node.js transport wrapper
+- **[@bobfrankston/lxlan-browser](../lxlan-browser)** - Browser transport wrapper
+- **[@bobfrankston/rmfudp](../../../../utils/udp/rmfudp)** - Node.js UDP transport
+- **[@bobfrankston/httpudp-client](../../../../utils/udp/httpudp-client)** - Browser WebSocket UDP client
+- **[@bobfrankston/httpudp](../../../../utils/udp/httpudp)** - WebSocket-to-UDP proxy server
+- **[@bobfrankston/colorlib](../../../../utils/colorlib)** - Color utilities
+
+## TypeScript Configuration
+
+This package uses `strictNullChecks: false` - undefined is treated as a first-class value throughout the codebase.
+
+## License
+
+MIT

package/client.d.ts

@@ -7,8 +7,6 @@ import { LxDevice } from './device.js';
 export interface LxClientOptions {
     /** Transport layer implementation (required) */
     transport: LxTransport;
-    /** Broadcast addresses for discovery */
-    broadcastAddresses: string[];
     /** Event emitter implementation (required - use Node EventEmitter or browser equivalent) */
     eventEmitter: LxEventEmitter;
     /** LIFX port (default 56700) */
@@ -40,7 +38,6 @@ export declare class LxClient {
     private emitter;
     private transport;
     private port;
-    private broadcastAddresses;
     private discoveryTimer?;
     /** Cached devices by MAC address (lowercase) */
     devices: Map<string, LxDevice>;

package/client.js

@@ -26,7 +26,6 @@ export class LxClient {
     emitter;
     transport;
     port;
-    broadcastAddresses;
     discoveryTimer; // NodeJS.Timeout in Node, number in browser
     /** Cached devices by MAC address (lowercase) */
     devices = new Map();
@@ -34,9 +33,10 @@ export class LxClient {
         this.emitter = options.eventEmitter;
         this.transport = options.transport;
         this.port = options.port ?? LIFX_PORT;
-        this.broadcastAddresses = options.broadcastAddresses;
         this.transport.onMessage((data, rinfo) => {
-            this.handleMessage(data, rinfo.address, rinfo.port);
+            // Ensure data is Uint8Array for protocol decoder
+            const buf = data instanceof Uint8Array ? data : new Uint8Array(data);
+            this.handleMessage(buf, rinfo.address, rinfo.port);
         });
         this.transport.onError((err) => {
             this.emitter.emit('error', err);
@@ -80,7 +80,7 @@ export class LxClient {
             type: MessageType.GetService,
             tagged: true
         });
-        this.transport.broadcast(msg, this.port, this.broadcastAddresses);
+        this.transport.broadcast(msg, this.port);
     }
     /**
      * Get device by MAC address
@@ -152,6 +152,7 @@ export class LxClient {
             case MessageType.StateService: {
                 const info = decodeStateService(msg.payload);
                 device.port = info.port;
+                device.markResponseReceived(MessageType.GetService);
                 break;
             }
             case MessageType.State: {
@@ -159,16 +160,23 @@ export class LxClient {
                 device.color = hsbk16ToHsbk(state.hsbk);
                 device.power = state.power > 0;
                 device.label = state.label;
+                device.markResponseReceived(MessageType.Get);
+                // State messages also respond to SetPower and SetColor
+                device.markResponseReceived(MessageType.SetPower);
+                device.markResponseReceived(MessageType.SetColor);
                 this.emit('state', device);
                 break;
             }
             case MessageType.StatePower: {
                 device.power = decodeStatePower(msg.payload);
+                device.markResponseReceived(MessageType.GetPower);
+                device.markResponseReceived(MessageType.SetPower);
                 this.emit('power', device);
                 break;
             }
             case MessageType.StateLabel: {
                 device.label = decodeStateLabel(msg.payload);
+                device.markResponseReceived(MessageType.GetLabel);
                 this.emit('label', device);
                 break;
             }
@@ -176,16 +184,19 @@ export class LxClient {
                 const ver = decodeStateVersion(msg.payload);
                 device.vendor = ver.vendor;
                 device.product = ver.product;
+                device.markResponseReceived(MessageType.GetVersion);
                 this.emit('version', device);
                 break;
             }
             case MessageType.StateGroup: {
                 device.group = decodeStateGroup(msg.payload);
+                device.markResponseReceived(MessageType.GetGroup);
                 this.emit('group', device);
                 break;
             }
             case MessageType.StateLocation: {
                 device.location = decodeStateGroup(msg.payload);
+                device.markResponseReceived(MessageType.GetLocation);
                 this.emit('location', device);
                 break;
             }
@@ -193,6 +204,7 @@ export class LxClient {
                 const info = decodeStateHostInfo(msg.payload);
                 device.signal = info.signal;
                 device.rssi = Math.round(10 * Math.log10(info.signal));
+                device.markResponseReceived(MessageType.GetHostInfo);
                 this.emit('hostInfo', device);
                 this.checkDeviceInfoComplete(device);
                 break;
@@ -200,6 +212,7 @@ export class LxClient {
             case MessageType.StateHostFirmware: {
                 const fw = decodeStateHostFirmware(msg.payload);
                 device.firmwareVersion = fw.version;
+                device.markResponseReceived(MessageType.GetHostFirmware);
                 this.emit('hostFirmware', device);
                 this.checkDeviceInfoComplete(device);
                 break;
@@ -208,6 +221,7 @@ export class LxClient {
                 const info = decodeStateWifiInfo(msg.payload);
                 device.signal = info.signal;
                 device.rssi = Math.round(10 * Math.log10(info.signal));
+                device.markResponseReceived(MessageType.GetWifiInfo);
                 this.emit('wifiInfo', device);
                 this.checkDeviceInfoComplete(device);
                 break;
@@ -216,6 +230,7 @@ export class LxClient {
                 const info = decodeStateInfo(msg.payload);
                 device.uptime = info.uptime;
                 device.downtime = info.downtime;
+                device.markResponseReceived(MessageType.GetInfo);
                 this.emit('info', device);
                 this.checkDeviceInfoComplete(device);
                 break;

package/device.d.ts

@@ -47,6 +47,10 @@ export declare class LxDevice {
     /** Recent message sequences for deduplication (sequence -> timestamp) */
     private recentSequences;
     private transport?;
+    /** Pending requests awaiting responses (message type -> timeout) */
+    private pendingRequests;
+    /** Default timeout for requests in milliseconds */
+    private requestTimeout;
     /**
      * Create a LIFX device
      *
@@ -69,8 +73,18 @@ export declare class LxDevice {
     setTransport(transport: LxTransport): void;
     /** Send raw message to device */
     send(type: number, payload?: Buffer): void;
+    /** Start tracking a request with timeout */
+    private startRequestTimeout;
+    /** Clear request timeout when response received */
+    private clearRequestTimeout;
     /** Set power on/off */
     setPower(on: boolean): void;
+    /**
+     * Set brightness while keeping current color
+     * @param brightness - Brightness 0-100
+     * @param duration - Transition time in milliseconds (default 0)
+     */
+    setBrightness(brightness: number, duration?: number): void;
     /**
      * Set color - accepts flexible input formats
      * @param color - Color as hex "#ff0000", RGB {r,g,b}, HSL {h,s,l}, HSB {h,s,b}, HSBK {h,s,b,k}, or Kelvin number
@@ -118,6 +132,8 @@ export declare class LxDevice {
     getDeviceInfo(): void;
     /** Update last seen timestamp and online status */
     markSeen(): void;
+    /** Notify that a response was received for a message type */
+    markResponseReceived(messageType: number): void;
     /**
      * Check if message is a duplicate based on sequence number.
      * LIFX devices sometimes send duplicate responses.

package/device.js

@@ -47,6 +47,10 @@ export class LxDevice {
     /** Recent message sequences for deduplication (sequence -> timestamp) */
     recentSequences = new Map();
     transport;
+    /** Pending requests awaiting responses (message type -> timeout) */
+    pendingRequests = new Map();
+    /** Default timeout for requests in milliseconds */
+    requestTimeout = 1000;
     /**
      * Create a LIFX device
      *
@@ -92,6 +96,27 @@ export class LxDevice {
             resRequired: true
         });
         this.transport.send(this.ip, this.port, msg);
+        // Track this request with a timeout
+        this.startRequestTimeout(type);
+    }
+    /** Start tracking a request with timeout */
+    startRequestTimeout(messageType) {
+        // Clear any existing timeout for this message type
+        this.clearRequestTimeout(messageType);
+        // Set new timeout
+        const timeout = setTimeout(() => {
+            this.online = false;
+            this.pendingRequests.delete(messageType);
+        }, this.requestTimeout);
+        this.pendingRequests.set(messageType, timeout);
+    }
+    /** Clear request timeout when response received */
+    clearRequestTimeout(messageType) {
+        const timeout = this.pendingRequests.get(messageType);
+        if (timeout) {
+            clearTimeout(timeout);
+            this.pendingRequests.delete(messageType);
+        }
     }
     /** Set power on/off */
     setPower(on) {
@@ -103,6 +128,19 @@ export class LxDevice {
             ackRequired: true
         });
         this.transport.send(this.ip, this.port, msg);
+        // Track this request with a timeout
+        this.startRequestTimeout(MessageType.SetPower);
+    }
+    /**
+     * Set brightness while keeping current color
+     * @param brightness - Brightness 0-100
+     * @param duration - Transition time in milliseconds (default 0)
+     */
+    setBrightness(brightness, duration = 0) {
+        this.requireTransport();
+        // Keep current hue/saturation/kelvin, just change brightness
+        const newColor = { ...this.color, b: brightness };
+        this.setColor(newColor, duration);
     }
     /**
      * Set color - accepts flexible input formats
@@ -120,6 +158,8 @@ export class LxDevice {
             ackRequired: true
         });
         this.transport.send(this.ip, this.port, msg);
+        // Track this request with a timeout
+        this.startRequestTimeout(MessageType.SetColor);
     }
     /**
      * Set white color temperature
@@ -140,7 +180,6 @@ export class LxDevice {
     }
     /** Set label */
     setLabel(label) {
-        this.requireTransport();
         const msg = encodeMessage({
             type: MessageType.SetLabel,
             target: this.mac,
@@ -155,7 +194,6 @@ export class LxDevice {
     }
     /** Set group */
     setGroup(id, label) {
-        this.requireTransport();
         const msg = encodeMessage({
             type: MessageType.SetGroup,
             target: this.mac,
@@ -170,7 +208,6 @@ export class LxDevice {
     }
     /** Set location */
     setLocation(id, label) {
-        this.requireTransport();
         const msg = encodeMessage({
             type: MessageType.SetLocation,
             target: this.mac,
@@ -223,6 +260,10 @@ export class LxDevice {
         this.lastSeen = Date.now();
         this.online = true;
     }
+    /** Notify that a response was received for a message type */
+    markResponseReceived(messageType) {
+        this.clearRequestTimeout(messageType);
+    }
     /**
      * Check if message is a duplicate based on sequence number.
      * LIFX devices sometimes send duplicate responses.

package/index.d.ts

@@ -1,7 +1,7 @@
 export * from './types.js';
 export { LxDevice } from './device.js';
 export { LxClient, LxClientOptions } from './client.js';
-export { LxTransport, RemoteInfo } from './transport.js';
+export { UdpTransport, LxTransport, RemoteInfo } from './transport.js';
 export { LxEventEmitter, LxEventEmitterBase } from './events.js';
 export { encodeMessage, decodeMessage } from './protocol.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/lxlan",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "LIFX LAN protocol library for device control via UDP",
   "type": "module",
   "main": "index.js",
@@ -15,8 +15,8 @@
     "build": "tsc",
     "watch": "tsc -w",
     "preversion": "npm run build",
-    "postversion": "git push && git push --tags && npm publish --loglevel=error",
-    "release": "git add -A && git diff-index --quiet HEAD || git commit -m 'Build for release' && npm version patch"
+    "release": "git add -A && git diff-index --quiet HEAD || git commit -m 'Build for release' && npm version patch",
+    "postversion": "git push && git push --tags && npm publish --loglevel=error"
   },
   "keywords": [
     "lifx",
@@ -31,9 +31,14 @@
     "url": "https://github.com/BobFrankston/lxlan.git"
   },
   "dependencies": {
-    "@bobfrankston/colorlib": "file:../../../../utils/colorlib"
+    "@bobfrankston/colorlib": "^0.1.6",
+    "@bobfrankston/udp-transport": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.0.6"
+    "@types/node": "^25.0.9"
+  },
+  ".dependencies": {
+    "@bobfrankston/colorlib": "file:../../../../utils/colorlib",
+    "@bobfrankston/udp-transport": "file:../../../../utils/udp/udp-transport"
   }
 }

package/protocol.d.ts

@@ -4,76 +4,78 @@ import { LxMessage } from './types.js';
 export declare function nextSequence(): number;
 /** Get global source ID */
 export declare function getSource(): number;
-/** Encode LIFX message to buffer */
+/** Encode LIFX message to Uint8Array */
 export declare function encodeMessage(options: {
     type: number;
-    target?: string; /** MAC address, empty for broadcast */
-    payload?: Buffer;
+    target?: string;
+    payload?: Uint8Array;
     tagged?: boolean;
     ackRequired?: boolean;
     resRequired?: boolean;
     sequence?: number;
-}): Buffer;
-/** Decode LIFX message from buffer */
-export declare function decodeMessage(buf: Buffer): LxMessage;
+}): Uint8Array;
+/** Decode LIFX message from Uint8Array */
+export declare function decodeMessage(buf: Uint8Array): LxMessage;
 /** Encode SetPower payload */
-export declare function encodeSetPower(on: boolean): Buffer;
+export declare function encodeSetPower(level: boolean): Uint8Array;
 /** Encode SetColor payload */
-export declare function encodeSetColor(hsbk: HSBK16, duration?: number): Buffer;
+export declare function encodeSetColor(hsbk: HSBK16, duration?: number): Uint8Array;
 /** Encode SetLabel payload */
-export declare function encodeSetLabel(label: string): Buffer;
+export declare function encodeSetLabel(label: string): Uint8Array;
 /** Encode SetGroup payload */
-export declare function encodeSetGroup(id: string, label: string): Buffer;
+export declare function encodeSetGroup(id: string, label: string): Uint8Array;
 /** Encode SetLocation payload (same format as SetGroup) */
-export declare function encodeSetLocation(id: string, label: string): Buffer;
+export declare function encodeSetLocation(id: string, label: string): Uint8Array;
 /** Decode State (107) payload - light state */
-export declare function decodeState(payload: Buffer): {
+export declare function decodeState(payload: Uint8Array): {
     hsbk: HSBK16;
     power: number;
     label: string;
 };
 /** Decode StatePower (22) payload */
-export declare function decodeStatePower(payload: Buffer): boolean;
+export declare function decodeStatePower(payload: Uint8Array): boolean;
 /** Decode StateLabel (25) payload */
-export declare function decodeStateLabel(payload: Buffer): string;
+export declare function decodeStateLabel(payload: Uint8Array): string;
 /** Decode StateVersion (33) payload */
-export declare function decodeStateVersion(payload: Buffer): {
+export declare function decodeStateVersion(payload: Uint8Array): {
     vendor: number;
     product: number;
     version: number;
 };
 /** Decode StateGroup (53) or StateLocation (50) payload */
-export declare function decodeStateGroup(payload: Buffer): {
+export declare function decodeStateGroup(payload: Uint8Array): {
     id: string;
     label: string;
     updatedAt: number;
 };
 /** Decode StateService (3) payload */
-export declare function decodeStateService(payload: Buffer): {
+export declare function decodeStateService(payload: Uint8Array): {
     service: number;
     port: number;
 };
 /** Decode StateHostInfo (13) payload */
-export declare function decodeStateHostInfo(payload: Buffer): {
+export declare function decodeStateHostInfo(payload: Uint8Array): {
     signal: number;
     tx: number;
     rx: number;
 };
 /** Decode StateHostFirmware (15) payload */
-export declare function decodeStateHostFirmware(payload: Buffer): {
+export declare function decodeStateHostFirmware(payload: Uint8Array): {
     build: number;
     version: number;
 };
 /** Decode StateWifiInfo (17) payload - same format as StateHostInfo */
-export declare function decodeStateWifiInfo(payload: Buffer): {
+export declare function decodeStateWifiInfo(payload: Uint8Array): {
     signal: number;
     tx: number;
     rx: number;
 };
 /** Decode StateInfo (35) payload */
-export declare function decodeStateInfo(payload: Buffer): {
+export declare function decodeStateInfo(payload: Uint8Array): {
     time: number;
     uptime: number;
     downtime: number;
 };
+/** Encode GetService payload (empty) */
+export declare function encodeGetService(): Uint8Array;
 //# sourceMappingURL=protocol.d.ts.map