MQTT

This walkthrough shows a step by step process to onboard building data to DCH using MQTT. This is a general process and does not detail specific gateway/tool workflow. We may have a detailed documentation regarding your gateway, check this page.

Step 1: create your sites and buildings on DCH

1. On the sidebar go to Sites and click on Add New Site.

   
2. Enter a Site ID. All other fields including the address details are optional.

   
3. Press Create Site Information.

4. On the sidebar, go to Sites again and press on Add New Building.

5. Select your previously created site and set a Building ID. All other fields are optional.

   
6. Press Create Building Information

You now have a site and that site has a building.

Step 2: create a data source for your site/building

A detailed description of this step is provided here. At the end of this step you should have:

1. Your MQTT username

2. Your MQTT password

In this case, our username is dsapi-annoying-willing-tank:[e-mail] and our password is walkthrough_password.

You can verify your data source is created by navigating to the Data Sources page.

Step 3: publish MQTT messages to the data source

This walkthrough assumes you already have a list of points which you want to export and your gateway is already polling those values. In addition, it assumes your gateway can create JSON payloads and encrypt the data using TLS 1.2. For the purposes of this walkthrough, a simple Python script is publishing mock data to DCH.

The host ID of DCH's broker is broker2.dataclearinghouse.org.

Please make sure you have read this section of the documentation before you continue. For this walkthrough we will be using the full recommended payload. The topic of all MQTT messages will be:

dch/walkthrough_site/walkthrough_building/generic/walkthrough_datasource

Consistency between your site/building IDs on DCH and your MQTT messages is incredibly helpful and will be handy for the BRICK model construction later.

A sample payload would be:

{
    "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
    "point": {
        "pointName": "Air_Temp",
        "timestamp": "2024-03-04T12:03:26.993+11:00",
        "currentValue": 15.822375150773174,
        "parentName": "W_First_Floor_Room_1",
        "facets": {
            "units": "degrees celsius"
        }
    }
}

To summarise:

• Host ID: broker.dataclearinghouse.org

• Port: tcp_8883

• Encryption: TLS 1.2

• Username: dsapi-annoying-willing-tank:[e-mail]

• Password: walkthrough_password

• MQTT topic: dch/walkthrough_site/walkthrough_building/generic/walkthrough_datasource

• Sample MQTT payload:

{
    "$schema": "http://csiro.au/dch/bms-json/schema-draft-07.json",
    "point": {
        "pointName": "Air_Temp",
        "timestamp": "2024-03-04T12:03:26.993+11:00",
        "currentValue": 15.822375150773174,
        "parentName": "W_First_Floor_Room_1",
        "facets": {
            "units": "degrees celsius"
        }
    }
}

If the publish is successful, you should be able to see the data on DCH. Navigate to your data source again and the points should be listed there after a short period of time.