Skip to main content
Version: 1.0

Shelly

This service is common for all Gen2+ devices. It handles device management. Here are listed all methods supported by the Shelly namespace.

Shelly.GetStatus​

This method returns the status of all the components of the device.

Request​

This method takes no parameters.

Response​

Attributes in the result are the status objects of all components in the device.

Shelly.GetConfig​

This method returns the configuration of all the components of the device.

Request​

This method takes no parameters.

Response​

Attributes in the result are the configuration objects of all components in the device.

Shelly.ListMethods​

This method lists all available RPC methods. It takes into account both ACL and authentication restrictions and only lists the methods allowed for the particular user/channel that's making the request.

Request​

This method takes no parameters.

Response​

Attributes in the result:

PropertyTypeDescription

methods

array of type string

Names of the methods allowed

Shelly.GetDeviceInfo​

This method returns information about the device.

Request​

Parameters:

PropertyTypeDescription

ident

boolean

Flag specifying if extra identifying information should be displayed. Optional

Response​

Attributes in the result:

PropertyTypeDescription

id

string

Id of the device

mac

string

Mac address of the device

model

string

Model of the device

gen

number

Generation of the device

fw_id

string

Id of the firmware of the device

ver

string

Version of the firmware of the device

app

string

Application name

profile

string

Name of the device profile (only applicable for multi-profile devices)

auth_en

boolean

true if authentication is enabled, false otherwise

auth_domain

string or null

Name of the domain (null if authentication is not enabled)

discoverable

boolean

Present only when false. If true, device is shown in 'Discovered devices'. If false, the device is hidden.

key

string

Cloud key of the device (see note below), present only when the ident parameter is set to true

batch

string

Batch used to provision the device, present only when the ident parameter is set to true

fw_sbits

string

Shelly internal flags, present only when the ident parameter is set to true

note

The cloud key of the device is a JSON Web Token (JWT), generated by the Shelly provisioning server and obtained by the device during provisioning used to identify device to the Shelly cloud. More information about JSON Web Token as well as an online tool to verify the integrity of the cloud key be found on this site. The public key to verify the signature of the cloud key JWT is:

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEhwiPS5G27EGpuW3uaRQYSlcCxdxMm9E0
0xI6zeqfou0cI7Cn5+oaf7SsH2E/8nKQN4uAkRIlX2PG/yoggEXR+iwOzA/ZW6km
Pcy25FAkstbYuzYWJRme27O8OhURBc7W
-----END PUBLIC KEY-----

Shelly.ListProfiles​

The term profile abstracts high-level device functionality. Some devices can operate in different exclusive modes or profiles, for example, Shelly Plus2PM and Shelly Pro2PM can operate in a switch or cover profile. Shelly.ListProfiles lists the names of available profiles and the type/count of functional components exposed for each profile. Shelly.ListProfiles is only available on multi-profile devices.

Request​

This method takes no parameters.

Shelly.SetProfile​

This method sets the device profile. Shelly.SetProfile is only available on multi-profile devices.

danger

Changing the device profile will delete all webhooks and schedules on the device.

Request​

Parameters:

PropertyTypeDescription

name

string

Name of the device profile

Response​

  • When the newly selected profile is different than the active profile:
    • Shelly.SetProfile returns profile_was, followed by an automatic reboot
  • When the newly selected profile is the same as the active profile:
    • Shelly.SetProfile returns profile_was

Shelly.ListTimezones​

This method returns list of timezones, it supports paging.

Request​

Parameters:

PropertyTypeDescription

offset

number

Index of the list from which to start generating the result Optional

Response​

Attributes in the result:

PropertyTypeDescription

timezones

array of type string

List of timezones

offset

number

Index of the first entry in the result

total

number

Total number of available timezones

Shelly.DetectLocation​

This method detects and returns the location of the device.

Request​

This method takes no parameters.

Response​

Attributes in the result:

PropertyTypeDescription

tz

string or null

Timezone of the detected location (null if not available)

lat

number or null

Latitude of the detected location in degrees (null if not available)

lon

number or null

Longitude of the detected location in degrees (null if not available)

Shelly.CheckForUpdate​

This method checks for new firmware version for the device and returns information about it. If no update is available returns empty JSON object as result.

Request​

This method takes no parameters.

Response​

Attributes in the result (only the ones available are shown):

PropertyTypeDescription

stable

object

Indicates new stable version of the firmware.

PropertyTypeDescription

version

