> For the complete documentation index, see [llms.txt](https://docs.dataclearinghouse.org/dch-2.0-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dataclearinghouse.org/dch-2.0-documentation/si-docs/dch-onboarding-timeseries-data/building-to-dch-data-export-process.md).

# Building to DCH Data Export Process

{% hint style="info" %}
If you would like to onboard your timeseries data using our REST API instead of MQTT, go [here](/dch-2.0-documentation/walkthroughs/onboarding-building-data/rest-api.md).
{% endhint %}

## 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 **broker.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](#payload-schema).&#x20;

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](https://bitbucket.csiro.au/projects/SBDCH/repos/bms-json/browse). Some examples and notes are listed below.

{% hint style="info" %}
If you want to verify your payloads are abiding by the schema, you can go to [**https://www.jsonschemavalidator.net**](https://www.jsonschemavalidator.net/)**.** Copy and paste [our schema](https://github.com/csiro/ensys-dch-bms-json) 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".
{% endhint %}

### Absolute minimum required for successful parsing:

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

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
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](/dch-2.0-documentation/si-docs/dch-onboarding-timeseries-data/special-character-conversions.md).
{% endhint %}

### Minimum recommended payload:

```json
{
  "$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
  }
}
```

{% hint style="info" %}
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
{% endhint %}

### Full recommended payload:

```json
{
  "$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.

```json
{
   "$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"
     }
  }
}
```

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
The custom metadata field MUST be namespaced as \<string>:\<string>.
{% endhint %}

### Sending historic data:

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

```json
{
  "$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
      ]
    ]
  }
}
```

{% hint style="danger" %}
Maximum allowed size of a single payload is currently 10MB. We recommend keeping the payloads well below that amount.
{% endhint %}