System

The system component provides information about general device status, resource usage, availability of firmware updates, etc.

The system component can be used to configure aspects of the device behavior:

• log streaming over websocket, UDP or serial port. Logs can provide valuable insight about firmware behavior and enable debugging;
• UDP RPC channel availability, useful in some integration scenarios;
• Local timezone and geolocation, used for scheduling and sunrise/sunset event time calculation;
• Experimental ECO Mode, which, when enabled throttles CPU speed and enables low-power mode for the WiFi radio when possible. This can signifficantly decrease power consumption, but may increase latency.

The system component uses Sys as RPC namespace. It handles the system services of a device and provides the minimal component interface:

• Sys.GetConfig to obtain the component's configuration
• Sys.SetConfig to update the component's configuration
• Sys.GetStatus to obtain the component's status

It uses the key sys when enumerated in objects including multiple component payloads, like Shelly.GetStatus.

Methods

Sys.SetConfig

Properties:

Property	Type	Description
config	object	Configuration that the method takes

Find more about the config properties in config section

Sys.GetConfig

Find the Sys.GetConfig response properties in config section

Sys.GetStatus

Find more about the status response properties in status section

Configuration

System configuration contains information about device's identifiers, location, debug logs, UI data, and communication over udp.

Properties:

Property	Type	Description
device	object	Information about the device Property Type Description name string Name of the device eco_mode boolean Experimental Decreases power consumption when set to true, at the cost of reduced execution speed and increased network latency mac string Read-only base MAC address of the device fw_id string Read-only build identifier of the current firmware image profile string Name of the device profile (only applicable for multi-profile devices) discoverable boolean If true, device is shown in 'Discovered devices'. If false, the device is hidden. addon_type string or null Enable/disable addon board (if supported). Range of values: sensor, prooutput; null to disable. sys_btn_toggle boolean Enable/disable outputs toggle when the system (reset) button is pressed (shown if applicable).
location	object	Information about the current location of the device Property Type Description tz string or null Timezone (null if unavailable) lat number or null Latitude in degrees (null if unavailable) lon number or null Longitude in degrees (null if unavailable)
debug	object	Configuration of the device's debug logs. See more about the debug logs and how to read them here Property Type Description mqtt object Configuration of logs streamed over MQTT Property Type Description enable boolean True if enabled, false otherwise websocket object Configuration of logs streamed over websocket. Property Type Description enable boolean True if enabled, false otherwise udp object Configuration of logs streamed over UDP Property Type Description addr string or null Address that the device log is streamed to (null to disable logs)
ui_data	object	User interface data
rpc_udp	object	Configuration for the RPC over UDP Property Type Description dst_addr string listen_port number or null Port number for inbound UDP RPC channel, null disables. Restart is required for changes to apply
sntp	object	Configuration for the sntp server Property Type Description server string Name of the sntp server
cfg_rev	number	Configuration revision. This number will be incremented for every configuration change of a device component. If the new config value is the same as the old one there will be no change of this property. Can not be modified explicitly by a call to Sys.SetConfig

info

sys_btn_toggle is available on a selected range of pro devices:

• ShellyPro1
• ShellyPro1PM
• ShellyPro2
• ShellyPro2PM
• ShellyPro3
• ShellyProEM
• ShellyPro3EM

It functions on the following principle:

In switch mode/profile:

• If at least one switch is ON -> set all switches to OFF.

• If all switches are OFF -> set all switches to ON.

In cover mode/profile, the device is acting as in cover->in_mode->single configuration (affected device: ShellyPro2PM).

Status

System status contains information about network state, system time and other common attributes of the Shelly device. Presence of some keys is optional, depending on the underlying hardware components.

Properties:

