Shelly

HSYCO integrates Allterco's Shelly devices, a comprehensive range of WiFi-enabled smart home devices operating on 2.4GHz with IPv4 support. Each device offers a documented API.

HSYCO independently manages these devices without relying on the Allterco Shelly Cloud (which, in fact, can be disabled). It operates alongside the Shelly App for smartphones, Shelly Device Web UI, Shelly Cloud and MQTT.

HSYCO's primary functions include reporting device status and enabling device control. Initial setup and configuration of devices must be conducted using the Shelly Apps (either through the Web UI or Smartphone App).

Communication

HSYCO communicates with Shelly devices through UDP, enabling it when discovering or adding new devices. You should configure only one I/O Server for each LAN. Support for multiple local networks is achieved by configuring one I/O Server for each network.

HSYCO Configuration

Add a Shelly I/O Server in the I/O Servers section of the Settings and set its parameters:

Communication

• IP Address: broadcast IP address of the LAN (e.g. 192.168.1.255)
• IP Port: TCP/IP port to use, leave blank to use default port 50752.

High Availability

• Shutdown when inactive: defaults to false.

Options

ID	Default	Values	Description
listening_port	53292	1 ... 65535	Devices listening port for incoming UDP traffic from HSYCO
disableverbosedump	true	true	when verbose log is enabled, don’t write UDP packets dump to the log files
		false	when verbose log is enabled, all decoded UDP packets are written to the log files

Shelly Utility

The Shelly Utility provides a graphical interface to discover, edit and delete devices, and update their firmware to the latest stable version available.

Devices

The following Shelly devices are supported:

• Generation 2, 3 and 4: Plus / Pro series of devices
• Shelly Plus Mini: Shelly Plus devices in compact format (Gen 2, 3 and 4)

Model	Vendor ID
Shelly Plus 1	SNSW-001X16EU
Shelly Plus 1 UL	SNSW-001X15UL
Shelly Plus 1 Mini	SNSW-001X8EU
Shelly Plus 1 PM	SNSW-001P16EU
Shelly Plus 1 PM UL	SNSW-001P15UL
Shelly Plus 1 PM Mini	SNSW-001P8EU
Shelly Plus 2 PM	SNSW-002P16EU / SNSW-102P16EU
Shelly Plus 2 PM UL	SNSW-002P15UL
Shelly Plus I4	SNSN-0024X
Shelly Plus I4DC	SNSN-0D24X
Shelly Plus Plug IT	SNPL-00110IT
Shelly Plus Plug S	SNPL-10112EU / SNPL-00110EU / SNPL-00112EU / SNPL-0112EU
Shelly Plus Plug UK	SNPL-00112UK
Shelly Plus Plug US	SNPL-00116US
Shelly Plus H&T	SNSN-0013A
Shelly Plus Smoke	SNSN-0031Z
Shelly Plus WallDimmer	SNDM-0013US
Shelly Plus RGBW PM	SNDC-0D4P10WW
Shelly Plus 0-10V Dimmer	SNDM-00100WW
Shelly Plus PM Mini	SNPM-001PCEU16
Shelly Plus Uni	SNSN-0043X
Shelly Pro 1	SPSW-201XE16EU / SPSW-001XE16EU / SPSW-001XE15UL
Shelly Pro 1 PM	SPSW-001PE16EU / SPSW-201PE16EU / SPSW-001PE15UL / SPSW-201PE15UL
Shelly Pro 2	SPSW-002XE16EU / SPSW-202XE16EU / SPSW-002XE15UL / SPSW-202XE12UL
Shelly Pro 2 PM	SPSW-002PE16EU / SPSW-202PE16EU / SPSW-202PE15UL
Shelly Pro 3	SPSW-003XE16EU / SPSW-003XE15UL
Shelly Pro 3 EM	SPEM-003CEBEU
Shelly Pro 3 EM 400	SPEM-003CEBEU120 / SPEM-003CEBEU400
Shelly Pro 4 PM	SPSW-004PE16EU / SPSW-104PE16EU / SPSW-004PE15UL
Shelly Pro Dual Cover PM	SPSH-002PE16EU
Shelly Pro EM 50	SPEM-002CEBEU50
Shelly Pro Dimmer 1 PM	SPDM-001PE01EU
Shelly Pro Dimmer 2 PM	SPDM-002PE01EU
Shelly Pro Dimmer 0/1-10V PM	SPCC-001PE10EU
Shelly Pro RGBWW PM	SPDC-0D5PE16EU
Shelly BLU Gateway	GWF-KZ01
Shelly 1 (Gen3)	S3SW-001X16EU
Shelly 1 PM (Gen3)	S3SW-001P16EU
Shelly 2 PM	S3SW-002P16EU
Shelly I4	S3SN-0024X
Shelly 1L	S3SW-0A1X1EUL
Shelly 2L	S3SW-0A2X4EUL
Shelly 1 Mini (Gen3)	S3SW-001X8EU
Shelly 1 PM Mini (Gen3)	S3SW-001P8EU
Shelly PM Mini	S3PM-001PCEU16
Shelly AZ Plug	S3PL-10112EU
Shelly Plug S	S3PL-00112EU
Shelly Outdoor Plug S	S3PL-20112EU
Shelly Plug M	S3PL-30110EU
Shelly Plug PM	S3PL-30116EU
Shelly Dimmer 0/1-10V PM	S3DM-0010WW
Shelly Dimmer	S3DM-0A101WWL
Shelly Dali Dimmer	S3DM-0A1WW
Shelly Duo Bulb	S3BL-D010009AEU
Shelly RGBCCT Bulb	S3BL-C010007AEU
Shelly H&T	S3SN-0U12A
Shelly 3EM	S3EM-003CXCEU63
Shelly EM	S3EM-002CXCEU
Shelly BLU Gateway Gen3	S3GW-1DBT001
Shelly Shutter	S3SH-0A2P4EU
Shelly 1 (Gen4)	S4SW-001X16EU
Shelly 1 PM (Gen4)	S4SW-001P16EU
Shelly 1 Mini (Gen4)	S4SW-001X8EU
Shelly 1 PM Mini (Gen4)	S4SW-001P8EU
Shelly EM Mini (Gen4)	S4EM-001PXCEU16
Shelly Flood	S4SN-0071A
Shelly 2 PM (Gen4)	S4SW-002P16EU
Shelly Plug US (Gen4)	S4PL-00116US
Shelly Dimmer (Gen4)	S4DM-0A101WWL
Shelly Dimmer US (Gen4)	S4DM-0A102US
Shelly Dimmer 0/1-10V PM (Gen4)	S4DM-0010WW
Shelly PowerStrip	S4PL-00416EU

