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.

It also facilitates backing up and restoring device settings as well as changing the factory defaults.

note

Backup and default configuration are available on all Gen3 and Gen4 devices, and on Gen2 devices still in active production (see Firmware Update Policy). They are not available on Shelly Plus Uni, Shelly Plus RGBW PM, Shelly EM Gen4 (Zigbee firmware) and Shelly 2PM Gen4 (Zigbee firmware), where there is not enough free flash space to include them.

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

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

Methods​

Sys.SetConfig​

Parameters:

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

Sys.SetTime​

Method sets system time.

Request:

PropertyTypeDescription

unixtime

number

Unix timestamp (in UTC) to set as current time


Fraction number, where the whole part (before decimal) is in seconds, fraction part in milliseconds (fraction part is optional and should be up to 3 digits)

note

If the device gets time from NTP server the set will be overwritten.

Sys.StartDiscovery​

(since 2.2.0)

note

Network discovery is available on all Gen3 and Gen4 devices, and on Gen2 devices still in active production (see Firmware Update Policy). It is not available on Gen4 devices running Zigbee firmware, where there is not enough free flash space to include it. These devices still advertise themselves over mDNS while connected to Wi-Fi, so other devices can discover them.

Starts a timed mDNS browse of the local network for other Shelly devices. Every Gen2+ Shelly advertises itself over the _shelly._tcp service, so this method makes it possible to enumerate the Shellies present on the network — with their name, model, firmware version and address — directly from the device, without relying on the cloud or the router.

The call returns null immediately and the scan runs in the background. Results are delivered asynchronously as discovery_results events, batched over a short window, followed by a single discovery_done event when the scan ends. While a scan is active, Sys.GetStatus includes a discovery object.

The host device does not appear in its own results. Results are not persisted — nothing is retained after the scan ends.

Request:

PropertyTypeDescription

duration

number

Optional, defaults to 10. Scan duration in seconds. Range: 5..60.

Returns null on success, or an error if a scan is already in progress or duration is out of range.

Sys.StopDiscovery​

(since 2.2.0)

Stops an in-progress Sys.StartDiscovery scan before its duration elapses, for example once the target device has been found. A discovery_done event is emitted exactly as it is for a naturally-expiring scan, so clients see one consistent terminal signal regardless of how the scan ended.

Takes no parameters. Returns null on success, or an error if no scan is currently in progress.

Backup operations and provisioning state​

Some backup-related operations are gated by the device's provisioning state. They expose data captured from the device filesystem (Wi-Fi passwords, cloud tokens, Matter fabric keys, etc.) or set/clear the authentication header that protects the default-configuration slot, so they are only allowed once the open setup window has closed:

Gated (allowed only in complete or locked)Not gated (allowed in any state)
Sys.CreateBackupSys.UploadBackup
Sys.DownloadBackupSys.RestoreBackup
GET /backup.zipSys.UploadDefaultConfig
Sys.CreateDefaultConfigSys.ApplyDefaultConfig
Sys.ClearDefaultConfig

In pending or confirmed, gated RPCs return an error indicating that the precondition is not met (the current provisioning state is included in the error message), and GET /backup.zip returns 503 Service Unavailable. The non-gated entries import data into the device rather than exfiltrate it, so they remain available during setup ("Unbox & Go").

Sys.CreateBackup​

Method creates a downloadable backup of the device setup.

note

Gated by provisioning state: only allowed in complete or locked.

Request:

PropertyTypeDescription

encrypt

boolean

Optional, defaults to false. When true, the device generates a random human-readable password, encrypts the archive with AES-128, and returns the password in the response. The password is not persisted; if lost the backup cannot be decrypted.

Response:

PropertyTypeDescription

key

string

Present only when encrypt: true was requested. Random ~145-bit password the client must keep in order to restore the backup later.

restart_required

boolean

Always true on success. The backup is produced early on the next boot, when the filesystem is quiet — see note below.

note

The device does not reboot on its own. After this call returns, Sys status reports restart_required: true (and a Sys status-change notification is emitted with the same field). The caller picks the moment to reboot, typically via Shelly.Reboot. The previous backup, if any, remains downloadable via Sys.DownloadBackup and the /backup.zip endpoint until the reboot. Once the reboot completes, the new backup is described by the backup property in the status.

Sys.DownloadBackup​

Method allows reading a previously created backup in chunks.

note

