ekko/LPT26x-HSF-4MB-Hilink_14.2.0.308_20250411

Files

ekko.bao 21c6d05bad 1. 解决PWM 更新导致周期混乱继而亮度抖动的问题

2. 增加无论何种状态都能强制复位的机制
3. 添加设备注册检查机制，如果设备已经处于配网但是还是注册的状态，强制进行一次复位
4. 添加串口控制协议

2025-10-26 17:49:12 +08:00

19 KiB

Raw Permalink Blame History

WS63 Check.json 文件分析完整文档

概述

本文档详细分析了 ws63-liteos-hilink-check.json 文件的生成机制、校验内容和对应关系。该文件是WS63项目独立升级功能的核心组件，用于验证HiLink固件与App-IoT固件之间的接口兼容性。

1. JSON文件基本信息

文件路径: ./output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json

文件内容结构:

{
  "ver": 1,
  "app": "3A23309AAF0B692188B9C56755C084522354143382C5309A2D3258C3E6C834A500B53089C7A65C43392D51DFEF32BBC125B613C6B37656F59E142F0D713AD6115955749E72C53C3BA8CD96D2C69CB534231411DEAE5C4F1782DA2760BB04E0199813CAC4CBA339BEBF3D734FBF0955235DD160C0387CA4AD28BFC8766508F627D0B46BE48319EAC371921D27D806C9F3464BF4DFBAE09ADB95232386B021EEFBD3FAD2C6B405A1E9C13BB0420CAB5EF02D3D543090162EB8E51C2E1D10F3EE4EE5FE71A0BA8DF1E95E4A36694908DDB16E08F54B606E13CACB530F71320CC9DF6C3DCB70DC6E54BDA7B3C1720E7ECCB54E88950CFC3D4D700224AB40D9E568A89571387053E9BB3D77889DAA102DB1FC4CE38751F2E6A0BD27B0EC51B8EA015CE0E475ADF3E3CDB49580E84E228803A691F39D958D3F28B0E4D53C670A27B5AB436D11F83A8AAEB6538628D32F674C398B6CF1C295BAB9499E19EA993B11D07524E025EF6FF88F42331C3BE36689468DAF74C6B811187E2D7953251B9228B8A8C32422F97C0122332BB295C110F36291A845CD2FA2D6BC34E37B7CBE23083067AE8AF9346DEEEFCC168D2D4658A94AB5049858C11E8BE4672F492DE9B4046E4B0EEEA5E3D6FE8809743B2B6111718F2038742D7C48EE81BBD5D485373D34C70868622D3233179ADED3E8C5026A2217F6938E85AA7A6754CE869A8127656D364C00F05E95FE7738AD05E79CACA11368FAE6717C71C469FC934FF221953E9F7CA301D52266EA04E8184A6D5AF66621F90139D0642D0350FA3F28ED49CF23AC20D03710992FBE7E3DBCEBD737385AE906D8D885A6118F2416A45FFA93EC3483EDADE5864419C451689382274A6DEC6FD6734D3975199C9FFB561202FEAB34F195D595E791C43315669E430FB9E7288EF87BC4498A4DF1A93918FA7C7805F7131CCF092F762F28C0A502EC955661D19C624CD0B61E88F81F9D57108A971D268273CEABEE8013FF69661C1A29BBD995111C6A64314013FBA647F77B736AE8E330F3D7157E6C3774AFBCC38D643C7108363127CB03B902C6D32C202A73EE7099A65902A14959BA60D70D055A89A6C3E489489F355E418A02EF8A543D8DF826C59AD8FABD1564AF4FEE6224FCA67974F6F63E17D3036A50120E5449669A4D792E919F88C4BBEEC64E542216D35ED1DE5A21434FC521776D37F5C50257B639AA3F47D1CC1888A19961CD6F5D7C9BEF30D5EACE785DB24268E360581533F98458376DD1E770BF3612B6D1F9C62395F48BEDE23AE1514E24C79360CE44291140AFEC5576503E6EBBC1D453DC9ED772F6AA506112D26C5B806EC4E0EAEC6A98F6F1683AC86494FA565B7CE2A0540F45AC6A8A556CDEE96B315EF45ED456EF46F1E5C234ABF92B121CCE688D2163BDF57FB6098B4742FBC504AC5E03230ADF90428D53F024F9C20964CA8AEA8A9042D1CEF0A2BA9C88A011C1004A9B8F7F9EBEDA365056947E9426D868829904D70DA74B7276D93829D151333F3506E83032A8CF68630BD5D0A39237FDF0BADD131AB77B6092987F07139588081D140EB2A0CA25BF9267FBC809457528A7C5DFA1729552A8D76B3362B9915E84795CD770EB84A3AE73DE78F04D37E8FC2F53E2F72853D57F170FC2551F7CBBB9B63D119AC4775120418F3865792FEFAAFF69038BFD3AA3C2C476B26DFB2B48F3B3904203C394782FE1C40F718001C31504539827DDC80900966524DCE965006F86EBDA9C46226BC1DA2387E2AE9565DFEE621F0DA936298371D1AD83860B4E607BB473E4103ADF872D1A3CA9EB171CF73077B4AFC2D7FC3737FAE5337290D8116CE0826F347C621502BA313EEF20F1F67D00A7EB1BB555DE7B0FCDD05C747D7615136B35079DA4BF9A6EED5F0C5448B8364FB03476275BD823C8C7F3CBCC1D0BD41C5B49538D65C00C85F9C8D50201EDA6266D7A2A375141F7F5E69E1AD06932C3A6C044EAE908D43657EA22C5FA797FE8D04592541477B362753A05",
  "hilink": "BEC62B3A1B90717BABD8C9AD15D3BE1560977111A022C59CEF399A97E8B1D1D2D981EE972F4C881D0D3D30D8165FA46BEB1F07B4B8F1AECEA4335DFC7388E1234641EDD1AF31DFEDB616EBF0A9900778C03C4467D3CBCD6540F51D66CBE0FF998506BA06448D8BEB6CDA8E9E79BE4C8BF15449A4DEFEB22F342B09F03683E17D699DA475D08A2F079EDA59B99A96CD0E468B089224120EE96B86A8BB4B250B35E0E8B8A1E77FE8A13F50CF8B018FA5A91475DDA932141DAF1F5C4D9C5D7F8DC8E3CB582D0DB0EA8823396BF6BC0A30D68B968BEE77AB6014036385A68BB35701D274404A9BFA24348E7321F63FEA98B7"
}

