# 设备集成设备端SDK接入
华为云设备接入云服务（IoTDA）是提供海量设备的接入和管理能力的物联网平台，将物理设备连接到云，支撑设备数据采集上云和云端下发命令给设备进行远程控制。IoTDA配合华为云其他产品，可以帮助您快速构筑物联网解决方案。
接下来，将以Java SDK为例，体验如何使用IoT Device SDK进行代码场景适配、并将该SDK集成入IoT设备实现设备快速接入IoTDA平台。本章节以一个自定义燃气表的产品模型为例，介绍如何适配SDK代码以实现数据（消息、属性）上报，上报燃气表数据；下发命令，对燃气表进行远程配置和控制，最后将适配好的代码集成入设备中。
设备侧SDK不绑定某个特定的产品模型，本章节使用自定义燃气表仅为举例，用户可根据自己实际情况适配代码。
#### 设备侧SDK全表
表1设备侧SDK全表
| 资源包名 | 描述 | 下载路径 |
|:---|:---|:---|
| 设备侧 IoT Device Java SDK | 设备可以通过集成IoT Device SDK(Java)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考 [设备侧 IoT Device Java SDK使用指南](https://support.huaweicloud.com/sdkreference-iothub/iot_02_0089.html)。 | [设备侧 IoT Device Java SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-java) |
| 设备侧 IoT Device C for Linux/Windows SDK | 设备可以通过集成IoT Device SDK(C)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考 [设备侧 IoT Device C for Linux/Windows SDK使用指南](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-c)。 | [设备侧 IoT Device C for Linux/Windows SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-c) |
| 设备侧 IoT Device C# SDK | 设备可以通过集成IoT Device SDK(C#)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考 [设备侧 IoT Device C# SDK使用指南](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-cSharp)。 | [设备侧 IoT Device C# SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-cSharp) |
| 设备侧 IoT Device Android SDK | 设备可以通过集成IoT Device SDK(Android)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考[设备侧 IoT Device Android SDK使用指南](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-Android)。 | [设备侧 IoT Device Android SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-Android) |
| 设备侧 IoT Device Go SDK(社区版) | 设备可以通过集成IoT Device SDK(Go)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考[设备侧 IoT Device Go SDK(社区版)使用指南](https://github.com/ctlove0523/huaweicloud-iot-device-sdk-go)。 | [设备侧 IoT Device Go SDK(社区版)](https://github.com/ctlove0523/huaweicloud-iot-device-sdk-go) |
| 设备侧 IoT Device Python SDK | 设备可以通过集成IoT Device SDK(Python)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考[设备侧 IoT Device Python SDK使用指南](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-python)。 | [设备侧 IoT Device Python SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-python) |
| 设备侧 IoT Device C for Linux/Windows SDK Tiny | 设备可以通过集成IoT Device SDK Tiny (C)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考[设备侧 IoT Device C for Linux/Windows SDK Tiny使用指南](https://github.com/LiteOS/LiteOS_Lab) | [设备侧 IoT Device C for Linux/Windows SDK Tiny](https://github.com/LiteOS/LiteOS_Lab) |
| 设备侧 IoT Device Arkts(OpenHarmony) SDK | 设备可以通过集成IoT Device SDK (ArkTS)接入物联网平台, Demo提供了调用SDK接口的样例代码。使用指导请参考[设备侧 IoT Device Arkts(OpenHarmony) SDK使用指南](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-arkts/blob/main/huaweicloud_iot_device_library/README.md) | [设备侧 IoT Device Arkts(OpenHarmony) SDK](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-arkts/tree/main) |
表2SDK主要功能矩阵
| 主要功能 | C | Java | C# | Android | GO | python | C Tiny | ArkTS |
|:---|:--|:---|:---|:---|:---|:---|:---|:---|
| 属性上报 | √ | √ | √ | √ | √ | √ | √ | √ |
| 消息上报、下发 | √ | √ | √ | √ | √ | √ | √ | √ |
| 事件上报、下发 | √ | √ | √ | √ | √ | √ | √ | × |
| 命令下发、响应 | √ | √ | √ | √ | √ | √ | √ | √ |
| 设备影子 | √ | √ | √ | √ | √ | √ | √ | √ |
| OTA升级 | √ | √ | √ | √ | √ | √ | √ | × |
| bootstrap | √ | √ | √ | √ | √ | √ | √ | × |
| 时间同步 | √ | √ | √ | √ | √ | √ | √ | × |
| 网关与子设备管理 | √ | √ | √ | √ | √ | √ | √ | × |
| 端侧规则引擎 | √ | × | √ | × | × | × | √ | × |
| 远程SSH | √ | × | √ | × | × | × | × | × |
| 异常检测 | √ | × | √ | × | × | × | × | × |
| 端云安全通信（软总线） | √ | × | √ | × | × | × | × | × |
| M2M功能 | √ | × | √ | × | × | × | × | × |
| 泛协议接入 | √ | √ | √ | √ | × | √ | × | × |
#### 前提条件
- 开发环境要求：已安装java的集成环境（IntelliJ IDEA），并配置好Maven等相关环境。
- 本示例使用的是设备侧的MQTTS协议。
- 已注册华为云官方账号并完成实名制认证。
- 已开通设备接入服务。未开通则访问[设备接入服务](https://www.huaweicloud.com/product/iothub.html)，单击"立即使用"后开通该服务。
#### 业务流程
使用IoT Device SDK(Java)将设备接入华为云IoTDA平台，进行数据上报、命令下发等业务的体验。
1. [创建产品]。创建一个MQTT协议的产品。
2. [开发产品模型]。通过定义产品模型，在物联网平台构建一款燃气表设备，支持上报燃气表读数、远程给燃气表下发配置和命令。
3. [注册设备]。注册一个MQTT协议的设备。
4. [使用Java SDK接入华为云]。下载SDK、适配代码并使用Java SDK激活在物联网平台上注册的设备。
5. [消息上报]。适配代码、使用Java SDK向物联网平台上报消息。
6. [属性上报]。适配代码、使用Java SDK向物联网平台设备属性数据。
7. [命令下发]。适配代码、在管理控制台下发命令，远程设置设备属性。
8. [设备集成Java SDK并运行]。将适配好的SDK打包成可运行文件，导入IoT设备并运行，完成设备连接IoTDA平台。
#### 创建产品
1. 访问[设备接入服务](https://www.huaweicloud.com/product/iothub.html)，单击"管理控制台"进入设备接入控制台，选择您的实例，单击实例卡片进入。单击左侧导航栏"产品"，单击页面左侧的"创建产品"。
图1产品-创建产品
2. 建一个协议类型为MQTT协议、自定义设备类型为"自定义燃气表"的产品，参考下表及页面提示填写参数后，单击"确定"。
表3创建产品参数
| 所属资源空间 | 选择默认资源空间 |
|---|---|
| 产品名称 | 自定义，如"燃气表模型" |
| 协议类型 | 选择"MQTT" |
| 数据格式 | 选择"JSON" |
| 设备类型选择 | 选择"自定义类型" |
| 设备类型 | 自定义，如"自定义燃气表模型" |
图2创建产品-MQTT
#### 开发产品模型
1. 找到新增的产品，单击产品进入产品界面。
2. 在产品详情"基本信息"页面，单击"自定义模型"，配置产品的服务。
图3自定义模型-MQTT
3. 新增服务类型"GasMeter"。单击"自定义模型"后，会弹出"添加服务"页面，根据页面提示填写"服务ID"、"服务类型"和"服务描述"，单击"确定"。
图4添加服务-GasMeter
4. 新增属性物模型。单击"GasMeter"服务列表中的"新增属性"，按照下图填写相关信息后，单击"确定"。
图5新增属性-flow
5. 新增命令模型。
1. 单击"GasMeter"服务列表中的"新增命令"，设置命令名称为"TOGGLE"。
图6新增命令-TOGGLE
2. 在"新增命令"页面，单击"新增下发参数"，按照下图填写相关信息后，单击"确定"。
图7新增命令-toggle
6. 上述步骤完成后，可见物模型如下图所示：
图8物模型-燃气表模型
#### 注册设备
1. 在设备接入控制台页面，选择您的实例，选择左侧导航栏"设备 \> 所有设备"，单击"注册设备"。
图9所有设备-注册设备
2. 根据页面提示信息填写参数，然后单击"确定"。
| 参数名称 | 说明 |
|:---|:---|
| 所属资源空间 | 确保和所属产品归属在同一个资源空间。 |
| 所属产品 | 选择对应产品。 |
| 设备标识码 | 即nodeID，设备唯一物理标识。设备标识码长度为4至64个字符，只允许字母、数字、下划线（_）、连接符（-）的组合。可自定义由英文字母和数字组成。 |
| 设备名称 | 即device_name，可自定义。 |
| 设备认证类型 | 选择"密钥"。 |
| 密钥 | 此处如不填写，物联网平台会自动生成。 |
图10单设备注册-MQTT
3. 成功注册设备后，平台会自动生成设备ID和密钥，请妥善保管好设备ID（deviceId）和密钥（deviceSecret），用于设备接入。
图11设备-注册设备成功
#### 使用Java SDK接入华为云
接下来将使用IntelliJ IDEA（以下截图为IntelliJ IDEA 2023社区版）进行代码编写及调试。请先确认IDEA环境完好，Maven可用。Java SDK使用说明及接口：[README.md](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-java/blob/master/README.md)。
推荐用户首先在电脑上完成SDK代码适配和设备激活，再将修改好的代码导入设备中完成集成。
1. 新建项目。打开IntelliJ IDEA，单击"New Project"，在弹出的界面填写项目名及新建项目地址，语言选择"java"，构建系统选择"Maven"，单击"Create"。
图12创建java项目
2. 添加Mvn引用。创建成功后，可在项目中看到自动生成了pom.xml及Main.java文件。打开pom.xml文件，添加Java SDK的Mvn引用。
```
com.huaweicloud
iot-device-sdk-java
LATEST
```
图13添加Java SDK Mvn引用
3. 编写引用代码，实现设备建链。
1. 打开Main.java文件，将下面代码复制到Main.java文件中。
```
import com.huaweicloud.sdk.iot.device.IoTDevice;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
public class Main {
private static final String IOT_ROOT_CA_RES_PATH = "ca.jks";
private static final String IOT_ROOT_CA_TMP_PATH = "huaweicloud-iotda-tmp-" + IOT_ROOT_CA_RES_PATH;
public static void main(String[] args) throws InterruptedException, IOException {
// 加载iot平台的ca证书，进行服务端校验
File tmpCAFile = new File(IOT_ROOT_CA_TMP_PATH);
try (InputStream resource = Main.class.getClassLoader().getResourceAsStream(IOT_ROOT_CA_RES_PATH)) {
Files.copy(resource, tmpCAFile.toPath(), REPLACE_EXISTING);
}
// 创建设备并初始化. 用户请替换为自己的接入地址。
IoTDevice device = new IoTDevice("ssl://xxx.st1.iotda-device.cn-north-4.myhuaweicloud.com:8883",
"5e06bfee334dd4f33759f5b3_demo", "mysecret", tmpCAFile);
if (device.init() != 0) {
return;
}
}
}
```
2. 添加证书文件。[获取设备侧CA证书](https://support.huaweicloud.com/devg-iothub/iot_02_1004.html#section3)，请根据您的局点获取CA证书，并将证书名改为ca.jks，放到项目resources目录下。
图14获取设备侧CA文件
图15添加CA文件到SDK中
3. 修改接入信息。将设备接入地址、设备ID、设备密钥，修改为[注册设备]的设备信息。
图16修改设备连接参数
图17总览-获取接入信息
- 选择设备接入的MQTTS协议接入地址，复制到代码中。若是想使用MQTT协议，可将"ssl://xxx.st1.iotda-device.cn-north-4.myhuaweicloud.com:8883"修改为："tcp://xxx.st1.iotda-device.cn-north-4.myhuaweicloud.com:1883"
- 设备ID与设备密钥在创建设备时会弹出是否保存界面，若是单击了保存，会以文件的形式保存到电脑中。
4. 编译及运行。单击IDEA中的运行按钮，即可在平台看到设备为在线状态。
图18IDEA运行代码
图19设备在线
SDK默认具有自动重建链的功能，当设备由于网络等原因断链时，会自动重新连接。
#### 消息上报
在[使用Java SDK接入华为云]的基础上，开发消息上报功能，SDK接口可见：[消息上报、下发](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-java/blob/master/README.md#33--消息上报下发)。
1. 将下列代码复制到新建项目的Main.java文件中，请复制到device.init()设备建链成功后。
```
// pubBody为要上报的消息，发送时会被编辑为标准上报数据格式
// reportDeviceMessage方法默认上报的topic为$oc/devices/{device_id}/sys/messages/up
String pubBody = "hello";
device.getClient().reportDeviceMessage(new DeviceMessage(pubBody), new ActionListener() {
@Override
public void onSuccess(Object context) {
System.out.println("reportDeviceMessage ok");
}
@Override
public void onFailure(Object context, Throwable var2) {
System.out.println("reportDeviceMessage fail: " + var2);
}
});
```
图20消息上报-IDEA
2. 开启设备消息跟踪，查看消息记录。在华为云管理控制台找到对应设备，进入"设备详情"，单击"消息跟踪 \> 启动消息跟踪"，再次运行代码，即可看到上报消息。
图21设备列表-详情
图22消息跟踪-查看device_sdk_java消息跟踪
#### 属性上报
在[使用Java SDK接入华为云]的基础上，开发属性上报功能，SDK接口可见：[属性上报](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-java/blob/master/README.md#34-属性上报设置查询)。
1. 将下列代码复制到Main.java中，请复制到device.init()设备建链成功后。
```
// 属性上报
Map json = new HashMap<>();
Random rand = new SecureRandom();
// 按照物模型设置属性
json.put("flow", rand.nextFloat() * 100.0f);
ServiceProperty serviceProperty = new ServiceProperty();
serviceProperty.setProperties(json);
serviceProperty.setServiceId("GasMeter"); // serviceId要和物模型一致
device.getClient().reportProperties(Arrays.asList(serviceProperty), new ActionListener() {
@Override
public void onSuccess(Object context) {
System.out.println("pubMessage success");
}
@Override
public void onFailure(Object context, Throwable var2) {
System.out.println("reportProperties failed" + var2.toString());
}
});
```
图23属性上报-IDEA
样例代码为燃气表产品物模型的属性设置。用户可以根据自己实际场景自行进行代码适配。
2. 在平台查看属性上报值。在华为云控制台找到对应设备，进入"设备详情"，单击"设备信息"，再次运行代码，即可看到属性上报值。
图24设备列表-详情
图25查看上报数据-flow
#### 命令下发
在[使用Java SDK接入华为云]的基础上，开发下发功能，SDK接口可见：[命令下发](https://github.com/huaweicloud/huaweicloud-iot-device-sdk-java/blob/master/README.md#35--命令下发)。
1. 将下列代码复制到Main.java文件中，请复制到device.init()设备建链前。
```
// 设置监听器接收下行
device.getClient().setCommandListener(new CommandListener() {
@Override
public void onCommand(String requestId, String serviceId, String commandName, Map paras) {
System.out.println("onCommand, serviceId = " + serviceId);
System.out.println("onCommand , name = " + commandName);
System.out.println("onCommand, paras = " + paras.toString());
// 用户可以在该处进行处理命令
// 发送命令响应
device.getClient().respondCommand(requestId, new CommandRsp(0));
}
});
```
图26命令下发-IDEA
2. 在平台进行命令下发。运行SDK代码，在华为云控制台找到对应设备，进入"设备详情"，单击"云端下发 \> 命令下发 \> 命令下发"，单击"确定"，即可在IDEA控制台中收到下发值。
图27设备列表-详情
图28命令下发-TOGGLE
图29IDEA命令下发结构查看
#### 设备集成Java SDK并运行
华为云IoT提供的设备侧SDK可以被快速集成在用户的IoT设备中。这里以使用Linux系统的IoT设备和Java SDK为例，介绍如何将上文调试好的SDK集成进设备中，实现设备快速连接IoTDA平台。Java SDK可以通过IDEA生成jar包，传输到Linux设备中运行。
**前提条件**
设备为Linux系统并已安装jdk。
**运行步骤**
1. 修改根目录下的pom.xml文件：复制以下配置到pom.xml文件中。
```
org.apache.maven.plugins
maven-assembly-plugin
package
single
org.example.Main
jar-with-dependencies
false
```
图30IDEA-添加package参数
2. 在IDEA中打开Maven，单击package，即可在目录下生成jar包。
图31IDEA-生成jar包
3. 把jar包复制到Linux设备中，输入"java -jar test-javaSdk-1.0-SNAPSHOT"，即可看到代码运行成功，设备成功连接到IoTDA平台。
图32在Linux中运行jar包
若是显示没有java命令，可输入"java -version"查看是否安装了jdk及jdk安装版本。