Skip to content

Web Interface Guide

Overview

The LIFX Emulator includes a modern web interface built with SvelteKit for real-time monitoring and device management. The dashboard uses WebSocket for instant updates, eliminating polling delays, and provides a browser-based alternative to the REST API.

Access: Open http://localhost:8080 in your web browser (after starting the emulator with --api)

Technology: Built with SvelteKit and real-time WebSocket updates for instant state synchronization

Getting Started

Enable the Web Interface

# Start emulator with API (enables web interface)
lifx-emulator --api

# Custom host and port
lifx-emulator --api --api-host 127.0.0.1 --api-port 9090

# Then open in browser:
# http://localhost:8080
# or http://127.0.0.1:9090

Interface Layout

The web interface features a dark theme by default (with light and system theme options) and is organized into four main sections:

Server Statistics Card (Top Left)

Displays real-time emulator health metrics:

Server Statistics
├─ Uptime: 123s
├─ Devices: 3
├─ Packets RX: 1250
├─ Packets TX: 2100
└─ Errors: 0

Metrics:

  • Uptime: Time since server started (auto-updating)
  • Devices: Number of currently emulated devices
  • Packets RX: Total packets received from LIFX clients
  • Packets TX: Total packets sent to LIFX clients
  • Errors: Total packet processing errors

Use Cases:

  • Verify API server is running
  • Monitor packet flow during testing
  • Check for errors during protocol testing

Device Management Card (Top Right)

Manage devices with unified toolbar:

Device Management                              [Remove All]
├─ Product: [dropdown menu] [Add Device button]

Features:

  • Dropdown list of all available products (137+ options)
  • Serial numbers are auto-generated
  • Remove All button with confirmation (disabled when no devices exist)
  • Instant WebSocket updates when devices are added/removed

Use Cases:

  • Quick device creation for testing
  • Create multiple device types without CLI
  • Bulk removal of all devices
  • Test with different device configurations

Devices Section

Displays all emulated devices with detailed status:

Devices (3)                                    [Remove All]

┌─ Device Card ─────────────────────────────────────────┐
│ d073d5000001                                    [Del]  │
│ Living Room Light                                      │
│                                                        │
│ [ON]  [P27]  [color]  [multizone×16]  [HEV]         │
│                                                        │
│ ▸ Show metadata  (click to expand)                    │
│ ▸ Show zones (16)  (click to expand)                 │
└────────────────────────────────────────────────────────┘

Device Card Components

Header:

  • Device serial number (clickable, displays copy tooltip)
  • Device label (e.g., "Living Room Light")
  • Delete button (red, with confirmation)

Status Badges:

  • Power status: [ON] (green) or [OFF] (gray)
  • Product ID: [P27] (light blue)
  • Capabilities: [color], [multizone×16], [HEV], etc.
  • Extended multizone: [extended-mz×80] (green)

Expandable Metadata (click "▸ Show metadata"): 

Firmware: 3.70
Vendor: 1
Product: 27
Capabilities: Color, Multizone (16 zones)
Group: (empty)
Location: (empty)
Uptime: 123s
WiFi Signal: -45.5 dBm

Color/Zone Display:

For color lights: 

▸ Show zones
  ■ Current color

For multizone devices: 

▸ Show zones (16)  (click to expand)
  [colored strips representing each zone]

For matrix/tile devices: 

▸ Show tiles (5)  (click to expand)
  ┌──────────┐
  │ T1       │  (8×8 zone grid)
  │ ████████ │
  │ ████████ │
  │ ████████ │
  │ ████████ │
  │ ████████ │
  │ ████████ │
  │ ████████ │
  │ ████████ │
  └──────────┘
  (repeats for each tile)

Zone Display:

  • Each zone shown as a colored segment
  • Colors represent current HSBK values
  • Heights approximately proportional to brightness
  • Saturation affects color intensity
  • Hue determines the color

Recent Activity Log (Bottom)

Displays the last 100 LIFX protocol packets in real-time with filtering capabilities:

Recent Activity

Direction: [All ▼]  Device/Target: [______]  Packet: [______]  [Clear]

