Skip to main content
Version: 1.0

Shelly Pro Sensor Add-On

ProSensorAddon is a Service for Shelly Pro devices that manages the exposure of add-on peripherals through an external addon board. It shares most functionality with SensorAddon but is designed specifically for Pro series devices.

ProSensorAddon uses ProSensorAddon, SensorAddon and Addon RPC namespaces and provides the following methods:

ProSensorAddon-specific methods:

Shared SensorAddon methods:

AddOn management methods:

ProSensorAddon allows the client to link add-on peripherals to Component instances, which in effect means that access to said peripherals is available through the standard Component interfaces: <Component>.GetStatus(), <Component>.GetConfig(), <Component>.SetConfig(). Ids of Components linked to add-on peripherals start from 100 and are limited to 199. Ids range [0..99] is reserved for Components linked to "internal" peripherals.

Supported IOs​

The Pro Sensor Addon supports multiple IOs per peripheral type:

Peripheral typeSupported IOsLabels
analog_in0, 1GND, AIN (0, 1)
voltmeter0, 1GND, AIN (0, 1)
digital_in0, 1GND, DIN (0, 1)
ds18b200, 1GND, DATA (0, 1), VCC
dht220, 1GND, DATA (0, 1), VCC
digital_out0IN, OUT

Peripheral Types and Component Mapping​

Below is a list of supported add-on peripherals and the Component types they can be linked to:

Peripheral typeComponent type
analog_ininput
voltmetervoltmeter
digital_ininput
ds18b20temperature
dht22temperature, humidity
digital_outswitch

Changes in peripheral<->component links made with SensorAddon.AddPeripheral, SensorAddon.RemovePeripheral, SensorAddon.UpdatePeripheral bond the firmware to spawn/destroy Component instances and therefore require reboot to apply.

Supported Devices​

Devices that support Shelly Pro Sensor Addon:

Addon Configuration​

Addon board can be enabled or disabled by setting device.addon_type parameter in Sys config. To enable Shelly Pro Sensor Addon, addon_type must be set to "sensor". When Addon is enabled, device must be restarted and all related API will be accessible. To disable Shelly Pro Sensor Addon, parameter device.addon_type must be set to null.

Methods​

ProSensorAddon.GetStatus​

ProSensorAddon.GetStatus returns the status of the Pro Sensor Addon component.

Request​

PropertyTypeDescription

id

number

Id of the ProSensorAddon component instance. Required

Response​

PropertyTypeDescription

id

number

Id of the component instance

fw_version

string

Current firmware version of the addon board

available_updates

object

Information about available firmware updates. Present only if an update is available and AddOn.CheckForUpdate is executed

PropertyTypeDescription

stable

object

Stable update channel information

PropertyTypeDescription

version

string

Available firmware version

update

object

Information about ongoing firmware update. Present only during update

PropertyTypeDescription

progress

number

Update progress in percent (0-100)

state

string

Update state: "started", "updating", "success", "error", "finished"

ts

number

Timestamp of the status

errors

array of strings

Error conditions. Possible values: "addon_update_required", "ota_update_failed"

Examples​

http://192.168.33.1/rpc/ProSensorAddon.GetStatus?id=101

Response

{
  "id": 101,
  "fw_version": "1.0.0"
}

Response with available update:

Response

{
  "id": 101,
  "fw_version": "1.0.0",
  "available_updates": {
    "stable": {
      "version": "1.1.0"
    }
  }
}

Response during firmware update:

Response

{
  "id": 101,
  "fw_version": "1.0.0",
  "update": {
    "progress": 45,
    "state": "updating",
    "ts": 1699876543.21
  }
}

ProSensorAddon.GetConfig​

ProSensorAddon.GetConfig returns the configuration of the Pro Sensor Addon component.

Request​

This method takes no parameters.

Response​

Returns an empty object {}. The ProSensorAddon component currently has no configurable parameters.

Examples​

http://192.168.33.1/rpc/ProSensorAddon.GetConfig

Response

{}

ProSensorAddon.SetConfig​

ProSensorAddon.SetConfig sets the configuration of the Pro Sensor Addon component.

Request​

This method takes no parameters as there are currently no configurable parameters.

Response​

The result from this method is null on success.

Examples​

http://192.168.33.1/rpc/ProSensorAddon.SetConfig

Response

null

SensorAddon.AddPeripheral​

SensorAddon.AddPeripheral links an add-on peripheral to a Component instance.

Request​

Parameters:

PropertyTypeDescription

type

string

Peripheral type: "ds18b20", "dht22", "digital_in", "analog_in", "voltmeter", "digital_out"

attrs

object

Attributes that the method takes

Find more about the attrs properties in AddPeripheral attributes section

Response​

List of JSON objects, where the object key designates the Component key (in format <type>:<id>, e.g. temperature:100) to which the peripheral is linked.

