此文档介绍设备接入浪潮云物联网服务的操作过程，用户可参考操作，快速实现设备接入。
浪潮云IoT服务快速入口

产品简介

浪潮云物联网服务是一个全托管的云服务，提供一个安全、稳定、高效的连接平台，旨在帮助开发者建立设备与云端之间安全可靠的双向连接，以支撑海量设备数据收集、监控、故障预测等物联网场景，可以实现设备之间的互动、设备的数据上报和配置下发，基于规则引擎和浪潮云其他产品打通，方便快捷地实现海量设备数据的存储、计算以及智能分析。

名词&概念

接入流程

1. 接入需求分析

进行物联网设备接入前，首先对接入需求进行分析，整理出设备种类、型号、数量以及接入方式、需要采集或控制的属性点等。
接入的设备可以归纳为两大类场景：自有设备接入和产品设备接入。其中，自有设备接入是指将已拥有的设备进行接入，亦可理解为设备智能化改造；产品设备接入是指用户作为设备的制造商或运营商，将自身生产或运营的智能产品接入平台，为其客户提供智能设备或服务。

1. 产品注册

在平台对设备型号进行建模描述，建模过程称之为产品注册。

• 创建产品

录入产品的名称、节点类型、产品模板、数据格式、描述等基本信息，对产品进行创建。

  - 所属项目：项目指租户下的一个接入单元，目前平台只允许用户创建一个项目；
  - 产品名称：对应设备型号名称，平台暂未支持在产品下区分和管理不同的型号，故此处产品名称的命名建议采用“产品名称+型号”的方式（例：苹果手机-A2102），如不要在产品下区分型号，亦可直接只用产品名称命名；
  - 节点类型：根据设备的接入方式选择直连设备、网关、子设备；
  - 产品模板：平台预制了一些产品模板供用户快速选择，模板中定义了该类设备常用的一些属性，选择模板后这些属性会直接初始化到物模型中；
  - 数据格式：目前仅支持透传/自定义格式；
  - 描述：对产品的一些说明、备注等描述信息。

• 配置产品标签

产品标签主要用于表示某个设备类型共有的静态属性，如制造商、产品型号、颜色、重量、长、宽、高等，产品下的设备可以直接继承产品标签。

  - 标签key：标签的变量标识，英文命名，如corlor；
  - 显示名称：标签的应用显示名称，如：颜色；
  - 标签value：标签的属性值，如：红色。

• 配置物模型（功能定义）

对产品功能定义的模型化描述称之为物模型，故功能定义也称之为物模型。功能定义主要用于定义产品的属性、事件、服务，目前浪潮云物联网服务只支持属性定义。一般来说，需要监测和控制的设备的动态属性（温度、压力等）在平台使用功能定义中属性来描述。

  - 功能类型：默认选中属性，当前仅支持属性；
  - 功能名称：属性、服务、时间的显示名称；
  - 数据类型：根据监控属性的实际数据类型选择，支持float、int、double、enum、bool、text、date；
  - 取值范围：数据类型为数值型（int、float、double）时填写，可用于后续超限报警等；
  - 步长：数据类型为数值型（int、float、double）时填写，可用于后续数据分析、展示等；
  - 单位：数据类型为数值型（int、float、double）时可填写，可用于后续应用展示等；
  - 枚举项：数据类型为枚举（enum）时填写，可设置多个枚举项，参数值-设备上报的属性值，参数描述-该属性代表的含义，例：1001-待机；
  - 布尔值0/布尔值1：数据类型为布尔（bool）时填写，分别代表false和true的含义，例布尔值0-关闭，布尔值1-打开；
  - 数据长度：数据类型为文本（text）时填写，文本的最大长度，可用于后续应用校验；
  - 时间格式：数据类型为时间（date）时选择，默认选中“String类型的UTC时间戳（毫秒）”，当前仅支持该时间格式；
  - 读写类型：该属性的读写权限，读写-设备可以上报该属性，平台可以下发指令设置该属性的值，只读-设备可以上报该属性，平台不能下发指令设置该属性；
  - 描述：对该属性的说明、备注等描述信息。

• 物模型导出导入

平台提供物模型导入导出功能，该功能可以解决属性的批量录入问题，极大的提供物模型的配置效率。

  - 导出物模型：可以将已经定义的属性导出为物模型json文件，编辑修改后导入；
  - 导入物模型：支持拷贝其他产品和物模型文件导入，两种方式均采用覆盖式导入机制，即导入的物模型会覆盖掉产品已经定义的全部属性，请特别注意。

