硬件云（私网版）

硬件云（私网版）-使用手册

姚智聪最后一次编辑

大约 3 年前 185

硬件云（私部署）平台产品说明为硬件设备提供安全可靠的连接通信能力，可支撑海量设备接入，支持数据在私有云环境下流转；为其他关联业务提供API，业务端通过调用API将指令下发至设备端，实现远程控制。本平台提供网关设备管理和设备管理、提供订阅接口获取topic，为各类IoT场景和行业开发者提供稳定且高效的物联网设备接入能力。
备注：本平台是PAAS平台，仅提供服务的接入能力，不对数据信息做区分，因部署在私网环境下，数据安全部分请用户做好防范。

1. 设备接入物联网平台支持海量设备连接上云，设备与云端通过IoT Hub进行稳定可靠地双向通信。 • 提供设备端SDK、驱动、软件包等帮助不同设备、网关轻松接入私有云。 • 4G/5G）、NB-IoT、Wi-Fi等不同网络设备接入方案，解决企业异构网络设备接入管理痛点。 • 提供既满足长连接的实时性需求，也满足短连接的低功耗需求的sdk。

2.设备管理物联网平台提供完整的设备生命周期管理功能，支持设备注册、功能定义、数据解析、在线调试、远程配置、实时监控、分组管理、设备删除等功能。

提供设备优模型，简化设备功能定义，方便应用开发。
提供设备上下线变更通知服务，方便实时获取设备状态。
提供数据存储能力，方便用户海量设备数据的存储及实时访问。

3.安全能力物联网平台提供多重防护，有效保障设备和云端数据的安全。

提供一机一密的设备认证机制，降低设备被攻破的安全风险。适合有能力批量预分配设备证书（产品ID、设备ID和设备密钥），将设备证书信息烧入到每个设备的芯片。安全级别高。
提供一型一密的设备认证机制。设备预烧产品证书（产品密钥和产品ID），认证时动态获取设备证书（产品ID、设备ID和设备密钥）。适合批量生产时无法将设备证书烧入每个设备的情况。安全级别普通。

4.通信安全

支持TLS（MQTT\HTTP）、DTLS（CoAP）数据传输通道，保证数据的机密性和完整性，适用于硬件资源充足、对功耗不是很敏感的设备。安全级别高。
支持设备权限管理机制，保障设备与云端安全通信。
支持设备级别的通信资源（Topic等）隔离，防止设备越权等问题。

设备接入：

提供不同协议类型的设备接入的SDK
集成设备配网方案

硬件云（私网）：

产品和设备的生命周期管理
设备数据存储
运维监控，实时状态和历史状态

信息安全：

私网环境下数据快速回收，信息安全性高，不易丢失。

灵活扩展：

可根据提供的API，根据业务场景快速拓展

以下主要介绍硬件云的相关名词解释：

名称	描述
产品	设备的集合，通常指一组具有相同功能的设备。物联网平台为每个产品颁发全局唯一的ProductKey。
设备	归属于某个产品下的具体设备。物联网平台为设备颁发产品内唯一的证书DeviceName。设备可以直接连接物联网平台，也可以作为子设备通过网关连接物联网平台。
网关	能够直接连接物联网平台的设备，且具有子设备管理功能，能够代理子设备连接云端。
子设备	本质上也是设备。子设备不能直接连接物联网平台，只能通过网关连接。
设备证书（设备三元组）	设备证书指产品ID、设备ID、设备密钥。产品ID：是物联网平台为产品颁发的全局唯一标识。该参数很重要，在设备认证以及通信中都会用到，因此需要您保管好。设备ID：在注册设备时，自定义的或自动生成的设备名称，具备产品维度内的唯一性。该参数很重要，在设备认证以及通信中都会用到，因此需要您保管好。设备密钥：物联网平台为设备颁发的设备密钥，和DeviceName成对出现。该参数很重要，在设备认证时会用到，因此需要您保管好并且不能泄露。
ProductSecret	由物联网平台颁发的产品密钥，通常与ProductKey成对出现，可用于一型一密的认证方案。该参数很重要，需要您保管好，不能泄露。
标签	标签分为产品标签、设备标签。产品标签：描述同一个产品下，所有设备所具有的共性信息。设备标签：通常根据设备的特性为设备添加的特有的标记，您可灵活自定义标签内容。
优模型	是对设备在云端的功能描述，包括设备的属性、服务和事件。物联网平台通过定义一种物的描述语言来描述物模型，称之为 TSL（即 Thing Specification Language），采用JSON格式，您可以根据TSL组装上报设备的数据。
属性	设备的模型之一，一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持 GET 和 SET 请求方式。应用系统可发起对属性的读取和设置请求。
服务	设备的模型之一，设备可被外部调用的能力或方法，可设置输入参数和输出参数。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务。
事件	设备的模型之一，设备运行时的事件，事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。
数据解析脚本	针对采用透传格式/自定义数据格式的设备，需要在云端编写数据解析脚本，将设备上报的二进制数据或自定义的JSON数据，转换为平台上的Alink JSON数据格式。
场景联动	场景联动是一种开发自动化业务逻辑的可视化编程方式，您可以通过可视化的方式定义设备之间联动规则，并将规则部署至云端或者边缘端。
一型一密	同一产品下所有设备可以烧录相同产品证书（即ProductKey和ProductSecret）。设备发送激活请求时，物联网平台进行产品身份确认，认证通过，下发该设备对应的DeviceSecret。
一机一密	每个设备烧录其唯一的设备证书（ProductKey、DeviceName和DeviceSecret）。当设备与物联网平台建立连接时，物联网平台对其携带的设备证书信息进行认证。

