Version: 1.0

RGBW

The RGBW component handles an output with possibility to change color and brightness of RGBW LED load. Component has additional on/off control. It has night mode capability that can reduce brightness in selected period of time. It uses RGBW as RPC namespace and provides the methods:

RGBW.GetConfig to obtain the component's configuration
RGBW.SetConfig to update the component's configuration
RGBW.GetStatus to obtain the component's status
RGBW.Set to control the output state, color, transition and brightness level
RGBW.Toggle to toggle the output state
RGBW.DimUp to dim up
RGBW.DimDown to dim down
RGBW.DimStop to stop dimming

RGBW components are identified with rgbw:<id> in objects containing multiple component payloads.

Methods:

RGBW.SetConfig

Property	Type	Description
`id`	number	Id of the RGBW component instance
`config`	object	Configuration that the method takes

Find more about the config properties in config section

RGBW.GetConfig

Properties:

Property	Type	Description
`id`	number	Id of the RGBW component instance

Find the RGBW.GetConfig response properties in config section

RGBW.GetStatus

Properties:

Property	Type	Description
`id`	number	Id of the RGBW component instance

Find more about the status response properties in status section

RGBW.Set

This method sets the output, color, transition and brightness level of the RGBW component. It can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request

Parameters:

Property	Type	Description
`id`	number	Id of the RGBW component instance. Required
`on`	boolean	True for output on, false otherwise. Optional
`brightness`	number	Brightness level 1%-100% Optional
`rgb`	array of type number	Red, Green, Blue [r,g,b] - each value represents level between 0..255 Optional
`white`	number	White level 0..255 Optional
`transition_duration`	number	Transition time in seconds - time between change from current brightness level and color to desired brightness level and color in request Optional
`toggle_after`	number	Flip-back timer in seconds. Optional
`offset`	number	Set current brightness level with applied offset. Can not be used together with `brightness`. Boundaries [-100, 100] Optional
`offset_white`	number	Set current white level with applied offset_white. Can not be used together with `white`. Boundaries [-255, 255] Optional

info

At least one of the on and brightness parameters is required.

RGBW.Toggle

This method toggles the output state. It can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request

Parameters:

Property	Type	Description
`id`	number	Id of the RGBW component instance. Required

RGBW.DimUp

This method dims up the brightness and white level. Dimming stops with RGBW.DimStop.

Request

Parameters:

Property	Type	Description
`id`	number	Id of the RGBW component instance. Required
`fade_rate`	number	Fade rate of the brightness level dimming. Range `[1,5]` where `5` is fastest, `1` is slowest. If not provided, value is defaulted to `button_fade_rate`. Optional

RGBW.DimDown

This method dims down the brightness and white level. Dimming stops with RGBW.DimStop.

Request

Parameters:

Property	Type	Description
`id`	number	Id of the RGBW component instance. Required
`fade_rate`	number	Fade rate of the brightness level dimming. Range `[1,5]` where `5` is fastest, `1` is slowest. If not provided, value is defaulted to `button_fade_rate`. Optional

RGBW.DimStop

This method stops the dimming of the brightness level.

Request

Parameters:

Property	Type	Description
`id`	number	Id of the RGBW component instance. Required

HTTP Endpoint: /color/`id`

Through this endpoint a light can be turned on/off with or without a timer, brightness and color can be changed also. This can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request

Parameters:

Property	Type	Description
`turn`	string	Action to be executed. Range of values: `on`, `off`, `toggle`. Required
`timer`	number	A one-shot flip-back timer in seconds.
`brightness`	number	Brightness, 0..100 %
`red`	number	Intensity of the color red, 0..255
`green`	number	Intensity of the color green, 0..255
`blue`	number	Intensity of the color blue, 0..255
`white`	number	Intensity of the white, 0..255
`transition`	number	One-shot transition, 500..10800000 [ms]

Response

Received attributes:

