Introduction

Welcome to the RESET API V2.1 for Data Providers. RESET API V2 went live in 2021. If you are looking for V1.0, please click here.

RESET Accredited Data Provider refers to the RESET authorized partner to provide data as a data provider. Learn more about the RESET Data Providers Accreditation process by clicking here or check out the RESET Data Providers Directory for a list of all RESET Accredited Data Providers.

RESET uses sockets a two-way communication mechanism that meets the needs of Data Providers for pushing monitor updates and monitor reading data required by RESET. RESET uses Socket.IO as its socket server. Data Providers can choose their choice of socket client when creating the socket connection with RESET. Data providers will communicate with RESET through Socket.IO to provide data. After the socket is connected, different events are used to complete the set up and data push capabilities.

The following webpage will explain the role of each API event, the specific parameters, and provide examples. If you encounter an API that does not match the document or if there is any part of the document that we can clarify, please do not hesitate to email our team at info@reset.build.

Version Changes

From V2.0 to V2.1

• Introduced the following Modules: Water, Energy, and Circularity.
• Introduced Channels for Water, Energy, and Circularity monitors.

From V1.0 to V2.0

• V2.0's SOCKET_SERVER_URL updated to https://reset.build:8069/v2.
• Officially uses temperature as temp and humidity as rh. V1.0 used temperature and humidity.
• Monitoring Stations are now referred to as Monitors, which is more accurate for what RESET wants as data. All mentions of 'stations' is now 'monitors'.
• Monitors (was Monitoring Stations in V1.0) now includes indicator units that can be set and updated per monitor.
• All response events will include "api_version": "v2".
• A monitor must be created first before data can be pushed.

Technology Stack

Below are the recommended technology stack considerations for different languages.

• Currently, RESET Socket API is using Socket.IO v4 (specifically, we are currently using v4.1.2), Here is the compatibility information.
• If you are using a Javascript Socket.IO client, we recommend the use of v4. Check the compatibility by clicking here .
• If your are using a Java Socket.IO client, we recommend the use of version 2.x. Check the compatibility by clicking here.
• If your are using a Python Socket.IO client, we recommend the use of version 5.x. Check the compatibility by clicking here.
• If you are using any other language, please check to see if it will work as we have not tested them ourselves.

Tools and Links

• RESET Data Provider Management: RESET provides data providers with an interface to check what data is being pushed to the RESET Cloud. Developers can log in to to view the latest data uploads and also see their client_id and client_secret.
• Sample Socket Code: Sample socket code (on Github).
• Socket Tester: A socket messaging testing interface.
• RESET Data Providers Accreditation Process: Instructions on how to apply to become a RESET Accredited Data Provider.
• RESET Data Providers Directory: List of all RESET Accredited Data Providers.
• Socket.IO: Learn more about Socket.io.

Initial Setup

Data Providers need to acquire a client_id and client_secret to establish a socket connection with the RESET Cloud. Without it, the socket connnection will automatically close. To get access to your client_id and client_secret, please log into your RESET Data Provider Management Page.

Authentication credentials are given to data providers who are getting accredited. If you do not have one yet, please email our team at info@reset.build for more information.

Setting up the Socket Connection

Sample code for creating a socket connection:

// Use the client and server URL to establish Socket Connection
const Client = require('socket.io-client');
socket = Client(SOCKET_SERVER_URL, { jsonp: false });
// Remember to change SOCKET_SERVER_URL to the server url

// Monitor server connection status
socket.on('connect_error', (err) => {
  console.log(err);
  throw 'Socket connection damaged, please check';
});

Confirm that 'SOCKET_SERVER_URL' is changed to point to the correct socket server address: https://reset.build:8069/v2

Setting up the socket connection consists of requiring the socket.io client and pointing to the SOCKET_SERVER_URL. It is recommended to have code for detecting connection error.

When setting this, please make sure that SOCKET_SERVER_URL is pointed to the updated correct socket server address for v2.0: https://reset.build:8069/v2.

Authentication

Sample code for vertification:

// You must use your own client_id and client_secret in the auth event
socket.emit('auth', {
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET",
});

// The return value will be transmitted by the `auth` event
socket.on('auth', (data) => {
  console.log(data);
});

Please confirm that YOUR_CLIENT_ID,YOUR_CLIENT_SECRET are replaced by the corresponding parameters

A successful authentication for the auth event will return the following JSON:

{
  "code": "10200",
  "message": "Authentication succeeded.",
  "api_version": "v2"
}

