Skip to main content
Version: 0.14

Shelly Sensor Add-On

SensorAddon is a Service (similar to Webhook and Schedule), which manages the exposure of add-on peripherals. It uses SensorAddon as RPC namespace and provides the following methods:

SensorAddon 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. Below is a list of supported add-on peripherals and the Component types they can be linked to:

Peripheral typeComponent type
ds18b20temperature
dht22temperature, humidity
digital_ininput
analog_ininput
voltmetervoltmeter

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.

Devices that support Shelly Sensor Addon

Addon configuration​

Addon board can be enabled or disabled by setting device.addon_type parameter in Sys config. To enable Shelly 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 Sensor Addon, parameter device.addon_type must be set to null.

Methods​

SensorAddon.AddPeripheral​

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

Request​

Parameters:

PropertyTypeDescription

type

string

Peripheral type

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]). 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 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, 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

Examples: SensorAddon.OneWireScan Examples​

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)

UpdatePeripheral Attributes​

PropertyTypeDescription

addr

string

Address of DS18B20 sensor. (required for DS18B20 sensor)

Examples​

Enable / Disable SensorAddon examples​

Enable SensorAddon​

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

Disable SensorAddon​

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

SensorAddon.AddPeripheral examples​

Add Digital Input​

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

Response

{
  "input:100": {}
}

Add Analog Input​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="analog_in"

Response

{
  "input:100": {}
}

Add DS18B20 sensor​

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

Response

{
  "temperature:101": {}
}

Add DHT22 sensor​

http://192.168.33.1/rpc/SensorAddon.AddPeripheral?type="dht22"

Response

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

SensorAddon.RemovePeripheral example​

http://192.168.33.1/rpc/SensorAddon.RemovePeripheral?component="input: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": {}
  },
  "ds18b20": {
    "temperature:100": {
      "addr": "40:255:100:6:199:204:149:177"
    }
  },
  "dht22": {},
  "analog_in": {
    "input:101": {}
  }
}

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
    },
    {
      "type": "ds18b20",
      "addr": "40:255:100:6:199:204:149:178",
      "component": "temperature:100"
    }
  ]
}