ekko/LPT26x-HSF-4MB-Hilink_14.2.0.308_20250411
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb1ef391084db167c050e5af56289d779dbf1075
LPT26x-HSF-4MB-Hilink_14.2.…/ws63_check_json_analysis.md
ekko.bao 21c6d05bad 1. 解决PWM 更新导致周期混乱继而亮度抖动的问题 
2. 增加无论何种状态都能强制复位的机制
3. 添加设备注册检查机制，如果设备已经处于配网但是还是注册的状态，强制进行一次复位
4. 添加串口控制协议
2025-10-26 17:49:12 +08:00

19 KiB
Raw 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 校验码生成原理

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

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

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

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

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

  4. 校验码串联: 将所有接口的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 文档，开启独立升级需要：

  1. 修改配置 (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'

  2. 分别编译两个固件:

    # 先编译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

  3. 使用简化编译工具:

    # 完整编译
python3 indie_build.py all

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

6.3 独立升级流程

  1. 准备已认证的App-IoT固件:

    • ws63-liteos-app-iot-sign.bin
    • ws63-liteos-app-iot-check.json

  2. 更新HiLink SDK库文件:

    • 替换 application/samples/wifi/libhilink/ 中的库文件

  3. 执行独立编译:

    python3 indie_build.py sdk

  4. 接口兼容性校验:

    • 自动比较新HiLink固件与已认证App-IoT固件的接口
    • 如果接口不匹配，构建失败
    • 校验通过后生成完整升级包

6.4 约束条件

  1. 分区兼容性: 非独立升级版本与独立升级版本不可交叉升级
  2. 接口兼容性: 模组App程序不变时，HiLink接口不能发生变更
  3. 版本号格式:
    • 非独立升级：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);

  1. 接口声明 (application/samples/wifi/ohos_connect/hilink_adapt/include/hilink_test.h):

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

  2. 查表适配实现 (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;
}

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

    uapi_hilink_test.c

  4. 配置脚本识别 (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",)

  5. 白名单配置（可选）:

    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个参数函数

参数说明:

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

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文件未生成

可能原因:

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

排查步骤:

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

10.2 接口兼容性校验失败

错误信息示例:

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

排查步骤:

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

10.3 接口映射表生成失败

可能原因:

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

排查步骤:

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

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

Reference in New Issue View Git Blame Copy Permalink