string

The new version

build_id

string

Id of the new build

beta

object

Indicates new beta version of the firmware.

PropertyTypeDescription

version

string

The new version

build_id

string

Id of the new build

Shelly.Update​

This method updates the firmware version of the device.

Request​

Parameters:

PropertyTypeDescription

stage

string

The type of the new version - either stable or beta. By default updates to stable version. Optional

url

string

Url address of the update. Optional

caution

Shelly.Update takes either stage or url.

Shelly.FactoryReset​

This method resets the configuration to its default state.

Request​

This method takes no parameters.

Shelly.ResetWiFiConfig​

This method resets the WiFi configuration of the device.

Request​

This method takes no parameters.

Response​

The result from this method is null.

Shelly.Reboot​

This method reboots the device.

Request​

Parameters:

PropertyTypeDescription

delay_ms

number

Delay until reboot in milliseconds. Any values are valid but the minimum is capped at 500 ms. Default value: 1000 ms. Optional

Shelly.SetAuth​

This method sets authentication details (password) for the device. More detailed description of the authentication mechanism can be found here.

Request​

Parameters:

PropertyTypeDescription

user

string

Must be set to admin. Only one user is supported. Required

realm

string

Must be the id of the device. Only one realm is supported. Required

ha1

string or null

"user:realm:password" encoded in SHA256 (null to disable authentication). Required

Shelly.PutUserCA​

This method allows uploading of a custom certificate authority (CA) PEM bundle. Because the file can be larger than what can fit in a single RPC frame, the method allows uploading in chunks (for example line by line). More about the user CA support provided by Shelly can be found here.

Request​

Parameters:

PropertyTypeDescription

data

string or null

Contents of the PEM file (null if you want to delete the existing data). Required

append

boolean

true if more data will be appended afterwards, default false.

Response​

The result from this method is the lenght of the certificate in bytes.

Shelly.PutTLSClientCert​

This method allows uploading of a custom client certificate client.crt. Because the file can be larger than what can fit in a single RPC frame, the method allows uploading in chunks (for example line by line). More about the user certificate support provided by Shelly can be found here.

Request​

Parameters:

PropertyTypeDescription

data

string or null

Contents of the client.crt file (null if you want to delete the existing data). Required

append

boolean

true if more data will be appended afterwards, default false.

Response​

The result from this method is the lenght of the certificate in bytes.

Shelly.PutTLSClientKey​

This method allows uploading of a custom client key client.key. Because the file can be larger than what can fit in a single RPC frame, the method allows uploading in chunks (for example line by line). More about the user certificate support provided by Shelly can be found here.

Request​

Parameters:

PropertyTypeDescription

data

string or null

Contents of the client.key file (null if you want to delete the existing data). Required

append

boolean

true if more data will be appended afterwards, default false.

Response​

The result from this method is the length of the certificate in bytes.

Shelly.GetComponents​

This method returns a list with device's components, it supports paging, filter for dynamic components (for example virtual components) and allows the user to get only the needed information from the component.

Request​

Parameters:

PropertyTypeDescription

offset

number

Index of the component from which to start generating the result Optional

include

array of strings

"status" will include the component's status, "config" - the config. The keys are always included. Combination of both (["config", "status"]) to get the full config and status of each component. Optional

dynamic_only

boolean

true to include only dynamic components, default false. Optional

Response​

PropertyTypeDescription

components

array of objects

PropertyTypeDescription

key

string

Component's key (in format <type>:<cid>, for example boolean:200)

status

object

Component's status, will be omitted if "status" is not specified in the include property.

config

object

Component's config, will be omitted if "config" is not specified in the include property.

cfg_rev

number

Sys's configuration revision

offset

number

Index of the first component in the result

total

number

Total number of components with all filters applied

HTTP Endpoint: /shelly​

This resource is equivalent to invoking Shelly.GetDeviceInfo. The aim of this request is to identify a device. As the generation (gen) of the device determines the channels and methods/endpoints available, this information is useful for further integrations of Shelly devices in other systems.

Example:

Request
curl http://${SHELLY}/shelly
Response
{
  "id": "shellypro4pm-f008d1d8b8b8",
  "mac": "F008D1D8B8B8",
  "model": "SPSW-004PE16EU",
  "gen": 2,
  "fw_id": "20210720-153353/0.6.7-gc36674b",
  "ver": "0.6.7",
  "app": "FourPro",
  "auth_en": true,
  "auth_domain": "shellypro4pm-f008d1d8b8b8"
}