Examples: SensorAddon.AddPeripheral Examples​

SensorAddon.GetPeripherals​

SensorAddon.GetPeripherals returns the configured links between add-on peripherals and Components.

Request​

This method takes no parameters.

Response​

List of JSON objects, one for each supported peripheral, where the object key designates the peripheral type ([ds18b20, dht22, digital_in, analog_in, voltmeter, digital_out]). The object body contains a nested list of JSON objects, where the object key designates the Component keys (in format <type>:<id>, e.g. temperature:100) to which the peripheral is linked. The object body also contains the io on which the sensor is attached and may contain additional attributes depending on the peripheral type.

Examples: SensorAddon.GetPeripherals Examples​

SensorAddon.RemovePeripheral​

Request​

PropertyTypeDescription

component

string

Linked Component key (in format <type>:<cid>, e.g. temperature:100)

Response​

The result from this method is null on success otherwise will return error information.

Examples: SensorAddon.RemovePeripheral Examples​

SensorAddon.UpdatePeripheral​

SensorAddon.UpdatePeripheral serves to reconfigure peripheral-component links or reassign peripheral-specific properties. Currently only ds18b20 peripheral has updateable attributes.

Request​

PropertyTypeDescription

component

string

Linked Component key (in format <type>:<cid>, e.g. temperature:100)

attrs

object

Attributes that the method takes

Find more about the attrs properties in UpdatePeripheral attributes section

Response​

The result from this method is null on success otherwise will return error information.

Examples: SensorAddon.UpdatePeripheral Examples​

SensorAddon.OneWireScan​

SensorAddon.OneWireScan returns a list of discovered OneWire devices. This method returns an error if a dht22 peripheral is currently in use on all IOs, as dht22 occupies the same GPIOs used for OneWire. For now the only supported OneWire peripheral type is ds18b20.

Request​

This method takes no parameters.

Response​

Attributes in the result:

PropertyTypeDescription

devices

array of objects

List of all discovered devices on the bus

PropertyTypeDescription

type

string

Device type. "ds18b20" or "unknown" if not supported

addr

string

Address of device

component

string

Linked Component key (in format <type>:<cid>, e.g. temperature:100) if added, null otherwise

io

number

IO/bus number on which the sensor is attached/detected

Examples: SensorAddon.OneWireScan Examples​

AddOn.GetInfo​

AddOn.GetInfo returns information about the addon hardware and firmware.

Request​

This method takes no parameters.

Response​

PropertyTypeDescription

type

string

Addon type. For Pro Sensor Addon this is "ProSensorAddon"

hw_ver

string

Hardware version of the addon board. null if not available

fw_ver

string

Firmware version of the addon board. null if not available

supported_ios

object

Object describing supported IOs per peripheral type

PropertyTypeDescription

digital_in

array of numbers

List of supported IO numbers for digital input

analog_in

array of numbers

List of supported IO numbers for analog input

digital_out

array of numbers

List of supported IO numbers for digital output

ds18b20

array of numbers

List of supported IO/bus numbers for DS18B20

dht22

array of numbers

List of supported IO numbers for DHT22

Examples​

http://192.168.33.1/rpc/AddOn.GetInfo

Response

{
  "type": "ProSensorAddon",
  "hw_ver": "1.0",
  "fw_ver": "1.0.0",
  "supported_ios": {
    "digital_in": [
      0,
      1
    ],
    "analog_in": [
      0,
      1
    ],
    "digital_out": [
      0
    ],
    "ds18b20": [
      0,
      1
    ],
    "dht22": [
      0,
      1
    ]
  }
}

Response when addon is not connected:

Response

{}

AddOn.CheckForUpdate​

AddOn.CheckForUpdate checks for available firmware updates for the addon board.

Request​

This method takes no parameters.

Response​

PropertyTypeDescription

available_updates

object

Information about available firmware updates. Present only if an update is available

PropertyTypeDescription

type

string

Addon type ("ProSensorAddon")

stable

object

Stable update channel information

PropertyTypeDescription

version

string

Available firmware version

The result from this method is null if no updates are available.

Examples​

http://192.168.33.1/rpc/AddOn.CheckForUpdate

Response with available update:

Response

{
  "available_updates": {
    "type": "ProSensorAddon",
    "stable": {
      "version": "1.1.0"
    }
  }
}

Response when no update is available:

Response

null

AddOn.Update​

AddOn.Update initiates a firmware update of the addon board.

Request​

PropertyTypeDescription

url

string

URL to download the firmware from. Optional - if not provided, uses the URL from the last CheckForUpdate result

timeout

number

Update timeout in seconds. Must be greater than 300 seconds. Optional, defaults to system timeout

Response​

The result from this method is null on success. The update progress can be monitored via ProSensorAddon.GetStatus.

Examples​

Update using discovered update URL:

http://192.168.33.1/rpc/AddOn.Update?timeout=600

