Innerscene Developer API

Once an Innerscene fixture - Circadian Sky or Virtual Sun - is connected to your local Wi-Fi network, it exposes a small HTTP server on the LAN. You can read its status and drive its color and brightness from any device on the same network using ordinary GET and POST requests - no SDK, no cloud round-trip, no account.

This guide walks through the four prerequisites - updating the firmware, joining Wi-Fi, finding the IP address, and choosing a command - and then provides a complete reference for every publicly-supported endpoint along with copy-and-paste examples in Node.js and Python.

1. Update the fixture firmware

The HTTP endpoints described in this guide require recent firmware. Before you start, update each fixture using Innerscene Studio (the iOS app):

• Install Innerscene Studio from the iOS App Store.
• Open Innerscene Studio within Bluetooth range of the fixture and tap it in the device list to connect.
• Open Settings → Firmware Updates. If a newer build is available the app will prompt you to install it; the fixture reboots automatically when the update finishes.

You can confirm the running version at any time with GET /getVersion after Wi-Fi is configured.

2. Connect the fixture to Wi-Fi

Wi-Fi is configured from the fixture's built-in web interface, which Innerscene Studio reaches over Bluetooth. The full step-by-step instructions - including SSID selection, password entry, and the captive-portal flow - are documented in the User Guide (the same guide applies to Virtual Sun - append ?product=virtual-sun to the URL).

3. Find the fixture's IP address

Once joined to Wi-Fi, every fixture is assigned an IP address by your router. There are several ways to find it:

• From Innerscene Studio. Connect to the fixture, open Settings → Wi-Fi. The current IP address is shown alongside the connected SSID. The fixture's MAC address is shown on the same screen and on the device-info page.
• From your router's client list. Look it up by MAC address - copy the MAC from Innerscene Studio and match it against the connected-clients table in your router's admin UI. Each fixture also broadcasts its own Wi-Fi network with the SSID Innerscene-<type>-<mac> (for example Innerscene-pri-a4cf12ab34cd), where type reflects the fixture's role or daughterboard: pri (primary), sub (secondary), cas (Casambi), dmx, dali, 0-10, cal, hub. This SSID can be used to identify nearby fixtures from your phone's Wi-Fi scan.
• By scanning your subnet. Every Circadian Sky fixture responds to /getVersion, so the quickest way to enumerate fixtures from a Mac, Linux, or Windows-with-WSL machine is:

# Replace 192.168.1 with your subnet. Returns IPs that respond to /getVersion.
for n in $(seq 1 254); do
  ip="192.168.1.$n"
  curl -s -m 0.4 "http://$ip/getVersion" \
    | grep -q '"version"' && echo "$ip"
done

Once you have an IP, verify the fixture is reachable:

$ curl http://192.168.1.42/getVersion
{"version": "2.4.1", "build_date": "Apr 30 2026", "build_time": "14:22:08", ...}

If you plan to control a fixture from a long-running script, reserve its IP in your router's DHCP settings so it does not change.

4. Send your first command

Every fixture interaction is a single HTTP request. Most endpoints are GET requests with parameters in the query string and return JSON. The example below disables the circadian schedule and sets the fixture to 4500 K at 50% brightness:

curl "http://192.168.1.42/setSchedule?mode=0"
curl "http://192.168.1.42/setCCT?cct=4500&i=0.5"

The first call exits the automatic schedule so manual commands are honored, and the second sets the color temperature and brightness. Skip ahead to Examples for full Node.js and Python programs.

API Reference

All endpoints are served from the fixture's IP on port 80. JSON is the default response format. Parameters are passed as URL query parameters (for both GET and POST requests).

Every write endpoint listed below takes effect immediately - no reboot is required. Configuration changes are applied to the running fixture and saved to non-volatile storage in the same call. The only way to reboot is the explicit /restart endpoint.

Status & Identity

Tap any endpoint to expand its parameters, example request, and example response.

curl http://192.168.1.42/getVersion

{
  "version": "2.4.1",
  "build_date": "Apr 30 2026",
  "build_time": "14:22:08",
  "build_timestamp": "6814a3e0",
  "sdk": "5.1.2"
}

curl "http://192.168.1.42/getStatus"

{
  "timezone": "America/Los_Angeles",
  "utc_time": "2026-05-07T18:42:12Z",
  "cct": 4500, "lux": 1280, "nlux": 0.45000000,
  "mac": "a4:cf:12:ab:34:cd",
  "cs": 0, "toff": 0.00, "flags": 1, "puc": 7, "ls": 1,
  "m": 0, "wx": 0,
  "ssc": 0, "msc": 0, "esc": 0,
  "as": 0, "dv1": 0.0, "dv2": 0.0,
  "gc": 0, "ir": -1, "sss": 0,
  "fr": 0, "ddb": 0, "rc": 6
}