HTTP Endpoint: /ota​

danger

Flashing devices with custom firmware will irreversably void the device warranty.

Shelly devices contains a suite of safety features. Every firmware build goes through extensive testing to ensure all safety features and protection mechanisms work reliably. We cannot provide the same guarantee for unofficial firmware images.

This endpoints allows a shelly device to be flashed with a compatible Shelly OS firmware. It expects a url parameter and will attempt to download the firmware image from there.

Example:

Request
curl http://${SHELLY}/ota?url=http://third-party-firmware.site/path/to/image.zip

Examples​

Shelly.GetStatus example​

http://192.168.33.1/rpc/Shelly.GetStatus

Response

{
  "ble": {},
  "cloud": {
    "connected": false
  },
  "eth": {
    "ip": "10.33.55.170"
  },
  "input:0": {
    "id": 0,
    "state": false
  },
  "input:1": {
    "id": 1,
    "state": false
  },
  "input:2": {
    "id": 2,
    "state": false
  },
  "input:3": {
    "id": 3,
    "state": false
  },
  "mqtt": {
    "connected": false
  },
  "switch:0": {
    "id": 0,
    "source": "timer",
    "output": true,
    "timer_started_at": 1626935739.79,
    "timer_duration": 60,
    "apower": 8.9,
    "voltage": 237.5,
    "aenergy": {
      "total": 6.532,
      "by_minute": [
        45.199,
        47.141,
        88.397
      ],
      "minute_ts": 1626935779
    },
    "temperature": {
      "tC": 23.5,
      "tF": 74.4
    }
  },
  "switch:1": {
    "id": 1,
    "source": "init",
    "output": false,
    "apower": 0,
    "voltage": 237.5,
    "aenergy": {
      "total": 0,
      "by_minute": [
        0,
        0,
        0
      ],
      "minute_ts": 1626935779
    },
    "temperature": {
      "tC": 23.5,
      "tF": 74.4
    }
  },
  "switch:2": {
    "id": 2,
    "source": "timer",
    "output": false,
    "timer_started_at": 1626935591.8,
    "timer_duration": 345,
    "apower": 0,
    "voltage": 237.5,
    "aenergy": {
      "total": 0.068,
      "by_minute": [
        0,
        0,
        0
      ],
      "minute_ts": 1626935779
    },
    "temperature": {
      "tC": 23.5,
      "tF": 74.4
    }
  },
  "switch:3": {
    "id": 3,
    "source": "init",
    "output": false,
    "apower": 0,
    "voltage": 237.5,
    "aenergy": {
      "total": 0,
      "by_minute": [
        0,
        0,
        0
      ],
      "minute_ts": 1626935779
    },
    "temperature": {
      "tC": 23.5,
      "tF": 74.4
    }
  },
  "sys": {
    "mac": "A8032ABE54DC",
    "restart_required": false,
    "time": "16:06",
    "unixtime": 1650035219,
    "uptime": 11081,
    "ram_size": 254744,
    "ram_free": 151560,
    "fs_size": 458752,
    "fs_free": 180224,
    "cfg_rev": 26,
    "kvs_rev": 2725,
    "schedule_rev": 0,
    "webhook_rev": 0,
    "available_updates": {
      "stable": {
        "version": "0.10.1"
      }
    }
  },
  "wifi": {
    "sta_ip": null,
    "status": "disconnected",
    "ssid": null,
    "rssi": 0
  },
  "ws": {
    "connected": true
  }
}

Shelly.GetConfig example​

http://192.168.33.1/rpc/Shelly.GetConfig

Response

