|
<< Click to Display Table of Contents >> Navigation: The API > JSON Adminstrator API > REST Resources > Devices > POST > POST /devices/{deviceId} |
Overview
If you want to learn-in a device completely via API, be aware of:
•It probably makes only sense for unidirectional sensors
•If you want to learn-in bidirectional actuators, you will have to coordinate the Learn-in telegram that needs to be transmitted to the device by hand.
Client to Gateway:
Resource Path |
HTTP method |
/devices/{deviceId} |
POST |
POST body:
parameter |
datatype |
value / formatting |
Required |
Read/Write |
description |
||
device |
object |
{} |
|
|
|
||
|
deviceId |
string |
4 byte hex value |
Yes |
Write |
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. |
|
|
friendlyId |
string |
alphanumeric, hyphen and underscore |
Yes |
Write |
user-assigned name of EnOcean device |
|
|
physicalDevice |
string |
|
No |
Write |
User-assigned name to group actuators and sensors. |
|
|
learnInProcedure |
string |
manuallyConfigured | UTE | SmartAck | UserInteractionRequired | receivedRps | received1Bs | received4Bs | incompleteEep | internetOfThings |
|
Write |
Device should be set to manuallyConfigured |
|
|
eeps |
array of objects |
[{}] |
|
|
|
|
|
|
eep |
string |
xx-xx-xx |
Yes |
Write |
EnOcean Equipment Profiles, definition of Enocean radio telegram structure |
|
|
version |
float |
|
No |
Write |
Version of the API Commands |
|
|
direction |
string |
from | to | both |
Yes |
Write |
"from", "to" or "both" |
|
|
variation |
string |
manufacturer _ productname |
No |
Write |
Manufacturer specific variation |
|
|
|
|
|
|
|
|
|
firstSeen |
string |
yyyy-mm-ddT hh:mm:ss.sss+ hhmm |
No |
Read only |
timestamp on which the device has been detected for the first time |
|
|
lastSeen |
string |
yyyy-mm-ddT hh:mm:ss.sss+ hhmm |
No |
Read only |
timestamp on which the device has been detected for the last time |
|
|
secured |
boolean |
false |
No |
Read only |
Device using Security over air (Not supported at the moment) |
|
|
manufacturer |
string |
|
No |
Write |
Manufacturer of the device. |
|
|
softSmartAck |
boolean |
true | false |
No |
Write |
Device using Soft Smart-Ack |
|
|
transmitModes |
array of objects |
[{}] |
|
|
|
|
|
|
key |
string |
|
Yes |
Write |
Key of the profile |
|
|
transmitOnConnect |
boolean |
|
Yes |
Write |
True/False |
|
|
transmitOnEvent |
boolean |
|
Yes |
Write |
True/False |
|
|
transmitOnDuplicate |
boolean |
|
Yes |
Write |
True/False |
|
states |
array of objects |
[{}] |
|
Read only |
|
|
|
|
key |
string |
|
|
Read only |
Technical key of function. |
|
|
channel (optional) |
integer |
|
|
Read only |
Channel if supported by this device. |
|
|
value |
float |
|
|
Read only |
Value of the function. |
|
|
unit (optional) |
string |
[unit] |
|
Read only |
Unit ISO. |
|
|
meaning (optional) |
string |
|
|
Read only |
Description of value in English. |
|
|
timestamp |
string |
yyyy-mm-ddT hh:mm:ss.sss+ hhmm |
|
Read only |
Timestamp function value was received in case of last state functions. |
|
|
age |
integer |
|
|
Read only |
Age of function value in case of last state functions in milli seconds. |
|
operable |
boolean |
true | false |
Yes |
Write |
Shows if the device is operable respectively the learn in procedure has been completed. |
|
|
supported |
boolean |
true | false |
No |
Read Only |
Shows if the device is supported as of the profile |
|
example 1:
This first example shows a post request to store the device in the database with all required properties.
POST a new device to the database
POST /devices/FFF26803 |
{ "device" : { "deviceId" : "FFF26803", "friendlyId" : "Peha_Ch2", "learnInProcedure" : "manuallyConfigured", "eeps" : [ { "eep" : "D2-01-08", "version" : 1.0, "direction" : "both" } ], "manufacturer" : "Peha", "firstSeen" : "2016-05-09T09:27:05.260+0200", "lastSeen" : "2016-05-09T16:46:30.822+0200", "secured" : false, "softSmartAck" : false, "transmitModes" : [ { "key" : "overcurrentSwitchOff", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true }, { "key" : "power", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true }, { "key" : "localControl", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true }, { "key" : "energy", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true }, { "key" : "errorLevel", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true }, { "key" : "switch", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : true } ], "operable" : true, "supported" : true } } |
example 2:
This example shows also how to set up a Post request to learn in a device. But in this case it is shown that we can use many properties from the JSON we received earlier during streaming. That requires the gateway to be in learn in mode while the device sends a learn in telegram.Equivalent information can be retrieved on this resource:
/devices/newDevice=true.
GET /devices/stream |
(...)
{
(...) |
|
Attach a friendlyId and set operable to true. |
POST /devices/019724DB |
{ "header" : { "content" : "devices" }, "devices" : [ { "deviceId" : "019724DB", "friendlyId" : "OFIPostTest", "learnInProcedure" : "UTE", "eep" : "D2-01-09", "manufacturer" : "permundo GmbH", "firstSeen" : "2015-12-15T14:54:30.058+0100", "secured" : false, "softSmartAck" : false, "transmitModes" : [ { "key" : "overcurrentSwitchOff", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false }, { "key" : "dimValue", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false }, { "key" : "power", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false }, { "key" : "localControl", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false }, { "key" : "errorLevel", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false }, { "key" : "energy", "transmitOnConnect" : true, "transmitOnEvent" : true, "transmitOnDuplicate" : false } ], "states" : [ ], "operable" : true, "supported" : true } ] } |