Difference between revisions of "API2"

From Larnitech wiki page
Jump to navigation Jump to search
 
(4 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
API2 works via WebSocket connection, so you can interact with your Larnitech server from a browser using extensions (such as WebSocket Test Client).<br>
 
API2 works via WebSocket connection, so you can interact with your Larnitech server from a browser using extensions (such as WebSocket Test Client).<br>
 
To get started, you should:<br><br>
 
To get started, you should:<br><br>
−
1. Establish a web socket connection.<br>
+
1. Establish a web socket connection.<br> Locally
 
<syntaxhighlight lang="xml">
 
<syntaxhighlight lang="xml">
 
ws://IPADDR:PORT/api
 
ws://IPADDR:PORT/api
 
</syntaxhighlight>
 
</syntaxhighlight>
 
Where: IPADDR – ip address of your metaforsa or DE-MG;<br>
 
Where: IPADDR – ip address of your metaforsa or DE-MG;<br>
−
PORT – port for API2 (you can get it from LT_Setup =&gt; General =&gt; API =&gt; Websocket port (2041 by default);<br><br>
+
PORT – port for API2 (you can get it from LT_Setup =&gt; General =&gt; API =&gt; Websocket port (2041 by default); <br>
 +
Or use next for remote:
 +
<syntaxhighlight lang="xml">
 +
wss://SERIAL.in.larnitech.com:8443/api
 +
</syntaxhighlight>
 +
Where: SERIAL is serial number of your server, you can find it in LT_Setup =&gt; General <br><br>
 
2. Authorize
 
2. Authorize
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 22: Line 27:
 
Fields of JSON_REQUEST:
 
Fields of JSON_REQUEST:
 
<ul>
 
<ul>
−
  <li>"requestType" - Type of request:
+
  <li>"request" - Type of request:
 
<ul>
 
<ul>
−
  <li>“getDevicesList” – 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 45:
 
<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"
 +
}
 +
},
 +
{
 +
"addr":"33:200",
 +
"type":"climate-control",
 +
"name":"climate",
 +
"area":"Living room",
 +
"status":{
 +
"state":"on",
 +
"setpoint":23.0,
 +
"setpoint-heat":21.0,
 +
"setpoint-cool":25.0,
 +
"current-temperature":0.0,
 +
"pid-temperature":100,
 +
"current-humidity":0.0,
 +
"current-co2":0,
 +
"automation":"Comfort",
 +
"mode":"auto",
 +
"time-interval":0
 +
},
 +
"automations":[
 +
"Comfort"
 +
],
 +
"automation":"Comfort",
 +
"modes":[
 +
"heat",
 +
"cool"
 +
]
 +
},
 +
],
 +
"found":3
 
}
 
}
−
+
 
 
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"
+
}
 +
 
 +
request (set status for climate-control):
 +
{"request":"status-set","addr":"33:200", "status":{"state":"on","setpoint-heat":21.0}}
 +
 
 +
response:
 +
{
 +
"response":"status-set",
 +
"devices":[
 +
{
 +
"addr":"33:200",
 +
"success":true
 +
}
 +
]
 
}
 
}
 +
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 136: Line 184:
  
 
1. Use request to get detailed info about element with "status":"detailed"
 
1. Use request to get detailed info about element with "status":"detailed"
−
<syntaxhighlight lang="xml" line>
+
<syntaxhighlight lang="json" line>
 
curl --header 'Content-Type: application/json' --data '{"request":"status-get", "API-KEY":"ENTER_API_KEY", "addr":"585:17", "status":"detailed"}' 'http://de-mg.local/API2/'
 
curl --header 'Content-Type: application/json' --data '{"request":"status-get", "API-KEY":"ENTER_API_KEY", "addr":"585:17", "status":"detailed"}' 'http://de-mg.local/API2/'
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 143: Line 191:
  
 
2. Use request to set brightness for dimmer element
 
2. Use request to set brightness for dimmer element
−
<syntaxhighlight lang="xml" line>
+
<syntaxhighlight lang="json" line>
 
curl --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/'
 
curl --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/'
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 150: Line 198:
  
 
3. Use request to set color-temp for dimmer element
 
3. Use request to set color-temp for dimmer element
−
<syntaxhighlight lang="xml" line>
+
<syntaxhighlight lang="json" line>
 
curl --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/'
 
curl --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/'
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 10:15, 11 July 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.
Locally 

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);
Or use next for remote: 

wss://SERIAL.in.larnitech.com:8443/api

Where: SERIAL is serial number of your server, you can find it in LT_Setup => General

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			"addr":"33:200",
 28			"type":"climate-control",
 29			"name":"climate",
 30			"area":"Living room",
 31			"status":{
 32				"state":"on",
 33				"setpoint":23.0,
 34				"setpoint-heat":21.0,
 35				"setpoint-cool":25.0,
 36				"current-temperature":0.0,
 37				"pid-temperature":100,
 38				"current-humidity":0.0,
 39				"current-co2":0,
 40				"automation":"Comfort",
 41				"mode":"auto",
 42				"time-interval":0
 43			},
 44			"automations":[
 45				"Comfort"
 46			],
 47			"automation":"Comfort",
 48			"modes":[
 49				"heat",
 50				"cool"
 51			]
 52		},
 53		],
 54	"found":3
 55}
 56
 57request:
 58{"request":"status-get","addr":"158:240", "status":"detailed"}
 59response:
 60{
 61	"response":"status-get",
 62	"devices":[
 63		{
 64			"addr":"158:240",
 65			"type":"valve-heating",
 66			"status":{
 67				"state":"off"
 68			}
 69		}
 70	],
 71	"found":1
 72}
 73 
 74request:
 75{"request":"status-set","addr":"999:250", "status":{"state":"off"}}
 76 
 77response:
 78{
 79	"response":"status-set",
 80	"devices":[
 81		{
 82			"addr":"999:250",
 83			"success":true
 84		}
 85	]
 86}
 87 
 88request:
 89{"request":"status-subscribe","addr":"999:250"}
 90 
 91response:
 92{
 93	"response":"status-subscribe",
 94	"devices":[
 95		{
 96			"addr":"999:250",
 97			"status":"0x08"
 98		}
 99	],
100	"found":1,
101	"subscribed":1
102}
103 
104request:
105{"request":"status-set","addr":"999:250", "status":"0x01"}
106 
107response:
108{
109	"response":"status-set",
110	"devices":[
111		"999:250"
112	]
113}
114
115request (set status for climate-control):
116{"request":"status-set","addr":"33:200", "status":{"state":"on","setpoint-heat":21.0}}
117
118response:
119{
120	"response":"status-set",
121	"devices":[
122		{
123			"addr":"33:200",
124			"success":true
125		}
126	]
127}

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=20580"