2. 文件生成机制

2.1 生成触发条件

触发时机: 在构建过程的 build_post 阶段（构建完成后）

配置条件: 编译配置中必须包含 CONFIG_SUPPORT_HILINK_INDIE_UPGRADE

当前项目状态：该配置已被注释（config.py:334行）
因此只有HiLink固件生成了check.json，App-IoT固件未生成

2.2 生成调用链

构建系统 (build.py) 
  ↓
build_post 钩子
  ↓  
entry.py:153 → dump_indie_upg_check_file()
  ↓
indie_upgrade_utils.py:324 → 生成JSON文件

2.3 核心生成文件

主要脚本文件:

build/config/target_config/ws63/script/entry.py:153 - 构建钩子调用点
build/script/utils/indie_upgrade_utils.py:324 - JSON文件生成函数
build/script/utils/indie_upgrade_utils.py:292-320 - 接口校验码生成核心逻辑

3. 校验内容详解

3.1 JSON字段含义

字段	含义	数据格式
`ver`	校验文件版本号	整数，当前为1
`app`	App侧接口校验码串联	CRC32十六进制字符串
`hilink`	HiLink侧接口校验码串联	CRC32十六进制字符串

3.2 校验码生成原理

接口函数扫描: 通过正则表达式扫描源文件中的函数原型

