@bobfrankston/lxlan 0.1.0 → 0.1.3

package/notes.md

@@ -1,530 +0,0 @@
-# LIFX LAN Library Design - lxlan
-
-**Updated: 2026-01-11 by Claude Code**
-
-## Overview
-
-TypeScript library for LIFX device control over LAN using UDP protocol. Designed for simplicity and portability.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Application                          │
-├─────────────────────────────────────────────────────────┤
-│  @bobfrankston/lxlan                                    │
-│  ├── LxClient        - main entry, event emitter        │
-│  ├── LxDevice        - device abstraction               │
-│  └── LxProtocol      - message encode/decode            │
-├─────────────────────────────────────────────────────────┤
-│  @bobfrankston/lxudp (separate package)                 │
-│  └── UDP transport with port sharing, retry, timeouts   │
-│      Future: web server proxy for browser UDP access    │
-│      May complement/replace y:\dev\homecontrol\utils\netsupport │
-├─────────────────────────────────────────────────────────┤
-│  @bobfrankston/colorlib (separate package)              │
-│  └── Color conversions: RGB ↔ HSL ↔ HSBK ↔ Kelvin      │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Design Decisions
-
-### Async Model (Fire-and-Forget)
-- **Send methods return when packet sent**, not when response received
-- **Results delivered via EventEmitter**
-- Sequence numbers track request/response internally
-
-### Event Emission Policy
-- **Emit on every message** from device, even if state unchanged
-- **Cache state** on device object for sync queries
-- Traffic is light - no throttling needed
-
-### Retry Policy
-- **Auto-retry** with configurable count (default 3)
-- **Configurable via API** at runtime, not just constructor
-- **Long timeouts supported** - up to 10+ seconds for network issues
-- Settings: retryCount, retryDelay, responseTimeout
-
-### Port Sharing
-- Uses `SO_REUSEADDR` via dgram `reuseAddr: true`
-- Multiple instances share port 56700
-
-### Scope - v1
-- **No multizone** - treat as single device (see Future section)
-- **Include label/group/location get/set** - for naming management
-- Strategy: set device labels to factory-default-based names, use external DB for management
-
-### Separation of Concerns
-- **lxcolor**: Pure color math, no dependencies
-- **lxudp**: Generic UDP transport, reusable
-- **lxlan**: LIFX protocol only, uses lxudp
-
----
-
-## lxudp API (separate package)
-
-Reusable UDP transport with port sharing, retry logic, configurable timeouts.
-
-```typescript
-import { EventEmitter } from 'events';
-
-interface UdpSocketOptions {
-    port?: number;  /** default 0 (ephemeral) */
-    reuseAddr?: boolean;  /** default true */
-    broadcastAddr?: string;  /** default "255.255.255.255" */
-}
-
-interface UdpRetryOptions {
-    retryCount?: number;  /** default 3 */
-    retryDelay?: number;  /** ms between retries, default 100 */
-    responseTimeout?: number;  /** ms to wait for response, default 1000 */
-}
-
-class UdpSocket extends EventEmitter {
-    constructor(options?: UdpSocketOptions);
-
-    // Lifecycle
-    bind(): Promise<void>;
-    close(): void;
-
-    // Runtime config
-    setRetryOptions(options: UdpRetryOptions): void;
-    getRetryOptions(): UdpRetryOptions;
-
-    // Send
-    send(ip: string, port: number, data: Buffer): void;  /** fire-and-forget */
-    broadcast(data: Buffer, port?: number): void;
-
-    // Events:
-    // 'message' (data: Buffer, rinfo: { address: string, port: number })
-    // 'error' (err: Error)
-    // 'bound' ()
-}
-
-// Future: UdpProxy for web server bridge
-// class UdpProxyServer { ... }
-```
-
----
-
-## colorlib API (separate package)
-
-Generic color conversion library. No LIFX specifics.
-
-```typescript
-// Types
-interface RGB { r: number; g: number; b: number; }  /** 0-255 */
-interface HSL { h: number; s: number; l: number; }  /** h: 0-360, s/l: 0-100 */
-interface HSB { h: number; s: number; b: number; }  /** h: 0-360, s/b: 0-100 */
-interface HSBK { h: number; s: number; b: number; k: number; }  /** k: 1500-9000 Kelvin */
-
-// Conversions
-function rgbToHsl(rgb: RGB): HSL;
-function hslToRgb(hsl: HSL): RGB;
-function rgbToHsb(rgb: RGB): HSB;
-function hsbToRgb(hsb: HSB): RGB;
-function hsbToHsbk(hsb: HSB, kelvin?: number): HSBK;  /** default 3500K */
-function kelvinToRgb(kelvin: number): RGB;  /** approximate white point */
-
-// Parsing - flexible input
-function parseColor(input: string | RGB | HSL | HSB | HSBK | number): HSBK;
-// Accepts: "#ff0000", "rgb(255,0,0)", "red", {r,g,b}, {h,s,l}, {h,s,b,k}, 6500 (kelvin)
-
-// 16-bit wire format conversion
-function hsbkTo16(hsbk: HSBK): HSBK16;  /** h/s/b: 0-0xFFFF, k: 1500-9000 */
-function hsbk16ToHsbk(hsbk16: HSBK16): HSBK;
-```
-
----
-
-## lxlan API
-
-### LxClient - Main Entry Point
-
-```typescript
-import { EventEmitter } from 'events';
-
-interface LxClientOptions {
-    port?: number;  /** default 56700 */
-    broadcastAddr?: string;  /** default "255.255.255.255" */
-    discoveryInterval?: number;  /** ms, 0 = manual only */
-}
-
-class LxClient extends EventEmitter {
-    constructor(options?: LxClientOptions);
-
-    // Lifecycle
-    start(): void;
-    stop(): void;
-
-    // Runtime configuration
-    setRetryOptions(options: { retryCount?: number; retryDelay?: number; responseTimeout?: number }): void;
-    getRetryOptions(): { retryCount: number; retryDelay: number; responseTimeout: number };
-
-    // Discovery
-    discover(): void;
-
-    // Device access (sync - reads cache)
-    devices: Map<string, LxDevice>;
-    getDevice(mac: string): LxDevice;
-    addDevice(mac: string, ip: string, port?: number): LxDevice;  /** manual registration */
-
-    // Events:
-    // 'device'   (device: LxDevice)              - new device discovered
-    // 'message'  (device: LxDevice, msg: LxMessage) - any message from device
-    // 'state'    (device: LxDevice)              - state message (always emits)
-    // 'power'    (device: LxDevice)              - power message
-    // 'label'    (device: LxDevice)              - label changed
-    // 'group'    (device: LxDevice)              - group info received
-    // 'location' (device: LxDevice)              - location info received
-    // 'online'   (device: LxDevice)              - device online
-    // 'offline'  (device: LxDevice)              - device offline
-    // 'error'    (error: Error)                  - transport/protocol error
-}
-```
-
-### LxDevice - Device Abstraction
-
-```typescript
-interface LxDevice {
-    // Identity
-    mac: string;
-    ip: string;
-    port: number;
-    label: string;
-
-    // Cached state
-    power: boolean;
-    color: HSBK;
-    online: boolean;
-    lastSeen: number;
-
-    // Product info
-    vendor: number;
-    product: number;
-    productName: string;
-
-    // Commands - fire-and-forget with auto-retry
-    setPower(on: boolean): void;
-    setColor(color: string | RGB | HSL | HSB | HSBK | number, duration?: number): void;
-    setWhite(kelvin: number, brightness?: number, duration?: number): void;
-
-    // Queries - trigger fetch, results via events
-    getState(): void;
-    getPower(): void;
-
-    // Label/Group/Location (supported but not fundamental)
-    setLabel(label: string): void;
-    getLabel(): void;
-    setGroup(id: string, label: string): void;
-    getGroup(): void;
-    setLocation(id: string, label: string): void;
-    getLocation(): void;
-
-    // Cached group/location info
-    group: { id: string; label: string; updatedAt: number };
-    location: { id: string; label: string; updatedAt: number };
-
-    // Raw
-    send(type: number, payload?: Buffer): void;
-}
-```
-
-### LxProtocol - Message Encoding
-
-```typescript
-enum LxMessageType {
-    GetService = 2,
-    StateService = 3,
-    GetPower = 20,
-    SetPower = 21,
-    StatePower = 22,
-    GetLabel = 23,
-    SetLabel = 24,
-    StateLabel = 25,
-    GetVersion = 32,
-    StateVersion = 33,
-    GetLocation = 48,
-    SetLocation = 49,
-    StateLocation = 50,
-    GetGroup = 51,
-    SetGroup = 52,
-    StateGroup = 53,
-    Get = 101,
-    SetColor = 102,
-    State = 107,
-}
-
-interface LxMessage {
-    size: number;
-    tagged: boolean;
-    source: number;
-    target: string;
-    sequence: number;
-    type: LxMessageType;
-    payload: Buffer;
-}
-
-function encodeMessage(msg: Partial<LxMessage>): Buffer;
-function decodeMessage(data: Buffer): LxMessage;
-```
-
----
-
-## Usage Examples
-
-### Basic Discovery and Control
-
-```typescript
-import { LxClient } from '@bobfrankston/lxlan';
-
-const client = new LxClient();
-
-client.on('device', (device) => {
-    console.log(`Found: ${device.label} (${device.mac})`);
-});
-
-client.on('state', (device) => {
-    console.log(`${device.label}: power=${device.power}`);
-});
-
-client.start();
-client.discover();
-
-// Adjust for slow network
-client.setRetryOptions({ retryCount: 5, responseTimeout: 10000 });
-
-// Control
-const bulb = client.getDevice('d0:73:d5:xx:xx:xx');
-bulb.setPower(true);
-bulb.setColor('#ff0000', 1000);
-bulb.setWhite(2700, 80);
-```
-
----
-
-## LIFX Protocol Summary
-
-### Header (36 bytes)
-- Frame: size, protocol, tagged, source
-- Address: target MAC, sequence
-- Protocol: message type
-
-### Color (HSBK) - 8 bytes
-| Field | Bits | Range | Maps to |
-|-------|------|-------|---------|
-| Hue | 16 | 0-65535 | 0-360° |
-| Saturation | 16 | 0-65535 | 0-100% |
-| Brightness | 16 | 0-65535 | 0-100% |
-| Kelvin | 16 | 1500-9000 | temp |
-
----
-
-## File Structure
-
-```
-lxudp/
-├── index.ts
-├── socket.ts         - UdpSocket class
-├── address.ts        - getBroadcastAddresses(), computeBroadcast()
-├── types.ts
-├── package.json
-└── tsconfig.json
-
-colorlib/
-├── index.ts
-├── convert.ts
-├── parse.ts
-├── types.ts
-├── package.json
-└── tsconfig.json
-
-lxlan/
-├── index.ts
-├── client.ts
-├── device.ts
-├── protocol.ts
-├── types.ts
-├── package.json
-└── tsconfig.json
-```
-
-## Implementation Order
-
-1. **lxcolor** - pure color math
-2. **lxudp** - UDP transport with retry
-3. **lxlan/types.ts, protocol.ts** - message handling
-4. **lxlan/device.ts, client.ts** - device abstraction
-5. **tests/** - discovery, control
-
----
-
-## Future - v2 Considerations
-
-### Multizone Support (LIFX Beam, Z strips)
-Multizone devices have individually addressable LED segments.
-
-**Additional message types:**
-| Type | Name | Description |
-|------|------|-------------|
-| 501 | SetColorZones | Set color for zone range |
-| 502 | GetColorZones | Query zone colors |
-| 503 | StateZone | Single zone response |
-| 506 | StateMultiZone | Multiple zones response |
-
-**API additions for LxDevice:**
-```typescript
-interface LxDevice {
-    // Multizone properties
-    zoneCount: number;  /** 0 = not multizone */
-    zones: HSBK[];  /** cached zone colors */
-
-    // Multizone commands
-    setZoneColor(start: number, end: number, color: HSBK, duration?: number): void;
-    getZones(start?: number, end?: number): void;
-}
-```
-
-**Events:**
-- `'zones'` (device: LxDevice) - zone state updated
-
-### UDP Web Proxy (lxudp-server)
-HTTP/WebSocket server exposing UDP operations for browsers.
-```typescript
-// Future API sketch
-const proxy = new UdpProxyServer({ httpPort: 8080 });
-proxy.start();
-// Browser: ws://localhost:8080/udp
-```
-
-### Related: y:\dev\homecontrol\utils\netsupport
-Evaluate overlap with existing netsupport utilities. lxudp may complement or replace portions.
-
----
-
-## Separate Future Project: lxhttp
-
-**Entirely separate library** - LIFX Cloud HTTP API. Not part of lxlan.
-
-### Purpose
-- Enumerate devices including **offline** ones (cloud knows all registered devices)
-- Alternative control path when LAN unavailable
-- Account-level operations
-
-### Key Differences from lxlan
-| Aspect | lxlan (UDP) | lxhttp (Cloud) |
-|--------|-------------|----------------|
-| Offline devices | No | Yes |
-| Latency | ~ms | ~100ms+ |
-| Rate limits | None | Yes (cloud) |
-| Auth | None | OAuth token |
-| Local network | Required | Not required |
-
-### API Sketch (future)
-```typescript
-class LxHttpClient extends EventEmitter {
-    constructor(token: string);
-
-    listDevices(): void;  /** includes offline */
-    getDevice(id: string): void;
-    setPower(id: string, on: boolean): void;
-    setColor(id: string, color: HSBK, duration?: number): void;
-    // ... similar to lxlan but via HTTP
-}
-```
-
-### lxmanager (future app)
-Application using **both** lxlan and lxhttp:
-- lxhttp for full device enumeration (including offline)
-- lxlan for fast local control
-- External database for device/group management
-- Device labels set to factory-default-based names
-
----
-
-## UDP Proxy for Android/Browser
-
-Android and browsers cannot send UDP directly. Need a local proxy server.
-
-### Architecture
-```
-┌──────────────┐     HTTP/WS      ┌──────────────┐      UDP       ┌──────────┐
-│ Android App  │ ◄──────────────► │  UDP Proxy   │ ◄────────────► │  LIFX    │
-│ or Browser   │                  │  (Node.js)   │                │  Bulbs   │
-└──────────────┘                  └──────────────┘                └──────────┘
-```
-
-### Proxy REST API (suggested)
-
-**Discovery**
-```
-POST /discover
-  → triggers broadcast, returns immediately
-
-GET /devices
-  → returns cached device list
-
-GET /devices/:mac
-  → returns single device state
-```
-
-**Control**
-```
-POST /devices/:mac/power
-  Body: { "on": true }
-
-POST /devices/:mac/color
-  Body: { "color": "#ff0000", "duration": 1000 }
-  Body: { "color": { "h": 120, "s": 100, "b": 100 }, "duration": 500 }
-  Body: { "kelvin": 2700, "brightness": 80 }
-
-POST /devices/:mac/label
-  Body: { "label": "Kitchen Light" }
-```
-
-**Events (WebSocket)**
-```
-WS /events
-  → receives: { "event": "state", "mac": "d0:73:...", "device": {...} }
-  → receives: { "event": "device", "mac": "d0:73:...", "device": {...} }
-  → receives: { "event": "offline", "mac": "d0:73:..." }
-```
-
-### Implementation Notes
-- Proxy uses lxlan internally
-- Stateless HTTP for commands
-- WebSocket for real-time events
-- Single proxy instance per LAN
-- Can run on Raspberry Pi, NAS, or any Node.js host
-
----
-
-## LIFX Cloud HTTP API Reference
-
-Official API: https://api.lifx.com/
-
-### Authentication
-```
-Authorization: Bearer <token>
-```
-Get token from https://cloud.lifx.com/settings
-
-### Key Endpoints
-```
-GET  /v1/lights/all                    → list all devices
-GET  /v1/lights/:selector              → get device(s) state
-PUT  /v1/lights/:selector/state        → set power/color/brightness
-POST /v1/lights/:selector/toggle       → toggle power
-POST /v1/lights/:selector/effects/...  → effects (breathe, pulse, etc.)
-```
-
-### Selector Format
-- `all` - all devices
-- `id:d073d5xxxxxx` - by device ID
-- `label:Kitchen` - by label
-- `group:Living Room` - by group
-- `location:Home` - by location
-
-### Rate Limits
-- 120 requests per 60 seconds per token
-- Responses include `X-RateLimit-*` headers