Difference between revisions of "API2"

From Larnitech wiki page
Jump to navigation Jump to search
(changes for actual websocket api)
Line 24: Line 24:
 
  <li>"request" - Type of request:
 
  <li>"request" - Type of request:
 
<ul>
 
<ul>
−
  <li>“getDevices” – request for getting the list of all devices;</li>
+
  <li>“get-devices” – request for getting the list of all devices;</li>
−
  <li>“getDeviceStatus” – request for getting device status;</li>
+
  <li>“status-get” – request for getting device status;</li>
−
  <li>“setDeviceStatus” – request for setting device status;</li>
+
  <li>“status-set” – request for setting device status;</li>
−
        <li>“setDeviceStatusRaw” – request for setting device status (status in hex format);</li>
+
<li>“status-subscribe” – request for subscribe events (WebSocket only)</li>
−
<li>“getAllDevicesStatus” – request for getting all devices status.</li>
 
 
        
 
        
 
</ul>
 
</ul>
Line 41: Line 40:
 
<syntaxhighlight lang="json" line>
 
<syntaxhighlight lang="json" line>
 
request:
 
request:
−
{"requestType":"getDevicesList","key":"ENTER_API_KEY"}
+
{"request":"get-devices", "status":"detailed"}
 
   
 
   
 
response:
 
response:
 
{
 
{
−
    "requestType":"devicesList",
+
"response":"get-devices",
−
    "devices": [
+
"devices":[
−
        {
+
{
−
            "type": "lamp",
+
"addr":"158:21",
−
            "name": "Ceiling",
+
"type":"ir-receiver",
−
            "addr":"401:1"
+
"name":"IR receiver",
−
        },
+
"area":"Setup",
−
                     
+
"status":{
−
        {
+
"state":"undefined"
−
            "type": "conditioner",
+
}
−
            "name": "AC",
+
},
−
            "addr":"158:200",
+
{
−
            "t-min":"16",
+
"addr":"158:40",
−
            "t-delta":"16"
+
"type":"com-port",
−
        }
+
"name":"RS232",
−
+
"area":"Setup",
−
        ]
+
"status":{
 +
"state":"undefined"
 +
}
 +
}
 +
],
 +
"found":2
 
}
 
}
−
+
 
 
request:
 
request:
−
{"requestType":"getDeviceStatus","addr":"310:1","key":"ENTER_API_KEY"}
+
{"request":"status-get","addr":"158:240", "status":"detailed"}
 
response:
 
response:
 
{
 
{
−
  "requestType" : "deviceStatus",
+
"response":"status-get",
−
  "status" : {
+
"devices":[
−
      "addr" : "310:1",
+
{
−
      "state" : "middle",
+
"addr":"158:240",
−
      "type" : "jalousie"
+
"type":"valve-heating",
−
  }
+
"status":{
 +
"state":"off"
 +
}
 +
}
 +
],
 +
"found":1
 
}
 
}
 
   
 
   
 
request:
 
request:
−
{"requestType":"setDeviceStatus","addr":"310:1","key":"ENTER_API_KEY","status":{"state": "on"}}
+
{"request":"status-set","addr":"999:250", "status":{"state":"off"}}
 
   
 
   
 
response:
 
response:
 
{
 
{
−
  "requestType":"setDeviceStatus",
+
"response":"status-set",
−
  "addr":"410:1",
+
"devices":[
−
  "status":{
+
{
−
    "state": "on"
+
"addr":"999:250",
−
  }
+
"success":true
−
 
+
}
 +
]
 
}
 
}
 
   
 
   
 
request:
 
request:
−
{"requestType":"getAllDevicesStatus","key":"ENTER_API_KEY"}
+
{"request":"status-subscribe","addr":"999:250"}
 
   
 
   
 
response:
 
response:
 
{
 
{
−
    "requestType":"allDevicesStatus",
+
"response":"status-subscribe",
−
    "statuses": [
+
"devices":[
−
      {
+
{
−
        "addr":"401:1",
+
"addr":"999:250",
−
        "state": "off",
+
"status":"0x08"
−
      },
+
}
−
     
+
],
−
      {
+
"found":1,
−
        "addr":"158:200",
+
"subscribed":1
−
        "state": "on",
 
−
        "temp":"25",
 
−
        "mode":"cool",
 
−
        "fan":"low",
 
−
        "vane-ver":"1",
 
−
        "vane-hor":"4"
 
−
      } 
 
−
        ]
 
 
}
 
}
 
   
 
   
 
