Subscribing to messages

Written by

Updated at May 13, 2025

Getting started
- Authentication
Subscribing a registry to device topics
- Subscribe a registry to a single device's topic
- Subscribe a registry to the topics of all devices added to it
Subscribing a device to registry topics
- Subscribe a device to topics that are commands for a specific device
- Subscribe a device to topics that are commands for all devices
Subscribe to broker topics

With a broker, you can subscribe to a random topic that does not start with $ using a certificate or a username and password.

For registries and devices, the selection of topics is limited. You can subscribe:

Registry to device events using the $devices/<device_ID>/events or $registries/<registry_ID>/events topics.
Registry to device events using the permanent $devices/<device_ID>/state or $registries/<registry_ID>/state topics.
Device to registry commands using the $devices/<device_ID>/commands or $registries/<registry_ID>/commands topics.
Device to registry commands using the permanent $devices/<device_ID>/config or $registries/<registry_ID>/config topics.
Registry or device to device monitoring data using the $monitoring/<device_ID>/json topic.

To learn about messaging, see Sending messages.

Warning

Registry and device topics are not interconnected. If a device sends data to the device topic for telemetry data, you can only receive it by subscribing to this topic. The same is true for registry topics.

Getting started

Set up resources:

(Optional) Create registry and device certificates.
Create a registry.
Add a certificate to the registry.
Create a device.
Add a certificate to the device.

Authentication

To send messages, you must be authenticated. To do this, use an X.509 certificate or a username and password. This section provides examples for both authentication methods.

Subscribing a registry to device topics

You can subscribe a registry to topics of one, multiple, or all devices added to it.

Note

If you encounter an error while running the command, add the --debug flag to the command and try again. This flag outputs the debug log when running the command, which helps you diagnose the problem.

Subscribe a registry to a single device's topic

CLI

If you do not have the Yandex Cloud (CLI) command line interface yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

Subscribe a registry to a device topic using certificate-based authorization:

yc iot mqtt subscribe \
  --cert registry-cert.pem \
  --key registry-key.pem \
  --topic '$devices/<device_ID>/events' \
  --qos 1

Subscribe a registry to a device's permanent topic using certificate-based authorization:
```
yc iot mqtt subscribe \
  --cert registry-cert.pem \
  --key registry-key.pem \
  --topic '$devices/<device_ID>/state' \
  --qos 1
```
Where:
- --cert and --key: Parameters for authorization using a certificate.
- --topic: Device topic for sending data.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a registry to a device topic using username and password authorization:

yc iot mqtt subscribe \
  --username <registry_ID> \
  --password <registry_password> \
  --topic '$devices/<device_ID>/events' \
  --qos 1

Subscribe a registry to a device's permanent topic using username and password authorization:
```
yc iot mqtt subscribe \
  --username <registry_ID> \
  --password <registry_password> \
  --topic '$devices/<device_ID>/state' \
  --qos 1
```
Where:
- --username and --password: Parameters for authorization using a username and password.
- --topic: Device topic for sending data.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a registry to the topics of all devices added to it

The registry will receive data only from the devices that send messages to the $registries/<registry_ID>/events or $registries/<registry_ID>/state topic.

CLI

Subscribe a registry to the topics of all devices using certificate-based authorization:

yc iot mqtt subscribe \
  --cert registry-cert.pem \
  --key registry-key.pem \
  --topic '$registries/<registry_ID>/events' \
  --qos 1

Subscribe a registry to the permanent topics of all devices using certificate-based authorization:
```
yc iot mqtt subscribe \
  --cert registry-cert.pem \
  --key registry-key.pem \
  --topic '$registries/<registry_ID>/state' \
  --qos 1
```
Where:
- --cert and --key: Parameters for authorization using a certificate.
- --topic: Registry topic for getting data.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a registry to the topics of all devices using username and password authorization:

yc iot mqtt subscribe \
  --username <registry_ID> \
  --password <registry_password> \
  --topic '$registries/<registry_ID>/events' \
  --qos 1

