Sensors can be used to measure environment parameters like brightness or activation of a switch. With a coressponding rule they can control lights and groups.

Create sensor 

POST /api/<apikey>/sensors

Creates a new 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: allowed sensor types and its 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: supported sensor types and its states). optional
config Object The config of the sensor.
  • on - Bool - default: true
  • reachable - Bool - default: true
  • battery - Number (0..100)
optional

Supported sensor types and its states

Sensor typeSupported stateType
ZHAAlarm alarm Bool
lastupdated String
lowbattery Bool
tampered Bool
ZHACarbonMonoxide carbonmonoxide Bool
lastupdated String
lowbattery Bool
tampered Bool
ZHAConsumption consumption Number
lastupdated String
power Number
ZHAFire fire Bool
lastupdated String
lowbattery Bool
tampered Bool
ZHAHumidity humidity Number
lastupdated String
ZHALightLevel lux Number
lastupdated String
lightlevel Number
dark Bool
daylight Bool
ZHAOpenClose open Bool
lastupdated String
ZHAPower current Number
lastupdated String
power Number
voltage Number
ZHAPresence presence Bool
lastupdated String
ZHASwitch buttonevent Number
lastupdated String
gesture Number
eventduration Number
x Number
y Number
angle Number
ZHAPressure pressure Number
lastupdated String
ZHATemperature temperature Number
lastupdated String
ZHATime lastset Time
lastupdated Time
localtime Time
utc Time
ZHAThermostat on Bool
errorcode
  • Introduced with deCONZ version 2.05.81
Bool
fanmode
  • Introduced with deCONZ version 2.05.85
String
lastupdated String
mountingmodeactive
  • Introduced with deCONZ version 2.05.81
Bool
temperature Number
valve Number
windowopen
  • Introduced with deCONZ version 2.05.79
String
ZHAVibration vibration Bool
lastupdated String
orientation_x Number
orientation_y Number
orientation_z Number
tiltangle Number
vibrationstrength Number
ZHAWater water Bool
lastupdated String
lowbattery Bool
tampered Bool

Example request data

    
{
    "config": {
        "on": true
        "reachable": true
    }
    "manufacturername": "Me"
    "modelid": "T1000"
    "name": "My Switch"
    "swversion": "1.0"
    "type": "CLIPSwitch"
    "uniqueid": "0x001fee00000008bb"
}

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 then an empty object {} will be returned.

Parameters

None

Response


HTTP/1.1 200 OK


