Light

The Light component handles a dimmable light output with additional on/off control. It has night mode capability that can reduce brightness in selected period of time. It uses Light as RPC namespace and provides the methods:

• Light.GetConfig to obtain the component's configuration
• Light.SetConfig to update the component's configuration
• Light.GetStatus to obtain the component's status
• Light.Set to control the output state and brightness level
• Light.Toggle to toggle the output state

Light components are identified with light:<id> in objects containing multiple component payloads.

Methods:

Light.SetConfig

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

Find more about the config properties in config section

Light.GetConfig

Properties:

Property	Type	Description
id	number	Id of the Light component instance

Find the Light.GetConfig response properties in config section

Light.GetStatus

Properties:

Property	Type	Description
id	number	Id of the Light component instance

Find more about the status response properties in status section

Light.Set

This method sets the output and brightness level of the Light 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 Light component instance. Required
on	boolean	True for light on, false otherwise. Optional
brightness	number	Brightness level Optional
toggle_after	number	Optional flip-back timer in seconds. Optional

info

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

Light.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 Light component instance. Required

HTTP Endpoint: /light/id

Through this endpoint a light can be turned on/off with or without a timer, brightness 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 %
transition	number	One-shot transition, 0..10800000 [ms]

Response

Received attributes:

Property	Type	Description
ison	boolean	True if the light is turned on, false otherwise
brightness	number	Brightness, 0..100 %
transition	number	One-shot transition, 0..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 Light component contains information about night mode settings, default brightness level and the timers of the chosen light instance. To Get/Set the configuration of the Light component its id must be specified.

Properties:

Property	Type	Description
id	number	Id of the Light component instance
name	string or null	Name of the light instance
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
default.brightness	number	Brightness level (in percent) after power on
min_brightness_on_toggle	number	Brightness level (in percent) applied when there is a toggle and current brightness is 0.
night_mode.enable	boolean	Enable or disable night mode
night_mode.brightness	number	Brightness level limit when night mode is active
night_mode.active_between	array	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

Status

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

Properties:

Property	Type	Description
id	number	Id of the Light 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
brightness	number	Current brightness level (in percent)
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)

Webhook Events

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

• light.on - produced when the light changes its state from off to on
• light.off - produced when the light changes its state from on to off

Examples

Light.SetConfig example

Light.SetConfig HTTP GET Request

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

Light.SetConfig Curl Request

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

Light.SetConfig Mos Request

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

Response

Light.SetConfig HTTP GET Response

null

Light.SetConfig Curl Response

{
  "id": 1,
  "src": "shellypluswdus-30839809eac0",
  "params": null
}

Light.SetConfig Mos Response

null

Light.GetConfig example

Light.GetConfig HTTP GET Request

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

Light.GetConfig Curl Request

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

Light.GetConfig Mos Request

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

Response

Light.GetConfig HTTP GET Response

{
  "id": 0,
  "name": null,
  "initial_state": "restore_last",
  "auto_on": true,
  "auto_on_delay": 60,
  "auto_off": true,
  "auto_off_delay": 60,
  "default": {
    "brightness": 100
  },
  "min_brightness_on_toggle": 3,
  "night_mode": {
    "enable": true,
    "brightness": 15,
    "active_between": [
      "21:45",
      "05:30"
    ]
  }
}

Light.GetConfig Curl Response

{
  "id": 1,
  "src": "shellypluswdus-30839809eac0",
  "params": {
    "id": 0,
    "name": null,
    "initial_state": "restore_last",
    "auto_on": true,
    "auto_on_delay": 60,
    "auto_off": true,
    "auto_off_delay": 60,
    "default": {
      "brightness": 100
    },
    "min_brightness_on_toggle": 3,
    "night_mode": {
      "enable": true,
      "brightness": 15,
      "active_between": [
        "21:45",
        "05:30"
      ]
    }
  }
}

Light.GetConfig Mos Response

{
  "id": 0,
  "name": null,
  "initial_state": "restore_last",
  "auto_on": true,
  "auto_on_delay": 60,
  "auto_off": true,
  "auto_off_delay": 60,
  "default": {
    "brightness": 100
  },
  "min_brightness_on_toggle": 3,
  "night_mode": {
    "enable": true,
    "brightness": 15,
    "active_between": [
      "21:45",
      "05:30"
    ]
  }
}

Light.GetStatus example

Light.GetStatus HTTP GET Request

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

Light.GetStatus Curl Request

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

Light.GetStatus Mos Request

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

Response

Light.GetStatus HTTP GET Response

{
  "id": 0,
  "source": "timer",
  "output": false,
  "brightness": 50,
  "timer_started_at": 1626942399.36,
  "timer_duration": 60
}

Light.GetStatus Curl Response

{
  "id": 1,
  "src": "shellypluswdus-30839809eac0",
  "params": {
    "id": 0,
    "source": "timer",
    "output": false,
    "brightness": 50,
    "timer_started_at": 1626942399.36,
    "timer_duration": 60
  }
}

Light.GetStatus Mos Response

{
  "id": 0,
  "source": "timer",
  "output": false,
  "brightness": 50,
  "timer_started_at": 1626942399.36,
  "timer_duration": 60
}

Light.Set example

Light.Set HTTP GET Request

http://192.168.33.1/rpc/Light.Set?id=0&on=true&brightness=50

Light.Set Curl Request

curl -X POST -d '{"id":1,"method":"Light.Set","params":{"id":0,"on":true,"brightness":50}}' http://${SHELLY}/rpc

Light.Set Mos Request

mos --port ${PORT} call Light.Set '{"id":0,"on":true,"brightness":50}'

Response

Light.Set HTTP GET Response

null

Light.Set Curl Response

{
  "id": 1,
  "src": "shellypluswdus-30839809eac0",
  "params": null
}

Light.Set Mos Response

null

Light.Toggle example

Light.Toggle HTTP GET Request

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

Light.Toggle Curl Request

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

Light.Toggle Mos Request

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

Response

Light.Toggle HTTP GET Response

null

Light.Toggle Curl Response

{
  "id": 1,
  "src": "shellypluswdus-30839809eac0",
  "params": null
}

Light.Toggle Mos Response

null

HTTP Endpoint example

Example:

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

Example:

{
  "ison": true,
  "brightness": 100,
  "transition": 10,
  "has_timer": true,
  "timer_started_at": 258,
  "timer_duration": 10,
  "timer_remaining": 1.98,
  "source": "http"
}