curl http://192.168.1.42/getDeviceCapabilities

{
  "cct": { "min": 1800, "max": 20000 },
  "lux": { "min": 0,    "max": 4000 }
}

curl http://192.168.1.42/getLuxCurve

{
  "curve": [
    [1800, 1200],
    [2400, 2400],
    [3000, 3200],
    [4000, 3900],
    [5000, 4000],
    [6500, 3800],
    [10000, 3100],
    [20000, 1900]
  ]
}

curl http://192.168.1.42/getTemp

{
  "adc_raw": 1843,
  "adc_cal": 1521,
  "degC": 42.18
}

curl http://192.168.1.42/getUpTime

84326

curl http://192.168.1.42/getDBInfo

{
  "type": 1,
  "longDescription": "Dual 0-10V",
  "wifiDescription": "0-10",
  "adc": 2147,
  "dbInt": 0
}

Light Control

curl http://192.168.1.42/getCCT

{
  "cct": 4500,
  "i": 0.450000,
  "lux": 1280.000000
}

# Set 4500 K at 50% brightness
curl "http://192.168.1.42/setCCT?cct=4500&i=0.5"

# Set 3000 K at an absolute 800 lux
curl "http://192.168.1.42/setCCT?cct=3000&lux=800"

1

curl "http://192.168.1.42/previewCCT?cct=2700&i=0.3"

1

# Resume automatic schedule
curl "http://192.168.1.42/setSchedule?mode=1"

# Switch to manual control
curl "http://192.168.1.42/setSchedule?mode=0"

1

curl "http://192.168.1.42/setFade?on=1"

1

# Blink this fixture
curl http://192.168.1.42/identify

# Blink a different fixture by MAC
curl "http://192.168.1.42/identify?mac=a4cf12ab34cd"

1

curl "http://192.168.1.42/restart?delay=2000"

true

Direct Channel Control

The fixture exposes four PWM-driven channels, addressed as c0 through c3. Each accepts a 12-bit duty value (0–4095). The spectral mapping of each channel is product-specific and not published — if you need precise spectral control, characterise the output with a spectrometer.

curl http://192.168.1.42/getChannels

[1820, 1145, 0, 312]

# Drive only c3 at ~25%, all others off
curl "http://192.168.1.42/setChannels?c0=0&c1=0&c2=0&c3=1024"

# Tune just one channel without touching the others
curl "http://192.168.1.42/setChannels?c2=512"

0

Time & Schedule

curl "http://192.168.1.42/setTimezone?tz=America/Los_Angeles"

1

curl http://192.168.1.42/readClock

{
  "time": "2026-05-07T18:42:12Z",
  "bat": 1
}

External Inputs (Daughterboards)

These endpoints are only meaningful on fixtures fitted with a 0–10 V, DALI, DMX, or Casambi daughterboard. Use /getDBInfo to detect what is installed before calling them.

curl http://192.168.1.42/read010V

{
  "vCCT": 7.42, "vDIM": 5.10,
  "aCCT": 1834, "aDIM": 1265,
  "nCCT": 0.74, "nDIM": 0.51,
  "oCCT": 4500, "oDIM": 0.50,
  "cct_min": 0.5, "cct_max": 9.5,
  "dim_min": 0.5, "dim_max": 9.5,
  "dim_pow": 2.0,
  "mode": 0, "filter": 0,
  "cctSource": 0, "fixedCCT": 4500,
  "schedExitV": 9.0,
  "refCCT": 7.40, "refDIM": 5.05
}

# Linear-dim calibration with full range 0.5–9.5 V
curl "http://192.168.1.42/set010VParams?dim_min=0.5&dim_max=9.5&dim_pow=1&persistent=1"

1

curl "http://192.168.1.42/setDaliParams?cct_min=2700&cct_max=6500&persistent=1"

1

curl "http://192.168.1.42/setDMXParams?baseAddress=24&mode=1&persistent=1"

1

curl http://192.168.1.42/read_DMX

{
  "baseAddress": 24,
  "dip_addr": 24,
  "mode_flags": 1,
  "changeTime": 142,
  "index": 1,
  "oldValue": 128,
  "newValue": 200,
  "cct": [180, 4500],
  "dim": [200, 0.78],
  "schedule": 0,
  "inSchedule": 0
}

curl http://192.168.1.42/casambiInfo

{
  "ua": "AA:BB:CC:DD:EE:FF",
  "nu": "11:22:33:44:55:66",
  "fid": 12345,
  "fwv": "37.20",
  "uid": 12, "sm": 0, "smn": "Idle", "ir": 1,
  "cmin": 2200, "cmax": 6500,
  "fmin": 1800, "fmax": 20000,
  "lon": -118.2437, "lat": 34.0522, "tzo": -480,
  "rt": "2026-05-07T11:42:12",
  "d": 0.500, "k": 4500, "y": 1
}