Response

null

Update from custom URL:

http://192.168.33.1/rpc/AddOn.Update?url="https://example.com/firmware/prosensoraddon-1.1.0.bin"&timeout=600

Response

null

AddPeripheral Attributes​

Some peripherals require additional configuration attributes like one wire device address. For every SensorAddon peripheral, component cid can be predefined or will be taken first available.

PropertyTypeDescription

cid

number

Id of component. (optional)

addr

string

Address of DS18B20 sensor. (required for DS18B20 sensor)

io

number

IO number on which the sensor is attached (required for ProSensorAddon as it has multiple IOs per peripheral type)

UpdatePeripheral Attributes​

PropertyTypeDescription

addr

string

Address of DS18B20 sensor. (required for DS18B20 sensor)

io

number

IO number on which the sensor is attached (required only for addons that can have multiple peripherals of the same type)

Examples​

Enable / Disable ProSensorAddon examples​

Enable ProSensorAddon​

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"addon_type":"sensor"}}

Disable ProSensorAddon​

http://192.168.33.1/rpc/Sys.SetConfig?config={"device":{"addon_type":null}}

SensorAddon.AddPeripheral examples​

Add Digital Input on IO 0​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="digital_in"&attrs={"cid":100,"io":0}

Response

{
  "input:100": {
    "io": 0
  }
}

Add Digital Input on IO 1​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="digital_in"&attrs={"io":1}

Response

{
  "input:101": {
    "io": 1
  }
}

Add Analog Input on IO 0​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="analog_in"&attrs={"io":0}

Response

{
  "input:100": {
    "io": 0
  }
}

Add Analog Input on IO 1​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="analog_in"&attrs={"io":1}

Response

{
  "input:101": {
    "io": 1
  }
}

Add Digital Output​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="digital_out"&attrs={"cid":100}

Response

{
  "switch:100": {
    "io": 0
  }
}

Add DS18B20 sensor on IO/bus 0​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="ds18b20"&attrs={"cid":101,"addr":"11:22:33:44:55:66:77:88","io":0}

Response

{
  "temperature:101": {
    "io": 0
  }
}

Add DS18B20 sensor on IO/bus 1​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="ds18b20"&attrs={"cid":102,"addr":"11:22:33:44:55:66:77:99","io":1}

Response

{
  "temperature:102": {
    "io": 1
  }
}

Add DHT22 sensor on IO 0​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="dht22"&attrs={"io":0}

Response

{
  "humidity:100": {
    "io": 0
  },
  "temperature:100": {
    "io": 0
  }
}

Add DHT22 sensor on IO 1​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="dht22"&attrs={"io":1}

Response

{
  "humidity:101": {
    "io": 1
  },
  "temperature:101": {
    "io": 1
  }
}

Add Voltmeter on IO 0​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="voltmeter"&attrs={"io":0}

Response

{
  "voltmeter:100": {
    "io": 0
  }
}

SensorAddon.RemovePeripheral example​

http://192.168.33.1/rpc/SensorAddon.RemovePeripheral?component="input:100"

Response

null

Remove Digital Output​

http://192.168.33.1/rpc/SensorAddon.RemovePeripheral?component="switch:100"

Response

null

SensorAddon.UpdatePeripheral example​

http://192.168.33.1/rpc/SensorAddon.UpdatePeripheral?component="temperature:100"&attrs={"addr":"40:255:100:6:199:204:149:177"}

Response

null

SensorAddon.GetPeripherals example​

http://192.168.33.1/rpc/SensorAddon.GetPeripherals

Response

{
  "digital_in": {
    "input:100": {
      "io": 0
    },
    "input:101": {
      "io": 1
    }
  },
  "ds18b20": {
    "temperature:102": {
      "addr": "40:255:100:6:199:204:149:177",
      "io": 0
    },
    "temperature:103": {
      "addr": "40:255:100:6:199:204:149:178",
      "io": 1
    }
  },
  "dht22": {
    "temperature:104": {
      "io": 0
    },
    "humidity:104": {
      "io": 0
    }
  },
  "analog_in": {
    "input:105": {
      "io": 0
    }
  },
  "voltmeter": {
    "voltmeter:106": {
      "io": 1
    }
  },
  "digital_out": {
    "switch:107": {
      "io": 0
    }
  }
}

SensorAddon.OneWireScan example​

http://192.168.33.1/rpc/SensorAddon.OneWireScan

Response

{
  "devices": [
    {
      "type": "ds18b20",
      "addr": "40:255:100:6:199:204:149:177",
      "component": null,
      "io": 0
    },
    {
      "type": "ds18b20",
      "addr": "40:255:100:6:199:204:149:178",
      "component": "temperature:100",
      "io": 0
    },
    {
      "type": "ds18b20",
      "addr": "40:255:100:6:199:204:149:179",
      "component": null,
      "io": 1
    }
  ]
}