Sensors¶

Sensors can be used to measure environment parameters like temperature or to emit events like a button press from a switch. With a coressponding rule they can control lights and groups.

Create sensor ¶

POST /api/<apikey>/sensors

Creates a new CLIP sensor.

Parameters¶

Field	Type	Description	Required
name	String	The name of the sensor.	required
modelid	String	The model identifier of the sensor.	required
swversion	String	The software version of the sensor.	required
type	String	The type of the sensor, see Sensor types and states.	required
uniqueid	String	The unique id of the sensor. Should be the MAC address of the device.	required
manufacturername	String	The manufacturer name of the sensor.	required
state	Object	The state of the sensor, see Sensor types and states.	optional
config	Object	The config of the sensor. `on` — Bool (default: true) `reachable` — Bool (default: true) `battery` — Number (0–100)	optional

Example request data¶


{
    "config": {
        "on": true,
        "reachable": true
    },
    "manufacturername": "Me",
    "modelid": "T1000",
    "name": "My Switch",
    "swversion": "1.0",
    "type": "CLIPSwitch",
    "uniqueid": "00:1f:ee:00:00:00:08:bb-01-1000"
}

Response¶


HTTP/1.1 200 OK


[ { "success": { "id": "1" } } ]

Response fields¶

Field	Type	Description
id	String	The unique identifier of the new sensor.

Possible errors¶

400 Bad Request

403 Forbidden

Get all Sensors ¶

GET /api/<apikey>/sensors

Returns a list of all sensors. If there are no sensors in the system an empty object {} is returned.

Parameters¶

None

Response¶


HTTP/1.1 200 OK