关键操作	说明
创建产品	在开发者中心前端页面创建产品档案，产品信息包括产品名称、节点类型、联网方式等信息。
产品优模型开发	定义产品的通讯协议，系统封装成属性、服务和事件。
应用服务端开发	基于硬件云平台提供的API接口，便于设备的远程监控和控制。
设备开发	设备接入硬件云平台提供的设备端 SDK ,便于设备能够接入到IoT平台，并能正常上报数据和接收命令。

关键操作	说明
注册设备	设备在接入前，需要在硬件云平台为设备开户，将设备接入需要的信息提前录入到硬件云平台，也就是得闲生成设备的三元组。
接入设备	设备通电，被用户激活后，设备能够正常接入到硬件云平台。

关键操作	说明
调测应用后台	应用接入硬件云平台后，查看应用服务器是否能够远程控制设备。

进入系统后根据提示进行产品创建

进入菜单【IoT 硬件云】 - 【产品】管理页面：

点击右上角【创建产品】的按钮，在弹窗中按照提示填写产品的基本信息，然后点击“完成”进行产品创建。

创建成功，会生成产品的唯一标识符产品ID。

每个开发者账号最多创建 100 款产品。
每款产品的 ProductKey 都是唯一的，由系统自动生成的，如果该的产品被删除了，要重新创建，那么原来已经烧录了三元组的设备要重新烧录，请谨慎删除产品。

优模型，将实际产品抽象成由属性、服务、事件所组成的数据模型，便于云端管理和数据交互。产品创建完成后，开发者可以为它定义优模型，产品下的设备将自动继承优模型内容。

为了方便开发者定义产品的物模型，以下用取餐柜作为一个示例（仅提供参考），协助理解属性、服务、事件的定义：

属性：

服务：

事件：

点击已经创建的产品，进入产品的详情页面，点击【优模型】进行管理

点击右上角的【新增】按钮，按照提醒填写信息

支持管理员直接调用创建设备的后台接口进行创建
创建设备可以选择创建单台设备或批量创建多台设备

已经完成对应设备的产品创建，且产品优模型等都已经创建完成，产品已发布

进入菜单【设备管理】管理页面：

点击右上角【新建设备】的按钮，在弹窗中按照提示填写设备的基本信息，然后点击“完成”进行设备创建。

创建成功，会生成设备的设备ID。设备ID ：指设备的ID，和设备密钥成对出现。该参数很重要，在设备认证时会用到，因此需要您保管好并且不能泄露。设备三元组之一。

进入菜单【设备-新增管理】管理页面：

点击右上角【批量新建】的按钮，在弹窗中按照提示填写设备的基本信息，然后点击“完成”进行设备创建。

点击设备列表详情，可以查询到本次批量创建设备的记录。

点击详情右侧的【下载设备证书】的按钮，可以下载该批次下的所有设备的三元组，可用于烧录到设备中。

单款产品最多可以添加 50000 台设备。
批量创建设备，每次最多可以创建 1000 台设备。

方便以对设备进行分组管理
单台设备可进入到多个分组

已经完成设备创建

进入菜单【分组管理】管理页面：

在此页面会展示当前分组信息，分组数量等，并且可以针对分组进行删除，删除分组不会造成设备丢失。

点击右上角【新建分组】的按钮，在弹窗中按照提示填写设备的基本信息，然后点击“完成”进行设备创建。

