# 设备下行

## 页面导读

- **适用场景**: 外部业务系统需要经 Kafka 向设备下发消息与指令，例如平台功能调用、参数设置等所有对设备变更的内容。
- **前置条件**: MQTT Dashboard 可访问，Kafka 服务可用，设备已接入集群并可订阅对应 MQTT 主题。
- **操作路径**: 集成 → 转换配置 → 创建 → 集成 → 设备下行 → 创建 → 可视化观测。
- **验收点**: 外部系统向 Kafka 主题发送消息后，设备收到对应 MQTT 主题的消息，可视化观测中可查到下发记录。

## 1. 设备下行定义

设备下行即是给设备发送消息，指令等所有对设备变更的内容都可以由设备下行实现。

下图以kafka为例：外部系统给设备下发指令，通过kafka生产者，将下发给设备的内容，缓存到mq对列。

而MQTT服务中通过kafka消费者将mq队列中的消息进行消费，发送给对应的设备。

<img src="../images/device-down/downcard.png" style="border:1px solid #ccc;border-radius:6px;margin:8px 0;" loading="lazy" alt="设备下行定义示意图" />

FMQ 与 Kafka 的桥接原理可参见 [桥接Kafka](https://www.fastbee.cn/doc/cluster/v2/use/kafka-integration.md)。

## 2. 创建设备下行

1. 进入 MQTT Dashboard，并点击 **集成** -> **转换配置**，点击页面右上角的 **创建**

2. 进行转换参数配置
   * 名称,转换配置名称
   * 主题, 这里是MQTT主题，支持字段映射 ，我们这里填写 **`/${productId}/${clientId}/function/get`**    $是占位符
   * QOS，下发指令的消息指令
   * 是否保留消息，MQTT的保留消息功能
   * kafka主题是根据MQTT主题自动生成，按照step2，这里对应的kafka主题是 **`function_get`**

3. 进入 MQTT Dashboard，并点击 **集成** -> **设备下行**，点击页面右上角的 **创建**

4. 选择 **`KAFKA-服务`**，配置参数
   * 转换器，选择上面创建的转换器（转换器的创建参见 [转换器](https://www.fastbee.cn/doc/cluster/v2/use/transform.md)）

     <img src="../images/device-down/downcard-transfrom.png" style="border:1px solid #ccc;border-radius:6px;margin:8px 0;" loading="lazy" alt="创建设备下行页面截图" />

   * 转换配置，选择step2中创建的转换配置

     <img src="../images/device-down/downcard-property.png" style="border:1px solid #ccc;border-radius:6px;margin:8px 0;" loading="lazy" alt="创建设备下行页面截图" />

## 3. 下发验证

1. 由外部系统通过 Kafka 生产者向转换配置对应的 Kafka 主题（本例为 `function_get`）发送一条测试消息。
2. 设备下行可视化观测，可以查看下发情况，确认产生对应的下发记录。

<img src="../images/shared/downcard-metris.png" style="border:1px solid #ccc;border-radius:6px;margin:8px 0;" loading="lazy" alt="设备下行记录与消息指标观测页面" />

3. 在设备端确认收到 MQTT 主题 `/${productId}/${clientId}/function/get` 的消息，且消息内容与外部系统发送的一致。

## 4. 常见问题

### 下行指令经过哪些组件？

外部系统通过 Kafka 生产者把下发内容写入 MQ 队列，MQTT 服务中的 Kafka 消费者消费队列中的消息，再通过 MQTT 发送给对应设备。

### Kafka 主题是如何确定的？

Kafka 主题根据转换配置中的 MQTT 主题自动生成。例如 MQTT 主题为 `/${productId}/${clientId}/function/get` 时，对应的 Kafka 主题为 `function_get`。

### 设备收不到下行指令如何排查？

按以下顺序排查：确认设备在线并已订阅转换配置中的 MQTT 主题；核对主题中 `${productId}`、`${clientId}` 占位符与实际设备匹配；确认设备下行配置引用的转换器与转换配置正确；最后在可视化观测中查看下发记录，定位失败环节。
