Using topics
You can subscribe devices and registries to the $<devices_or_registries>/<device_or_registry_ID>/events
and $<devices_or_registries>/<device_or_registry_ID>/commands
topics.
If you have devices whose sensor readings require your quick response, and your network is potentially vulnerable to connection failures between your devices and the MQTT server, subscribe your devices and registries to the $<devices_or_registries>/<device_or_registry_ID>/state
and $<devices_or_registries>/<device_or_registry_ID>/config
permanent topics. A permanent topic stores the last message sent to it and shows this message when the connection is restored (even if no devices or registries are writing data to the topic at the time of reconnection). After the connection is restored, permanent topics work like regular topics and information appears in them when a device or registry writes data to them.
The table below describes actions that devices and registries can perform using topics:
Topics | Device | Registry |
---|---|---|
$devices/<device_ID>/events $devices/<device_ID>/state |
Sends telemetry data. | Receives telemetry data. The device is known. |
$devices/<device_ID>/commands $devices/<device_ID>/config |
Receives commands. | Sends commands to a specific device. |
$registries/<registry_ID>/events $registries/<registry_ID>/state |
Sends telemetry data. | Receives telemetry data from all devices in the registry. The device is unknown. |
$registries/<registry_ID>/commands $registries/<registry_ID>/config |
Receives commands. | Sends commands to all devices in the registry. |
$monitoring/<device_ID>/json |
Receives another device's monitoring data in JSON format. | Receives device monitoring data in JSON format. |
Using topic aliases
An alias is an alternate name of a device topic assigned by the user. Aliases can be assigned to standard topics that are already implemented in the service and topics with arbitrary subtopics.
Note
You can only use the $me
system alias for the $monitoring/<device_ID>/json
topic.
An alias is set in the key-value format:
<alias>='<device_topic>'
You can use aliases for sending messages and subscribing to messages along with regular device topics. You can also use wildcard characters in aliases when subscribing to messages. In this case, the service checks the format of the original topic that was assigned an alias.
Aliases must uniquely identify devices, so the topic that the alias is assigned to must contain a unique device ID.
If you create an alias named
my/alias/=$devices/<device_ID>/
, you can use themy/alias/events
topic. It will be equivalent to$devices/<device_ID>/events
. Similarly, you can also use other topics starting with$devices/<device_ID>/
.
Aliases cannot match the prefixes of other aliases within the same registry.
If you created an alias named
my/alias/=...
in the registry, you cannot create aliases namedmy/=...
,my/alias/2/=...
, ormy/ali=...
in this registry.
You can create such aliases as
my/alias1/=...
,my/alias2/=...
, ormy/ali/=...
.
Using $me system aliases in $me topics
To avoid entering the ID of the device on whose behalf an MQTT session is established each time, you can use me` aliases already created in the service.
$me topic | Equivalent topic |
---|---|
$me/device/events |
$devices/<device_ID>/events |
$me/device/commands |
$devices/<device_ID>/commands |
$me/device/state |
$devices/<device_ID>/state |
$me/device/config |
$devices/<device_ID>/config |
$me/registry/commands |
$registries/<device_ID>/commands |
$me/registry/config |
$registries/<device_ID>/config |
$me/monitoring/json |
$monitoring/<device_ID>/json |
When sending messages and subscribing to messages, $me topics are converted to topics with <device ID>
at the MQTT level.
If you subscribe to a $me topic, you will receive data in the $me topic, too.
Subscribing to topics using wildcard characters
You can use special wildcard characters, such as #
and +
, to filter subscriptions to topics.
If a filter starts with $devices/
, it includes device topics. If it starts with $registries/
, it contains registry topics. In other cases, only aliases are included in filters.
Note
Subscribing to permanent topic aliases using wildcard characters is similar to subscribing to regular topics. When reconnecting to the MQTT server, the current state of the topic is not sent to the registries or devices that are subscribed to it.
If more than a thousand topics are included in a filter when subscribing to permanent topics using wildcard characters, data delivery for all topics is not guaranteed.
# character
Substitutes one or more parts of a topic and an empty string. This character is always the last in a filter.
Examples of using #
:
#
— Subscribe to all topic aliases.$devices/#
— Subscribe to all topics of all devices.$devices/<device_ID>/#
: Subscribe to all specific device's topics.$devices/<device_ID>/events/#
: Subscribe to all specific device's topics with telemetry data.$devices/<device_ID>/state/#
: Subscribe to all permanent topics with telemetry data of the device with the specified unique ID.
+ character
Substitutes a part of a topic between two /
or at the end after a single /
.
For example, devices subscribed to $registries/<registry_ID>/commands/+
will receive commands sent to the $registries/<registry_ID>/commands/bedroom
and $registries/<registry_ID>/commands/kitchen
topics while ignoring the command sent to the $registries/<registry_ID>/commands/bedroom/entrance
topic.
Examples of using +:
$devices/<device_ID>/+
: Subscribe to all specific device's topics with telemetry data and commands.$devices/<device_ID>/events/+
: Subscribe to all specific device's topics with telemetry data from all rooms. The example assumes that the+
stands for the location.$devices/+/events/bedroom/temperature
: Subscribe to all topics with bedroom temperature telemetry data from all devices.$devices/+/events/bedroom/+
: Subscribe to all topics with bedroom telemetry data from all devices. The example assumes that the+
stands for the unique device ID and sensor type.
The $devices/+
and $registries/+
filters do not apply, because a topic must consist of these three parts: $<devices_or_registries>/<device_or_registry_ID>/<events_or_commands>
.
Using + and # simultaneously
You can use #
after +
to substitute the rest of a topic or subtopic:
-
$devices/#
: Subscribe to all topics of all devices. Same as the$devices/#
filter. -
$devices/+/events/#
: Subscribe to all topics with telemetry data from all devices.
Filtering also takes general rules for subscribing to topics into account, such as:
-
Subscribing to the
$devices/#
filter with a registry certificate is the same as subscribing to$devices/+/events/#
.In which case you will also get all the messages sent to
$devices/<device_ID>/events
. -
Subscribing to the
$registries/#
filter with a device certificate is the same as subscribing to$registries/<registry_ID>/commands/#
.In which case you will also get all the messages sent to
$registries/<registry_ID>/commands
.
Triggers for topics
Triggers are conditions that automatically launch a specific function or container when met.
A trigger for Yandex IoT Core is used to manage messages exchanged between devices and registries. It is created for topics: it receives copies of messages from the topics and delivers them to a Cloud Functions function or a Serverless Containers container for processing.
The trigger must be in the same cloud as the device, registry, or broker whose topic it reads messages from.
You can create a trigger:
- For a standard topic implemented by the service except for the
$monitoring/<device_ID>/json
topic. - For a topic with any subtopics and wildcards.
- For an alias topic.
A trigger for Yandex IoT Core needs a service account to call the function or container.
Read more about triggers in the Cloud Functions and Serverless Containers documentation.
Exporting to Data Streams
You can set up export of messages from registry and device topics to a Yandex Data Streams data stream to transfer the resulting data to other services and applications for further analysis and processing. You can only set up one export per registry.
Note
Exporting messages from broker topics is not supported.
The data is exported in the following format:
{
"device_id": "<device_ID",
"mqtt_topic": "<topic>",
"payload": "<message_text>",
"is_base64": true|false
}
Where:
device_id
: ID of the device that transfers data to a topic. If the message is sent by a registry, this field is left empty.mqtt_topic
: Topic from which the message is exported.payload
: Message body.is_base64
: Set totrue
if the message is Base64 encoded, andfalse
otherwise. A message is Base64-encoded if it has incorrect UTF-8 encoding.