{
    "1": {
        "config": {
            "on": true,
            "reachable": true
        },
        "ep": 1,
        "etag": "61eaee2477fc3d5c27932fefeef638bd",
        "lastseen": "2016-07-06T09:39Z",
        "manufacturername": "dresden elektronik",
        "modelid": "Lighting Switch",
        "name": "Lighting Switch 1",
        "state": {
            "lastupdated": "2016-07-06T09:39:53"
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "00:21:2e:ff:ff:00:a6:bc-01-1000"
    },

    "2": {
        "config": {
            "on": true,
            "reachable": true
        },
        "ep": 2,
        "etag": "61eaee2477fc3d5c27932fefeef638bd",
        "lastseen": "2016-07-06T09:39Z",
        "manufacturername": "dresden elektronik",
        "modelid": "Lighting Switch",
        "name": "Lighting Switch 2",
        "state": {
            "lastupdated": "2016-07-06T09:39:53"
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "00:21:2e:ff:ff:00:a6:bc-02-1000"
    }
}

Response fields¶

The whole sensor object as descripted in Get sensor.

Possible errors¶

403 Forbidden

Get sensor ¶

GET /api/<apikey>/sensors/<id>

Returns the sensor with the specified id.

Parameters¶

None

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


{
    "config": {
        "on": true,
        "reachable": true
    },
    "ep": 1,
    "etag": "61eaee2477fc3d5c27932fefeef638bd",
    "lastseen": "2016-07-06T09:39Z",
    "manufacturername": "dresden elektronik",
    "mode": 2,
    "modelid": "Lighting Switch",
    "name": "Lighting Switch 1",
    "state": {
        "lastupdated": "2016-07-06T09:39:53"
    },
    "swversion": "1.0",
    "type": "ZHASwitch",
    "uniqueid": "00:21:2e:ff:ff:00:a6:bc-01-1000"
}

Response fields¶

Field	Type	Description
config	Object	The config of the sensor. Refer to Change sensor config for further details.
ep	Number	The Endpoint of the sensor.
etag	String	HTTP etag which changes whenever the sensor changes.
lastseen	ISO 8601 timestamp	Timestamp representing the last time a message from the sensor was received. UTC with resolution of minutes.
manufacturername	String	The manufacturer name of the sensor.
mode	Number	The mode of the sensor. 1 = Scenes mode 2 = Two groups mode 3 = Color temperature mode (only available for dresden elektronik Lighting Switch)
modelid	String	The model id of the sensor.
name	String	The name of the sensor.
state	Object	The state of the sensor.
swversion	String	Software version of the sensor.
type	String	The type of the sensor.
uniqueid	String	The unique identifiers including the MAC address of the sensor.

Possible errors¶

403 Forbidden

404 Not Found

Update sensor ¶

PUT /api/<apikey>/sensors/<id>

Update a sensor with the specified parameters.

Parameters¶

Field

Type

Description

Required

name

String

The name of the sensor.

optional

mode

Number

Only availabe for dresden elektronik Lighting Switch. Set the mode of the switch.

1 = Scenes mode
2 = Two groups mode
3 = Color temperature mode

optional

Example request data¶

{
  "name": "a nice name"
}

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


    { "success": { "/sensors/1/name": "a nice name" } }

Possible errors¶

400 Bad Request

403 Forbidden

Change sensor config ¶

PUT /api/<apikey>/sensors/<id>/config

Update a sensor config with the specified parameters.
Sensors expose certain configuration parameters depending on their defined or known capabilities. To get an overview on which parameters are available for a particular device, get the sensor state of either all Get all sensors or a single sensor Get sensor.

Parameters¶

Important: Most attributes can be found in Supported config attributes

Field	Type	Description	Required
battery	Number (1–100)	The current battery state in percent, only for battery powered devices.	optional
on	Bool	The on/off status of the sensor.	optional
reachable	Bool	The reachable status of the sensor.	optional

Example request data¶

{
  "on": false,
  "reachable": false
}

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


    {
      "success": { "/sensors/1/config/on": false },
      "success": { "/sensors/1/config/reachable": false }
    }

Possible errors¶

400 Bad Request

403 Forbidden

Change sensor state ¶

PUT /api/<apikey>/sensors/<id>/state

Update a sensor state with the specified parameters.

Note

Changing the sensor state is only allowed for CLIP sensors.

Parameters¶

Allowed parameters are listed in CLIP sensors.

Example request data¶

{
  "flag": false
}

Response¶


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


    {
      "success": { "/sensors/1/state/flag": false }
    }

Possible errors¶

400 Bad Request

403 Forbidden

Delete sensor ¶

DELETE /api/<apikey>/sensors/<id>

Delete a sensor.

Parameters¶

Field	Type	Description	Required
reset	Bool	If this parameter is omitted, it will implicitly be set to false and the sensor is marked as deleted in the database. If set to true, deCONZ is trying to reset the whole physical device by issuing a leave request. It is required that the device is awake (able to receive commands) or supports this type of request respectively and on success, the device is deleted as a node and reset to factory defaults.	optional

Response¶

Response when no reset option provided.


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[ { "success": { "id": "1" } } ]

Response when reset option is provided.


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[ { "success": { "/sensors/1/reset": false } } ]

Possible errors¶

400 Bad Request

403 Forbidden

404 Not Found

Supported sensor types and states¶

CLIP sensors¶

These are virtual sensors without a real device behind it. CLIP sensors can be created, modified and used in rules.

Supported state attributes¶

Sensor type	State attribute	Type
CLIPAlarm	alarm	Bool
CLIPBattery	battery	Number (uint8)
CLIPCarbonMonoxide	carbonmonoxide	Bool
CLIPConsumption	consumption	Number (uint64)
CLIPFire	fire	Bool
CLIPGenericFlag	flag	Bool
CLIPGenericStatus	status	Int32
CLIPHumidity	humidity	Uint16
CLIPLightLevel	lightlevel	Uint16
	lux	Uint32
	dark	Bool
	daylight	Bool
CLIPOpenClose	open	Bool
CLIPPower	power	Int16
	voltage	Uint16
	current	Uint16
CLIPPresence	presence	Bool
	duration	Uint16
CLIPPressure	pressure	Int16
CLIPSwitch	buttonevent	Uint32
CLIPTemperature	temperature	Int16
CLIPVibration	vibration	Bool
CLIPWater	water	Bool

Supported config attributes¶

Sensor type	Config attribute	Type
CLIPHumidity	offset	Int16
CLIPLightLevel	tholddark	Uint16
	tholddarkoffset	Uint16
CLIPTemperature	offset	Int16

Device sensors¶

Supported state attributes¶

Sensor type	State attribute	Type
ZHAAirQuality	airquality	String Supported values: "excellent" "good" "moderate" "poor" "unhealthy" "out of scale"
	airqualityppb	Uint16 (0–65534)
ZHAAlarm	alarm	Bool
	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	tampered	Bool
ZHACarbonMonoxide	carbonmonoxide	Bool
	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	tampered	Bool
ZHAConsumption	consumption	Number
	lastupdated	ISO 8601 timestamp
	power	Number
ZHAFire	fire	Bool
	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	tampered	Bool
ZHAHumidity	humidity	Number
	lastupdated	ISO 8601 timestamp
ZHALightLevel	lux	Number
	lastupdated	ISO 8601 timestamp
	lightlevel	Number
	dark	Bool
	daylight	Bool
ZHAOpenClose	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	open	Bool
	tampered	Bool
ZHAPower	current	Number
	lastupdated	ISO 8601 timestamp
	power	Number
	voltage	Number
ZHAPresence	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	presence	Bool
	tampered	Bool
ZHASwitch	buttonevent Refer to Button Events for device specific values.	Number
	lastupdated	ISO 8601 timestamp
	gesture	Number
	eventduration	Number
	x	Number
	y	Number
	angle	Number
ZHAPressure	pressure	Number
	lastupdated	ISO 8601 timestamp
ZHATemperature	temperature	Number
	lastupdated	ISO 8601 timestamp
ZHATime	lastset	Time
	lastupdated	ISO 8601 timestamp
	localtime	ISO 8601 timestamp
	utc	Time
ZHAThermostat	on	Bool
	errorcode	String
	fanmode	String
	floortemperature	Number
	heating	Bool
	lastupdated	ISO 8601 timestamp
	mountingmodeactive	Bool
	temperature	Number
	valve	Number
	windowopen	String
ZHAVibration	vibration	Bool
	lastupdated	ISO 8601 timestamp
	orientation	Array of 3 Numbers
	tiltangle	Number
	vibrationstrength	Number
ZHAWater	water	Bool
	lastupdated	ISO 8601 timestamp
	lowbattery	Bool
	tampered	Bool
Various sensors	charging	Bool
Various sensors	presenceevent	String

Supported config attributes¶

Sensor type	Config attribute	Type	Description
Daylight	configured	Bool	True if the daylight sensor is configured with coordinates.	R
	lat	Number	Latitude of the set location/timezone.	W
	long	Number	Longitude of the set location/timezone.	W
	sunriseoffset	Number (-120–120)	Sunrise offset value for location/timezone in minutes.	R
	sunsetoffset	Number (-120–120)	Sunset offset value for location/timezone in minutes.	R
ZHALightLevel	tholddark	Number (0–65534)	Specifies at which `lightlevel` the `dark` attribute turns false. Default: 12000	RW
	tholdoffset	Number (1–65534)	Relative offset to `tholddark`. Sets `daylight` attribute to true when when lightlevel is at or above (tholddark + tholdoffset). Default: 7000	RW
ZHAHumidity	offset	Number (-32768–32767)	Adds a signed offset value to measured state values. Values send by the REST-API are already amended by the offset.	RW
ZHAPresence	duration	Number (0–65535)	Timeout in seconds presence state is set to false again.	RW
	delay	Uint16 (0–65535)	The occupied to unoccupied delay in seconds.	RW
ZHATemperature	offset	Number (-32768–32767)	Adds a signed offset value to measured state values. Values send by the REST-API are already amended by the offset.	R
ZHASwitch	group	Uint16	The associated Zigbee group the sensor controls. (only supported by some sensors)	R
	mode	String	For ubisys S1/S2, operation mode of the switch. Supported values: "momentary" "rocker"	RW
Ubisys J1 (ZHASwitch)	window coveringtype	Number (0–9)	Sets the covering type and starts calibration. Supported values: 0 = Roller Shade 1 = Roller Shade two motors 2 = Roller Shade exterior 3 = Roller Shade two motors ext 4 = Drapery 5 = Awning 6 = Shutter 7 = Tilt Blind Lift only 8 = Tilt Blind lift & tilt 9 = Projector Screen	RW
ZHAThermostat	mode	String	Sets the current operating mode of a thermostat. Supported values: "off" "auto" "cool" "heat" "emergency heating" "precooling" "fan only" "dry" "sleep" (Supported modes are device dependent)	RW
	displayflipped	Bool	Flip the display for TRVs supporting it.	RW
	externalsensortemp	Number (-32768–32767)	Allows to use the temperature value provided by an external sensor. (device dependent and only exposed for devices supporting it)	RW
	externalwindowopen	Bool	Allows to use the open/close state from an external sensor. (device dependent and only exposed for devices supporting it)	RW
	fanmode	String	Sets the mode of the fan. Supported values: "off" "low" "medium" "high" "on" "auto" "smart" (device dependent and only exposed for devices supporting it)	RW
	hostflags	Uint32	Eurotronic Spirit SPZB 0x0002 — Display flipped 0x0004 — Mode heat 0x0010 — Mode off 0x0080 — Locked Only for debugging purpose.	R
	locked	Bool	Child lock active/inactive for thermostats/TRVs supporting it.	RW
	preset	String	Sets the operating mode for Tuya thermostats. Supported values: "holiday" "auto" "manual" "comfort" "eco" "boost" "complex" (supported modes are device dependent)	RW
	setvalve	Bool	Controls valve of thermostats. false — Close valve true — Open valve (exposed for thermostats supporting it)	RW
	swingmode	String	Sets the AC louvers position. Supported values: "fully closed" "fully open" "quarter open" "half open" "three quarters open" (exposed for thermostats supporting it)	RW
	temperature measurement	String	Sets the mode of operation for Elko Super TR thermostat. Supported values: "air sensor" "floor sensor" "floor protection"	RW
	window open_set	Bool	Sets if window open detection shall be active or inactive for Tuya thermostats. (support is device dependent)	RW
	schedule	Array	A thermostat schedule. todo: describe	RW
	schedule_on	Bool	True when a thermostat schedule is enabled.	RW
	coolsetpoint	Number (700–3500)	Set the desired cooling temperature.	RW
	heatsetpoint	Number (500–3200)	Set the desired heating temperature.	RW
	mountingmode	Bool	Sets a TRV into mounting mode if supported (valve fully open position).	RW
Various sensors	clickmode	String	Intended for devices which can configure the click behavior of a button. Xiaomi devices have possible values of 'coupled', 'decoupled', 'multiclick' and 'highspeed'. (only supported by some sensors)	RW
	devicemode	String	Intended for devices which can change their mode of operation. Xiaomi devices have possible values of 'compatibility' and 'zigbee'. (only supported by some sensors, shouldn't be changed)	RW
	enrolled	Number	Displays the current IAS enrollment status. Supported for all devices having the IAS Zone cluster: 0 = Init 1 = Enrolled 2 = Read 3 = Wait read 4 = Write CIE address 5 = Wait write CIE address 6 = Delay enroll 7 = Enroll 8 = Wait enroll 9 = Max (invalid)	R
	ledindication	Bool	Lets the sensor indicate itself, usually via LED blinking. Supported for Philips Hue motion sensor.	RW
	pending	Uint8	Bitmap of outstanding configuration tasks for a device. A value of "[]" indicates no outstanding tasks. todo: describe possibe values	R
	resetpresence	Bool	Resets the presence state of the Xiaomi FP1 presence sensor.	W
	sensitivity	Number	Device specific sensitivity, with following supported values. Philips Hue motion sensor: 0 = low 1 = medium 2 = high Xiaomi vibration sensor: 21 = low 11 = medium 1 = high	RW
	sensitivitymax	Number	Device specific maximum `sensitivity` value. Xiaomi vibration sensor: 21 Philips Hue motion sensor: 2	R
	triggerdistance	String	A device specific distance setting when it triggers the associated function (e.g. detect presence or motion).	RW
	usertest	Bool	Starts the sensor self-test mode. Supported for Philips Hue motion sensor.	RW
Xiaomi sensors	temperature	Number (-27315–32767)	Reported temperature values by devices which are no temperature measuring devices. (presumably device temperature).	R
Develco Metering Interfaces	interfacemode	Number	Allows to set the device specific interface mode. ZHEMI101: 1 = Pulse Counting on an Electricity Meter – Unit KWh 2 = Pulse Counting on a Gas Meter – Unit m3 3 = Pulse Counting on a Water Meter – Unit m3 4 = Kamstrup KMP Protocol 5 = Not Supported - Linky Protocol 6 = DLMS-COSEM - IEC62056-21 mod A 7 = P1 Dutch Standard – DSMR 2.3 Version 8 = P1 Dutch Standard – DSMR 4.0 Version EMIZB-132: 1 = Norwegian HAN 2 = Norwegian HAN – Enable extra load 3 = Aidon Meter supporting Norwegian HAN HW interface 4 = Kaifa meter and Kamstrup meters running old firmware 5 = Auto detect meter function (device dependent and only exposed for devices supporting it)	RW
	pulseconfiguration	Number (0–65535)	Pulse Configuration represents the number of pulses the meter outputs per unit. (device dependent and only exposed for devices supporting it)	RW