Subscribing to messages
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
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. 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.
-
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
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 device to topics that are commands for a specific device
-
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.
-
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.
-
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).