{
  "ble": {
    "enable": true
  },
  "cloud": {
    "enable": false,
    "server": "iot.shelly.cloud:6012/jrpc"
  },
  "eth": {
    "enable": true,
    "ipv4mode": "dhcp",
    "ip": null,
    "netmask": null,
    "gw": null,
    "nameserver": null
  },
  "input:0": {
    "id": 0,
    "name": null,
    "type": "switch",
    "invert": false
  },
  "input:1": {
    "id": 1,
    "name": null,
    "type": "switch",
    "invert": false
  },
  "input:2": {
    "id": 2,
    "name": null,
    "type": "switch",
    "invert": false
  },
  "input:3": {
    "id": 3,
    "name": null,
    "type": "switch",
    "invert": false
  },
  "mqtt": {
    "enable": false,
    "server": null,
    "user": null,
    "pass": null
  },
  "switch:0": {
    "id": 0,
    "name": null,
    "in_mode": "follow",
    "initial_state": "match_input",
    "auto_on": true,
    "auto_on_delay": 60,
    "auto_off": true,
    "auto_off_delay": 60,
    "power_limit": 3500,
    "voltage_limit": 280,
    "current_limit": 16
  },
  "switch:1": {
    "id": 1,
    "name": null,
    "in_mode": "follow",
    "initial_state": "match_input",
    "auto_on": false,
    "auto_on_delay": 60,
    "auto_off": false,
    "auto_off_delay": 60,
    "power_limit": 3500,
    "voltage_limit": 280,
    "current_limit": 16
  },
  "switch:2": {
    "id": 2,
    "name": null,
    "in_mode": "follow",
    "initial_state": "match_input",
    "auto_on": true,
    "auto_on_delay": 345,
    "auto_off": true,
    "auto_off_delay": 2,
    "power_limit": 3500,
    "voltage_limit": 280,
    "current_limit": 16
  },
  "switch:3": {
    "id": 3,
    "name": null,
    "in_mode": "follow",
    "initial_state": "match_input",
    "auto_on": false,
    "auto_on_delay": 60,
    "auto_off": false,
    "auto_off_delay": 60,
    "power_limit": 3500,
    "voltage_limit": 280,
    "current_limit": 16
  },
  "sys": {
    "device": {
      "name": null,
      "mac": "F008D1D8B8B8",
      "fw_id": "20210720-153353/0.6.7-gc36674b"
    },
    "location": {
      "tz": "Europe/Sofia",
      "lat": 42.67236,
      "lon": 23.38738
    },
    "ui_data": {},
    "sntp": {
      "server": "time.google.com"
    }
  },
  "wifi": {
    "ap": {
      "ssid": "ShellyPro4PM-F008D1D8B8B8",
      "is_open": true,
      "enable": true
    },
    "sta": {
      "ssid": null,
      "is_open": true,
      "enable": false,
      "ipv4mode": "dhcp",
      "ip": null,
      "netmask": null,
      "gw": null,
      "nameserver": null
    },
    "sta1": {
      "ssid": null,
      "is_open": true,
      "enable": false,
      "ipv4mode": "dhcp",
      "ip": null,
      "netmask": null,
      "gw": null,
      "nameserver": null
    },
    "ws": {
      "enable": false,
      "server": null,
      "ssl_ca": "ca.pem"
    },
    "roam": {
      "rssi_thr": -80,
      "interval": 60
    }
  }
}

Shelly.ListMethods example​

http://192.168.33.1/rpc/Shelly.ListMethods

Response

{
  "methods": [
    "Switch.SetConfig",
    "Switch.GetConfig",
    "Switch.GetStatus",
    "Switch.Toggle",
    "Switch.Set",
    "Schedule.List",
    "Schedule.DeleteAll",
    "Schedule.Delete",
    "Schedule.Update",
    "Schedule.Create",
    "Input.SetConfig",
    "Input.GetConfig",
    "Input.GetStatus",
    "Webhook.ListSupported",
    "Webhook.List",
    "Webhook.DeleteAll",
    "Webhook.Delete",
    "Webhook.Update",
    "Webhook.Create",
    "Mqtt.SetConfig",
    "Mqtt.GetConfig",
    "Mqtt.GetStatus",
    "Cloud.SetConfig",
    "Cloud.GetConfig",
    "Cloud.GetStatus",
    "BLE.SetConfig",
    "BLE.GetConfig",
    "BLE.GetStatus",
    "Eth.SetConfig",
    "Eth.GetConfig",
    "Eth.GetStatus",
    "Wifi.Scan",
    "Wifi.SetConfig",
    "Wifi.GetConfig",
    "Wifi.GetStatus",
    "Sys.SetConfig",
    "Sys.GetConfig",
    "Sys.GetStatus",
    "HTTP.GET",
    "Shelly.ListMethods",
    "Shelly.PutTLSClientKey",
    "Shelly.PutTLSClientCert",
    "Shelly.PutUserCA",
    "Shelly.Reboot",
    "Shelly.SetAuth",
    "Shelly.Update",
    "Shelly.CheckForUpdate",
    "Shelly.DetectLocation",
    "Shelly.ListTimezones",
    "Shelly.GetStatus",
    "Shelly.FactoryReset",
    "Shelly.ResetWiFiConfig",
    "Shelly.GetConfig",
    "Shelly.GetDeviceInfo",
    "Shelly.ListProfiles",
    "Shelly.SetProfile"
  ]
}