Network & Peers

curl http://192.168.1.42/getIPs

[
  ["sta", "WIFI_STA_DEF",
   "192.168.1.42", "255.255.255.0", "192.168.1.1"],
  ["ap", "WIFI_AP_DEF",
   "172.30.0.1",   "255.255.255.0", "172.30.0.1"],
  "a4:cf:12:ab:34:cd",
  "Innerscene-pri-a4cf12ab34cd"
]

curl http://192.168.1.42/getAPInfo

{
  "sta": {
    "ssid": "MyHomeNetwork",
    "passwd": "********",
    "bssid": "f0:9f:c2:11:22:33",
    "channel": 6,
    "authmode": 3,
    "rssi": -54
  },
  "ap": {
    "ssid": "Innerscene-pri-a4cf12ab34cd",
    "passwd": "innerscene",
    "channel": 6,
    "authmode": 3,
    "ssid_hidden": 0,
    "max_connection": 4,
    "beacon_interval": 1000
  }
}

apMac,ipv4,buildTimestamp,flags,wirelessGroup,channel,tempScaled,upTime,rssi

curl http://192.168.1.42/getPeerInfo

{
  "puc": 7,
  "p": [
    "a4cf12ab34cd,2a01a8c0,68142b00,1,3,6,33825,84326,-46",
    "a4cf12ab35ef,2b01a8c0,68142b00,0,3,6,33279,84102,-58"
  ]
}

for s in r.json()["p"]:
    mac, ipv4_hex, build, flags, group, ch, t, up, rssi = s.split(",")
    n = int(ipv4_hex, 16)
    ip = f"{n & 0xff}.{(n>>8) & 0xff}.{(n>>16) & 0xff}.{(n>>24) & 0xff}"
    degC = -20 + (int(t) / 65535) * 120
    is_primary = (int(flags) & 1) == 1

Messages

curl http://192.168.1.42/getMessages

[
  "12,-15,Schedule mode turned on via WebUI",
  "5,-94,Power on : Last CCT, DIM = 4500K, 50%"
]

curl "http://192.168.1.42/clearMessages?type=12"

{"status":"success"}

Examples

Node.js

Discover capabilities, read state, and adjust the fixture:

// fixture.mjs - control an Innerscene fixture from Node.js
//   npm install node-fetch
//   node fixture.mjs 192.168.1.42

import fetch from "node-fetch";

const ip = process.argv[2];
if (!ip) throw new Error("Usage: node fixture.mjs <fixture-ip>");

const base = `http://${ip}`;

async function get(path) {
  const res = await fetch(`${base}${path}`);
  if (!res.ok) throw new Error(`${path} -> HTTP ${res.status}`);
  const text = await res.text();
  try { return JSON.parse(text); } catch { return text; }
}

// 1. Discover what the fixture supports
const caps = await get("/getDeviceCapabilities");
console.log("CCT range :", caps.cct);
console.log("Lux range :", caps.lux);

// 2. Read its current state
const status = await get("/getStatus");
console.log("Now      :", status.cct, "K  ", status.lux, "lux");

// 3. Disable the schedule and set 4500 K at 50% brightness
await get("/setSchedule?mode=0");
await get("/setCCT?cct=4500&i=0.5");

// 4. Blink it to confirm which physical fixture you just controlled
await get("/identify");

A simple sunset routine that fades the fixture from daylight to warm dim over ten minutes:

// Sunset routine: drop from 5000 K / 100% to 2700 K / 10% over 10 minutes.
// Each fade takes ~2 seconds on the fixture; we issue 30 steps over 600 seconds.
import fetch from "node-fetch";

const ip = "192.168.1.42";
const steps = 30;
const totalSeconds = 600;
const startCCT = 5000, endCCT = 2700;
const startI = 1.0,  endI = 0.10;

await fetch(`http://${ip}/setSchedule?mode=0`);

for (let i = 0; i <= steps; i++) {
  const t = i / steps;
  const cct = Math.round(startCCT + (endCCT - startCCT) * t);
  const intensity = (startI + (endI - startI) * t).toFixed(3);
  await fetch(`http://${ip}/setCCT?cct=${cct}&i=${intensity}`);
  await new Promise(r => setTimeout(r, (totalSeconds * 1000) / steps));
}

Python

Same flow as the Node.js example, using requests:

# fixture.py - control an Innerscene fixture from Python
#   pip install requests
#   python fixture.py 192.168.1.42

import sys, json, requests