Property	Type	Description
`ison`	boolean	True if the light is turned on, false otherwise
`brightness`	number	Brightness, 0..100 %
`red`	number	Intensity of the color red, 0..255
`green`	number	Intensity of the color green, 0..255
`blue`	number	Intensity of the color blue, 0..255
`white`	number	Intensity of the white, 0..255
`transition`	number	One-shot transition, 500..10800000 [ms]
`has_timer`	boolean	True if the light is turned on, false otherwise
`timer_started_at`	number	Unix timestamp, start time of the timer (in UTC)
`timer_duration`	number	Duration of the timer in seconds
`timer_remaining`	number	Time remaining (in seconds) until the request is executed
`source`	string	Source of the last command, for example: `init`, `WS_in`, `http`, ...

Configuration

The configuration of the RGBW component contains information about night mode settings, the timers of the chosen light instance. To Get/Set the configuration of the RGBW component its id must be specified.

Properties:

Property Type Description

id

number

Id of the RGBW component instance

name

string or null

Name of the RGBW instance

in_mode

string

Mode of the associated input. Range of values: follow, flip, activate, detached, dim

initial_state

string

Output state to set on power_on. Range of values: off, on, restore_last

auto_on

boolean

True if the "Automatic ON" function is enabled, false otherwise

auto_on_delay

number

Seconds to pass until the component is switched back on

auto_off

boolean

True if the "Automatic OFF" function is enabled, false otherwise

auto_off_delay

number

Seconds to pass until the component is switched back off

transition_duration

number

Transition time (in seconds) - time to change from 0% to 100% of brightness, RGB or white

min_brightness_on_toggle

number

Brightness level (in percent) applied when there is a toggle and current brightness is lower than min_brightness_on_toggle.

night_mode.enable

boolean

Enable or disable night mode

night_mode.brightness

number or null

Brightness level limit (in percent) when night mode is active. null overrides night_mode.brightness with current brightness when night mode starts. Default value 50.

night_mode.rgb

array of type number or null

Color level when night mode is active. Red, Green, Blue [r,g,b] - each value represents level between 0..255. null overrides night_mode.rgb array with current rgb array when night mode starts. Default value 255 for each color

night_mode.white

number or null

White level limit (in percent) when night mode is active. null overrides night_mode.white with current white when night mode starts. Default value 127.

night_mode.active_between

array of type string

Containing 2 elements of type string, the first element indicates the start of the period during which the night mode will be active, the second indicates the end of that period. Both start and end are strings in the format HH:MM, where HH and MM are hours and minutes with optinal leading zeros

button_fade_rate

number

Controls how quickly the output level changes while a button is held down for dimming (if applicable). Default value 3. Range [1,5] where 5 is fastest, 1 is slowest

button_presets

object

Button presets config

Property Type Description

button_doublepush

object

null disables button_doublepush preset

Property	Type	Description
`brightness`	number or null	Brightness level (in percent) set on double click (if applicable). `null` overrides `brightness` with current brightness when preset is applied. Default `100`
`rgb`	array of type number or null	Color level set on double click (if applicable). Red, Green, Blue [r,g,b] - each value represents level between 0..255. `null` overrides `rgb` array with current `rgb` array when preset is applied. Default value `255` for each color
`white`	number or null	White level 0.255 set on double click (if applicable). `null` overrides `white` with current white when preset is applied. Default `255`

current_limit

number

Limit (in Amperes) over which overcurrent condition occurs (shown if applicable)

power_limit

number

Limit (in Watts) over which overpower condition occurs (shown if applicable)

voltage_limit

number

Limit (in Volts) over which overvoltage condition occurs (shown if applicable)

info

follow: the state of the output is the same as the state of the input (e.g. when the input is off => the output is off). For type:analog sets to output current % of input.
flip: change of the state of the input causes change of the state of the output (e.g. when input is toggled the output is also toggled)
activate: when input state is on sets output to on (and activates auto_off if enabled), input state off does nothing.
detached: the state of the input doesn't affect the state of the output.
dim: short press toggles output, long press starts dimming with alternating directions. If output is currently off, holding the button will turn on and start dimming from 0%. Stops when reached 100% or 1%.
follow and flip are available for type:switch.
activate available for type:switch and type:button
dim available for type:button

Status

The status of the RGBW component contains information about the brightness level and output state of the light instance. To obtain the status of the RGBW component its id must be specified.

Properties:

Property Type Description

id

number

Id of the RGBW component instance

source

string

Source of the last command, for example: init, WS_in, http, ...

output

boolean

