Skip to main content
Version: 1.0

RPC Protocol

RPCs (Remote Procedure Calls) are used to send commands to devices and receive notifications and replies from these devices.

Gen2+ is monitored and controlled by JSON-RPC 2.0 protocol. This protocol is supported by Shelly OS and detailed documentation about it can be found here. The protocol is symmetric: both peers can call methods and notify.

According to the Shelly conventions each procedure is a method that has a name (e.g., Switch.GetConfig), takes JSON object as arguments (e.g., {"id":1}) and returns JSON object as a result (e.g., {"restart_required":false}). Methods are kept in namespaces as in:

  • Shelly - system management, configuration and status
    • Shelly.FactoryReset
    • Shelly.ResetWiFiConfig
    • Shelly.ListTimezones, etc.
  • Switch - A component for a discrete power output; usually a relay
    • Switch.Set
    • Switch.GetConfig, etc.

There are three types of frames in the communication between a user and a device:

  • request frame
  • response frame
  • notification frame

Request Frame

The request frame is a JSON object, containing the following attributes:

PropertyTypeDescription

jsonrpc

string

2.0. The version of jsonrpc used. May be omitted

id

number or string

Identifier of this request, will be used to match the response frame. Required

src

string

Name of the source of the request (you can choose whatever string you like to identify you as the source of the request).Required

method

string

Name of the procedure to be called. Required

params

object

Parameters that the method takes (if any) Optional

Example 1:

Request frame invoking Switch.GetConfig method:
{
"jsonrpc":"2.0",
"id": 1,
"src":"user_1",
"method":"Switch.GetConfig",
"params": {
"id":2
}
}

Example 2:

Request frame invoking Switch.Set method:
{
"id": 2,
"src":"user_1",
"method":"Switch.Set",
"params": {
"id":1,
"on":true
}
}

Response Frame

The response frame is a JSON object, containing the following attributes:

PropertyTypeDescription

id

number or string

Id of the communication

src

string

Name of the source of the response

dst

string

Name of the destination (the source of the request)

result

object

The result of the invoked procedure and is returned if the request is successful. result and error re mutually exclusive. More about the error frames used in Gen2+ can be found here

error

object

Contains description of the error occurred and is returned if the request is unsuccessful.result and error re mutually exclusive. More about the error frames used in Gen2+ can be found here

Example 1:

Response frame returning result object after successful request:
{
"id": 2,
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"result": {
"was_on": false
}
}

Example 2:

Response frame returning error object after unsuccessful request:
{
"id": 1,
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"error": {
"code": -105,
"message": "Bad id=12"
}
}

Notification Frame

The notification frame is a JSON object, similar to a request but not expecting a response. It contains the following attributes:

PropertyTypeDescription

src

string

Name of the source of the response. Required

dst

string

Name of the destination. Required

method

string

The method invoked. Required

params

object

The parameters of the notification. Required

Example 1:

Notification frame containing information about status change:
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1623243781.01,
"switch:3": {
"id": 3,
"aenergy": {
"by_minute": [
0,
0.015,
0
],
"minute_ts": 1623243779,
"total": 0.037
}
}
}
}

Example 2:

Notification frame containing information about event occurred:
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266595.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "single_push",
"ts": 1631266595.44
}
]
}
}