Relayr MQTT Broker 1.16.1

The relayr MQTT Broker allows your IoT devices to communicate with the relayr Cloud using the MQTT protocol.

On the relayr broker, messages can be published with QoS 0 or 1. The data published to the broker can be raw JSON data or compressed gzip JSON data for all topics.

Requirements

Authorization

Tools

Any MQTT client

Generated on Mon Oct 16 2023 15:54:57 GMT+0000 (Coordinated Universal Time)

Servers

cloud-mqtt.relayr.io:8883 mqtt 3.1.1

MQTT broker ingestion

Security:

User / Password:
Username and password obtained from the Cloud MQTT endpoints
X509:
X.509 Certificate

cloud-mqtt.prd.az.relayr.io:8883 mqtt 3.1.1

MQTT broker ingestion

Security:

User / Password:
Username and password obtained from the Cloud MQTT endpoints
X509:
X.509 Certificate

Operations

Pub devices/{deviceId}/alerts

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/alerts

Publish alert(s)

alerts

Payload

array<object>

message alertMessage

string

length <= 256 length >= 1

Optional alert message

name alertName

required

string

Name of the alert defined in device-model

state alertState

required

string

State of the alert (set/clear)

Enum: "set" "clear"

timestamp datetime

oneOf

Date and time of the message. We don't store data with higher precision than millisecond. Measurements sent for the same millisecond will overwrite each other. If it is a "number" it should be Unix timestamp in milliseconds. If it is a string, it should be ISO 8601 format.

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/alerts

Payload

