MQTT client API

Description

The MQTT client API provides you with examples and specifications that makes it possible to directly control the MQTT (Message Queuing Telemetry Transport) messaging on your Axis device. This includes configuring the device to act as an MQTT client, which can then be connected to an MQTT broker to handle message exchanges.

For more information about MQTT brokers and how to connect them to Axis devices, see MQTT.

Model

The API implements client.cgi as its communications interface and supports the following methods:

Method	Description
`configureClient`	Configure the MQTT client.
`activateClient`	Activate the MQTT client.
`deactivateClient`	Deactivate the MQTT client.
`getClientStatus`	Return the client status.
`getSupportedVersions`	Retrieve API versions supported by the product.

Identification

API Discovery: id=mqtt-client

Common examples

MQTT client management

Use this example to exchange messages and data over MQTT. MQTT is based on two entities: the client and the broker. The client is able to send and receive messages, while the broker is responsible for routing said messages between different clients.

Configure the MQTT client

The first step to enable MQTT messaging is to configure the MQTT client, which includes all aspects such as the broker, security, protocol settings, last will testament, announcement, etc. To configure the client, a configureClient request should be sent.

1. Configure the MQTT client.

http://<servername>/axis-cgi/mqtt/client.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "configureClient",
  "params": {
    "server": {
      "protocol": "ssl",
      "host": "somebroker.somewhere.com",
      "port": 8883
    },

    "username": "user_1",
    "password": "password_1",
    "keepExistingPassword": false,
    "clientId": "unique_id_on_broker",
    "keepAliveInterval": 20,
    "connectTimeout": 30,
    "cleanSession": true,
    "autoReconnect": true,
    "deviceTopicPrefix": "some/topic/prefix",

    "lastWillTestament": {
      "useDefault": false,
      "topic": "Camera_1/ConnectionStatus",
      "message": "Connection Lost",
      "retain": true,
      "qos": 1
    },

    "connectMessage": {
      "useDefault": false,
      "topic": "Camera_1/ConnectionStatus",
      "message": "Connected",
      "retain": true,
      "qos": 1
    },

    "disconnectMessage": {
      "useDefault": false,
      "topic": "Camera_1/ConnectionStatus",
      "message": "Disconnected",
      "retain": true,
      "qos": 1
    },

    "ssl": {
      "validateServerCert": true
    }
  }
}

2. Parse the JSON response

Successful response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "configureClient",
  "data": {
  }
}

Failed response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "configureClient",
  "error": {
    "code": 1100,
    "message": "Internal Error"
  }
}

Activate the MQTT client

The client have two states: active and inactive. An active client is either trying to connect, or has already connected to a configured broker, while an inactive client does not have any effect, nor connection to the broker. To activate the client, an activateClient request should be sent. Please note that an active client remains active even after a reboot.

1. Activate the MQTT client.

http://<servername>/axis-cgi/mqtt/client.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "activateClient",
  "params": {
  }
}

2. Parse the JSON response.

Successful response

{
  "apiVersion": "1.0",
  "context": "come context",
  "method": "activateClient",
  "data": {
  }
}

Error response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "activateClient",
  "error": {
    "code": 1100,
    "message": "Internal Error"
  }
}

Deactivate the MQTT client

An activated MQTT can be turned off by sending a deactivation request, which will terminate the connection with the broker.

1. Deactivate the MQTT client instance.

http://<servername>/axis-cgi/mqtt/client.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "deactivateClient",
  "params": {
  }
}

2. Parse the JSON response.

Successful response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "deactivateClient",
  "data": {
  }
}

Error response

{
  "apiVersion": "1.0",
  "context": "somce context",
  "method": "deactivateClient",
  "error": {
    "code": 1100,
    "message": "Internal Error"
  }
}

Get the MQTT client status

The status of an MQTT client can be obtained by making a status request, where the response will contain the status and configuration.

1. Request the status of the MQTT client.

