Binary Configuration File

Deprecated

Recipes replace the configuration file with additional functionality in a simpler JSON format.

The MQTT configuration file provides a means by which settings applicable to MQTT operation can be modified in an automated manner. One of the primary reasons for implementing this feature is to provide a way for cloud systems to perform remote updates of things like security certificates, base topics, broker URL etc.

Update Process

The update process will be triggered from either the cloud or the onboarding process. Initially, the onboarding process will load the MQTT configuration file and reboot the data logger. The data logger will search for the MQTT configuration file on boot up. If the file exists, all MQTT settings in the file will be stored and the file will be erased. The data logger will then reboot and use the newly configured MQTT settings to connect to the configured MQTT endpoint. After successfully connecting to the MQTT endpoint, the data logger will subscribe to an MQTT CC (command and control) topic. Each time an update is required, the URL of a new MQTT configuration file will be published to the MQTT CC topic. The data logger will use http(s) GET to retrieve the file and repeat the above process.

MQTT Command and Control Topic

MqttConfig Publishing to the topic {Base Topic}/CC/MqttConfig with a JSON object with the following payload:

{
    "cmd": "MqttConfig",
    "fileName": "mqttCfg.bin",
    "url": "upload.example.test.com"
}

Will cause the data logger to issue a HTTP(s) GET to retrieve a file with the specified name from the url in the JSON object. After the file is successfully retrieved, it will be parsed and all settings applied and the device restarted. As this operation is intended to be completed by known and trusted sources, the contents of the binary file are assumed to be correct and within the appropriate bounds. There is not extensive bounds checking in the parsing of the settings, so care must be taken by the creator of the binary settings image to ensure the intended settings are appropriately configured (i.e. use at your risk).

File Format

The file format consists of:

  • 2–byte header which must be 0x0020. This header must be stored to the file in Big Endian (MSB first) format.

  • 2-byte setting id (0x0001 to 0x0011). The Id must also be in Big Endian (MSB first).

  • 4-byte setting size, Also Big Endian (MSB first)

  • Setting value in ASCII (setting byte length must match the setting size parameter exactly),

  • Next 2-byte setting id (if more than one setting),

  • …

  • Last 2-byte setting id, setting length, setting value.

  • The end of the file is terminated with an ID of 0x0000 (2 bytes).

If a setting is to be omitted, it is omitted from the setting file and the parsing function will skip that setting. The data logger traverses this binary list of settings applying each one as it is encountered until the NULL setting (0x0000) is detected. At this point the data logger will reboot and the new settings will take effect.

MQTT Configuration Setting ID The setting identifier is a 16-bit, unsigned integer (Big Endian) which identifies the setting.

  • Account ID – 1 (0x0001)

  • Private Key – 2 (0x0002)

  • Public Certificate – 3 (0x0003)

  • Root Certificate Authority – 4 (0x0004)

  • Endpoint – 5 (0x0005)

  • Port Number – 6 (0x0006)

  • User Name – 7 (0x0007)

  • Password – 8 (0x0008)

  • Keep Alive Time – 9 (0x0009)

  • Client Id – 10 (0x000A)

  • Last Will Topic – 11 (0x000B)

  • Last Will Message – 12 (0x000C)

  • Last Will QoS – 13 (0x000D)

  • Last Will Message retained by broker – 14 (0x000E)

  • Enable TLS in logger – 15 (0x000F)

  • Base MQTT Topic – 16 (0x0010)

  • State Publish Interval – 18 (0x0012)

  • Status Info Publish Interval - 19 (0x0013)

  • MQTT Connect with Clean session - 20 (0x0014)

  • Campbell Cloud Enable - 21 (0x0015)

  • Enable v1 topics - 99 (0x0063)

Setting Length: The setting length identifier is a 32-bit unsigned integer (Big Endian), which immediately follows the setting identifier.

Setting Value: The setting value starts at the byte position immediately following the Setting Length. The setting value is either an ASCII string or ASCII character.