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:

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.

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 the my/alias/events topic. It is the same as $devices/<device_ID>/events. Similarly, you can use other topics starting with $devices/<device_ID>/.

Aliases cannot match the prefixes of other aliases within the same registry.

After creating an alias named my/alias/=..., you cannot create aliases named my/=..., my/alias/2/=..., or my/ali=... in the same registry.

You can create aliases named my/alias1/=..., my/alias2/=..., or my/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 topics based on existing `$me` aliases.

When sending or 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, and if it starts with $registries/, registry topics. In other cases, only aliases are included in filters.

# 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 topics of a specific device.
• $devices/<device_ID>/events/#: Subscribe to all topics of a specific device 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 get commands sent to the $registries/<registry_ID>/commands/bedroom and $registries/<registry_ID>/commands/kitchen topics while ignoring a command sent to the $registries/<registry_ID>/commands/bedroom/entrance topic.

Examples of using +:

• $devices/<device_ID>/+: Subscribe to all topics of a specific device with telemetry data and commands.
• $devices/<device_ID>/events/+: Subscribe to all topics of a specific device with telemetry data from all rooms. The example assumes that + 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 + 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. It is the 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 this case, you will also get all the messages sent to $devices/<registry_ID>/events.

• Subscribing to the $registries/# filter with a device certificate is the same as subscribing to $registries/<registry_ID>/commands/#.

  In this case, you will also get all 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.

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 sends 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 text.
• is_base64: Set to true if the message is Base64-encoded, and false otherwise. A message is Base64-encoded if it has incorrect UTF-8 encoding.

Use cases

• Writing data from a device into a database
• Status monitoring of geographically distributed devices
• Sensor reading monitoring and event notifications