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

FieldTypeDescriptionRequired
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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 typeState attributeType
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 typeConfig attributeType
CLIPHumidity offset Int16
CLIPLightLevel tholddark Uint16
tholddarkoffset Uint16
CLIPTemperature offset Int16

Device sensors

Supported state attributes

Sensor typeState attributeType
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 typeConfig attributeTypeDescription
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