# Subscribing a device or registry to receive messages using Mosquitto

{% 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 %}

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`.

To learn more about messaging, see [Sending a message using Mosquitto](mosquitto-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}

Prepare the following:

1. [Registry](../../operations/registry/registry-create.md).
1. [A registry certificate](../../operations/certificates/registry-certificates.md).
1. [Device](../../operations/device/device-create.md).
1. [A device certificate](../../operations/certificates/device-certificates.md).
1. [Mosquitto](https://mosquitto.org), an open source MQTT message broker. It is used in instructions for sending messages and subscribing to devices. [Download and install](https://mosquitto.org/download/) it to work with commands given in instructions.

## Connecting to an MQTT server {#connect-mqtt-server}

To connect to the MQTT server, use the following parameters:
- [A certificate from the certificate authority](https://storage.yandexcloud.net/mqtt/rootCA.crt).
- **Server address**: `mqtt.cloud.yandex.net`.
- **Server port**: `8883`.
- **Protocol**: `TLSv1.2`.

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

You can subscribe a registry to topics of one, multiple, or all devices added to it. Let's look at all the options.

Subscribe a registry to a device or devices using the following parameters:
- `-h`: MQTT server address.
- `-p`: MQTT server port.
- `--cafile`: Path to the certificate from the certificate authority.
- `--cert`: Path to the public part of the registry.
- `--key`: Path to the private part of the registry certificate.
- `-t`: Device topics.
- `-q`: [Quality of service (QoS) level](../../concepts/index.md#qos).

{% 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 %}

{% list tabs group=instructions %}

- Mosquitto {#mosquitto}

    - Subscribe a registry to a single device's topic:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$devices/<device_ID>/events' \
          -q 1
        ```

    - Subscribe a registry to a device's permanent topic:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$devices/<device_ID>/state' \
          -q 1
        ```

    - Subscribe a registry to the topics of multiple devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$devices/<device_1_ID>/events' \
          -t '$devices/<device_2_ID>/events' \
          -q 1
        ```

    - Subscribe a registry to the permanent topics of multiple devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$devices/<device_1_ID>/state' \
          -t '$devices/<device_2_ID>/state' \
          -q 1
        ```

    - Subscribe a registry to the topics of all devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$registries/<registry_ID>/events' \
          -q 1
        ```

    - Subscribe a registry to the permanent topics of all devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert registry-cert.pem \
          --key registry-key.pem \
          -t '$registries/<registry_ID>/state' \
          -q 1
        ```

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

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

Subscribe a device to a registry using the following parameters:
- `-h`: MQTT server address.
- `-p`: MQTT server port.
- `--cafile`: Path to the certificate from the certificate authority.
- `--cert`: Path to the public part of the certificate.
- `--key`: Path to the private part of the device certificate.
- `-t`: Device topic.
- `-q`: [Quality of service (QoS) level](../../concepts/index.md#qos).

{% 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 %}

{% list tabs group=instructions %}

- Mosquitto {#mosquitto}

    - Subscribe a device to topics that are commands for a specific device:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert device-cert.pem \
          --key device-key.pem \
          -t '$devices/<device_ID>/commands' \
          -q 1
        ```

    - Subscribe a device to permanent topics that are commands for a specific device:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert device-cert.pem \
          --key device-key.pem \
          -t '$devices/<device_ID>/config' \
          -q 1
        ```

  - Subscribe a device to topics that are commands for all devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert device-cert.pem \
          --key device-key.pem \
          -t '$registries/<registry_ID>/commands' \
          -q 1
        ```

  - Subscribe a device to permanent topics that are commands for all devices:

        ```bash
        mosquitto_sub -h mqtt.cloud.yandex.net \
          -p 8883 \
          --cafile rootCA.crt \
          --cert device-cert.pem \
          --key device-key.pem \
          -t '$registries/<registry_ID>/config' \
          -q 1
        ```

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

{% endlist %}