NEW
Blog Webinars Get Support

MQTT Device API

Overview

MQTT is a lightweight messaging protocol specifically designed for IoT (Internet of Things) applications. It enables efficient communication between devices in constrained environments, such as those with limited bandwidth, power, or processing resources.

Base connection

Topics can be tested on the public Kaa Cloud installation.

  • MQTT host: mqtt://mqtt.cloud.kaaiot.com. The default port is 1883
  • MQTTS (MQTT over TLS) host: mqtts://mqtt.cloud.kaaiot.com. The default port is 8883

MQTT topic structure

MQTT topic structure:

kp1/{app_version_name}/{extension_instance_name}/{endpoint_token}/{resource_path}[/{request_id}]

where:

Every MQTT topic consists of next parts:

  • kp1 - Is constant and is the reserved prefix for the Kaa Protocol version 1.
  • {app_version_name} - The application version name where the endpoint is registered.
  • {extension_instance_name} - Is a name that uniquely identifies an extension the message is destined to (every device connectivity feature is backed by specific extension). It can be dcx that implements Data Collection feature, epmx that implements Endpoint Metadata Management feature, cex that implements Command Execution feature, etc.
  • {endpoint_token} - Is an endpoint token that uniquely identifies the endpoint, e.g. JTjdbENzHh. Decoupling endpoint tokens from IDs makes tokens disposable. You can revoke a lost or leaked endpoint token at any moment and issue a new one, retaining the same digital twin of your device with the same endpoint ID.
  • {resource_path} is an extension-specific resource path that exposes some IoT functionality to endpoints. For example, Data collection feature (dcx extension) has /json resource path that allows endpoints to push telemetry data into the platform; Endpoint Metadata Management (epmx extension) has /update/keys for updating endpoint metadata attributes, etc. Below we will list more examples of extensions and their resource paths.
  • {request_id} - This could be a random number between 1 and 99. Square brackets [/{request_id}] means that request ID is optional. In the MQTT request/response pattern section you will find the purpose of request ID.

MQTT request/response pattern

Many IoT functions require request/response style communication, which is not natively supported by MQTT. For that reason Kaa has the concept of request ID in the request MQTT topic. Whenever endpoint wants to use request/response pattern, it must append request ID to the end of the MQTT topic.

Successful responses to requests with the request ID arrive back to your client on the request topic with the /status suffix in the end. Error responses arrive at the request topic with the /error suffix.

Imagine that you want to receive confirmation messages that the submitted telemetry data is successfully processed and saved by Kaa platform. Then the MQTT topic you should use to publish telemetry data is NOT just kp1/clpg49rml4es7380a2bg-v1/dcx/JTjdbENzHh/json (request ID is absent), BUT kp1/clpg49rml4es7380a2bg-v1/dcx/JTjdbENzHh/json/42, where 42 is the request ID. Request IDs you use for outstanding requests from that endpoint to dcx service instance must be unique at any point in time so that you can properly match received responses.

42 is not a constant but just an example, and, coincidentally, the [“Answer to the Ultimate Question of Life, the Universe, and Everything”][42].

The response on successful data processing will arrive to the kp1/demo_application_v1/dcx/myToken/json/42/status MQTT topic. The response on unsuccessful data processing will arrive to the kp1/demo_application_v1/dcx/myToken/json/42/error MQTT topic.

Prerequisites

In the below section you can find Mosquitto examples of communication with the Kaa platform. To run these examples, export $APP_VERSION and $ENDPOINT_TOKEN with your application version and endpoint token respectively:

export APP_VERSION={app_version_name}
export ENDPOINT_TOKEN={endpoint_token}

Data collection

Send data samples

PUB kp1/{app_version_name}/dcx/{endpoint_token}/json[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1 -m '{
  "temperature": 21,
  "humidity": 73
}'

Publishes telemetry data to the platform in JSON format. This supports both single and batched messages sent as an array. Historical data is stored in two databases. For fast access to raw data, it’s stored in InfluxDB and is accessible via the time series REST API. Aggregated data is stored in OpenSearch, which operates on top of ElasticSearch, and can be accessed via the analytics REST API or Kibana.

When used with MQTT, you can optionally specify the “Request ID” to subscribe to the /status or /error topic to get the operation status. Alternatively, subscribe to kp1/{app_version_name}/dcx/{endpoint_token}/json/# to receive both status and error responses.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "2/DCP request schema",
  "type": "array"
}

Payload example for single data sample:

{
  "temperature": 21,
  "humidity": 73,
  "location": {
    "lat": 34.1340258,
    "lon": -118.3238652
  }
}