• 配置产品接口（Topic类）

浪潮云物联网服务使用MQTT协议作为设备接入协议，MQTT的通信方式是通过发布/订阅的方式进行的，topic可以理解为消息的类型，订阅者订阅（Subscribe）后，就会收到该主题的消息内容（payload）。
对于设备来说一个Topic可以理解为是设备接收/上报数据的某个接口，向某个topic发布消息=向某个接口上报数据，订阅某个topic=从某个接口获取数据。
topic类实际上是某个产品类型设备的topic模板，在产品上定义了topic类，产品实例化设备时会自动赋予设备具体的主题权限（发布/订阅），如iot/iotxwmwvo15/09l3bdnf/${deviceCode}/shadow/update,topic类中的每一层代表不同的含义，具体组成规则为“topic类型/项目编码/产品编码/设备编码占位符/URI”，topic类型iot-平台定义的系统topic，usr-用户自定义的topic，URI为具体的资源路径可由用户自定义。
系统定义的设备影子及设备端通用topic，供用户直接使用，该类topic类不允许编辑，如不满足需求可自定义topic类。
系统topic列表如下：

iot/{endpointCode}/{IotModelCode}/{IotDeviceCode}/ | 设备影子 | shadow/update | 更新设备影子 | √ | 　 | √ | 　 | √ | √ | √ |

| | | shadow/update/accepted | 更新成功响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/update/rejected | 更新失败响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/update/documents | 设备影子更新通知 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/update/delta | 更新增量通知 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/get | 获取设备影子 | √ | 　 | 　 | 　 | √ | √ | √ | | | | shadow/get/accepted | 获取影子成功响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/get/rejected | 获取影子失败响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/delete | 删除设备影子 | √ | 　 | 　 | 　 | √ | √ | √ | | | | shadow/delete/accepted | 删除设备影子成功响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | | shadow/delete/rejected | 删除设备影子失败响应 | 　 | √ | 　 | 　 | √ | √ | √ | | | 通用数据上下行接口 | event | 数据上报接口 | √ | 　 | 　 | 　 | √ | √ | √ | | | | control | 数据下发接口 | 　 | √ | √ | 　 | √ | √ | √ | | | 设备拓扑关系 | thing/topo/get | 获取设备的拓扑关系 | √ | 　 | 　 | 　 | 　 | √ | 　 | | | | thing/topo/get_reply | 设备的拓扑关系响应 | 　 | √ | 　 | 　 | 　 | √ | 　 | | | 子设备上下线 | online | 子设备上线 | √ | 　 | 　 | 　 | 　 | √ | 　 | | | | online_reply | 子设备上线响应 | 　 | √ | 　 | 　 | 　 | √ | 　 | | | | offline | 子设备下线 | √ | 　 | 　 | 　 | 　 | √ | 　 | | | | offline_reply | 子设备下线响应 | 　 | √ | 　 | 　 | 　 | √ | 　 | | | 设备生命周期变更 | mqtt/status | 设备上下线状态 | 　 | √ | 　 | 　 | √ | √ | √ | | | TSL物模型模板 | thing/dsltemplate/get | 获取设备的TSL模板 | √ | 　 | 　 | 　 | √ | √ | √ | | | | thing/dsltemplate/get_reply | 设备的TSL模板响应 | 　 | √ | 　 | 　 | √ | √ | √ | | 自定义主题
usr/{endpointCode}/{IotModelCode}/{IotDeviceCode}/ | 用户自定义主题 | xxx/xxx/xxx | 设备仅有订阅权限的自定义主题 | 　 | √ | √ | 　 | √ | √ | √ | | | | xxx/xxx/xxx | 设备仅有发布权限的自定义主题 | √ | 　 | 　 | 　 | √ | √ | √ | | | | xxx/xxx/xxx | 设备有发布和订阅权限的自定义主题 | √ | √ | √ | 　 | √ | √ | √ |

• 添加自定义topic类

  - 设备操作权限：可选订阅、发布、发布和订阅；
  - topic类：自定义topic类资源地址，权限是订阅时支持通配符；
  - 描述：一些说明备注等描述信息。

• 服务端订阅

