Secondary MQTT Format Guide for Enterprise Devices

In addition to sending your data to the Kaiterra Web App, Secondary MQTT allows you to specify another location for your data to be sent. This article will help you understand how Secondary MQTT works for our Enterprise devices. 

Sensedge

Navigate to Settings --> Device Details --> Connectivity --> MQTT to set up your Secondary MQTT information.

Once the Sensedge is connected to your Secondary MQTT broker, you will need to subscribe to this MQTT topic:

The "+" is a placeholder (or wildcard) that matches anything; in this case, the UDID of the device.

All the data will be uploaded in one message. No sub-path is used for each pollutant.
An MQTT message will look something like this:

{
  "ts": "2019-09-25T05:30:00Z",
    "rco2 (ppm)": 441.5,
    "rtemp": -45,
    "rhumid": 0,
    "km103.rtvoc (ppb)": 205.6,
    "km103.rhumid": 54.24,
    "km103.rtemp": 25.43,
    "km100.rgt25": 4.565,
    "km100.rpm25": 38.26,
    "km100.rpm25c": 45.65,
    "km100.rgt03": 4331,
    "km100.rpm10": 41.09,
    "km100.rpm10c": 49.02,
    "rbtrytemp": 30,
    "rbtryvoltage_now": 4049000,
    "rbtryvoltage_max": 4100000,
    "rbtrycurrent_now": 334000,
    "rbrdtemp": 37
}

---

Sensedge Mini

Using the Kaiterra Enterprise Configuration Tool, connect to your Sensedge Mini to set up your Secondary MQTT settings.

We support four modes for secondary MQTT (sMQTT):

1. Unsecured
2. Secured via SSL
3. Secured via SSL, with username + password authentication
4. Secured via SSL, with x.509 certificate-based authentication

1. Unsecured

For unsecured sMQTT, all that's required is to fill out the fields below.
Once you fill out the "Broker URI", the other fields will appear.

2. Secured via SSL

To encrypt the MQTT communications using SSL, the above fields are required, plus a Server Certificate. To enable, check the "Use a secure connection" box and paste in the Server Certificate:

3. Secured via SSL, with username + password authentication

Some MQTT brokers are configured to require a username and password. These can be entered in the Username and Password fields that appear alongside the other Secondary MQTT fields.

4. Secured via SSL, with x.509 certificate-based authentication

As an alternative to usernames and passwords, some MQTT brokers use what's called certificate-based authentication (sometimes called x.509 authentication). This is generally considered more secure than username + password, and in any case may simply be the IT policy.

To enable this, the above fields are required except for the username and password field. Then, paste in a Client Certificate and Client Key in the provided fields, shown below.

Customers who need this feature will know what the Client Certificate and Client Key are.

Once the Secondary MQTT settings are configured, you will need to subscribe to the MQTT topic:

The "+" is a placeholder (or wildcard) that matches anything; in this case, the UDID of the device.

You can also specify custom topics for the Sensor Reading Topic and the Sensor Metadata Topic, using {sn} and {udid} as placeholders.

All the data will be uploaded in one message. No sub-path is used for each pollutant.

You can choose from two different message formats, which will change how the data appears in the MQTT message.

Format 1:

{
	"ts": 1624874669,
	"dsn": "KG200104631",
	"dudid": "00000000-0031-0101-0000-00007e57c0de",
	"data": {
		"km200.rgt03": 800,
		"km200.rgt25": 3,
		"km200.rpm10": 6,
		"km200.rpm10c": 7,
		"km200.rpm25": 6,
		"km200.rpm25c": 7,
		"km203.reco2 (ppm)": 810,
		"km203.reco2_bl": 34730,
		"km203.rethoh": 18200,
		"km203.rh2": 12500,
		"km203.rtvoc": 1218,
		"km203.rtvoc_bl": 37470,
		"km203.rtvoc_eng": 109.9,
		"km203.rtvocb (ppb)": 1218,
                "km207.r03": 50,
		"rco2 (ppm)": 1141,
		"rhumid": 38.08,
		"rhumidb": 33.11,
		"rtemp": 31.04
		"rtempb": 33.61,
		"signal_strength": -40,
	}
  }

Format 2:

{
       "ts": 1624874676,
       "dsn": "KG200104631",
       "dudid": "00000000-0031-0101-0000-00007e57c0de",
       "data": {
          "temperature": 28.90,
          "humidity": 28.23,
          "pm25": 21,
          "pm10": 22,
          "co2": 1471,
          "tvoc": 0
          "o3": 20
       },
       "units": {
          "temperature": "C",
          "humidity": "%",
          "pm25": "ug/m3",
          "pm10": "ug/m3",
          "co2": "ppm",
          "tvoc": "ppb",
          "o3": "ppb"
       }
}

• "ts" - Timestamp in UTC 
• "temperature" - temperature in celsius
• "humidity" - relative humidity in %
• "pm25" - PM2.5 in micrograms per cubic meter
• "pm10" - PM10 in micrograms per cubic meter
• "co2" - CO2 in ppm
• "tvoc" - TVOC in ppb
  
• "o3" - Ozone in ppb

---

Kaiterra Square

Using the Kaiterra Enterprise Configuration Tool, connect to your Kaiterra Square in order to set up your Secondary MQTT settings.

We support four modes for secondary MQTT (sMQTT):

1. Unsecured
2. Secured via SSL
3. Secured via SSL, with username + password authentication
4. Secured via SSL, with x.509 certificate-based authentication

1. Unsecured

For unsecured sMQTT, all that's required is to fill out the fields below.
Once you fill out the "Broker URI", the other fields will appear.

2. Secured via SSL

To encrypt the MQTT communications using SSL, the above fields are required, plus a Server Certificate. To enable, check the "Use a secure connection" box and paste in the Server Certificate:

3. Secured via SSL, with username + password authentication

Some MQTT brokers are configured to require a username and password. These can be entered in the Username and Password fields that appear alongside the other Secondary MQTT fields.

4. Secured via SSL, with x.509 certificate-based authentication

As an alternative to usernames and passwords, some MQTT brokers use what's called certificate-based authentication (sometimes called x.509 authentication). This is generally considered more secure than username + password, and in any case may simply be the IT policy.

To enable this, the above fields are required except for the username and password field. Then, paste in a Client Certificate and Client Key in the provided fields, shown below.

Customers who need this feature will know what the Client Certificate and Client Key are.

Once the Secondary MQTT settings are configured, you will need to subscribe to the MQTT topic:

The "+" is a placeholder (or wildcard) that matches anything; in this case, the UDID of the device.

All the data will be uploaded in one message. No sub-path is used for each pollutant.

An MQTT message will look something like this:

{
	“ts”: “2021-05-19T09:27:29Z”,
	“data”: {
		“humidity”: 27.43,
		“pm10”: 28,
		“pm10_count”: 38,
		“pm25”: 27,
		“pm25_count”: 2509,
		“rco2 (ppm)“: 530,
		“rgt05”: 751,
		“rgt1": 136,
		“rgt10”: 0,
		“rgt5": 1,
		“rhumidb”: 23.85,
		“rpm10": 27,
		“rpm25”: 25,
		“rtempb”: 34.58,
		“signal_strength”: -54,
		“st03.reco2": 656,
		“st03.reco2_bl”: 34750,
		“st03.rtvoc”: 130,
		“st03.rtvoc_bl”: 38450,
		“st03.rtvocb”: 435,
		“temp”: 32
	}
}