Skip to main content
Version: 1.0

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:

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

Methods

Sys.SetConfig

Properties:

PropertyTypeDescription

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:

PropertyTypeDescription

device

object

Information about the device

PropertyTypeDescription

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.

location

object

Information about the current location of the device

PropertyTypeDescription

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

PropertyTypeDescription

mqtt

object

Configuration of logs streamed over MQTT

PropertyTypeDescription

enable

boolean

True if enabled, false otherwise

websocket

object

Configuration of logs streamed over websocket.

PropertyTypeDescription

enable

boolean

True if enabled, false otherwise

udp

object

Configuration of logs streamed over UDP

PropertyTypeDescription

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

PropertyTypeDescription

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

PropertyTypeDescription

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

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:

PropertyTypeDescription

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

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

PropertyTypeDescription

beta

object

Shown only if beta update is available

PropertyTypeDescription

version

string

Version of the new firmware

stable

object

Shown only if stable update is available

PropertyTypeDescription

version

string

Version of the new firmware

wakeup_reason

object

Information about boot type and cause (only for battery-operated devices)

PropertyTypeDescription

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
note

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

Examples

Sys.SetConfig example

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

Response

{
"restart_required": false
}

Sys.GetConfig example

http://192.168.33.1/rpc/Sys.GetConfig

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

http://192.168.33.1/rpc/Sys.GetStatus

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