Gated by provisioning state: only allowed in complete or locked.

Request:

PropertyTypeDescription

offset

number

Chunk offset

len

number

Maximum number of bytes to read

Response:

PropertyTypeDescription

data

string

Base64-encoded data

left

number

Bytes remaining to be read

Sys.UploadBackup​

Method uploads a backup archive to the device in chunks. Call this first, inspect the returned manifest, then trigger the actual restore with Sys.RestoreBackup.

Sending offset: 0 implicitly discards any in-progress upload and starts a fresh session. Chunks must be ordered by offset with no gaps.

Request:

PropertyTypeDescription

offset

number

Chunk offset

data

string

Base64-encoded data

final

boolean

Marks the final chunk and triggers manifest extraction

Response (final chunk only):

PropertyTypeDescription

manifest

object

Metadata extracted from the uploaded archive's unencrypted manifest file

PropertyTypeDescription

created_at

number

Unix timestamp of backup creation

fw_ver

string

Firmware version of the source device

model

string

Device model identifier (e.g. SNSN-10138)

app_name

string

Application name (e.g. Pro4PM)

device_name

string

User-assigned device name, falls back to the device identifier when unset

encrypt

boolean

True when the archive is AES-encrypted and requires a decryption key

Sys.RestoreBackup​

Restores the backup uploaded via Sys.UploadBackup. The device reboots and extracts the archive onto a wiped filesystem. If the manifest returned by the upload step reports encrypt: true, a decryption key must be provided.

Request:

PropertyTypeDescription

key

string

Optional. Required when the uploaded archive is encrypted.

note

Unlike Sys.CreateBackup and Sys.CreateDefaultConfig, restore reboots the device immediately. Restore is destructive — the live filesystem is wiped before extraction — so there is no useful state to expose between the RPC call and the reboot. The device comes back up running the freshly restored configuration.

Sys.CreateDefaultConfig​

Method makes the current setup the factory default. A password protects all subsequent operations on the default configuration. The first call establishes the password; later calls must present the same password.

note

Gated by provisioning state: only allowed in complete or locked.

Request:

PropertyTypeDescription

password

string

Default-configuration password

Response:

PropertyTypeDescription

restart_required

boolean

Always true on success. The default-configuration archive is written early on the next boot — see note below.

note

The device does not reboot on its own. After this call returns, Sys status reports restart_required: true (and a Sys status-change notification is emitted with the same field). The caller picks the moment to reboot, typically via Shelly.Reboot. Once the reboot completes and the archive has been written, default_config.exists flips to true and a status-change notification is emitted on that field.

Sys.UploadDefaultConfig​

Uploads a default-configuration archive to the device in chunks. Same chunked-upload semantics as Sys.UploadBackup (including offset: 0 starting a fresh session). Call this first, then Sys.ApplyDefaultConfig to commit.

Request:

PropertyTypeDescription

password

string

Default-configuration password (set or verified on every call)

offset

number

Chunk offset

data

string

Base64-encoded data

final

boolean

Marks the final chunk and triggers manifest extraction

Response (final chunk only):

PropertyTypeDescription

manifest

object

Metadata extracted from the uploaded archive's unencrypted manifest file (same fields as the Sys.UploadBackup manifest).

Sys.ApplyDefaultConfig​

Commits the archive uploaded via Sys.UploadDefaultConfig as the device's default configuration. If the manifest reports encrypt: true, a decryption key must be provided; the archive is then decrypted in place. No reboot.

Request:

PropertyTypeDescription

password

string

Default-configuration password

key

string

Optional. Required when the uploaded archive is encrypted.

note

A failed apply (wrong decryption key, flash error) invalidates the default-configuration slot; the archive must be re-uploaded.

Sys.ClearDefaultConfig​

Clears the installed default configuration. The device is left as-is at runtime; the next factory reset will produce a truly blank device rather than restoring the default configuration.

note

Gated by provisioning state: only allowed in complete or locked.

Request:

PropertyTypeDescription

password

string

Default-configuration password

Returns an error if no default configuration is installed or if the password does not match the stored hash.

note

The 30-second hold of the system button performs an equivalent action (clearing the default configuration) and then factory-resets the device. It is always available and cannot be disabled.

Default configuration​

The default configuration is an archive that a vendor can install on the device so it survives factory reset: after any factory reset (via Shelly.FactoryReset or the system-button hold), the device first wipes user state and then re-applies the default configuration automatically. A password-hashed authentication header protects the slot; all operations that create, replace or remove it must present that password.