A failed authentication for the auth event will return the following JSON:

{
  "code": "10401",
  "message": "Authentication failed."
  "api_version": "v2"
}

Use the auth event to authenticate. The parameters need to include the correct client_id and client_secret to establish a stable socket connection.

If the authentication via the auth event is successful, the server will return a JSON with the code, 10200. If the client_id or client_secret parameters are missing or if there is a parameter mismatch, the auth event will fail and return an error with the code, 10401.

Once successfully authenticated, we recommend maintaining the socket connection until all the monitors and readings events planned this session are completed.

Event - Monitors

Monitors is the general term for a monitor in the RESET Cloud.

Monitor information is updated via the monitors event. There are two monitors events:

• Create (create a new monitor in the RESET Cloud)
• Modify (update information about a monitor)

Each event needs to contain a unique message_id parameter for communication and debugging purposes. For message_id, we recommend using epoch time in some way to make sure they are always unique.

For each event message emitted, RESET will verify the structure and validity of the data. The verification is successful if the ack event is returned and if the verification fails, the error message is returned via the errors event.

Monitors - Create

Sample code for creating a Air monitor:

socket.emit('monitors', {
  "message_type": "create",
  "message_id": "<MESSAGE_ID>",
  "data":{
    "label": "<LABEL>", // optional
    "connection_id": "<CONNECTION_ID>",
    "module": "air", 
    "meta": {
      "monitor_detail": {
        "monitor_brand":"<MONITOR_BRAND>",
        "monitor_sku":"<MONITOR_SKU>",
        "monitor_serial_id":"<MONITOR_ID>",
        "last_monitor_calibration_date":"<LAST_CALIBRATION_DATE>" // last_monitor_calibration_date is optional
      },
      "included_parameters": {
        "pm2p5": {
          "unit": "ug/m3"
        },
        "tvoc": {
          "unit": "ppb"
        },
        "co2": {
          "unit": "ppm"
        },
        "temp": {
          "unit": "C"
        },
        "rh": {
          "unit": "%RH"
        }
      }
    }
  }
});

Examples for Variables above:
- MESSAGE_ID: mi_1662109200000 (some var, maybe name of Data Provider, with epoch time in milliseconds. Make sure that each MESSAGE_ID is unique.)
- LABEL: 3rd Floor Office (Monitor label to more easily reference this monitor when comparing between the RESET Cloud and the Data Provider.)
- CONNECTION_ID: GA_23682013 (the Data Provider ID used to reference this monitor. Often the same as the Monitor ID below.) - MONITOR_BRAND: GIGA (Assuming that the brand of this monitor is called GIGA)
- MONITOR_SKU: AirM3 (the SKU used to reference this monitor)
- MONITOR_ID: GA_23682013 (the unique serial ID that represents this monitor)
- LAST_CALIBRATION_DATE: 2022-08-01T00:00:00+08:00 (if applicable, the time when the monitor was last calibrated.)

socket.on('errors', (data) => {
  console.log(data);
});

socket.on('ack', (data) => {
  console.log(data);
});

The data is validated via the ack event. Returns the following JSON:

{
  "code": "10200",
  "ack": true,
  "message_id": "<MESSAGE_ID>",
  "api_version": "v2"
 }

Sample code for creating an Energy monitor with two channels:

socket.emit('monitors', {
  "message_type": "create",
  "message_id": "<MESSAGE_ID>",
  "data":{
    "label": "<LABEL>",
    "connection_id": "<CONNECTION_ID>",
    "module": "energy",
    "meta": {
      "monitor_detail": {
        "monitor_brand": "<MONITOR_BRAND>",
        "monitor_sku":"<MONITOR_SKU>",
        "monitor_serial_id":"<MONITOR_ID>",
        "last_monitor_calibration_date":"<LAST_CALIBRATION_DATE>"
      },
      "included_parameters": {
        "power_consumption": {
          "unit": "kWh"
        }
      }
    },
    // all energy, water, and circularity monitors will
    // need at least one channel.
    "channels": [
      {
        "channel_id": "<CHANNEL_ID_1>",
        "channel_label": "<CHANNEL_LABEL_1>" // optional
      },
      {
        "channel_id": "<CHANNEL_ID_2>",
        // if there is no label, no need to include
      }
    ]
  }
});

