Skip to main content

Connhex JSON

Despite its name, this is not a format tied to Connhex - your devices will still be compatible with any IoT platform, since the message format is simple JSON with some predetermined keys.

A message compliant to the Connhex JSON has the following structure:

{
// Timestamp
"t": 1559813429,
// Tags
"m": {
"key1": "value1",
"key2": "value2"
// ...
},
// Data
"keyA": "valueA",
"keyB": 1
// ...
}

Tags

Tags are the keys that will be indexed at the database level.

KeyMandatoryDescription
myesObject key to group all tags. If there's at least one tag, there must be this key and its corresponding value must contain all tags.
key1noExample key. Can be any string, and the corresponding value must be a string.
key2noExample key. Can be any string, and the corresponding value must be a string.

A few notes:

  • You can add as many keys as necessary, and each key can be any string (key1, key2 are just examples)
  • Connhex will use these keys to create database columns - or equivalents
  • The value corresponding to a tag key must be a string

Data

Data fields will, as a matter of fact, be stored at the database level as data.

KeyMandatoryDescription
keyAnoExample key. Can be any string, and the corresponding value should be either a string or a number.
keyBnoExample key. Can be any string, and the corresponding value should be either a string or a number.

A few notes:

  • You can add as many keys as necessary, and each key can be any string (keyA, keyB are just examples)
  • For performance reasons, try to stick with single values - string, number, boolean, ... - corresponding to a data key. Avoid deeply nested structures if possible

Other fieds

KeyMandatoryDescription
tyesUnix timestamp, in milliseconds.

Tags or data?

When formatting a message according to Connhex JSON, one of the most difficult decisions is to choose between creating a tag or a data field for a given value to transmit.

Here are a few guidelines and best practices:

  • if the value you need to transmit together with a given key is not a string, use a data field
  • if user facing apps need to use a key to sort, filter or search, leverage tags for that key-value pair
  • a tag field is heavier in terms of disk usage than a data field. Try to use tags only for fields that need to be used as filters, and use data fields for the rest.

Connhex JSON vs SenML

If your devices need to send multiple message types, you could be facing the choice between using Connex JSON and SenML.

As a rule of thumb:

  • if you only need to send data from sensors, and all measurements are independent from each other, use SenML.
  • if at least one message is different from a single measurement - or may be in the future - use Connhex JSON and format your message like the example below.

Connhex JSON for sensor measurements

Instead of using SenML for sensor measurements, you can structure messages according to Connhex JSON using name, unit and value as keys:

{
"t": 1645627703, // Unix timestamp in milliseconds
"m": {
"name": "name"
},
"unit": "unit",
"value": 0 // Measurement as number
}

For example, the same measurement used to illustrate how to create a SenML message here would be represented as:

{
"t": 1645627703,
"m": {
"name": "urn:dev:ow:10e2073a01080063"
},
"unit": "Cel",
"value": 23.1
}

Standardizing your messages this way leaves room for further optimization - compressing messages on the edge would be one typical example.

Examples

Enough of the theory, it's time to see some actual messages that Connhex instances are receiving right now.

Example 1: fleet diagnostic

{
"t": 1559813429,
"m": {
"license_plate": "AB123CD",
"unit_type": "T"
},
"id": "000000-0337283",
"diagnostic_1": 45.3,
"diagnostic_2": 88.0,
"diagnostic_3": 65.9,
"alarm_2": 0,
"alarm_3": 0,
"lat": 45.6446004,
"lon": 12.1524293,
"alt": 1
}

This message is used to register diagnostic data:

  • license_plate and unit_type are tags, since a dashboard allows to aggregate diagnostic data by license plate and measuring unit type
  • diagnostics, alarms and coordinates are data and there's a single level of nesting

Example 2: machining data

{
"t": 1645627703,
"m": {
"job": "Milling"
},
"customer": "Acme Inc.",
"job_ref": "0x-7ac",
"job_start": 1645627703,
"job_end": 1645746845
}

This message is used to register data about machining operations:

  • job is a tag, since a mobile app needs to filter data by job type
  • all other fields are registered as data. In this case customer and job_ref have not been deemed interesting to query against: if an app needs to retrieve all operations related to a certain customer, the customer key should become a tag.