## 数字管家设备接入FA指南

#### 简介

本文档为帮助开发者快速将设备接入到数字管家，完成FA、服务端和设备的通信，实现数字管家对设备的命令控制、日程管理，以及设备对数字管家的主动告警。 

#### 快速上手

![流程](https://images.gitee.com/uploads/images/2021/1029/171429_9242b0b7_2322605.jpeg "画板.jpg")

##### 1. 前提

- IoT平台：完成IoT平台新设备配置，参考 [设备连接IoT云平台指南](../../../dev/docs/iot_huawei/README.md#%E8%AE%BE%E5%A4%87%E8%BF%9E%E6%8E%A5iot%E4%BA%91%E5%B9%B3%E5%8F%B0%E6%8C%87%E5%8D%97)；
- 设备端：完成设备端的开发并定义好profile设备模型，参考 [设备模型定义](../../../profile)；
- 服务端：搭建并配置好了服务端，参考 [服务端README](../../../Server/README.md)；
- **数据库：device_type表中添加好相关产品数据；**

##### 2. 编写设备控制页面

1. 在slice目录下新建 xxxxSlice.java文件，通过 **addActionRoute()** 方法为此AbilitySlice配置一条路由规则，并且在在应用配置文件（config.json）中注册，可[参考AbilitySlice路由配置文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ability-page-concept-0000000000033573)。
   ![路由配置1](https://images.gitee.com/uploads/images/2021/1029/161723_1697536c_2322605.png "image-20211029092102324.png")
   ![路由配置2](https://images.gitee.com/uploads/images/2021/1029/161803_5398e162_2322605.png "image-20211029092300848.png")
2. 在resources->base->layout下新建对应xml布局文件，可参考[HarmonyOS设计原则](https://developer.harmonyos.com/cn/docs/design/des-guides/principle-0000001156667269#ZH-CN_TOPIC_0000001156667269__section1474151718349)，在上述两个文件中编写相应界面代码。

##### 3. 页面逻辑与数据处理

1. slice页面获取deviceId：在onStart中通过调用**intent.getStringParam("deviceId")**，获取设备标识用于对设备进行控制或者获取设备信息。

   ![deviceId](https://images.gitee.com/uploads/images/2021/1029/161839_38efd8f2_2322605.png "image-20211029092723327.png")
2. slice页面获取状态：对于可以主动控制的设备，调用**intent.getBooleanParam(KEY_IS_SET_COMMAND, false)**，用于判断当前状态下是需要执行命令，还是通过 [EventBus](https://gitee.com/openharmony-tpc/EventBus) 将命令数据传出用于日程对设备的编排之中。
   ![设备页状态](https://images.gitee.com/uploads/images/2021/1029/161915_960fc238_2322605.png "image-20211029092947363.png")
3. 编写设备控制命令的获取和解析方法：在CommandUtil中根据具体设备profile定义，来新增获取命令和解析命令的方法，以供设备调用sendCommand来发送命令和在日程中来解析命令。
   ![获取命令](https://images.gitee.com/uploads/images/2021/1029/162015_17b57164_2322605.png "image-20211029142646316.png")
   ![解析命令](https://images.gitee.com/uploads/images/2021/1029/162134_dca2f8b6_2322605.png "image-20211029142655821.png")
4. 配置设备相关信息：在DeviceData类的initData方法中，根据设备productId添加设备图片资源ID、跳转的action参数和日程解析方法，配置完成后设备列表页、日程页面等都能通过该配置进行图片加载、路由跳转和日程解析。
   ![设备信息](https://images.gitee.com/uploads/images/2021/1029/162156_4e2b052f_2322605.png "image-20211029115116255.png")
5. 以上代码逻辑处理和实现可参考LampAbilitySlice.java。

##### 4. 接口对接

​	项目使用的网络请求组件为RetrofitCache，使用方式可参考[RetrofitCache组件](https://gitee.com/archermind-ti/retrofit-cache)，项目中服务端api定义于ApiRx2，通过OKHttpUtilsRx2来实现异步调用。

1. 若使用自己部署的服务端，须做如下修改:
   (1) 将OKHttpUtilsRx2类中SERVER_URL变量修改为自己的服务端api地址;
   (2) 将DeviceStateListener类中RABBITMQ_HOST变量修改为自己的服务端地址;

2. 初始化设备状态：通过调用**getDeviceInfo**接口，传入deviceId和userId来获取，其中UserId在登录时会储存于Preferences轻量级数据存储之中。
   ![设备状态](https://images.gitee.com/uploads/images/2021/1029/162217_fe7e5806_2322605.png "image-20211029143303492.png")

3. 设备控制命令：通过调用**sendCommand**接口，传入deviceId和命令json字符串来对指定设备进行控制。

   ![控制](https://images.gitee.com/uploads/images/2021/1029/162234_30e9c4e0_2322605.png "image-20211029143355870.png")

#### 如何验证

##### 1. 写入NFC数据

根据设备定义好的设备profile模型，使用**应用调测组助手**将tlv格式数据写入NFC，使用方式参考 [设备碰一碰配置指南](../../../dev/docs/NFC_label_definition/README.md#%E4%B8%89nfc%E6%95%B0%E6%8D%AE%E5%86%99%E5%85%A5) NFC数据写入章节。

##### 2. 对设备进行碰一碰配网

将手机靠近NFC标签，可正常拉起数字管家，并开始无感配网。

![无感配网](https://images.gitee.com/uploads/images/2021/1029/162515_e9ad6e9b_2322605.gif "无感配网.gif")

##### 3. 验证设备跳转入口

- 在线设备贴近设备NFC标签碰一碰，可正常跳转至应用；

![碰一碰](https://images.gitee.com/uploads/images/2021/1029/171822_455f1a9a_2322605.gif "1.gif")

- 在首页设备Tab和新增日程页面的设备图标能正确显示设备状态，在线设备点击图标后可跳转设备页；

![跳转](https://images.gitee.com/uploads/images/2021/1029/171900_0516656e_2322605.gif "2.gif")

##### 4. 验证功能

- 新增日程：在输入成员、设备执行动作、执行时间等后，日程页面可看见新增的日程以及需执行的动作，在到达指定时间后所有设备能够执行预设动作，并且相关成员手机会收到系统通知。
  ![新建日程](https://images.gitee.com/uploads/images/2021/1029/162613_917b637d_2322605.gif "建立日程.gif")
- 设备单点控制：进入设备控制页面，执行控制操作设备能有相应动作执行。
  ![控制](https://images.gitee.com/uploads/images/2021/1029/162629_2aab9acd_2322605.gif "控制设备.gif")
- 主动告警：验证设备端能否通过AMQP通知到数字管家，例如智能垃圾桶检测到垃圾桶已满会通过服务端通知到相关用户，并且能触发铃声提醒和系统通知弹框。

![告警](https://images.gitee.com/uploads/images/2021/1029/162644_230f3dd7_2322605.gif "告警.gif")

#### FAQ

[FAQs](FAQs.md)