PDF《智能家居 HiLink MCU SDK》

智能家居 HiLink MCU SDK 集成开发调测指南 文档版本

02 发布日期 2019-03-26 华为技术有限公司 华为专有和保密信息 版权所有 ? 华为技术有限公司 ii 版权所有 ? 华为技术有限公司 2019.

保留一切权利. 非经本公司书面许可,任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部,并不 得以任何形式传播. 商标声明 和其他华为商标均为华为技术有限公司的商标. 本文档提及的其他所有商标或注册商标,由各自的所有人拥有. 注意 您购买的产品、服务或特性等应受华为公司商业合同和条款的约束,本文档中描述的全部或 部分产品、服务或特性可能不在您的购买或使用范围之内.除非合同另有约定,华为公司对 本文档内容不做任何明示或默示的声明或保证. 由于产品版本升级或其他原因,本文档内容会不定期进行更新.除非另有约定,本文档仅作 为使用指导,本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保. 华为技术有限公司 地址: 深圳市龙岗区坂田华为总部办公楼 邮编:518129

网址: http://www.huawei.com 客户服务

邮箱: [email protected] 华为专有和保密信息 版权所有 ? 华为技术有限公司 iii 名词解释 名词 解释 MCU 设备电控板控制芯片,用运行设备业务相关的程序. MCU SDK 华为提供的电控板程序,已实现电控板与 WiFi 模组的通信交互.开发者 集成本 SDK 到电控板程序中,可以快速实现电控板与 WiFi 模组的对 接. Profile 开发者定义的设备功能集合. 华为专有和保密信息 版权所有 ? 华为技术有限公司 iv 目录1. 概述.1 2. MCU SDK 代码结构简介.2 2.1. 功能框图说明

2 2.2. 源代码简介

2 3. MCU SDK 集成步骤.4 3.1. 第一步:获取集成开发包

4 3.2. 第二步:主框架集成

4 3.3. 第三步:HiLink 功能集成.4 3.3.1. 串口数据接收

5 3.3.2. 模组重启与重置(可选)5 3.3.3. 获取模组联网状态(可选)5 3.3.4. 获取模组 WiFi 信息(可选)5 3.3.5. 主动数据上报

5 3.4. 第四步:设备功能实现

6 3.4.1. 设备硬件相关接口实现

6 3.4.2. 服务属性控制接口实现

7 3.4.3. 设备升级接口实现(可选)7 3.4.4. Profile 版本更新(可选)9 4. MCU SDK 功能验证.10 4.1. 说明

10 4.2. APP 调试环境设置

10 4.3. 搜索添加待测设备

13 4.4. 验证设备控制功能

19 概述 华为专有和保密信息 版权所有 ? 华为技术有限公司

1 1. 概述 本文档用于指导使用 HiLink WiFi 模块的智能家居开发者在智能设备中集成 HiLink MCU SDK、实现HiLink 设备的设备信息注册、远程控制、设备状态上报和 OTA 升级等功能.通过本文档,开发者可 以掌握集成 HiLink MCU SDK 的基本流程及内容. HiLink MCU SDK 开发集成流程如下: 图1-1 HiLink MCU SDK 开发集成流程 MCU SDK 代码结构简介 华为专有和保密信息 版权所有 ? 华为技术有限公司

2 2. MCU SDK 代码结构简介 本章节介绍 HiLink MCU SDK 代码的组成,帮助开发者了解代码和功能的框架. 图2-1 HiLink MCU SDK 系统框架 2.1. 功能框图说明 HiLink MCU SDK 代码主要由两部分组成,见下表. 序号 构成部分 概述

1 HiLink 通信及串口协议部分 实现了 MCU 端与 WiFi 模组间的业务通讯逻辑以及串口通信协 议.此部分开发者不需关注.

2 开发者适配及功能实现部分 包括硬件适配、设备控制功能、设备升级功能(可选)实现. 注:此部分需要开发者修改实现. 2.2. 源代码简介 ? 目录结构组成 HiLink MCU SDK 集成指导书 2MCU SDK 代码结构简介 华为专有和保密信息 版权所有 ? 华为技术有限公司

3 图2-2 HiLink MCU SDK 源代码结构 ? 目录概要说明 序号 目录名 功能概述

1 hilink_mcu_sdk 根目录下是开发者需要适配实现的功能接口.

2 hilink_mcu_sdk/include 此目录存放的是开发者需要调用或实现的接口的声明头文件.

3 hilink_mcu_sdk/system 此目录存放 HiLink 通信和串口协议相关实现及头文件. ? 开发者需要关注的文件详细说明 序号 文件名 功能概述

1 hilink_mcu_sdk/hilink_device.c 需要开发者实现的设备控制相关接口.

2 hilink_mcu_sdk/hilink_mcu.c 需要开发者适配的非设备控制相关接口.

3 hilink_mcu_sdk/hilink_ota.c 需要开发者选择实现的设备升级相关接口.