http://<servername>/axis-cgi/mqtt/client.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "getClientStatus",
  "params": {
  }
}

2. Parse the JSON response.

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "getClientStatus",
  "data": {
    "status": {
      "state": "inactive",
      "connectionStatus": "disconnected"
    },
    "config": {
      "server": {
        "protocol": "ssl",
        "host": "somebroker.somewhere.com",
        "port": 8883
      },
      "username": "user_1",
      "password": "*****",
      "clientId": "unique_id_on_broker",
      "keepAliveInterval": 20,
      "connectTimeout": 30,
      "cleanSession": true,
      "autoReconnect": true,
      "deviceTopicPrefix": "some/topic/prefix",
      "lastWillTestament": {
        "useDefault": false,
        "topic": "Camera_1/ConnectionStatus",
        "message": "Connection Lost",
        "retain": true,
        "qos": 1
      },
      "connectMessage": {
        "useDefault": false,
        "topic": "Camera_1/ConnectionStatus",
        "message": "Connected",
        "retain": true,
        "qos": 1
      },
      "disconnectMessage": {
        "useDefault": false,
        "topic": "Camera_1/ConnectionStatus",
        "message": "Disconnected",
        "retain": true,
        "qos": 1
      },
      "ssl": {
        "validateServerCert": true
      }
    }
  }
}

Get supported versions

Use this example to retrieve a list of API versions supported by your device.

1. Retrieve a list of supported API versions.

http://<servername>/axis-cgi/mqtt/client.cgi

JSON input parameters

{
  "context": "some context",
  "method": "getSupportedVersions"
}

2. Parse the JSON response.

Successful response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0"]
  }
}

Error response

