Building to DCH Data Export Process

If you would like to onboard your timeseries data using our REST API instead of MQTT, go here.

Protocol

While DCH offers multiple protocols for data export, secure MQTT over TCP port 8883 (TLS encrypted messages) is the preferred method.

Host ID

All MQTT messages must be published to broker2.dataclearinghouse.org.

MQTT Topic

The topic of the MQTT messages must follow this format:

dch/<siteName>/<buildingName>/<gatewayType>/<gatewayName>

siteName: Name of the site, preferably same as what you have created on DCH.

buildingName: Name of the building, preferably same as what you have created on DCH.

gatewayType: If you are using a Tridium JACE gateway, you can set this to "tridium". Otherwise, set this to "generic".

gatewayName: Give your gateway a name.

E.g. 1: dch/MelbourneCBD/Block3/generic/MyGateway

E.g. 2: dch/SydneyCBD/Building22/tridium/SydneyB22JACE

Name of the points in DCH are derived from the Site and Building names you provide in the topic and also the parentName and pointName fields of the payload as described below.

The general structure of the point name: DATASOURCE_PREFIX-SITE_NAME.BUILDING_NAME.PARENT_NAME.POINT_NAME

E.g. 1: dsapi-cold-two-paper-MelbourneCBD.Block3.AHU_1.RA_Temp

E.g. 2: dsapi-hot-three-rock-SydneyCBD.Building22.MSSB-1.KWH_IMPORT

Payload schema

All MQTT payloads must be in JSON format and follow the schema as detailed here. Some examples and notes are listed below.

If you want to verify your payloads are abiding by the schema, you can go to https://www.jsonschemavalidator.net. Copy and paste our schema on the left box, copy and paste a sample of your payload on the right box. You should see the message: "No errors found. JSON validates against the schema".

Absolute minimum required for successful parsing:

{
  "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
  "point": {
    "parentName": "AHU02",
    "pointName": "CS.EC.OFF.AHU 02.HW VALVE",
    "currentValue": 0
  }
}

Since this payload has no timestamp field, the time of this measurement is recorded as the timestamp of when the payload is processed by the parser. Messages are not processed when they are received and may be queued for some time.

DCH can parse language characters that are part of the Extended ASCII table. These include é, ü, â, etc.

If the character is a "Special" character such as "_" or "." , it is converted as defined here.

Minimum recommended payload:

{
  "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
  "point": {
    "parentName": "AHU02",
    "pointName": "CS.EC.OFF.AHU 02.HW VALVE",
    "timestamp": "2024-03-04T12:03:26.993+11:00",
    "currentValue": 0
  }
}

The timestamp field MUST be in ISO 8601 format represented in any of the following options:

yyyy-MM-dd'T'HH:mm:ssZ

yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,9}Z

yyyy-MM-dd'T'HH:mm:ss[+-]HH:mm

yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,9}[+-]HH:mm

Full recommended payload:

{
  "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
  "point": {
    "parentName": "AHU02",
    "pointName": "RA_Temp",
    "timestamp": "2024-03-04T12:03:26.993+11:00",
    "currentValue": 0,
    "facets": {
      "units":"°C"
    }
  }
}

Including custom metadata to the payload:

If the metadata field you want to send is not covered in our schema, you can add your own custom metadata field in the "tags" field.

{
   "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
   "point": {
     "parentName": "AHU02",
     "pointName": "CS.EC.OFF.AHU 02.HW VALVE",
     "timestamp": "2024-03-04T12:03:26.993+11:00",
     "currentValue": 0,
     "facets": {
       "units":"°C"
     },
     "tags":{
       "namespace:my_metadata_field":"my_metadata_value"
     }
  }
}

The metadata you provide in the MQTT payloads are NOT linked to any building models. Rather, these fields are designed to inform model developers in their modelling process.

The custom metadata field MUST be namespaced as <string>:<string>.

Sending historic data:

If you wish to backfill historic data for a point, use this format:

{
  "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
  "point": {
    "pointName": "CS.EC.OFF.AHU 02.HW VALVE",
    "currentValue": 0,
    "parentName": "AHU02",
    "historyData": [
      [
        "2024-02-26T13:03:18.998+11:00",
        3.142
      ],
      [
        "2024-02-26T13:08:18.998+11:00",
        2.71
      ]
    ]
  }
}

Maximum allowed size of a single payload is currently 10MB. We recommend keeping the payloads well below that amount.