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.Calibrate (if applicable)
• Light.ResetCounters to reset component's energy counters (if applicable)

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
transition_duration	number	Transition time in seconds - time between change from current brightness level to desired brightness level in request 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

Light.Calibrate

This method (if applicalbe) starts calibration of device's outputs.

Request

Parameters:

Property	Type	Description
id	number	Id of the Light component instance

Response

The result from this method is null when calibration is started succesfully.

If invoked while calibration is already in progress, an error is returned:

{
  "code": -114,
  "message": "Callibration is in progress"
}

Light.ResetCounters

This method resets associated counters (if applicable).

Request

Parameters:

Property	Type	Description
id	number	Id of the Light component instance. Required
type	array of strings	Array of strings, selects which counter to reset Optional

note

If no 'type' is provided, the method will reset all available counters.

Response

Attributes in the result:

Property	Type	Description
aenergy	object	Information about the active energy counter prior to reset Property Type Description total number Last counter value of the total energy consumed in Watt-hours

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, 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 %
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 Light component contains information about night mode settings, button presets 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
in_mode	string	Mode of the associated input. Range of values: follow, flip, activate, detached, dim (if applicable), dual_dim (if applicable)
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 (if applicable)
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	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
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 Brightness level (in percent) set on double click (if applicable), default: 100
range_map	array or null	Remaps output 0%-100% range to values in array (if applicable). First value in array is min setting, second value is max setting. Array elements are of type number. Float values are supported. Accepted range for values is from 0% to 100%. Default values are [0, 100]. max must be greater than min.
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)
undervoltage_limit	number	Limit (in Volts) under which undervoltage condition occurs (shown if applicable)
current_limit	number	Limit (in Amperes) over which overcurrent 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%.

• dual_dim: short press toggles output, long press starts dimming up/down depending on which button is pressed. 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

  dual_dim available for type:button

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)
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.brightness number Brightness level (in percent) 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 (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)
calibration	object	Information about the calibration process, only present when calibration is running (shown if applicable). Property Type Description progess number Calibration progress in percent
errors	array of type string	Error conditions occurred, shown if at least one error is present. Depending on component capabilities may contain: overtemp, overpower, overvoltage, undervoltage, overcurrent, unsupported_load, cal_abort:interrupted, cal_abort:power_read, cal_abort:no_load, cal_abort:non_dimmable, cal_abort:overpower, cal_abort:unsupported_load
flags	array of type string	Communicates present conditions, shown if at least one flag is set. Depending on component capabilites may contain: uncalibrated

info

• If applicable, calibration is performed by Light.Calibrate. The calibration procedure measures consumption for each channel and should be run when there is change in loads. Consumed power of the load should be >= 3.5W.

  The following errors can occur during the calibration procedure:

  Errors:

  • cal_abort:interrupted: input or output are triggered
  • cal_abort:power_read: there is an error in reading the powermeter
  • cal_abort:no_load: there is no load attached
  • cal_abort:non_dimmable: attached load is not dimmable
  • cal_abort:overpower: load power exceeds max limit
  • cal_abort:unsupported_load: load can not be calibrated

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,
  "transition_duration": 3,
  "min_brightness_on_toggle": 3,
  "button_presets": {
    "button_doublepush": {
      "brightness": 100
    }
  },
  "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,
    "transition_duration": 3,
    "min_brightness_on_toggle": 3,
    "button_presets": {
      "button_doublepush": {
        "brightness": 100
      }
    },
    "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,
  "transition_duration": 3,
  "min_brightness_on_toggle": 3,
  "button_presets": {
    "button_doublepush": {
      "brightness": 100
    }
  },
  "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,
  "transition": {
    "target": {
      "output": true,
      "brightness": 100
    },
    "started_at": 1626942399.36,
    "duration": 20
  }
}

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,
    "transition": {
      "target": {
        "output": true,
        "brightness": 100
      },
      "started_at": 1626942399.36,
      "duration": 20
    }
  }
}

Light.GetStatus Mos Response

{
  "id": 0,
  "source": "timer",
  "output": false,
  "brightness": 50,
  "timer_started_at": 1626942399.36,
  "timer_duration": 60,
  "transition": {
    "target": {
      "output": true,
      "brightness": 100
    },
    "started_at": 1626942399.36,
    "duration": 20
  }
}

Light.Set example

Light.Set HTTP GET Request

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

Light.Set Curl Request

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

Light.Set Mos Request

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

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

Light.Calibrate example

Light.Calibrate HTTP GET Request

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

Light.Calibrate Curl Request

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

Light.Calibrate Mos Request

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

Response

Light.Calibrate HTTP GET Response

null

Light.Calibrate Curl Response

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

Light.Calibrate Mos Response

null

Light.ResetCounters example

Light.ResetCounters HTTP GET Request

http://192.168.33.1/rpc/Light.ResetCounters?id=0&type=["aenergy"]

Light.ResetCounters Curl Request

curl -X POST -d '{"id":1,"method":"Light.ResetCounters","params":{"id":0,"type":["aenergy"]}}' http://${SHELLY}/rpc

Light.ResetCounters Mos Request

mos --port ${PORT} call Light.ResetCounters '{"id":0,"type":["aenergy"]}'

Response

Light.ResetCounters HTTP GET Response

{
  "aenergy": {
    "total": 11.679
  }
}

Light.ResetCounters Curl Response

{
  "id": 1,
  "src": "shellyprodm1pm-441793ce3f08",
  "params": {
    "aenergy": {
      "total": 11.679
    }
  }
}

Light.ResetCounters Mos Response

{
  "aenergy": {
    "total": 11.679
  }
}

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"
}