4 hilink_mcu_sdk/include /hilink_device.h 需要开发者实现的设备控制相关接口声明.

5 hilink_mcu_sdk/include /hilink_mcu.h MCU SDK 入口函数及其他需要开发者调用或实现的非设 备控制接口声明.

6 hilink_mcu_sdk/include /hilink_ota.h 需要开发者选择实现的设备升级接口声明. 智能家居 HiLink MCU SDK 集成开发调测指南 MCU SDK 集成步骤 华为专有和保密信息 版权所有 ? 华为技术有限公司

4 3. MCU SDK 集成步骤 本章节将详细介绍开发者如何集成 HiLink MCU SDK 代码,帮助开发者快速完成集成开发. 3.1. 第一步:获取集成开发包 1) 开发者提供厂商信息、产品功能定义给华为;

2) 华为提供 MCU SDK 集成开发软件包给开发者;

3) 开发者将 MCU SDK 代码目录 hilink_mcu_sdk 添加到工程中,准备集成开发. 3.2. 第二步:主框架集成 1) 开发者根据 HiLinkMcuMain()函数说明在 while 循环中添加合适的延时,函数在 hilink_mcu_main.c 文件中.延时时间参考值为

100 毫秒(ms),请根据实际情况调整. 参考示例: void HiLinkMcuMain(void) { HiLinkDevInit();

while (1) { HiLinkMainProcess();

/* 根据实际情况,在此处添加合适的延时 */ } } 2) 开发者在主程序文件中包含 hilink_mcu.h 头文件. 3) 主程序中调用 HiLinkMcuMain()函数,即可集成 HiLink MCU SDK 主框架流程. 3.3. 第三步:HiLink 功能集成 开发者调用 HiLink MCU SDK 提供的接口完成功能集成,提供给开发者的接口声明在 hilink_mcu.h 头文件中,开发者调用相关接口时需要在文件中包含 hilink_mcu.h 头文件. 智能家居 HiLink MCU SDK 集成开发调测指南 MCU SDK 集成步骤 华为专有和保密信息 版权所有 ? 华为技术有限公司

5 3.3.1. 串口数据接收 开发者在串口接收中断处理函数中调用 HiLinkUartRcvOneByte 函数接收单个字节数据. 示例:假如开发板有如下的串口接收中断处理函数. HAL_StatusTypeDef los_receive_it(int uartidx) //串口接收中断处理函数 { . . . if (huart->

Init.Parity == UART_PARITY_NONE) { data = (huart->

Instance->

RDR &

0xFF);

HiLinkUartRcvOneByte(data);

// 调用接口接收串口数据 } . . . } 3.3.2. 模组重启与重置(可选) 1) 若开发者需要重启 WiFi 模组,可在任何地方调用 HiLinkModuleReboot()函数. 2) 若开发者需要重置 WiFi 模组,可在任何地方调用 HiLinkModuleReset()函数. 3.3.3. 获取模组联网状态(可选) 开发者可以通过调用如下接口获取模组当前的联网状态. ModuleNetStatus HiLinkGetLocalNetStatus(void);

接口返回的模组联网状态值定义如下: typedef enum { NET_NOAP = 0, /* 未获得 AP 信息, 配网中 */ NET_NOTCONN = 1, /* 已获得 AP 信息, 未连接 AP */ NET_CONWIFI = 2, /* 已连接 AP, 未连接云服务器 */ NET_ONLINE = 3, /* 已连接云服务器 */ NET_UNKONWN =

4 /* 未获得 AP 信息, 未配网 */ } ModuleNetStatus;

3.3.4. 获取模组 WiFi 信息(可选) 1) 若开发者需要获取模组的 WiFi 信息,则在注册 Profile 数据完成后,可以调用 HiLinkGetModuleInfo(NULL)函数;

2) 如果设备工厂生产时,需要获取某个固定 WiFi 的信息,可以调用 HiLinkGetModuleInfo( APNAME ),其中 APNAME 是要获取的 WiFi 热点的名字(不能超过

32 字符). 3) 调用该接口获取模组的 WiFi 信息后,需要在 hilink_mcu.c 中实现 HiLinkNotifyModuleInfo 函数,处理返回的模组信息. 3.3.5. 主动数据上报 1) 单个属性值数据上报 智能家居 HiLink MCU SDK 集成开发调测指南 MCU SDK 集成步骤 华为专有和保密信息 版权所有 ? 华为技术有限公司

6 电控板数据更新后,如果需要上报数据,可以直接调用下面的接口进行数据上报. int HiLinkUpdateKeyVal(short svcMapId, short keyMapId, int val, const char* str);

对不同类型的数据上报,函数调用参数的填写有所不同. (1)整型 int 和布尔类型 bool 数据上报,val 为上报数值,str 置为 NULL. HiLinkUpdateKeyVal(svcMapId, keyMapId, val, NULL);

