Sending messages
The service provides two resource management models:
- When using a broker, you can send and receive messages in random topics that do not start with
$. - When registries and devices are used, the selection of topics is limited.
For more information about the differences between brokers and device registries, see Resource relationships in Yandex IoT Core.
When using registries and devices, you can send messages of the following types:
- Send data from a device to a registry using the
$devices/<device_ID>/eventsor$registries/<registry_ID>/eventstopics. - Send data from a device to a registry using the permanent
$devices/<device_ID>/stateor$registries/<registry_ID>/statetopics. - Send registry commands to a device using the
$devices/<device_ID>/commandsor$registries/<registry_ID>/commandstopics. - Send registry commands to a device using the permanent
$devices/<device_ID>/configor$registries/<registry_ID>/configtopics.
To receive messages, you need to subscribe to the sender. For information about how to do this, see Subscribing to messages.
On how to make sure a message has been successfully sent and delivered, see Testing message delivery.
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.
Sending a message with data
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.
Send data from a device to a device topic
Registries subscribed to this topic will know which device sent the data, because the topic contains a unique device ID.
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.
-
Send data to a device topic using certificate-based authorization:
yc iot mqtt publish \ --cert device-cert.pem \ --key device-key.pem \ --topic '$devices/<device_ID>/events' \ --message 'Test data' \ --qos 1 -
Send data to the permanent topic of a device using certificate-based authorization:
yc iot mqtt publish \ --cert device-cert.pem \ --key device-key.pem \ --topic '$devices/<device_ID>/state' \ --message 'Test data' \ --qos 1Where:
--certand--key: Parameters for authorization with a certificate.--topic: Device topic for sending data.--message: Message text.--qos: Quality of service (QoS) level.
-
Send data to a device topic using username and password authorization:
yc iot mqtt publish \ --username <device_ID> \ --password <device_password> \ --topic '$devices/<device_ID>/events' \ --message 'Test data' \ --qos 1 -
Send data to the permanent topic of a device using username and password authorization:
yc iot mqtt publish \ --username <device_ID> \ --password <device_password> \ --topic '$devices/<device_ID>/state' \ --message 'Test data' \ --qos 1Where:
--usernameand--password: Credentials for authentication with a username and password.--topic: Device topic for sending data.--message: Message text.--qos: Quality of service (QoS) level.
To send device data to a device topic, use the publish REST API method for the DeviceData resource or the DeviceDataService/Publish gRPC API call.
Send data from a device to a registry topic
The registry subscribed to this topic will not know which device sent the data, because the topic does not contain a unique device ID.
- Send data to a registry topic using certificate-based authorization:
```
yc iot mqtt publish \
--cert device-cert.pem \
--key device-key.pem \
--topic '$registries/<registry_ID>/events' \
--message 'Test data' \
--qos 1
```
-
Send data to the permanent topic of a registry using certificate-based authorization:
yc iot mqtt publish \ --cert device-cert.pem \ --key device-key.pem \ --topic '$registries/<registry_ID>/state' \ --message 'Test data' \ --qos 1Where:
--certand--key: Parameters for authorization with a certificate.--topic: Registry topic for receiving data.--message: Message text.--qos: Quality of service (QoS) level.
-
Send data to a registry topic using username and password authorization:
yc iot mqtt publish \ --username <device_ID> \ --password <device_password> \ --topic '$registries/<registry_ID>/events' \ --message 'Test data' \ --qos 1 -
Send data to the permanent topic of a registry using username and password authorization:
yc iot mqtt publish \ --username <device_ID> \ --password <device_password> \ --topic '$registries/<registry_ID>/state' \ --message 'Test data' \ --qos 1Where:
--usernameand--password: Credentials for authentication with a username and password.--topic: Registry topic for receiving data.--message: Message text.--qos: Quality of service (QoS) level.
To send device data to a registry topic, use the publish REST API method for the DeviceData resource or the DeviceDataService/Publish gRPC API call.
Sending messages with commands
A registry can send messages with commands to one, multiple, or all devices added to it. Let's look at all the options.
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.
Send a command to a single device
-
Send a command using certificate-based authorization:
yc iot mqtt publish \ --cert registry-cert.pem \ --key registry-key.pem \ --topic '$devices/<device_ID>/commands' \ --message 'Test command for first device' \ --qos 1 -
Send a command using a permanent topic and certificate-based authorization:
yc iot mqtt publish \ --cert registry-cert.pem \ --key registry-key.pem \ --topic '$devices/<device_ID>/config' \ --message 'Test command for first device' \ --qos 1Where:
--certand--key: Parameters for authorization with a certificate.--topic: Device topic for receiving commands.--message: Message text.--qos: Quality of service (QoS) level.
-
Send a command using username and password authorization:
yc iot mqtt publish \ --username <registry_ID> \ --password <registry_password> \ --topic '$devices/<device_ID>/commands' \ --message 'Test command for first device' \ --qos 1 -
Send a command using a permanent topic and username and password authorization:
yc iot mqtt publish \ --username <registry_ID> \ --password <registry_password> \ --topic '$devices/<device_ID>/config' \ --message 'Test command for first device' \ --qos 1Where:
--usernameand--password: Credentials for authentication with a username and password.--topic: Device topic for receiving commands.--message: Message text.--qos: Quality of service (QoS) level.
To send a command to a single device, use the publish REST API method for the RegistryData resource or the RegistryDataService/Publish gRPC API call.
Send a command to all devices added to the registry
-
Send a command to all devices using certificate-based authorization:
yc iot mqtt publish \ --cert registry-cert.pem \ --key registry-key.pem \ --topic '$registries/<registry_ID>/commands' \ --message 'Test command for all devices' \ --qos 1 -
Send a command to all devices using a permanent topic and certificate-based authorization:
yc iot mqtt publish \ --cert registry-cert.pem \ --key registry-key.pem \ --topic '$registries/<registry_ID>/config' \ --message 'Test command for all devices' \ --qos 1Where:
--certand--key: Parameters for authorization with a certificate.--topic: Registry topic for sending commands.--message: Message text.--qos: Quality of service (QoS) level.
-
Send a command to all devices using username and password authorization:
yc iot mqtt publish \ --username <registry_ID> \ --password <registry_password> \ --topic '$registries/<registry_ID>/commands' \ --message 'Test command for all devices' \ --qos 1 -
Send a command to all devices using a permanent topic and username and password authorization:
yc iot mqtt publish \ --username <registry_ID> \ --password <registry_password> \ --topic '$registries/<registry_ID>/config' \ --message 'Test command for all devices' \ --qos 1Where:
--usernameand--password: Credentials for authentication with a username and password.--topic: Registry topic for sending commands.--message: Message text.--qos: Quality of service (QoS) level.
To send a command to all devices added to a registry, use the publish REST API method for the RegistryData resource or the RegistryDataService/Publish gRPC API call.
Sending a message in a broker
When using a broker, you can send a message to a random topic using your username and password or any certificate assigned to the broker for authorization.
-
Send a message using your username and password for authorization:
yc iot mqtt publish \ --username <broker_ID> \ --password <broker_password> \ --topic /my/custom/topic \ --message 'Test broker message' --qos 1Where:
--usernameand--password: Credentials for authentication with a username and password.--topic: Random topic name that matches the MQTT specification and does not start with$.--message: Message text.--qos: Quality of service (QoS) level.
-
Send a message using certificate-based authorization:
yc iot mqtt publish \ --cert broker-cert.pem \ --key broker-key.pem \ --topic /my/custom/topic \ --message 'Test broker message' --qos 1Where:
--certand--key: Parameters for authorization with a certificate.--topic: Random topic name that matches the MQTT specification and does not start with$.--message: Message text.--qos: Quality of service (QoS) level.
To send a message in a broker, use the publish REST API method for the BrokerData resource or the BrokerDataService/Publish gRPC API call.