Skip to main content

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.

note

This guide will use the command line tool to generate some needed resources, such as api keys and nodes, you can read more about the command line tool and how to install it here.

If you don't want to use the command line tool, most of the operations can be completed using the dashboard.

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.

PUBLISHapio/core/projects/{projectId}/devices/{deviceId}/telemetry/uplink

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.

PUBLISHapio/core/projects/{projectId}/telemetry/uplink

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.

SUBSCRIBEapio/core/projects/{projectId}/devices/{deviceId}/commands/downlink

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.

SUBSCRIBEapio/core/projects/{projectId}/commands/downlink

payload

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