EdgeIQ Sevice MQTT Specification 0.1.2 documentation

EdgeIQ Sevice MQTT Specification 0.1.2

This is the EdgeIQ Device MQTT API specification. It describes the operations that can be performed on the EdgeIQ Device MQTT API.

Changelog

0.1.2 - Added description and examplesfor report and heartbeat message payload.
0.1.1 - Added description for username/password security scheme.
0.1.0 - Updated production broker endpoint to mqtt.edgeiq.io:443
0.0.1 - Initial Release

Servers

mqtts://mqtt.edgeiq.io:443/mqttsproduction
Production server, should be used for any new deployments. Offers higher security levels.
Security:
User/Password
Authentication using username and password.

Client ID must be in the format: <company_id>/<device_unique_id>/<client_name_and_version-string> (the <client_name_and_version-string> part can be left empty)

Username must be in the format: <company_id>/<device_unique_id>

Password: Your device MQTT password
#env:production
#visibility:public
mqtts://mqtt.ms-io.com:443/mqttsproduction-legacy
(Deprecated) Production server for legacy devices (Coda < 4.0). Only use for devices already deployed that cannot be updated to Coda > 4.0.
Security:
User/Password
Authentication using username and password.

Client ID must be in the format: <company_id>/<device_unique_id>/<client_name_and_version-string> (the <client_name_and_version-string> part can be left empty)

Username must be in the format: <company_id>/<device_unique_id>

Password: Your device MQTT password

Operations

RECEIVE d/{companyId}/{deviceId}/gateway_commands/{gatewayCommandType}
Receive standard gateway commands from the EdgeIQ cloud. The device must support all types of commands in order to be controllable via Symphony WebUI.
Operation IDReceiveGatewayCommand
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

gatewayCommandType
required
string
The type of gateway command.

object
qos
1
Accepts the following message:
Gateway Command MessageGatewayCommandMessage
This message is sent to the device when a gateway command is issued in the EdgeIQ cloud.
application/json
Message IDGatewayCommandMessage
object
command_type
string
The type of command.

Allowed values:
"software_update"
"lwm2m_request"
"lwm2m_file"
object
The payload that is sent to the device. Not all commands require a payload.

Additional properties are allowed.
object [GatewayCommandSchedule]
GatewayCommandSchedules define when a GatewayCommand can be executed. Note that this currently applies only to software update type gateway commands.

start_datetime
required
string
format: date-time
The beginning of the execution window

end_datetime
required
string
format: date-time
The end of the execution window

retry_interval
string
Defines when the execution window can be applied again. daily creates window the next day, weekly creates window the next week (same day of week). If omitted, only the original window will be observed.

Additional properties are allowed.
timeout
integer
The number of seconds before the command will be aborted.

device_id
string
The _id of the device that will receive the command.

settings_id
string
The _id of the setting that will receive the command.

command_id
string
The _id of the command that will receive the gateway command.

software_update_id
string
The _id of the software update to use for the command. This value is only required when issuing a software_update command.

array<string>
Allows for targeting specific attached device _id's via the gateway device.

Items:
string
object [Retry Options]
Options for retryable actions, e.g. gateway commands and commands. If null command will not be retried.

timeout
number
[ 60 .. 300 ]
Retry attempts will be abandoned once the timeout number of seconds is reached, if unable to execute command. May not apply to all types of commands.

Default value:180
max_retries
number
[ 1 .. 20 ]
Maximum number of times to retry.

Default value:5
object
Details about how to retry.

type
string
The strategy to use while retrying.

"" or none - do not retry

fixed - retry using a fixed period.

exponential_backoff - retry with a period that grows exponentially less frequent, according to a multiplier.

Default value:"none"
Allowed values:
""
"none"
"fixed"
"exponential_backoff"
fixed_interval
number
[ 60 .. 3600 ]
If type is fixed, this is the period of the retry in seconds. E.g. an interval of 180 will retry every three minutes.

Default value:180
exponential_base_interval
number
[ 60 .. 3600 ]
The starting interval in seconds for the period of an exponential_backoff type retry. E.g. a base interval of 180 will retry in three minutes the first time.

Default value:180
exponential_multiplier
number
[ 2 .. 10 ]
The multiplier indicating how much to increase each exponential_backoff type retry. E.g. with a base interval of 180 and a multiplier of 2, the first retry will be after three minutes, then six, then 12, 24, and so on.

Default value:2
exponential_max_interval
number
[ 300 .. 86400 ]
The maximum interval in seconds for an exponential_backoff type retry.

Default value:3600
Additional properties are allowed.
Additional properties are allowed.
type
string
The type of LWM2M command (use only with command_type lwm2m_request or lwm2m_file). For lwm2m_request:

'read', 'observe', 'observe_stop', 'exec' you must specify the LWM2M path in the field 'endpoint'

'write' the path in 'endpoint' and the value in the field 'data'

For lwm2m_file:

'fileupload' to push a file to the device, you must specify the file id in the field 'file_id' and the file path on the device in the field 'filepath'

'filedownload' to get a file from the device, you must specify the file path on the device in the field 'filepath'.

Allowed values:
"read"
"write"
"execute"
"observe"
"observe_stop"
"download"
"fileupload"
"filedownload"
endpoint
string
the LWM2M path targeted by a gateway_command of type lwm2m_request

oneOf
the value for a LWM2M command of type 'write'