Use JSON array in order to send multiple data samples in one MQTT message. In the example below there is a batched payload with a predefined timestamp and two nested location JSON objects. Pay attention to the “ts” field, which is the timestamp for a sample and should be configured in Device management -> Applications -> your application -> “epts” (Kaa component that is responsible for time series processing). The “location” object should be configured as a custom Time series to value mapping in time series settings. The analytics storage may require you to specify the mapping to parse the string as a date. This can be configured in Data transformation -> Mappings.

Payload example for batch payload:

[
  {
    "ts": "2019-04-26T15:41:07+0000",
    "temperature": 21,
    "humidity": 73,
    "location": {
      "lat": 34.1340258,
      "lon": -118.3238652
    }
  },
  {
    "ts": "2019-04-26T16:41:07+0000",
    "temperature": 21.5,
    "humidity": 67,
    "location": {
      "lat": 34.1340258,
      "lon": -118.3238652
    }
  }
]

Subscribe status / error topics:

  • SUB kp1/bspu542ikfmmfgrk47s0-v1/dcx/{endpoint_token}/json[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1/status
  • SUB kp1/bspu542ikfmmfgrk47s0-v1/dcx/{endpoint_token}/json[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1/error

Send plain data samples

PUB kp1/{app_version_name}/dcx/{endpoint_token}/plain/{metric_name}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/plain/temperature -m '200'

Publish telemetry data to the platform in a plain format. Optionally, you can specify units in the value that will be mapped under the ${metric-name}-unit key. NOTE: It is required to enable Relaxed resource path validation under the Device management -> Applications -> your application -> “dcx” (Kaa component that is responsible for raw data samples processing).

Payload schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": [
        "number",
        "string"
    ]
}

Payload example:

200

Metadata

Get all metadata keys request

PUB kp1/{app_version_name}/epmx/{endpoint_token}/get/keys/{request ID}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys/1

Publish a message to request all endpoint metadata keys. Responses are available at the /status topic, and errors at the /error topic, both relative to this topic. Alternatively, subscribe to “kp1/{app_version_name}/epmx/{endpoint_token}/get/keys/#” to receive both status and error responses.

Response schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "10/EPMP get metadata keys response: a set of endpoint metadata keys",
    "type": "array",
    "items": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_]+$",
        "description": "Endpoint metadata key name"
    },
    "uniqueItems": true
}

Response example:

[
    "name",
    "location",
    "deviceModel"
]

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/get/keys/{request ID}/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys/1/status
  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/get/keys/{request ID}/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys/1/status -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys/1 -V 311

Get metadata request

PUB kp1/{app_version_name}/epmx/{endpoint_token}/get/{request ID}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/1

Publish the message to request all endpoint metadata. You need to subscribe to the response topic to get the result, which is at the /status ending relative to this topic.

Response schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "10/EPMP get metadata response: a set of EP metadata key-value pairs in JSON object representation",
    "type": "object",
    "patternProperties": {
        "^[a-zA-Z0-9_]+$": {}
    },
    "additionalProperties": false
}

Response example:

{
    "name": "Device name",
    "deviceModel": "new model"
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/get/{request ID}/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/1/status
  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/get/{request ID}/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/1/status -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/1 -V 311

Full metadata update

PUB kp1/{app_version_name}/epmx/{endpoint_token}/update[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/1 -m '{
  "deviceModel": "example model",
  "name": "Sensor 1"
}'

Update endpoint metadata with a set of key-value pairs in JSON object representation. When using with MQTT, optionally specify the “Request ID” to subscribe to the /status or /error topic to get the operation status.

Payload schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "10/EPMP update metadata request: a set of EP metadata key-value pairs in JSON object representation",
    "type": "object",
    "minProperties": 1,
    "patternProperties": {
        "^[a-zA-Z0-9_]+$": {}
    },
    "additionalProperties": false
}

Payload example

{
    "deviceModel": "example model",
    "name": "Sensor 1"
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/update[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/1/status
  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/update[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/1/status -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/1 -V 311 -m '{
  "deviceModel": "example model",
  "name": "Sensor 1"
}'

Partial metadata update

PUB kp1/{app_version_name}/epmx/{endpoint_token}/update/keys[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys/1 -m '{
  "deviceModel": "new model"
}'

Update endpoint metadata with a set of key-value pairs in JSON object representation. When using with MQTT optionally specify the “Request ID” to subscribe on /status or /error topic to get the operation status.

Payload schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "10/EPMP update metadata request: a set of EP metadata key-value pairs in JSON object representation",
    "type": "object",
    "minProperties": 1,
    "patternProperties": {
        "^[a-zA-Z0-9_]+$": {}
    },
    "additionalProperties": false
}

Payload example

{
    "deviceModel": "new model"
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/update/keys[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys/1/status
  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/update/keys[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys/1/status -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys/1 -V 311 -m '{
  "deviceModel": "new model"
}'

Delete metadata keys

PUB kp1/{app_version_name}/epmx/{endpoint_token}/delete/keys[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys/1 -m '[
  "location",
  "areaId"
]'

Delete endpoint metadata keys. When using with MQTT optionally specify the “Request ID” to subscribe on /status or /error topic to get the operation status.

Payload schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "10/EPMP delete metadata keys request",
    "type": "array",
    "items": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_]+$",
        "description": "Endpoint metadata key name"
    },
    "minItems": 1,
    "uniqueItems": true
}

