ThingsEye 诊断应用
NB-IoT / LoRa 设备诊断链路指南
本页面提供 ThingsEye Diagnosis App v1.0.1 的用户手册和发布包。
下载文件
| 文件 | 描述 |
|---|---|
| Device-Diagnostic User Manual v1.0.1 | 用于 NB-IoT / LoRaWAN 诊断流程的 Word 用户手册 |
| ThingsEye Diagnosis Setup v1.0.1 x64 | Windows x64 安装程序包 |
| ThingsEye Diagnosis Portable v1.0.1 x64 | Windows x64 便携包，无需安装 |
| ThingsEye Diagnosis-1.0.1 Mac | Mac ARM64 安装程序包 |
产品概述
ThingsEye Diagnosis App 可帮助用户快速识别设备的数据链路连接问题。用户使用 ThingsEye 主租户账户和密码登录后，可选择 NB-IoT 设备诊断或 LoRaWAN 设备诊断。
根据所选设备类型，系统会自动检查从设备接入、平台集成到数据转换和 ThingsEye 遥测存储的完整诊断链路。每个模块都会显示独立状态，以便用户快速定位数据链路中断的位置。
版本说明
- 对于 Windows，提供便携版和安装版。
- 对于 Mac，目前仅提供便携版。
- 要正式分发 Mac 版本，需要进行 Developer ID 签名和公证，以减少 Gatekeeper 安全提示和启动缓慢问题。
- 由于诊断期间多平台后端存在与隐私相关的集成问题，目前设备查询仅支持 主租户管理员账户。
- 使用下级账户的用户应联系主管理员协助诊断。
应用版本和运行模式
| 平台类型 | 版本类型 | 交付文件 | 运行方式 |
|---|---|---|---|
| Windows | 安装版 | ThingsEye_Diagnosis_Setup_1.0.1_x64.zip | 解压 zip 文件，运行安装程序，然后从开始菜单或桌面快捷方式打开程序。 |
| Windows | 便携版 | ThingsEye_Diagnosis_Portable_1.0.1_x64.zip | 解压 zip 文件，双击 ThingsEye Diagnosis.exe 运行程序。 |
| Mac | 便携版 | ThingsEye Diagnosis-1.0.1-arm64-mac | 解压包并打开 ThingsEye Diagnosis Core 运行程序。 |
注意：本页面可下载的文件为 Windows 安装包和 Windows 便携包。如需 Mac 包交付，请联系 ThingsEye 团队。
登录和诊断入口
- 打开 ThingsEye Diagnosis App 并进入登录页面。
- 输入主租户的 ThingsEye 用户名和密码。
- 登录后，选择要诊断的设备类型：NB-IoT 或 LoRaWAN。
- 按照屏幕提示输入或选择设备。
- 点击 Diagnose 查看各链路节点的诊断结果。
截图
NB-IoT 设备诊断链路
NB-IoT 设备诊断会检查以下路径：
UDP Forwarder → TE Integration → TE Converter → TE Device
| 链路节点 | 检查项 | 含义 |
|---|---|---|
| UDP Forwarder | 检查是否存在 IMEI、Topic、Ack Required 和转发记录。 | 确认 NB-IoT 设备已由 UDP Forwarder 转发。 |
| TE Integration | 检查数据是否已进入 ThingsEye Integration，并查询最近的 Integration 事件。 | 确认数据是否已到达 ThingsEye 集成入口。 |
| TE Converter | 检查 Integration 接收到的数据是否已由 Converter 解析和转换。 | 确认原始载荷能否转换为 ThingsEye 遥测数据。 |
| TE Device | 检查 IMEI 与 ThingsEye 设备名称是否完全匹配、设备是否存在、遥测数据和最后更新时间。 | 确认最终数据是否已添加到 ThingsEye 设备数据中。 |
4.1 UDP Forwarder
UDP Forwarder 模块确认 NB-IoT 设备是否有有效的转发记录。它会检查 IMEI、Topic、Ack Required 设置和转发记录是否存在。
重要：UDP Forwarder 注册和 ThingsEye Device 是否存在是相互独立的检查。即使 ThingsEye Device 不存在，只要存在正确的转发记录，UDP Forwarder 仍可标记为 Pass。
4.2 TE Integration
TE Integration 模块检查设备数据是否已进入 ThingsEye Integration。如果找到匹配的 Integration 事件，该模块可标记为 Pass。如果未找到事件但设备已有遥测数据，该模块可能显示 No Event。
4.3 TE Converter
TE Converter 模块检查 Integration 载荷是否已解析并转换为 ThingsEye 遥测数据。如果存在转换事件，该模块可标记为 Pass。如果未找到 Converter 事件但设备已有遥测数据，结果可能显示 No Event。
4.4 TE Device
TE Device 模块检查 ThingsEye 设备是否存在以及遥测数据是否可用。对于 NB-IoT 设备，设备查找要求设备 IMEI 与 device.name 完全匹配。
LoRaWAN 设备诊断链路
LoRaWAN 设备诊断会检查以下路径：
ChirpStack → ChirpStack Uplink → TE Integration → TE Converter → TE Device
| 链路节点 | 检查项 | 含义 |
|---|---|---|
| ChirpStack | 检查设备是否已注册。 | 确认 LoRaWAN 设备已在 ChirpStack 中正确创建。 |
| ChirpStack Uplink | 检查最后上行时间、上行帧计数以及 ChirpStack 是否已收到数据。 | 确认 LoRaWAN 网络已收到来自设备的上行数据。 |
| TE Integration | 检查数据是否已进入 ThingsEye Integration。 | 确认 ChirpStack 数据是否已进入 ThingsEye 集成网关。 |
| TE Converter | 检查上行载荷是否已由 ThingsEye Converter 解析和转换。 | 确认载荷能否转换为 ThingsEye 遥测数据。 |
| TE Device | 检查目标 ThingsEye 设备是否存在以及遥测数据是否可用。 | 确认数据是否最终到达 ThingsEye 设备。 |
5.1 ChirpStack
ChirpStack 模块检查 LoRaWAN 设备是否存在于 ChirpStack 中。如果设备已注册，即使下游 ThingsEye 模块失败，该模块也可通过。
5.2 ChirpStack Uplink
ChirpStack Uplink 模块检查 ChirpStack 是否已收到来自设备的上行数据，包括最后上行时间和上行帧计数。
5.3 TE Integration
TE Integration 模块检查 ChirpStack 数据是否已进入 ThingsEye Integration。如果未捕获到匹配事件但 ThingsEye 设备已有遥测数据，状态可能显示 No Event。
5.4 TE Converter
TE Converter 模块检查上行载荷是否已转换为 ThingsEye 遥测数据。如果未捕获到匹配的 Converter 事件但设备已有遥测数据，状态可能显示 No Event。
5.5 TE Device
TE Device 模块检查 ThingsEye 设备是否存在以及是否已收到遥测数据。如果设备有历史遥测数据但近期没有遥测数据，该模块可能显示 Pass(offline)。
诊断链路模块和颜色含义
| 状态 | 颜色 | 图标 | 显示文本 | 含义 |
|---|---|---|---|---|
| 已通过 | 绿色 | ✓ | Pass | 当前模块已通过检查，链路状态正常。 |
| 离线但此前已通过 | 灰蓝色 | ? | Pass(offline) | TE Device 有历史遥测数据，但超过 48 小时未收到新的遥测数据。 |
| 无事件但设备有数据 | 黄色 | ? | No Event | Integration / Converter 当前没有事件，但 TE Device 已有遥测数据。这通常发生在未启用 Debug 或未捕获到最近事件时。 |
| 失败 | 红色 | × | Fail | 没有匹配事件且没有遥测数据，系统无法验证数据已进入 ThingsEye。 |
Integration / Converter Debug 和事件说明
7.1 诊断逻辑
Integration 和 Converter 诊断依赖平台捕获的事件记录。如果启用了 Debug 并找到匹配事件，模块显示 Pass。如果未捕获到事件但设备已有遥测数据，模块显示 No Event，而不是直接失败。
7.2 事件显示规则
| 情况 | 显示状态 | 含义 |
|---|---|---|
| 无事件，但设备有遥测数据 | 黄色 ? / No Event | 设备数据曾在某个时间成功发送到 ThingsEye，但此时未捕获到 Integration 或 Converter 事件。 |
| 无事件且设备无遥测数据 | 红色 × / Fail | 没有证据表明数据已进入 ThingsEye；连接可能已失败。 |
| 启用 Debug 后仍无事件 | 继续排查 | 检查设备上报、UDP Forwarder / ChirpStack、Topic / DevEUI / IMEI、Integration 配置、Converter 绑定和载荷格式。 |
链路诊断和故障排查顺序
8.1 LoRaWAN 设备
- 确认设备已在 ChirpStack 中注册。
- 确认 ChirpStack 已收到上行数据。
- 检查 TE Integration 是否有匹配的调试事件。
- 检查 TE Converter 是否有匹配的调试事件。
- 确认 TE Device 存在并已收到遥测数据。
8.2 NB-IoT 设备
- 确认 UDP Forwarder 注册和 Topic 正确。
- 确认 IMEI 和 Topic 完全准确。
- 检查 TE Integration 是否有匹配的调试事件。
- 检查 TE Converter 是否有匹配的调试事件。
- 确认 TE Device 名称与设备 IMEI 完全匹配。
- 确认 TE Device 已收到遥测数据。
诊断状态示例
9.1 NB-IoT 设备诊断状态示例
9.1.1 NB-IoT：整条链路显示 Pass
图 1：NB-IoT 全链路 Pass。
当 UDP Forwarder、TE Integration、TE Converter 和 TE Device 全部显示 Pass 时，完整 NB-IoT 诊断链路工作正常。
9.1.2 NB-IoT：前三个部分通过，TE Device 显示 Pass(offline)
图 2：NB-IoT TE Device Pass offline。
这意味着设备存在且有历史遥测数据，但最近未收到新的遥测数据。请检查设备电源状态、网络可用性、SIM 状态和上报间隔。
9.1.3 NB-IoT：Integration / Converter 显示 No Event，设备已通过
图 3：NB-IoT No Event 但设备 Pass。
这通常意味着设备在 ThingsEye 中有遥测数据，但未捕获到最近的 Integration 或 Converter 调试事件。请启用 Debug 并触发新的上行，然后再次运行诊断。
9.1.4 NB-IoT：整条链路显示 Fail
图 4：NB-IoT 全链路 Fail。
如果整条链路失败，首先检查设备是否已在 UDP Forwarder 中正确配置，以及 IMEI 和 Topic 是否正确。
9.1.5 NB-IoT：UDP Forwarder 通过，下游链路失败
图 5：NB-IoT UDP Forwarder Pass，下游 Fail。
这意味着存在转发记录，但数据可能未到达 ThingsEye Integration，或未被 Converter 处理。请检查 Integration 配置、Converter 绑定、Topic 设置和载荷格式。
9.1.6 NB-IoT：UDP Forwarder 通过，下游链路失败且无遥测数据
图 6：NB-IoT UDP Forwarder Pass，无遥测数据。
这意味着 UDP Forwarder 有有效的转发记录，但下游 ThingsEye 处理链未完成，且没有有效遥测数据写入 TE Device。
建议检查：
- 确认 UDP Forwarder 中配置的 IMEI 和 Topic 与 Integration 配置完全匹配。
- 确认 Integration 已启用并监听正确的 Topic。
- 确认正确的 Converter 已绑定到 Integration。
- 检查 Converter 是否能正确解析 NB-IoT 载荷格式。
- 确认 TE Device 名称与 IMEI 完全匹配，并创建在正确的租户账户下。
9.2 LoRaWAN 设备诊断状态示例
9.2.1 Integration / Converter 显示 No Event，设备显示 Pass
图 7：LoRaWAN No Event 但设备 Pass。
这意味着 ThingsEye 设备有遥测数据，但未捕获到当前 Integration 或 Converter 事件。请启用 Debug 并触发新的上行。
9.2.2 LoRaWAN：全链路绿色 Pass
图 8：LoRaWAN 全链路 Pass。
当 ChirpStack、ChirpStack Uplink、TE Integration、TE Converter 和 TE Device 全部显示 Pass 时，完整 LoRaWAN 诊断链路工作正常。
9.2.3 LoRaWAN：Integration / Converter 显示 No Event，设备显示 Pass(offline)
图 9：LoRaWAN No Event 且 Pass offline。
这意味着设备有历史遥测数据，但近期没有遥测数据。请检查设备当前是否在线，以及 ChirpStack 是否正在接收上行数据。
9.2.4 LoRaWAN：ChirpStack 已注册，Uplink 及后续链路失败
图 10：LoRaWAN 已注册但上行 Fail。
这意味着设备存在于 ChirpStack 中，但未收到上行数据。请检查网关覆盖、设备激活、DevEUI/AppKey 配置、频段计划和设备电源状态。
9.2.5 LoRaWAN：ChirpStack 已注册，Uplink 及下游链路失败且无设备事件
图 11：LoRaWAN 已注册但下游 Fail 且无事件。
这意味着 ChirpStack 中有设备记录，但缺少上行数据或下游 ThingsEye 事件。请检查 ChirpStack 上行、Integration 连接、Converter 绑定和设备身份映射。
注意事项
- 设备查询目前仅支持主租户管理员账户。
- NB-IoT 设备查找要求 IMEI 与 ThingsEye 设备名称完全匹配。
- UDP Forwarder 注册与 ThingsEye Device 是否存在相互独立。
- LoRaWAN 设备诊断遵循 ChirpStack 设备身份和上行事件。
- 存在但近期没有遥测数据的设备可能显示 Pass(offline)。
- 当平台链路存在但未找到最近的匹配事件时，Integration 或 Converter 可能显示 No Event。