Adheres to:
string
Or to:
number
Or to:
boolean
filepath
string
for command of type 'lwm2m_file' the path of the file to retrieve or replace on a device

file_id
string
for command of type 'lwm2m_file' and type 'fileupload', the identifier of the file to be pushed to the device

Additional properties are allowed.
Examples
{ "command_type": "software_update", "payload": {}, "schedule": { "start_datetime": "2019-08-24T14:15:22Z", "end_datetime": "2019-08-24T14:15:22Z", "retry_interval": "string" }, "timeout": 0, "device_id": "string", "settings_id": "string", "command_id": "string", "software_update_id": "string", "attached_device_ids": [ "string" ], "retry_options": { "timeout": 180, "max_retries": 5, "retry_strategy": { "type": "", "fixed_interval": 180, "exponential_base_interval": 180, "exponential_multiplier": 2, "exponential_max_interval": 3600 } }, "type": "read", "endpoint": "string", "data": "string", "filepath": "string", "file_id": "string" }

This example has been generated automatically.
RECEIVE d/{companyId}/{deviceId}/commands/{userDefinedCommandId}
Receive custom user-defined commands from the EdgeIQ cloud.
Operation IDReceiveUserDefinedCommand
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

userDefinedCommandId
required
string
The ID of the user-defined command.

object
qos
1
Accepts the following message:
User-Defined Command MessageUserDefinedCommandMessage
This message is sent to the device when a user-defined command is issued in the EdgeIQ cloud.
application/json
Message IDUserDefinedCommandMessage
restricted any
_id
read-only
string
A unique id for this Command.

name
required
string
The name of the command.

device_id
string
The id of the device to which this command will be sent. This may be omitted until the command is executed.

sender_type
required
string
The type of sender used to send the command.

Allowed values:
"tcp_sender"
"http_sender"
"dev_sender"
"rest_fwd_sender"
"plugin_sender"
"shell_sender"
"opcua_sender"
"modbus_sender"
"bacnet_sender"
object
The sender (as specified by sender_type) used to send the command.

Additional properties are allowed.
translator_id
string
The id of the translator used to translate the command payload into the data format expected by the recipient device. This can be omitted if a translator is not needed to process and send the command.

long_description
string
A long description of the command. This field is intended to be populated with instructions on how to send the command. These instructions can then be displayed to users of an application.

object
A JSON object containing metadata needed to process and send the command. This field is not used by commands sent directly by Edge (but may optionally be used by REST Command forwarders and plugins).

Additional properties are allowed.
payload
string
A JSON object containing all of the data that will comprise the actual message sent to the recipient device. This payload is the input to the translator.

Examples
{ "_id": "string", "name": "string", "device_id": "string", "sender_type": "tcp_sender", "sender": {}, "translator_id": "string", "long_description": "string", "options": {}, "payload": "string" }

This example has been generated automatically.
RECEIVE d/{companyId}/{deviceId}/escrow
Receive escrow message from the EdgeIQ cloud.
Operation IDReceiveEscrow
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Escrow MessageEscrowMessage
This message sent to the device when a escrow is flow execution starter in the EdgeIQ cloud.
application/text
Message IDEscrowMessage
Payload
string
The Company ID

Examples
string

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/config
Request the gateway configuration from the EdgeIQ cloud. Device must request the configuration right after connection establishment.
Operation IDSendGatewayConfig
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Gateway Config Request MessageGatewayConfigRequestMessage
A message to request the gateway configuration
application/json
Message IDGatewayConfigRequestMessage
object
config_version
integer
The version of the configuration

Default value:3
requested
boolean
Whether the configuration is requested

Default value:true
Additional properties are allowed.
Examples
{ "config_version": 3, "requested": true }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/action
Send an action to the cloud.
Operation IDSendUpstreamActionRequest
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Upstream Action MessageUpstreamActionMessage
A message to send an action to the cloud
application/json
Message IDUpstreamActionMessage
object
device_id
string
The device id

name
string
The name of the action

type
string
The type of the action

Allowed values:
"http_request"
"greengrass_redeploy"
object
Payload of the action

Additional properties are allowed.
Additional properties are allowed.
Examples
{ "device_id": "string", "name": "string", "type": "http_request", "action": {} }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/status
Send the status of the device to the cloud. Device must send the status right after connection establishment.
Operation IDSendStatus
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Send Status MessageStatusMessage
A message to send the status of the device to the cloud
application/json
Message IDStatusMessage
object
object
received
boolean
valid
boolean
configured
boolean
greengrass_installed
required
boolean
Additional properties are allowed.
edge_version
string
firmware_version
string
platform_tag
string
array<string>
Items:
string
serial
string
object
lat
required
number
long
required
number
Additional properties are allowed.
object
Additional properties are allowed.
object
status_type
string
Allowed values:
"info"
"warning"
"error"
message
string
timestamp
number
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "config_status": { "received": true, "valid": true, "configured": true, "greengrass_installed": true }, "edge_version": "string", "firmware_version": "string", "platform_tag": "string", "build_tags": [ "string" ], "serial": "string", "gps": { "lat": 0, "long": 0 }, "connections_status": {}, "status_messages": { "status_type": "info", "message": "string", "timestamp": 0 } }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/reports/hb
Send the device heartbeat report to the cloud. Device must send the heartbeat report periodically based on the configuration.
Operation IDSendHeartbeat
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Device Heartbeat MessageHeartbeatMessage
A message the device sends to the cloud to report its operational metrics. Note that numerical values submitted as strings.
application/json
Message IDHeartbeatMessage
object
status
string
The status of the device (optional).