True if the output channel is currently on, false otherwise

rgb

array of type number

Current Red, Green, Blue [r,g,b] level 0..255

brightness

number

Current brightness level (in percent)

white

number

Current white level 0..255

timer_started_at

number

Unix timestamp, start time of the timer (in UTC) (shown if the timer is triggered)

timer_duration

number

Duration of the timer in seconds (shown if the timer is triggered)

transition

object

Information about the transition (shown if transition is triggered)

Property	Type	Description
`target.output`	boolean	True if the output channel becomes on, false otherwise
`target.rgb`	array of type number	Red, Green, Blue [r,g,b] level 0..255
`target.brightness`	number	Brightness level (in percent)
`target.white`	number	White level 0..255
`started_at`	number	Unix timestamp, start time of the transition (in UTC)
`duration`	number	Duration of the transition in seconds

temperature

object

Information about the temperature (shown if applicable)

Property	Type	Description
`tC`	number or null	Temperature in Celsius (`null` if temperature is out of the measurement range)
`tF`	number or null	Temperature in Fahrenheit (`null` if temperature is out of the measurement range)

aenergy

object

Information about the active energy counter (shown if applicable)

Property	Type	Description
`total`	number	Total energy consumed in Watt-hours
`by_minute`	array of type number	Energy consumption in Milliwatt-hours for the last three complete minutes. The 0-th element indicates the counts accumulated during the minute preceding `minute_ts`. Present only if the device clock is synced.
`minute_ts`	number	Unix timestamp marking the start of the current minute (in UTC).

apower

number

Last measured instantaneous active power (in Watts) delivered to the attached load (shown if applicable)

voltage

number

Last measured voltage in Volts (shown if applicable)

current

number

Last measured current in Amperes (shown if applicable)

errors

array of type string

Error conditions occurred. May contain overtemp, (shown if at least one error is present)

Webhook Events

Currently, there are two events related to the RGBW component that can trigger webhooks:

rgbw.on - produced when the output changes its state from off to on
rgbw.off - produced when the output changes its state from on to off

Examples

RGBW.SetConfig example

RGBW.SetConfig HTTP GET Request
RGBW.SetConfig Curl Request
RGBW.SetConfig Mos Request

http://192.168.33.1/rpc/RGBW.SetConfig?id=0&config={"name":"RGBW0"}

curl -X POST -d '{"id":1,"method":"RGBW.SetConfig","params":{"id":0,"config":{"name":"RGBW0"}}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.SetConfig '{"id":0,"config":{"name":"RGBW0"}}'

Response

RGBW.SetConfig HTTP GET Response
RGBW.SetConfig Curl Response
RGBW.SetConfig Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

RGBW.GetConfig example

RGBW.GetConfig HTTP GET Request
RGBW.GetConfig Curl Request
RGBW.GetConfig Mos Request

http://192.168.33.1/rpc/RGBW.GetConfig?id=0

curl -X POST -d '{"id":1,"method":"RGBW.GetConfig","params":{"id":0}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.GetConfig '{"id":0}'

Response

RGBW.GetConfig HTTP GET Response
RGBW.GetConfig Curl Response
RGBW.GetConfig Mos Response

{
  "id": 0,
  "name": null,
  "in_mode": "dim",
  "initial_state": "restore_last",
  "auto_on": true,
  "auto_on_delay": 60,
  "auto_off": true,
  "auto_off_delay": 60,
  "transition_duration": 3,
  "min_brightness_on_toggle": 3,
  "button_presets": {
    "button_doublepush": {
      "brightness": 100,
      "rgb": [
        255,
        255,
        255
      ],
      "white": 255
    }
  },
  "night_mode": {
    "enable": true,
    "brightness": 50,
    "rgb": [
      255,
      255,
      255
    ],
    "white": 127,
    "active_between": [
      "21:45",
      "05:30"
    ]
  },
  "button_fade_rate": 3
}

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": {
    "id": 0,
    "name": null,
    "in_mode": "dim",
    "initial_state": "restore_last",
    "auto_on": true,
    "auto_on_delay": 60,
    "auto_off": true,
    "auto_off_delay": 60,
    "transition_duration": 3,
    "min_brightness_on_toggle": 3,
    "button_presets": {
      "button_doublepush": {
        "brightness": 100,
        "rgb": [
          255,
          255,
          255
        ],
        "white": 255
      }
    },
    "night_mode": {
      "enable": true,
      "brightness": 50,
      "rgb": [
        255,
        255,
        255
      ],
      "white": 127,
      "active_between": [
        "21:45",
        "05:30"
      ]
    },
    "button_fade_rate": 3
  }
}

