设备接入
约 1464 字大约 5 分钟
设备接入联犀协议网关接入协议扩展
2025-01-27
设备接入部分主要回答一个问题：
当你已经决定把设备接入联犀之后，应该走哪条链路，如何在“原生能力、协议扩展和网关形态”之间做选择。
原生 MQTT：从零接通一台设备
这条路径可独立完成接入，详细参数、报文与排障见联犀协议设备接入教程。
- 创建产品：在物联网后台“设备接入 → 产品管理”新建直连设备产品，选择内置物模型协议和密钥认证。
- 定义属性：进入该产品“物模型”，至少添加一个属性，记下大小写一致的标识符，例如
temperature。 - 创建设备：在“设备接入 → 设备管理”选择该产品创建设备，进入设备详情“设备接入”取得 MQTT 地址、ClientID、用户名和密码。
- 连接 MQTT：将这些参数填入 MQTTX 或设备固件，连接后检查设备状态为“在线”。
- 上报属性：向
$thing/up/property/{productID}/{deviceName}发布{"method":"report","msgToken":"access-1","params":{"temperature":25}}，标识符须换成刚定义的属性。 - 验收与排障：在设备详情“属性”查看该属性的实际值和平台接收时间，并在“日志”核对报文。只有设备当前在线且定义的属性已有实值与接收时间，才算本次接入完成。
HTTP、动态注册、第三方协议和网关接入见下方独立分支，不沿用上述 MQTT 验收结论。
先用自己的 AI 辅助接入
把设备资料交给 WorkBuddy、Codex 等支持命令和 Skills 的 AI 工具，说清楚要接入哪个项目、希望看到什么数据。AI 借助联犀 CLI 与 Skills 生成配置并检查上报；遇到离线、没有数据或数值异常，继续问它即可，不要求你手动下载物模型或分析日志。
从让 AI 接入和调试设备开始；尚未准备工具时，可以让 AI 按本地 AI 安装教程协助安装。你完成本人授权和必要的接线、联网等现场操作。以下协议资料供开发者或 AI 进一步参考，不必先逐篇阅读。
三类入口
联犀协议
适合直接按联犀原生方式接入设备的场景。
如果你希望获得完整的平台能力，通常应该优先从这里开始。
这里重点包括：
- 设备身份认证
- MQTT 认证
- HTTP 接入
- 动态注册
- 物模型协议
- 设备服务
- OTA 升级
- NTP 时间同步
- 网关子设备
- 设备远程配置
第三方协议
适合设备已有既定协议、历史系统或外部云平台对接场景。
这部分更关注：
- 如何快速接入第三方协议
- 如何使用协议网关
- 如何开发协议网关
- 如何使用协议脚本
它更适合“平台适配已有设备生态”，而不是从零定义设备接入协议。
网关接入
适合现场存在网关、边缘节点或协议汇聚层的场景。
这部分更关注：
怎么选接入方式
设备是新接入，协议可控
优先选 联犀协议。
这样平台能力最完整，认证、物模型、控制、日志、OTA 等能力都更顺。
设备已经在线运行，协议不可改
优先看 第三方协议。
这类场景更强调兼容和迁移，而不是重新设计设备端。
设备前面已有网关或边缘节点
优先看 网关接入。
这类场景的重点不只是设备连不连得上，而是怎样组织网关、子设备和现场数据链路。
推荐阅读顺序
如果你是做真实接入项目，建议按这个顺序：
接入时最容易忽略的几个点
- 不要只验证“设备上线”，还要验证属性、事件、控制和异常链路
- 不要只关注协议格式，还要关注物模型语义是否统一
- 不要只做单设备验证，还要提前考虑批量设备和网关场景
- 不要把日志、远程配置、OTA 等运维能力留到最后再补
本部分适合谁看
- 设备端开发人员
- 协议开发人员
- 网关对接人员
- 平台实施工程师
- 需要做设备生态兼容的技术负责人
和其它文档的关系
提示
如果你不确定该选哪条设备接入路径，优先从 联犀协议 开始理解平台的标准能力边界，再决定是否退回第三方协议或网关模式。
接入成功后，欢迎在 Gitee 为 物联网模块 点亮 Star；遇到问题可提交 Issue。
更新日志
2026/10/8 20:48
查看所有更新日志
83986-docs(快速开始): 直接进入安装教程于9c9b0-feat(文档站): 精简导航并完善物联网模块接入与关注引导于54945-docs(文档站): 统一官网入口并完善 AI 辅助接入说明于7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于696a2-优化使用文档入口结构于17288-doc于