edge_version
string
The version of the EdgeIQ Coda Agent (optional).

cell_signal
string
The cell signal strength of the device (optional).

cell_usage
string
The cell usage of the device (optional).

sim_card
string
The SIM card of the device (optional).

object
The connections of the device (optional).

Additional properties:
string
array<string>
The wifi clients of the device (optional).

Items:
string
cpu_usage
string
The CPU usage of the device (optional).

ram_usage
string
The RAM usage of the device (optional).

disk_size
string
The disk size of the device (optional).

disk_free
string
The free disk space of the device (optional).

disk_usage
string
The disk usage of the device (optional).

seq
string
The sequence number of the heartbeat (optional).

array<string>
The IP addresses of the device (optional).

Items:
string
object
The custom properties of the device (optional).

Additional properties:
string
online
boolean
Whether the device is online (optional).

object
Used for attached sensors. The last endpoint report at (optional).

Additional properties:
string
Additional properties are allowed.
Examples
#1 Example - Heartbeat with device metrics
{ "ram_usage": "10.2", "cpu_usage": "65.1", "disk_usage": "23.7", "disk_free": "76.3" }
SEND u/{companyId}/{deviceId}/reports
Send the device report to the cloud. Device must send the report after gateway command execution. Device must send the report periodically based on the configuration.
Operation IDSendReport
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Device Report MessageReportMessage
A message containing device report data
application/json
Message IDReportMessage
object
id
string
The unique identifier for the report (optional).

device_datetime
string
format: date-time
The date and time the report was created on the device (optional).

created_at
string
format: date-time
The date and time the report was processed on the cloud (generated).

object
non-empty
The payload of the report (JSON).

Additional properties are allowed.
device_id
string
The unique id or database id of the device (optional). If not provided, the device_unique_id will be used or the device unique id will be derived from the topic name.

device_unique_id
string
The unique identifier for the device (optional). If not provided, the device_id will be used or the device unique id will be derived from the topic name. The device unique id can be set to the id of an attached sensor to relay messages on their behalf.

raw_data
string
The raw data of the report (optional).

seq
integer
The sequence number of the report (optional).

source_id
string
The source id of the report (optional).

Additional properties:
any
Additional properties are allowed but may be ignored by the system.

Examples
#1 Example - Simple Report
{ "temperature": 31.2, "humidity": 50 }

#2 Example - Report on behalf of a sensor
{ "device_unique_id": "sensor_1234567890", "temperature": 31.2, "humidity": 50 }

#3 Example - Report with JSON object payload
{ "temperature": 31.2, "humidity": 50, "power_usage": { "voltage": 120, "current": 10.5, "power": 1260 } }
SEND u/{companyId}/{deviceId}/command_execution_status
Send the status of the user-defined command execution to the cloud. Device must send the status of the user-defined command execution after command execution.
Operation IDSendUserDefinedCommandExecutionStatus
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Command Execution Status MessageCommandExecutionStatusMessage
A message containing terminal data
application/json
Message IDCommandExecutionStatusMessage
object
id
required
string
The unique identifier for the command execution status.

execution_id
string
The unique identifier for the execution.

status
required
string
The status of the command execution.

Allowed values:
"initiated"
"info"
"success"
"error"
message
string
The message associated with the command execution status.

created_at
required
string
format: date-time
The time the command execution status was created.

updated_at
required
string
format: date-time
The time the command execution status was last updated.

Additional properties are allowed.
Examples
{ "id": "string", "execution_id": "string", "status": "initiated", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/error
Send the error message to the cloud. Device must send the error message when an error occurs.
Operation IDSendError
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Error MessageErrorMessage
A message containing error data
application/json
Message IDErrorMessage
object
type
required
string
The type of the error.

level
required
number
The level of the error.

error
required
string
The error message.

Additional properties are allowed.
Examples
{ "type": "string", "level": 0, "error": "string" }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/reported_settings
Send the self-reported setting to the cloud.
Operation IDSendSelfReportedSetting
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Self Reported Setting MessageSelfReportedSettingMessage
A message to send the self-reported setting to the cloud
application/json
Message IDSelfReportedSettingMessage
object allOf
configurationUniqueIdentifier
string
Unique identifier for the configuration

deviceUniqueId
string
Unique identifier for the device

object allOf
version
integer
Version of the setting

name
string
Name of the setting

configurationId
string
Configuration ID of the setting

description
string
Description of the setting

object
Values of the setting

Additional properties are allowed.
array<object>
object
id
string
ID of the device type

name
string
Name of the device type

description
string
Description of the device type

enforceSecureMQTT
boolean
Indicates if secure MQTT is enforced

Additional properties are allowed.
array<object>
object
id
string
ID of the device

name
string
Name of the device

description
string
Description of the device

Additional properties are allowed.
isSelfReported
boolean
Indicates if the setting is self-reported

object
id
string
ID of the base string

origin
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
createdAt
string
format: date-time
Creation timestamp

updatedAt
string
format: date-time
Last update timestamp

companyId
string
Company ID related to the base string

userId
string
User ID related to the base string

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "configurationUniqueIdentifier": "string", "deviceUniqueId": "string", "version": 0, "name": "string", "configurationId": "string", "description": "string", "values": {}, "deviceTypes": [ { "id": "string", "name": "string", "description": "string", "enforceSecureMQTT": true } ], "devices": [ { "id": "string", "name": "string", "description": "string" } ], "isSelfReported": true, "id": "string", "origin": "edge", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "companyId": "string", "userId": "string" }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/gateway_command_status
Send the status of the gateway command execution to the cloud. Device must send the status of the gateway command execution after command execution.
Operation IDSendGatewayCommandStatus
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Gateway Command Status MessageGatewayCommandStatusMesssage
A message to send the status of the gateway command execution to the cloud
application/json
Message IDGatewayCommandStatusMesssage
object
id
required
string
The unique identifier for the command execution.

