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:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
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
         }
      ]
   }
}