rgl = r"((?:const )?(?:unsigned )?(?:struct )?(?:enum )?\w+[ \*]*)" + \
      r"(\w+)[\s\n]*" + \
      r"(\()" + \
      r"([\s\*,\w\[\]]*?)" + \
      r"(\))" + \
      r"\s*\{"

原型标准化: 去除参数名，保留参数类型，生成标准化函数原型字符串

CRC32计算: 对每个函数原型字符串计算CRC32校验码

checksum = "{:08X}".format(zlib.crc32(prototype.encode("utf8")))

校验码串联: 将所有接口的8位十六进制CRC32码按顺序串联

3.3 校验码对应的编译文件

JSON字段	编译目标	二进制文件	签名文件
`"app"`	`ws63-liteos-app-iot`	`output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot.bin`	`ws63-liteos-app-iot-sign.bin`
`"hilink"`	`ws63-liteos-hilink`	`output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink.bin`	`ws63-liteos-hilink-sign.bin`

4. 接口映射文件体系

4.1 App侧接口配置

源文件路径: application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/app_uapi/

主要接口文件:

uapi_hilink_kv_adapter.c - KV存储适配器接口
uapi_hilink_mem_adapter.c - 内存管理适配器接口
uapi_hilink_socket_adapter.c - Socket网络适配器接口
uapi_hilink_stdio_adapter.c - 标准IO适配器接口
uapi_hilink_thread_adapter.c - 线程管理适配器接口
uapi_hilink_time_adapter.c - 时间管理适配器接口
uapi_hilink_network_adapter.c - 网络适配器接口
uapi_hilink_device.c - 设备管理接口
uapi_hichain.c - 设备认证接口
uapi_hilink_ble_adapter.c - BLE适配器接口
等共52个接口适配文件

生成的映射表: application/samples/wifi/hilink_indie_upgrade/address_mapping/application/app_function_mapping.c

4.2 HiLink侧接口配置

源文件路径: application/samples/wifi/hilink_indie_upgrade/address_mapping/application/hilink_uapi/

主要接口文件:

uapi_hilink.c - HiLink核心接口
uapi_hilink_log_manage.c - 日志管理接口
uapi_hilink_device_ext.c - 设备扩展接口
uapi_ble_cfg_net_api.c - BLE配网接口
uapi_hilink_bt_function.c - 蓝牙功能接口
uapi_hilink_network_adapter.c - 网络适配器接口
uapi_hilink_socket_adapter.c - Socket适配器接口
uapi_hilink_custom.c - 自定义功能接口
uapi_hilink_sle_api.c - SLE接口
uapi_hilink_quick_netcfg_api.c - 快速配网接口

生成的映射表: application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/hilink_function_mapping.c

4.3 接口头文件映射

App侧头文件路径:

application/samples/wifi/ohos_connect/hilink_adapt/adapter/include/ - 适配器接口声明
application/samples/wifi/ohos_connect/hilink_adapt/product/ - 产品相关接口
application/samples/wifi/ohos_connect/hilink_adapt/include/ - 通用接口声明
open_source/deviceauth/interfaces/innerkits/deviceauth_lite/ - 设备认证接口
kernel/liteos/liteos_v208.5.0/Huawei_LiteOS/open_source/CMSIS/CMSIS/RTOS2/Include/ - RTOS接口
open_source/cjson/cjson/ - JSON库接口
open_source/mbedtls/mbedtls_v3.1.0/include/ - 加密库接口

HiLink侧头文件路径:

application/samples/wifi/ohos_connect/hilink_adapt/include/ - HiLink核心接口声明
application/samples/wifi/ohos_connect/hilink_adapt/product/ - 产品相关接口
application/samples/wifi/ohos_connect/hilink_adapt/adapter/include/ - 适配器接口声明

