Skip to main content

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"
}
]
}