Payload example

[
    "location",
    "areaId"
]

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/delete/keys[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys/1/status
  • SUB kp1/{app_version_name}/epmx/{endpoint_token}/delete/keys[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys/1/status -t kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys/1 -V 311 -m '[
  "location",
  "areaId"
]'

Command execution

Request pending commands

PUB kp1/{app_version_name}/cex/{endpoint_token}/command/{command_type}[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/<command_type>/1 -m '{
  "observe": true
}'

Request pending commands for the endpoint.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "title": "11/CEP command request schema",
    "type": "object",
    "properties": {
        "observe": {
            "type": "boolean",
            "description": "Whether to send upcoming command for this endpoint."
        }
    },
    "additionalProperties": false
}

Payload example

{
    "observe": true
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cex/{endpoint_token}/command/{command_type}[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/<command_type>/1/status
  • SUB kp1/{app_version_name}/cex/{endpoint_token}/command/{command_type}[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/<command_type>/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/<command_type>/1/status -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/<command_type>/1 -V 311 -m '{
  "observe": true
}'

Response schema:

{
    "$schema": "http://json-schema.org/schema#",
    "title": "11/CEP command request schema",
    "type": "object",
    "properties": {
        "observe": {
            "type": "boolean",
            "description": "Whether to send upcoming command for this endpoint."
        }
    },
    "additionalProperties": false
}

Response example:

{
    "observe": true
}

Report command execution result

PUB kp1/{app_version_name}/cex/{endpoint_token}/result/{command_type}[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/<command_type>/1 -m '[
  {
    "id": 1,
    "statusCode": 200,
    "reasonPhrase": "Ok",
    "payload": {
      "engine_on": true
    }
  }
]'

Report command execution result to the platform. Optionally specify the “Request ID” to subscribe on /error topic to get the operation status.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "title": "11/CEP result request schema",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "description": "ID of the command."
            },
            "statusCode": {
                "type": "integer",
                "description": "Status code of the command execution. Based on HTTP status codes."
            },
            "reasonPhrase": {
                "type": "string",
                "description": "Intended to give a short textual description of the status code."
            },
            "payload": {
                "description": "A command result payload to be interpreted by the caller."
            }
        },
        "required": [
            "id",
            "statusCode"
        ],
        "additionalProperties": false
    }
}

Payload example

[
    {
        "id": 1,
        "statusCode": 200,
        "reasonPhrase": "Ok",
        "payload": {
            "engine_on": true
        }
    }
]

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cex/{endpoint_token}/result/{command_type}[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/<command_type>/1/status
  • SUB kp1/{app_version_name}/cex/{endpoint_token}/result/{command_type}[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/<command_type>/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/<command_type>/1/status -t kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/<command_type>/1 -V 311 -m '[
  {
    "id": 1,
    "statusCode": 200,
    "reasonPhrase": "Ok",
    "payload": {
      "engine_on": true
    }
  }
]'

Configuration

Configuration resource request

PUB kp1/{app_version_name}/cmx/{endpoint_token}/config/json/{request ID}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json/1 -m '{
  "observe": false
}'

Request configuration by ID. When using with MQTT you need to subscribe to the response topic to get the result at /status ending relative to this topic.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "title": "7/CMP configuration request schema",
    "type": "object",
    "properties": {
        "configId": {
            "type": "string",
            "description": "Identifier of the currently applied configuration"
        },
        "observe": {
            "type": "boolean",
            "description": "Whether the endpoint is interested in observing its configuration"
        }
    },
    "additionalProperties": false
}

Payload example

{}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cmx/{endpoint_token}/config/json/{request ID}/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json/1/status
  • SUB kp1/{app_version_name}/cmx/{endpoint_token}/config/json/{request ID}/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json/1/status -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json/1 -V 311 -m '{
  "observe": false
}'

Response schema:

{
    "$schema": "http://json-schema.org/schema#",
    "title": "7/CMP configuration request schema",
    "type": "object",
    "properties": {
        "configId": {
            "type": "string",
            "description": "Identifier of the currently applied configuration"
        },
        "observe": {
            "type": "boolean",
            "description": "Whether the endpoint is interested in observing its configuration"
        }
    },
    "additionalProperties": false
}