Shelly.GetDeviceInfo example​

http://192.168.33.1/rpc/Shelly.GetDeviceInfo

Response

{
  "id": "shellypro4pm-f008d1d8b8b8",
  "mac": "F008D1D8B8B8",
  "model": "SPSW-004PE16EU",
  "gen": 2,
  "fw_id": "20210720-153353/0.6.7-gc36674b",
  "ver": "0.6.7",
  "app": "FourPro",
  "auth_en": true,
  "auth_domain": "shellypro4pm-f008d1d8b8b8",
  "discoverable": false
}

Shelly.ListProfiles example​

http://192.168.33.1/rpc/Shelly.ListProfiles

Response

{
  "profiles": {
    "cover": {
      "components": [
        {
          "type": "input",
          "count": 2
        },
        {
          "type": "cover",
          "count": 1
        }
      ]
    },
    "switch": {
      "components": [
        {
          "type": "input",
          "count": 2
        },
        {
          "type": "switch",
          "count": 2
        }
      ]
    }
  }
}

Shelly.SetProfile example​

http://192.168.33.1/rpc/Shelly.SetProfile?name="cover"

Response

{
  "profile_was": "switch"
}

Shelly.ListTimezones example​

http://192.168.33.1/rpc/Shelly.ListTimezones

Response

{
  "timezones": [
    "Africa/Abidjan",
    "Africa/Accra",
    "Africa/Addis_Ababa",
    "Africa/Algiers",
    "Africa/Asmara",
    "Africa/Asmera"
  ],
  "offset": 0,
  "total": 597
}

Shelly.DetectLocation example​

http://192.168.33.1/rpc/Shelly.DetectLocation

Response

{
  "tz": "Europe/Sofia",
  "lat": 42.67236,
  "lon": 23.38738
}

Shelly.CheckForUpdate example​

http://192.168.33.1/rpc/Shelly.CheckForUpdate

Response

{
  "beta": {
    "version": "0.5.1",
    "build_id": "20210610-122509/g4bbec18"
  }
}

Shelly.Update example​

http://192.168.33.1/rpc/Shelly.Update?stage="beta"

Response

null

Shelly.FactoryReset example​

http://192.168.33.1/rpc/Shelly.FactoryReset

Response

null

Shelly.ResetWiFiConfig example​

http://192.168.33.1/rpc/Shelly.ResetWiFiConfig

Response

null

Shelly.Reboot example​

http://192.168.33.1/rpc/Shelly.Reboot

Response

null

Shelly.SetAuth example​

http://192.168.33.1/rpc/Shelly.SetAuth?user="admin"&realm="shellypro4pm-f008d1d8b8b8"&ha1="7f22c63135ab3c86d165d812fbab2ac30950ee53d86451e508c699e5de9c39ac"

Response

null

Shelly.PutTLSClientKey example​

http://192.168.33.1/rpc/Shelly.PutTLSClientKey?data="MIIB4TCCAYegAwIBAgIRKjikHJYKBN5CsiilC+g0mAIwCgYIKoZIzj0EAwIwUDEk"&append=true

Response

{
  "len": 64
}

Shelly.PutTLSClientCert example​

http://192.168.33.1/rpc/Shelly.PutTLSClientCert?data="MIIB4TCCAYegAwIBAgIRKjikHJYKBN5CsiilC+g0mAIwCgYIKoZIzj0EAwIwUDEk"&append=true

Response

{
  "len": 64
}

Shelly.PutUserCA example​

http://192.168.33.1/rpc/Shelly.PutUserCA?data="MIIB4TCCAYegAwIBAgIRKjikHJYKBN5CsiilC+g0mAIwCgYIKoZIzj0EAwIwUDEk"&append=true

Response

{
  "len": 64
}

Shelly.GetComponents example​

http://192.168.33.1/rpc/Shelly.GetComponents?include=["config"]

Response

{
  "components": [
    {
      "key": "ble",
      "config": {
        "enable": true,
        "rpc": {
          "enable": true
        },
        "observer": {
          "enable": false
        }
      }
    },
    {
      "key": "boolean:201",
      "config": {
        "id": 201,
        "name": "",
        "meta": null,
        "persisted": false,
        "default_value": true
      }
    }
  ]
}