Model File Format

See also

The Xentara Model File in the Xentara user manual

A JSON object describing MQTT Client has the following syntax:

{
  "@Microservice.MQTT.Client": {
    "id": "MQTT Client",
    "uuid": "887f7fe0-8444-40ec-95d3-16cb0a04c05e",
    "brokerAddress": "host-name.azure-devices.net:8883",
    "clientId": "myDeviceId",
    "mqttVersion": "3.1.1",
    "timeoutMs": 100,
    "keepaliveIntervalS": 500,
    "verifyCertificate": true,
    "useTLS": true,
    "caCertificateFile": "/path/to/the/client/certificate.crt",
    "caCertificateDirectory": "/path/to/the/directory",
    "lastWill": {
      "topic": "devices/myDeviceId/messages/events/",
      "qos": 1,
      "retained": true,
      "payload": "{\"will\":\"Last Will Message.\"}"
    },
    "userName": "host-name.azure-devices.net/myDeviceId/?api-version=2018-06-30",
    "password": "SharedAccessSignature sr=host-name.azure-devices.net...",
    "clientCertificate": {
      "certificateFile": "/path/to/the/client/certificate.crt",
      "privateKeyFile": "/path/to/the/client/certificate.key"
    },
    "children": [
      {
      "@Microservice.MQTT.Topic": {
        "name": "devices/myDeviceId/messages/events/",
        "qos": 0,
        "retained": false,
        "payload": [
          {
            "key": "temperature",
            "value": "myDeviceId.ValueId.Temperature.value"
          },
          {
            "key": "humidity",
            "value": " myDeviceId.ValueId.Humidity.value"
          }
        ]
       }
      }
    ]
  }
}

Object Members

id	A string value containing the ID of the MQTT Client. The ID is used to construct the MQTT client’s primary key.
uuid	A string value containing the unique UUID of the MQTT Client.
brokerAddress	A string value containing the broker address for the connection from client to the host. broker address should be of the form “host:port”, where: host is the domain name port MQTT port is "1883" by default For connection with Azure Iot Hub port number should be 8883. It should follow the form: {iothubhostname}.azure-devices.net.8883, for example if the iothubhostname is “host-name” it should be: host-name.azure.devices.net:8883 Tip: host name for the azure IoT Hub can be found in the create IoT hub under the option “Overview”
clientId	A string value containing MQTT client ID. Devices can be directly created in the Azure IoT Hub. MQTT client is connected as a device with Azure IoT Hub therefore the name of the device must be same as the device created in Azure IoT hub. Note : This is optional if there will be no client ID specified MQTT Client will run without it. However in order to run it with Azure IoT Hub Client ID is not optional.
mqttVersion	A integer value containing the Version. MQTT Client supports all the versions: mqttVersion: "3.1" mqttVersion: "3.1.1" mqttVersion: "5" For the connection with Azure IoT Hub only mqttVersion: “3.1.1” should be use.
timeoutMs	A interger value containing the time in milliseconds. This value gets set in the main network loop of the MQTT client.
keepaliveIntervalS	A interger value containing the time in seconds. This value gets set when the connection to MQTT broker is established. The value must be <5
verifyCertificate	A Boolean value (true or false) containing the flag that enables or disables the verification of the server certificate. Note: This is optional.
useTLS	A Boolean value (true or false) containing the flag that enables or disables the TLS. Note: This is optional.
caCertificateFile	A string value containing the file path to certificate store containing the trusted digital certificates. The certificate could be self-signed certificate or could be downloaded from DigiCert Baltimore Root Certificate Understanding Azure IoT Hub MQTT support | Microsoft Docs (refer to the section “TLS/SSL Configuration”) For running it under the Linux following path can be used: "/etc/ssl/certs/ca-certificates.crt"
caCertificateDirectory	A string value containing the directory path to certificate store containing the trusted digital certificates. Either caCertificateFile or caCertificateDirectory can be used for server authentication. Note : This is optional if there will be no caCertificateFile / caCertificateDirectory specified MQTT Client will run without it.
lastWill	A JSON object to set last will topic and message. topic A string value containing the topic to publish. A topic for the last will can be user defined. For Azure IoT hub connection it has the iothub-MessageType property therefore it should follow the form. devices/{deviceId}/messages/events/ Understanding Azure IoT Hub MQTT support | Microsoft Docs (refer to the section “For Azure IoT Tools”) qos A integer containing the quality-of-service level for the will message. There are three possible level. 0 – at most once 1 – at least once 2 – exactly once This is optional by default qos is set to “0” retained A boolean value containing the retain message flag. This is optional by default retained is set to “false” payload A string value containing last will message. It should show valid JSON string therefore some additional "" are there. Last will topic must be same as one of the publishing topic. Note : This is optional if there will be no last will message specified MQTT Client will run without it.
username	A string value to set user name. For Azure IoT hub connection it should follow a specific format {iothubhostname}/{device_id}/?api-version=2018-06-30{iothubhostname} Understanding Azure IoT Hub MQTT support | Microsoft Docs(refer to the section “Using the MQTT protocol directly (as a device)”)
password	A string value to set the password. For Azure connection the device needs authentication at the IoT Hub. It uses SAS token that can be generated from [Visual Studio Code Azure IoT Tools - Visual Studio Marketplace] (https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-tools) or Azure CLI az iot hub | Microsoft Docs(refer to the section “az iot hub generate-sas-token”) The generate SAS token has a expiry Understanding Azure IoT Hub MQTT support | Microsoft Docs(refer to the section “For Azure IoT Tools”) Note: User name and password are optional, if there are no credential specified MQTT Client will run without it.
clientCertificate	A JSON object to set client certificates. certificateFile A string value containing the certificate file path. privateKeyFile A string value containing private key file path. There are different approaches to get client certification. MQTT client has been tested using openSSL with following: "test certificates" Tutorial: Using OpenSSL to create test certificates | Microsoft Docs following the tutorial certificates are generated to the following path "../test-certificates/rootca/..." "self-signed cerficates" Tutorial: Using OpenSSL to create self-signed certificates | Microsoft Docs following the tutorial certificates are generated to the following path "../test-certificates/selfsignedca/..." Note: This is optional but if client certificates are specified useTLS flag must be set to "true".
Microservice.MQTT.Topic	A MQTT Topic microservice inside a MQTT Client as a sub service. It is to set parameters for publishing telemetry. name A string value containing topic to publish telemetry For Azure IoT hub connection use the form devices/{deviceId}/messages/events/ as topic publishing telemetry Understanding Azure IoT Hub MQTT support | Microsoft Docs (refer to the section “sending device-to-cloud message”) Note: Azure only supports one topic qos A integer containing the quality-of-service level. There are three possible level. 0 – at most once 1 – at least once 2 – exactly once Azure IoT hub does not support qos = 2 Note: This is optional by default qos is set to “0” retained A boolean value containing the retain message flag. This flag tells the server to keep the last message on a topic or not. Note: This is optional by default retained is set to “false” payload A JSON array containing the elements. Each element has a JSON object with key and value. Payload keys and values can be user defined. key A string value containing the JSON key. value A string values describing the payload content to be publish. The string values must contain the primary keys of the attributes. For e.g. "key": "temperature", "value": "myDeviceId.ValueId.Temperature.value" Note: Each topic has a separate publish task. Therefore topics can be published as per the user need.