{
  "apiVersion": "1.0",
  "context": "some context",
  "method": "getSupportedVersions",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

API specifications

configureClient

This API method is used when you want to configure the MQTT client.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/mqtt/client.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "configureClient",
  "params": {

    "server": {
      "protocol": <string>,
      "host": <string>,
      "port": <integer>,
      "basepath": <string>,
      "alpnProtocol": <string>
    },

    "httpProxy": <string>,
    "httpsProxy": <string>,
    "username": <string>,
    "password": <string>,
    "keepExistingPassword": <boolean>
    "clientId": <string>,
    "keepAliveInterval": <int>,
    "connectTimeout": <int>,
    "cleanSession": <boolean>,
    "autoReconnect": <boolean>,
    "deviceTopicPrefix": <string>,

    "lastWillTestament": {
      "useDefault": <boolean>,
      "topic": <string>,
      "message": <string>,
      "retain": <boolean>,
      "qos": <int>
    },

    "connectMessage": {
      "useDefault": <boolean>,
      "topic": <string>,
      "message": <string>,
      "retain": <boolean>,
      "qos": <int>
    },

    "disconnectMessage": {
      "useDefault": <boolean>,
      "topic": <string>,
      "message": <string>,
      "retain": <boolean>,
      "qos": <int>
    },
    "ssl": {
      "validateServerCert": <boolean>,
      "clientCertID": <string>,
      "CACertID": <string>
    }
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that should be used in the request.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The operation that should be performed.
`params.server`	Object	Contains the address and protocol related information. See sub fields for additional information.
`params.server.protocol`	String	Contains the protocols used by `params.server`. Possible values are: `tcp`: MQTT over TCP `ssl`: MQTT over SSL `ws`: MQTT over Websocket `wss`: MQTT over Websocket Secure
`params.server.host`	String	The Broker location, i.e. the Hostname or IP address.
`params.server.port`	Integer	The port that should be used (optional). Default values for the protocols are: `tcp`: `1883` `ssl`: `8883` `ws`: `80` `wss`: `443`
`params.server.basepath`	String	The path that should be used as a suffix for the constructed URL and will only be used for the `ws` and `wss` connections (optional). The default value is empty string.
`params.server.alpnProtocol`	String	The ALPN protocol that should be used if the selected protocol was ssl or wss (optional). If the string value is empty the ALPN will not be used. Default value is empty and the maximum length of the protocol is 255 bytes.
`params.httpProxy`	String	The HTTP proxy that should be used (optional). If the string value is empty the HTTP proxy will not be used. The maximum length of the proxy name is 255 bytes.
`params.httpsProxy`	String	The HTTPS proxy that should be used (optional). If the string value is empty the HTTPS proxy will not be used. The maximum length of the proxy name is 255 bytes.
`params.username`	String	The user name that should be used for authentication and authorization (optional).
`params.password`	String	The password that should be used for authentication (optional).
`params.keepExistingPassword`	Boolean	Specifies whether the stored password should be kept or erased. If set to `true` the previously stored password will be kept, while the password field will be discarded. When set to `false`, the given password will be used instead. (optional). The default value is `false`.
`params.clientId`	String	The client identifier sent to the server when the client connects to it.
`params.keepAliveInterval`	Integer	Defines the maximum time (in seconds) that should pass without communication between the client and server. At least one message will be sent over the network by the client during each keep alive period and the interval makes it possible to detect when the server is no longer available without having to wat for the TCP/IP timeout (optional). The default value is 60.
`params.connectTimeout`	Integer	The timed interval (in seconds) to allow a connect to finish (optional). The default value is 60.
`params.cleanSession`	Boolean	This parameter controls the behavior of both the client and the server during connection and disconnection time. When this parameters is true, the state information is discarded when the client and server change state. Setting the parameter to false means that the state information is kept.
`params.autoReconnect`	Boolean	Specifies if the client should reconnect on an unintentional disconnect (optional). The default value is true.
`params.deviceTopicPrefix`	String	Specifies a prefix on MQTT topics in various scenarios, such as when you want to configure the translation of events into MQTT messages or prefix all published MQTT messages with a common prefix (optional). The default value is axis/{device serial number}.
`params.lastWillTestament`	Object	Contains the options related to LWT. If LWT is not required, this parameter should not be included in the request (optional).
`params.lastWillTestament.useDefault`	Boolean	Specifies if the default LWT should be used. If set to true, other options in this parameter will be discarded. If set to false, topic, messages, retained and qos options are required and used. See Default LWT/Connected/Disconnected messages for default messages.
`params.lastWillTestament.topic`	String	The topic that should be used by LWT (optional). This field is only required if the useDefault option is set to false.
`params.lastWillTestament.message`	String	The content that should be used by LWT (optional). This field is only required if the useDefault option is set to false.
`params.lastWillTestament.retain`	Boolean	The retained option that should be used by LWT (optional). This field is only required if the useDefault option is set to false.
`params.lastWillTestament.qos`	Integer	The QoS option that should be used by LWT (optional). This field is only required if the useDefault option is set to false. Possible values are 0, 1, 2.
`params.connectMessage`	Object	Specifies if a message should be sent when a connection is established and contains options related to connect announcements (optional). If this object is not defined this message won’t be sent. For potential subfields, see `lastWillTestament`.
`params.disconnectMessage`	Object	Specifies if a message should be sent when the client is manually disconnected and contains options related to manual disconnect announcements (optional). If this object is not defined this message won’t be sent. This message should not be confused with LWT, as it is used when the connection is lost and managed by the broker. For potential subfields, see `lastWillTestament`.
`params.ssl`	Object	Contains the options related to the SSL connection (optional). This object should only be present if the connection type is `ssl` or `wss`.
`params.ssl.validateServerCert`	Boolean	Specifies if the server certificate shall be validated.
`params.ssl.clientCertID`	String	Specifies the client certificate and key that should be used. The certificates are managed through the user interface or via ONVIF services.
`params.ssl.CACertID`	String	Specifies the CA Certificate that should be used to validate the server certificate. The certificates are managed through the user interface or via ONVIF services.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body

{
  "apiVersion":"<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "data": {
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`data`	Object	An empty object.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`error.code`	Integer	The code representing the error that occurred in the request.
`error.message`	Integer	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

Default LWT/Connected/Disconnected messages

LWT message

Topic	`{device topic prefix}/event/connection`
Qos	1
Retained	Yes
Payload	`{ "serialNumber": "{device serial number}", "connected": false, "description": "Connection Lost", "timestamp": null }`

Connected message

Topic	`{device topic prefix}/event/connection`
Qos	1
Retained	Yes
Payload	`{ "serialNumber": "{device serial number}", "connected": true, "description": "Connected", "timestamp": "2020-09-04T11:02:55z" }`

Disconnected message

Topic	`{device topic prefix}/event/connection`
Qos	1
Retained	Yes
Payload	`{ "serialNumber": "{device serial number}", "connected": false, "description": "Disconnected", "timestamp": "2020-09-04T11:02:55z" }`

activateClient

This API method is used when you want to activate the MQTT client. Please note that this client will remain active after a reboot is not deactivated.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/mqtt/client.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "activateClient"
}

Parameter	Type	Description
`apiVersion`	String	The API version that should be used in the request.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The operation that should be performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "data": {
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`data`	Object	An empty object.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`error.code`	Integer	The code representing the error that occurred in the request.
`error.message`	Integer	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

deactivateClient

This API method is used when you want to deactivate the MQTT client.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/mqtt/client.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "deactivateClient"
}

Parameter	Type	Description
`apiVersion`	String	The API version that should be used in the request.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The operation that should be performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "data": {
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`data`	Object	An empty object.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`error.code`	Integer	The code representing the error that occurred in the request.
`error.message`	Integer	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

getClientStatus

This API method is used when you want to retrieve the status of the MQTT client.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/mqtt/client.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getClientStatus"
}

Parameter	Type	Description
`apiVersion`	String	The API version that should be used in the request.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The operation that should be performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getClientStatus",
  "data": {
    "status": {
      "state": <string>,
      "connectionStatus": <string>
    },
    "config": {
      <all options used when configuring the client>
    }
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`data.status.state`	String	The current state of the client. Possible values are `active` and `inactive`.
`data.status.connectionStatus`	String	The current connection state of your client. Possible values are `connected`, `disconnected`.
`data.config`	Object	Contains the settings used by your client. Its structure is the same as the one found in configureClient.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`error.code`	Integer	The code representing the error that occurred in the request.
`error.message`	Integer	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

getSupportedVersions

This API method is used when you want to retrieve a list of supported API versions.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/mqtt/client.cgi

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Parameter	Type	Description
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The operation that should be performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major1>.<Minor1>","<Major2>.<Minor2>"]
  }
}

Parameter	Type	Description
`context`	String	The context that was used when the request was made (optional).
`method`	String	The operation that was performed.
`data.apiVersions[]=<list of versions>`	String	Specifies the list of supported versions and includes all major versions together with their highest supported minor version.
`<list of versions>`	String	The list of ”<Major>.<Minor>” versions e.g. [“1.4”, “2.5”].

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used in the request.
`context`	String	The context that was used when the request was made.
`method`	String	The operation that was performed.
`error.code`	Integer	The code representing the error that occurred in the request.
`error.message`	Integer	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

Error codes

The error codes for this API are sorted into the following ranges:

1100–1199

Generic errors that are common to many API:s and reserved for server errors, e.g. “Maximum number of configurations reached”. The cause can be seen in the server log and the problems can in some cases be solved by restarting the device.

1200–1999

API-specific server errors.

2100–2199

Generic error codes common to many API:s and reserved for client errors, e.g. “Invalid parameter”. These errors can be solved by changing the input data to the API.

2200–2999

API-specific client errors. Codes in this range may collide between different API:s.

Code	Description
`1100`	Internal error
`2100`	API version not supported
`2101`	Invalid JSON format
`2102`	Method not supported
`2103`	Required parameter missing or invalid
`2104`	Invalid parameter value specified
`2105`	Authorization failure
`2106`	Request size too large