required
object
object
status
string
The status of the command execution.

error
string
Error message if the command failed.

Additional properties are allowed.
Additional properties are allowed.
Examples
{ "id": "string", "statuses": { "property1": { "status": "string", "error": "string" }, "property2": { "status": "string", "error": "string" } } }

This example has been generated automatically.
SEND u/{companyId}/{deviceId}/escrow_request
Send the escrow request to the cloud.
Operation IDSendEscrowRequest
Available only on servers:
- production
- production-legacy
object
companyId
required
string
The ID of the company which the device belongs to.

deviceId
required
string
The unique ID of the device.

object
qos
1
Accepts the following message:
Escrow Request MessageEscrowRequestMessage
This message device sent to EdgeIQ cloud to start the escrow flow.
application/text
Message IDEscrowRequestMessage
Payload
string
empty body

Examples
string

This example has been generated automatically.

Messages

#1Gateway Command MessageGatewayCommandMessage
This message is sent to the device when a gateway command is issued in the EdgeIQ cloud.
- application/json
Message IDGatewayCommandMessage
object
command_type
string
The type of command.

Allowed values:
"software_update"
"lwm2m_request"
"lwm2m_file"
object
The payload that is sent to the device. Not all commands require a payload.

Additional properties are allowed.
object [GatewayCommandSchedule]
GatewayCommandSchedules define when a GatewayCommand can be executed. Note that this currently applies only to software update type gateway commands.

start_datetime
required
string
format: date-time
The beginning of the execution window

end_datetime
required
string
format: date-time
The end of the execution window

retry_interval
string
Defines when the execution window can be applied again. daily creates window the next day, weekly creates window the next week (same day of week). If omitted, only the original window will be observed.

Additional properties are allowed.
timeout
integer
The number of seconds before the command will be aborted.

device_id
string
The _id of the device that will receive the command.

settings_id
string
The _id of the setting that will receive the command.

command_id
string
The _id of the command that will receive the gateway command.

software_update_id
string
The _id of the software update to use for the command. This value is only required when issuing a software_update command.

array<string>
Allows for targeting specific attached device _id's via the gateway device.

Items:
string
object [Retry Options]
Options for retryable actions, e.g. gateway commands and commands. If null command will not be retried.

timeout
number
[ 60 .. 300 ]
Retry attempts will be abandoned once the timeout number of seconds is reached, if unable to execute command. May not apply to all types of commands.

Default value:180
max_retries
number
[ 1 .. 20 ]
Maximum number of times to retry.

Default value:5
object
Details about how to retry.

type
string
The strategy to use while retrying.

"" or none - do not retry

fixed - retry using a fixed period.

exponential_backoff - retry with a period that grows exponentially less frequent, according to a multiplier.

Default value:"none"
Allowed values:
""
"none"
"fixed"
"exponential_backoff"
fixed_interval
number
[ 60 .. 3600 ]
If type is fixed, this is the period of the retry in seconds. E.g. an interval of 180 will retry every three minutes.

Default value:180
exponential_base_interval
number
[ 60 .. 3600 ]
The starting interval in seconds for the period of an exponential_backoff type retry. E.g. a base interval of 180 will retry in three minutes the first time.

Default value:180
exponential_multiplier
number
[ 2 .. 10 ]
The multiplier indicating how much to increase each exponential_backoff type retry. E.g. with a base interval of 180 and a multiplier of 2, the first retry will be after three minutes, then six, then 12, 24, and so on.

Default value:2
exponential_max_interval
number
[ 300 .. 86400 ]
The maximum interval in seconds for an exponential_backoff type retry.

Default value:3600
Additional properties are allowed.
Additional properties are allowed.
type
string
The type of LWM2M command (use only with command_type lwm2m_request or lwm2m_file). For lwm2m_request:

'read', 'observe', 'observe_stop', 'exec' you must specify the LWM2M path in the field 'endpoint'

'write' the path in 'endpoint' and the value in the field 'data'

For lwm2m_file:

'fileupload' to push a file to the device, you must specify the file id in the field 'file_id' and the file path on the device in the field 'filepath'

'filedownload' to get a file from the device, you must specify the file path on the device in the field 'filepath'.

Allowed values:
"read"
"write"
"execute"
"observe"
"observe_stop"
"download"
"fileupload"
"filedownload"
endpoint
string
the LWM2M path targeted by a gateway_command of type lwm2m_request

oneOf
the value for a LWM2M command of type 'write'

Adheres to:
string
Or to:
number
Or to:
boolean
filepath
string
for command of type 'lwm2m_file' the path of the file to retrieve or replace on a device

file_id
string
for command of type 'lwm2m_file' and type 'fileupload', the identifier of the file to be pushed to the device