{
  "id": 0,
  "name": null,
  "in_mode": "dim",
  "initial_state": "restore_last",
  "auto_on": true,
  "auto_on_delay": 60,
  "auto_off": true,
  "auto_off_delay": 60,
  "transition_duration": 3,
  "min_brightness_on_toggle": 3,
  "button_presets": {
    "button_doublepush": {
      "brightness": 100,
      "rgb": [
        255,
        255,
        255
      ],
      "white": 255
    }
  },
  "night_mode": {
    "enable": true,
    "brightness": 50,
    "rgb": [
      255,
      255,
      255
    ],
    "white": 127,
    "active_between": [
      "21:45",
      "05:30"
    ]
  },
  "button_fade_rate": 3
}

RGBW.GetStatus example

RGBW.GetStatus HTTP GET Request
RGBW.GetStatus Curl Request
RGBW.GetStatus Mos Request

http://192.168.33.1/rpc/RGBW.GetStatus?id=0

curl -X POST -d '{"id":1,"method":"RGBW.GetStatus","params":{"id":0}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.GetStatus '{"id":0}'

Response

RGBW.GetStatus HTTP GET Response
RGBW.GetStatus Curl Response
RGBW.GetStatus Mos Response

{
  "id": 0,
  "source": "timer",
  "output": true,
  "rgb": [
    0,
    0,
    127
  ],
  "brightness": 50,
  "white": 50,
  "timer_started_at": 1626942399.36,
  "timer_duration": 60,
  "transition": {
    "target": {
      "output": true,
      "brightness": 50,
      "rgb": [
        20,
        30,
        40
      ],
      "white": 80
    },
    "started_at": 1626942399.36,
    "duration": 20
  },
  "temperature": {
    "tC": 53.1,
    "tF": 127.6
  },
  "aenergy": {
    "total": 0.55
  },
  "apower": 2,
  "current": 0.165,
  "voltage": 12.1
}

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": {
    "id": 0,
    "source": "timer",
    "output": true,
    "rgb": [
      0,
      0,
      127
    ],
    "brightness": 50,
    "white": 50,
    "timer_started_at": 1626942399.36,
    "timer_duration": 60,
    "transition": {
      "target": {
        "output": true,
        "brightness": 50,
        "rgb": [
          20,
          30,
          40
        ],
        "white": 80
      },
      "started_at": 1626942399.36,
      "duration": 20
    },
    "temperature": {
      "tC": 53.1,
      "tF": 127.6
    },
    "aenergy": {
      "total": 0.55
    },
    "apower": 2,
    "current": 0.165,
    "voltage": 12.1
  }
}

{
  "id": 0,
  "source": "timer",
  "output": true,
  "rgb": [
    0,
    0,
    127
  ],
  "brightness": 50,
  "white": 50,
  "timer_started_at": 1626942399.36,
  "timer_duration": 60,
  "transition": {
    "target": {
      "output": true,
      "brightness": 50,
      "rgb": [
        20,
        30,
        40
      ],
      "white": 80
    },
    "started_at": 1626942399.36,
    "duration": 20
  },
  "temperature": {
    "tC": 53.1,
    "tF": 127.6
  },
  "aenergy": {
    "total": 0.55
  },
  "apower": 2,
  "current": 0.165,
  "voltage": 12.1
}

RGBW.Set example

RGBW.Set HTTP GET Request
RGBW.Set Curl Request
RGBW.Set Mos Request

http://192.168.33.1/rpc/RGBW.Set?id=0&on=true&brightness=50&rgb=[20,30,40]&white=80&transition_duration=20

curl -X POST -d '{"id":1,"method":"RGBW.Set","params":{"id":0,"on":true,"brightness":50,"rgb":[20,30,40],"white":80,"transition_duration":20}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.Set '{"id":0,"on":true,"brightness":50,"rgb":[20,30,40],"white":80,"transition_duration":20}'

