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:

request:
{"request":"get-devices", "status":"detailed"}
 
response:
{
	"response":"get-devices",
	"devices":[
		{
			"addr":"158:21",
			"type":"ir-receiver",
			"name":"IR receiver",
			"area":"Setup",
			"status":{
				"state":"undefined"
			}
		},
		{
			"addr":"158:40",
			"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":"status-get","addr":"158:240", "status":"detailed"}
response:
{
	"response":"status-get",
	"devices":[
		{
			"addr":"158:240",
			"type":"valve-heating",
			"status":{
				"state":"off"
			}
		}
	],
	"found":1
}
 
request:
{"request":"status-set","addr":"999:250", "status":{"state":"off"}}
 
response:
{
	"response":"status-set",
	"devices":[
		{
			"addr":"999:250",
			"success":true
		}
	]
}
 
request:
{"request":"status-subscribe","addr":"999:250"}
 
response:
{
	"response":"status-subscribe",
	"devices":[
		{
			"addr":"999:250",
			"status":"0x08"
		}
	],
	"found":1,
	"subscribed":1
}
 
request:
{"request":"status-set","addr":"999:250", "status":"0x01"}
 
response:
{
	"response":"status-set",
	"devices":[
		"999:250"
	]
}

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
		}
	]
}

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