Property	Type	Description
mac	string	Mac address of the device
restart_required	boolean	True if restart is required, false otherwise
time	string	Current time in the format HH:MM (24-hour time format in the current timezone with leading zero). null when time is not synced from NTP server.
unixtime	number	Unix timestamp (in UTC), null when time is not synced from NTP server.
uptime	number	Time in seconds since last reboot
ram_size	number	Total size of the RAM in the system in Bytes
ram_free	number	Size of the free RAM in the system in Bytes
fs_size	number	Total size of the file system in Bytes
fs_free	number	Size of the free file system in Bytes
cfg_rev	number	Configuration revision number
kvs_rev	number	KVS (Key-Value Store) revision number
schedule_rev	number	Schedules revision number, present if schedules are enabled
webhook_rev	number	Webhooks revision number, present if webhooks are enabled
knx_rev	number	KNX configuration revision number, present on devices supporting KNX with KNX enabled
available_updates	object	Information about available updates, similar to the one returned by Shelly.CheckForUpdate (empty object: {} , if no updates available). This information is automatically updated every 24 hours. Note that build_id and url for an update are not displayed here Property Type Description beta object Shown only if beta update is available Property Type Description version string Version of the new firmware stable object Shown only if stable update is available Property Type Description version string Version of the new firmware
wakeup_reason	object	Information about boot type and cause (only for battery-operated devices) Property Type Description boot Boot type, one of: poweron, software_restart, deepsleep_wake, internal (e.g. brownout detection, watchdog timeout, etc.), unknown cause Boot cause, one of: button, usb, periodic, status_update, alarm, alarm_test, undefined (in case of deep sleep, reset was not caused by exit from deep sleep)
wakeup_period	number	Period (in seconds) at which device wakes up and sends "keep-alive" packet to cloud, readonly. Count starts from last full wakeup

MQTT control

Since version 0.14.0

The system component MQTT functionality provides commands for OTA updates.

• Shelly will subscribe to the following topics, accepting commands:

  • <topic_prefix>/command/sys

• Shelly publishes on:

  • <topic_prefix>/status/sys - topic where the result of the status_update and ota_update_check commands is published. The status_update command can be sent either on the common device topic or the component specific topic. This topic is already used for existing status notifications, if enabled.
  • <topic_prefix>/error/sys - error message is published if update is requested and the corresponding stage is not found.
  • <topic_prefix>/events/rpc - regular event notifications of OTA progress are published on this topic when update is started with the ota_update_to commands.

• Accepted commands are:

  • status_update - causes status of the sys component to be published on the <topic_prefix>/status/sys topic, which includes available updates information.
  • ota_update_check - causes the device to request information of available updates and then publishes component status which includes available updates information on the <topic_prefix>/status/sys topic. Also event notification with information for updates is published on the <topic_prefix>/events/rpc topic.
  • ota_update_to_stable, ota_update_to_beta, ota_update_to_test - starts an update for the specified stage.

note

<topic_prefix> is a custom prefix if set or defaults to <device_id>

Notifications

This section describes notifications for events specific to the System component. For general information please see this page.

The System component can send notifications for the following events:

• ota_begin
• ota_progress
• ota_success
• ota_error
• sleep
• scheduled_restart
• component_added
• component_removed
• sys_btn_down
• sys_btn_up
• sys_btn_push

note

component_added and component_removed events are produced whenever a new dynamic component or Shelly script is added or removed.

Examples

Sys.SetConfig example

Sys.SetConfig HTTP GET Request

http://192.168.33.1/rpc/Sys.SetConfig?config={"location":{"tz":"Europe/Sofia"}}

Sys.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"Sys.SetConfig","params":{"config":{"location":{"tz":"Europe/Sofia"}}}}' http://${SHELLY}/rpc

Sys.SetConfig Mos Request

mos --port ${PORT} call Sys.SetConfig '{"config":{"location":{"tz":"Europe/Sofia"}}}'

Response

Sys.SetConfig HTTP GET Response

{
  "restart_required": false
}

Sys.SetConfig Curl Response

{
  "id": 1,
  "src": "shellyplus2pm-a8032ab636ec",
  "params": {
    "restart_required": false
  }
}

Sys.SetConfig Mos Response

{
  "restart_required": false
}

Sys.GetConfig example

