Controller 2.0 API Documentation

The following document describes the Controller 2.0 API.

(1) Request panel identity list (since M6)
(2) Request panel UI layout by logical identity (since M6)
(3) Send a control command (since M6)
(4) Status request (since M6)
(5) Polling request (since M6)
(6) Group member RESTful service (since M6)

(1) Request panel identity list (since M6)

Request URL:
```
/rest/panels
```

Request Method: GET

Parameters: none

Sample Request Url:
- http://localhost:8080/controller/rest/panels

Output: xml format data

Sample Response:

 
<openremote>
  <panel id="xxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxx" name="father"/> <!-- 'name' is logical id -->
  <panel id="xxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxx" name="mother"/>
  <panel id="FF7BBE64-A2D3-57F4-856C-D0806CC8B4F7" name="me"/> <!-- use device id -->
</openremote>

Note

you should use the name attribute to request panel UI layout.
the id attribute is device id, it's reserved and not available for now.
the name attribute is the logical identity and easier for user to remember and input.

Errors:
- Error Code:426, panel.xml not found Error.
- Error Code:427, Invalid panel.xml Error.

Since: M6

(2) Request panel UI layout by logical identity (since M6)

Request URL:
```
/rest/panel/{panel_logical_identity}
```

Request Method: GET

Parameters: panel_logical_identity

Sample Request Url:

Output: xml format data

Sample Response:

 
<openremote xmlns="http://www.openremote.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.openremote.org http://www.openremote.org/schemas/controller.xsd">
	<screens>
		<screen id="5" name="basement" background="BG_paper_tileable_002.png">
			<gesture id="51" type="swipe-top-to-bottom" hasControlCommnad="true" />
			<gesture id="52" type="swipe-bottom-to-top" hasControlCommnad="true" />

			<grid left="20" top="20" width="300" height="400" rows="3" cols="3">
				<cell x="0" y="0" rowspan="1" colspan="1">
					<switch id="1">
						<image src="lamp_on.png" state="ON" />
						<image src="lamp_off.png" state="OFF" />
					</switch>
				</cell>
				<cell x="0" y="1" rowspan="1" colspan="1">
					<button id="60" name="B">
						<image src="icon_achievment.png" />
						<image src="icon_note.png" state="onPress" />
						<navigate toGroup="12" />
					</button>
				</cell>
				<cell x="1" y="0" colspan="1">
					<switch id="3">
						<image src="lamp_on.png" state="ON" />
						<image src="lamp_off.png" state="OFF" />
					</switch>
				</cell>
				<cell x="1" y="1">
					<button id="60" name="B">
						<image src="icon_calendar.png" />
						<image src="icon_note.png" state="onPress" />
						<navigate toGroup="11" toScreen="6" />
					</button>
				</cell>
				<cell x="2" y="0">
					<button id="60" name="back">
						<navigate toBack="true" />
					</button>
				</cell>
				<cell x="0" y="2">
					<button id="60" name="settings">
						<image src="icon_gear.png" />
						<navigate toSetting="true" />
					</button>
				</cell>
				<cell x="2" y="1">
					<button id="60" name="logout">
						<image src="icon_ganmeinfo.jpg" />
						<navigate toLogout="true" />
					</button>
				</cell>
				<cell x="1" y="2">
					<button id="60" name="previous">
						<navigate toPreviousScreen="true" />
					</button>
				</cell>
				<cell x="2" y="2">
					<button id="60" name="next">
						<navigate toNextScreen="true" />
					</button>
				</cell>
			</grid>
		</screen>
		<screen id="6" name="basement" background="BG_paper_tileable_002.png">
			<absolute left="20" top="20" width="50" height="50" >
				<button id="60" name="back">
					<navigate toBack="true" />
				</button>
                        </absolute>
			<absolute left="100" top="100" width="50" height="50" >	
				<button id="60" name="previous">
					<navigate toPreviousScreen="true" />
				</button>
                        </absolute>
                        <absolute left="150" top="100" width="50" height="50" >
				<button id="60" name="next">
					<navigate toNextScreen="true" />
				</button>
			</absolute>	
		</screen>
		<screen id="7" name="basement" background="BG_paper_tileable_002.png">
			<grid left="20" top="20" width="300" height="400" rows="3" cols="3">
				<cell x="2" y="0">
					<button id="60" name="back">
						<navigate toBack="true" />
					</button>
				</cell>
				<cell x="0" y="0" rowspan="1" colspan="1">
					<switch id="1">
						<image src="lamp_on.png" state="ON" />
						<image src="lamp_off.png" state="OFF" />
					</switch>
				</cell>
				<cell x="0" y="1" rowspan="1">
					<switch id="2">
						<image src="lamp_on.png" state="ON" />
						<image src="lamp_off.png" state="OFF" />
					</switch>
				</cell>

				<cell x="1" y="1">
					<button id="60" name="B">
						<image src="icon_calendar.png" />
						<image src="icon_note.png" state="onPress" />
						<navigate toScreen="5" />
					</button>
				</cell>
				<cell x="0" y="2">
					<button id="60" name="login">
						<navigate toLogin="true" />
					</button>
				</cell>
				<cell x="1" y="2">
					<button id="60" name="previous">
						<navigate toPreviousScreen="true" />
					</button>
				</cell>
				<cell x="2" y="2">
					<button id="60" name="next">
						<navigate toNextScreen="true" />
					</button>
				</cell>
			</grid>
		</screen>
	</screens>
	<groups>
		<group id="11" name="All rooms">
			<include type="screen" ref="5" />
			<include type="screen" ref="6" />
			<include type="screen" ref="7" />
		</group>
		<group id="12" name="All rooms">
			<include type="screen" ref="6" />
			<include type="screen" ref="7" />
		</group>
	</groups>
