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 "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/'