12:34:56  RX  GetColor           d073d5000001  192.168.1.100:54321
12:34:56  TX  State              d073d5000001  192.168.1.100:54321
12:34:57  RX  GetPower           d073d5000002  192.168.1.101:54322
12:34:57  TX  StatePower         d073d5000002  192.168.1.101:54322

Activity Event Fields:

  • Time: HH:MM:SS (local time)
  • Direction:
  • RX (blue) - Received from client
  • TX (orange) - Transmitted to client
  • Packet Name: Human-readable LIFX packet type (e.g., "GetColor", "SetColor")
  • Device: Target device serial number
  • Address: Client IP address and port

Filtering Options:

  • Direction: Filter by RX (received) or TX (transmitted)
  • Device/Target: Text filter for device serial numbers
  • Packet: Text filter for packet names (e.g., "GetColor", "SetPower")
  • Clear: Reset all filters to show all activity

Filters are applied in real-time as you type, with instant feedback.

Use Cases:

  • Debugging LIFX client communication
  • Verifying packet flow for specific devices
  • Monitoring specific packet types
  • Identifying communication problems
  • Isolating RX vs TX traffic

Note: Activity log is only visible if activity logging is enabled (--api-activity flag, default: true). Disable to reduce server traffic.

Common Tasks

Add a New Device

  1. Open the web interface: http://localhost:8080
  2. Find the "Add Device" card (top right)
  3. Select a product from the dropdown menu
  4. Click "Add Device" button
  5. New device appears in the Devices section with auto-generated serial

The device is immediately available to LIFX clients and is added to the emulator runtime.

Check Device Status

  1. Locate device in the Devices section
  2. Check power badge ([ON] or [OFF])
  3. Check capability badges (color, multizone, matrix, HEV, etc.)
  4. Click "▸ Show metadata" to view:
  5. Firmware version
  6. Product ID and vendor
  7. Assigned group and location
  8. Device uptime
  9. WiFi signal strength

View Multizone Colors

For multizone devices (strips, beams):

  1. Locate device in Devices section
  2. Click "▸ Show zones" to expand
  3. Colored bar displays all zone colors
  4. Each segment represents one zone
  5. Color indicates current HSBK values
  6. Click again to collapse

Color Interpretation:

  • Hue (0-360°): Color wheel position
  • Saturation (0-100%): Color intensity (white to saturated)
  • Brightness (0-100%): Light intensity
  • Kelvin (1500-9000K): Color temperature

View Tile/Matrix Colors

For matrix devices (tiles, candles, ceiling):

  1. Locate device in Devices section
  2. Click "▸ Show tiles" to expand
  3. Grid display shows zone colors
  4. Each small square is one zone
  5. Tiles labeled T1, T2, etc.
  6. Click again to collapse

Monitor Packet Activity

  1. Scroll to "Recent Activity" section (bottom)
  2. Watch for real-time WebSocket packet updates
  3. Use filter controls to narrow down activity:
  4. Direction dropdown: Select "All", "RX", or "TX"
  5. Device/Target filter: Type device serial to filter (e.g., "d073d5000001")
  6. Packet filter: Type packet name to filter (e.g., "GetColor", "Power")
  7. Clear button: Reset all filters

Filter Examples:

# Show only received packets
Direction: RX

# Show only packets for specific device
Device/Target: d073d5000001

# Show only power-related packets
Packet: Power

# Combine filters: RX packets for GetColor on device d073d5000001
Direction: RX
Device/Target: d073d5000001
Packet: GetColor

Common Packet Patterns: 

RX GetService (broadcast)     <- Client discovering devices
TX StateService (response)    <- Device responds

RX GetColor                   <- Client querying color
TX State (color response)     <- Device responds

RX SetColor + params          <- Client setting new color
TX Acknowledgment             <- Device confirms

RX GetPower                   <- Client querying power
TX StatePower                 <- Device responds

Remove a Device

Remove Single Device:

  1. Locate device in Devices section
  2. Click red "Del" button on device card
  3. Confirm deletion in prompt
  4. Device disappears from list
  5. Device stops responding to LIFX protocol packets

Remove All Devices:

  1. Click "Remove All" button (top right of Devices section)
  2. Confirmation dialog shows: "Remove all X device(s)?"
  3. Click OK to confirm
  4. All devices removed from runtime