request:
 
request:
−
{"requestType":"setDeviceStatusRaw","addr":"310:1","key":"0","status":{"state":"ff00"}}
+
{"request":"status-set","addr":"999:250", "status":"0x01"}
 
   
 
   
 
response:
 
response:
 
{
 
{
−
  "addr" : "310:1",
+
"response":"status-set",
−
  "key" : "0",
+
"devices":[
−
  "requestType" : "setDeviceStatusRaw",
+
"999:250"
−
  "status" : {
+
]
−
      "state" : "ff00"
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>

Revision as of 12:01, 23 June 2025

API2 works via WebSocket connection, so you can interact with your Larnitech server from a browser using extensions (such as WebSocket Test Client).
To get started, you should:

1. Establish a web socket connection.

ws://IPADDR:PORT/api

Where: IPADDR – ip address of your metaforsa or DE-MG;
PORT – port for API2 (you can get it from LT_Setup => General => API => Websocket port (2041 by default);

2. Authorize 

{
    "request": "authorize",
    "key": "XXXXXXXXXXXXXXX"
}

Where XXXXXXXXXXXXXXX - key from LT_Setup => Security => Show API key

3.After this you can send json requests:

Fields of JSON_REQUEST:

  • "request" - Type of request:
    • “get-devices” – request for getting the list of all devices;
    • “status-get” – request for getting device status;
    • “status-set” – request for setting device status;
    • “status-subscribe” – request for subscribe events (WebSocket only)
  • “key” – key for API plugin (you can get it from LT Setup=>Plugins=>API=>Configure button).
  • “addr” – address of device.
  • “status” – status of device.

Examples of requests and responses: 

 1request:
 2{"request":"get-devices", "status":"detailed"}
 3 
 4response:
 5{
 6	"response":"get-devices",
 7	"devices":[
 8		{
 9			"addr":"158:21",
10			"type":"ir-receiver",
11			"name":"IR receiver",
12			"area":"Setup",
13			"status":{
14				"state":"undefined"
15			}
16		},
17		{
18			"addr":"158:40",
19			"type":"com-port",
20			"name":"RS232",
21			"area":"Setup",
22			"status":{
23				"state":"undefined"
24			}
25		}
26		],
27	"found":2
28}
29
30request:
31{"request":"status-get","addr":"158:240", "status":"detailed"}
32response:
33{
34	"response":"status-get",
35	"devices":[
36		{
37			"addr":"158:240",
38			"type":"valve-heating",
39			"status":{
40				"state":"off"
41			}
42		}
43	],
44	"found":1
45}
46 
47request:
48{"request":"status-set","addr":"999:250", "status":{"state":"off"}}
49 
50response:
51{
52	"response":"status-set",
53	"devices":[
54		{
55			"addr":"999:250",
56			"success":true
57		}
58	]
59}
60 
61request:
62{"request":"status-subscribe","addr":"999:250"}
63 
64response:
65{
66	"response":"status-subscribe",
67	"devices":[
68		{
69			"addr":"999:250",
70			"status":"0x08"
71		}
72	],
73	"found":1,
74	"subscribed":1
75}
76 
77request:
78{"request":"status-set","addr":"999:250", "status":"0x01"}
79 
80response:
81{
82	"response":"status-set",
83	"devices":[
84		"999:250"
85	]
86}

CURL

1<item addr="585:16" auto-period="1" cfgid="4" name="color-temp dimmer" type="dimer-lamp"/>
2<item addr="585:17" name="main dimmer" type="dimer-lamp" auto-period="600" color-temp="585:16"/>

1. Use request to get detailed info about element with "status":"detailed" 

1curl --header 'Content-Type: application/json' --data '{"request":"status-get", "API-KEY":"ENTER_API_KEY", "addr":"585:17", "status":"detailed"}' 'http://de-mg.local/API2/'


2. Use request to set brightness for dimmer element 

1curl --header 'Content-Type: application/json' --data '{"request":"status-set","API-KEY":"ENTER_API_KEY", "addr":"585:17", "status":{"level":10}}' 'http://de-mg.local/API2/'


3. Use request to set color-temp for dimmer element 

1curl --header 'Content-Type: application/json' --data '{"request":"status-set","API-KEY":"ENTER_API_KEY","addr":"585:17", "status":{"color-temp":100}}' 'http://de-mg.local/API2/'


Retrieved from "https://wiki.larnitech.com/index.php?title=API2&oldid=20578"