Two ways to install a default configuration:

  • On-device snapshot. Sys.CreateDefaultConfig takes the current device filesystem and commits it as the default configuration.
  • Off-device upload. Sys.UploadDefaultConfig uploads an archive in chunks. The final chunk returns the archive's manifest, so the caller can inspect encrypt, model, etc. before calling Sys.ApplyDefaultConfig to commit. When the archive is encrypted, Sys.ApplyDefaultConfig decrypts it in place.

Sys.ClearDefaultConfig removes the installed default configuration. Holding the system button for 30 seconds performs an equivalent clear and then factory-resets the device; that path is always available and is the intended escape hatch when the password is lost.

The current state is reported in the status as default_config.exists and in notifications as a status change on the same field: false the moment an upload begins or a clear completes, true once a successful apply commits the configuration. For Sys.CreateDefaultConfig, the flip to true happens after the caller-initiated reboot, when the post-reboot half writes the archive — at the same time the restart_required flag clears.

HTTP Endpoint: /backup.zip​

Downloads the most recently created user backup as a ZIP archive — the same payload streamed by Sys.DownloadBackup, exposed over HTTP for clients that prefer a direct file download.

The endpoint is gated by provisioning state: only available in complete or locked. In pending or confirmed it returns 503 Service Unavailable.

When the device has authentication configured (http.auth_domain or, as a fallback, rpc.auth_domain set via Shelly.SetAuth), the endpoint requires HTTP digest authentication; either set of credentials is accepted.

Returns 404 Not Found when no backup exists yet — i.e. Sys.CreateBackup has not been invoked, or the device has not yet rebooted to produce one.

Example:

Request
curl -OJ http://${SHELLY}/backup.zip

Configuration​

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

Parameters:

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(SensorAddon), sensor(ProSensorAddon), prooutput, LoRa, RS485; null to disable.

sys_btn_toggle

boolean

Enable/disable outputs toggle when the system (reset) button is pressed (shown if applicable).

tls_check_cert_validity_time

boolean

(Since 2.0.0) When true, TLS certificate date/time validation is enforced for outbound connections. Can only be set to false when enhanced_security is false. This is a temporary option for users experiencing certificate validation issues due to time synchronization problems; subject to deprecation in future releases.

enhanced_security

boolean

(Since 2.0.0) Read-only on devices shipped with firmware 2.0.0+ from factory (always true). On devices with factory firmware prior to 2.0.0, can be set to true but can only be reset to false via factory reset. When enabled, enforces additional security measures (see Enhanced Security section below).

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)

file_log

object

Configuration of log files stored on device.

PropertyTypeDescription

enable

boolean

True if enabled, false otherwise

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. Supports host:port format; default port is 123

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:

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).

Secure provisioning​

(since 1.7.5)

Access Point & BLE RPC protection​

  1. Open AP & BLE RPC auto-shutdown: Open AP & BLE RPC are only available for 15 minutes after boot on devices that have never yet acquired IP over Wi-Fi or Ethernet. Once an IP is acquired, AP (unless protected with a password) & BLE RPC are automatically disabled. In case no IP was acquired during the initial setup window, AP (unless protected with a password) & BLE RPC are temporarily shut down - until the device is power-cycled or a factory/network reset occurs.

  2. AP password persistence: Once an AP password has been set, it cannot be changed back to empty (open AP).

Provisioning state​

The device reports its provisioning state in Shelly.GetDeviceInfo via the provision field:

  • pending: initial device provisioning available over a 15 minutes setup window (3 minutes on battery-powered devices)
  • confirmed: device provisioned, unprotected interfaces remain available over a 5 minutes grace window (on battery-powered devices, the original 3-minute setup timer continues instead)
  • complete: grace window expired, AP (unless protected with a password) & BLE RPC are automatically disabled
  • locked: initial setup window expired without going online, AP (unless protected with a password) & BLE RPC are temporarily shut down until device is power-cycled, a factory/network reset occurs, or user button is pressed (latter only applicable to battery-powered devices). While in this state, the device emits a BLE advertisement with the locked flag (bit 5) set in the 0x01 Shelly-Specific Flags block of the Shelly manufacturer-specific data, so it remains discoverable even though BLE RPC is disabled. The device is still connectable while locked, but the only accessible service is GAP.

