add ota_quick_start document

doc/21.OTA_Quick_Start_based_EVB_MX_Plus.md

@@ -0,0 +1,361 @@
+# 1. TencentOS-tiny OTA
+
+## 1.1. OTA与IAP
+
+IAP全称 In Application Programming，什么是在应用编程呢？
+
+正常开发流程如下：
+
+- 使用Keil MDK工具编写应用程序；
+- 编译出.axf可执行程序或者.bin文件，或者.hex文件；
+- 使用Keil MDK工具直接烧录.axf文件到STM32 Flash中，或者使用类似STM32CubeProg之类的软件烧录.bin文件到STM32 Flash中；
+- 复位，单片机从Flash起始地址处读取程序并执行；
+
+当产品开发完成用于生产后，通常不会再引出下载器接口给用户，所以也就无法连接各种各样的下载器，更别说用Keil或者STM32CubeProg这些工具下载程序，如果发现应用程序有漏洞，或者要修改部分功能，都已经无法完成。
+
+### 1.1.1. IAP设计思想
+
+IAP巧妙的解决了这个问题，即在应用程序正常工作的时候，还可以接收新的固件并烧录到Flash中。
+
+- 应用程序如何接收新的固件？
+
+一般产品设计时都会留一个用于打印日志信息的串口，可以直接利用此串口来接收PC发送到新固件，传输协议大多都采用Y-Modem协议。
+
+- 接收之后的新固件存放到哪里？
+
+固件大小一般都有几十KB或者上百KB，应用程序接收到新的固件之后，如果是以数组的形式暂存在RAM空间中，不仅会浪费RAM空间，而且容易发生固件数据丢失，所以直接存储到空闲的Flash空间中是最好的方式。
+
+eg. 官方开发板使用的芯片是STM32L431RCT6，Flash空间有256KB，如果应用程序的大小只有100KB，那么接收进来的新固件就可以存放在剩余的156KB空间中。
+
+同时会人为的对Flash划分分区，也就是对某一段地址空间起个名字，如下图：
+
+![iap-partition-no-bootloader](image/OTA/iap-partition-no-bootloader.jpg)
+
+- 如何将老固件替换为为新固件？
+
+上电之后CPU会从Flash的起始地址处读取数据开始执行，这点无法改变，正在运行的应用程序如果进行自己擦除自己的操作，设备直接变砖。
+
+bootloader可以完美的解决这一问题，即写一小段应用程序，放在Flash的起始位置处，使得每次上电之后最先运行bootloader，完成两个功能：
+
+- 检查升级标志，是否有新的固件被下载到IAP分区中；
+- 如果无升级标志，则跳转到ActiveAPP分区，开始执行应用程序；
+- 如果有升级标志，则先将IAP分区中的固件拷贝到ActiveAPP分区中，然后跳转到ActiveAPP分区，开始执行新的应用程序；
+
+加入bootloader之后，整个Flash的分区情况如下：
+
+![iap-partition](image/OTA/iap-partition.jpg)
+
+### 1.1.2. OTA设计思想
+
+在IAP的这种设计思想之上，因为当前的物联网设备都已经具备基本的网络通信功能，所以无需通过串口传输新的固件，直接通过网络传输新的固件即可，称之为OTA IAP(Over The Air In Application Programming)，也就是平常所说的空中升级，简称OTA。
+
+## 1.2. OTA组件概述、特性及优势
+
+TencentOS-tiny中提供的OTA组件完全开源免费，相较于其他的OTA功能，TencentOS-tiny OTA组件提供更小的差分升级包，耗用更少的传输流量，占用更小的内存空间，提供更可靠的升级服务。
+
+TencentOS-tiny OTA组件有以下的特性：
+
+- 传输差分升级包，而不是整个固件
+- 灵活的分区表功能
+- 支持原地升级
+- 支持乒乓升级，可以在升级中断的情况下进行版本回滚
+- 支持通过HTTP从自建服务器拉取固件
+- 支持从腾讯云平台进行统一的固件拉取和管理
+
+## 1.3. OTA组件开发调试推荐流程
+
+OTA的整个流程调试较复杂，如果分步来做会比较容易：
+
+(1)调试bootloader是否可以正常读取分区表信息；
+
+(2)调试bootloader是否可以正常跳转到Active APP;
+
+(3)调试bootloader是否直接可以根据patch包进行升级;
+
+(4)调试Active APP是否可以通过网络拉取patch升级包并下载到 OTA 分区;
+
+(5)综合调试。
+
+# 2. 分区规划及分区表的生成、烧录
+
+## 2.1. 分区规划
+
+TencentOS-tiny支持两种升级方式，两种升级方式对应有不同的分区表
+
+原地升级方式中，bootloader直接根据旧固件+patch升级包生成新的固件，一旦开始升级，无论升级成功与否都无法回滚到上一个版本，主要有五个分区：
+
+- Bootloader分区
+- Active APP分区：当前正在运行的固件存放分区；
+- OTA分区：新固件存放分区；
+- KV分区：记录系统升级中的一些环境变量；
+- 分区表：存放分区表（固定大小32B，一般放在Flash的最后一个扇区中）
+
+乒乓升级方式中，bootloader在升级之前会将原来的固件拷贝一份，一旦开始升级，无论新固件升级成功与否，都可以回滚到上一个版本，主要有六个分区：
+
+- Bootloader分区
+- Active APP分区：当前正在运行的固件存放分区；
+- **Backup分区**：备份当前正在运行的固件；
+- OTA分区：新固件存放分区；
+- KV分区：记录系统升级中的一些环境变量；
+- 分区表：存放分区表（固定大小32B，一般放在Flash的最后一个扇区中）
+
+在实际应用中，两种方式的选择要根据设备需求，设备Flash空间大小，设备Flash扇区大小综合考虑。
+
+本文接下来如无特殊说明，都是以第一种方式（原地升级）为例，官方板的Flash大小为256KB，可以如下分区：
+
+![](./image/OTA/ota_partition_ip.jpg)
+
+## 2.2. 分区表工具的使用方法
+
+TencentOS-tiny 源码中提供了一个生成分区表的命令行工具，需要先使用gcc编译，没有gcc环境可以安装MinGW。
+
+### 2.2.1. 编译
+
+进入`\components\ota\tools\partition_table`目录，执行make命令开始编译，编译之后进入到当前目录下的`out\target`即可看到工具 `ptbl.exe`：
+```bash
+cd out/target/ 
+```
+该工具有如下参数：
+
+- `-h`：打印帮助信息
+- `-p <ip/pp>`：选择升级方式,ip或者pp
+- `-a <start,end>`：Active APP分区的起始和结束地址
+- `[-b <start,end>]`：Backup 分区的起始和结束地址，选了pp方式才需要
+- `-o <start,end>`：OTA分区的起始和结束地址
+- `-k <start,end>`：KV分区的起始和结束地址
+- `-v <major>.<minor>`：初识固件版本号
+
+为官方板生成分区表文件的命令如下：
+```bash
+./ptbl.exe -p ip -a 0x08007800,0x0802D000 -o 0x0802D000,0x08039800 -k 0x08039800,0x0803F800 -v 0.1 ptbl.bin
+```
+运行之后即可在当前目录下看到生成的分区表文件`ptbl.bin`。
+
+## 2.3. 分区表烧录方法
+
+生成的分区表文件`ptbl.bin`可以通过STM32CubeProg直接烧录到Flash中，按照之前规划的分区，烧录位置为 0x0803F800 ，烧录方法如下：
+
+(1)使用下载器连接开发板到PC，打开STM32CubeProg工具，点击Connect连接到开发板：
+
+![stm32cubeprog_01](./image/OTA/stm32cubeprog_01.jpg)
+
+(2)如果是**第一次使用OTA**，点击左侧的烧录按钮，点击全片擦除：
+
+![stm32cubeprog_02](./image/OTA/stm32cubeprog_02.jpg)
+
+>第一次使用的时候，KV分区中的数据不确定，可靠起见直接选择全片擦除。
+
+(3)点击左侧的烧录按钮，选择刚刚生成的`ptbl.bin`，下载地址填写 0x0803F800，点击烧录：
+
+![stm32cubeprog_03](./image/OTA/stm32cubeprog_03.jpg)
+
+出现烧录成功弹窗即可。
+
+# 3. 测试Bootloader程序
+
+进入`board\TencentOS_tiny_EVB_MX_Plus\KEIL\ota`目录，打开官方提供的bootloader示例工程：`ota_bootloader_recovery`。
+
+bootloader其实是一个裸机程序，在 main 函数中主要有三部分，分别对应三个功能：
+
+- 读取分区表
+- 根据patch包进行升级
+- 跳转到Active APP分区开始执行
+
+接下来将完成 1.3 节所给出的OTA组件开发调试推荐流程前三步。
+
+## 3.1. 测试bootloader是否可以读取分区表
+
+首先需要指定分区表地址：
+```c
+uint32_t partition_addr = 0x0803f800;
+```
+
+完善初始化环境变量的代码，在初始化之后手动添加打印分区表的代码，最后的while(1)用于停止程序，防止进行后面的功能：
+```c
+    if ((ret = ota_env_init(OTA_UPDATE_IN_POSITION, partition_addr, &stm32l4_norflash_onchip_drv_ota, &stm32l4_norflash_onchip_prop_ota)) != OTA_ERR_NONE) {
+        printf("env init failed!OTA errcode = %d\n", ret);
+        return -1;
+    } else {
+		printf("env init successfully!\r\n");
+		printf("+-------------------------+\r\n");
+		printf("|Active APP |  0x%08x |\r\n", ota_partition_start(OTA_PARTITION_ACTIVE_APP));
+		printf("|   OTA     |  0x%08x |\r\n", ota_partition_start(OTA_PARTITION_OTA));
+		printf("|   KV      |  0x%08x |\r\n", ota_partition_start(OTA_PARTITION_KV));
+		printf("| Version   |      %d.%d    |\r\n", ota_partition_init_version_get().major, ota_partition_init_version_get().minor);
+		printf("+-------------------------+");
+	}
+		
+	while(1);
+```
+修改程序编译地址和大小，与Bootloader分区的划分相对应：
+
+![](./image/OTA/bootloader_option.jpg)
+
+编译程序。
+
+编译成功之后修改下载设置，选择扇区擦除方式、设置程序烧录起始地址、设置程序烧录大小，同样与bootloader分区的划分相对应：
+
+![](./image/OTA/bootloader_prog_option.jpg)
+
+下载程序，在串口助手中观察输出：
+
+![](./image/OTA/bootload_partition_read_result.jpg)
+
+## 3.2. 测试bootloader是否可以跳转到Active APP分区
+
+打开和bootloader在一个目录下的app工程：`ota_application_download_through_http`。
+
+目前我们只是测试bootloader是否可以跳转过来执行此程序，所以如图所示修改代码，不要触发OTA固件拉取功能：
+
+![](./image/OTA/app_mofidy.jpg)
+
+另外，因为此程序被烧录到 Active APP 分区，是从Active APP分区的起始地址开始运行的，所以需要修改中断向量表的偏移地址，如图：
+
+![](./image/OTA/app_mofidy_2.jpg)
+
+同样修改程序编译的起始地址和大小，与规划的 Active APP分区信息相对应：
+
+![](./image/OTA/actice_app_option.jpg)
+
+编译程序。
+
+编译成功之后修改下载设置，烧录到Actice APP分区中：
+
+![](./image/OTA/actice_app_prog_option.jpg)
+
+最后再修改bootloader程序，屏蔽while(1)，屏蔽OTA固件升级功能，开启跳转功能：
+
+![](./image/OTA/bootloader_modify.jpg)
+
+再次编译，下载bootloader，复位开发板，查看串口助手中的输出，可以看到bootloader成功跳转到Actice APP开始执行：
+
+![](./image/OTA/bootload_jump_result.jpg)
+
+## 3.3. 差分patch包生成方法
+
+### 3.3.1. 准备老固件和新固件
+
+官方示例工程已经在MDK中配置编译后生成.bin固件，如图：
+
+![](./image/OTA/actice_app_bin_option.jpg)
+
+编译之后会在工程目录下生成TencentOS_tiny.bin文件，拷贝一份出来，重命名为:TencentOS_tiny_0_1.bin，表示这是0.1版本的固件。
+
+修改app工程，将打印信息中的0.1改为0.2，以验证是否升级成功：
+
+![](./image/OTA/actice_app_0_2_option.jpg)
+
+重新编译，生成新固件TencentOS_tiny.bin，同样拷贝一份，重命名为：TencentOS_tiny_0_2，表示这是0.2版本的固件。
+
+### 3.3.2. 差分升级包生成工具的使用
+
+>编译此工具同样需要gcc环境。
+
+进入`\components\ota\tools\diff`目录，执行make命令开始编译，编译之后进入到当前目录下的`out\target`即可看到工具 `diff.exe`：
+```bash
+cd out/target/ 
+```
+该工具有如下参数：
+
+- `-h`：打印帮助信息
+- `-v`：打印更多信息
+- `-s`：<待定...>
+- `-b <n>`：指定扇区大小，单位：字节Byte
+- `-n <major>.<minor>`：新的固件版本号
+- `-o <major>.<minor>`：旧的固件版本号
+
+将3.3.1节准备的两个固件拷贝到当前工具所在目录下。
+
+根据前面准备的两个新旧固件，制作差分升级包的命令如下：
+```bash
+./diff.exe -v -b 2048 -n 0.2 -o 0.1 TencentOS_tiny_0_1.bin TencentOS_tiny_0_2.bin patch.bin
+```
+运行之后即可在当前目录下看到生成的差分升级包`patch.bin`。
+
+## 3.4. 测试bootloader是否可以根据patch进行升级
+
+使用STM32CubeProg直接将差分升级包patch.bin下载到OTA分区：
+
+![](./image/OTA/patch_prog.jpg)
+
+下载成功后，因为bootloader通过检测KV分区中的环境变量new_version来判断是否有新的固件，但是环境变量在app程序拉取固件成功之后才会设置，所以我们手动在bootloader中来设置此环境变量。
+
+在main.c中引入KV的头文件：
+```c
+#include "tos_kv.h" 
+```
+
+在环境变量初始化代码之后，升级代码之前添加如下的代码：
+```c
+ota_img_vs_t new_version;
+new_version.major = 0;
+new_version.minor = 2;
+
+tos_kv_set("new_version", &new_version, sizeof(ota_img_vs_t));
+```
+
+添加之后编译，下载，在串口助手中查看输出：
+
+![](./image/OTA/bootload_recovery_result.jpg)
+
+可以看到bootloader成功根据patch差分包和旧的固件，还原出了新的固件并成功升级。
+
+# 4. 使用HTTP方式获取固件并升级
+
+TencentOS-tiny OTA组件支持使用 HTTP 协议拉取差分升级patch包，并烧写到OTA分区中。
+
+## 4.1. 准备HTTP服务器
+
+HTTP服务器的选择非常多，常用选择有：
+
+- 在Windows上使用类似MyWebServer的小工具开启HTTP服务
+  - 优点：简单方便，用于测试
+  - 缺点：无公网ip，只能在同一个局域网内被访问
+
+![](./image/OTA/my_webserver.jpg)
+
+- 在云服务器上安装类似Nginx的工具，开启HTTP访问
+  - 优点：性能强劲、有公网ip、支持高并发（大量设备同时开机拉取固件）
+  - 缺点：安装过程较复杂
+
+
+除了这两种方式外，还有很多的方式可供选择，只需要开启HTTP服务即可，本文中我使用第一种方式。
+
+开启之后将第3步中生成的差分升级固件 patch.bin 上传/复制到HTTP服务目录中，然后使用浏览器访问`http://<已经开启HTTP服务PC的ip>:<HTTP服务端口>/patch.bin`，测试正常获取之后方可进行后续操作。
+
+>开启HTTP服务之后记得关闭各种防火墙，比如Win10网络防火墙，云服务器安全组等。
+
+## 4.2. HTTP获取固件并升级
+
+(1)使用STM32CubeMX Prog全片擦除，烧写分区表到0x0803f800;
+
+(2)修改bootloader程序，去除手动设置new_version环境变量代码，编译，下载，**不要复位**:
+
+![](./image/OTA/ota_bootloader_modify.jpg)
+
+(3)修改Actice APP工程(`ota_application_download_through_http`)，开启HTTP固件拉取和升级功能:
+
+![](./image/OTA/ota_active_app_modify.jpg)
+
+![](./image/OTA/ota_active_app_netinfo_modify.jpg)
+
+修改之后编译，下载。
+
+特别注意，**此时0.1版本的程序已经被我们修改，所以之前生成的patch包无法完成升级**，重新在0.1版本的基础上修改处0.2版本的程序，并制作patch包。
+
+重复一遍之前的制作流程即可：
+
+- ① 将当前固件拷贝出来，重命名为`TencentOS_tiny_0_1.bin`;
+- ② 修改打印提示，表示这是0.2版本的程序：
+
+```c
+printf("do sth(v0.2)...\n");
+```
+
+- ③ 将新固件拷贝出来命名为`TencentOS_tiny_0_2.bin`;
+- ④ 使用diff命令行工具或者可视化工具制作差分升级包patch.bin；
+- ⑤ 将制作出的差分升级包拷贝/上传到HTTP服务器目录；
+
+此时，一切准备就绪，复位设备，即可在串口助手中看到OTA的升级状况：
+
+![](./image/OTA/ota_http_result.jpg)