Sensors

Sensors can be used to measure environment conditions like brightness, motion, temperature, humidity, switch button presses, etc. In combination with rules they can control lights, groups and virtual sensors — and therefore are the foundation of powerful automations.

The sensors endpoint supports virtual so called CLIP sensors as well as physical sensors. For a complete list of supported sensors and their specific details refer to the supported devices page.

All changes of the sensor attribues can be monitored in real-time with the Websocket endpoint.

Create sensor

Creates a new CLIP sensor which can be controlled by REST-API calls and rules.

Parameters

CLIP sensor types and their states

Create sensor example

The following request creates a new virtual CLIPSwitch sensor resource. It is possible to provide initial state values like here the buttonevent attribute will be initialized with 5 (default 0).

{
    "config": {
        "on": true,
        "reachable": true
    },
    "manufacturername": "My Company",
    "modelid": "SW1000",
    "name": "My Switch",
    "state": {
        "buttonevent": 5,
    },
    "swversion": "1.0",
    "type": "CLIPSwitch",
    "uniqueid": "0011223344556677"
}

Response

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

The returned id can be used to retreive and modify the state of the sensor with respective REST-API requests.

Possible errors

400 Bad Request

403 Forbidden

Get all Sensors

Returns all sensors in an object. If no sensors are registered an empty object {} will be returned.

Response

{
    "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",
            "buttonevent": 2001
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "00:12:4b:00:09:0d:94:76-01-1000"
    },
    "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",
            "buttonevent": 1001
        },
        "swversion": "1.0",
        "type": "ZHASwitch",
        "uniqueid": "00:0f:17:12:41:01:00:94-01-1000"
    }
}

Each sensor is included as key-value pair, where the key is the sensor id and the value is the sensor object as descripted in Get sensor.

Possible errors

403 Forbidden

Get sensor

Returns the sensor for a the given id or uniqueid.

Response

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

Response fields

For details about the state and config objects refer to the sensor specific Supported devices page.

Possible errors

403 Forbidden

404 Not Found

Search new sensors

Starts searching new sensors. While the search is active sensors and switches should be brought into pairing mode — most of the time this is achived by resetting the device according to its user manual. A ongoing search can be monitored with the Get new sensors call.

Response

[{
    "success": {
        "/sensors": "Searching for new devices",
        "/sensors/duration": 60
    }
}]

Possible errors

503 Service Unavailable

Get new sensors

Query results and progress of a sensors search.

Response

{
    "3": {
        "name": "Motion sensor 3"
    },
    "lastscan": "2018-08-15T11:24:15"
}

Response fields

If new sensors or switches are found they are listed with their id as key holding an object with the device name attribute.

Possible errors

503 Service Unavailable

Update sensor

Update the specified top level attributes of a sensor.

Parameters

Example request data

{
  "name": "Floor motion sensor"
}

Response

[{ "success": { "/sensors/1/name": "Floor motion sensor" } }]

Possible errors

400 Bad Request

403 Forbidden

Change sensor config

Update the sensor config with the specified parameters from the following table.

See a complete list of Supported devices and its states and config attributes.

Example request data

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

Response

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

Possible errors

400 Bad Request

403 Forbidden

Change sensor state

Update a CLIP sensor state with the specified parameters.

Parameters

See Allowed sensor types and its states

Example request data

{
  "flag": false
}

Response

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

Possible errors

400 Bad Request

403 Forbidden

Delete sensor

Delete a sensor.

Response

[{ "success": "1"}]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found