When provision field changes, the device emits a corresponding notification event: provision_pending, provision_confirmed, provision_complete, provision_locked, for example:

Notify that device provisioning is completed.
{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631266683.84,
      "events": [
         {
            "component": "sys",
            "event": "provision_complete",
            "ts": 1631266683.84
         }
      ]
   }
}

Provisioning object in Sys.GetStatus​

While the device is in the pending or confirmed provisioning state, Sys.GetStatus includes a provisioning object with:

  • stage — the current provisioning stage
  • started_at — when the device entered the stage (Unix timestamp)
  • started_ut — when the device entered the stage (Uptime in seconds)
  • duration — how long the stage lasts, in seconds

A NotifyStatus event is emitted when the object appears or its contents change.

NotifyStatus event with the provisioning object.
{
   "src": "shellyhtg3-dcda0cb79604",
   "dst": "user_1",
   "method": "NotifyStatus",
   "params": {
      "ts": 1778246311.0,
      "sys": {
         "provisioning": {
            "stage": "confirmed",
            "started_at": 1778246311,
            "started_ut": 3,
            "duration": 180
         }
      }
   }
}

Battery Device Provisioning​

(since 2.0.0)

Battery-powered devices have modified provisioning behavior:

  • Setup window: The provisioning window is 3 minutes (tied to setup mode), not 15 minutes
  • No grace window: The 5-minute confirmed grace timer does not apply; the original setup timer continues until completion
  • Button wake recovery: Pressing the device button while in locked state restarts setup mode and returns to pending
  • Periodic wake: When the device wakes from deep sleep via periodic timer (not button press), it remains in locked state with AP and BLE RPC disabled
  • Upgrade path: Devices that already have Wi-Fi configured (station mode enabled, AP disabled) before updating to firmware 2.0.0 boot directly into complete — the provisioning state machine is skipped entirely

Enhanced Security​

(Since firmware 2.0.0)

The enhanced_security flag enforces additional security measures to protect the device. This feature is part of Shelly's compliance with Radio Equipment Directive (RED) cybersecurity requirements.

HTTPS by Default​

info

For additional information regarding custom HTTPS certificates refer to this guide

Devices shipped from factory with firmware 2.0.0+ come with:

  • Pre-installed HTTPS certificates issued by Shelly's internal PKI
  • HTTP to HTTPS redirection enabled by default

Behavior by Factory Firmware Version​

Factory Firmwareenhanced_security DefaultCan Disable?
Prior to 2.0.0falseYes, via factory reset only (after enabling)
2.0.0 or latertrueNo (permanently enabled)
danger

Once enhanced_security is enabled on a device with factory firmware prior to 2.0.0, it can only be disabled by performing a factory reset.

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 when a configuration change or a deferred operation needs a reboot to take effect, false otherwise. Set by config changes that require a restart, and also by Sys.CreateBackup and Sys.CreateDefaultConfig. Cleared by reboot.

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.

last_sync_ts

number

