Light

The Light API provides a dedicated handle for a Standard Shelly Light.

API Reference

Method	Description
Light.get(id)	Returns a LightHandle for the light, or null if not found.
light.getStatus()	Returns the light's current status object.
light.getConfig()	Returns the light's config object.
light.setConfig(cfg)	Updates the config. Returns true on success.
light.set(state)	Writes a new state {on, brightness, transition_duration, toggle_after}.
light.on(event, callback)	Registers a listener. Returns a listener id.
light.off(id)	Removes a listener by its id.
light.setWriteOutputState(callback)	Handles every write to the light.

note

The Light API is only available to the component's owner service (identified by the svc property in the script's JWT). Other services cannot obtain a handle for it.

Light.get(id)

Look up a light component and return a handle to it.

const light = Light.get(0);
if (!light) {
  console.log('ERROR: no light:0');
  throw new Error('Light not available');
}

Parameters:

• id — Light component id (0 for the first light).

Returns a LightHandle, or null if the component is not available.

light.getStatus()

Read the light's current status.

const status = light.getStatus();
// { output: true, brightness: 75 }

if (status.output) {
  console.log('Light is on at ' + status.brightness + '%');
}

Returned fields:

• output — Boolean on/off state.
• brightness — Overall brightness (e.g. 0–100).

Every status object also carries id, source, and tag, and may include temperature, transition, and errors when applicable — see the Light component reference for the full shape.

light.getConfig()

Read the light's current configuration.

const cfg = light.getConfig();
console.log('config:', JSON.stringify(cfg));

Returns the configuration object. Notable fields include name, in_mode, initial_state, transition_duration, and night_mode. See the Light component reference for the full shape.

light.setConfig(cfg)

Apply a configuration update. Configs are merged before applying, so you can provide only the values you want to update.

const cfg = light.getConfig();
cfg.name = 'Kitchen light';

const ok = light.setConfig(cfg);
if (!ok) {
  console.log('Failed to update config');
}

Returns true on success, false if the config was rejected.

light.set(state)

Write a new state to the light. Any of the fields below may be provided; fields you omit are left unchanged.

light.set({ on: true, brightness: 60 });
light.set({ on: false });
light.set({ brightness: 30 });
light.set({ on: true, brightness: 75, transition_duration: 2.0 });
light.set({ on: true, toggle_after: 30 });  // on now, off after 30s

Parameters:

• on — Boolean on/off state.
• brightness — Integer 0–100. Values outside this range throw "brightness must be 0-100".
• transition_duration — Optional. Transition time in seconds (float).
• toggle_after — Optional. Seconds after which the light flips to the opposite state (float).

Calling light.set triggers the write handler (see below), so this is also how a script pushes hardware-reported state back into the light.

light.on(event, callback)

Listen for events on the light. The callback is passive — it observes changes and its return value is ignored.

const subId = light.on('change', (status) => {
  if (status.output) {
    console.log('Light turned on at ' + status.brightness + '%');
  } else {
    console.log('Light turned off');
  }
});

Parameters:

• event — Event name. Only "change" is accepted; any other name throws "unsupported event".
• callback — Function invoked with the light's status object (same shape as getStatus()).

Returns a numeric listener id, which you pass to light.off to remove the listener.

light.off(id)

Remove a listener previously registered with light.on.

light.off(subId);

Returns true if the listener was found and removed, false otherwise.

light.setWriteOutputState(callback)

setWriteOutputState installs a handler that runs on every write to the light — from the UI, an automation, or another script.

light.setWriteOutputState((params) => {
  // params: { output: boolean, brightness: number, source: string }
  // return null to accept, or an error string to reject
  return null;
});

The function receives:

• output — Requested on/off state.
• brightness — Requested brightness (0–100).
• source — String identifying where the write originated.

Return value:

• null — Accept the write. The requested state is applied to the component.
• string — Reject the write. The returned string is surfaced as the error message to the caller (UI, RPC, or script), and the component's state is left unchanged. Use this to enforce policy or validation — for example, refuse an out-of-range value or block a write while the hardware is busy.

Bidirectional Synchronization

The Light API sits between the app (UI, RPC calls, other scripts) and your physical hardware. Two directions need to stay in sync:

• Hardware -> Light: when your hardware reports a state change, call light.set(...) so the app sees the new state.
• Light -> Hardware: when a user, RPC caller, or other script changes the light, your write handler runs — drive the hardware from there.

Note that your own light.set(...) calls also fire the handler. Without care, this creates a loop: hardware reports a change -> script calls light.set -> handler drives hardware -> hardware reports again -> repeat. Break the loop by inspecting params.source inside the handler and only driving hardware for writes that came from outside your script. The UART example below shows one common pattern.

Light Examples

Getting a Handle

const light = Light.get(0);
if (!light) {
  throw new Error('Light not available');
}

Reading Status

const status = light.getStatus();
console.log(status.output ? 'On at ' + status.brightness + '%' : 'Off');

Reading Config

const cfg = light.getConfig();
console.log('Configured name:', cfg.name);

Updating Config

const cfg = light.getConfig();
cfg.name = 'Kitchen light';

if (!light.setConfig(cfg)) {
  console.log('Config update rejected');
}

Setting State

// Turn on at 50%
light.set({ on: true, brightness: 50 });

// Later, dim without changing on/off
light.set({ brightness: 20 });

// Turn off
light.set({ on: false });

// Fade to 80% over 2 seconds
light.set({ on: true, brightness: 80, transition_duration: 2.0 });

Listening for Changes

const subId = light.on('change', (status) => {
  console.log('Light is now', status.output ? 'on' : 'off');

  // Stop listening after the first change:
  light.off(subId);
});

Validation

Use the handler to enforce a policy — here, cap brightness at 80:

const light = Light.get(0);
if (!light) {
  throw new Error('Light not available');
}

light.setWriteOutputState((params) => {
  if (params.brightness > 80) {
    return 'brightness limited to 80';
  }
  return null;
});

Light (UART)

const uart = UART.get(0);
uart.configure({ baud: 115200, mode: '8N1' });

const light = Light.get(0);
if (!light) {
  throw new Error('Light not available');
}

// Device to app
uart.recv((data) => {
  const line = data.trim();
  if (line.startsWith('STATE:')) {
    const on = line.substring(6).toUpperCase() === 'ON';
    light.set({ on });
  } else if (line.startsWith('DIM:')) {
    const brightness = parseInt(line.substring(4), 10);
    if (!isNaN(brightness)) {
      light.set({ brightness, on: brightness > 0 });
    }
  }
});

// App to device
light.setWriteOutputState((params) => {
  if (params.source !== 'user' && params.source !== 'api') {
    return null;
  }
  uart.write('STATE:' + (params.output ? 'ON' : 'OFF') + '\n');
  uart.write('DIM:' + params.brightness + '\n');
  return null;
});