HSYCO Remote API

The HSYCO Remote I/O Server uses a secure HTTPS API based on the REST (Representational state transfer) model and the JSON data format.

This API is simple to use, yet it allows a highly efficient mechanism for a client service to stay in synch with HSYCO internal I/O data points state. It is a bidirectional API, and can also be used to send I/O commands to the HSYCO Server.

A subset of this API can be used by any HTTP client application, provided it is enabled in HSYCO’s settings.

The public portion of the remote I/O API is documented in the following sections.

Other features of this API are reserved to the Remote I/O Server and should not be used for third-party applications.

The non-public portion of the API is subject to change between different versions of the HSYCO Server.

Reading I/O Data Points State

From a client having an IP address that is listed in the Remote Server settings RemoteServerAddress list, you can issue the following HTTPS GET request to the HSYCO Server:

https://<address>:<port>/x/rioget?1*<timestamp>*<password>

The password parameter must correspond to the RemoteServerPassword parameter in the Remote Server settings.

The timestamp parameter must be greater than 0 integer number.

The first request should have timestamp=1 to immediately retrieve the current state of all data points.

HSYCO will return a code 200 HTTP response, with a JSON body having the following format:

{"hsycostate":{
"timestamp":<timestamp>[,"system":"system"],"topotime":<topo timestamp>[,
"io":{"<data point name>": "<value>"[,"<data point name>": "<value>"]}]}}

Square brackets enclose sections that may not be present in the response.

timestamp will be the internal time of last change of a data point. The topotime data should be ignored when using the API from third-party applications.

The next request from the client should use the same timestamp number returned in the previous response. HSYCO will only return the data points that have changed since that timestamp.

HSYCO also supports a long-polling mechanism that allows clients to efficiently request state changes, also reducing the latency time of changes notifications.

If no data points have changed since the timestamp passed in the request, HSYCO will not return immediately, but wait up to 10 seconds before either returning a JSON response without the IO section, or the list of newly changed data points if changes occurred shortly after the request.

If the password is wrong or the client is not authorized for remote I/O, the HSYCO Server will drop the connection with no reply after a 10 seconds delay.

Examples

https://192.168.0.50/x/rioget?1*1*MyRemoteApiPassword

{"hsycostate":{
"timestamp":1403628628848000,"system":"system","topotime":1403171030000,
"io":{"office.temp.5.cooling.status":"0","office.temp.4.temp":"259" ... }}}

https://192.168.0.200/x/rioget?1*1403628628848000*MyRemoteApiPassword

{"hsycostate":{
"timestamp":1403628740123000,"system":"system","topotime":1403171030000,
"io":{"mbus.1.8199":"87","mbus.1.8196":"90645"}}}

https://192.168.0.200/x/rioget?1* 1403628740123000*MyRemoteApiPassword

{"hsycostate":{
"timestamp":1403628740123000,"system":"system","topotime":1403171030000}}

Sending I/O Commands

If RemoteServerControl is enabled in the Remote Server settings, a client could send I/O commands to the HSYCO Server via a simple HTTPS GET request with the following syntax:

https://<address>:<port>/x/rioset?io*<URL encoded data point name>*<URL encoded value>*<password>

If the request is accepted and the password valid, HSYCO Server will return a code 200 HTTP response, and a body text with just the “ack” string.

The data point name and value must be URL-encoded in the query string portion of the HTTP request.

Examples

https://192.168.0.50/x/rioset?io*m.light.89*0*MyRemoteApiPassword