Additional properties are allowed.
#2User-Defined Command MessageUserDefinedCommandMessage
This message is sent to the device when a user-defined command is issued in the EdgeIQ cloud.
- application/json
Message IDUserDefinedCommandMessage
restricted any
_id
read-only
string
A unique id for this Command.

name
required
string
The name of the command.

device_id
string
The id of the device to which this command will be sent. This may be omitted until the command is executed.

sender_type
required
string
The type of sender used to send the command.

Allowed values:
"tcp_sender"
"http_sender"
"dev_sender"
"rest_fwd_sender"
"plugin_sender"
"shell_sender"
"opcua_sender"
"modbus_sender"
"bacnet_sender"
object
The sender (as specified by sender_type) used to send the command.

Additional properties are allowed.
translator_id
string
The id of the translator used to translate the command payload into the data format expected by the recipient device. This can be omitted if a translator is not needed to process and send the command.

long_description
string
A long description of the command. This field is intended to be populated with instructions on how to send the command. These instructions can then be displayed to users of an application.

object
A JSON object containing metadata needed to process and send the command. This field is not used by commands sent directly by Edge (but may optionally be used by REST Command forwarders and plugins).

Additional properties are allowed.
payload
string
A JSON object containing all of the data that will comprise the actual message sent to the recipient device. This payload is the input to the translator.
#3Terminal Control MessageTerminalControlMessage
A message to control the terminal
- application/json
Message IDTerminalControlMessage
object
t
string
Allowed values:
"cc"
"cr"
"i"
"o"
subtype
string
Allowed values:
"ping"
"pong"
"resize"
"status"
object
status
string
Allowed values:
"exited"
"killed"
"crashed"
"hanging"
"running"
"disconnected"
message
string
Additional properties are allowed.
Additional properties are allowed.
#4Terminal Data MessageTerminalDataMessage
A message containing terminal data
- application/octet-stream
Message IDTerminalDataMessage
Payload
string
format: binary
Binary data for the terminal
#5Error MessageErrorMessage
A message containing error data
- application/json
Message IDErrorMessage
object
type
required
string
The type of the error.

level
required
number
The level of the error.

error
required
string
The error message.

Additional properties are allowed.
#6Command Execution Status MessageCommandExecutionStatusMessage
A message containing terminal data
- application/json
Message IDCommandExecutionStatusMessage
object
id
required
string
The unique identifier for the command execution status.

execution_id
string
The unique identifier for the execution.

status
required
string
The status of the command execution.

Allowed values:
"initiated"
"info"
"success"
"error"
message
string
The message associated with the command execution status.

created_at
required
string
format: date-time
The time the command execution status was created.

updated_at
required
string
format: date-time
The time the command execution status was last updated.

Additional properties are allowed.
#7Device Heartbeat MessageHeartbeatMessage
A message the device sends to the cloud to report its operational metrics. Note that numerical values submitted as strings.
- application/json
Message IDHeartbeatMessage
object
status
string
The status of the device (optional).

edge_version
string
The version of the EdgeIQ Coda Agent (optional).

cell_signal
string
The cell signal strength of the device (optional).

cell_usage
string
The cell usage of the device (optional).

sim_card
string
The SIM card of the device (optional).

object
The connections of the device (optional).

Additional properties:
string
array<string>
The wifi clients of the device (optional).

Items:
string
cpu_usage
string
The CPU usage of the device (optional).

ram_usage
string
The RAM usage of the device (optional).

disk_size
string
The disk size of the device (optional).

disk_free
string
The free disk space of the device (optional).

disk_usage
string
The disk usage of the device (optional).

seq
string
The sequence number of the heartbeat (optional).

array<string>
The IP addresses of the device (optional).

Items:
string
object
The custom properties of the device (optional).

Additional properties:
string
online
boolean
Whether the device is online (optional).

object
Used for attached sensors. The last endpoint report at (optional).

Additional properties:
string
Additional properties are allowed.
#8Device Report MessageReportMessage
A message containing device report data
- application/json
Message IDReportMessage
object
id
string
The unique identifier for the report (optional).

device_datetime
string
format: date-time
The date and time the report was created on the device (optional).

created_at
string
format: date-time
The date and time the report was processed on the cloud (generated).

object
non-empty
The payload of the report (JSON).

Additional properties are allowed.
device_id
string
The unique id or database id of the device (optional). If not provided, the device_unique_id will be used or the device unique id will be derived from the topic name.

device_unique_id
string
The unique identifier for the device (optional). If not provided, the device_id will be used or the device unique id will be derived from the topic name. The device unique id can be set to the id of an attached sensor to relay messages on their behalf.

raw_data
string
The raw data of the report (optional).

seq
integer
The sequence number of the report (optional).

source_id
string
The source id of the report (optional).

Additional properties:
any
Additional properties are allowed but may be ignored by the system.
#9Send Status MessageStatusMessage
A message to send the status of the device to the cloud
- application/json
Message IDStatusMessage
object
object
received
boolean
valid
boolean
configured
boolean
greengrass_installed
required
boolean
Additional properties are allowed.
edge_version
string
firmware_version
string
platform_tag
string
array<string>
Items:
string
serial
string
object
lat
required
number
long
required
number
Additional properties are allowed.
object
Additional properties are allowed.
object
status_type
string
Allowed values:
"info"
"warning"
"error"
message
string
timestamp
number
Additional properties are allowed.
Additional properties are allowed.
#10Upstream Action MessageUpstreamActionMessage
A message to send an action to the cloud
- application/json
Message IDUpstreamActionMessage
object
device_id
string
The device id

