# 独立升级使用指导
## 如何开启独立升级

修改
>build/config/target_config/ws63/config.py  

中的配置项
>ws63-liteos-app-iot

具体修改如下：  
1. 删除`'liteos_kconfig': 'ws63_iot'`
2. 在`'defines'`中增加`CONFIG_SUPPORT_HILINK_INDIE_UPGRADE`
3. 在`'ram_component'`中增加`'app_addr_map'`并删除`'hilinkdevicesdk'`、`'hilinkota'`、`'hilinkbtsdk'`、`'hilinkquickcfg'`

若需关闭独立升级，反向操作即可。独立升级默认已开启。

## 开启独立升级时的编译方式

1. 开启独立升级后，代码将编译为两个固件，hilink sdk单独一个固件，因此需要分别进行编译，即：  
    先编译hilink固件  
    `./build.py -c ws63-liteos-hilink`  
    再编译app-iot固件，并生成完整烧录包  
    `./build.py -c ws63-liteos-app-iot`  
    产物位于
    >output/ws63/fwpkg/ws63-liteos-app-iot/ws63-liteos-app-iot_all.fwpkg

    打包生成完整升级包  
    `./build/config/target_config/ws63/build_ws63_update.py --pkt=app_iot`  
    产物位于
    >output/ws63/upgrade/update.fwpkg
2. **（建议）**使用新增编译工具进行一步编译，该工具可一步生成所需产物，如下：  
    模组工程有更新，需要全量编译时：  
    `./indie_build.py all`  
    该命令会依次编译hilink固件、app-iot固件，生成完整烧录包与完整升级包，并将相关输出打包，产物位于
    >output/ws63/ws63-liteos_all.zip  

    压缩包中除了完整烧录包和完整升级包外，也归档了两个固件以及他们的校验文件，其中  
    >ws63-liteos-app-iot-sign.bin  
    ws63-liteos-app-iot-check.json

    需要进行归档，用于独立升级时的合包和校验过程。

## 独立升级流程

当app-iot固件无需更新，仅hilink固件需要更新，且其互相调用的接口未发生变化时，可进行独立升级流程。步骤如下：

1. 获取已经过认证并归档的app-iot固件，及其校验文件，即
    >ws63-liteos-app-iot-sign.bin  
    ws63-liteos-app-iot-check.json
    
    将其置于工程目录中
    >output/ws63/acore/ws63-liteos-app-iot/

2. 获取更新的hilink sdk库文件，替换工程中原有的库文件：
    >application/samples/wifi/libhilink/

    独立编译sdk，并生成完整烧录包和完整升级包：  
    `./indie_build.py sdk`  
    该命令会编译生成新的hilink固件，并与已经过认证的app-iot固件进行匹配校验。若有接口不匹配，将校验失败，表示不允许进行独立升级，可在日志检查具体接口。在通过校验后，与app-iot固件打包生成完整的烧录包以及升级包。产物位于
    >output/ws63/upgrade/package.zip

    即完整升级包，上传平台进行独立升级流程。

## 独立升级约束
1.  由于分区划分存在差异，非独立升级版本与独立升级版本不可以交叉升级。
2.  由于独立升级时，模组app程序不变，仅HiLink程序改变，若有接口发生变更（如参数类型、顺序等）发生变化，则可能引起程序不可预期的现象。因此会在制作独立升级OTA包时，对模组app和HiLink双方固件的接口进行校验，若未通过，不允许进行独立升级。
3.  开启独立升级时，产品固件版本号格式会拼接sdk版本号，例：
    非独立升级：1.0.0
    独立升级：1.0.0_14.2.0.304
    部署OTA升级时，需按对应格式填写版本号

## 新增接口适配
开启独立升级后，由于模组app和HiLink分别编译成两个固件，其接口未经过链接，不能直接相互调用。其调用机制为，双方各自维护一张接口地址表，当一方需要调用另一方接口时，查询对方接口地址表并返回接口函数指针，再进行调用。  
因此双方接口需要额外适配，才能实现互相调用。对HiLink新增接口举例如下（HiLink需新增调用模组app侧接口可类似参考）：
1.  HiLink新增接口，原型为：  
    `retType TestFuncName(type1 param1, type2 param2, type3 param3);`  
    接口函数声明位于  
    >application/samples/wifi/ohos_connect/hilink_adapt/include/hilink_test.h
2.  在
    >application/samples/wifi/hilink_indie_upgrade/address_mapping/application/hilink_uapi/

    中新增文件`uapi_hilink_test.c`，添加该接口的查表适配实现，如下：  
    ```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;
    }
    ```
    其中，宏hilink_call3表示查找并调用具有3个参数的hilink接口，需根据函数的返回值和参数数量选择对应的宏`hilink_callx`或`hilink_callx_ret_void`。若查找到对应接口，会直接调用返回，若未查找到则往下走，第二行`return (retType)0;`为查找失败时的返回逻辑。  
    该宏接收的第一个参数为该接口的枚举值，用于表示接口在地址表中的位置，于  
    >application/samples/wifi/hilink_indie_upgrade/address_mapping/include/func_call_list.h  

    中定义，该文件会在编译时通过脚本根据接口函数名生成，无需手动增加。在编写查表实现时，可预先参考其他枚举值填写。
    该宏的后续参数分别为函数名、返回值类型、参数类型、参数名。
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"`  
    
    工程编译时，脚本会正则匹配所添加的源文件和头文件中的接口函数原型，并检查其是否匹配，若想跳过该检查，可在`default_config["hilink"]["white_list"]`中添加对应的接口函数名，如`"TestFuncName"`。检查完成后，会自动生成接口地址表：
    >application/samples/wifi/hilink_indie_upgrade/address_mapping/hilinksdk/hilink_function_mapping.c