Response

RGBW.Set HTTP GET Response
RGBW.Set Curl Response
RGBW.Set Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

RGBW.Toggle example

RGBW.Toggle HTTP GET Request
RGBW.Toggle Curl Request
RGBW.Toggle Mos Request

http://192.168.33.1/rpc/RGBW.Toggle?id=0

curl -X POST -d '{"id":1,"method":"RGBW.Toggle","params":{"id":0}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.Toggle '{"id":0}'

Response

RGBW.Toggle HTTP GET Response
RGBW.Toggle Curl Response
RGBW.Toggle Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

RGBW.DimUp example

RGBW.DimUp HTTP GET Request
RGBW.DimUp Curl Request
RGBW.DimUp Mos Request

http://192.168.33.1/rpc/RGBW.DimUp?id=0&fade_rate=3

curl -X POST -d '{"id":1,"method":"RGBW.DimUp","params":{"id":0,"fade_rate":3}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.DimUp '{"id":0,"fade_rate":3}'

Response

RGBW.DimUp HTTP GET Response
RGBW.DimUp Curl Response
RGBW.DimUp Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

RGBW.DimDown example

RGBW.DimDown HTTP GET Request
RGBW.DimDown Curl Request
RGBW.DimDown Mos Request

http://192.168.33.1/rpc/RGBW.DimDown?id=0&fade_rate=3

curl -X POST -d '{"id":1,"method":"RGBW.DimDown","params":{"id":0,"fade_rate":3}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.DimDown '{"id":0,"fade_rate":3}'

Response

RGBW.DimDown HTTP GET Response
RGBW.DimDown Curl Response
RGBW.DimDown Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

RGBW.DimStop example

RGBW.DimStop HTTP GET Request
RGBW.DimStop Curl Request
RGBW.DimStop Mos Request

http://192.168.33.1/rpc/RGBW.DimStop?id=0

curl -X POST -d '{"id":1,"method":"RGBW.DimStop","params":{"id":0}}' http://${SHELLY}/rpc

mos --port ${PORT} call RGBW.DimStop '{"id":0}'

Response

RGBW.DimStop HTTP GET Response
RGBW.DimStop Curl Response
RGBW.DimStop Mos Response

null

{
  "id": 1,
  "src": "shellyplusrgbwpm-b48a0a123db4",
  "params": null
}

null

HTTP Endpoint example

Example:

curl http://${SHELLY}/color/0?turn=on

Example:

{
  "ison": true,
  "brightness": 100,
  "red": 127,
  "green": 0,
  "blue": 0,
  "white": 0,
  "transition": 10,
  "has_timer": true,
  "timer_started_at": 258,
  "timer_duration": 10,
  "timer_remaining": 1.98,
  "source": "http"
}

RGBW

Methods:​

RGBW.SetConfig​

RGBW.GetConfig​

RGBW.GetStatus​

RGBW.Set​

Request​

RGBW.Toggle​

Request​

RGBW.DimUp​

Request​

RGBW.DimDown​

Request​

RGBW.DimStop​

Request​

HTTP Endpoint: /color/id​

Request​

Response​

Configuration​

Status​

Webhook Events​

Examples​

RGBW.SetConfig example​

Response

RGBW.GetConfig example​

Response

RGBW.GetStatus example​

Response

RGBW.Set example​

Response

RGBW.Toggle example​

Response

RGBW.DimUp example​

Response

RGBW.DimDown example​

Response

RGBW.DimStop example​

Response

HTTP Endpoint example​

Methods:

RGBW.SetConfig

RGBW.GetConfig

RGBW.GetStatus

RGBW.Set

Request

RGBW.Toggle

Request

RGBW.DimUp

Request

RGBW.DimDown

Request

RGBW.DimStop

Request

HTTP Endpoint: /color/`id`

Request

Response

Configuration

Status

Webhook Events

Examples

RGBW.SetConfig example

RGBW.GetConfig example

RGBW.GetStatus example

RGBW.Set example

RGBW.Toggle example

RGBW.DimUp example

RGBW.DimDown example

RGBW.DimStop example

HTTP Endpoint example