Discovery

For discovery to work, devices generally need to be active. Battery-powered devices require waking up by pressing the button (so that they enter setup mode); they remain active for about a minute, providing enough time to initiate discovery.

Discovery is performed via mDNS, with devices periodically broadcasting their presence. HSYCO uses this to locate them on the local network. In some cases, you may need to run manual discovery multiple times to ensure all devices are detected.

Dynamic Channel Creation

The Shelly device series includes various combinations of relays, meters (in different versions), sensors, and more. HSYCO dynamically creates channels based on the status information received from the device during initialization.

note

If a device's configuration changes after discovery, all packets coming from that device wil be discarded. In order to receive and process again packets from these devices, restart the I/O server so that HSYCO polls the devices to obtain their new configuration.

Polling

Devices are polled every two minutes to update their full components status and their basic information, like uptime, available updates or whether a restart is required.

The Device Configuration Database

Devices discovered or registered by the I/O Server are added to catalog.json, the shared user interface configuration database. Each device entry in catalog.json associates the device with a graphical representation in the user interface.

Entries are created automatically during discovery. The device description is initialised to its short name and can be changed from the Utility, as can its name.

This is an example of the catalog.json entries created for Shelly devices:

{
  "devices": [
    { "ioServer": "shelly", "id": "mini1g3_1.switch.0.switch", "function": "LIGHT", "type": "LIGHT",  "description": { "en": "Mini1G3" } },
    { "ioServer": "shelly", "id": "plugsg3_1.switch.0.switch", "function": "LIGHT", "type": "LIGHT",  "description": { "en": "PlugSG3" } },
    { "ioServer": "shelly", "id": "plus10v_1.light.0.light",   "function": "LIGHT", "type": "DIMMER", "description": { "en": "Plus10V" } },
    { "ioServer": "shelly", "id": "plus2pm_1.cover.0.cover",   "function": "AUTOM", "type": "VSHUT",  "description": { "en": "Plus2PM" } },
    { "ioServer": "shelly", "id": "pro2_1.switch.0.switch",    "function": "LIGHT", "type": "LIGHT",  "description": { "en": "Pro2" } },
    { "ioServer": "shelly", "id": "pro2_1.switch.1.switch",    "function": "LIGHT", "type": "LIGHT",  "description": { "en": "Pro2" } }
  ]
}

See catalog.json for the full structure and editing instructions.

Datapoints

The Shelly I/O Server creates datapoints based on each device's channels, and they all begin with the same format:

<device_name>.<channel_name>.<channel_id>.<property_name>

where:

• <device_name> is the name of the device, automatically assigned by HSYCO at discovery and manually editable
• <channel_name> is the name of the channel, like 'switch', 'light', 'input', ...
• <channel_id> is the ID of the channel
• <property_name> is the name of the property, like 'state', 'current', 'switch', ...

For example this datapoint

pro2_1.switch.0.state

represents the output value of the switch with ID 0 of device "pro2_1".

Datapoints Table

Common Datapoints

ID	Value	R/W	Description
<device_name>.offline	0 / 1	R	Whether the device is offline or not
<device_name>.skipped	0 / 1	R	Whether the device is skipped or not

INPUT channel

ID	Value	R/W	Description
<device_name>.input.<channel_id>.state	0 / 1	R	(only for type switch, button) State of the input
<device_name>.input.<channel_id>.percent	<value>	R	(only for type analog) Analog value in percent
<device_name>.input.<channel_id>.xpercent	<value>	R	(only for type analog) Percent transformed with config.xpercent.expr
<device_name>.input.<channel_id>.counts.total	<value>	R	(only for type count) Total pulses counted
<device_name>.input.<channel_id>.counts.xtotal	<value>	R	(only for type count) Total transformed with config.xcounts.expr
<device_name>.input.<channel_id>.freq	<value>	R	(only for type count) Measured frequency in Hz
<device_name>.input.<channel_id>.xfreq	<value>	R	(only for type count) Freq transformed with config.xfreq.expr
<device_name>.input.<channel_id>.errors	<value>	R	Shown only if at least one error is present. May contain out_of_range, read

SWITCH channel