Examples for Variables above:
- CHANNEL_ID_1: c01 (the Data Provider ID used to reference this data channel from this monitor. Could be something very short, needs to be unique for this CONNECTION_ID.)
- CHANNEL_LABEL_1: 1st_floor_plug_load (optional label for CHANNEL_ID_1.)
- CHANNEL_ID_2: c02 (the Data Provider ID used to reference this data channel from this monitor. Must be unique for this CONNECTION_ID.)

A new monitor with a unique connection_id will be created in the RESET Cloud.

Event Name: monitors

Parameter: data

A wrapper for all the data pertaining to the monitor.

Parameter: channels

Channels is a new parameter relevant for the Water, Energy, and Circularity modules. Do not include if the module is Air.

Channels exist because it is possible for a monitor to measure multiple iterations of the same parameter. For example, an Energy monitor might handle power consumption monitoring for 5 separate meters. Each of these meters would be considered an individual channel.

If there is only one reading, then the monitor would only have one channel.

Parameter: meta

Specific monitor information pertaining to its brand and make and the parameters it measures.

Parameter: monitor_detail

A wrapper for monitor information pertaining to its brand and make.

Parameter: included_parameters

A wrapper for monitor information pertaining to the parameters it measures. Include only the parameters that the monitor is monitoring and reporting.

For air module

For water module:

For energy module:

For circularity module:

Monitors - Modify

Sample code for updating a monitor:

socket.emit('monitors', {
  "message_type": "modify",
  "message_id": "<MESSAGE_ID>",
  "data":{
    "label": "<LABEL>",
    "connection_id": "<CONNECTION_ID>",
    // note that modify does not have 'module'
    "meta": {
      "monitor_detail": {
        "monitor_brand": "<MONITOR_BRAND>",
        "monitor_sku":"<MONITOR_SKU>",
        "monitor_serial_id":"<MONITOR_ID>",
        "last_monitor_calibration_date":"<LAST_CALIBRATION_DATE>"
      },
      "included_parameters": {
        "pm2p5": {
          "unit": "ug/m3"
        },
        "tvoc": {
          "unit": "ppb"
        },
        "co2": {
          "unit": "ppm"
        },
        "temp": {
          "unit": "C"
        },
        "rh": {
          "unit": "%RH"
        }
      }
    }
  }
});

socket.on('errors', (data) => {
  console.log(data);
});

socket.on('ack', (data) => {
  console.log(data);
});

A successful authentication for the auth event will return the following JSON:

{
  "code": "10200",
  "ack": true,
  "message_id": "<MESSAGE_ID>",
  "api_version": "v2"
 }

Update Monitors is used to inform RESET of updates to the monitor information. The main scenario for using this is to update last_calibration_date.

RESET will enable/add a monitor according to connection_id submitted. included_parameters is used to describe the indicators and units your monitor has.

Event Name: monitors

Event Parameters

Event - Readings

The data provider will push data to the RESET Cloud, where the data is a set of readings per indicator averaged per every half-hour.

This is done with the readings event and each message pushed by the data provider needs to include a uniquemessage_id parameter.

RESET will verify the validity of the data. If the verification is successful, the acknowledgement message is returned via the ack event with the message_id. If the verification fails, the error message is returned via the errors event with the message_id.

There are two options for when to send data: "once every 24 hours" or "every 30 minutes":

• For "once every 24 hours", please communicate with the RESET team on when you would like to push. For example, the data for a particular data provider is set to push at 01:00 AM (UTC +08:00) everyday. The dataset includes data from 0:00 to 24:00 from the day before. A 24 hours set of 30 minute averaged readings for each indicator, per monitor, is submitted once a day.
• For "every 30 minutes", only one set of 30 minute averaged readings for each indicator, per monitor, will be submitted every 30 minutes.

Single Data Push for Air

Sample code for single data push for an Air monitor:

socket.emit('readings',{
  "message_id": "<MESSAGE_ID>",
  "data": {
    "connection_id": "<CONNECTION_ID>", // for convenience of processing
    "readings": [{
      "connection_id": "<CONNECTION_ID>", // exactly the same as the above connection_id
      // used to confirm that the the readings data is coming from the same connection_id
      "reading_time": "2017-03-15T15:00:00.000+08:00",
      "pm2p5": 100,
      "tvoc": 0.5,
      "co2": 500,
      "temp": 25,
      "rh": 50
    }]
  }
});

// For catching errors
socket.on('errors', (data) => {
  console.log(data);
});

// For catching acknowledgement
socket.on('ack', (data) => {
  console.log(data);
});

The data is validated via the ack event. Returns the following JSON:

{
  "code": "10200",
  "ack": true,
  "message_id": "<MESSAGE_ID>",
  "api_version": "v2"
}

Here are details for how to push for air monitors.

Event Name: readings

Parameter: data

data contains the readings from a monitor. data includes the following attributes: connection_id and readings.

data consists of parameters that are 30 minute averages of the raw data, which will be compiled by the data provider. Every 30 minute average should start at exactly XX:00:00 (XX hour 0 minute 0 seconds) and end at exactly XX:30:00 (30 minute and 0 seconds) or vice versa. reading_time is defined as the end of the 30 minute average.

For example, reading_time is 2017-03-15T16:30:00.000+08:00 for the 30 minute averaged reading between 2017-03-15T16:00:00(excluded) to 2017-03-15T16:30:00(included). In other words, 2017-03-15T16:00:00 < 30 min average <= 2017-03-15T16:30:00.

Parameter: readings

This is where the actual readings data is held. It is possible to submit one reading or multiple readings (up to 48, or one day's worth), but it must be from the same connnection_id.

If there are multiple connection_id, each needs to send a separate message.

For air module:

Multiple Data Push for Air

Sample code for data push for an Air monitor with multiple sets of data:

socket.emit('readings',{
  "message_id": "<MESSAGE_ID>"
  "data": {
    "connection_id": "<CONNECTION_ID>", // for convenience of processing
    "readings": [{
      "connection_id": "<CONNECTION_ID>", // same as the above
      "reading_time": "2017-03-15T15:00:00.000+08:00",
      "pm2p5": 100,
      "tvoc": 0.5,
      "co2": 500,
      "temp": 25,
      "rh": 50
    }, {
      "connection_id": "<CONNECTION_ID>",
      "reading_time": "2017-03-15T15:30:00.000+08:00",
      "pm2p5": 100,
      "tvoc": 0.5,
      "co2": 500,
      "temp": 25,
      "rh": null // if there is no data for a parameter, you can use null, a blank string, or "None"
    }]
  }
});

It is possible to push multiple sets of data at once by including them in readings. It must be from the same connection_id and one message maxes out at 48 readings (one days worth). If it is more than 48 readings, another message needs to be sent.

Single Data Push for Other Modules

Sample code for data push:

// energy, circularity, water module contains channel info in readings.
// Below is sample code for water module monitor with two channels

socket.emit('readings',{
  "message_id": "<MESSAGE_ID>",
  "data": {
    "connection_id": "<CONNECTION_ID>", // for convenience of processing
    "readings": [{
      "connection_id": "<CONNECTION_ID>",
      "reading_time":"2022-03-15T15:00:00.000+08:00",
      "water_flow": [
        {
          "channel_id": "<CHANNEL_ID_1>",
          "reading": 68
        },
        {
          "channel_id": "<CHANNEL_ID_2>",
          "reading": 2300
        }
      ],
      "water_temp": [
        {
          "channel_id": "<CHANNEL_ID_1>",
          "reading": 18
        },
        {
          "channel_id": "<CHANNEL_ID_2>",
          "reading": 20
        }
      ]
    }]
  }
});

Examples for Variables above:
- MESSAGE_ID: mi_1662109200000 (some var, maybe name of Data Provider, with epoch time in milliseconds. Make sure that each MESSAGE_ID is unique.)
- CONNECTION_ID: GA_23682013 (the Data Provider ID used to reference this monitor. Often the same as the Monitor ID below.) - CHANNEL_ID_1: c01 (the Data Provider ID used to reference this data channel from this monitor. Could be something very short, needs to be unique for this CONNECTION_ID.)
- CHANNEL_ID_2: c02 (the Data Provider ID used to reference this data channel from this monitor. Must be unique for this CONNECTION_ID.)

Here are details for how to push data for Water, Energy, and Circularity monitors. Please note that channels need to be included.

Event Name: readings

Parameter: data

data contains the readings from a monitor. data includes the following attributes: connection_id and readings.

Parameter: readings

This is where the actual readings data is held. It is possible to submit one reading or multiple readings (up to 48, or one day's worth), but it must be from the same connnection_id.

If there are multiple connection_id, each needs to send a separate message.

reading_time must be set to exactly XX:00:00 (XX hour 0 minute 0 seconds) or exactly XX:30:00 (30 minutes and 0 seconds). If it is not, then the data might not get recorded properly in the RESET Cloud. If there is no reading at that exact time, find the closest reading to it and make sure that it is reported as XX:00:00 or XX:30:00.

For water module:

water_flow, water_temp, tds, orp, and ph are arrays for reading objects with each object containing:

For energy module:

power_consumption is an array for reading objects, each object contains:

For circularity module:

bin_weight is an array for reading objects, each object contains:

*There is a scenario where a bin is emptied and then accrues even more weight than before within 30 minutes. Using the max weight logic, we lose count of the emptying. Therefore, data providers will need to add one more piece of logic where it sends an additional bin_weight array for the max weight before every emptying of the bins.

Multiple Data Push for Other Modules

// energy, circularity, water module contains channel info in readings.
// Below is sample code for water module monitor.

socket.emit('readings',{
  "message_id": "<MESSAGE_ID>",
  "data": {
    "connection_id": "<CONNECTION_ID>", // for convenience of processing
    "readings": [
      {
        "connection_id": "<CONNECTION_ID>",
        "reading_time":"2022-03-15T15:00:00.000+08:00",
        "water_flow": [
          {
            "channel_id": "<CHANNEL_ID_1>",
            "reading": 3888
          },
          {
            "channel_id": "<CHANNEL_ID_2>",
            "reading": 4868
          }
        ],
        "water_temp": [
          {
            "channel_id": "<CHANNEL_ID_1>",
            "reading": 18
          },
          {
            "channel_id": "<CHANNEL_ID_2>",
            "reading": 17
          }
        ]
      },
      {
        "connection_id": "<CONNECTION_ID>",
        "reading_time":"2022-03-15T15:30:00.000+08:00",
        "water_flow": [
          {
            "channel_id": "<CHANNEL_ID_1>",
            "reading": 570
          },
          {
            "channel_id": "<CHANNEL_ID_2>",
            "reading": 899
          }
        ],
        "water_temp": [
          {
            "channel_id": "<CHANNEL_ID_1>",
            "reading": 18
          },
          {
            "channel_id": "<CHANNEL_ID_2>",
            "reading": 23
          }
        ]
      },
    ]
  }
});

It is possible to push multiple sets of data at once by including them in readings. It must be from the same connection_id and one message maxes out at 48 readings (one days worth). If it is more than 48 readings, another message needs to be sent.

Ack & Error Messages

For all successful events, RESET will return an ack event in the form of the following JSON:

{
  "code", "10200",
  "ack": true,
  "id": "<MESSAGE_ID>"
}

For all unsuccessful ecents, RESET will return an errors event in the form of the following JSON:

{
  "code", "10400",
  "message": "<ERROR_MESSAGE>",
  "id": "<MESSAGE_ID>"
}

When a event is successful while using the RESET API, the RESET Cloud will acknowledge the success via the ack event with the code:10200. The message_id will also be returned as id so the event message can be referenced.

When a event is unsuccessful while using the RESET API, the RESET Cloud will end an error message via the errors event with the code displaying an Error Code listed below. The message_id will also be returned as id so the event message can be referenced.

Below are the definitions of the error codes:

FAQ

connection_id – Is this code assigned by RESET or does the Data Provider generate it? If Data Provider generate it, is there a certain format?

The connection_id is generated by the Data Provider. There is no required format, aside that each connection_id from a data provider must be unique. If the code is human friendly in terms of readability, even better. It will be used for recognizing a monitoring station on both or our servers.

The connection_id is used to find and add a monitoring station or monitor to their project within the RESET Cloud.

There is no mention of the building or location in this API document. Why?

The RESET API only handles the monitor or monitoring stations. The RESET Cloud user interface is where the managing of the building and locations happen.

monitor_serial_id – Does the Data Provider generate this?

The monitor_serial_id is the serial code of the actual physical monitor. It is stored for asset management purposes. The data provider should be able to get this information from the hardware.

Does message_id have to be unique at all times?

The message_id should be unique at all times from the data provider as it is used for debugging and locating messages in the server log.

How are you mapping connection_id to building/location on the RESET Project Cloud? In other words, how do we, the RESET Accredited Data Provider, work with the RESET AP so they know they data that they are analyzing is for the building/location that they are certifying?

This is an example of how it works in QLEAR, a RESET Accredited Data Provider.

In QLEAR, they have an integration screen that looks like this:

The code is generated for the user to copy and add into the RESET Cloud. In the RESET Cloud, there is a section called Monitor List, where you add the monitors.

When you add monitors, you get this view: So this is where you would input the code that was given by the data provider.