{
    "1": {
        "config": {
            "on": true,
            "reachable": true
        },
        "ep": 1,
        "etag": "61eaee2477fc3d5c27932fefeef638bd",
        "manufacturername": "dresden elektronik",
        "modelid": "Lighting Switch",
        "name": "Lighting Switch 1",
        "state": {
            "lastupdated": "2016-07-06T09:39:53"
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "0x00212effff00a6bc"
    }
    "2": {
        "config": {
            "on": true,
            "reachable": true
        },
        "ep": 2,
        "etag": "61eaee2477fc3d5c27932fefeef638bd",
        "manufacturername": "dresden elektronik",
        "modelid": "Lighting Switch",
        "name": "Lighting Switch 2",
        "state": {
            "lastupdated": "2016-07-06T09:39:53"
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "0x00212effff00a6bc"
    }
}

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",
    "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": "0x00212effff00a6bc"
}

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.
manufacturername String The manufacturer name of the sensor.
modelid String The model id of the sensor.
mode Number (1|2|3) The mode of the sensor (Only available for dresden elektroink Lighting Switch).
  • 1 = Scenes mode
  • 2 = Two groups mode
  • 3 = Color temperature mode
name String The name of the sensor..
state Object The state of the sensor.
state.lastupdated String Timestamp when the sensor was last updated.
swversion String Software version of the sensor.
type String The type of the sensor.
uniqueid String The unique identifiers (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 (1|2|3) 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

FieldTypeDescriptionRequired
battery Number (1..100) The current battery state in percent, only for battery powered devices. optional
configured Bool NOT SETTABLE and exclusively for predefined daylight sensor. Determines if the sensor has been configured. optional
coolingsetpoint Number (700..3500) Set the desired cooling temperature for thermostats.
  • Introduced with deCONZ version 2.05.85
optional
delay Number (0..65535) optional
displayflipped Bool Flip the display for TRVs supporting it. optional
duration Number (0..65535) For ZHAPrensence sensors: time in seconds presence state is set to false again. optional
fanmode String Sets the mode of the fan (exposed for thermostats supporting it).
Generally supported values are: off, low, medium, high, on, auto, smart
(Supported modes are device dependent)
  • Introduced with deCONZ version 2.05.85
optional
groups Number NOT SETTABLE. Displays the groups associated with the sensor. Display only
heatingsetpoint Number (500..3200) Set the desired heating temperature for thermostats/TRVs. optional
hostflags Display only
lat Number NOT SETTABLE and exclusively for predefined daylight sensor. Latitude of the set location/timezone. Display only
ledindication Bool optional
localtime optional
locked Bool Child lock active/inactive for thermostats/TRVs supporting it.
  • Introduced with deCONZ version 2.05.81
optional
long Number NOT SETTABLE and exclusively for predefined daylight sensor. Longitude of the set location/timezone. Display only
mode String Sets the current operating mode of a thermostat.
Generally supported values are: off, auto, cool, heat, emergency heating, precooling, fan only, dry, sleep
(Supported modes are device dependent)

For ubisys S1/S2, operation mode of the switch.
Supported values are: momentary, rocker
optional
mountingmode Bool Sets a TRV into mounting mode if supported (valve fully open position).
  • Introduced with deCONZ version 2.05.81
optional
on Bool The on/off status of the sensor. optional
offset Number (-32768..32767) Adds a signed offset value to measured temperature and humidity state values. Values send by the REST API are already amended by the offset. optional
pending Number NOT SETTABLE. Bitmap of outstanding configuration tasks for a device. A value of "[]" indicates no outstanding tasks. Display only
preset String Sets the current operating mode for Tuya thermostats.
Generally supported values are: holiday, auto, manual, comfort, eco, boost, complex
(Supported modes are device dependent)
  • Introduced with deCONZ version 2.05.83
optional
reachable Bool The reachable status of the sensor. optional
schedule optional
scheduleon optional
sensitivity Number optional
sensitivitymax Number For Xiaomi vibration sensors, only following 3 values apply: low: 21, medium: 11, high: 1 optional
sunriseoffset Number (-120..120) NOT SETTABLE and exclusively for predefined daylight sensor. Sunrise offset value for location/timezone in minutes. Display only
sunsetoffset Number (-120..120) NOT SETTABLE and exclusively for predefined daylight sensor. Sunset offset value for location/timezone in minutes. Display only
temperature Number (-27315..32767) NOT SETTABLE. Reported temperature values by Xiaomi devices which are no temperature measuring devices (presumably device temperature). Display only
tholddark Number (0..65534) optional
tholdoffset Number (1..65534) optional
usertest Bool optional
windowcoveringtype Number (0..9) Sets the covering type and starts calibration for ubisys J1.
Supported values are:
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)
optional
windowopen_set Bool Sets if window open detection shall be active/inactive for Tuya thermostats.
(Support is device dependent)
  • Introduced with deCONZ version 2.05.83
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.

Parameters

Allowed sensor types and its states:

Sensor typeAllowed statetype
CLIPSwitch buttonevent Number
CLIPOpenClose open Bool
CLIPPresence presence Bool
CLIPTemperature temperature Number
CLIPGenericFlag flag Bool
CLIPGenericStatus status Number
CLIPHumidity humidity Number

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


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": "1"}]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found