Skip to main content
Version: 1.0

RPC Channels

Shellies support communication through multiple RPC channels. The number of simultaneous non-persistent RPC channels that can be opened on a Shelly is limited to 6.

HTTP​

HTTP is used for one-shot request-response calls. It does not support connection keepalive and notifications cannot be sent and received through this channel. Protection through digest authentication over HTTP is enforced when enabled.

There are a few ways a RPC call can be made via http.

POST request with entire frame as payload​

Clients POST to /rpc on the Shelly, supplying the entire JSON RPC call frame as payload:

> POST /rpc HTTP/1.1
> Content-Type: application/json
> Content-Length: 58
> 
> {"id":0,"method":"Switch.Set","params":{"id":0,"on":true}}
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 65
< Connection: close
< 
< {"id":0,"src":"shellydev1-c8f09e47e6f0","result":{"was_on":true}}

The response is a complete frame, including the id of the request and either the result or error.

POST request with args only​

Clients POST to an endpoint which contains the method name: /rpc/<method name>, the payload contains params of the request:

> POST /rpc/Switch.Set HTTP/1.1
> Content-Type: application/json
> Content-Length: 18
> 
> {"id":0,"on":true}
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 15
< Connection: close
< 
< {"was_on":true}

The Shelly replies only with the contents of result or error from the JSON response frame.

GET with query string​

Clients submit a GET request to an endpoint which includes the method name: /rpc/<method name> and supply the parameters to the method in a query string. For simple scalar parameters, just put them in the url: /rpc/Switch.Set?id=0,on=true.

Prior to version 1.0.0 string values need to be enclosed in ". Now, only the literal strings "true" and "false" or numeric values need the quotes, otherwise string type is implied.

There are two ways to pass objects:

  • by passing the JSON object as a query string value, properly url-encoded, examples:
    • /rpc/Sys.SetConfig?config={%22device%22:{%22name%22:%22Awesome%20Shelly%22}}
  • Since version 1.0.0, individual scalar values within an object hierarchy can be set, the same examples:
    • /rpc/Sys.SetConfig?config.device.name=%22Awesome%20Shelly%22

Note, that browsers will do the necessary escaping of special symbols in the query string, so the following will work as well: /rpc/Sys.SetConfig?config.device.name="Awesome Shelly".

Example 1:

Environmental variable for connecting to Shelly host with IP address 192.168.33.1:
export SHELLY=192.168.33.1

Example 2:

HTTP GET request invoking the method Switch.Set:
curl "http://${SHELLY}/rpc/Switch.Set?id=0&on=true"

Example 3:

HTTP POST request invoking the method Switch.Set with JSON object containing the parameters as request payload:
curl -X POST -d '{"id":0, "on":true}' "http://${SHELLY}/rpc/Switch.Set"

Example 4:

HTTP POST request invoking the method Switch.Set with entire request frame as payload:
curl -X POST -d '{"id":2, "method":"Switch.Set", "params":{"id":0, "on":true}}' \
 "http://${SHELLY}/rpc"

Websocket​

The connection is kept alive through the whole duration of the communication (not only for one request-response pair) as used by the local web interface and aioshelly. Each Shelly device has a websocket endpoint and a client can connect to it to communicate with the device. Protection through digest authentication is supported over this channel.

The websocket channel is served on ws://<shelly.addr>/rpc. Clients must send at least one request frame with valid src to be able to receive notifications from the device.

Example 1:

A websocket connection to Shelly host is opened and the method Switch.Set is invoked:
wscat -c ws://${SHELLY}/rpc
{"id":2, "src":"user_1", "method":"Switch.Set", "params":{"id":0, "on":true}}

MQTT​

This is publisher-subscriber based communication. Each client can subscribe and publish to chosen topics. The connection is established by the client, subscribing to a topic or publishing into a topic on a MQTT broker. For a client to be able to communicate with a device, both the device and the client must be connected to the same MQTT broker, or a federated set of brokers.

  • Topic for publishing requests: <shelly-id>/rpc. To be able to send requests to a device, you must subscribe to this topic, substituting <shelly-id> with the relative data for your Shelly device. For example, shellypro4pm-f008d1d8b8b8/rpc.
  • Topic for responses: <src>/rpc. To be able to receive a response to a request you send, you must subscribe to this topic, substituting <src> with the source defined in your request frame. For example, for a request frame containing "src":"user_1", the topic is user_1/rpc.
  • Topic for notifications: <shelly-id>/events/rpc. To be able to receive notifications from a device, you must subscribe to this topic, substituting <shelly-id> with the relative data for your Shelly device. For example, shellypro4pm-f008d1d8b8b8/events/rpc.
  • Topic for online status: <shelly-id>/online. On this topic the device publishes true once connected to mqtt and false will be published by the broker as a "Last will and testament" message of the device, once one of those conditions happen:
    • The broker detects an I/O error or network failure.
    • The client fails to communicate within the defined Keep Alive period.
    • The client does not send a DISCONNECT packet before it closes the network connection.
    • The broker closes the network connection because of a protocol error.