Features and Capabilities

Real-Time Updates via WebSocket

  • Instant updates - no polling delay
  • Server statistics pushed every second
  • Device changes reflected immediately
  • Activity events stream in real-time
  • Automatic reconnection on connection loss
  • No manual refresh needed

Persistent UI State

The interface remembers your preferences:

  • Zone/tile display states (expanded/collapsed) per device
  • Metadata display states (expanded/collapsed) per device
  • Preferences stored in browser localStorage
  • Persists across page reloads
  • Per-device basis (no global toggle)

Color Display

Colors are displayed accurately:

  • HSBK to RGB conversion for display
  • Hue: Color wheel position
  • Saturation: Intensity/purity
  • Brightness: Light level
  • Kelvin: Color temperature (white point)

Modern UI Design

  • Theme support: Dark (default), Light, and System themes
  • Theme toggle in header (☀/☾/◐ icon)
  • Theme preference persisted in browser localStorage
  • Adapts to different screen sizes
  • Device cards responsive grid layout
  • Touch-friendly on tablets
  • Built with SvelteKit for optimal performance

Performance Considerations

Activity Logging Impact

Activity logging has performance implications:

# Disable activity logging (reduces traffic)
lifx-emulator --api --api-activity=false

# Activity endpoint returns 503 Service Unavailable when disabled
curl http://localhost:8080/api/activity
# Response: 503 Service Unavailable

Optimal Configuration for Monitoring

# Balance between visibility and performance
lifx-emulator --api \
  --api-host 127.0.0.1 \  # Limit to localhost if not needed on network
  --api-port 8080

Browser Performance

For emulators with many devices (50+):

  • WebSocket updates are efficient and low-overhead
  • Activity log filtering helps focus on relevant events
  • Consider disabling activity logging (--api-activity=false) for extreme load
  • SvelteKit's reactive system provides excellent performance
  • Use REST API directly for automated monitoring if needed

Troubleshooting

Web Interface Not Loading

# Check if API server is running
curl http://localhost:8080/api/stats

# Check if port is correct
# Default: http://localhost:8080
# Custom: http://localhost:9090  (if --api-port 9090)

Activity Log Not Updating

  • Ensure --api-activity is not disabled (default: enabled)
  • Check WebSocket connection status in header (should show green indicator)
  • Check browser developer console for WebSocket errors
  • Verify WebSocket endpoint is accessible: ws://localhost:8080/ws
  • Try refreshing page to reconnect WebSocket

Devices Not Appearing

# Verify devices exist via API
curl http://localhost:8080/api/devices | jq

# Check emulator logs for creation errors
# Device should appear in response

Zones Not Displaying

For multizone devices:

  • Click "▸ Show zones" to expand display
  • Ensure device has has_multizone: true
  • Check that zone_count > 0 and zone_colors array is populated

For tile/matrix devices:

  • Click "▸ Show tiles" to expand display
  • Ensure device has has_matrix: true
  • Check that tile_count > 0 and colors are populated

Browser Compatibility

Tested and Supported:

  • Chrome/Chromium 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Required:

  • JavaScript enabled (ES2022+ features)
  • WebSocket support
  • LocalStorage for UI state and theme persistence
  • CSS Grid and Custom Properties support

Security Considerations

The web interface provides no authentication or authorization:

  • Intended for local development/testing only
  • No user login required
  • All operations available to anyone with network access
  • Consider firewall rules if on shared network
  • Use --api-host 127.0.0.1 for localhost-only access

Advanced Features

Serial Number Details

Each device has a unique 12-character hexadecimal serial:

  • Default prefix: d073d5
  • Default range: d073d5000001 - d073d5999999
  • Can be customized with --serial-prefix and --serial-start CLI flags

Product IDs

Common products:

  • 27: LIFX A19 (color light)
  • 29: LIFX A19 Night Vision (infrared)
  • 32: LIFX Z (multizone strip)
  • 38: LIFX Beam (extended multizone)
  • 50: LIFX Mini White to Warm (color temperature)
  • 55: LIFX Tile (matrix/tile device)
  • 90: LIFX Clean (HEV)

See lifx-emulator list-products for complete list.