PUT /devices/{deviceId}/state

<< Click to Display Table of Contents >>

Navigation:  The API > JSON API > REST Resources > Devices > PUT >

PUT /devices/{deviceId}/state

Overview

 

Change a state of a single device

 

Client to Gateway:

URL

call method

/devices/{deviceId}/state

PUT

necessary additional call parameters:

parameter

values

call option

functionality

deviceId

deviceID | friendlyId

required

SenderID of Enocean device, EnOcean modules usually send telegrams with their unique 32-bit Chip ID. In the other case, these are the Base ID of the EnOcean device.

+ additionally in  json notation (Call Body):

parameter

datatype

value / formatting

description

state

object

{}

 

 

functions

array of objects

[{}]

 

 

key

string

 

Technical key of function.

 

channel
(optional)

integer


Channel if supported by this device.

 

value

float 


Value of the function.

 

All functions of a functionGroup have to be set in one PUT-request. For many functions default values have been introduced. That means, if you don't set a function and a default value is available, the gateway will auto-complete the telegram with associated default values.

The function group described in the profile, must have the attribute “direction” : “to” or “direction”: “both”.

If the request is incomplete the gateways responses with error code 3010 and message "incomplete request - function(s) missing: XYZ,ABC".

If several function groups exist for a device, the gateway searches for  the corresponding one depending on the functions send. If this fails, the gateway responses with error code 3011: " no matching group found”.

 

Response Gateway to Client:

parameter

datatype

 

 

header

message header

 

httpStatus

integer

 

HTTP state code (200 = OK), otherwise refer to eMSG

 

gateway

string

 

current firmware version

 

timestamp

string

yyyy-mm-ddT hh:mm:ss.sss+ hhmm

transmission time in UTC format

 

Response Gateway to Client (in case of error):

parameter

datatype

 

 

header

message header

 

httpStatus

integer

e.g. 400

HTTP state code (200 = OK), otherwise refer to eMSG

 

code

integer

e.g. 3011

error number

 

message

string

e.g. "no matching group found"

 

 

gateway

string

e.g. DC-GW/EO-IP v0.99.1

current firmware version

 

timestamp

string

yyyy-mm-ddT hh:mm:ss.sss+ hhmm

transmission time in UTC format

 

example:

Basic structure of outgoing message(s) based on d2-01-08:

 

"Actuator Set Output"

 

PUT http://hostname:api_port/devices/switchActuator/state
 
{
  "state" : {
    "functions" : [ 
    {
      "key" : "switch",
      "value" : "on"
    }
   ]
  } 
}

 

 

 

"Configure Actuator"

 

PUT http://hostname:api_port/devices/switchActuator/state

 

{
  "state" : {
    "functions" : [ 
    {
      "key" : "defaultState",

      "value": "previousState",

    },

    {
      "key" : "localControl",

      "value": "off",

    },

    {
      "key" : "overcurrentSwitchOffMode",

      "value": "staticOff",

    },

    {
      "key" : "overcurrentSwitchOffReset",

      "value": "false",

    },

    {
      "key" : "taughtInDevices",

      "value": "on",

    },

    {
      "key" : "userInterfaceIndication",

      "value": "day",

    }
   ]
  } 
}

Simplified "Configure Actuator" command due to default values. The same result we would get with a http-request:

"Configure Actuator"

 

PUT http://hostname:api_port/devices/switchActuator/state

 

{
  "state" : {
    "functions" : [ 
    {
      "key" : "localControl",

      "value": "off",

    }
   ]
  } 
}