Using topics

You can subscribe your 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 that require a fast response to sensor readings and you may face network communication problems that cause a broken connection between your devices and the MQTT server, subscribe your devices and registries to permanent topics like $<devices or registries>/<device or registry ID>/state and $<devices or registries>/<device or registry ID>/config. 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 my/alias/=$devices/<device ID>/, you can use the my/alias/events topic. This is the same as $devices/< device ID>/events. Similarly, you can use other topics starting with $devices/<device ID>/.

Aliases can't match the prefixes of other aliases within the same registry.

If you created an alias like my/alias/=... in a registry, you can't create aliases like my/=..., my/alias/2/=..., or my/ali=... in this registry.

You can create such aliases as 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 $me aliases already created in the service.

When sending messages and subscribing to messages, $me topics are converted to topics with a at the MQTT level.
If you subscribe to a $me topic, you'll 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.

# 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 with telemetry data of a specific device.
• $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 with telemetry data and commands of a specific device.
• $devices/<device ID/events/+ — Subscribe to all topics with a specific device's 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 don't apply as a topic must contain three parts: $<devices or registries>/<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 this case, you'll also get all messages sent to $devices/<DeviceID>/events.

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

  In this case, you'll 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.

The trigger for Yandex IoT Core is designed for managing messages exchanged between devices and registries. The trigger is created for topics: it picks up copies of messages from them and passes them to the function Cloud Functions or container Serverless Containers for processing.

The trigger must be in the same cloud as the device or register as the 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.