.. _设备升级:  

AW30N 设备升级
=========================================

    AW30N SDK 提供了 设备升级功能。
    
    设备升级功能 指的是 **SD卡升级** 和 **U盘升级**。
    
    两个升级功能 分别由 **app_modules_h.c** 里的 **SD_UPDATE_EN** 和 **UDISK_UPDATE_EN** 宏控制开关。

下面分为3个部分来介绍设备升级：
        1. ":ref:`设备升级简要流程`"
        2. ":ref:`SDK中的设备升级处理`"
        3. ":ref:`设备升级常见问题`"

.. _设备升级简要流程:  

设备升级简要流程
*****************************

   设备升级 分为 **SD卡升级** 和 **U盘升级**；

   下面简要介绍一下设备升级流程：

    1. 打开设备，检查文件  -->  2. 校验ufw文件  -->  3. 进入loader升级  
        
        | 1：根据使用的是哪一种设备升级，在app_config.h里 打开对应设备使能；
        | 2：根据使用的是哪一种设备升级，在app_modules_h.c里 打开对应的设备升级使能；
        | 3：调用 dev_update_check(char* logo) 进行升级：::

            | 1）该函数会先检测对应设备是否在线；
            | 2）判断在线后挂载fat文件系统，搜索文件里第一个后缀名为 “ufw” 的升级文件；
            | 3）搜索到对应 "ufw" 文件后 , 就会真正开始进行升级动作；
            | 4）升级过程中会校验ufw文件数据各项是否合法，不合法则会执行复位操作；
            | 5）校验成功后即可跳到loader完成剩余升级，该过程不受断电、拔卡影响，重新上电或者插卡即可继续步骤5）升级；

.. note:: 升级注意

    1：在识别到ufw文件前的任意流程出错时，均会返回错误值退出（即步骤3的第二点前）；（例如对应设备不在线，挂载不成功，均会 **有返回值返回退出** ）

    2：在识别到ufw文件后进入升级后，但在进入loader前，任意出错会执行系统复位操作；（检验文件过程中出错会执行 **复位操作** ）

    3：在识别到ufw文件后进入升级，升级库里面需要使用缓存来处理升级数据，该缓存是位于overlay区域(具体可看下载目录里的app_ld.c文件里的update_tmp_buf区域)；
    （对应":ref:`升级资源复用问题`"部分）

    4：针对于升级注意的第三点缓存位于overlay区域，在识别到ufw文件后 进入升级前，提供了一个升级回调，用户可根据自身应用，在进入升级前注册回调来关掉相关与升级模块overlay的模块；
    （对应":ref:`升级资源复用问题`"部分）

    5：升级需要需要占据一定的 VM空间（注意不是VM存储记忆使用的EEPROM区域），在使用对应升级前，可在下载时观察OTA UPDATE INFO 剩余VM空间是否支持升级；

    .. image:: update_need_space.png
        :alt: "各项升级所需空间细看"
        :align: center
    .. centered:: 各项升级所需空间细看

    6：U盘升级前除了要打开 设备宏 和 升级宏 外，还需注意是否调用过usb_host_mount()，默认在识别到U盘上线时即会挂载，用户在后续操作即可；

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _SDK中的设备升级处理:  

SDK中的设备升级处理
******************************
    
    下面介绍设备升级 中的 **U盘升级** 在SDK里的运转流程：

    （SD卡升级 与 U盘升级流程一样，只是不需要usb_host_mount挂载步骤）

打开对应需要升级的设备宏（app_config.h）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    .. image:: app_config.h.png
        :alt: "app_config.h"
        :align: center
    .. centered:: app_config.h

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

打开对应设备升级宏（app_modules_h.c）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    .. image:: update_enable.png
        :alt: "升级宏"
        :align: center
    .. centered:: 升级宏

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

公共消息里，接收到U盘上线消息后，会挂载usb
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    .. image:: usb_mount.png
        :alt: "usb挂载"
        :align: center
    .. centered:: usb挂载

.. note:: 
    挂载usb不能重复挂载

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

挂载完usb后，会推送U盘消息上线消息，调用升级函数
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    .. image:: dev_update.png
        :alt: "设备升级"
        :align: center
    .. centered:: 设备升级

    | 设备升级函数： dec_update_check()
    | 该函数里可分为3个步骤，每个步骤对应的错误处理均不同：

        | 1：打开设备，检查文件存在：失败直接关闭设备退出该函数返回错误值；
        | 2：进入升级回调，关闭与升级相关复用功能模块；（具体可参考最后常见问题章节）
        | 2：进行升级，校验ufw升级文件：失败会执行系统复位操作；（具体可参考最后常见问题章节）
        | 3：校验成功跳入loader执行程序：此时重新上电或者拔卡亦可重新升级；

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _设备升级常见问题:  

设备升级常见问题
******************************

U盘升级时打开设备失败
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    检查调用升级函数的地方是否在调用了usb_host_mount();

    默认U盘上线时会自动挂载。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

设备升级时升级对应的ufw文件
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    
    v1.0.0 ~ v1.2.0版本(不包含v1.2.0)是设备中的第一个后缀名为 ufw 的文件进行升级。

    v1.2.0（包括v1.2.0版本）后，只有对应的update.ufw文件名才能进行升级。

    用户可自行选择升级文件可更改 update.c 里的 update_file_name 来指定升级对应ufw文件。

    .. image:: update_name.png
        :alt: "升级路径指定"
        :align: center
    .. centered:: 升级路径指定

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

设备升级过程中，在校验ufw文件过程前需要关闭与升级复用功能模块
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    
    在校验数据前，用户需要关闭与 升级复用的功能模块。
    
    用户可注册升级回调来关闭 与 升级复用的功能模块。

    默认该回调会关闭audio 和 adc。

    .. image:: update_cb.png
        :alt: "升级回调注册"
        :align: center
    .. centered:: 升级回调注册

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

设备升级过程中，在校验ufw文件过程中进行复位原因
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    
    1：升级空间不够，需要足够的VM区域。

    2：ufw文件数据不合法，检查ufw文件是否损坏。

    3：升级文件与芯片key不对应。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

设备升级中，只支持FAT32文件系统进行升级
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    
    设备升级只支持FAT32的设备进行升级，否则会在dev_update_check()里判断到文件系统错误直接退出。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

升级过程中保持住IO状态实现
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    请看 ":ref:`升级时如何保持住某个IO状态`" 章节

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

带快速启动进行升级
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    请看 ":ref:`带快速启动进行升级`" 章节