if len(sys.argv) < 2:
    raise SystemExit("Usage: python fixture.py <fixture-ip>")

base = f"http://{sys.argv[1]}"

def get(path):
    r = requests.get(base + path, timeout=5)
    r.raise_for_status()
    try:
        return r.json()
    except ValueError:
        return r.text

# 1. Discover what the fixture supports
caps = get("/getDeviceCapabilities")
print("CCT range :", caps["cct"])
print("Lux range :", caps["lux"])

# 2. Read its current state
status = get("/getStatus")
print("Now       :", status["cct"], "K  ", status["lux"], "lux")

# 3. Disable the schedule and set 4500 K at 50% brightness
get("/setSchedule?mode=0")
get("/setCCT?cct=4500&i=0.5")

# 4. Blink it to confirm which physical fixture you just controlled
get("/identify")

Continuously print the fixture's state once per second - useful for logging or driving a dashboard:

# Poll the fixture once per second and print CCT + lux
import time, requests

ip = "192.168.1.42"
while True:
    s = requests.get(f"http://{ip}/getStatus", timeout=2).json()
    print(f"{s['utc_time']}  {s['cct']:>5} K  {s['lux']:>5} lux  flags={s['flags']}")
    time.sleep(1)

Home Assistant

Home Assistant can talk to the fixture using its built-in rest_command and rest sensor integrations - no custom integration is required. Add the snippets below to your Home Assistant configuration to expose the fixture as both a callable service and a live sensor.

Outbound commands (set CCT, switch modes, identify, restart):

# configuration.yaml - define outbound commands
rest_command:
  fixture_set_cct:
    url: "http://192.168.1.42/setCCT?cct={{ cct }}&i={{ intensity }}"
    method: GET
  fixture_preview_cct:
    url: "http://192.168.1.42/previewCCT?cct={{ cct }}&i={{ intensity }}"
    method: GET
  fixture_schedule:
    url: "http://192.168.1.42/setSchedule?mode={{ mode }}"
    method: GET
  fixture_identify:
    url: "http://192.168.1.42/identify"
    method: GET
  fixture_restart:
    url: "http://192.168.1.42/restart"
    method: GET

Once defined, call them from automations, scripts, or dashboards:

- service: rest_command.fixture_set_cct
  data: { cct: 4500, intensity: 0.5 }

Pull live state into Home Assistant entities so you can graph CCT, lux, and temperature over time, or use them as automation triggers:

# configuration.yaml - pull live state into Home Assistant
sensor:
  - platform: rest
    name: Office Fixture
    resource: "http://192.168.1.42/getStatus"
    scan_interval: 10
    value_template: "{{ value_json.cct }}"
    unit_of_measurement: "K"
    json_attributes:
      - cct
      - lux
      - nlux
      - flags
      - ls         # 1 = schedule active, 0 = manual
      - utc_time
      - mac

  - platform: rest
    name: Office Fixture Temperature
    resource: "http://192.168.1.42/getTemp"
    scan_interval: 60
    value_template: "{{ value_json.degC }}"
    unit_of_measurement: "°C"
    device_class: temperature

Example automations - a sunset fade and an auto-resume on motion:

# automations.yaml - fade to warm dim 30 min before sunset
- alias: Office fixture sunset fade
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"
  action:
    - service: rest_command.fixture_schedule
      data: { mode: 0 }                    # exit automatic schedule
    - service: rest_command.fixture_set_cct
      data: { cct: 2700, intensity: 0.15 }

# Resume the schedule when motion is detected after a manual override
- alias: Office fixture resume schedule on motion
  trigger:
    - platform: state
      entity_id: binary_sensor.office_motion
      to: "on"
  condition:
    - condition: state
      entity_id: sensor.office_fixture
      attribute: ls
      state: 0
  action:
    - service: rest_command.fixture_schedule
      data: { mode: 1 }

Notes & Caveats

• Manual overrides exit the schedule. Calling /setCCT takes the fixture out of automatic mode. Re-enable the schedule with /setSchedule?mode=1 when you are done.
• Use previewCCT for sliders. If a user is dragging a UI control, previewCCT avoids permanently disabling the schedule and self-clears after a few seconds of inactivity.
• Poll at most a few times per second. /getStatus is cheap, but the fixture is a small embedded device. One poll every 1–2 seconds is plenty for a dashboard.
• Reserve the IP in your router. Long-running automations break if DHCP reassigns the address. Most routers support binding an IP to a MAC.
• Endpoints not in this guide are private. The fixture exposes additional URIs used internally by Innerscene Studio for provisioning, calibration, and OTA updates. They are not part of the supported API and may change between firmware releases. Calling them can corrupt the fixture's calibration state.

Need an endpoint that is not listed? Have a question about integrating with a building-management system? Email [email protected].