ID	Value	R/W	Description
<device_name>.switch.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.switch.<channel_id>.state	0	W	Channel output off
<device_name>.switch.<channel_id>.state	off	W	Channel output off
<device_name>.switch.<channel_id>.state	1	W	Channel output on
<device_name>.switch.<channel_id>.state	on	W	Channel output on
<device_name>.switch.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.switch.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.switch.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.switch.<channel_id>.pf	<value>	R	Last measured power factor
<device_name>.switch.<channel_id>.freq	<value>	R	Last measured network frequency in Hz
<device_name>.switch.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.switch.<channel_id>.ret_aenergy.total	<value>	R	Total returned energy consumed in Watt-hours
<device_name>.switch.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.switch.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.switch.<channel_id>.errors	<value>	R	Error conditions occurred. May contain overtemp, overpower, overvoltage, undervoltage
<device_name>.switch.<channel_id>.flags	<value>	R	Shown only if at least one flag is present

LIGHT channel

ID	Value	R/W	Description
<device_name>.light.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.light.<channel_id>.state	1...100	R	Output channel brightess (when light is on)
<device_name>.light.<channel_id>.state	off	W	Channel output off
<device_name>.light.<channel_id>.state	on	W	Channel output on
<device_name>.light.<channel_id>.state	0...100%	W	Channel output brightness
<device_name>.light.<channel_id>.transition.target.output	<value>	R	Whether the transition output channel is on
<device_name>.light.<channel_id>.transition.target.brightness	<value>	R	Transition brightness level (in percent)
<device_name>.light.<channel_id>.transition.duration	<value>	R	Duration of the transition in seconds
<device_name>.light.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.light.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.light.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.light.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.light.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.light.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.light.<channel_id>.calibration.progress	<value>	R	Information about the calibration process, only present when calibration is running
<device_name>.light.<channel_id>.errors	<value>	R	Error conditions occurred. 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

COVER channel

ID	Value	R/W	Description
<device_name>.cover.<channel_id>.state	open / closed / opening / closing / stopped / calibrating	R	State of the cover
<device_name>.cover.<channel_id>.state	open	W	Open the cover
<device_name>.cover.<channel_id>.state	close	W	Close the cover
<device_name>.cover.<channel_id>.state	stop	W	Stop the cover
<device_name>.cover.<channel_id>.state	0...100%	R/W	Move the cover to the target position
<device_name>.cover.<channel_id>.apower	<value>	R	Active power in Watts
<device_name>.cover.<channel_id>.voltage	<value>	R	Volts
<device_name>.cover.<channel_id>.current	<value>	R	Amperes
<device_name>.cover.<channel_id>.pf	<value>	R	power factor
<device_name>.cover.<channel_id>.freq	<value>	R	network frequency, Hz
<device_name>.cover.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.cover.<channel_id>.current_pos	<value>	R	Only present if Cover is calibrated. Represents current position in percent from 0 (fully closed) to 100 (fully open)
<device_name>.cover.<channel_id>.target_pos	<value>	R	Only present if Cover is calibrated and is actively moving to a requested position in either open or closed directions. Represents the target position in percent from 0 (fully closed) to 100 (fully open)
<device_name>.cover.<channel_id>.move_timeout	<value>	R	Seconds, only present if Cover is actively moving in either open or closed directions. Cover will automatically stop after the timeout expires
<device_name>.cover.<channel_id>.move_started_at	<value>	R	Only present if Cover is actively moving in either open or closed directions. Represents the time at which the movement has begun
<device_name>.cover.<channel_id>.pos_control	<value>	R	0 if Cover is not calibrated and only discrete open/close is possible; 1 if Cover is calibrated and can be commanded to go to arbitrary positions between fully open and fully closed
<device_name>.cover.<channel_id>.last_direction	<value>	R	Direction of the last movement: open/close or null when unknown
<device_name>.cover.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.cover.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.cover.<channel_id>.slat_pos	<value>	R	Only present if slat control is supported and enabled. Represents current slat position in percent from 0 (fully closed) to 100 (fully open)
<device_name>.cover.<channel_id>.errors	<value>	R	Only present if an error condition has occurred. May contain overtemp, overpower, overvoltage, undervoltage, overcurrent, obstruction, safety_switch, bad_feedback:rotating_in_wrong_direction, bad_feedback:both_directions_active, bad_feedback:failed_to_halt, cal_abort:timeout_open, cal_abort:timeout_close, cal_abort:safety, cal_abort:ext_command, cal_abort:bad_feedback, cal_abort:implausible_time_to_fully_close, cal_abort:implausible_time_to_fully_open, cal_abort:implausible_power_consumption_in_close_dir, cal_abort:implausible_power_consumption_in_open_dir, cal_abort:too_many_steps_to_close, cal_abort:too_few_steps_to_close, cal_abort:implausible_time_to_fully_close_w_steps, cal_abort:implausible_step_duration_in_open_dir, cal_abort:too_many_steps_to_open, cal_abort:too_few_steps_to_open, cal_abort:implausible_time_to_fully_open_w_steps

RGB channel