Sys.GetConfig HTTP GET Request

http://192.168.33.1/rpc/Sys.GetConfig

Sys.GetConfig Curl Request

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

Sys.GetConfig Mos Request

mos --port ${PORT} call Sys.GetConfig

Response

Sys.GetConfig HTTP GET Response

{
  "device": {
    "name": null,
    "mac": "A8032AB636EC",
    "fw_id": "20220527-091739/0.10.2-beta4-gecc3a61",
    "eco_mode": false,
    "profile": "cover",
    "discoverable": false
  },
  "location": {
    "tz": "Europe/Sofia",
    "lat": 42.6534,
    "lon": 23.31119
  },
  "debug": {
    "mqtt": {
      "enable": false
    },
    "websocket": {
      "enable": false
    },
    "udp": {
      "addr": null
    }
  },
  "ui_data": {},
  "rpc_udp": {
    "dst_addr": null,
    "listen_port": null
  },
  "sntp": {
    "server": "time.google.com"
  },
  "cfg_rev": 10
}

Sys.GetConfig Curl Response

{
  "id": 1,
  "src": "shellyplus2pm-a8032ab636ec",
  "params": {
    "device": {
      "name": null,
      "mac": "A8032AB636EC",
      "fw_id": "20220527-091739/0.10.2-beta4-gecc3a61",
      "eco_mode": false,
      "profile": "cover",
      "discoverable": false
    },
    "location": {
      "tz": "Europe/Sofia",
      "lat": 42.6534,
      "lon": 23.31119
    },
    "debug": {
      "mqtt": {
        "enable": false
      },
      "websocket": {
        "enable": false
      },
      "udp": {
        "addr": null
      }
    },
    "ui_data": {},
    "rpc_udp": {
      "dst_addr": null,
      "listen_port": null
    },
    "sntp": {
      "server": "time.google.com"
    },
    "cfg_rev": 10
  }
}

Sys.GetConfig Mos Response

{
  "device": {
    "name": null,
    "mac": "A8032AB636EC",
    "fw_id": "20220527-091739/0.10.2-beta4-gecc3a61",
    "eco_mode": false,
    "profile": "cover",
    "discoverable": false
  },
  "location": {
    "tz": "Europe/Sofia",
    "lat": 42.6534,
    "lon": 23.31119
  },
  "debug": {
    "mqtt": {
      "enable": false
    },
    "websocket": {
      "enable": false
    },
    "udp": {
      "addr": null
    }
  },
  "ui_data": {},
  "rpc_udp": {
    "dst_addr": null,
    "listen_port": null
  },
  "sntp": {
    "server": "time.google.com"
  },
  "cfg_rev": 10
}

Sys.GetStatus example

Sys.GetStatus HTTP GET Request

http://192.168.33.1/rpc/Sys.GetStatus

Sys.GetStatus Curl Request

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

Sys.GetStatus Mos Request

mos --port ${PORT} call Sys.GetStatus

Response

Sys.GetStatus HTTP GET Response

{
  "mac": "A8032AB636EC",
  "restart_required": false,
  "time": "16:20",
  "unixtime": 1654694407,
  "uptime": 2339,
  "ram_size": 253464,
  "ram_free": 146012,
  "fs_size": 458752,
  "fs_free": 212992,
  "cfg_rev": 10,
  "kvs_rev": 277,
  "schedule_rev": 0,
  "webhook_rev": 0,
  "available_updates": {
    "stable": {
      "version": "0.10.2"
    }
  }
}

Sys.GetStatus Curl Response

{
  "id": 1,
  "src": "shellyplus2pm-a8032ab636ec",
  "params": {
    "mac": "A8032AB636EC",
    "restart_required": false,
    "time": "16:20",
    "unixtime": 1654694407,
    "uptime": 2339,
    "ram_size": 253464,
    "ram_free": 146012,
    "fs_size": 458752,
    "fs_free": 212992,
    "cfg_rev": 10,
    "kvs_rev": 277,
    "schedule_rev": 0,
    "webhook_rev": 0,
    "available_updates": {
      "stable": {
        "version": "0.10.2"
      }
    }
  }
}