Last time the system synced time from NTP server (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

btrelay_rev

number

BLE cloud relay configuration revision number, present on devices supporting BLE cloud relay functionality

bthc_rev

number

BTHomeControl configuration revision number, present when device supports control with BLU devices

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

nsteps

number

Denotes a special update. Present only for certain devices and versions. See note below.

stable

object

Shown only if stable update is available

PropertyTypeDescription

version

string

Version of the new firmware

nsteps

number

Denotes a special update. Present only for certain devices and versions. See note below.

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

utc_offset

number

Time offset (in seconds). This is the difference between the device local time and UTC

backup

object

Backup status

PropertyTypeDescription

created

number

The Unix timestamp (in UTC) when the backup was created

error

string

The presence of this field indicates that the last backup attempt failed, and it provides a brief explanation of the reason

href

string

Download location

default_config

object

State of the installed default configuration. A NotifyStatus event is emitted whenever exists flips.

PropertyTypeDescription

exists

boolean

true when a default configuration is committed and will be re-applied on the next factory reset; false otherwise

provisioning

object

Provisioning timer state. Present only while the device is in an active provisioning state (pending or confirmed). A NotifyStatus event is emitted when the object appears or its contents change.

PropertyTypeDescription

stage

string

Current provisioning stage: pending or confirmed

started_at

number

Unix timestamp (in UTC) when the device entered the current provisioning stage

started_ut

number

Uptime in seconds when the device entered the current provisioning stage

duration

number

Duration of the current provisioning stage in seconds

discovery

object

(since 2.2.0) Network-discovery state. Present only while a Sys.StartDiscovery scan is running; absent otherwise. A NotifyStatus event is emitted when the object appears and when it is removed.

PropertyTypeDescription

started_at

number

Unix timestamp (in UTC) when the scan started

duration

number

Scan duration in seconds

info

The last_sync_ts property is stored in energy-independent memory for devices with a real-time clock(e.g. ShellyPro3EM).

info

The nsteps property in available_updates is meant to aid in designing user interaction for a special case of updates that may require a two step pass, which although rarely may be necessary as for example updates of certain devices after release 2.0.0 which will perform server assisted repartitioning. For regular updates the property will not be present. For a two step update, based on information sent by the server when the update is determined to require two steps the nsteps property will be shown in Sys.Status with a value of 1 and also will be included in a status change. Due to the specifics of OTA implementation in firmware for this kind of updates the same update may not require a second pass in which case nsteps won't be shown. When the second pass starts, which will happen automatically after the delay for committing update, the server will send nsteps with a value of 0, denoting last step. After completion available updates will change and will not include the entry for the version firmware just updated to, thus not showing nsteps.

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
  • provision_pending (since 1.7.5)
  • provision_confirmed (since 1.7.5)
  • provision_complete (since 1.7.5)
  • provision_locked (since 1.7.5)
  • discovery_results (since 2.2.0)
  • discovery_done (since 2.2.0)
note

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

The discovery_results and discovery_done events are emitted during a Sys.StartDiscovery scan. They are delivered to local channels only (WebSocket, MQTT, scripts) and are not forwarded to the cloud.

discovery_results carries a batch of results collected over a short window (results stream while the scan is active, they are not all delivered at the end):

PropertyTypeDescription

results

array

Discovery results found in this batch. Each entry:

PropertyTypeDescription

name

string

The DNS-SD service instance name: the device's friendly name if one is set, otherwise its device id (e.g. shellyplusplugs-b0b21c19e41c).

host

string

The advertised .local hostname.

iface

string

The interface on the scanning device that received this record, e.g. WiFi STA or ETH. It does not describe the discovered device's own interface.

ipv4

array

IPv4 addresses of the device, as received in the mDNS response. Omitted when none.

ipv6

array

IPv6 addresses of the device. Omitted when none.

attrs

object

The device's TXT record fields verbatim, currently app, gen and ver. Kept as a flexible object so future firmware can add fields without breaking clients.

note

A physical device advertises more than one DNS-SD record (one under its device id, one under its friendly name), so the same device may appear as more than one entry across a scan.

caution

iface reports which of the scanning device's own network interfaces the record arrived on. It says nothing about how the discovered device is connected — a result with iface: "ETH" may itself be a device connected over WiFi; the value only means the scanning device heard it on its Ethernet interface.

On a device with a single active interface every result carries the same iface. The field only becomes meaningful on multi-homed scanning devices (e.g. Pro models): there the same remote device can legitimately be heard on both interfaces and reported twice — once with iface: "WiFi STA" and once with iface: "ETH" — with the address as seen from each.

discovery_done is emitted exactly once when the scan ends, whether by duration expiry or by an explicit Sys.StopDiscovery:

PropertyTypeDescription

result_count

number

Number of results reported during the scan.

Examples​

Sys.SetConfig example​

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

Response

{
  "restart_required": false
}

Sys.SetConfig - Enable Enhanced Security​

note

This example applies only to devices with factory firmware prior to 2.0.0. Once enabled, enhanced_security can only be disabled via factory reset.

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"enhanced_security":true}}

Response

{
  "restart_required": true
}

Sys.SetConfig - Disable TLS Certificate Time Validation​

Temporary Option

The tls_check_cert_validity_time setting is provided as a temporary workaround for users experiencing TLS certificate validation failures due to time synchronization issues. This option is subject to deprecation in future firmware releases. It is recommended to resolve time synchronization issues rather than disabling this security check.

note

