Skip to main content

Communication

For calling a device you need the device_id for that device. It is available in the Shelly Cloud app in Device->Settings->Device Info

The request is HTTPS POST to the Server your devices are hosted at. You need to supply the auth_key, server_uri (as described in Getting started and device_id

Communicating with a device

Check device status
curl -X POST https://<server_uri>/device/status -d "id=<device_id>&auth_key=<auth_key>"
Check device status response
{
"isok": true,
"data": {
"online": true,
"device_status": {
"script:1": { "id": 1, "running": false },
"_updated": "2021-10-19 07:59:18",
"cloud": { "connected": true },
"script:4": { "id": 4, "running": false },
"wifi": {
"sta_ip": "192.168.2.16",
"status": "got ip",
"ssid": "linux-bg.org",
"rssi": -59
},
"serial": 1634630341.44,
"script:2": { "id": 2, "running": false },
"id": "a8032abe41fc",
"switch:0": {
"id": 0,
"aenergy": {
"by_minute": [0, 0, 0],
"minute_ts": 1634630339,
"total": 0.031
},
"apower": 0,
"current": 0,
"output": false,
"source": "SHC",
"voltage": 236.2,
"temperature": { "tC": 47.4, "tF": 117.4 }
},
"code": "SNSW-001P16EU",
"mqtt": { "connected": true },
"script:3": { "id": 3, "running": false },
"ble": [],
"sys": {
"available_updates": {
"stable": { "version": "0.8.1" },
"test": { "version": "0.9.0-beta1-dev20330" }
}
},
"input:0": { "id": 0, "state": false }
}
}
}

Controlling device output channels

The request parameters are:

  • channel: number. Output channel on the device to be controlled. Required
  • turn: string, on or off. Required
Control device output
curl -X POST https://<server_uri>/device/relay/control -d "channel=<id>&turn=<on|off>&id=<device_id>&auth_key=<auth_key>"

Controlling cover control devices (Shelly 2, Shelly 2.5)

The request parameters are:

  • direction: string, open, close or stop.
Control device output
curl -X POST https://<server_uri>/device/relay/roller/control -d "direction=<open|close|stop>&id=<device_id>&auth_key=<auth_key>"

Or you can move the cover to a specified position (percentage)

The request parameter is:

  • pos: number [0..100].
Control device output
curl -X POST https://<server_uri>/device/relay/roller/control -d "pos=<[0..100]>&id=<device_id>&auth_key=<auth_key>"

Controlling lights in color mode - Shelly RGBW, Shelly RGBW2, Shelly Bulb

The request parameters are:

  • turn: string, on or off. Required
  • white: number [0..255]
  • red: number [0..255]
  • green: number [0..255]
  • blue: number [0..255]
  • gain: number [0..100], applies only for RGB color.
Turn lamp on or off
curl -X POST https://<server_uri>/device/light/control -d "turn=<on|off>&id=<device_id>&auth_key=<auth_key>"
Set white at 30
curl -X POST https://<server_uri>/device/light/control -d "white=30&id=<device_id>&auth_key=<auth_key>"
Turn on and set white at 30
curl -X POST https://<server_uri>/device/light/control -d "turn=on&white=30&id=<device_id>&auth_key=<auth_key>"

Controlling lights in white mode - Shelly RGBW, Shelly RGBW2, Shelly Bulb

The request parameters are:

  • channel: number. Output light channel to be controlled. Required
  • turn: string, on or off. Required
  • brightness: number [0..100]
Control lamp channel in white mode
curl -X POST https://<server_uri>/device/light/control -d "channel=<id>&turn=<on|off>&brightness=<[0..100]>&id=<device_id>&auth_key=<auth_key>"

Control device groups

Control of similar types of devices - Relays, Lights, Roller controls can be done en masse.

Relays

The request parameter is:

  • devices: array of objects, {id: number, turn: "on"|"off"}[].
    • turn parameter can be "on" or "off"
    • id is the device id, as mentioned earlier,
    • type device type / model for Gen. 2,
    • channel: the index of the "relays" array / "switch" component for Gen. 2,
    • gen: generation of the device, can be "1" or "2"
Control group of relays output
curl -X POST https://<server_uri>/device/relay/bulk_control -d 'devices=[{"id":<device_id>,"channel":<channel>},...]&auth_key=<auth_key>'

Lights

The request parameter is:

  • devices: array of objects, {id: number, turn: "on"|"off"}[].
    • turn parameter can be "on" or "off"
    • gain|brightness depends on the light model, gen. 2 lights can be controlled via the brightness parameter range from "0" to "100",
    • id is the device id, as mentioned earlier,
    • type device type / model for Gen. 2,
    • channel: the index of the "lights" array / "light" component for Gen. 2,
    • gen: generation of the device, can be "1" or "2"
Control group of relays output
curl -X POST https://<server_uri>/device/light/bulk_control -d 'devices=[{"id":<device_id>,"channel":<channel>},...]&auth_key=<auth_key>'

Rollers

The request parameter is:

  • devices: array of objects, {id: number, turn: "open"|"close"|"stop"}[].
    • direction parameter can be "open", "close" or "stop"
    • position range from "0" to "100",
    • id is the device id, as mentioned earlier,
    • type device type / model for Gen. 2,
    • channel: the index of the "rollers" array / "cover" component for Gen. 2,
    • gen: generation of the device, can be "1" or "2"
Control group of relays output
curl -X POST https://<server_uri>/device/roller/bulk_control -d 'devices=[{"id":<device_id>,"channel":<channel>},...]&auth_key=<auth_key>'