Subscribe a registry to the permanent topics of all devices using username and password authorization:
```
yc iot mqtt subscribe \
  --username <registry_ID> \
  --password <registry_password> \
  --topic '$registries/<registry_ID>/state' \
  --qos 1
```
Where:
- --username and --password: Parameters for authorization using a username and password.
- --topic: Registry topic for getting data.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribing a device to registry topics

Commands from a registry can be given to a specific device or all devices in the registry. This involves using different topics.

Note

Subscribe a device to topics that are commands for a specific device

CLI

Subscribe a device to topics that are commands for a specific device using certificate-based authorization:

yc iot mqtt subscribe \
  --cert device-cert.pem \
  --key device-key.pem \
  --topic '$devices/<device_ID>/commands' \
  --qos 1

Subscribe a device to permanent topics that are commands for a specific device using certificate-based authorization:
```
yc iot mqtt subscribe \
  --cert device-cert.pem \
  --key device-key.pem \
  --topic '$devices/<device_ID>/config' \
  --qos 1
```
Where:
- --cert and --key: Parameters for authorization using a certificate.
- --topic: Device topic for getting commands.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a device to topics that are commands for a specific device using username and password authorization:

yc iot mqtt subscribe \
  --username <device_ID> \
  --password <device_password> \
  --topic '$devices/<device_ID>/commands' \
  --qos 1

Subscribe a device to permanent topics that are commands for a specific device using username and password authorization:
```
yc iot mqtt subscribe \
  --username <device_ID> \
  --password <device_password> \
  --topic '$devices/<device_ID>/config' \
  --qos 1
```
Where:
- --username and --password: Parameters for authorization using a username and password.
- --topic: Device topic for getting commands.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a device to topics that are commands for all devices

Only the devices subscribed to the $registries/<registry_ID>/commands or $registries/<registry_ID>/config topic will receive commands.

CLI

Subscribe a device to topics that are commands using certificate-based authorization:

yc iot mqtt subscribe \
  --cert device-cert.pem \
  --key device-key.pem \
  --topic '$registries/<registry_ID>/commands' \
  --qos 1

Subscribe a device to permanent topics that are commands using certificate-based authorization:
```
yc iot mqtt subscribe \
  --cert device-cert.pem \
  --key device-key.pem \
  --topic '$registries/<registry_ID>/config' \
  --qos 2
```
Where:
- --cert and --key: Parameters for authorization using a certificate.
- --topic: Registry topic for sending commands.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe a device to topics that are commands using username and password authorization:

yc iot mqtt subscribe \
  --username <device_ID> \
  --password <device_password> \
  --topic '$registries/<registry_ID>/commands' \
  --qos 1

Subscribe a device to permanent topics that are commands using username and password authorization:
```
yc iot mqtt subscribe \
  --username <device_ID> \
  --password <device_password> \
  --topic '$registries/<registry_ID>/config' \
  --qos 1
```
Where:
- --username and --password: Parameters for authorization using a username and password.
- --topic: Registry topic for sending commands.
- --message: Message text.
- --qos: Quality of service (QoS).

Subscribe to broker topics

When using a broker, you can subscribe to a random topic using your username and password or any certificate assigned to the broker for authorization.

CLI

Subscribe to a topic using your username and password for authorization:
```
yc iot mqtt subscribe \
  --username <broker_ID> \
  --password <broker_password> \
  --topic /my/custom/topic \
  --qos 1
```
Where:
- --username and --password: Parameters for authorization using a username and password.
- --topic: Random topic name that conforms to the MQTT specification and does not start with $.
- --qos: Quality of service (QoS).
Subscribe to the topic using certificate-based authorization:
```
yc iot mqtt subscribe \
  --cert broker-cert.pem \
  --key broker-key.pem \
  --topic /my/custom/topic \
  --qos 1
```
Where:
- --cert and --key: Parameters for authorization using a certificate.
- --topic: Random topic name that conforms to the MQTT specification and does not start with $.
- --qos: Quality of service (QoS).