[
  {
    "message": "temperature too high",
    "name": "temperature_high",
    "state": "set",
    "timestamp": 0
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/command_responses

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/command_responses

Publish command response(s)

commands

Payload

array<object>

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Command identifier

message commandMessage

string

length <= 256 length >= 1

Optional response message

status commandStatus

required

string

Command status

Enum: "in_progress" "success" "error"

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/command_responses

Payload

[
  {
    "id": "7f5bc456-21f2-4e9e-a38f-80baf762b1c5",
    "message": "message describing the command progress",
    "status": "in_progress",
    "timestamp": 0
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Sub devices/{deviceId}/commands

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/commands

Subscribe to device commands

commands

Commands can be sent and executed on devices through the Cloud command import endpoint and command execution endpoint.

Payload command

object

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Command identifier

name commandName

required

string

Name of the command defined in device-model

parameter commandParameter

oneOf

Parameter of the command (depending on device-model can be optional)

number

string

boolean

object

Additional properties are allowed.

array

Additional items are allowed.

timestamp datetime

required

oneOf

number

string

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/commands

Payload

{
  "deviceId": "d44d8a14-5fbb-4e4a-96a6-ed0c71c11fa8",
  "id": "7f5bc456-21f2-4e9e-a38f-80baf762b1c5",
  "name": "dim_light",
  "parameter": true,
  "timestamp": 0
}

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/config_requests

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/config_requests

Publish configuration request

configurations

Payload

array<object>

timestamp datetime

required

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/config_requests

Payload

[
  {
    "timestamp": 0
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/config_responses

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/config_responses

Publish configuration response(s)

configurations

Payload

array<object>

message configurationMessage

string

Optional response message

status configurationStatus

required

string

Status of the configuration

Enum: "success" "error"

timestamp datetime

oneOf

number

string

version configurationVersion

required

integer

Version of the configuration

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/config_responses

Payload

[
  {
    "message": "missing value x",
    "status": "error",
    "timestamp": 0,
    "version": 2
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Sub devices/{deviceId}/configs

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/configs

Subscribe to device configurations

configurations

Configurations can be sent to devices through the Cloud configuration endpoints.

Payload configuration

object

configuration configurationPayload

required

Payload of the configuration (any valid JSON)

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

version configurationVersion

required

integer

Version of the configuration

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/configs

Payload

{
  "configuration": {
    "maximum_temperature": 60
  },
  "deviceId": "d44d8a14-5fbb-4e4a-96a6-ed0c71c11fa8",
  "version": 2
}

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Sub devices/{deviceId}/errors

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/errors

Subscribe to device errors

errors

When malformed message is published it will be filtered out and rejected.
Reason for rejection can be obtained from the /errors topic.

Payload error

object

error errorContent

required

string

Human-readable error message

messageId errorMessageId

required

integer

Id of the message (for tracking purposes)

payload errorPayload

required

string

Payload of the message that caused the error (stringified)

topic errorTopic

required

string

Topic to which the malformed message was sent

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/errors

Payload

{
  "error": "command field 'id' is NOT an UUID",
  "messageId": 31248,
  "payload": "{'id':'not UUID','status':'in_progress'}",
  "topic": "devices/763c073a-e0ff-41a9-bd51-3386975ea4e3/commands"
}

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/installation_responses

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/installation_responses

Publish configuration response(s)

installations

Payload

array<object>

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Installation identifier

message installationMessage

string

length <= 256 length >= 1

Optional response message

status installationStatus

required

string

Status of the installation

Enum: "in_progress" "success" "error"

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/installation_responses

Payload

[
  {
    "id": "763c073a-e0ff-41a9-bd51-3386975ea4e3",
    "message": "message describing installation progress",
    "status": "in_progress",
    "timestamp": 0
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Sub devices/{deviceId}/installations

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/installations

Subscribe to device installations

installations

Installations can be sent to devices through the Cloud software installation endpoints.

Payload installation

object

buildStamp installationBuildStamp

string

a build stamp of the software to be installed

description installationDesc

string

Optional file description

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

fileName installationFile

string

Name of the installation file

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Installation identifier

location installationLocation

string

Location (url) of the installation file

signature installationSignature

string

Signature of the installation file

signatureType installationSignatureType

string

Type of the file signature

size installationSize

integer

Size of the installation file (bytes)

timestamp datetime

required

oneOf

number

string

type installationType

string

Type of the installation file

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/installations

Payload

{
  "buildStamp": "string",
  "description": "package.gwa-core-v1.1",
  "deviceId": "d44d8a14-5fbb-4e4a-96a6-ed0c71c11fa8",
  "fileName": "gwa-core.tgz",
  "id": "763c073a-e0ff-41a9-bd51-3386975ea4e3",
  "location": "http://foo.bar/buzz.xyz",
  "signature": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
  "signatureType": "sha-256",
  "size": 1048576,
  "timestamp": 0,
  "type": "gwa-core-package"
}

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/locations

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/locations

Location of the device

location

Device location is received from the device through MQTT and published to Kafka. Location service receives the Kafka message and updates the device location.

Payload

array<object>

address

string

length <= 200

address of device location

city

string

city of device location

country

string

Country code from ISO 3166-1 alpha-2 standard

latitude

required

number

>= -90 <= 90

number of degrees north

longitude

required

number

>= -180 <= 180

number of degrees east

timestamp datetime

oneOf

number

string

zipCode

string

zipCode of device location

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/locations

Payload

[
  {
    "address": "string",
    "city": "string",
    "country": "UA",
    "latitude": -90,
    "longitude": -180,
    "timestamp": 0,
    "zipCode": "string"
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/logs

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/logs

Publish device log(s)

logs

Payload

array<object>

level logLevel

required

integer

>= 0 <= 5

Level of log severity (0 - 5) 5 = trace 4 = debug 3 = minor 2 = major 1 = error 0 = critical

message logMessage

required

string

Log message

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/logs

Payload

[
  {
    "level": 2,
    "message": "Device has been restarted",
    "timestamp": 0
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Pub devices/{deviceId}/measurements

Parameters

deviceId deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Resource identifier

Accepts the following message:

devices/measurements

Publish measurement(s)

measurements

Measurements are sent in an array which contains one or more measurements for a single device. Measurements must be defined in the device model version.

Payload

array<object>

name measurementName

required

string

Name of the measurement defined in device-model

timestamp datetime

oneOf

number

string

value measurementValue

required

oneOf

Value of the measurement

number

boolean

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

Examples

devices/measurements

Payload

[
  {
    "name": "temperature",
    "timestamp": 0,
    "value": 36.6
  }
]

This example has been generated automatically.

Headers

{
  "qos": 1
}

This example has been generated automatically.

Messages

#1 devices/alerts

Publish alert(s)

alerts

Payload

array<object>

message alertMessage

string

length <= 256 length >= 1

Optional alert message

name alertName

required

string

Name of the alert defined in device-model

state alertState

required

string

State of the alert (set/clear)

Enum: "set" "clear"

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#2 devices/command_responses

Publish command response(s)

commands

Payload

array<object>

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Command identifier

message commandMessage

string

length <= 256 length >= 1

Optional response message

status commandStatus

required

string

Command status

Enum: "in_progress" "success" "error"

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#3 devices/commands

Subscribe to device commands

commands

Commands can be sent and executed on devices through the Cloud command import endpoint and command execution endpoint.

Payload command

object

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Command identifier

name commandName

required

string

Name of the command defined in device-model

parameter commandParameter

oneOf

Parameter of the command (depending on device-model can be optional)

number

string

boolean

object

Additional properties are allowed.

array

Additional items are allowed.

timestamp datetime

required

oneOf

number

string

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#4 devices/config_requests

Publish configuration request

configurations

Payload

array<object>

timestamp datetime

required

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#5 devices/config_responses

Publish configuration response(s)

configurations

Payload

array<object>

message configurationMessage

string

Optional response message

status configurationStatus

required

string

Status of the configuration

Enum: "success" "error"

timestamp datetime

oneOf

number

string

version configurationVersion

required

integer

Version of the configuration

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#6 devices/configs

Subscribe to device configurations

configurations

Configurations can be sent to devices through the Cloud configuration endpoints.

Payload configuration

object

configuration configurationPayload

required

Payload of the configuration (any valid JSON)

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

version configurationVersion

required

integer

Version of the configuration

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#7 devices/errors

Subscribe to device errors

errors

When malformed message is published it will be filtered out and rejected.
Reason for rejection can be obtained from the /errors topic.

Payload error

object

error errorContent

required

string

Human-readable error message

messageId errorMessageId

required

integer

Id of the message (for tracking purposes)

payload errorPayload

required

string

Payload of the message that caused the error (stringified)

topic errorTopic

required

string

Topic to which the malformed message was sent

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#8 devices/installation_responses

Publish configuration response(s)

installations

Payload

array<object>

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Installation identifier

message installationMessage

string

length <= 256 length >= 1

Optional response message

status installationStatus

required

string

Status of the installation

Enum: "in_progress" "success" "error"

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#9 devices/installations

Subscribe to device installations

installations

Installations can be sent to devices through the Cloud software installation endpoints.

Payload installation

object

buildStamp installationBuildStamp

string

a build stamp of the software to be installed

description installationDesc

string

Optional file description

deviceId

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Device identifier

fileName installationFile

string

Name of the installation file

required

string

uuid must match ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Installation identifier

location installationLocation

string

Location (url) of the installation file

signature installationSignature

string

Signature of the installation file

signatureType installationSignatureType

string

Type of the file signature

size installationSize

integer

Size of the installation file (bytes)

timestamp datetime

required

oneOf

number

string

type installationType

string

Type of the installation file

Additional properties are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#10 devices/locations

Location of the device

location

Device location is received from the device through MQTT and published to Kafka. Location service receives the Kafka message and updates the device location.

Payload

array<object>

address

string

length <= 200

address of device location

city

string

city of device location

country

string

Country code from ISO 3166-1 alpha-2 standard

latitude

required

number

>= -90 <= 90

number of degrees north

longitude

required

number

>= -180 <= 180

number of degrees east

timestamp datetime

oneOf

number

string

zipCode

string

zipCode of device location

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#11 devices/logs

Publish device log(s)

logs

Payload

array<object>

level logLevel

required

integer

>= 0 <= 5

Level of log severity (0 - 5) 5 = trace 4 = debug 3 = minor 2 = major 1 = error 0 = critical

message logMessage

required

string

Log message

timestamp datetime

oneOf

number

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.

#12 devices/measurements

Publish measurement(s)

measurements

Measurements are sent in an array which contains one or more measurements for a single device. Measurements must be defined in the device model version.

Payload

array<object>

name measurementName

required

string

Name of the measurement defined in device-model

timestamp datetime

oneOf

number

string

value measurementValue

required

oneOf

Value of the measurement

number

boolean

string

Additional items are allowed.

Headers

object

qos MQTTQoSHeader

number

int32

Quality of Service (0 - 1)

Enum: 1 0

Additional properties are allowed.