name
string
The name of the action

type
string
The type of the action

Allowed values:
"http_request"
"greengrass_redeploy"
object
Payload of the action

Additional properties are allowed.
Additional properties are allowed.
#11Gateway Config Request MessageGatewayConfigRequestMessage
A message to request the gateway configuration
- application/json
Message IDGatewayConfigRequestMessage
object
config_version
integer
The version of the configuration

Default value:3
requested
boolean
Whether the configuration is requested

Default value:true
Additional properties are allowed.
#12Self Reported Setting MessageSelfReportedSettingMessage
A message to send the self-reported setting to the cloud
- application/json
Message IDSelfReportedSettingMessage
object allOf
configurationUniqueIdentifier
string
Unique identifier for the configuration

deviceUniqueId
string
Unique identifier for the device

object allOf
version
integer
Version of the setting

name
string
Name of the setting

configurationId
string
Configuration ID of the setting

description
string
Description of the setting

object
Values of the setting

Additional properties are allowed.
array<object>
object
id
string
ID of the device type

name
string
Name of the device type

description
string
Description of the device type

enforceSecureMQTT
boolean
Indicates if secure MQTT is enforced

Additional properties are allowed.
array<object>
object
id
string
ID of the device

name
string
Name of the device

description
string
Description of the device

Additional properties are allowed.
isSelfReported
boolean
Indicates if the setting is self-reported

object
id
string
ID of the base string

origin
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
createdAt
string
format: date-time
Creation timestamp

updatedAt
string
format: date-time
Last update timestamp

companyId
string
Company ID related to the base string

userId
string
User ID related to the base string

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#13Gateway Command Status MessageGatewayCommandStatusMesssage
A message to send the status of the gateway command execution to the cloud
- application/json
Message IDGatewayCommandStatusMesssage
object
id
required
string
The unique identifier for the command execution.

required
object
object
status
string
The status of the command execution.

error
string
Error message if the command failed.

Additional properties are allowed.
Additional properties are allowed.
#14Escrow MessageEscrowMessage
This message sent to the device when a escrow is flow execution starter in the EdgeIQ cloud.
- application/text
Message IDEscrowMessage
Payload
string
The Company ID
#15Escrow Request MessageEscrowRequestMessage
This message device sent to EdgeIQ cloud to start the escrow flow.
- application/text
Message IDEscrowRequestMessage
Payload
string
empty body

Schemas

object
command_type
string
The type of command.

Allowed values:
"software_update"
"lwm2m_request"
"lwm2m_file"
object
The payload that is sent to the device. Not all commands require a payload.

Additional properties are allowed.
object [GatewayCommandSchedule]
GatewayCommandSchedules define when a GatewayCommand can be executed. Note that this currently applies only to software update type gateway commands.

start_datetime
required
string
format: date-time
The beginning of the execution window

end_datetime
required
string
format: date-time
The end of the execution window

retry_interval
string
Defines when the execution window can be applied again. daily creates window the next day, weekly creates window the next week (same day of week). If omitted, only the original window will be observed.

Additional properties are allowed.
timeout
integer
The number of seconds before the command will be aborted.

device_id
string
The _id of the device that will receive the command.

settings_id
string
The _id of the setting that will receive the command.

command_id
string
The _id of the command that will receive the gateway command.

software_update_id
string
The _id of the software update to use for the command. This value is only required when issuing a software_update command.

array<string>
Allows for targeting specific attached device _id's via the gateway device.

Items:
string
object [Retry Options]
Options for retryable actions, e.g. gateway commands and commands. If null command will not be retried.

timeout
number
[ 60 .. 300 ]
Retry attempts will be abandoned once the timeout number of seconds is reached, if unable to execute command. May not apply to all types of commands.

Default value:180
max_retries
number
[ 1 .. 20 ]
Maximum number of times to retry.

Default value:5
object
Details about how to retry.

type
string
The strategy to use while retrying.

"" or none - do not retry

fixed - retry using a fixed period.

exponential_backoff - retry with a period that grows exponentially less frequent, according to a multiplier.

Default value:"none"
Allowed values:
""
"none"
"fixed"
"exponential_backoff"
fixed_interval
number
[ 60 .. 3600 ]
If type is fixed, this is the period of the retry in seconds. E.g. an interval of 180 will retry every three minutes.

Default value:180
exponential_base_interval
number
[ 60 .. 3600 ]
The starting interval in seconds for the period of an exponential_backoff type retry. E.g. a base interval of 180 will retry in three minutes the first time.

Default value:180
exponential_multiplier
number
[ 2 .. 10 ]
The multiplier indicating how much to increase each exponential_backoff type retry. E.g. with a base interval of 180 and a multiplier of 2, the first retry will be after three minutes, then six, then 12, 24, and so on.

Default value:2
exponential_max_interval
number
[ 300 .. 86400 ]
The maximum interval in seconds for an exponential_backoff type retry.

Default value:3600
Additional properties are allowed.
Additional properties are allowed.
type
string
The type of LWM2M command (use only with command_type lwm2m_request or lwm2m_file). For lwm2m_request:

'read', 'observe', 'observe_stop', 'exec' you must specify the LWM2M path in the field 'endpoint'

