RGB

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

API Reference

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

note

The RGB 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.

RGB.get(id)

Look up an RGB component and return a handle to it.

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

Parameters:

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

Returns an RGBHandle, or null if the component is not available.

rgb.getStatus()

Read the light's current status.

const status = rgb.getStatus();
// { id: 0, source: "...", output: true, brightness: 75, rgb: [255, 128, 0] }

if (status.output) {
  const [r, g, b] = status.rgb;
  console.log('On at ' + status.brightness + '%, color (' + r + ',' + g + ',' + b + ')');
}

Returned fields:

• output — Boolean on/off state.
• brightness — Overall brightness (e.g. 0–100).
• rgb — Array of three color channel values [r, g, b], each 0–255.

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

rgb.getConfig()

Read the light's current configuration.

const cfg = rgb.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 RGB component reference for the full shape.

rgb.setConfig(cfg)

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

const cfg = rgb.getConfig();
cfg.name = 'Living room strip';

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

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

rgb.set(state)

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

rgb.set({ on: true, brightness: 60, rgb: [255, 128, 0] });
rgb.set({ on: false });
rgb.set({ rgb: [0, 255, 0] });
rgb.set({ on: true, brightness: 100, rgb: [255, 0, 0], transition_duration: 2.0 });

Parameters:

• on — Boolean on/off state.
• brightness — Integer 0–100. Values outside this range throw "brightness must be 0-100".
• rgb — Array of exactly three integers [r, g, b], each 0–255. Arrays of wrong length or values outside 0–255 are rejected.
• transition_duration — Optional. Transition time in seconds (float).
• toggle_after — Optional. Seconds after which the light flips to the opposite state (float).

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

rgb.on(event, callback)

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

const subId = rgb.on('change', (status) => {
  if (status.output) {
    const [r, g, b] = status.rgb;
    console.log('RGB now (' + r + ',' + g + ',' + b + ')');
  } else {
    console.log('RGB 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 rgb.off to remove the listener.

rgb.off(id)

Remove a listener previously registered with rgb.on.

rgb.off(subId);

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

rgb.setWriteOutputState(callback)

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

rgb.setWriteOutputState((params) => {
  // params: { output: boolean, brightness: number, rgb: [r, g, b], 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).
• rgb — Requested color as an array [r, g, b], each 0–255.
• 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 RGB 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 rgb.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 rgb.set(...) calls also fire the handler. Without care, this creates a loop: hardware reports a change -> script calls rgb.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.

RGB Examples

Getting a Handle

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

Reading Status

const status = rgb.getStatus();
const [r, g, b] = status.rgb;
console.log(status.output ? 'On at ' + status.brightness + '%, (' + r + ',' + g + ',' + b + ')' : 'Off');

Reading Config

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

Updating Config

const cfg = rgb.getConfig();
cfg.name = 'Living room strip';

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

Setting State

// Turn on, medium brightness, orange
rgb.set({ on: true, brightness: 60, rgb: [255, 128, 0] });

// Change color without touching output/brightness
rgb.set({ rgb: [0, 255, 0] });

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

// Fade to red over 2 seconds
rgb.set({ on: true, brightness: 100, rgb: [255, 0, 0], transition_duration: 2.0 });

Listening for Changes

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

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

Validation

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

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

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

RGB (UART)

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

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

// Device to app
uart.recv((data) => {
  const line = data.trim();
  if (line.startsWith('STATE:')) {
    const on = line.substring(6).toUpperCase() === 'ON';
    rgb.set({ on });
  } else if (line.startsWith('DIM:')) {
    const brightness = parseInt(line.substring(4), 10);
    if (!isNaN(brightness)) {
      rgb.set({ brightness });
    }
  } else if (line.startsWith('RGB:')) {
    const parts = line.substring(4).split(',');
    if (parts.length === 3) {
      const r = parseInt(parts[0], 10);
      const g = parseInt(parts[1], 10);
      const b = parseInt(parts[2], 10);
      if (!isNaN(r) && !isNaN(g) && !isNaN(b)) {
        rgb.set({ rgb: [r, g, b] });
      }
    }
  }
});

// App to device
rgb.setWriteOutputState((params) => {
  if (params.source !== 'user' && params.source !== 'api') {
    return null;
  }
  const [r, g, b] = params.rgb;
  uart.write('STATE:' + (params.output ? 'ON' : 'OFF') + '\n');
  uart.write('DIM:' + params.brightness + '\n');
  uart.write('RGB:' + r + ',' + g + ',' + b + '\n');
  return null;
});