MQTT Connectivity

Introduction

Apio IoT allows to write and read data through the MQTT protocol, enabling your MQTT capable devices and applications to interact with the platform in real-time.

If your application needs to send data in a non real-time fashion, the HTTP API might be a better option.

For SaaS projects, the default endpoint is located at broker.apio.network and the default port is 1883, while for on-premise projects, the endpoint depends on the chosen infrastructure and is communicated just after the setup.

Authentication

MQTT Credentials must be provided in the form of MQTT username and password. These values can be obtained creating apikeys, the value of the apikey will provide the value for the password field, while the username field can be constructed as follows:

• If the client represents a Device: /projects/{projectId}/devices/{deviceId}
• If the client represents a Node: /projects/{projectId}/nodes/{nodeId}
• If the client represents an Application: /projects/{projectId}/applications/{applicationId}

Obtaining MQTT credentials using the Command Line Interface:

First create the gateway

$ apio nodes create --name='myGateway01'

metadata:
connectivityStatus: disconnected
description:
name:               myGateway01
projectId:          someprojectid
uuid:               someuuid
createdAt:          2020-11-30T14:11:55.721Z
updatedAt:          2020-11-30T14:11:55.721Z

At this point we already have the username for our client: /projects/someprojectid/nodes/someuuid

Then we create an apikey, for this we create a file named key.json with the following content:

{
  "name":"apikey01",
  "description":"Api key for my gateway",
  "permissions":[
    "apio.telemetry.data.read",
    "apio.telemetry.data.write"
  ]
}

The value for the apikey won’t be readable after creation, be sure to write it down

$ apio apikeys create @key.json


expire:      +275760-09-13T00:00:00.000Z
permissions:
  - apio.telemetry.data.read
  - apio.telemetry.data.write
name:        apikey01
description: Api key per il gw 1
projectId:   someprojectid
value:       abcdef.xxxxxxxxxxxxxxxxxxxxxxxxxxx=
uuid:        someapikeyid
createdAt:   2020-11-30T16:29:01.274Z
updatedAt:   2020-11-30T16:29:01.274Z

Now we also have the password: abcdef.xxxxxxxxxxxxxxxxxxxxxxxxxxx= , which can be used along with the username /projects/someprojectid/nodes/someuuid obtained above to provide mqtt credentials to the broker

Topics

Send device data

Requires the apio.telemetry.data.write permission.

Sends measurements to the cloud. Measurements are related to a specific device corresponding to the deviceId in the topic. If no timestamp is provided, the processing time is used.

payload

[{
  "time":"2023-04-01T08:00:00.000Z",
  "temperature":19,
  "humidity":65
},{
  "time":"2023-04-01T09:00:00.000Z",
  "temperature":19,
  "humidity":65
}]

Send project data

Requires the apio.telemetry.data.write permission.

Sends measurements to the cloud. Measurements are related to any device in the project corresponding to the projectId in the topic. If no timestamp is provided, the processing time is used.

Every measurement set must provide a deviceId.

payload

[{
  "deviceId":"my-device-1",
  "time":"2023-04-01T08:00:00.000Z",
  "temperature":19,
  "humidity":65
},{
  "deviceId":"my-device-2",
  "time":"2023-04-01T09:00:00.000Z",
  "temperature":19,
  "humidity":65
}]

Listen for device specific commands

Requires the apio.core.commands.read permission.

By subscribing to this topic, clients can listen for commands sent to a specific device that matches the uuid in the subscription topic.

payload

{
  "name":"reboot",
  "projectId":"my-project-id",
  "deviceId":"my-device-1",
  "parameters":{
    "wait":"8s"
  },
  "uuid":"810b7efb-f648-47eb-b03b-8edf290e0a27"
}

Listen for project specific commands

Requires the apio.core.commands.read permission.

By subscribing to this topic, clients can listen for commands sent to any device within the project.

payload

{
  "name":"reboot",
  "projectId":"my-project-id",
  "deviceId":"my-device-1",
  "parameters":{
    "wait":"8s"
  },
  "uuid":"810b7efb-f648-47eb-b03b-8edf290e0a27"
}

Listen for node specific commands

Requires the apio.core.commands.read permission.

By subscribing to this topic, a node, such as a gateway, can listen for the commands sent to it.

The payload has the same form as device commands, with nodeId instead of deviceId.

Acknowledge commands

Requires the apio.core.commands.write permission.

By publishing to the acknowledgement topic, devices and nodes report the progress of a command. Append /ack to the topic the command was received on:

payload

{
  "uuid":"810b7efb-f648-47eb-b03b-8edf290e0a27",
  "status":"completed"
}

See Acknowledging commands for the accepted statuses and how to return a result.

Short Topic Names

Every topic is also available in a shorter form, which saves bandwidth on constrained devices: replace projects with p, devices with d and nodes with n. For example, apio/core/projects/{projectId}/devices/{deviceId}/telemetry/uplink can also be written as:

apio/core/p/{projectId}/d/{deviceId}/telemetry/uplink