# 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 **broker2.dataclearinghouse.org**. ## MQTT Topic The topic of the MQTT messages must follow this format: dch/\/\/\/\ **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). 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://bitbucket.csiro.au/projects/SBDCH/repos/bms-json/browse/schema-draft-07.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 \:\. {% 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dataclearinghouse.org/dch-2.0-documentation/si-docs/dch-onboarding-timeseries-data/building-to-dch-data-export-process.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.