[Yandex Cloud documentation](../../index.md) > [Yandex IoT Core](../index.md) > [Step-by-step guides](index.md) > Subscribing a device or registry to receive messages

# Subscribing to messages

{% note warning %}

Yandex IoT Core is no longer available to new users. 

Current users can create resources until November 1, 2026. Afterwards, the service will go read-only and cease to operate on December 1, 2026. For more information on the timing and procedure, see [Service shutdown](../sunset.md).

{% endnote %}

With a broker, you can subscribe to a random topic that does not start with `$` either using a certificate or username and password.

For registries and devices, the selection of topics is limited. You can subscribe:

- A registry to device events using the `$devices/<device_ID>/events` or `$registries/<registry_ID>/events` topics.
- A registry to device events using the permanent topics: `$devices/<device_ID>/state` or `$registries/<registry_ID>/state`.
- A device to registry commands using the `$devices/<device_ID>/commands` or `$registries/<registry_ID>/commands` topics.
- A device to registry commands using the permanent topics: `$devices/<device_ID>/config` or `$registries/<registry_ID>/config`.
- Registry or device to device monitoring data using the `$monitoring/<device_ID>/json` topic.

To learn more about messaging, see [Sending messages](publish.md).

{% note 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.

{% endnote %}

## Getting started {#before-you-begin}

Set up resources:
1. (Optional) [Create registry and device certificates](certificates/create-certificates.md).
1. [Create a registry](registry/registry-create.md).
1. [Add a certificate to the registry](certificates/registry-certificates.md#add-cert).
1. [Create a device](device/device-create.md).
1. [Add a certificate to the device](certificates/device-certificates.md#add-cert).

### Authentication {#auth}

To send messages, you must be [authenticated](../concepts/authorization.md). 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 {#sub-events}

You can subscribe a registry to topics of one, multiple, or all devices added to it.

{% note info %}

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.

{% endnote %}

### Subscribe a registry to a single device's topic {#one-device}

{% list tabs group=instructions %}

- CLI {#cli}
    
    If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).
    
    The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

    - 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 authentication with a certificate.
        - `--topic`: Device topic for sending data.
        - `--message`: Message text.
        - `--qos`: [Quality of service (QoS) level](../concepts/index.md#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 authentication with a username and password.
        - `--topic`: Device topic for sending data.
        - `--message`: Message text.
        - `--qos`: [Quality of service (QoS) level](../concepts/index.md#qos).
      
{% endlist %}

### Subscribe a registry to the topics of all devices added to it {#all-device}

The registry will only receive data from devices that send messages to the `$registries/<registry_ID>/events` or `$registries/<registry_ID>/state` topic.

{% list tabs group=instructions %}

- CLI {#cli}

   - 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 authentication with a certificate.
      - `--topic`: Registry topic for receiving data.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#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 authentication with a username and password.
      - `--topic`: Registry topic for receiving data.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#qos).

{% endlist %}

## Subscribing a device to registry topics {#sub-commands}

Commands from a registry can be given to a specific device or all devices in the registry. This involves using different topics.

{% note info %}

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.

{% endnote %}

### Subscribe a device to topics that are commands for a specific device {#for-one}

{% list tabs group=instructions %}

- CLI {#cli}

   - 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 authentication with a certificate.
      - `--topic`: Device topic for receiving commands.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#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 authentication with a username and password.
      - `--topic`: Device topic for receiving commands.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#qos).

{% endlist %}

### Subscribe a device to topics that are commands for all devices {#for-all}

Only devices subscribed to the `$registries/<registry_ID>/commands` or `$registries/<registry_ID>/config` topic will receive commands.

{% list tabs group=instructions %}

- CLI {#cli}

   - 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 authentication with a certificate.
      - `--topic`: Registry topic for sending commands.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#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 authentication with a username and password.
      - `--topic`: Registry topic for sending commands.
      - `--message`: Message text.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#qos).

{% endlist %}

## Subscribe to broker topics {#broker}

When using a broker, you can subscribe to a random topic using your username and password or any certificate assigned to the broker for authentication.

{% list tabs group=instructions %}

- CLI {#cli}

   - 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 authentication with a username and password.
      - `--topic`: Random topic name that matches the MQTT specification and does not start with `$`.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#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 authentication with a certificate.
      - `--topic`: Random topic name that matches the MQTT specification and does not start with `$`.
      - `--qos`: [Quality of service (QoS) level](../concepts/index.md#qos).

{% endlist %}