Skip to main content

RPC Protocol

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

Shelly-NG is monitored and controlled by JSON-RPC 2.0 protocol. This protocol is supported by Mongoose 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:

  • jsonrpc: string, 2.0. The version of jsonrpc used. May be omitted
  • id: number/string, identifier of this request, will be used to match the response frame. Required
  • src: string, name of the source of the request. Required
  • method: string, name of the procedure to be called. Required
  • params: JSON 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:

  • id: number/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/error: JSON object, result is the result of the invoked procedure and is returned if the request is successful. error contains description of the error occurred and is returned if the request is unsuccessful. These two are mutually exclusive. More about the error frames used in Shelly-NG 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:

  • src: string, name of the source of the response. Required
  • dst: string, name of the destination. Required
  • method: string, the method invoked. Required
  • params: JSON 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
}
]
}
}