创建成功，会生成分组ID。

进入操作菜单【分组管理】的管理菜单：

可针对分组名称等信息进行编辑，及对分组内设备进行管理。

点击右上角添加设备，即可将未分组设备添加到分组内。

理论上单台设备应关联一个分组，特殊情况下可在添加分组页面，通过分组筛选查找其他已添加分组的设备进行关联。

单一分组建议添加50000 台设备以内。

目前支持的操作系统：

Centos6
Centos7
Ubuntu 16.04
Ubuntu 18.04

产品部署建议 Linux 服务器，不推荐 Windows 服务器。

java: 1.8.x
mongodb：>=4.0，mongodb必须为副本集类型

1、通过此链接下载安装包

2、mongoDB创建iot_privitization库执行语句：

db.createCollection("deviceEntity");
db.createCollection("productEntity");
db.createCollection("deviceBatchEntity");
db.createCollection("deviceEventHistory");
db.createCollection("devicePropertyHistory");
db.createCollection("deviceServiceHistory");
db.createCollection("groupEntity");
db.createCollection("modelEventEntity");
db.createCollection("modelProfileEntity");
db.createCollection("modelPropertyEntity");
db.createCollection("modelServiceEntity");
db.createCollection("mqtt_acl");
db.createCollection("mqtt_user");
db.createCollection("productEntity");
db.createCollection("umoduleDataValidateEntity");

3、解压程序包

$ unzip iot_cloud_privatization-v1.00.00.00.zip

1、修改/etc/plugins/emqx_auth_mongo.conf配置，配置mongodb地址

auth.mongo.rs_set_name  : 配置副本集名称
auth.mongo.server :mongodb server 地址
auth.mongo.login : 登录用户名
auth.mongo.password : 登录密码
auth.mongo.auth_source: mongoDB数据库的名称

2、启动 EMQ X Broker，注意启动前需要添加‘emqx’文件执行权限

$ ./bin/emqx start
emqx 4.0.0 is started successfully!

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

$ ./bin/emqx stop
ok

1、检查是否安装java环境,需使用1.8.x版本

$ java -version
java version "1.8.0_251"
Java(TM) SE Runtime Environment (build 1.8.0_251-b08)
Java HotSpot(TM) 64-Bit Server VM (build 25.251-b08, mixed mode)

2、修改/etc/application.yml配置，配置mongodb地址

spring:
  data:
    mongodb:
      uri: mongodb://127.0.01:27017/iot_privitization    #mongodb连接url地址
      authentication-database: iot_privitization         #鉴权数据库

3、启动iotserver服务启动服务：

$ cd bin/
$ sh server.sh start

查看服务状态：

$ sh server.sh status
../lib/application.jar is running. Pid is 16764

关闭服务

$ sh server.sh stop

地址：localhost:20007 用户名：admin 密码：Ut123456

进入菜单【IoT 硬件云】 - 【产品】管理页面，可以看到开发者创建的所有产品记录：

在产品列表中找到需要查看的产品记录，点击进入详情：

本系统默认开通订阅服务，系统提供api供合作伙伴订阅

教程请参考：创建产品

入口：【IoT 硬件云】 - 【产品】 - 【产品详情】 -可编辑信息都有提示，点击【编辑】按钮。目前产品支持编辑的字段有：

产品名称
产品标签
备注

在产品详情页面，选择【优模型】- 【新增】优模型，可【下载优模型】和【导入优模型】。

优模型指将物理空间中的实体数字化，并在云端构建该实体的数据模型。在物联网平台中，定义优模型即定义产品功能。完成功能定义后，系统将自动生成该产品的优模型。优模型描述产品是什么、能做什么、可以对外提供哪些服务。

优模型是一个JSON格式的文件。它是物理空间中的实体，如传感器、车载装置、楼宇、工厂等在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了这三个维度，即完成了产品功能的定义。

优模型将产品功能类型分为三类：属性、服务和事件。定义了这三类功能，即完成了优模型的定义。

功能类型	说明
属性（Property）	一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持GET和SET请求方式。应用系统可发起对属性的读取和设置请求。
服务（Service）	设备可被外部调用的能力或方法，可设置输入参数和输出参数。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务。
事件（Event）	设备运行时的事件。事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。