</openremote>

Errors:
- Error Code:426, panel.xml not found Error.
- Error Code:427, Invalid panel.xml Error.
- Error Code:428, No such panel identity Error.

Since: M6

(3) Send a control command (since M6)

Request URL:

/rest/control/{control_id}/{command_param}

Request Method: POST

Parameters:
- control_id : control id
- command_param :
  - Switch: ON/OFF
  - Slider: integer, e.g. 27
  - Button: click
  - Gesture: swipe

Sample Request Url:
- Switch: http://localhost:8080/controller/rest/control/1/ON
- Switch: http://localhost:8080/controller/rest/control/1/OFF
- Slider: http://localhost:8080/controller/rest/control/1/27
- Button: http://localhost:8080/controller/rest/control/1/click
- Gesture: http://localhost:8080/controller/rest/control/1/swipe

Output: HTTP response code.

Sample Response:
```
200(OK)
```

Errors:
- Error Code:418, Command Build Error. Happens when a Command can't be built from a DOM Element.
- Error Code:419, No Such Component Error.
- Error Code:420, No Such Command Builder Error.
- Error Code:422, controller.xml Not Found Error.
- Error Code:423, No Such Command Error.
- Error Code:424, Invalid controller.xml Error.
- Error Code:429, Invalid XML element Error.

Since: M6

(4) Status request (since M6)

Desc: This service will return result immediately.

Request URL:

/rest/status/{sensor_id},{sensor_id},...

Request Method: GET

Parameters: sensor_id list

Sample Request Url:
- http://localhost:8080/controller/rest/status/1
- http://localhost:8080/controller/rest/status/1,2

Output: xml formatted data.

Sample Response:

 
<openremote xsi:schemaLocation="">
    <status id="1">on</status>
    <status id="2">off</status>
</openremote>

Errors:
- Error Code:418, Command Build Error. Happens when a Command can't be built from a DOM Element.
- Error Code:419, No Such Component Error.
- Error Code:420, No Such Command Builder Error.
- Error Code:422, controller.xml Not Found Error.
- Error Code:423, No Such Command Error.
- Error Code:424, Invalid controller.xml Error.
- Error Code:429, Invalid XML element Error.

Since: M6

(5) Polling request (since M6)

Desc: This service will return result until the statuses of sensor_id list changed.

Request URL:

/rest/polling/{device_id}/{sensor_id},{sensor_id},...

Request Method: GET

Parameters: device_id(The unique id of device), sensor_id list.

Sample Request Url:
- http://localhost:8080/controller/rest/polling/96e79218965eb72c92a549dd5a330112/1
- http://localhost:8080/controller/rest/polling/96e79218965eb72c92a549dd5a330112/2,3

Output: xml formatted data.

Sample Response:

or

 
<openremote xsi:schemaLocation="">
    <status id="2">on</status>
    <status id="3">off</status>
</openremote>

Errors:
- Error Code:418, Command Build Error. Happens when a Command can't be built from a DOM Element.
- Error Code:419, No Such Component Error.
- Error Code:420, No Such Command Builder Error.
- Error Code:422, controller.xml Not Found Error.
- Error Code:423, No Such Command Error.
- Error Code:424, Invalid controller.xml Error.
- Error Code:429, Invalid XML element Error.

Since: M6

(6) Group member RESTful service (since M6)

Desc: This service will return all group members' url of current service provider.

Request URL:
```
/rest/servers
```

Request Method: GET

Sample Request Url:
- http://localhost:8080/controller/rest/servers

Output: xml formatted data.

Sample Response:

 
<?xml version="1.0" encoding="UTF-8"?>
<openremote xmlns="http://www.openremote.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <servers>
        <server url="http://192.168.1.100:8080/controller" />
        <server url="http://192.168.1.200:8080/controller" />
    </servers>
</openremote>

Errors:
- Error Code:450, Failed to start tcp server.
- Error Code:451, Failed to start udp server.
- Error Code:452, Failed to establish udp client.
- Error Code:453, Invalid groupmember service url.

Since: M6