Example 1:

Environmental variables for connecting to the broker.hivemq.com MQTT server on port 1883:
export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883

Example 2:

A request invoking the Switch.Set method. The request is published to the topic shellyplus1-c4dd57877294/rpc:
mosquitto_pub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t shellyplus1-c4dd57877294/rpc \
 -m '{"id":123, "src":"user_1", "method":"Switch.Set", "params":{"id":0,"on":true}}'
Response
On topic user_1/rpc:
payload {"id": 0, "source": "init", "output": false}

Example 3:

Subscribing to the topic user_1/rpc for receiving responses:
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t user_1/rpc

Example 4:

Subscribing to the topic shellypro4pm-f008d1d8b8b8/events/rpc for receiving notifications:
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t shellypro4pm-f008d1d8b8b8/events/rpc

UDP​

RPC over UDP works in two directions:

  • RPC notifications can be sent from the Shelly device to a configured peer address;
  • RPC calls can be invoked by sending datagrams with request frames to a configured port on the Shelly.

Both are disabled by default. To enable them, set udp_rpc keys in the System Component. Because UDP provides no delivery guarantees it should be used only if Websocket or MQTT are not feasible.

Datagrams should contain complete JSON frames in both directions. More information on the inner workings can be found in the upstream documentation.

Example 1:

A request invoking Sys.GetStatus via mos tool
mos call --port udp://192.168.11.5:1234/ Shelly.GetStatus

Useful Tools​

Many tools can be used to send requests to and receive responses from Shelly devices. Some of them are:

mos​

The cli tool of MongooseOS. Quick start guide can be found here. Example requests are available throughout the Gen2+ API documentation.

info

To be able to easily execute the mos examples in this documentation you can set an environmental variable containing your MOS port in your terminal using:

export PORT=http://YourShellyIPOrHostname/rpc

Note that through this environmental variable you can send requests over websocket, as well as over HTTP.

Example 1:

Environmental variable for connecting to Shelly host with IP address 192.168.33.1 over HTTP:
export PORT=http://192.168.33.1/rpc

Example 2:

Example request with mos:
mos --port ${PORT} call Switch.Toggle '{"id":0}'
Response:
{
  "was_on": false
}

Example 3:

Environmental variable for connecting to Shelly host with IP address 192.168.33.1 over websocket:
export PORT=ws://192.168.33.1/rpc

Example 4:

Example request with mos:
mos --port ${PORT} call Switch.GetConfig '{"id":0}'
Response:
{
  "id": 0,
  "name": null,
  "in_mode": "follow",
  "initial_state": "match_input",
  "auto_on": true,
  "auto_on_delay": 60.00,
  "auto_off": true,
  "auto_off_delay": 60.00,
  "power_limit": 3500,
  "voltage_limit": 280,
  "current_limit": 16.00
}

curl​

curl is, as stated its official webpage, "command line tool and library for transferring data with URLs". It can be used to invoke RPC methods over HTTP. Documentation can be found here. Example requests with curl can be found above as well as throughout the Gen2+ API documentation.

info

To be able to easily execute the curl examples in this documentation you can set an environmental variable containing your Shelly IP/Shelly hostname in your terminal using:

export SHELLY=yourShellyIPOrHostname

websocat​

websocat is a command line websocket multitool. Documentation and source code are on github.com/vi/websocat

info

To be able to easily execute the websocat examples in this documentation you can set an environmental variable containing your Shelly IP/Shelly hostname in your terminal using:

export SHELLY=yourShellyIPOrHostname

mosquitto​

MQTT broker and clients. It comes with CLI tools: mosquitto_pub and mosquitto_sub. On ubuntu, these are packaged as mosquitto-clients. Documentation of all utilities available can be found here. Examples with mosquitto can be found above.

info

To be able to easily execute the mosquitto examples you can set an environmental variable containing the name of the MQTT server and the port in your terminal using:

export MQTT_SERVER=yourMQTTServer
export MQTT_PORT=yourPort

Weasel​

In-browser helper console for communication over Websocket. More information and demo can be found here.