NAV Navbar
Logo
javascript

RESET Data Push API V1.0 for Data Providers

This document explains how to use the RESET API V1.0 for Data Providers.

RESET Accredited Data Provider refers to the RESET authorized partner to provide data as a data provider. Third-party data providers must first contact RESET’s Support Team for accreditation at support@reset.build.

RESET uses Socket.IO as it’s 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 document 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, please email our support team at support@reset.build.

Technology Stack

Currently, RESET Socket API V1.0 is using Socket.IO v1 (specifically, we are currently using v1.7.2 ), Here is the compatibility information.

Initial Setup

Getting a RESET ID and Secret Authentication

Data Providers must be RESET Accredited to have a socket connection, otherwise, the connection will be closed. You can log in the RESET Data Provider Management page to view the see the status

Setting up Socket Connection

Sample code for creating a socket connection:

// You should change the SOCKET_SERVER_URL to the server url
const Client = require('socket.io-client');
socket = Client(SOCKET_SERVER_URL, { jsonp: false });

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

Please make sure that ‘SOCKET_SERVER_URL’ is pointed to the correct socket server address (http://reset.build:8088)

Use Socket Client to create connection

The Socket connection is created using a two-way communication mechanism that meets the needs of Data Providers for pushing monitoring data, monitor information updates, and other monitoring data requested by RESET.

Verification Method

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 a JSON structure as follows:

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

A failed authentication for the auth event will return a JSON structure as follows:

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

Use the auth event to complete the authentication. The parameters need to include the correctclient_id and client_secret value to establish a stable socket connection. After the successful authentication, the server will also return specific information through the auth event.

If the client_id or client_secret parameters are missing or if there is a parameter mismatch, the auth event will return an error.

Data Provider Management

RESET provides data providers with an interface to check Users can log in to Data Provider Management to find their own client_id and client_secret.

Data Push to RESET

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 and the verification will be successful by the ack event returns a message ID completion acknowledgement. If the verification fails, the error message is returned via the errors event.

Data Provider Data Push

Sample code for data push:

socket.emit('readings',{
  'message_id': '<MESSAGE_ID>', // <MESSAGE_ID> i.e. 373490371
  'data': {
    'station_code': '<CODE>', // for convenience of processing, <CODE> i.e.
    'readings': [{
      'station_code': '<CODE>', // should be the same as the above
      'reading_time':'2017-03-15T15:00:00.000+08:00',
      'tvoc': '0.5',
      'pm2p5': 100,
      'co2': '500',
      'temperature': '25',
      'humidity': '50'
    },{
      'station_code': '<CODE>',
      'reading_time':'2017-03-15T16:00:00.000+08:00',
      'tvoc': 0.5,
      'pm2p5': '100',
      'co2': '500',
      'temperature': '25',
      'humidity': null // if there is no data for a parameter, you can use null, a blank string, or 'None'
    }]
  },
});

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

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

The data is validated via the ack event. Returns a JSON structure as follows:

{
  "code", "10200",
  "ack": true,
  "id": "<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 should include 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 once every 30 minutes, only one set of 30 minute averaged readings for each indicator, per monitor, will be submitted every 30 minutes.

Event Name: readings

Message Parameters

Parameter Required Value Default Description
message_id true null a unique message ID from the data provider
data true null a wrapper for additional parameters, described below

data Parameters

The data contains the readings information of a Monitoring station, that is, the reading set of the day, wherein each reading includes but is not limited to the following attributes: station_code, tvoc, pm2p5, co2, reading_time. reading_time is the last point-in-time of the time range for an averaged reading. For example: the value of reading_time should be 2017-03-15T16:30:00.000+08:00 for the averaged reading between 2017-03-15T16:00:00(excluded) to 2017-03-15T16:30:00(included).

Parameter Required Default Description
station_code true null A monitoring station’s unique id, generated by the data provider. Needs to be unique for the data provider.
tvoc true null Data needs to be a 30 minute average for TVOC, Default unit: mg/m³
pm2p5 true null Data needs to be a 30 minute average for PM2.5, Default unit: μg/m³
co2 true null Data needs to be a 30 minute average for CO2, Default unit: ppm
temperature false null Data needs to be a 30 minute average for Temperature, Default unit: °C
humidity false null Data needs to be a 30 minute average for Relative humidity, Default unit: %RH

Monitoring Stations - Adding, Removing, and Updating

Monitoring stations is the general term for a monitor in the RESET Cloud.

Monitoring station updates are done via the stations events. Each event needs to contain a unique message_id parameter.

RESET will verify the validity of the data, the verification will be successful by the ack event return message ID completion message acknowledgement.

If the verification fails, the error message is returned via the errors event.

Add a Monitoring Station

Sample code for enabling a Monitoring Station:

socket.emit('stations', {
  'message_type': 'enable',
  'data': {
    'station_code': '<CODE>',
    'name': '<NAME>',
    'meta': {
      'monitor_detail': {
        'pm2p5': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ],
        'tvoc': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ],
        'co2': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ]
      }
    },
  },
  'message_id': '<MESSAGE_ID>'
});

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

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

