Home
A CLAGE Home Server creates the conditions for integrating CLAGE instantaneous water heaters into an IP network. This enables the devices to be controlled and configured and operating data to be queried regardless of location.
As a separate device, the original Home Server implemented the wireless protocol for direct communication with compatible devices as well as the application interface described below.
In the meantime, the interface provided by the former server has become an integral part of selected devices that supports WLAN.
Communication with external applications is handled via a REST-based API using HyperText Transfer Protocol. Preferably, access should be encrypted via HTTPS. The server provides this functionality via the standard port 443 (without encryption/HTTP: port 80).
Unless otherwise stated, responses from the server are generally delivered with the content type application/json as a text-based JSON data structure.
The Server can be reached under any IPv4 address, default URI:
https://192.168.204.204
Simple detection of home servers in the LAN is carried out via DNS Service Discovery (DNS-SD):
-
Available servers report with service type
_clage-hs._tcp, IP address and the port used (default 443). HTTPS is always expected on the port announced via this procedure.
The server provides the supported services (resources or endpoints) and the API version used.
An application must be able to derive the data format for communication and other, possibly hidden or not yet existing resources for further use.
"services": [
{"deviceList":"/devices"},
{"deviceStatus":"/devices/status"},
{"deviceSetpoint":"/devices/setpoint"},
{"deviceLogs":"/devices/logs"}
]
Building the URI for deviceStatus from the above services array (using the default URI):
https://192.168.204.204/devices/status
Note on the evaluation of a JSON response:
An application should only evaluate the keys version, error, time and the array/object that contains the requested data (e.g. services or devices).
The use of the keys cached, success and total is not recommended, as these are reserved for internal purposes and could be changed at any time.
If an optional or internal key is not available, this must not lead to a malfunction of the application.
The server object is also delivered under the main URI. This contains, inter alia, the unique server ID (id) and the name of the server (name). As no authentication is required for this URI, an application can distinguish new servers from known servers when performing a server search (DNS-SD). The server object is permitted in every response.
Access to the services and resources provided is only possible after appropriate authentication via a user name and password on the home server. This is done for each request using HTTP Basic Authentication in accordance with RFC2617. A valid account in the home server is required for the user used.
- The client performs a
GETrequest to the main URI of the server. - The server responds with a JSON object containing the array of
services. - The client must include the Basic Authentication Header on each request (if deviating from the main URI).
- The client performs a
GETrequest to URI ofdeviceList. - The client detects new devices and allows an initial setup.
- The client requests
deviceListusing HTTP long polling to detect changes of device status. - Then, a more detailed device status can be queried via the
deviceStatusresource (see 4.2). A minimum poll interval of 1 second is permitted here in order to be able to display the power consumption and water flow rate without noticeable delays. A short poll interval should only be used if the device in question is actually in operation (heating on, water flowing, see also “5.10 flags”) and the values are required for visualization in the application. - The setpoint temperature of a device can be written at any time via the
deviceSetpointresource (see 4.3 and 4.4). Thestatusobject is returned in the response. Setpoint changes that occur in very quick succession (e.g. generated via sliders) must not be transmitted individually. Only after an appropriate timeout (e.g. 2 s) should the request be sent with the last selected setpoint value.
The server supports the use of HTTP Long Polling (based on RFC6202) for the resources deviceList and deviceLogs.
Assuming the following request:
GET https://192.168.204.204/devices?lp=1
In this example, the server only delivers the response to the client when the status changes. The connection therefore remains open until a response has been sent, the client terminates it or a timeout occurs.
The value of the lp parameter must correspond to the return value of the global revision counter rev of the previous query. Initially, the value 1 should be used.
For maximum compatibility and reliability, the server ends a request after 30 seconds with a regular response, even if no changes have occurred. If an event occurs beforehand, the response is delivered as a JSON object, as in Short Poll mode, or in the event of an error, only a corresponding HTTP error code is delivered.
To record further changes, the client repeats the requests cyclically (with an updated value for lp) as soon as the previous request has been answered and waits until the next event or timeout. If rev is changed, the client is responsible for determining and evaluating the changed objects. If the server has still not delivered a response after 60 seconds, the client must end the request itself. Parallel long polling requests to the same resource are not permitted.
A detailed specification of all resources and data objects is available as an OpenAPI v3.0 document:
For convenience reasons, an HTML version is also available:
- CLAGE_REST_API_v1.4.html
- First download the HTML file. Then you can open the document in your browser locally.
The HTML document was created using redocly:
redocly build-docs CLAGE_REST_API_v1.4.yaml --disableGoogleFont -o CLAGE_REST_API_v1.4.html
Please note, that it will need to load some data from cdn.redoc.ly to function properly.
You can directly load this specification into the online Swagger Editor and try out some requests to an existing server implementing the CLAGE REST API:
- Swagger Editor with CLAGE REST API
- Simply adapt the URL of Default in the
serverssection to your needs.