5. 校验机制详解

5.1 接口兼容性检查函数

函数位置: build/script/utils/indie_upgrade_utils.py:353-370

检查逻辑:

def check_indie_upg_match(hilink_check_file, app_check_file):
    # 读取两个check.json文件
    f = open(hilink_check_file, "r", encoding="utf-8")
    hilink_check = json.loads(f.read())
    f.close()
    f = open(app_check_file, "r", encoding="utf-8")
    app_check = json.loads(f.read())
    f.close()

    # 版本号检查
    if hilink_check["ver"] != 1 or app_check["ver"] != 1:
        print("check file ver[h:%d,a:%d] not match" % (hilink_check["ver"], app_check["ver"]))
        return False
        
    # HiLink侧接口向后兼容检查
    if not hilink_check["hilink"].startswith(app_check["hilink"]):
        prt_not_match_info("hilink", hilink_check["hilink"], app_check["hilink"], True)
        return False
        
    # App侧接口向后兼容检查
    if not app_check["app"].startswith(hilink_check["app"]):
        prt_not_match_info("app", app_check["app"], hilink_check["app"], True)
        return False
        
    return True

5.2 校验失败信息输出

函数位置: indie_upgrade_utils.py:330-350

校验失败时会输出具体的不匹配接口信息：

显示接口序号和对应的CRC32校验码
帮助定位具体是哪个接口发生了变更
每个CRC32码长度为8个十六进制字符

5.3 升级包构建时的校验

调用位置: build/config/target_config/ws63/build_ws63_update.py:74

if not check_indie_upg_match(info.hilink_check, info.app_iot_check):
    print("indie upg hilink and app not match")
    return False

在生成升级包时会自动进行兼容性检查，如果接口不兼容，构建过程会失败。

6. 独立升级工作流程

6.1 独立升级概述

独立升级允许在不更新App-IoT固件的情况下，单独升级HiLink SDK固件。这种机制可以：

快速修复HiLink SDK的bug
更新云端协议和功能
减少升级包大小和升级时间
降低升级风险

6.2 配置开启流程

根据 indie_upg.md 文档，开启独立升级需要：

修改配置 (build/config/target_config/ws63/config.py):
- 删除 'liteos_kconfig': 'ws63_iot'
- 在 'defines' 中增加 CONFIG_SUPPORT_HILINK_INDIE_UPGRADE
- 在 'ram_component' 中增加 'app_addr_map'
- 在 'ram_component' 中删除 'hilinkdevicesdk'、'hilinkota'、'hilinkbtsdk'、'hilinkquickcfg'

分别编译两个固件:

# 先编译HiLink固件
python3 build.py -c ws63-liteos-hilink

# 再编译App-IoT固件
python3 build.py -c ws63-liteos-app-iot

# 生成升级包
python3 build/config/target_config/ws63/build_ws63_update.py --pkt=app_iot

使用简化编译工具:

# 完整编译
python3 indie_build.py all

# 仅编译SDK（用于独立升级）
python3 indie_build.py sdk

6.3 独立升级流程

准备已认证的App-IoT固件:
- ws63-liteos-app-iot-sign.bin
- ws63-liteos-app-iot-check.json
更新HiLink SDK库文件:
- 替换 application/samples/wifi/libhilink/ 中的库文件
执行独立编译:
```
python3 indie_build.py sdk
```
接口兼容性校验:
- 自动比较新HiLink固件与已认证App-IoT固件的接口
- 如果接口不匹配，构建失败
- 校验通过后生成完整升级包

6.4 约束条件

分区兼容性: 非独立升级版本与独立升级版本不可交叉升级
接口兼容性: 模组App程序不变时，HiLink接口不能发生变更
版本号格式:
- 非独立升级：1.0.0
- 独立升级：1.0.0_14.2.0.304 (拼接SDK版本号)

7. 新增接口适配指南

