Skip to main content
Version: main

Socket Interface

This guide explains how to control lights using the keylightd Unix socket API.

Authentication​

The Unix socket interface relies on Unix socket permissions for security. Only processes running as the same user as keylightd can access the socket, providing inherent security without additional authentication.

Socket Location​

The Unix socket is located at:

  • $XDG_RUNTIME_DIR/keylightd.sock (default on most systems)
  • Or fallback to /run/user/<uid>/keylightd.sock

Listing Lights​

List all discovered lights:

echo '{"action": "list_lights"}' | nc -U /run/user/$(id -u)/keylightd.sock

Response format:

{
  "status": "ok",
  "lights": {
    "Elgato Key Light ABC1._elg._tcp.local.": {
      "id": "Elgato Key Light ABC1._elg._tcp.local.",
      "productname": "Elgato Key Light",
      "serialnumber": "ABC123456",
      "firmwareversion": "1.0.3",
      "firmwarebuild": 194,
      "on": true,
      "brightness": 50,
      "temperature": 5000,
      "ip": "192.168.1.100",
      "port": 9123,
      "lastseen": "2024-03-20T10:00:00Z"
    }
  }
}

Getting Light Information​

Get information about a specific light:

echo '{"action": "get_light", "data": {"id": "LIGHT_ID"}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Response format:

{
  "status": "ok",
  "light": {
    "id": "Elgato Key Light ABC1._elg._tcp.local.",
    "productname": "Elgato Key Light",
    "serialnumber": "ABC123456",
    "firmwareversion": "1.0.3",
    "firmwarebuild": 194,
    "on": true,
    "brightness": 50,
    "temperature": 5000,
    "ip": "192.168.1.100",
    "port": 9123,
    "lastseen": "2024-03-20T10:00:00Z"
  }
}

Controlling Lights​

The socket API supports both single-property mode (property + value) and multi-property mode (on, brightness, temperature directly in data).

Multi-Property Mode​

Set multiple properties in a single request:

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "on": true, "brightness": 80, "temperature": 4500}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Single-Property Mode​

Power Control​

Turn a light on:

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "property": "on", "value": true}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Turn a light off:

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "property": "on", "value": false}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Brightness Control​

Set brightness (0-100):

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "property": "brightness", "value": 75}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Color Temperature Control​

Set color temperature in Kelvin (2900-7000):

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "property": "temperature", "value": 4500}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

Response Formats​

Success Response​

Successful operations return:

{
  "status": "ok"
}

Error Responses​

Error responses include an error message:

{
  "error": "Light not found: LIGHT_ID"
}

Common error messages:

  • "Light not found: X" - The specified light doesn't exist
  • "Device unavailable" - The light device couldn't be reached
  • "Invalid input: X" - The provided input is invalid (e.g., brightness outside 0-100 range)
  • "Missing required parameter: X" - A required parameter is missing

Light Properties​

Controllable Properties​

  • on: Power state (boolean true/false)
  • brightness: Brightness level (integer 0-100)
  • temperature: Color temperature in Kelvin (integer 2900-7000)

Read-only Properties​

  • id: Unique light identifier
  • productname: Product name from the device
  • serialnumber: Device serial number
  • firmwareversion: Firmware version
  • firmwarebuild: Firmware build number
  • ip: IP address of the light
  • port: Port number (usually 9123)
  • lastseen: Timestamp when the light was last seen

Using Python​

Here's an example using Python instead of netcat:

import socket
import json

sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect('/run/user/1000/keylightd.sock')

request = {
    'action': 'set_light_state',
    'data': {
        'id': 'Elgato Key Light ABC1._elg._tcp.local.',
        'property': 'on',
        'value': True
    }
}

sock.sendall(json.dumps(request).encode('utf-8'))
response = sock.recv(4096).decode('utf-8')
result = json.loads(response)
print(result)
sock.close()

Request Format​

All socket requests follow this format:

{
  "action": "action_name",
  "id": "optional-request-id",
  "data": {
    "parameter1": "value1",
    "parameter2": "value2"
  }
}

The id field is optional and will be included in the response if provided.

Multiple Property Changes​

You can set multiple properties in a single request using multi-property mode:

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "on": true, "brightness": 80, "temperature": 3200}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock

The single-property mode (property + value) is also supported for backwards compatibility:

echo '{"action": "set_light_state", "data": {"id": "LIGHT_ID", "property": "brightness", "value": 80}}' | \
  nc -U /run/user/$(id -u)/keylightd.sock