The data is validated via the ack event. Returns a JSON structure as follows:

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

RESET will enable/add a monitoring station according to station_code submitted.

Event Name: stations

Event Parameters

Parameter Required Value Default Description
message_type true enable null set to “enable” to add a new monitoring station to the RESET Cloud. Each event can only modify one monitoring station.
message_id true null a unique message ID from the data provider
data true null a wrapper for additional parameters, described below

data Parameters

Parameter Required Default Description
station_code true null A monitoring station’s unique id
name false null an optional label for the monitoring station, used to help recognize the monitor on top of the station_code
meta true null monitor information of the Monitoring station

The meta parameter is used to transmit the monitor information of each indicator of the current Monitoring station. The monitor information includes:

Parameter Required Default Description
monitor_brand true null the brand of the physical monitor (i.e. for a DST OPC-2000, DST would be the monitor_brand)
monitor_sku true null the SKU of the physical monitor (i.e. for a DST OPC-2000, OPC-2000 would be the monitor_sku)
monitor_id true null the serial id or code used to recognize the physical monitor (i.e. DST OPC-2000 monitors use a serial code that looks something like this: 1116210322)

Removing a Monitoring Station

Sample code for removing a Monitoring Station

socket.emit('stations', {
  'message_type': 'disable',
  'data': {
    'station_code': '<CODE>'
  },
  'message_id': '<MESSAGE_ID>'
});

The data is validated via the ack event. Returns a JSON structure as follows:

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

This message deletes or disables the corresponding Monitoring station information from RESET based on station_code.

Event Name: stations

stations Event Parameters when disabling

Parameter Required Value Default Description
message_type true disable null set to “disable” to remove a monitoring station from the RESET Cloud. Each event can only modify one monitoring station.
message_id true null a unique message ID from the data provider
data true null a wrapper for additional parameters, described below

data Parameters when disabling

Parameter Required Default Description
station_code true null A monitoring station’s unique id

Edit a Monitoring Station

Sample code for editing a Monitoring Station:

socket.emit('stations', {
  'message_type': 'modify',
  'data': {
    'station_code': '<CODE>',
    'meta': {
      'monitor_detail': {
        'pm2p5': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ],
        'tvoc': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ],
        'co2': [
          {
            "monitor_brand":"DST",
            "monitor_sku":"OPC-2000",
            "monitor_id":"1116210322",
          }
        ]
      }
    },
  },
  'message_id': '<MESSAGE_ID>'
});

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

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

The data is validated via the ack event. Returns a JSON structure as follows:

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

When the monitoring information of the observatory changes in the application of third party data, RESET modifies the meta information of the corresponding Monitoring station monitor according to the content of this message.

Event Name: stations

Event Parameters

Parameter Required Value Default Description
message_type true modify null set to “modify” to update monitoring stations to the RESET Cloud. Each event can only modify one monitoring station.
message_id true null a unique message ID from the data provider
data true null a wrapper for additional parameters, described below

data Parameters

Parameter Required Default Description
station_code true null A monitoring station’s unique id
meta true null wrapper for editable parameters, described below

meta Parameters

The meta parameters include the editable parameters for the monitoring station.

Parameter Required Default Description
monitor_brand true null the brand of the physical monitor (i.e. for a DST OPC-2000, DST would be the monitor_brand)
monitor_sku true null the SKU of the physical monitor (i.e. for a DST OPC-2000, OPC-2000 would be the monitor_sku)
monitor_id true null the serial id or code used to recognize the physical monitor (i.e. DST OPC-2000 monitors use a serial code that looks something like this: 1116210322)

Acknowledgement & 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:

Error Code Meaning
10400 Bad Request (there is an error with the request. Either something is written wrong or something required is missing)
10401 Unauthorized Access (error with the client_id and/or client_secret)
10500 Internal Server Error. Please reach out to us at support@reset.build to let us know.

FAQ

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

The station_code is generated by the Data Provider. There is no required format, aside that each station_code 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 station_code 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_id – Does the Data Provider generate this?

The monitor_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 station_code 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: Example reset integration

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.

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

The one thing we will need to do is to update station_code to connection_id at some point to unify the naming convention, but we will continue to support station_code regardless.

javascript