智能家居 HiLink 单模组芯片 二次开发指导 文档版本 02 发布日期 2019-03-26 华为技术有限公司
版权所有 华为技术有限公司 2019 保留一切权利 非经本公司书面许可, 任何单位和个人不得擅自摘抄 复制本文档内容的部分或全部, 并不 得以任何形式传播 商标声明 和其他华为商标均为华为技术有限公司的商标 本文档提及的其他所有商标或注册商标, 由各自的所有人拥有 注意您购买的产品 服务或特性等应受华为公司商业合同和条款的约束, 本文档中描述的全部或部分产品 服务或特性可能不在您的购买或使用范围之内 除非合同另有约定, 华为公司对本文档内容不做任何明示或默示的声明或保证 由于产品版本升级或其他原因, 本文档内容会不定期进行更新 除非另有约定, 本文档仅作为使用指导, 本文档中的所有陈述 信息和建议不构成任何明示或暗示的担保 华为技术有限公司 地址 : 深圳市龙岗区坂田华为总部办公楼邮编 :518129 网址 : 客户服务邮 箱 : http://www.huawei.com support@huawei.com 2019-3-26 华为保密信息, 未经授权禁止扩散第 2 页, 共 17 页
2019-3-26 华为保密信息, 未经授权禁止扩散第 3 页, 共 17 页
目录 1 概述... 5 2 华为 HiLink 认证模组开发步骤简介... 5 2.1 定义设备 profile... 5 2.2 实现 PIN 码获取接口... 7 2.3 实现 WiFi 模组的 ID 获取接口... 7 2.4 实现 put_char 以及 get_char... 8 2.5 实现 HiLink 状态通知... 9 2.6 timer 和 delay 功能适配... 9 2.6.1 添加服务... 9 2.6.2 启动计时器... 9 2.6.3 实现 timer/delay 处理函数... 10 2.7 模组 hostname 参数获取... 11 2.8 系统初始化实现... 11 3 模组网络状态获取... 11 4 其他开发适配接口 ( 可选 )... 12 5 华为 HiLink 认证模组基础 API... 13 6 FAQ... 13 2019-3-26 华为保密信息, 未经授权禁止扩散第 4 页, 共 17 页
1 概述 本文档用于指导开发者如何基于华为 HiLink 认证模组的开发环境进行二次开发 通过本文档, 开发者可以了解到基于华为 HiLink 认证模组进行二次开发的过程需要进行哪些步骤, 以及完成哪些接口的适配 帮助开发者快速完成单品的开发 说明 : 在二次开发的工程中, 配网以及 timer/delay, ota 升级等处理已经实现, 开发者只需要实现 profile 定义以及 put_char get_char 等处理 术语 : 序号术语名称说明华为 HiLink 认证模组 ( 集成了华为 HiLink 协议的 1 模组模组 ) 2 华为 HiLink 认证模组开发步骤简介 2.1 定义设备 profile 本章节介绍如何对华为 HiLink 认证模组的开发环境进行二次开发, 具体 包括如下几个步骤 : 一 定义设备 profile 二 完成设备 profile 的 put_char( 设备控制 ) 和 get_char( 设备状态查询 ) 的处理函数的适配 三 完成 HiLink 网络状态通知接口适配 四 完成 timer 和 delay 适配接口 ( 可选功能 ) 五 调用 HiLink 主任务 hilink_entry() 在华为 HiLink 认证模组初始化的时候, 需要使用到以下参数 : device info 信息, service 信息, service 个数 所以在开发时, 需要在代码中适配这三个参数 定义 dev info 结构体 (dev_profile.c) 如下图所示, 需要定义一个 dev_info_t 类型的变量, 然后根据华为的 profile 规则填写各种参数, 比如设备 ID 设备型号等等 dev_info_t dev_info = "B4XXXXXXXX17", /* 设备 SN*/ "1011", /* 设备 ID*/ "switch", /* 设备型号 */ 2019-3-26 华为保密信息, 未经授权禁止扩散第 5 页, 共 17 页
; "01D", /* 设备类型 */ "005", /* 设备制造商 */ "B4:XX:XX:XX:XX:17", /* 设备 MAC 地址 */ "1.0", /* 设备 HiLink 协议版本 */ "20000", /* 设备固件版本 */ "20000", /* 设备硬件版本 */ "20000", /* 设备软件版本 */ 1, /* 设备协议类型 */ 上面是一个 智能开关 的示例,MAC 地址可以根据实际需求, 从 flash 中读取出来 开发者需要实现接口 dev_profile_get_devinfo(dev_profile.c): dev_info_t *dev_profile_get_devinfo(void) unsigned char mac[6] = 0; hilink_wifi_get_macaddr(mac); snprintf(g_dev_mac, 32-1, "%02X:%02X:%02X:%02X:%02X:%02X", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]); dev_info.mac = g_dev_mac; return (dev_info_t*)&dev_info; 注意 : 在 SoftAP 方式下,dev_info 的 model 字段 ( 即设备型号 ) 中不能带 -, 并且,model 字段 ( 设备型号 ) 和 manu 字段 ( 设备制造商 ) 的长度 之和不能超过 17 个字符 定义 service(dev_profile.c) 如下图所示, 定义一个 svc_info_t 类型的变量, 并根据实际设备的 service 进行 svc 实例的填写 static svc_info_t hilink_svc[] = ; "binaryswitch", "switch", "timer", "timer", "delay", "delay", "netinfo", "netinfo" 然后实现接口 dev_profile_get_svc: svc_info_t* dev_profile_get_svc(int* count) if (count) *count = svccnt; 2019-3-26 华为保密信息, 未经授权禁止扩散第 6 页, 共 17 页
return &hilink_svc[0]; 定义 service 下的 key info 定义了 service 之后, 还需要将 service 下的 key 进行定义 ( 结构体需开 发者自行定义 ), const hl_key_t hikeys[] = ; 2.2 实现 PIN 码获取接口 0, "switch", "on" 说明 : 这个结构体用于定时器 / 延时器功能, 具体哪个 service 支持定时 / 延 时功能, 开发者需要与华为沟通确认 AC 数据获取适配 char *dev_process_get_ac(void); 接口即可 该接口返回 48 字节 的 ac 数据的首地址 ( 由华为提供 ) rsa 数据获取适配 char *dev_process_get_cr(void); 接口即可 该接口返回 512 字节 的 bi&rsa 数据的首地址 ( 由华为提供 ) 华为 HiLink 认证模组的出海版本中使用了 PIN 码安全配网, 如果不是出海版本, 可以不关注此节内容 出海版本中的 PIN 码必须是一个 8 位的随机数 厂家生产设备时需要将 8 位数字 PIN 写到模组 FLASH, 并在产品的外表或包装上打印 PIN 码或 PIN 码的二维码 模组启动时通过开发者适配的接口获取到当前设备 PIN 码 开发者通过在 APP 手动或扫二维码输入相同的 PIN 码进行配网 开发者需要适配接口 int HiLinkGetPinCode(void); 返回 -1 表示使用华为 HiLink 认证模组的默认 PIN 码, 配网时不需要开发者在 APP 输入 PIN 码 返回 8 位数字, 表示使用开发者适配的 PIN 码, 在使用配网时需要开发者在 APP 输入对应的 PIN 码 2.3 实现 WiFi 模组的 ID 获取接口 当需要批量升级特定的华为 HiLink 认证模组时,WiFi 模组的 id 就显得尤其重要 开发者可以实现接口 unsigned char *dev_get_wifi_deviceid(void) 来通知华为 HiLink 认证模组自己的 ID, 建议跟设备 dev_info 中的设备 ID 保持一致 说明 : 如果 WiFi 模组 id 没有设置正确, 将会影响 WiFi 模组的升级功能 2019-3-26 华为保密信息, 未经授权禁止扩散第 7 页, 共 17 页
2.4 实现 put_char 以及 get_char 当前华为 HiLink 认证模组内部调用的 put_chat 以及 get_char 接口已经封装在了二次开发工程的相关库文件中 基于二次开发工程, 开发者需要实现如下两个接口 :dev_process_put_char dev_process_get_char dev_process_get_char 用来实现 APP 对设备 service 状态的查询 在 demo(dev_profile.c) 中已经实现了 timer/delay/switch 的查询, 如果开发者有新增服务, 可以参考 demo 进行代码添加 int dev_process_get_char(const char* svc_id,..., unsigned isupdate) int err = 0; int svc_idx = 0;... if (memcmp(svc_id, "delay", strlen(svc_id)) == 0) hilink_profile_get_delay_info(*out, HILINK_MALLOC_SIZE); *out_len = hilink_strlen(*out); if (memcmp(svc_id, "switch", strlen(svc_id)) == 0) /* 在此处添加控制 IO 口操作 */ sprintf(*out, "\"on\":%d", test_on); *out_len = strlen(*out); /* 此处添加对自定义 service 的处理 */... return 0; dev_process_put_char 主要用来从 APP 端下发命令, 修改 service 的数值, 在 demo(dev_profile.c) 中已经实现了 timer/delay/switch 的修改, 开发者可以根据自定义的 service, 添加相应的处理函数 int dev_process_put_char(const char* svc_id,, unsigned int len) int err = 0;... if (memcmp(svc_id, "switch", strlen(svc_id)) == 0) /* 在此处添加控制 IO 口操作 */ if (hilink_json_get_number_value(pjson, "on", &value) == 0) test_on = value; (void)hilink_upload_char_state("switch", NULL, 0);... return 0; 说明 : 详细示例, 请参看 dev_profile.c 中的示例代码 2019-3-26 华为保密信息, 未经授权禁止扩散第 8 页, 共 17 页
2.5 实现 HiLink 状态通知 华为 HiLink 认证模组在设备上线 下线 超过十分钟未上线 设备重启 的时候, 会主动通知开发者, 方便开发者在不同状态下, 进行自定义处 理 在 dev_process.c 的接口 dev_process_notify_devstatus(dev_process.c) 中 实现自定义动作 void dev_process_notify_devstatus(int status) int ret = 0; int data = 0; switch (status) case 0: /* 设备离线 */ (void)hilink_daemon_set_net_status(net_conwifi); break; case 1: /* 设备上线 */ (void)hilink_daemon_set_net_status(net_online); break; case 2: /* 设备离线超过 10 分钟 */ break; case 3: /* 软件看门狗重启 */ HiLink_soft_boot(HILINK_WIFIDOG_REBOOT); break; 2.6 timer 和 delay 功能适配 开发者如果要使用 timer/delay 功能, 需要进行以下步骤 : 2.6.1 添加服务 在 hilink_svc[] 内加入 timer 或 delay 的服务, 以下为 switch 的示例 : const hl_key_t hikeys[] = 0, "switch", "on" ; const int svccnt = 4; static svc_info_t HiLink_svc[] = "binaryswitch", "switch", "timer", "timer", "delay", "delay", "netinfo", "netinfo" ; 2.6.2 启动计时器 模组内部处理逻辑需要开发者每隔一秒调用一次以下函数 : 2019-3-26 华为保密信息, 未经授权禁止扩散第 9 页, 共 17 页
void hilink_process_profile_time(void); 此函数会比较当前时间和设置的 timer/dalay 时间, 来判断是否触发并上报状态 推荐使用 LiteOS 软件定时器实现此功能, 示例代码如下 : static void hilink_timer_and_delay_func(uint32 uwpar) (void)uwpar; hilink_process_profile_time(); static UINT16 g_hilink_tm = 0; static void hilink_demon_start_timer_and_delay(void) UINT32 ret = LOS_OK; /* 通过软件定时器实现每隔 1s 调用 */ ret = LOS_SwtmrCreate(1000, LOS_SWTMR_MODE_PERIOD, (SWTMR_PROC_FUNC)hilink_timer_and_delay_func, &g_hilink_tm, 0); if (ret!= LOS_OK) /* 软件定时器创建失败 */ HILINK_DPRINT("LOS_SwtmrCreate fail, %d\r\n", ret); ret = LOS_SwtmrStart(g_HiLink_tm); if (LOS_OK!= ret) /* 软件定时器启动失败 */ HILINK_DPRINT("LOS_SwtmrStart fail, %d\r\n", ret); 2.6.3 实现 timer/delay 处理函数 当 timer/delay 到达设定时间后, 系统会调用如下函数, 开发者需要实现 此函数, 并在此函数中执行相关的硬件操作 unsigned int hilink_put_time_state(char *sid, char *para, int value); 说明 :sid 为服务 id,para 为服务属性,value 为属性将要设置的值 开发者需要通过 sid 和 para 找到对应的服务属性, 将找到的服务属性值设 置为 value, 设置成功后, 需要调用 hilink_upload_char_state 将新的属性值 上报 在如下示例代码中, 与硬件相关的动作可以加到第 6 行和 11 行之 间 unsigned int hilink_put_time_state(char *sid, char *para, int value) int ret = 0; unsigned char data = 0; //add your timer process code here HILINK_DPRINT("%s: sid:%s, para: %s, value: %d\r\n", FUNCTION, sid, para, value); 2019-3-26 华为保密信息, 未经授权禁止扩散第 10 页, 共 17 页
test_on = value; (void)hilink_upload_char_state(sid, NULL, 0); return DEV_TIME_OK; 2.7 模组 hostname 参数获取 2.8 系统初始化实现 开发者可以通过实现函数 void dev_get_hostname_pars(char **manu, char **devtname, char **devmode), 使得设备能够在路由器上显示自定义名 称 (Option60 参数 ) 该接口的三个参数都是出参, 需要开发者提供设备制造商的英文名称 设备类型英文名称 设备模型英文名称 下面的例子中, 在路由器界面上将会看到一个 AAA_BBB_CCC 的终端 设备 void dev_get_hostname_pars(char **manu, char **devtname, char **devmode) strncpy(*manu, "AAA", MAX_LEN); strncpy(*devtname, "BBB", MAX_LEN); strncpy(*devmode, "CCC", MAX_LEN); return; 实现接口 void hilink_entry(void) 说明 : 该接口是华为 HiLink 认证模组的入口函数, 在 main.c 中直接 调用即可启动模组 3 模组网络状态获取 通过调用下面接口, 开发者可以获取当前模组的运行状态 int hilink_daemon_get_net_status(hilink_net_status *netstatus) 通过此接口获取模组网络状态, 其中,netstatus 是出参, 需要开发这在外部申请内存 模组网络状态包括如下 : NET_UNKONWN: 设备未配网或者配网超时 ; NET_NOAP: 表示正处于配网过程中 ; NET_NOTCONN: 表示已经配网, 但是还没有连接路由器. NET_CONWIFI: 表示连接上了路由器但还未连上云 NET_ONLINE: 表示设备已连接上云 2019-3-26 华为保密信息, 未经授权禁止扩散第 11 页, 共 17 页
4 其他开发适配接口 ( 可选 ) 除上一个章节介绍的适配内容之外, 华为 HiLink 认证模组二次开发环境中还提供了以下适配接口, 开发者可以根据业务需要选择适配 int dev_run_extern_task(void) 此接口在模组的预处理阶段被调用, 开发者可以在此函数中创建一些自定义预处理功能, 比如 : 创建定时延时处理任务等 int dev_run_extern_task(void) /* 使用软件定时器, 创建自定义任务 */ LOS_SwtmrCreate ( ) return 0; 注 : 此函数中不能调用阻塞函数 int dev_extern_func_in_loop(void) 此接口是在模组的主体循环架构中被调用的, 每 50 毫秒会被调用一次 开发者可以将一些需要反复调用的功能在此接口中执行 int dev_extern_func_in_loop(void) int count = 0; bool level = 0; /* 增加一些需要反复处理的功能, eg 灯闪烁 */ if (count%20 == 0) level = led_get_gpio(); led_set_gpio(!level); count++; return 0; 注 : 此函数中不能调用阻塞函数 int dev_notify_wifi_param_deleted(void) 在 dev_process.c 中自动生成了模组重启之前供开发者实现的接口 int hilink_process_before_restart(int flag), 在异常情况下, 华为 HiLink 认证模组会发送重启请求, 调用该接口通知开发者进行数据备份等必要操作, 以保证模组重启后的运行状态与重启前一致 若该接口的返回 0, 华为 HiLink 认证模组将会重启, 否则继续等待 int dev_notify_wifi_param_deleted(void) /* 这里可以进行重启前的备份工作 */ save_user_data_to_flash(); return 0; 注 : 此函数中不能调用阻塞函数 2019-3-26 华为保密信息, 未经授权禁止扩散第 12 页, 共 17 页
5 华为 HiLink 认证模组基础 API 在开发过程中需要使用 Realtek 内部资源以及 LiteOS 等相关接口 相关的 API 的文档可以参考如下说明 LiteOS 的相关 API 可以参考 https://github.com/liteos/liteos/blob/develop/doc/huawei_liteos_de veloper_guide_zh.md Realtek 开发相关文档 请参考 doc 目录下的 api_doc.htm 其他文档请参考 * Realtek Ameba-Z*.pdf 的相关文档 6 FAQ Q1: 设备如何主动上报状态? A: 调用如下接口, 当前只需传入 svc_id 即可, 华为 HiLink 认证模组将上报该服务下的所有属性值 int hilink_upload_char_state(char* svc_id, char* payload, unsigned int len); svc_id: 服务 ID; payload:json 格式的数据, 当前暂未使用, 设为 NULL; len:payload 长度, 其值为 [0,512), 暂未使用, 设置为 0; Q2: 应用层代码可以使用的 Flash 空间有哪些? 相应 API( 读, 写等 ) 是那 些? A: 应用层代码使用的 FLASH 空间为 0XE5000-0xEB000( 共 24K) 相应读写 API 为 wifi_write_to_flash 和 wifi_read_from_flash int wifi_write_to_flash(unsigned int addr, unsigned char *data, uint32_t datalen); int wifi_read_from_flash(unsigned int address, unsigned char *data, uint32_t datalen); Q3: hilink_region_ab_crcchk 这个入参含义? 主要都校验那些参数? 仅仅 拷贝示例代码就可以? A: 只要拷贝 dev_main_init 内的用法就可以, 这个接口是用来检测双备 份区域内数据的合法性 Q4: 启动 timer 内部处理逻辑需要在任务中每隔一秒执行一次 void hilink_process_profile_time(void); 是必须的吗? A: 是的, 这个函数每秒调用一次用来处理 delay timer 等定时属性 2019-3-26 华为保密信息, 未经授权禁止扩散第 13 页, 共 17 页
Q5: 设备端发起恢复出厂设置, 调用哪个 Hilink 接口完成这个动作? A: 调用 hilink_save_revoke_flag() 通知 SDK; 调用 hilink_notify_wifi_param(null, 0, NULL, 0, -1) 恢复出厂设置 Q6: 关于自组网 ( 例如 WiFi 数据收发, 信号强度等信息 ),LiteOS 有哪 些现场的封装? A: 区分 Multicast 和 SoftAP Multicast 配网方式对应的 API 接口函数 : void entry_factory_mode() int wifi_link = 0; int retrytimes = 0; int rssi = 0; unsigned char *ssid = "liteos_debug"; unsigned char *pwd = "liteos_debug"; unsigned char ssid_len = hilink_strlen(ssid); unsigned char pwd_len = hilink_strlen(pwd); hilink_stop_auto_config(); (void)wifi_set_promisc(0, NULL, 0); (void)hilink_msleep(100); (void)wifi_init_netif_ip(); hilink_connect_wifi(ssid, ssid_len, pwd, pwd_len); while (0 == wifi_link) retrytimes++; if (retrytimes >= 20) if (wifi_is_connected_to_ap() == RTW_SUCCESS) (void)lwip_dhcp(0, 0); retrytimes = 0; (void)hilink_network_state(&wifi_link); (void)los_taskdelay(100); wifi_get_ap_rssi_value(ssid, &rssi); hilink_printf("\r\n factory ssid:%s rssi:%d \r\n", ssid, rssi); SoftAP 配网方式对应的 API 接口函数 : void entry_factory_mode() int wifi_link = 0; int retrytimes = 0; int rssi = 0; unsigned char *ssid = "liteos_debug"; 2019-3-26 华为保密信息, 未经授权禁止扩散第 14 页, 共 17 页
unsigned char *pwd = "liteos_debug"; unsigned char ssid_len = hilink_strlen(ssid); unsigned char pwd_len = hilink_strlen(pwd); unsigned int tmp_len = 0; hilink_stop_auto_config(); (void)wifi_set_promisc(0, NULL, 0); (void)hilink_msleep(100); ret = hilink_close_softap("null", &tmp_len); printf("hilink_close_softap ret: %d\r\n", ret); (void)wifi_init_netif_ip(); hilink_connect_wifi(ssid, ssid_len, pwd, pwd_len); while (0 == wifi_link) retrytimes++; if (retrytimes >= 20) if (wifi_is_connected_to_ap() == RTW_SUCCESS) (void)lwip_dhcp(0, 0); retrytimes = 0; (void)hilink_network_state(&wifi_link); (void)los_taskdelay(100); wifi_get_ap_rssi_value(ssid, &rssi); hilink_printf("\r\n factory ssid:%s rssi:%d \r\n", ssid, rssi); Q7: 两个管脚无法控制问题? A: 在文件中 extern void sys_jtag_off(void) 处理下 ;Realtek 提供的版本默认会占用管脚 Q8: OTA 升级完成重启前如何让应用知道重启, 返回状态位? A: 用户在自己的代码中适配接口 hilink_process_before_restart 即可 Q9: app 中 delay 和 timer 无法设置? A: 按照适配说明检查 Timer 和 delay 功能适配没有问题 ( 见本文 2.6 章节 ) 着重确认启动 timer 内部处理逻辑接口 hilink_process_profile_time(void) 在任务中会每隔一秒执行一次 Q10:JSON 解析接口? A: 接口描述见附件 HiLinkJsonAPI.txt 调用方法 : 可直接在 dev_profile.c 中调用 ; HiLinkJsonAPI.txt 2019-3-26 华为保密信息, 未经授权禁止扩散第 15 页, 共 17 页
Q11:hikeys 结构体适配说明? A: typedef struct int id; char* sid; char* name; hl_key_t; 此结构体的作用 : 只用作 timer 和 delay 服务下发的控制 svcid 校验, 校验接口是 dev_profile.c 中的 dev_get_svcinst_byname 举例说明 : (1) 假如 APP 下发的 timer 报文为 : "timer":["week":127,"para":"on","enable":1,"start":"083100z","end":" 083300Z","sid":"switch"],"action":1 delay 报文为 : "delay":["para":"on","start":"20180927t104702z","sid":"switch"],"a ction":1 即 timer 和 delay 功能只用于控制服务名称为 switch 的开关, 其属性名称为 on; 则 hikeys 结构体适配为 : const hl_key_t hikeys[] = 0, "switch", "on" ; (2) 如果某设备 timer 和 delay 还会控制别的服务执行定时或延时任务, 例如某设备有两个开关, 服务名称分别为 switch1 和 switch2, 属性均为 on; 且 APP 上规划功能, 两个开关均可支持定时或者 delay, 则此设备应该配置 hikeys 结构体如下 : const hl_key_t hikeys[] = 0, "switch1", "on", 1, "switch2", "on" ; 备注 : 第一个参数 id 仅为序号, 无实际意义, 按顺序累加即可 ; 结合以上两个示例说明,hikeys 结构体适配时, 需要根据产品和 APP 规划的定时 / 延时功能中控制的服务来适配 ; 并不是所有 profile 的服务都要添加, 这块只需要写会被 timer 和 delay 功能调用的服务属性 ; 如果产品未规划 timer 和 delay 功能, 此处不做修改即可 ; const hl_key_t hikeys[] = 0, "switch", "on" ; 错误影响 : 如果 timer 和 delay 要调用的服务未在 hikeys 中适配, 则使用 LiteOS 模组自带的 timer 和 delay 功能时, 定时 / 延时功能将无效 ; 2019-3-26 华为保密信息, 未经授权禁止扩散第 16 页, 共 17 页
Q12:SNTP 网络同步 API? A: 可以调用该接口 time_t rtc_read(void) 获取时间 ; 返回的单位为秒 2019-3-26 华为保密信息, 未经授权禁止扩散第 17 页, 共 17 页