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
ZHASwitch buttonevent Number
ZHALight lux Number
ZHAPresence presence 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.
config.on Bool Specifies if the sensor is on or off.
config.reachable Bool Specifies if the sensor is reachable.
config.battery Number (0..100) The battery status of the sensor.
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.

Parameters

FieldTypeDescriptionRequired
on Bool The on/off status of the sensor. optional
reachable Bool The reachable status of the sensor. optional
battery Number (1..100) The current battery state in percent, only for battery powered devices. 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

None

Response


HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"


[{ "success": "1"}]

Possible errors

400 Bad Request

403 Forbidden

404 Not Found