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: Plus / Pro series of devices
- Shelly Plus Mini: Shelly Plus devices in compact format (Gen 2 + 3)
| Model | Vendor ID |
|---|---|
| Shelly Plus 1 Mini | SNSW-001X8EU |
| Shelly Plus 1 PM Mini | SNSW-001P8EU |
| Shelly Plus 2 PM | SNSW-002P16EU / SNSW-102P16EU |
| Shelly Plus I4 | SNSN-0024X |
| Shelly Plus Plug IT | SNPL-00110IT |
| Shelly Plus Plug S V2 | SNPL-10112EU / 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 0-10V Dimmer | SNDM-00100WW |
| Shelly Plus PM Mini | SNPM-001PCEU16 |
| Shelly Plus Uni | SNSN-0043X |
| Shelly Pro 1 | SPSW-201XE16EU / SPSW-001XE16EU |
| Shelly Pro 1 PM | SPSW-001PE16EU / SPSW-201PE16EU |
| Shelly Pro 2 | SPSW-002XE16EU / SPSW-202XE16EU |
| Shelly Pro 2 PM | SPSW-002PE16EU / SPSW-202PE16EU |
| Shelly Pro 3 | SPSW-003XE16EU |
| Shelly Pro 4 PM | SPSW-004PE16EU / SPSW-104PE16E |
| Shelly Pro Dual Cover PM | SPSH-002PE16EU |
| Shelly Pro EM | SPEM-002CEBEU50 |
| Shelly Pro 3 EM (400) | SPEM-003CEBEU120 |
| Shelly Pro Dimmer 1 PM | SPDM-001PE01EU |
| Shelly Pro Dimmer 2 PM | SPDM-002PE01EU |
| Shelly Pro Dimmer 0/1-10V PM | SPCC-001PE10EU |
| Shelly BLU Gateway | GWF-KZ01 |
| Shelly 1 | S3SW-001X16EU |
| Shelly 1 PM | S3SW-001P16EU |
| Shelly 2 PM | S3SW-002P16EU |
| Shelly I4 | S3SN-0024X |
| Shelly 1 Mini | S3SW-001X8EU |
| Shelly 1 PM Mini | S3SW-001P8EU |
| Shelly PM Mini | S3PM-001PCEU16 |
| Shelly Plug S | S3PL-00112EU |
| Shelly Dimmer 0/1-10V PM | S3DM-0010WW |
| Shelly Dali Dimmer | S3DM-0A1WW |
| Shelly H&T | S3SN-0U12A |
| Shelly EM | S3EM-002CXCEU |
| Shelly BLU Gateway Gen3 | S3GW-1DBT001 |
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
The systemtopo.txt file contains the list of all virtual devices that should be directly associated to graphic objects in the Web-based user interface.
This file can be filled manually or automatically by HSYCO at start-up. To enable automatic discovery and automatic generation of devices’ information in the systemtopo.txt file, use the discovery option in Settings.
This is an example of an automatically generated systemtopo.txt file:
(devices)
shelly.mini1g3_1.switch.0.switch : LIGHT ; LIGHT ; Mini1G3
shelly.plugsg3_1.switch.0.switch : LIGHT ; LIGHT ; PlugSG3
shelly.plus10v_1.light.0.light : LIGHT ; DIMMER ; Plus10V
shelly.plus2pm_1.cover.0.cover : AUTOM ; VSHUT ; Plus2PM
shelly.pro2_1.switch.0.switch : LIGHT ; LIGHT ; Pro2
shelly.pro2_1.switch.1.switch : LIGHT ; LIGHT ; Pro2
...
...
The description of the Devices is initialized to their short name, and it can be changed from the Utility, as well as their name.
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
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 |
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 |
<device_name>.light.<channel_id>.flags | <value> | R | Communicates present conditions. May contain no_load, uncalibrated |
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 |
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 |
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 |
VOLTMETER channel
| ID | Value | R/W | Description |
|---|---|---|---|
<device_name>.devicepower.<channel_id>.voltage | <value> | R | Voltage in volts |
<device_name>.devicepower.<channel_id>.xvoltage | <value> | R | voltage transformed with config.xvoltage.expr |
<device_name>.devicepower.<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 |
Examples
Settin 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.0.0
- initial release
SHELLY is a trademark of SHELLY GROUP SE