ID	Value	R/W	Description
<device_name>.rgb.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.rgb.<channel_id>.state	on / off / 1 / 0	W	Channel output on or off. The color is not changed
<device_name>.rgb.<channel_id>.state	flip	W	Invert the output channel state
<device_name>.rgb.<channel_id>.rgb	0...255,0...255,0...255	R	Channel color, whether the channel is on or off. See Color Channels
<device_name>.rgb.<channel_id>.rgb	0...255,0...255,0...255	W	Set the channel color. The state is not changed. Commas, semicolons, asterisks or spaces are all accepted as separators
<device_name>.rgb.<channel_id>.rgb	0...255,0...255,0...255,on	W	Set the color and the state in one write, with on or off as the last field
<device_name>.rgb.<channel_id>.rgb	0,0,0	W	Ignored: all zeros is not a color. Use off to turn the channel off
<device_name>.rgb.<channel_id>.rgb	on / off / flip	W	Channel output on, off, or inverted
<device_name>.rgb.<channel_id>.brightness	0...100%	R	Channel output brightness, while the channel is on
<device_name>.rgb.<channel_id>.brightness	off	R	Channel output off. The brightness the channel comes back to is not lost
<device_name>.rgb.<channel_id>.brightness	1...100%	W	Set the brightness, turning the channel on
<device_name>.rgb.<channel_id>.brightness	0	W	Turn the channel off, keeping the brightness
<device_name>.rgb.<channel_id>.brightness	on / off / flip	W	Channel output on, off, or inverted. The brightness is not changed
<device_name>.rgb.<channel_id>.fault	0 / 1	R	Whether the device is unreachable. See Faults
<device_name>.rgb.<channel_id>.transition.target.output	<value>	R	Whether the transition output channel is on
<device_name>.rgb.<channel_id>.transition.target.rgb.r	<value>	R	Transition rgb level (<R> component)
<device_name>.rgb.<channel_id>.transition.target.rgb.g	<value>	R	Transition rgb level (<G> component)
<device_name>.rgb.<channel_id>.transition.target.rgb.b	<value>	R	Transition rgb level (<B> component)
<device_name>.rgb.<channel_id>.transition.target.brightness	<value>	R	Transition brightness level (in percent)
<device_name>.rgb.<channel_id>.transition.duration	<value>	R	Duration of the transition in seconds
<device_name>.rgb.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.rgb.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.rgb.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.rgb.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.rgb.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.rgb.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.rgb.<channel_id>.errors	<value>	R	Error conditions occurred. May contain overtemp

RGBW channel

ID	Value	R/W	Description
<device_name>.rgbw.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.rgbw.<channel_id>.state	on / off / 1 / 0	W	Channel output on or off. The color is not changed
<device_name>.rgbw.<channel_id>.state	flip	W	Invert the output channel state
<device_name>.rgbw.<channel_id>.rgb	0...255,0...255,0...255,0...255	R	Channel color, with the white channel as a fourth field, whether the channel is on or off. See Color Channels
<device_name>.rgbw.<channel_id>.rgb	0...255,0...255,0...255	W	Set the three color channels, leaving the white channel as it is. The state is not changed
<device_name>.rgbw.<channel_id>.rgb	0...255,0...255,0...255,0...255	W	Set the three color channels and the white channel
<device_name>.rgbw.<channel_id>.rgb	0...255,0...255,0...255,on	W	Set the color and the state in one write, with on or off as the last field
<device_name>.rgbw.<channel_id>.rgb	0,0,0	W	Ignored: all zeros is not a color. Use off to turn the channel off
<device_name>.rgbw.<channel_id>.rgb	on / off / flip	W	Channel output on, off, or inverted
<device_name>.rgbw.<channel_id>.brightness	0...100%	R	Channel output brightness, while the channel is on
<device_name>.rgbw.<channel_id>.brightness	off	R	Channel output off. The brightness the channel comes back to is not lost
<device_name>.rgbw.<channel_id>.brightness	1...100%	W	Set the brightness, turning the channel on
<device_name>.rgbw.<channel_id>.brightness	0	W	Turn the channel off, keeping the brightness
<device_name>.rgbw.<channel_id>.brightness	on / off / flip	W	Channel output on, off, or inverted. The brightness is not changed
<device_name>.rgbw.<channel_id>.white	0...255	R	Channel output white, while the channel is on
<device_name>.rgbw.<channel_id>.white	off	R	Channel output off. The white level the channel comes back to is not lost
<device_name>.rgbw.<channel_id>.white	1...255 or 1...100%	W	Set the white channel, turning the channel on
<device_name>.rgbw.<channel_id>.white	0	W	Turn the channel off, keeping the white channel
<device_name>.rgbw.<channel_id>.white	on / off / flip	W	Channel output on, off, or inverted. The white channel is not changed
<device_name>.rgbw.<channel_id>.fault	0 / 1	R	Whether the device is unreachable. See Faults
<device_name>.rgbw.<channel_id>.transition.target.output	<value>	R	Whether the transition output channel is on
<device_name>.rgbw.<channel_id>.transition.target.rgb.r	<value>	R	Transition rgb level (<R> component)
<device_name>.rgbw.<channel_id>.transition.target.rgb.g	<value>	R	Transition rgb level (<G> component)
<device_name>.rgbw.<channel_id>.transition.target.rgb.b	<value>	R	Transition rgb level (<B> component)
<device_name>.rgbw.<channel_id>.transition.target.brightness	<value>	R	Transition brightness level (in percent)
<device_name>.rgbw.<channel_id>.transition.target.white	<value>	R	Transition white level
<device_name>.rgbw.<channel_id>.transition.duration	<value>	R	Duration of the transition in seconds
<device_name>.rgbw.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.rgbw.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.rgbw.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.rgbw.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.rgbw.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.rgbw.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.rgbw.<channel_id>.errors	<value>	R	Error conditions occurred. May contain overtemp

CCT channel