7.1 接口调用机制

独立升级模式下，模组App和HiLink分别编译成两个固件：

各自维护接口地址表
通过查表机制获取对方接口函数指针
实现跨固件的函数调用

7.2 新增HiLink接口步骤

示例接口原型:

retType TestFuncName(type1 param1, type2 param2, type3 param3);

接口声明 (application/samples/wifi/ohos_connect/hilink_adapt/include/hilink_test.h):
```
retType TestFuncName(type1 param1, type2 param2, type3 param3);
```

查表适配实现 (application/samples/wifi/hilink_indie_upgrade/address_mapping/application/hilink_uapi/uapi_hilink_test.c):

retType TestFuncName(type1 param1, type2 param2, type3 param3)
{
    hilink_call3(HILINK_CALL_TEST_FUNC_NAME, TestFuncName, retType, type1, param1, type2, param2, type3, param3);
    return (retType)0;
}

添加到编译系统 (application/samples/wifi/hilink_indie_upgrade/address_mapping/application/CMakeLists.txt):
```
uapi_hilink_test.c
```

配置脚本识别 (build/script/utils/indie_upgrade_utils.py):

default_config["hilink"]["src_file"] += ("uapi_hilink_test.c",)
default_config["hilink"]["mapping_header"]["application/samples/wifi/ohos_connect/hilink_adapt/include/"] += ("hilink_test.h",)

白名单配置（可选）:

default_config["hilink"]["white_list"] += ("TestFuncName",)

7.3 宏说明

查表宏定义:

hilink_call0 / hilink_call0_ret_void - 无参数函数
hilink_call1 / hilink_call1_ret_void - 1个参数函数
hilink_call2 / hilink_call2_ret_void - 2个参数函数
hilink_call3 / hilink_call3_ret_void - 3个参数函数
hilink_callx / hilink_callx_ret_void - x个参数函数

参数说明:

枚举值（如 HILINK_CALL_TEST_FUNC_NAME）
函数名
返回值类型
参数类型和参数名交替列出

8. 相关文件清单

8.1 核心脚本文件

文件路径	功能描述
`build/script/utils/indie_upgrade_utils.py`	独立升级工具核心逻辑
`build/config/target_config/ws63/script/entry.py`	构建钩子入口
`build/config/target_config/ws63/build_ws63_update.py`	升级包构建脚本
`build/config/target_config/ws63/config.py`	编译配置文件
`indie_build.py`	独立升级编译工具
`package.py`	升级包生成工具

8.2 接口映射相关文件

目录/文件	描述
`application/samples/wifi/hilink_indie_upgrade/address_mapping/`	接口映射根目录
`application/samples/wifi/hilink_indie_upgrade/address_mapping/include/func_call_list.h`	函数调用枚举定义（自动生成）
`application/samples/wifi/hilink_indie_upgrade/address_mapping/application/`	App侧接口适配
`application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/`	HiLink侧接口适配
`application/samples/wifi/ohos_connect/hilink_adapt/`	接口声明头文件目录

8.3 输出文件

文件路径	描述
`output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json`	HiLink固件接口校验文件
`output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot-check.json`	App-IoT固件接口校验文件（需开启独立升级）
`output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink.bin`	HiLink固件二进制文件
`output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-sign.bin`	HiLink固件签名文件
`output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot.bin`	App-IoT固件二进制文件
`output/ws63/acore/ws63-liteos-app-iot/ws63-liteos-app-iot-sign.bin`	App-IoT固件签名文件
`output/ws63/fwpkg/ws63-liteos-app-iot/ws63-liteos-app-iot_all.fwpkg`	完整烧录包
`output/ws63/upgrade/update.fwpkg`	升级包
`output/ws63/ws63-liteos_all.zip`	完整产物压缩包

9. 当前项目状态

9.1 独立升级配置状态

当前状态: 独立升级功能已关闭

证据:

