API2

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