'write' the path in 'endpoint' and the value in the field 'data'

For lwm2m_file:

'fileupload' to push a file to the device, you must specify the file id in the field 'file_id' and the file path on the device in the field 'filepath'

'filedownload' to get a file from the device, you must specify the file path on the device in the field 'filepath'.

Allowed values:
"read"
"write"
"execute"
"observe"
"observe_stop"
"download"
"fileupload"
"filedownload"
endpoint
string
the LWM2M path targeted by a gateway_command of type lwm2m_request

oneOf
the value for a LWM2M command of type 'write'

Adheres to:
string
Or to:
number
Or to:
boolean
filepath
string
for command of type 'lwm2m_file' the path of the file to retrieve or replace on a device

file_id
string
for command of type 'lwm2m_file' and type 'fileupload', the identifier of the file to be pushed to the device

Additional properties are allowed.
object [GatewayCommandSchedule]
GatewayCommandSchedules define when a GatewayCommand can be executed. Note that this currently applies only to software update type gateway commands.

start_datetime
required
string
format: date-time
The beginning of the execution window

end_datetime
required
string
format: date-time
The end of the execution window

retry_interval
string
Defines when the execution window can be applied again. daily creates window the next day, weekly creates window the next week (same day of week). If omitted, only the original window will be observed.

Additional properties are allowed.
object [Retry Options]
Options for retryable actions, e.g. gateway commands and commands. If null command will not be retried.

timeout
number
[ 60 .. 300 ]
Retry attempts will be abandoned once the timeout number of seconds is reached, if unable to execute command. May not apply to all types of commands.

Default value:180
max_retries
number
[ 1 .. 20 ]
Maximum number of times to retry.

Default value:5
object
Details about how to retry.

type
string
The strategy to use while retrying.

"" or none - do not retry

fixed - retry using a fixed period.

exponential_backoff - retry with a period that grows exponentially less frequent, according to a multiplier.

Default value:"none"
Allowed values:
""
"none"
"fixed"
"exponential_backoff"
fixed_interval
number
[ 60 .. 3600 ]
If type is fixed, this is the period of the retry in seconds. E.g. an interval of 180 will retry every three minutes.

Default value:180
exponential_base_interval
number
[ 60 .. 3600 ]
The starting interval in seconds for the period of an exponential_backoff type retry. E.g. a base interval of 180 will retry in three minutes the first time.

Default value:180
exponential_multiplier
number
[ 2 .. 10 ]
The multiplier indicating how much to increase each exponential_backoff type retry. E.g. with a base interval of 180 and a multiplier of 2, the first retry will be after three minutes, then six, then 12, 24, and so on.

Default value:2
exponential_max_interval
number
[ 300 .. 86400 ]
The maximum interval in seconds for an exponential_backoff type retry.

Default value:3600
Additional properties are allowed.
Additional properties are allowed.
restricted any
_id
read-only
string
A unique id for this Command.

name
required
string
The name of the command.

device_id
string
The id of the device to which this command will be sent. This may be omitted until the command is executed.

sender_type
required
string
The type of sender used to send the command.

Allowed values:
"tcp_sender"
"http_sender"
"dev_sender"
"rest_fwd_sender"
"plugin_sender"
"shell_sender"
"opcua_sender"
"modbus_sender"
"bacnet_sender"
object
The sender (as specified by sender_type) used to send the command.

Additional properties are allowed.
translator_id
string
The id of the translator used to translate the command payload into the data format expected by the recipient device. This can be omitted if a translator is not needed to process and send the command.

long_description
string
A long description of the command. This field is intended to be populated with instructions on how to send the command. These instructions can then be displayed to users of an application.

object
A JSON object containing metadata needed to process and send the command. This field is not used by commands sent directly by Edge (but may optionally be used by REST Command forwarders and plugins).

Additional properties are allowed.
payload
string
A JSON object containing all of the data that will comprise the actual message sent to the recipient device. This payload is the input to the translator.
TerminalMessageType
string
Allowed values:
"cc"
"cr"
"i"
"o"
TerminalMessageSubType
string
Allowed values:
"ping"
"pong"
"resize"
"status"
TerminalCmdStatus
string
Allowed values:
"success"
"fail"
object
c
integer
Number of columns

r
integer
Number of rows

Additional properties are allowed.
object
t
string
Allowed values:
"cc"
"cr"
"i"
"o"
subtype
string
Allowed values:
"ping"
"pong"
"resize"
"status"
object
c
integer
Number of columns

r
integer
Number of rows

Additional properties are allowed.
Additional properties are allowed.
object
t
string
Allowed values:
"cc"
"cr"
"i"
"o"
subtype
string
Allowed values:
"ping"
"pong"
"resize"
"status"
object
c
integer
Number of columns

r
integer
Number of rows

Additional properties are allowed.
status
string
Allowed values:
"success"
"fail"
Additional properties are allowed.
object
counter
integer
epoch
integer
Additional properties are allowed.
object
t
string
Allowed values:
"cc"
"cr"
"i"
"o"
subtype
string
Allowed values:
"ping"
"pong"
"resize"
"status"
object
counter
integer
epoch
integer
Additional properties are allowed.
Additional properties are allowed.
TerminalStatus
string
Allowed values:
"exited"
"killed"
"crashed"
"hanging"
"running"
"disconnected"
object
status
string
Allowed values:
"exited"
"killed"
"crashed"
"hanging"
"running"
"disconnected"
message
string
Additional properties are allowed.
object
t
string
Allowed values:
"cc"
"cr"
"i"
"o"
subtype
string
Allowed values:
"ping"
"pong"
"resize"
"status"
object
status
string
Allowed values:
"exited"
"killed"
"crashed"
"hanging"
"running"
"disconnected"
message
string
Additional properties are allowed.
Additional properties are allowed.
object allOf
configurationUniqueIdentifier
string
Unique identifier for the configuration

