@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:

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:

# For Node.js projects
npm install @bobfrankston/lxlan-node

# For browser projects
npm install @bobfrankston/lxlan-browser

Direct usage (if providing your own transport):

npm install @bobfrankston/lxlan

Direct Usage (Advanced)

If you're implementing your own transport:

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

// 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

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 - Node.js transport wrapper
• @bobfrankston/lxlan-browser - Browser transport wrapper
• @bobfrankston/rmfudp - Node.js UDP transport
• @bobfrankston/httpudp-client - Browser WebSocket UDP client
• @bobfrankston/httpudp - WebSocket-to-UDP proxy server
• @bobfrankston/colorlib - Color utilities

TypeScript Configuration

This package uses strictNullChecks: false - undefined is treated as a first-class value throughout the codebase.

License

MIT