This setting can only be changed to false when enhanced_security is false.

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"tls_check_cert_validity_time":false}}

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,
    "tls_check_cert_validity_time": true,
    "enhanced_security": 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,
  "last_sync_ts": 1654694307,
  "uptime": 120,
  "ram_size": 253464,
  "ram_free": 146012,
  "fs_size": 458752,
  "fs_free": 212992,
  "cfg_rev": 10,
  "kvs_rev": 277,
  "schedule_rev": 0,
  "webhook_rev": 0,
  "btrelay_rev": 0,
  "available_updates": {
    "stable": {
      "version": "0.10.2"
    }
  },
  "backup": {
    "href": "/backup.zip",
    "created": 1758267551
  },
  "default_config": {
    "exists": false
  },
  "provisioning": {
    "stage": "pending",
    "started_at": 1654694292,
    "started_ut": 5,
    "duration": 900
  }
}

Sys.SetTime example​

http://192.168.33.1/rpc/Sys.SetTime?unixtime=1737104483.546

Response

null

Sys.StartDiscovery example​

http://192.168.33.1/rpc/Sys.StartDiscovery?duration=10

Response

null

Sys.StopDiscovery example​

http://192.168.33.1/rpc/Sys.StopDiscovery

Response

null

Sys.CreateBackup example​

http://192.168.33.1/rpc/Sys.CreateBackup?encrypt=true

Response

{
  "key": "a3b7k-m2xQp-L9t4n-d6Wfv-Zs1Ay",
  "restart_required": true
}

Sys.DownloadBackup example​

http://192.168.33.1/rpc/Sys.DownloadBackup?offset=0&len=4

Response

{
  "data": "UEsDBA==",
  "left": 1065
}

Sys.UploadBackup example​

Final chunk (non-final chunks take the same shape but return null):

http://192.168.33.1/rpc/Sys.UploadBackup?offset=6144&data="UEsFBgAAAAAAAA=="&final=true

Response

{
  "manifest": {
    "created_at": 1758267551,
    "fw_ver": "1.9.99",
    "model": "SNSN-10138",
    "app_name": "Pro4PM",
    "device_name": "Living Room Lights",
    "encrypt": true
  }
}

Sys.RestoreBackup example​

http://192.168.33.1/rpc/Sys.RestoreBackup?key="a3b7k-m2xQp-L9t4n-d6Wfv-Zs1Ay"

Response

null

Sys.CreateDefaultConfig example​

http://192.168.33.1/rpc/Sys.CreateDefaultConfig?password="vendor secret"

Response

{
  "restart_required": true
}

Sys.UploadDefaultConfig example​

Final chunk (non-final chunks take the same shape but return null):

http://192.168.33.1/rpc/Sys.UploadDefaultConfig?password="vendor secret"&offset=6144&data="UEsFBgAAAAAAAA=="&final=true

Response

{
  "manifest": {
    "created_at": 1758267551,
    "fw_ver": "1.9.99",
    "model": "SNSN-10138",
    "app_name": "Pro4PM",
    "device_name": "",
    "encrypt": false
  }
}

Sys.ApplyDefaultConfig example​

http://192.168.33.1/rpc/Sys.ApplyDefaultConfig?password="vendor secret"

Response

null

Sys.ClearDefaultConfig example​

http://192.168.33.1/rpc/Sys.ClearDefaultConfig?password="vendor secret"

Response

null

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

Example 9:

Notify a batch of discovered devices.
{
   "src": "shellyi4g3-8cbfea976af8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1774350200.41,
      "events": [
         {
            "component": "sys",
            "event": "discovery_results",
            "results": [
               {
                  "name": "Living Room Light",
                  "host": "shellycolorblbg3-48f6eeaaade0.local",
                  "iface": "WiFi STA",
                  "ipv4": ["192.168.1.101"],
                  "ipv6": ["fe80::a92:72ff:fe42:21ec"],
                  "attrs": {
                     "app": "RGBCCTBulbG3",
                     "gen": 3,
                     "ver": "2.0.0"
                  }
               }
            ],
            "ts": 1774350200.41
         }
      ]
   }
}
  • Discovery done

Example 10:

Notify that a discovery scan has ended.
{
   "src": "shellyi4g3-8cbfea976af8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1774350205.41,
      "events": [
         {
            "component": "sys",
            "event": "discovery_done",
            "result_count": 14,
            "ts": 1774350205.41
         }
      ]
   }
}

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,
  "last_sync_ts": 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,
  "btrelay_rev": 0,
  "available_updates": {
    "beta": {
      "version": "0.13.0-beta1"
    },
    "stable": {
      "version": "0.12.0"
    }
  }
}