一、产品介绍
平台介绍
平台简介
- 硬件云(私部署)平台产品说明 为硬件设备提供安全可靠的连接通信能力,可支撑海量设备接入,支持数据在私有云环境下流转;为其他关联业务提供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平台,并能正常上报数据和接收命令。 |
设备接入
关键操作 | 说明 |
注册设备 | 设备在接入前,需要在硬件云平台为设备开户,将设备接入需要的信息提前录入到硬件云平台,也就是得闲生成设备的三元组。 |
接入设备 | 设备通电,被用户激活后,设备能够正常接入到硬件云平台。 |
应用后台接入
关键操作 | 说明 |
调测应用后台 | 应用接入硬件云平台后,查看应用服务器是否能够远程控制设备。 |
步骤1:创建产品
创建产品的方式:
进入系统后根据提示进行产品创建
创建产品操作步骤:
- 进入菜单 【IoT 硬件云】 - 【产品】管理页面:
- 点击右上角【创建产品】的按钮,在弹窗中按照提示填写产品的基本信息,然后点击“完成”进行产品创建。
- 创建成功,会生成产品的唯一标识符产品ID。
注意事项:
- 每个开发者账号最多创建 100 款产品。
- 每款产品的 ProductKey 都是唯一的,由系统自动生成的,如果该的产品被删除了,要重新创建,那么原来已经烧录了三元组的设备要重新烧录,请谨慎删除产品。
步骤2:产品优模型定义
如何定义优模型
优模型,将实际产品抽象成由属性、服务、事件所组成的数据模型,便于云端管理和数据交互。产品创建完成后,开发者可以为它定义优模型,产品下的设备将自动继承优模型内容。
为了方便开发者定义产品的物模型,以下用取餐柜作为一个示例(仅提供参考),协助理解属性、服务、事件的定义:
属性:
服务:
事件:
开发优模型的操作步骤
- 点击已经创建的产品,进入产品的详情页面,点击【优模型】进行管理
- 点击右上角的【新增】按钮,按照提醒填写信息
步骤3:创建设备
创建设备的方式:
- 支持管理员直接调用创建设备的后台接口进行创建
- 创建设备可以选择创建单台设备或批量创建多台设备
前提条件:
- 已经完成对应设备的产品创建,且产品优模型等都已经创建完成,产品已发布
操作步骤:
新增单台设备
- 进入菜单 【设备管理】管理页面:
- 点击右上角【新建设备】的按钮,在弹窗中按照提示填写设备的基本信息,然后点击“完成”进行设备创建。
- 创建成功,会生成设备的 设备ID。设备ID :指设备的ID,和设备密钥成对出现。该参数很重要,在设备认证时会用到,因此需要您保管好并且不能泄露。设备三元组之一。
批量创建设备
- 进入菜单 【设备-新增管理】管理页面:
- 点击右上角【批量新建】的按钮,在弹窗中按照提示填写设备的基本信息,然后点击“完成”进行设备创建。
- 点击设备列表详情,可以查询到本次批量创建设备的记录。
- 点击详情右侧的【下载设备证书】的按钮,可以下载该批次下的所有设备的三元组,可用于烧录到设备中。
注意事项:
- 单款产品最多可以添加 50000 台设备。
- 批量创建设备,每次最多可以创建 1000 台设备。
步骤4:分组管理
创建分组的目的:
- 方便以对设备进行分组管理
- 单台设备可进入到多个分组
前提条件:
- 已经完成设备创建
操作步骤:
分组管理
- 进入菜单 【分组管理】管理页面:
在此页面会展示当前分组信息,分组数量等,并且可以针对分组进行删除,删除分组不会造成设备丢失。
- 点击右上角【新建分组】的按钮,在弹窗中按照提示填写设备的基本信息,然后点击“完成”进行设备创建。
- 创建成功,会生成分组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
启动emqx服务器
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
启动IOT-SERVER服务
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
访问Dashboard
地址:localhost:20007 用户名:admin 密码:Ut123456
直连设备产品管理
产品列表
进入菜单 【IoT 硬件云】 - 【产品】管理页面,可以看到开发者创建的所有产品记录:
产品详情
在产品列表中找到需要查看的产品记录,点击进入详情:
topic订阅
本系统默认开通订阅服务,系统提供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 台设备以内。
四、开发指南
设备端开发指引
SDK版本
C语言SDK适用于使用C语言开发业务处理逻辑的设备,由于C语言运行速度快、需要的运行内存较少,目前大多数的IoT设备使用C语言进行产品开发。
SDK v1.00.00.00
当前最新版本:v1.00.00.00 下载
版本更新记录
版本 | 修改内容 | 修改人 | 审核人 | 日期 |
v1.00.00.00 | 新建文档 | 吴伟 | 2020/05/29 |
SDK使用说明
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。
SDK接入概述
SDK接入环境
设备的硬件由一个MCU加上一个通信模组构成,模组上需支持TCP/IP协议,MCU集成SDK通过通信模组实现MQTT协议与云端通信。
SDK功能列表
功能模块 | 功能点 |
设备连云 | MQTT连云,设备可通过MQTT与硬件云(私网版)平台通信 |
设备身份认证 | 一机一密 |
物模型 | 使用属性、服务、事件对设备进行描述以及实现,包括: 1. 属性上报、设置 2. 服务调用 3. 事件上报 |
时间获取 | 从硬件云(私网版)平台获取当前最新的时间 |
功能模块功能点设备连云MQTT连云,设备可通过MQTT与硬件云(私网版)平台通信设备身份认证一机一密物模型使用属性、服务、事件对设备进行描述以及实现,包括: 1. 属性上报、设置 2. 服务调用 3. 事件上报时间获取从硬件云(私网版)平台获取当前最新的时间
SDK接入指引
SDK接入流程
解压SDK包
解压SDK包eng源代码目录、examples案例目录和Makefile编译文件。
编译环境
如果设备商的开发环境使用makefile编译代码,可以将SDK代码加入其编译环境进行编译。 如果设备商使用KEIL/IAR这样的开发工具,可以将SDK的代码文件加入到IDE的工程中进行编译。
实现HAL函数
SDK被设计为可以在不同的操作系统上运行,或者甚至在不支持操作系统的MCU上运行,因此与系统相关的操作被定义成一些HAL函数, 需要客户进行实现。另外,由于不同的通信模组指令集不一样, 所以与通信模组上TCP相关的操作也被定义成HAL函数需要设备开发者进行实现。
SDK需要对接的HAL函数位于文件output/eng/wrappers/下的wrapper_*.c文件中。
具体的HAL函数详情见API中的HAL列表。
参照example实现产品功能
目前设备支持MQTT连云, 可参考examples文件夹下的linkkit_example_solo.c文件。 设备厂商可以将该文件复制到产品工程中, 对其进行修改后使用。
该example将连接设备到硬件云,需更改设备连接服务器参数配置和三元组信息。