ID	Value	R/W	Description
<device_name>.cct.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.cct.<channel_id>.state	off	W	Channel output off
<device_name>.cct.<channel_id>.state	on	W	Channel output on
<device_name>.cct.<channel_id>.brightness	0...100	R	Channel output brightness
<device_name>.cct.<channel_id>.brightness	0...100%	W	Channel output brightness
<device_name>.cct.<channel_id>.ct	<value>	R	Channel output color temperature (in Kelvin)
<device_name>.cct.<channel_id>.ct	1000...10000	W	Channel output color temperature (in Kelvin)
<device_name>.cct.<channel_id>.timer_started_at	<value>	R	Unix timestamp, start time of the timer (in UTC)
<device_name>.cct.<channel_id>.timer_duration	<value>	R	Duration of the timer (in seconds)
<device_name>.cct.<channel_id>.transition.target.output	<value>	R	Whether the transition output channel is on
<device_name>.cct.<channel_id>.transition.target.brightness	<value>	R	Transition brightness level (in percent)
<device_name>.cct.<channel_id>.transition.target.ct	<value>	R	Transition color temperaturee level
<device_name>.cct.<channel_id>.transition.started_at	<value>	R	Unix timestamp, start time of the transition (in UTC)
<device_name>.cct.<channel_id>.transition.duration	<value>	R	Duration of the transition in seconds
<device_name>.cct.<channel_id>.temperature.tC	<value>	R	Temperature in Celsius
<device_name>.cct.<channel_id>.temperature.tF	<value>	R	Temperature in Fahrenheit
<device_name>.cct.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.cct.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.cct.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.cct.<channel_id>.errors	<value>	R	Error conditions occurred. May contain overtemp

RGBCCT channel

ID	Value	R/W	Description
<device_name>.rgbcct.<channel_id>.state	0 / 1	R	Output channel state
<device_name>.rgbcct.<channel_id>.state	on / off / 1 / 0	W	Channel output on or off. The color is not changed
<device_name>.rgbcct.<channel_id>.state	flip	W	Invert the output channel state
<device_name>.rgbcct.<channel_id>.rgb	0...255,0...255,0...255	R	Channel color, whether the channel is on or off. See Color Channels
<device_name>.rgbcct.<channel_id>.rgb	0...255,0...255,0...255	W	Set the channel color. The state is not changed. Commas, semicolons, asterisks or spaces are all accepted as separators
<device_name>.rgbcct.<channel_id>.rgb	0...255,0...255,0...255,on	W	Set the color and the state in one write, with on or off as the last field
<device_name>.rgbcct.<channel_id>.rgb	0,0,0	W	Ignored: all zeros is not a color. Use off to turn the channel off
<device_name>.rgbcct.<channel_id>.rgb	on / off / flip	W	Channel output on, off, or inverted
<device_name>.rgbcct.<channel_id>.brightness	0...100%	R	Channel output brightness, while the channel is on
<device_name>.rgbcct.<channel_id>.brightness	off	R	Channel output off. The brightness the channel comes back to is not lost
<device_name>.rgbcct.<channel_id>.brightness	1...100%	W	Set the brightness, turning the channel on
<device_name>.rgbcct.<channel_id>.brightness	0	W	Turn the channel off, keeping the brightness
<device_name>.rgbcct.<channel_id>.brightness	on / off / flip	W	Channel output on, off, or inverted. The brightness is not changed
<device_name>.rgbcct.<channel_id>.ct	1000...10000	R/W	Channel output color temperature (in Kelvin)
<device_name>.rgbcct.<channel_id>.fault	0 / 1	R	Whether the device is unreachable. See Faults
<device_name>.rgbcct.<channel_id>.transition.target.output	<value>	R	Whether the transition output channel is on
<device_name>.rgbcct.<channel_id>.transition.target.rgb.r	<value>	R	Transition rgb level (<R> component)
<device_name>.rgbcct.<channel_id>.transition.target.rgb.g	<value>	R	Transition rgb level (<G> component)
<device_name>.rgbcct.<channel_id>.transition.target.rgb.b	<value>	R	Transition rgb level (<B> component)
<device_name>.rgbcct.<channel_id>.transition.target.brightness	<value>	R	Transition brightness level (in percent)
<device_name>.rgbcct.<channel_id>.transition.target.ct	<value>	R	Transition color temperaturee level
<device_name>.rgbcct.<channel_id>.transition.duration	<value>	R	Duration of the transition in seconds
<device_name>.rgbcct.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.rgbcct.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load

TEMPERATURE channel

ID	Value	R/W	Description
<device_name>.temperature.<channel_id>.tC	<value>	R	Temperature in Celsius
<device_name>.temperature.<channel_id>.tF	<value>	R	Temperature in Fahrenheit
<device_name>.temperature.<channel_id>.errors	<value>	R	Error conditions occurred. May contain out_of_range, read

HUMIDITY channel

ID	Value	R/W	Description
<device_name>.humidity.<channel_id>.rh	<value>	R	Relative humidity in %
<device_name>.humidity.<channel_id>.errors	<value>	R	Shown only if at least one error is present. May contain out_of_range, read when there is problem reading sensor

ILLUMINANCE channel

ID	Value	R/W	Description
<device_name>.illuminance.<channel_id>.lux	<value>	R	Measured illuminance in lux
<device_name>.illuminance.<channel_id>.illumination	<value>	R	Illuminance level. May contain dark, twilight, bright
<device_name>.illuminance.<channel_id>.errors	<value>	R	Shown only if at least one error is present. May contain out_of_range, read

DEVICEPOWER channel

