Skip to main content

System

The system component is called Sys. It handles the system services of a device.

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:

  • 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 for hours)
  • unixtime: number, unix timestamp (in UTC)
  • 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
  • available_updates: JSON 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
    • beta: JSON object, shown only if beta update is available
      • version: string, version of the new firmware
    • stable: JSON object, shown only if stable update is available
      • version: string, version of the new firmware
Example status object
{
"mac": "F008D1D8B8B8",
"restart_required": false,
"time": "12:25",
"unixtime": 1626945905,
"uptime": 15869,
"ram_size": 250112,
"ram_free": 110736,
"fs_size": 474641,
"fs_free": 336340,
"available_updates": {}
}

Configuration#

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

Properties:

  • device: JSON object, information about the device

    • name: string, name of the device
    • mac: string, mac address
    • fw_id: string, id of the firmware
  • location: JSON object, information about the current location of the device

    • 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: JSON object, configuration of the device's debug logs. See more about the debug logs and how to read them here

    • mqtt: JSON object, configuration of logs streamed over MQTT
      • enable: boolean, true if enabled, false otherwise
    • websocket: JSON object, configuration of logs streamed over websocket. Attention: Access to log streams over websocket is not restricted, even when authentication is enabled!
      • enable: boolean, true if enabled, false otherwise
    • udp: JSON object, configuration of logs streamed over UDP
      • addr: string (in the format <host>:<port>) or null, address that the device log is streamed to (null to disable logs)
  • ui_data: JSON object, user interface data

  • rpc_udp: JSON object, configuration for the RPC over UDP

    • dst_addr: string (in the format <host>:<port>) or null, is address where notification for status/events will appear. E.g. if switch is pressed notification will be received at this address and port. null disables sending. Restart is required for changes to apply.

    • listen_port: port number for inbound UDP RPC channel, null disables. Restart is required for changes to apply.

      Example: Set configuration
      mos --port ${PORT} call Sys.SetConfig '{"config":{"rpc_udp":{"dst_addr":"192.168.1.2:4567","listen_port":1234}}}'
      Example: Get status over udp
      mos call --port udp://deviceip:1234/ Shelly.GetStatus

      Response from method Shelly.GetStatus will be received on calling computer/device on port 1234.

      If switch is pressed or something happens that generates event, status will be received at udp://192.168.1.2:4567

  • sntp: JSON object, configuration for the sntp server

    • 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

Example configuration object
{
"device": {
"name": null
"mac": "F008D1D8B8B8",
"fw_id": "20210720-153353/0.6.7-gc36674b"
},
"location": {
"tz": "Europe/Sofia",
"lat": 42.67236,
"lon": 23.38738
},
"debug": {
"mqtt": {
"enable": false
},
"websocket": {
"enable": false
},
"udp": {
"addr": null
}
},
"ui_data": {},
"rpc_udp": {
"dst_addr": null,
"listen_port": null
},
"cfg_rev": 19,
"sntp": {
"server": "time.google.com"
}
}

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:

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