(2)字符串类型数据上报,str 为上报字符串,val 置为 0. HiLinkUpdateKeyVal(svcMapId, keyMapId, 0, xxxxxx );

2) 某个服务下所有属性值数据上报 如果需要一次性上报某个 Service 下所有属性值数据,可以调用下面的接口. int HiLinkUpdateSvcVal(short svcMapId, short keyMapId, int val, const char* str, char rptFlag);

对不同类型的数据上报,函数调用参数的填写有所不同,填写方式与单个属性值上报相同. 上报标记位 rptFlag 的填写 上报某个 Service 下所有属性值需要依次调用 HiLinkUpdateSvcVal 接口将每一个属性的值上报. 其中除最后一个属性上报外,其他属性上报参数 rptFlag 为REPORT_LATER,表示稍后上报(数据只 会保存在电控板上);

最后一个属性上报参数 rptFlag 为REPORT_NOW,表示立即上报(触发 Service 下所有属性同时上报给模组,包括前面稍后上报的属性).示例如下: HiLinkUpdateSvcVal(svcMapId, keyMapId1, value1, NULL, REPORT_LATER);

HiLinkUpdateSvcVal(svcMapId, keyMapId2, value2, NULL, REPORT_LATER);

HiLinkUpdateSvcVal(svcMapId, keyMapId3, value3, NULL, REPORT_NOW);

3.4. 第四步:设备功能实现 开发者需要实现在 hilink_mcu.c、hilink_device.c 和hilink_ota.c 中定义的相关函数. 3.4.1. 设备硬件相关接口实现 hilink_mcu.c 文件具体需要适配的接口见下表. 序号 适配接口 功能概述

1 unsigned long long HiLinkGetSysCurTime(void);

必须实现接口.获取系统当前时间毫秒值(或时钟 tick 值).目前 HiLink 业务逻辑是使用毫秒(ms)为单位进行相关 延时处理的,因此时间单位为毫秒(或时钟 tick 设置为 1000Hz)

2 void HiLinkUartSendOneByte( unsigned char data);

必须实现接口.实现通过 UART 串口阻塞式发送一个字节 智能家居 HiLink MCU SDK 集成开发调测指南 MCU SDK 集成步骤 华为专有和保密信息 版权所有 ? 华为技术有限公司

7 序号 适配接口 功能概述

3 void HiLinkInitProfileValue( void);

必须实现接口.初始化所有服务属性的初始值.根据实际的 硬件获取相关数据,然后给 g_msgTable 中的 value 字段赋 值4void HiLinkNotifyModuleInfo( const char* mac, const char* hardVer, const char* softVer, int rssi, const char* apName);

可选实现接口.如果开发者调用了 HiLinkGetModuleInfo 函数获取 WiFi 模组信息, 则在本函数中处理返回的模组信 息5void HiLinkNotifyErrorInfo( unsigned int errCode);

可选实现接口.如果开发者希望看到 MCU SDK 的错误信息, 可在本函数中实现打印 MCU SDK 发来的错误码

6 int HiLinkDevRemoved(void);

可选实现接口.用户自定义函数,用于实现收到模组侧通知 MCU 设备被云端删除注册的通知时 MCU 的处理逻辑

7 void HiLinkGetDeviceSn( unsigned int len, char* sn);

可选实现接口.设备默认使用 MAC 地址作为 SN 号,如果开 发者需要根据实际情况录入 SN,可以实现本接口将 SN 数据 传给模组.其中 len 为SN 限制的最大长度

39 字节,sn 是录入的 SN 信息. 3.4.2. 服务属性控制接口实现 开发者实现服务特性对应的控制回调函数.根据服务属性值的变化控制实际设备功能以及数据更新的 上报.服务属性控制接口与 g_msgTable 每项服务属性的 AaaBbbCtrlFunc 函数字段对应. hilink_device.c 文件具体需要适配的接口见下表. 序号 适配接口 功能概述

1 int AaaBbbCtrlFunc( int value) 对整型、布尔型、枚举型的属性,控制函数的参数 value 即 属性的值.

2 int AaaBbbCtrlFunc( int strAddr) 对字符串类型的属性,控制函数的参数 strAddr 表示属性字 符串的地址值. 1) 接口名称中 Aaa 表示服务 id,Bbb 表示属性名称. 2) 开发者实现时需要根据服务实际定义的属性类型(功能定义 Profile 文件的 characteristicType 字段),对参数(如value)进行合法性校验. (1) 如果属性是整数类型且定义了取值范围(max、min)或步长(step),需要对取值范围进行校验. (2) 如果属性是枚举类型,需要对合法取值(enumList)进行校验. 3.4.3. 设备升级接口实现(可选) 需要适配实现的设备升级接口有

4 个,开发者可根据设备是否有升级功能的需求,选择适配该部分 接口并实现升级功能.接口定义在文件 hilink_ota.c 中. 进行........