Sys.GetStatus Mos Response

{
  "mac": "A8032AB636EC",
  "restart_required": false,
  "time": "16:20",
  "unixtime": 1654694407,
  "uptime": 2339,
  "ram_size": 253464,
  "ram_free": 146012,
  "fs_size": 458752,
  "fs_free": 212992,
  "cfg_rev": 10,
  "kvs_rev": 277,
  "schedule_rev": 0,
  "webhook_rev": 0,
  "available_updates": {
    "stable": {
      "version": "0.10.2"
    }
  }
}

Notifications example

The System component can send notifications for the following events:

• OTA begin:

Example 1:

Notify that OTA update has started.

{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266683.84,
      "events": [
         {
            "component": "sys",
            "event": "ota_begin",
            "msg": "Waiting for data",
            "ts": 1631266683.84
         }
      ]
   }
}

• OTA progress

Example 2:

Notify the current OTA update progress.

{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266684.6,
      "events": [
         {
            "component": "sys",
            "event": "ota_progress",
            "msg": "Waiting for data",
            "progress_percent": 22,
            "ts": 1631266684.6
         }
      ]
   }
}

• OTA success

Example 3:

Notify that OTA update has succeeded.

{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266736.82,
      "events": [
         {
            "component": "sys",
            "event": "ota_success",
            "msg": "Update applied, rebooting",
            "ts": 1631266736.82
         }
      ]
   }
}

• OTA error

Example 4:

Notify that OTA update has encountered an error.

{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266736.82,
      "events": [
         {
            "component": "sys",
            "event": "ota_error",
            "msg": "Unexpected end of data",
            "ts": 1631266736.82
         }
      ]
   }
}

• Sleep (only for battery-operated devices)

Example 5:

Notify that device is going to sleep.

{
   "src": "shellyplusht2-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266736.82,
      "events": [
         {
            "component": "sys",
            "event": "sleep",
            "ts": 1631266736.82
         }
      ]
   }
}

• Scheduled restart

Example 6:

Notify that device is going to reboot.

{
   "src": "shellyplus1-a8032abe54dc",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1664446358.14,
      "events": [
         {
            "component": "sys",
            "event": "scheduled_restart",
            "time_ms": 997,
            "ts": 1664446358.14
         }
      ]
   }
}

• Dynamic component added

Example 7:

Notify that a new dynamic component is added.

{
   "src": "shellyplus1-a8032abe54dc",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1705794984.07,
      "events": [
         {
            "component": "sys",
            "event": "component_added",
            "target":"script:1",
            "restart_required":false,
            "ts": 1705794984.07,
            "cfg_rev":10
         }
      ]
   }
}

• Dynamic component removed

Example 8:

Notify that some dynamic component is removed.

{
   "src": "shellyplus1-a8032abe54dc",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1705795031.69,
      "events": [
         {
            "component": "sys",
            "event": "component_removed",
            "target":"script:1",
            "restart_required":false,
            "ts": 1705795031.69,
            "cfg_rev":11
         }
      ]
   }
}

Request status over MQTT example

Subscription

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellyplus1-a8032abe54dc" # The <shelly-id> of your device
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/status/sys

Send command

export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellyplus1-a8032abe54dc" # The <shelly-id> of your device
mosquitto_pub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/command/sys -m status_update

Result

{
  "mac": "A8032ABE54DC",
  "restart_required": false,
  "time": "19:23",
  "unixtime": 1675272236,
  "uptime": 7971,
  "ram_size": 234768,
  "ram_free": 162196,
  "fs_size": 458752,
  "fs_free": 110592,
  "cfg_rev": 7,
  "kvs_rev": 1,
  "schedule_rev": 0,
  "webhook_rev": 0,
  "available_updates": {
    "beta": {
      "version": "0.13.0-beta1"
    },
    "stable": {
      "version": "0.12.0"
    }
  }
}