智能家居 HiLink 单模组芯片二次开发指导文档版本 02 发布日期华为技术有限公司

Size: px

Start display at page:

Download "智能家居 HiLink 单模组芯片二次开发指导文档版本 02 发布日期华为技术有限公司"

榴缪
4 years ago
Views:

1 智能家居 HiLink 单模组芯片二次开发指导文档版本 02 发布日期华为技术有限公司

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

3 华为保密信息, 未经授权禁止扩散第 3 页, 共 17 页

4 目录 1 概述华为 HiLink 认证模组开发步骤简介定义设备 profile 实现 PIN 码获取接口实现 WiFi 模组的 ID 获取接口实现 put_char 以及 get_char 实现 HiLink 状态通知 timer 和 delay 功能适配添加服务启动计时器实现 timer/delay 处理函数模组 hostname 参数获取系统初始化实现模组网络状态获取其他开发适配接口 ( 可选 ) 华为 HiLink 认证模组基础 API FAQ 华为保密信息, 未经授权禁止扩散第 4 页, 共 17 页

5 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", /* 设备型号 */ 华为保密信息, 未经授权禁止扩散第 5 页, 共 17 页

6 ; "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; 华为保密信息, 未经授权禁止扩散第 6 页, 共 17 页

7 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 模组的升级功能华为保密信息, 未经授权禁止扩散第 7 页, 共 17 页

8 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 中的示例代码华为保密信息, 未经授权禁止扩散第 8 页, 共 17 页

9 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 功能, 需要进行以下步骤 : 添加服务在 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" ; 启动计时器模组内部处理逻辑需要开发者每隔一秒调用一次以下函数 : 华为保密信息, 未经授权禁止扩散第 9 页, 共 17 页

10 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); 实现 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); 华为保密信息, 未经授权禁止扩散第 10 页, 共 17 页

11 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: 表示设备已连接上云华为保密信息, 未经授权禁止扩散第 11 页, 共 17 页

12 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; 注 : 此函数中不能调用阻塞函数华为保密信息, 未经授权禁止扩散第 12 页, 共 17 页

13 5 华为 HiLink 认证模组基础 API 在开发过程中需要使用 Realtek 内部资源以及 LiteOS 等相关接口相关的 API 的文档可以参考如下说明 LiteOS 的相关 API 可以参考 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 等定时属性华为保密信息, 未经授权禁止扩散第 13 页, 共 17 页

14 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"; 华为保密信息, 未经授权禁止扩散第 14 页, 共 17 页

15 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 华为保密信息, 未经授权禁止扩散第 15 页, 共 17 页

16 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":" Z","sid":"switch"],"action":1 delay 报文为 : "delay":["para":"on","start":" t104702z","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 功能时, 定时 / 延时功能将无效 ; 华为保密信息, 未经授权禁止扩散第 16 页, 共 17 页

17 Q12:SNTP 网络同步 API? A: 可以调用该接口 time_t rtc_read(void) 获取时间 ; 返回的单位为秒华为保密信息, 未经授权禁止扩散第 17 页, 共 17 页

API参考

API参考文档版本 03 发布日期 2018-06-20 华为技术有限公司版权所有华为技术有限公司 2018 保留一切权利非经本公司书面许可, 任何单位和个人不得擅自摘抄复制本文档内容的部分或全部, 并不得以任何形式传播商标声明和其他华为商标均为华为技术有限公司的商标本文档提及的其他所有商标或注册商标, 由各自的所有人拥有注意您购买的产品服务或特性等应受华为公司商业合同和条款的约束, 本文档中描述的全部或部分产品

智能家居 HiLink 单模组芯片 二次开发指导 文档版本 02 发布日期 华为技术有限公司

智能家居 HiLink 单模组芯片二次开发指导文档版本 02 发布日期华为技术有限公司