Response example:

{
  "id": 42,
  "configId": "97016dbe8bb4adff8f754ecbf24612f2",
  "statusCode": 200,
  "reasonPhrase": "ok",
  "config": {
    "key": "value",
    "array": [
      "value2"
    ]
  }
}

Report applied configuration request

PUB kp1/{app_version_name}/cmx/{endpoint_token}/applied/json/{request ID}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json/1 -m '{
  "configId": "97016dbe8bb4adff8f754ecbf24612f2"
}'

Report applied configuration to the platform. Configuration can be rejected by sending the status code 400 or higher. When using MQTT you can subscribe to the response topic to get the result at /status ending relative to this topic.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "title": "7/CMX applied configuration request schema",
    "type": "object",
    "properties": {
        "configId": {
            "type": "string",
            "description": "Identifier of the applied configuration"
        },
        "statusCode": {
            "type": "number",
            "description": "Status code based on HTTP status codes",
            "default": 200
        },
        "reasonPhrase": {
            "type": "string",
            "description": "Human-readable string explaining the cause of an error (if any)"
        }
    },
    "required": [
        "configId"
    ],
    "additionalProperties": false
}

Payload example

{
    "configId": "97016dbe8bb4adff8f754ecbf24612f2"
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cmx/{endpoint_token}/applied/json/{request ID}/status 
    mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json/1/status
  • SUB kp1/{app_version_name}/cmx/{endpoint_token}/applied/json/{request ID}/error 
    mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json/1/status -t kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json/1 -V 311 -m '{
  "configId": "97016dbe8bb4adff8f754ecbf24612f2"
}'

Software OTA

Software resource request

PUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/config/json/{request ID}

mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json/1 -m '{
"observe": true
}'

Request the new firmware version for the endpoint. You need to subscribe to the response topic to get the result at /status ending relative to this topic.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "type": "object",
    "properties": {
        "observe": {
            "type": "boolean",
            "description": "Whether to send upcoming firmware updates for this endpoint."
        }
    },
    "additionalProperties": false
}

Payload example

{
    "observe": true
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/config/json/{request ID}/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json/1/status
  • SUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/config/json/{request ID}/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json/1/status -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json/1 -V 311 -m '{
"observe": true
}'

Response schema:

{
    "$schema": "http://json-schema.org/schema#",
    "type": "object",
    "properties": {
        "observe": {
            "type": "boolean",
            "description": "Whether to send upcoming firmware updates for this endpoint."
        }
    },
    "additionalProperties": false
}

Response example:

{
    "observe": true
}

Report applied software update request

PUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/applied/json/{request ID}

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/applied/json/1 -m '{
  "configId": "0.0.2"
}'

Report applied software update to the platform. Software update can be rejected by sending the status code 400 or higher. You need to subscribe to the response topic to get the result at /status ending relative to this topic.

Payload schema

{
    "$schema": "http://json-schema.org/schema#",
    "title": "7/CMX applied configuration request schema",
    "type": "object",
    "properties": {
        "configId": {
            "type": "string",
            "description": "Identifier of the applied configuration"
        },
        "statusCode": {
            "type": "number",
            "description": "Status code based on HTTP status codes",
            "default": 200
        },
        "reasonPhrase": {
            "type": "string",
            "description": "Human-readable string explaining the cause of an error (if any)"
        }
    },
    "required": [
        "configId"
    ],
    "additionalProperties": false
}

Payload example

{
    "configId": "0.0.2"
}

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/applied/json/{request ID}/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/applied/json/1/status
  • SUB kp1/{app_version_name}/cmx_ota/{endpoint_token}/applied/json/{request ID}/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/applied/json/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/applied/json/1/status -t kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/applied/json/1 -V 311 -m '{
  "configId": "0.0.2"
}'

Binary data upload

Get upload token

PUB kp1/{app_version_name}/bcx/{endpoint_token}/token[/{request ID}]

mosquitto_pub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token/1

Request the upload token for the endpoint to be used in “x-auth-token” header for upload binary blob data.

Subscribe status / error topics:

  • SUB kp1/{app_version_name}/bcx/{endpoint_token}/token[/{request ID}]/status
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token/1/status
  • SUB kp1/{app_version_name}/bcx/{endpoint_token}/token[/{request ID}]/error
mosquitto_sub -h mqtt.cloud.kaaiot.com -t kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token/1/error

Request/Response

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token/1/status -t kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token/1 -V 311

Response schema:

{
    "type": "object",
    "properties": {
        "token": {
            "type": "string",
            "description": "Access token to be used in \"x-auth-token\" header for upload binary blob data."
        }
    },
    "additionalProperties": false
}

Response example:

{
    "token": "2222"
}