deviceUniqueId
string
Unique identifier for the device

object allOf
version
integer
Version of the setting

name
string
Name of the setting

configurationId
string
Configuration ID of the setting

description
string
Description of the setting

object
Values of the setting

Additional properties are allowed.
array<object>
object
id
string
ID of the device type

name
string
Name of the device type

description
string
Description of the device type

enforceSecureMQTT
boolean
Indicates if secure MQTT is enforced

Additional properties are allowed.
array<object>
object
id
string
ID of the device

name
string
Name of the device

description
string
Description of the device

Additional properties are allowed.
isSelfReported
boolean
Indicates if the setting is self-reported

object
id
string
ID of the base string

origin
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
createdAt
string
format: date-time
Creation timestamp

updatedAt
string
format: date-time
Last update timestamp

companyId
string
Company ID related to the base string

userId
string
User ID related to the base string

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object allOf
version
integer
Version of the setting

name
string
Name of the setting

configurationId
string
Configuration ID of the setting

description
string
Description of the setting

object
Values of the setting

Additional properties are allowed.
array<object>
object
id
string
ID of the device type

name
string
Name of the device type

description
string
Description of the device type

enforceSecureMQTT
boolean
Indicates if secure MQTT is enforced

Additional properties are allowed.
array<object>
object
id
string
ID of the device

name
string
Name of the device

description
string
Description of the device

Additional properties are allowed.
isSelfReported
boolean
Indicates if the setting is self-reported

object
id
string
ID of the base string

origin
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
createdAt
string
format: date-time
Creation timestamp

updatedAt
string
format: date-time
Last update timestamp

companyId
string
Company ID related to the base string

userId
string
User ID related to the base string

Additional properties are allowed.
Additional properties are allowed.
object
id
string
ID of the base string

origin
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
createdAt
string
format: date-time
Creation timestamp

updatedAt
string
format: date-time
Last update timestamp

companyId
string
Company ID related to the base string

userId
string
User ID related to the base string

Additional properties are allowed.
OriginType
string
Allowed values:
"edge"
"cloud"
"aws"
"all"
""
object
id
string
ID of the device type

name
string
Name of the device type

description
string
Description of the device type

enforceSecureMQTT
boolean
Indicates if secure MQTT is enforced

Additional properties are allowed.
object
id
string
ID of the device

name
string
Name of the device

description
string
Description of the device

Additional properties are allowed.
object
message
string
Status message content

statusType
string
Type of status message

timestamp
string
format: date-time
Timestamp of the status message

Additional properties are allowed.
object
command
string
Command issued

messageID
string
ID of the message

timestamp
string
format: date-time
Timestamp of the command status

Additional properties are allowed.
object
configReceived
boolean
Indicates if the configuration was received

configValid
boolean
Indicates if the configuration is valid

configured
boolean
Indicates if the device is configured

greengrassInstalled
boolean
Indicates if Greengrass is installed

Additional properties are allowed.
ProvisionStatusType
string
Allowed values:
"in_progress"
"completed"
"error"
DeviceHealthStatus
string
Allowed values:
"normal"
"needs_attention"
"critical"
""
HeartbeatStatusType
string
Allowed values:
"online"
"offline"
"idle"
"never_reported"
""
LogLevel
string
Allowed values:
"trace"
"debug"
"info"
"warn"
"error"
"critical"
object
localLevel
string
Allowed values:
"trace"
"debug"
"info"
"warn"
"error"
"critical"
forwardLevel
string
Allowed values:
"trace"
"debug"
"info"
"warn"
"error"
"critical"
forwardFrequencyLimit
integer
Frequency limit for forwarding logs

Additional properties are allowed.
object
id
required
string
The unique identifier for the command execution.

required
object
object
status
string
The status of the command execution.

error
string
Error message if the command failed.

Additional properties are allowed.
Additional properties are allowed.

EdgeIQ Sevice MQTT Specification 0.1.2

Changelog

Servers

Security:

Security:

Operations

RECEIVE d/{companyId}/{deviceId}/gateway_commands/{gatewayCommandType}

Examples

This example has been generated automatically.

RECEIVE d/{companyId}/{deviceId}/commands/{userDefinedCommandId}

Examples

This example has been generated automatically.

RECEIVE d/{companyId}/{deviceId}/escrow

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/config

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/action

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/status

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/reports/hb

Examples

#1 Example - Heartbeat with device metrics

SEND u/{companyId}/{deviceId}/reports

Examples

#1 Example - Simple Report

#2 Example - Report on behalf of a sensor

#3 Example - Report with JSON object payload

SEND u/{companyId}/{deviceId}/command_execution_status

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/error

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/reported_settings

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/gateway_command_status

Examples

This example has been generated automatically.

SEND u/{companyId}/{deviceId}/escrow_request

Examples

This example has been generated automatically.

Messages

Schemas