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.

note

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.1.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.1.50/x/rioget?1*1403628628848000*MyRemoteApiPassword

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

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

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

Reading Counter Data Loggers

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/riodlget?<data_logger_id>*<timestamp>*<password>

<data_logger_id> is the data logger id.

The timestamp parameter must be a not negative integer number. It represents a date and time formatted as yyyymmddhhmm00 (14 digits).

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

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

{"id":"<data_logger_id>","type":"counter","lastvalue":<last_value>,"lastvaluets":<last_value_timestamp>,
"values":[[<timestamp>,<delta_value>,<cost_value>,<locked>], ...]}

<last_value> is the last value recorded by the data logger. It is used by HSYCO, but is usually ignored by third-party applications.

<last_value_timestamp> is the UNIX epoch timestamp associated to the last value recorded by the data logger, and is also usually ignored by third party clients.

The values data block is a variable length array of 4 elements arrays. Each call returns up to 1000 records, in chronological order, starting from the oldest.

The timestamp of the oldest record returned is equal or grater than the timestamp passed in the query.

Each record is represented as a 4 elements array:

• <timestamp> is the record's timestamp, formatted as yyyymmddhhmm00
• <delta_value> is the total delta value (floating point, dot used as decimal separator) recorded in the time period for this record (based on the data logger's resolution)
• <cost_value> is the total cost value (floating point, dot used as decimal separator) recorded in the time period for this record
• <locked> is a boolean, represented as 1 for locked records, and 0 for unlocked records. A record is marked as locked when its cost value is permanently set, and will not change if the rates rules are changed in the future.

The first request should have timestamp=0 to retrieve data starting from the oldest record.

The following request from the client should use the same timestamp number returned in the last (most recent) values record from the previous response. HSYCO will only return data logger records equal or greater than the timestamp passed in the query.

note

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.1.50/x/riodlget?energy*0*MyRemoteApiPassword

{"id":"energy","type":"counter","lastvalue":330.0,"lastvaluets":1715944625674,"values":[[20240517130000,100.0,0.0,0],[20240517131600,20.0,0.0,0],[20240517131700,10.0,0.0,0]]}

https://192.168.1.50/x/riodlget?energy*20240517131700*MyRemoteApiPassword

{"id":"energy","type":"counter","lastvalue":330.0,"lastvaluets":1715944625674,"values":[[20240517131700,10.0,0.0,0]]}

Reading Range Data Loggers

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/riodlget?<data_logger_id>*<timestamp>*<password>

<data_logger_id> is the data logger id.

The timestamp parameter must be a not negative integer number. It represents a date and time formatted as yyyymmddhhmm00 (14 digits).

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

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

{"id":"<data_logger_id>","type":"range","lastvalue":<last_value>,"lastvaluets":<last_value_timestamp>,
"values":[[<timestamp>,<min_value>,<max_value>,<avg_value>,<number_of_values>], ...]}

<last_value> is the last value recorded by the data logger. It is used by HSYCO, but is usually ignored by third-party applications.

<last_value_timestamp> is the UNIX epoch timestamp associated to the last value recorded by the data logger, and is also usually ignored by third party clients.

The values data block is a variable length array of 5 elements arrays. Each call returns up to 1000 records, in chronological order, starting from the oldest.

The timestamp of the oldest record returned is equal or grater than the timestamp passed in the query.

Each record is represented as a 5 elements array:

<timestamp> is the record's timestamp, formatted as yyyymmddhhmm00 <min_value> is the minimum value (floating point, dot used as decimal separator) recorded in the time period for this record (based on the data logger's resolution) <max_value> is the maximum value (floating point, dot used as decimal separator) recorded in the time period for this record <avg_value> is the average value (floating point, dot used as decimal separator) recorded in the time period for this record <number_of_values> is a positive integer corresponding to the number of values recorded by the data logger in the time period for this record.

The first request should have timestamp=0 to retrieve data starting from the oldest record.

The following request from the client should use the same timestamp number returned in the last (most recent) values record from the previous response. HSYCO will only return data logger records equal or greater than the timestamp passed in the query.

note

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.1.50/x/riodlget?temperature*0*MyRemoteApiPassword

{"id":"temperature","type":"range","lastvalue":25.5,"lastvaluets":1715944625674,"values":[[20240517130000,20.0,24.0,22.0,5],[20240517131500,24.0,24.0,24.0,1],[20240517131600,25.0,25.0,25.0,1],[20240517131700,25.5,25.5,25.5,1]]}

https://192.168.1.50/x/riodlget?temperature*20240517131700*MyRemoteApiPassword

{"id":"temperature","type":"range","lastvalue":25.5,"lastvaluets":1715944625674,"values":[[20240517131700,25.5,25.5,25.5,1]]}

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.

note

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

Postman example

Open Postman and click the + icon

Paste the link above in the field (Make sure you have GET as a request)

Put here the time stamp

Click the "Send" button

You can read the server response in the lower box

Python example

This python code will send a request every minute extacting the datapoint change

import requests
import json
import time
import warnings

warnings.filterwarnings('ignore', message='Unverified HTTPS request')

def send_get_request(url):
    try:
        response = requests.get(url, verify=False)
        response.raise_for_status()
        return response.text
    except requests.exceptions.RequestException as e:
        print(f"Error sending GET request: {e}")
        return None

def parse_and_print_response(response_text):
    try:
        data = json.loads(response_text)
        hsycostate = data.get("hsycostate", {})

        # print formatted values
        print(f"Timestamp: {hsycostate.get('timestamp')}")
        print(f"System: {hsycostate.get('system')}")
        print("\n")

        io_data = hsycostate.get("io", {})
        if not io_data:
            print("No datapoint change detected.")
        else:
            for key, value in io_data.items():
                print(f"{key}: {value}")
                
        print("\n")
        print("Sending new request in 1 minute")
        print("\n")
    except json.JSONDecodeError as e:
        print(f"Error decoding JSON: {e}")

if __name__ == "__main__":
    base_url = "https://192.168.1.54/x/rioget?1*{}*ertgw4634tertgerterterg"

    while True:
        timestamp = int(time.time() * 1000000)  # Timestamp in microseconds
        url = base_url.format(timestamp)

        response_text = send_get_request(url)

        if response_text:
            parse_and_print_response(response_text)

        time.sleep(60)  # Wait 1 minute before the next request