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>'