Skip to main content
Version: 0.14

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 request-response based communication. Each Shelly device has an HTTP endpoint and a client can connect to it to communicate with the device. Shelly devices support GET and POST HTTP requests. Notifications cannot be sent and received through this channel. Protection through digest authentication over HTTP is supported.

Structure of the supported requests:

  • GET http://<shelly.addr>/rpc/<Method>?arg1=<argument>&arg2=<argument> (examples can be found throughout the Shelly-NG API documentation)
  • POST http://<shelly.addr>/rpc/<Method> with JSON object containing the parameters as request payload
  • POST http://<shelly.addr>/rpc with entire request frame as payload (examples can be found throughout the Shelly-NG API documentation)

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 Shelly-NG 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 Shelly-NG 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.