通过设置服务端订阅，物联网服务可以把用户需要订阅的消息主动推送到用户服务器进行实时业务处理。
功能正在测试中，下一个版本（v1.4.0）中发布，支持设备状态变化通知、设备影子更新通知两类消息的订阅。

1. 设备注册

产品注册和配置完成后，将需要接入的设备添加到平台。

• 单个添加设备

  

  • 所属产品：选择设备所属的产品；
  • 设备编码：可自定义设备编码，可使用设备自身携带的唯一标识作为编码，如不修改则默认使用系统生成的字符串作为设备编码；
  • 备注名称：标识设备的备注信息，便于区分具体设备，如：张三的苹果手机；
  • 描述：一些对设备的说明备注等描述信息。
• 批量添加设备

  ![image.png](https://cdn.nlark.com/yuque/0/2019/png/250308/1561467343436-57f37693-5dc9-40a2-8297-9890c3eec038.png#align=left&display=inline&height=215&name=image.png&originHeight=287&originWidth=525&size=18873&status=done&width=394)
  - 所属产品：选择设备所属的产品；
  - 添加方式：自动生成-输入设备数量，系统自动分配设备编码添加指定数量的设备，批量上传-使用模板批量注册设备，可以自定义每台设备的设备编码；
  - 设备数量：添加方式选择自动生成时需要添加的设备数量。
  - 上传文件：添加方式选择批量上传时需选择导入的文件，先下载模板，填写后导入。

• 动态注册

直连设备和网关可以通过内置产品秘钥，动态注册设备到平台，而不需要在每个设备内烧录不同的证书。
功能正在测试中，下一个版本（v1.4.0）中发布。

• 添加设备标签

设备标签与产品标签类似，主要用于表示设备的静态属性，设备除集成产品标签（value值可以修改）以外，可以由用户根据需要自定义设备标签，如安装位置、使用者等。

• 网关绑定子设备

子设备需要绑定到网关，建立拓扑关系后才能由网关对子设备数据进行上报。网关绑定子设备的操作在网关设备下进行，由网关详情页的子设备tab标签进入。
添加子设备需先将子设备注册，已添加的子设备可以在列表中被选中后绑定到网关，可选则的子设备列表中只显示未被任何网关绑定的子设备，即一个子设备只能绑定到一个网关下。
一个网关最多可以绑定1500个子设备，考虑网关的性能和单个MQTT连接上下行消息限制等因素，建议实际接入过程中网关挂载的子设备数量不宜过多。

1. 设备接入及调试

设备注册完成后，平台会为直连设备和网关设备分配接入地址、证书等设备接入需要的凭证信息。

• 下载SDK，在帮助中心>产品文档中下载相应的SDK。
  • 当前支持C、python、java三种语言的SDK支持，不同语言的SDK接口设置和使用说明，可参加相关文档。
  • SDK中封装了设备影子服务和设备端接口（topic）的全部操作方法，开箱即用，可帮助用户提高开发效率。
  • 如SDK不能满足用户的开发需求，也可参考SDK的接口实现逻辑自行开发实现与平台的交互逻辑，自行实现时可参考产品文档中设备影子、设备端接口相关内容。

• 接入前需在设备详情页下载设备证书，并在配置信息页提前记录设备的配置信息。

  

• 设备与平台建立连接

  • 如使用SDK进行开发，则只需要将配置信息放入相应的配置文件中，运行SDK即可建立与平台的连接；
  • 如自行开发实现连接，浪潮云MQTT连接鉴权采用SSL/TLS方式，采用CA证书进行鉴权，连接建立和接口测试可参考产品文档中使用MQTT.fx接入章节。需要特别注意，建立连接时对于clientId有固定的格式要求，使用不符合规范的clientId进行连接时客户端将被频繁踢下线。

  • 浪潮云IoT hub与Paho（MQTT Client SDK）完全兼容，推荐使用Paho开发MQTT客户端，可到Paho官方网站下载SDK并获取帮助文档，各语言支持详情如下： | Client | MQTT 3.1 | MQTT 3.1.1 | LWT | SSL/TLS | Automatic Reconnect | Offline Buffering | Message Persistence | WebSocket Support | Standard MQTT Support | Blocking API | Non-Blocking API | High Availability | | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | :—-: | | Java | √ | √ | √ | √ | √ | √ | √ | √ | √ | √ | √ | √ | | Python | √ | √ | √ | √ | √ | √ | ╳ | √ | √ | √ | √ | ╳ | | JavaScript | √ | √ | √ | √ | √ | √ | √ | √ | ╳ | ╳ | √ | √ | | GoLang | √ | √ | √ | √ | √ | √ | √ | √ | √ | ╳ | √ | √ | | C | √ | √ | √ | √ | √ | √ | √ | ╳ | √ | √ | √ | √ | | .Net (C#) | √ | √ | √ | √ | ╳ | ╳ | ╳ | ╳ | √ | ╳ | √ | ╳ | | Android Service | √ | √ | √ | √ | √ | √ | √ | √ | √ | ╳ | √ | √ | | Embedded C/C++ | √ | √ | √ | √ | ╳ | ╳ | ╳ | ╳ | √ | | | |

  • 直连设备或网关连接成功后平台会显示设备激活和设备的在线状态。

• 子设备接入和消息交互
  • 子设备通过网关代理与平台进行数据交互，网关拥有子设备所有的topic权限，发布和订阅相应的topic即可实现代理子设备发布/订阅消息；
  • 子设备上线时需网关调用online接口主动上报子设备在线状态，之后需要网关监测子设备的在线状态，如子设备与网关连接断开，则网关需主动上报子设备离线，以改变子设备在平台的在线状态为离线；
  • 平台通过监测子设备与平台的消息交互判断子设备的在线状态，当前心跳周期为300s，暂不支持用户自定义该周期，子设备在300s内向平台发布任意消息即会记录一个300s的在线时长，超过300s无任何消息交互则子设备会被平台设置为离线状态，这也就要求如果需要保持子设备在线状态，如300s内无业务数据上报，需网关发布一条子设备的心跳消息到平台（可以使用online接口或任意子设备topic），以保持子设比的在线状态。
  • 子设备和网关相关的接口和交互逻辑可参考产品文档设备端接口相关内容。
    1. 数据转发和存储（可选）

设备连接到平台后，设备数据可以通过配置规则引擎实现数据的转发和存储，之后用户可以使用设备数据进行应用开发、数据分析等。

• 创建规则
• 订阅topic
• 编写SQL查询语句
• 设置数据目的地的
  1. 应用开发

平台提供了几乎控制台全部操作的OpenAPI，用户可以通过restful接口结合MySQL/TSDB数据库进行设备应用开发，构建丰富的设备管理、能源管理等APP。
OpenAPI列表（接口定义详见产品文档>云端API参考）：

• 项目管理相关接口 | 接口 | 描述 | | :—-: | :—-: | | 项目列表 | 查询所有项目列表 | | 创建项目 | 创建项目 | | 项目详情 | 查询指定项目详情 | | 修改项目 | 修改指定项目 |

• 产品管理相关接口 | 接口 | 描述 | | :—-: | :—-: | | 产品列表 | 查询项目下所有产品列表 | | 产品详情 | 查询指定产品详情 | | 产品功能定义详情 | 查询指定产品物模型（功能定义列表） | | 创建产品 | 创建产品 | | 修改产品 | 修改产品 | | 删除产品 | 删除产品 | | 产品发布 | 产品发布 | | 创建产品标签 | 创建产品标签 | | 修改产品标签 | 修改产品标签 | | 删除产品标签 | 删除产品标签 | | 创建产品功能 | 创建产品功能 | | 修改产品功能 | 修改产品功能 | | 删除产品功能 | 删除产品功能 |

• 设备管理相关接口 | 接口 | 描述 | | :—-: | :—-: | | 创建设备 | 添加设备 | | 指定产品设备列表 | 查询指定产品下所有设备列表 | | 设备详情 | 查询指定设备详情 | | 修改设备 | 修改指定设备 | | 删除设备 | 删除指定设备 | | 查询指定设备状态 | 查询指定设备的运行状态（在线/离线和激活/未激活） | | 指定产品下所有设备状态 | 批量查询同一产品下指定设备的运行状态 | | 子设备所属网关 | 根据子设备信息查询对应的网关设备信息 | | 指定设备标签列表 | 查询指定设备的标签列表 | | 创建设备标签 | 为指定设备设置标签 | | 删除设备标签 | 删除设备下的指定标签 | | 网关下子设备列表 | 查询指定设备的拓扑关系（网关设备下子设备列表） | | 网关绑定子设备 | 添加子设备到网关 | | 网关解绑子设备 | 从网关中移除子设备 | | 自定义主题发布 | 自定义主题发布 |

• 设备影子相关接口 | 接口 | 描述 | | :—-: | :—-: | | 查询设备影子 | 查询指定设备的影子信息 | | 更新设备影子 | 更新指定设备的影子信息 |

设备接入示例

• 演示场景

1. 需求分析
   • 需求描述：
     • 灯泡自身不具备联网能力，需要通过网关进行接入；
     • 灯泡在待机状态下可以远程控制点亮和关机；
     • 灯泡默认显示白色光，可以远程设置灯泡改变颜色；
     • 灯泡关闭后再次打开灯光为关机前的颜色或用户设置的颜色。
   • 分析：
     • 由于灯泡没有存储能力，关灯之后不会存储自己上一次显示的状态，使用设备影子，能够实现这一功能。
     • 灯泡打开时，去读取影子信息，显示对应的状态，然后上报到云端，存储当前状态。
     • 之后每次打开，都去读取影子信息，显示期望改变成的状态或上一次显示的状态。
     • 灯泡在点亮或待机状态下，网关可以实时读取读取影子的增量信息，发现期望状态和当前状态不一致时，发送指令给灯泡改变灯泡的颜色，设置成功后上报最新状态。
   • 产品设计：
     • 定义灯泡产品
       • 产品名称：智能灯泡
       • 节点类型：子设备（需要通过网关接入）
       • 产品模板：自定义（自定义功能属性）
       • 数据格式：透传/自定义
       • 描述：演示用的产品智能灯泡
       • 产品属性：
         • 状态-LightStatus-开启（1）、待机（0）两种状态-读写
         • 颜色-color-可选值红色（red）、蓝色（blue）、白色（white）-读写
     • 定义网关产品
       • 产品名称：智能家居网关
       • 节点类型：网关
       • 产品模板：边缘计算/边缘网关（直接选择平台预制网关模板，也可自定义）
       • 数据格式：透传/自定义
       • 描述：智能家居网关
       • 产品属性：使用产品模板已定义的默认属性
     • 功能流程

使用平台提供的设备影子服务进行设备开发

     - 网关设备与平台建立连接
     - 网关主动获取设备配置信息（设备影子）、拓扑关系，进行初始化并上报自身状态；
     - 网关获取灯泡与网关的连接状态，若灯泡与网关连接正常，则上报灯泡上线；
     - 网关上报灯泡状态和接收平台下发的远程指令；
     - 将灯泡的状态存储到MySQL数据库。

1. 产品注册

使用上述产品定义的内容创建和配置网关、智能灯泡两个产品。

1. 设备注册及子设备绑定
   • 在平台注册一个网关设备和一个智能灯泡设备

• 将智能灯泡设备绑定到网关

• 下载网关证书备用

1. 设备接入及调试
   • 使用MQTT.fx模拟设备连接平台
   • 使用SDK模拟设备接入平台
   • 使用python开发MQTT客户端(详见下方代码参考)

模拟数据

• 网关上报数据,设备首次上线（激活）时主动上报状态。

{
    "state":{
        "reported":{
            "memory_usage":50,
            "gateway_version":"1.0.0",
            "cpu_usage":30,
            "system_info":"test",
            "memory_total":2147483647,
            "memory_free":483647,
            "cpu_core_number":2,
            "disk_usage":30
        }
    }
}

• 网关上报子设备上线

{
    "id":"123",
    "params":{
        "IotModelCode":"替换为产品编码",
        "IotDeviceCode":"替换为设备编码",
        "clientId":"123",
        "timestamp":1561538284
    }
}

• 灯泡上报数据,设备首次上线（激活）时主动上报当前状态为开启，颜色为红色。

  {
  "state":{
     "reported":{
         "LightStatus":1,
         "color":1
     }
  }
  }

• 向灯泡灯泡下发远程指令及灯泡接收指令。

{
    "state":{
        "desired":{
            "color":2
        }
    }
}

1. 数据转发、存储

   • 使用规则引擎转储灯泡数据到MySQL

   • 使用规则引擎实现两个灯泡联动

2. 应用开发
   • 待续…

     代码参考

     演示涉及的操作源程序下载地址：https://github.com/atorber/inspur-iot.git。

     使用限制

     参考产品文档相关内容。

     Q&A

     参考产品文档相关内容。