config.py:334 行："CONFIG_SUPPORT_HILINK_INDIE_UPGRADE" 被注释
config.py:291 行：'liteos_kconfig': 'ws63_iot' 仍然存在
只有HiLink固件生成了check.json文件
App-IoT固件目录下没有对应的check.json文件

9.2 编译产物状态

已生成的文件:

✅ ws63-liteos-hilink.bin (278K)
✅ ws63-liteos-hilink-sign.bin (279K)
✅ ws63-liteos-hilink-check.json (3.4K)
✅ ws63-liteos-app-iot.bin (1.7M)
✅ ws63-liteos-app-iot-sign.bin (1.7M)
❌ ws63-liteos-app-iot-check.json (未生成，因为独立升级未开启)

10. 故障排查指南

10.1 check.json文件未生成

可能原因:

CONFIG_SUPPORT_HILINK_INDIE_UPGRADE 未在配置中启用
构建过程中 build_post 钩子未执行
接口映射文件生成失败

排查步骤:

检查 config.py 中的配置项
查看构建日志中是否有 "create indie upg mapping files succ" 消息
检查接口源文件和头文件是否存在语法错误

10.2 接口兼容性校验失败

错误信息示例:

indie upg hilink and app not match
hilink checksum not match  
func 5 [A1B2C3D4:E5F6A7B8] not match

排查步骤:

确定是哪个接口发生了变更（根据func序号）
检查接口原型是否发生改变
检查参数类型、顺序、返回值类型
如果是合理的接口升级，需要重新生成App-IoT的check.json

10.3 接口映射表生成失败

可能原因:

源文件中函数原型格式不规范
头文件中接口声明与源文件实现不匹配
正则表达式匹配失败

排查步骤:

检查函数原型是否符合标准C语法
确保头文件声明与源文件实现一致
查看构建日志中的正则匹配错误信息

11. 总结

ws63-liteos-hilink-check.json 文件是WS63项目独立升级功能的核心组件，通过CRC32校验码机制确保固件间接口兼容性。虽然当前项目未启用独立升级功能，但完整的技术框架已经就绪，可以通过简单的配置修改来启用该功能。

该机制的核心价值在于：

风险控制: 通过接口校验防止不兼容升级
灵活部署: 支持HiLink SDK的独立快速升级
开发效率: 减少完整固件的编译和测试周期
维护便利: 清晰的接口约定和自动化校验流程

文档创建时间: 2025-09-10
项目版本: SR_Light_Hilink_14.2.1.312_20250714
分析对象: output/ws63/acore/ws63-liteos-hilink/ws63-liteos-hilink-check.json

19 KiB Raw Permalink Blame History Unescape Escape

WS63 Check.json 文件分析完整文档

概述

1. JSON文件基本信息

2. 文件生成机制

2.1 生成触发条件

2.2 生成调用链

2.3 核心生成文件

3. 校验内容详解

3.1 JSON字段含义

3.2 校验码生成原理

3.3 校验码对应的编译文件

4. 接口映射文件体系

4.1 App侧接口配置

4.2 HiLink侧接口配置

4.3 接口头文件映射

5. 校验机制详解

5.1 接口兼容性检查函数

5.2 校验失败信息输出

5.3 升级包构建时的校验

6. 独立升级工作流程

6.1 独立升级概述

6.2 配置开启流程

6.3 独立升级流程

6.4 约束条件

7. 新增接口适配指南

7.1 接口调用机制

7.2 新增HiLink接口步骤

7.3 宏说明

8. 相关文件清单

8.1 核心脚本文件

8.2 接口映射相关文件

8.3 输出文件

9. 当前项目状态

9.1 独立升级配置状态

9.2 编译产物状态

10. 故障排查指南

10.1 check.json文件未生成

10.2 接口兼容性校验失败

10.3 接口映射表生成失败

11. 总结

19 KiB

Raw Permalink Blame History