ID	Value	R/W	Description
<device_name>.devicepower.<channel_id>.battery.V	<value>	R	Battery voltage in Volts
<device_name>.devicepower.<channel_id>.battery.percent	<value>	R	Battery charge level in %
<device_name>.devicepower.<channel_id>.external.present	<value>	R	Whether external power source is connected

SMOKE channel

ID	Value	R/W	Description
<device_name>.smoke.<channel_id>.alarm	<value>	R	Whether the alarm state is on
<device_name>.smoke.<channel_id>.mute	<value>	R	Whether the mute state is on

FLOOD channel

ID	Value	R/W	Description
<device_name>.flood.<channel_id>.alarm	<value>	R	Whether the alarm state is on
<device_name>.flood.<channel_id>.mute	<value>	R	Whether the mute state is on
<device_name>.flood.<channel_id>.errors	<value>	R	Shown only if at least one error is present

VOLTMETER channel

ID	Value	R/W	Description
<device_name>.voltmeter.<channel_id>.voltage	<value>	R	Voltage in volts
<device_name>.voltmeter.<channel_id>.xvoltage	<value>	R	voltage transformed with config.xvoltage.expr
<device_name>.voltmeter.<channel_id>.errors	<value>	R	Shown only if at least one error is present. May contain out_of_range, read when there is problem reading sensor

EM channel

ID	Value	R/W	Description
<device_name>.em.<channel_id>.a_current	<value>	R	Phase A current measurement value, [A]
<device_name>.em.<channel_id>.a_voltage	<value>	R	Phase A voltage measurement value, [V]
<device_name>.em.<channel_id>.a_act_power	<value>	R	Phase A active power measurement value, [W]
<device_name>.em.<channel_id>.a_aprt_power	<value>	R	Phase A apparent power measurement value, [VA]
<device_name>.em.<channel_id>.a_pf	<value>	R	Phase A power factor measurement value
<device_name>.em.<channel_id>.a_freq	<value>	R	Phase A network frequency measurement value
<device_name>.em.<channel_id>.a_errors	<value>	R	Phase A error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current
<device_name>.em.<channel_id>.b_current	<value>	R	Phase B current measurement value, [A]
<device_name>.em.<channel_id>.b_voltage	<value>	R	Phase B voltage measurement value, [V]
<device_name>.em.<channel_id>.b_act_power	<value>	R	Phase B active power measurement value, [W]
<device_name>.em.<channel_id>.b_aprt_power	<value>	R	Phase B apparent power measurement value, [VA]
<device_name>.em.<channel_id>.b_pf	<value>	R	Phase B power factor measurement value
<device_name>.em.<channel_id>.b_freq	<value>	R	Phase B network frequency measurement value
<device_name>.em.<channel_id>.b_errors	<value>	R	Phase B error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current
<device_name>.em.<channel_id>.c_current	<value>	R	Phase C current measurement value, [A]
<device_name>.em.<channel_id>.c_voltage	<value>	R	Phase C voltage measurement value, [V]
<device_name>.em.<channel_id>.c_act_power	<value>	R	Phase C active power measurement value, [W]
<device_name>.em.<channel_id>.c_aprt_power	<value>	R	Phase C apparent power measurement value, [VA]
<device_name>.em.<channel_id>.c_pf	<value>	R	Phase C power factor measurement value
<device_name>.em.<channel_id>.c_freq	<value>	R	Phase C network frequency measurement value
<device_name>.em.<channel_id>.c_errors	<value>	R	Phase C error conditions occurred. May contain out_of_range:active_power, out_of_range:apparent_power, out_of_range:voltage, out_of_range:current
<device_name>.em.<channel_id>.n_current	<value>	R	Neutral current measurement value, [A] (if supported)
<device_name>.em.<channel_id>.n_errors	<value>	R	Neutral error conditions occurred. May contain out_of_range:current
<device_name>.em.<channel_id>.total_current	<value>	R	Sum of the current on all phases(excluding neutral readings if available)
<device_name>.em.<channel_id>.total_act_power	<value>	R	Sum of the active power on all phases
<device_name>.em.<channel_id>.total_aprt_power	<value>	R	Sum of the apparent power on all phases
<device_name>.em.<channel_id>.user_calibrated_phase	<value>	R	Indicates which phase was user calibrated
<device_name>.em.<channel_id>.errors	<value>	R	EM component error conditions. May contain power_meter_failure, phase_sequence, ct_type_not_set

EMDATA channel

ID	Value	R/W	Description
<device_name>.emdata.<channel_id>.a_total_act_energy	<value>	R	Total active energy on phase A, Wh
<device_name>.emdata.<channel_id>.a_total_act_ret_energy	<value>	R	Total active returned energy on phase A, Wh
<device_name>.emdata.<channel_id>.b_total_act_energy	<value>	R	Total active energy on phase B, Wh
<device_name>.emdata.<channel_id>.b_total_act_ret_energy	<value>	R	Total active returned energy on phase B, Wh
<device_name>.emdata.<channel_id>.c_total_act_energy	<value>	R	Total active energy on phase C, Wh
<device_name>.emdata.<channel_id>.c_total_act_ret_energy	<value>	R	Total active returned energy on phase C, Wh
<device_name>.emdata.<channel_id>.total_act	<value>	R	Total active energy on all phases, Wh
<device_name>.emdata.<channel_id>.total_act_ret	<value>	R	Total active returned energy on all phases, Wh
<device_name>.emdata.<channel_id>.errors	<value>	R	Error condition occurred. May contain database_error, ct_type_not_set

