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

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",

    }
   ]
  }
}

PUT /devices/{deviceId}/state

PUT /devices/{deviceId}/state