{
    "profile": {
        "id": "5edde65cb8d38253b8bc7670",
        "category": "ut-device",
        "identifier": "5edde65cb8d38253b8bc766f",
        "version": "1.0"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符（产品下唯一）",
            "name": "属性名称",
            "accessMode": "属性读写类型：只读（r）或读写（rw）。",
            "dataType": {
                "type": "属性类型: int（原生）、、double（原生）、string（原生）、bool（0或1的int类型）、struct（结构体类型，可包含前面4种类型）、array（数组类型，支持int/double/bool/string）",
                "specs": {
                    "min": "参数最小值（int、double类型特有）",
                    "max": "参数最大值（int、double类型特有）",
                    "unit": "属性单位",
                    "unitName": "单位名称",
                    "size": "数组大小，默认最大128（数组特有）。",
                    "step": "步长，字符串类型。",

直连设备管理可添加直连设备，用于直连设备的增删等操作，也可以批量添加直连设备

** 批量创建设备** 批量新增设备，可快速新建多设备，可针对设备进行三元组下载，方便用户快速实现设备入网。

单款产品最多可以添加 50000 台设备。
批量创建设备，每次最多可以创建 1000 台设备。

方便以对设备进行分组管理
单台设备可进入到多个分组

提供设备分组管理，便于适配用户使用场景

将设备与分组进行关联

可针对分组名称等信息进行编辑，及对分组内设备进行管理。

点击右上角添加设备，即可将未分组设备添加到分组内。

特别注意：理论上单台设备应关联一个分组，特殊情况下可在添加分组页面，通过分组筛选查找其他已添加分组的设备进行关联。

单一分组建议添加50000 台设备以内。

C语言SDK适用于使用C语言开发业务处理逻辑的设备，由于C语言运行速度快、需要的运行内存较少，目前大多数的IoT设备使用C语言进行产品开发。

当前最新版本：v1.00.00.00 下载

版本	修改内容	修改人	审核人	日期
v1.00.00.00	新建文档	吴伟		2020/05/29

SDK提供了API供设备厂商调用，用于实现与硬件云（私网版）IoT平台通信以及一些其它的辅助功能。

另外，C语言版本的SDK被设计为可以在不同的操作系统上运行，例如Linux、FreeRTOS、Windows，因此SDK需要OS或者硬件支持的操作被定义为一些HAL函数，设备厂商在使用SDK开发产品时需要将这些HAL函数进行实现。产品的业务逻辑、SDK、HAL的关系如下图所示。

其中产品业务逻辑和HAL需要设备厂商实现，SDK的目录wrappers下提供了针对Linux的部分HAL参考实现供参考。

默认关闭SSL/TLS，直接在源代码修改eng/infra/infra_config.h修改打开。
默认支持编译环境有自带标准头文件, 默认打开PLATFORM_HAS_STDINT。
默认支持目标系统上支持 malloc 和 free 这样的动态内存管理能力, 默认打开PLATFORM_HAS_DYNMEM。

设备的硬件由一个MCU加上一个通信模组构成，模组上需支持TCP/IP协议，MCU集成SDK通过通信模组实现MQTT协议与云端通信。

功能模块	功能点
设备连云	MQTT连云，设备可通过MQTT与硬件云（私网版）平台通信
设备身份认证	一机一密
物模型	使用属性、服务、事件对设备进行描述以及实现，包括： 1. 属性上报、设置 2. 服务调用 3. 事件上报
时间获取	从硬件云（私网版）平台获取当前最新的时间

功能模块功能点设备连云MQTT连云，设备可通过MQTT与硬件云（私网版）平台通信设备身份认证一机一密物模型使用属性、服务、事件对设备进行描述以及实现，包括： 1. 属性上报、设置 2. 服务调用 3. 事件上报时间获取从硬件云（私网版）平台获取当前最新的时间

解压SDK包eng源代码目录、examples案例目录和Makefile编译文件。

如果设备商的开发环境使用makefile编译代码，可以将SDK代码加入其编译环境进行编译。如果设备商使用KEIL/IAR这样的开发工具，可以将SDK的代码文件加入到IDE的工程中进行编译。

SDK被设计为可以在不同的操作系统上运行，或者甚至在不支持操作系统的MCU上运行，因此与系统相关的操作被定义成一些HAL函数, 需要客户进行实现。另外，由于不同的通信模组指令集不一样, 所以与通信模组上TCP相关的操作也被定义成HAL函数需要设备开发者进行实现。

SDK需要对接的HAL函数位于文件output/eng/wrappers/下的wrapper_*.c文件中。

具体的HAL函数详情见API中的HAL列表。

目前设备支持MQTT连云, 可参考examples文件夹下的linkkit_example_solo.c文件。设备厂商可以将该文件复制到产品工程中, 对其进行修改后使用。