EM1 channel

ID	Value	R/W	Description
<device_name>.em1.<channel_id>.current	<value>	R	Current measurement value, [A]
<device_name>.em1.<channel_id>.voltage	<value>	R	Voltage measurement value, [V]
<device_name>.em1.<channel_id>.act_power	<value>	R	Active power measurement value, [W]
<device_name>.em1.<channel_id>.aprt_power	<value>	R	Apparent power measurement value, [VA]
<device_name>.em1.<channel_id>.pf	<value>	R	Power factor measurement value
<device_name>.em1.<channel_id>.freq	<value>	R	Network frequency measurement value
<device_name>.em1.<channel_id>.calibration	<value>	R	Indicates factory calibration or which EM1:id is the source for calibration
<device_name>.em1.<channel_id>.errors	<value>	R	EM1 component error conditions. May contain power_meter_failure, out_of_range:act_power, out_of_range:aprt_power, out_of_range:voltage, out_of_range:current or ct_type_not_set
<device_name>.em1.<channel_id>.flags	<value>	R	Communicates present conditions. Depending on component capabilites may contain: count_disabled

EM1DATA channel

ID	Value	R/W	Description
<device_name>.em1data.<channel_id>.total_act_energy	<value>	R	Total active energy, Wh
<device_name>.em1data.<channel_id>.total_act_ret_energy	<value>	R	Total active returned energy, Wh
<device_name>.em1data.<channel_id>.errors	<value>	R	Error condition occurred. May contain database_error, ct_type_not_set

PM1 channel

ID	Value	R/W	Description
<device_name>.pm1.<channel_id>.voltage	<value>	R	Last measured voltage in Volts
<device_name>.pm1.<channel_id>.current	<value>	R	Last measured current in Amperes
<device_name>.pm1.<channel_id>.apower	<value>	R	Last measured instantaneous active power (in Watts) delivered to the attached load
<device_name>.pm1.<channel_id>.aprtpower	<value>	R	Last measured instantaneous apparent power (in Volt-Amperes) delivered to the attached load
<device_name>.pm1.<channel_id>.pf	<value>	R	Last measured power factor
<device_name>.pm1.<channel_id>.freq	<value>	R	Last measured network frequency
<device_name>.pm1.<channel_id>.aenergy.total	<value>	R	Total energy consumed in Watt-hours
<device_name>.pm1.<channel_id>.ret_aenergy.total	<value>	R	Total returned energy consumed in Watt-hours
<device_name>.pm1.<channel_id>.errors	<value>	R	Error conditions occurred. May contain power_meter_failure, out_of_range:voltage, out_of_range:current, out_of_range:aprtpower, out_of_range:apower

DALI channel

ID	Value	R/W	Description
<device_name>.dali.cg_count	<value>	R	Number of control gears found on the DALI bus
<device_name>.dali.scan.cg_count	<value>	R	Number of control gears found by the scan in progress
<device_name>.dali.scan.started_at	<value>	R	Unix timestamp, start time of the scan (in UTC)
<device_name>.dali.errors	<value>	R	Shown only if at least one error is present

ETH channel

ID	Value	R/W	Description
<device_name>.eth.ip	<value>	R	IP address of the device on the Ethernet interface

Color Channels

The RGB, RGBW and RGBCCT channels of a device are color channels, and behave the same way as the color devices of every other I/O Server that publishes one.

A color channel holds a color, a brightness and an on/off state, and the three are independent. Turning a channel off does not change its color: <device_name>.<channel_name>.<channel_id>.rgb always reports the color the channel is showing, or the color it will show when it is turned back on, so a user interface can display it either way.

plusrgbwpm_1.rgb.0.rgb          255,67,31
plusrgbwpm_1.rgb.0.brightness   off
plusrgbwpm_1.rgb.0.state        0

The level reports what the channel is emitting, so it reads off while the channel is off, and comes back to the level it was given when the channel is turned on again.

An RGBW channel drives a white LED as well, reported on its own as .white and as a fourth field of .rgb, and an RGBCCT channel has a color temperature, reported as .ct.

Writing a color accepts a comma, a semicolon, an asterisk or spaces as the separator, so all of these set the same color:

IO shelly.plusrgbwpm_1.rgb.0.rgb = 255,67,31
IO shelly.plusrgbwpm_1.rgb.0.rgb = 255;67;31
IO shelly.plusrgbwpm_1.rgb.0.rgb = 255*67*31
IO shelly.plusrgbwpm_1.rgb.0.rgb = 255 67 31

Each channel is a number from 0 to 255, or a percentage of full output such as 50%. A channel above its range is clamped to it, while a value that is negative, not a number, or a list with the wrong number of fields is rejected with an error in the log and changes nothing.

Color, state and brightness

Setting a color never turns a channel on. The state changes only when it is written: with on, off or flip, on the .state data point or on the .rgb one, or by adding on or off as a last field to a color, which sets both in one write.

IO shelly.plusrgbwpm_1.rgb.0.rgb = 255,67,31        # set the color, on or off as it was
IO shelly.plusrgbwpm_1.rgb.0.rgb = 255,67,31,on     # set the color and turn it on
IO shelly.plusrgbwpm_1.rgb.0.state = 1              # turn it on, at the color it was given

A color of all zeros is not a color, and is ignored, so the stored color is never lost and a color that shows nothing while the channel is on cannot be constructed. An on or off written as the last field still applies. On an RGBW channel, a color of three fields sets the three color channels and leaves the white channel as it is; a fourth field sets the white channel as well.

The .brightness and .white data points behave as dimmers, so that a slider or a knob bound to either of them works with no extra logic. A level written to them turns the channel on, and 0 turns it off, leaving the level where it was. They also take on, off and flip, which change the state without touching the level, and they report off while the channel is off, so a slider bound to either sits at the bottom until the channel comes back on.

Everything a single write asks for is sent to the device as one change, so setting a color and a state together does not make the lamp flicker through an intermediate state.

Faults

<device_name>.<channel_name>.<channel_id>.fault is set while the device is unreachable, mirroring the <device_name>.offline data point, and adds a fault field to the values the channel and its brightness and white companions are published with in the catalog, <r>*<g>*<b>*<on|off>*fault, <n>%*fault and <w>/255*fault, which is what makes the user interface raise its fault flag over them. Nothing else changes: the color and the state are left in place, so an interface still shows the channel as it was last reported. The flag is cleared as soon as the device answers again.

User Interface

To control a color channel, add a colorpicker object to your project page, set its action to datapoint and its datapoint to the channel's .rgb data point. Its on/off button writes on and off to the same data point.

For the brightness, and for the white LED of an RGBW channel, add a slider or a knob, set its action to datapoint, its datapoint to the .brightness or .white data point, and its range to 0,100 or 0,255 respectively.

<colorpicker action="datapoint" datapoint="shelly.plusrgbwpm_1.rgb.0.rgb" hsv="true" onoffbutton="true" />
<slider action="datapoint" datapoint="shelly.plusrgbwpm_1.rgb.0.brightness" range="0,100" />
<slider action="datapoint" datapoint="shelly.plusrgbwpm_1.rgbw.0.white" range="0,255" />

note

In the catalog, and therefore in the User Interface, a color channel is published as <r>*<g>*<b>*<on|off> on both its .rgb and its .state data points, so a project written against either name works with the colorpicker. This is not the value of those data points themselves, which report the plain comma separated color and the plain state. The brightness is published as <n>%, the same value its data point carries, and the white channel in the <w>/255 fractional format, both as off when the channel is emitting nothing, so that sliders and knobs show the correct position without any conversion.

Examples

Setting devices' states

init : IO shelly.plus2pm_1.switch.0.state shelly.plus2pm_1.switch.1.state = 1
init : IO shelly.plus10v_1.light.0.state = 75%

The first line sets the two switch channels (IDs 0 and 1) of the device named 'plus2pm_1' to 1 or on. The second line sets the light's brightness of device 'plus10v_1' to 75.

Release Notes

4.2.0

• BREAKING CHANGE. A level written to .brightness or .white now turns the channel on, as a dimmer does, and 0 turns the channel off instead of being sent to the device as a zero level. User code that set a level without meaning to switch the channel on must write the level and the state separately
• BREAKING CHANGE. The .rgb data point now reports <r>,<g>,<b>. It was documented as write only, but the driver was publishing the raw JSON array reported by the device, such as [255,67,31]: user code that read and parsed that value must be updated
• BREAKING CHANGE. The .brightness data point now reports a percentage, and both .brightness and .white report off while the channel is off, where they used to report the plain level the device reports. User code that read either of them as a number must be updated
• RGB, RGBW and RGBCCT channels now follow the color device behavior shared by all the I/O Servers that publish one, and can be controlled with the colorpicker object, which the Shelly I/O Server did not offer before. See Color Channels
• the .rgb data point is now readable, and reports the color as <r>,<g>,<b>, with the white channel as a fourth field on an RGBW channel. It used to be write only, and the value published internally was the raw JSON array the device reports, such as [255,67,31]
• a color and a state can now be set in one write, by adding on or off as a last field to a color; a color of all zeros is ignored; and a write accepts commas, semicolons, asterisks or spaces as separators
• the .state and .rgb data points now accept flip, to invert the state of a channel
• a level written to .brightness or .white now turns the channel on, as a dimmer does, and 0 turns it off keeping the level, so a slider can bring a channel that is off back up
• added the .fault data point of color channels, set while the device is unreachable. The channel keeps its color and its state, and the user interface raises its fault flag over them
• fixed the RGBCCT channel of the Shelly RGBCCT Bulb, whose status was not published at all and whose color could not be set
• added support for the Shelly Pro 3 EM (SPEM-003CEBEU), and for the model codes of the Shelly Dimmer 0/1-10V PM (Gen4) (S4DM-0010WW), of the UL versions of the Shelly Pro 1, Pro 1 PM, Pro 2, Pro 2 PM, Pro 3 and Pro 4 PM, and of the V1 versions of the Shelly Plus Plug S (SNPL-00110EU, SNPL-0112EU)

4.1.0

• added support for Shelly Pro EM 50, Shelly Plug M, Shelly Plug PM, Shelly Duo Bulb, Shelly RGBCCT Bulb, Shelly Shutter, Shelly EM Mini (Gen4), Shelly Flood, Shelly 2 PM (Gen4), Shelly Plug US, Shelly Dimmer (Gen4), Shelly Dimmer US (Gen4), Shelly Dimmer 0/1-10V PM (Gen4), Shelly Power Strip, plus Shelly Pro (Gen2) UL versions

4.0.1

• added support for Shelly Pro 3 EM, plus Shelly Pro 4 PM UL versions

4.0.0

• initial release

---

SHELLY is a trademark of SHELLY GROUP SE