面對成千上萬的終端設(shè)備，如何低成本完成版本迭代？FOTA是答案。本文聚焦LuatOS平臺的遠程升級能力，以極簡語言和清晰步驟，帶你走過從創(chuàng)建項目、獲取校驗碼到設(shè)備重啟升級的全過程，真正實現(xiàn)“極速上手”。

一、Flash 分區(qū)與 FOTA 分區(qū)簡介

大家好，在開始動手操作 FOTA 之前，我們必須先了解它的“工作場地”——模組內(nèi)部的 Flash 存儲器。這就像裝修房子前，一定要先看懂戶型圖。

不同型號的模組，F(xiàn)lash 分區(qū)就像不同的“戶型”，格局各異，但都有一個核心設(shè)計：必須有一個獨立的“系統(tǒng)升級專用間”，也就是 FOTA 分區(qū)。

今天，我們就以 Air780EHM 為例，來詳細解讀這份關(guān)鍵的“Flash 戶型圖”。

首先，我們看全局。Air780EHM 的 Flash 是一棟總?cè)萘?8MB 的“大樓”。但這里有個精妙的設(shè)計：這棟樓有兩個門牌號系統(tǒng)。

物理地址（0x0 – 8MB）：這是 Flash 芯片真實的“磚塊地址”，用于存儲所有數(shù)據(jù)。

XIP 映射地址（8MB – 16MB）：CPU 執(zhí)行代碼時“看到”的地址。系統(tǒng)固件被“映射”到這個區(qū)域，CPU 可以直接讀取執(zhí)行，這叫 XIP（就地執(zhí)行）。

簡單來說，固件實體存放在物理地址的低 8MB，而當 CPU 要運行時，它“看到”的是從 8MB 開始的那段地址。

大家可以看到，flash 中分區(qū)很多，但作為 LuatOS 開發(fā)者，我們主要關(guān)注其中四個“房間”：ap+cp image 分區(qū)（包含腳本代碼區(qū)）、LFS 分區(qū)、KV 分區(qū)和 FOTA 分區(qū)

1.1 ap+cp image 分區(qū)– “主系統(tǒng)套房”：

作用 ：這是設(shè)備的操作系統(tǒng)和核心應(yīng)用所在，相當于電腦的 C 盤。它包含了底層 C 固件、Lua 虛擬機，以及最重要的——腳本區(qū)。

腳本區(qū)：這是我們 Lua 代碼的“家”。代碼在這里擁有持久化特性，只有固件升級時才會被整體更新。它的大小在編譯時就已經(jīng)固定，不同固件版本會有差異，

腳本區(qū)大小會根據(jù)模組型號不同，固件編號不同也會有差別，大小在編譯時固定

1.2 LFS 分區(qū)– “用戶資料室” ：

作用：提供一個小型文件系統(tǒng)，用于存儲用戶數(shù)據(jù)和配置。

特點：具有持久化存儲，斷電不丟失 、可動態(tài)寫入和讀取、支持文件系統(tǒng) API 訪問、可隨時創(chuàng)建和刪除的特性。可以用來儲存用戶配置文件、設(shè)備運行日志、網(wǎng)絡(luò)配置信息、臨時數(shù)據(jù)和緩存、用戶生成的文件。

文件系統(tǒng)空間大小會根據(jù)模組型號不同，固件編號不同也會有差別，實際大小= 基礎(chǔ) lfs 空間 + 附件空間。

附加空間通常是去掉某些功能所節(jié)省出來的空間，所以有了不同編號的固件，來實現(xiàn)不同功能 + 大內(nèi)存的需求。

1.3 KV 分區(qū)– “配置存儲間”：

作用：KV（Key-Value）分區(qū)是一個小型的鍵值對存儲區(qū)域，用于保存設(shè)備的配置信息和狀態(tài)數(shù)據(jù)。

特點：

持久化存儲：斷電后數(shù)據(jù)不丟失

高效訪問：支持快速的鍵值對讀寫操作

固定大小：通常為 64KB

輕量級：適合存儲少量關(guān)鍵配置，如網(wǎng)絡(luò)參數(shù)、設(shè)備 ID、運行狀態(tài)等

KV 分區(qū)的典型用途：

存儲設(shè)備唯一標識符

保存網(wǎng)絡(luò)連接參數(shù)（APN、服務(wù)器地址等）

記錄設(shè)備運行狀態(tài)和統(tǒng)計信息

存儲用戶自定義配置

保存升級狀態(tài)和版本信息

1.4 FOTA 分區(qū)“系統(tǒng)升級專用間”：

1.4.1 分區(qū)介紹

作用 ：這是今天的主角，用于臨時存放固件升級包，實現(xiàn)安全、隔離的遠程升級。

fota 分區(qū)具有以下特性：

1、獨立空間 ：與其他分區(qū)嚴格分離，確保升級安全，從網(wǎng)絡(luò)或其他渠道下載的完整固件包或差分包先存儲到 FOTA 分區(qū)

2、安全機制 ：支持升級包完整性校驗和簽名驗證，升級包寫入 FOTA 分區(qū)后會進行 MD5 校驗，確保傳輸未損壞

FOTA 升級的核心安全規(guī)則：為什么“戶型”要對齊？

這里有一個至關(guān)重要的安全限制，可以通過下面這個表格來了解：

通過上面表格可以看出，雖然兩個固件的 FOTA 分區(qū)大小完全一樣，但它們的 fota 分區(qū)、ap+cp 分區(qū)和 LFS 分區(qū)的起始、結(jié)束地址發(fā)生了偏移。

結(jié)論：使用錯誤編號的固件包升級時，其設(shè)計的分區(qū)地址與設(shè)備當前分區(qū)布局不匹配。FOTA 機制會在升級包寫入前校驗升級包，將會檢查出完整性異常，并返回升級失敗。

所以會有一個鐵律：不同編號的固件之間不能進行 fota 升級，F(xiàn)OTA 差分升級只能在相同編號的固件版本之間進行。 既編號 1 固件只能差分升級為新版本的編號 1 固件，編號 2 固件只能差分升級為新版本的編號 2 固件。在制作升級包時，務(wù)必首先確認這個編號匹配關(guān)系。

如果不同編號固件間升級 ：需要使用完整包重新燒錄，不能使用 fota 升級

雖然這個房間總大小 1048KB，但是 fota 升級包大小并不等于 fota 分區(qū)空間大小。

在不同編號的固件版本規(guī)劃中，為了容納不同的功能，其整個 Flash 的分區(qū)表布局（包括 FOTA、AP、CP、LFS 等分區(qū)的起始地址和大小）是預(yù)先定義好且固定的。因此，不同編號的固件，其 FOTA 分區(qū)大小可能相同也可能不同，但更關(guān)鍵的是其在整個 Flash 中的"位置"（地址）不同。所以具體 fota 分區(qū)大小可以看 1.5 章節(jié)具體表格。

1.4.2 升級流程

初始化 FOTA → 下載升級包 → 寫入 FOTA 分區(qū) → MD5 校驗 → 設(shè)置升級標志 → 重啟

重啟后：Bootloader 檢查升級標志 → 驗證升級包 → 寫入目標分區(qū) → 啟動新固件 → 驗證新固件

1、升級包寫入流程：

初始化 FOTA 模塊： 創(chuàng)建升級上下文結(jié)構(gòu)體，分配必要的緩沖區(qū)和資源，為升級流程做準備。

下載升級包：

通過 HTTP、MQTT 或 UART 等通信協(xié)議從服務(wù)器或本地下載升級包數(shù)據(jù)。支持下載到文件系統(tǒng)，或者直接分包寫入 fota 分區(qū)。

寫入 FOTA 分區(qū)：

如果是下載到文件系統(tǒng)中暫存，待整個升級包在文件系統(tǒng)中下載完成后，再一次性從文件系統(tǒng)讀取并寫入到專用的 FOTA 分區(qū)。

也可以實時分包接收升級包數(shù)據(jù)并寫入到文件系統(tǒng)中。

完成寫入，驗證升級包：

執(zhí)行升級包的完整性校驗（MD5）

若校驗通過，則在特定位置中設(shè)置升級標志，并重啟系統(tǒng)。Bootloader 下次啟動時執(zhí)行升級。

若校驗失敗，則報告錯誤并終止升級流程。

2、重啟后升級流程：

設(shè)備上電，執(zhí)行 Bootloader

設(shè)備重啟后，Bootloader 首先檢查是否存在有效的升級標志。

驗證與執(zhí)行升級 若無升級標志：Bootloader 跳過升級流程，直接啟動現(xiàn)有固件。 若存在升級標志：

1.5 各模組 fota 分區(qū)空間

在實際使用中，不同的固件版本或型號為了支持不同的功能，會調(diào)整 FOTA 分區(qū)內(nèi)的大小，因此用戶實際可用的升級空間可查看下表。

Air7xx 系列模組 LuatOS 多固件版本

Air8000 系列固件版本

二、soc 軟件包文件分析

“理解了 FOTA 的‘工作場地’（Flash 分區(qū)），接下來一個很自然的問題是：我們要通過網(wǎng)絡(luò)下載并寫入這個場地的‘升級包’，它到底是什么？

這個核心的升級包就是 .soc 文件。它不是一個普通的固件，而是合宙定義的標準化容器。在 FOTA 流程中，它扮演著三個關(guān)鍵角色：

它是差分的藍本：我們下一章要講的‘差分升級’，其核心就是對比新舊兩個版本的.soc 文件，生成差異部分。

它攜帶了分區(qū)地圖：.soc 包內(nèi)的info.json配置文件，明確寫明了本固件的編號、分區(qū)地址等信息，這是 FOTA 進行安全校驗（防止變磚）的核心依據(jù)。

它統(tǒng)一了操作對象：無論底層是移芯還是展銳芯片，最終都封裝成統(tǒng)一的.soc 格式，讓升級工具和流程得以標準化。

所以，拆解.soc 文件，就是理解 FOTA 操作對象和實現(xiàn)原理的基礎(chǔ)。明白了它里面有什么，你才能徹底搞懂后續(xù)的差分生成和升級執(zhí)行究竟在操作什么。”

下面講解一下模組所用固件包.soc 文件的組成以及格式相關(guān)內(nèi)容。

2.1 soc 簡介

.soc 文件，是我們在 2021 年自定義的一個文件，該文件， 用于用一種通用的格式，保存不同型號模組的固件。

該文件格式的優(yōu)點是可以屏蔽模組差異， 對用戶通用， 對Luatools 通用；

缺點是，當前的 IOT 升級后臺尚且無法支持這個格式。

對于遠程升級來說， 必須用 Luatools 內(nèi)置的差分包制作工具， 輸入兩個不同版本的 soc文件， 生成一個.bin 結(jié)尾的差分包，才能上傳到 IOT 后臺進行遠程升級。

LuatOS 將來會適配非常多的 SoC/MCU 芯片來設(shè)計模組, 而各種模組的刷機格式各不相同,有必要定義一個統(tǒng)一的對外格式。

這里稱之為 soc 格式, 后綴選定為 soc, 實際內(nèi)容為 info.json 及多個固件文件的壓縮包。

2.2 SoC 組成部分

[必選]包含的文件 info.json

[可選]腳本數(shù)據(jù)存儲文件 script.bin, 使用 LuaDB v2 格式存儲

[必選]原始固件,以不同 SoC 芯片為準

2.2.1 info.json 的內(nèi)容

info.json 是固件配置文件，包含固件的詳細參數(shù)和配置信息。以 780EHM 的 2018 版本 1 號固件解壓后打開 info.json，具體包含如下參數(shù)：

2.2.2 腳本數(shù)據(jù)文件 script.bin

在給出的底層固件中并不包含此文件，此文件是在 luatools 工具點擊生成量產(chǎn)文件后所生成的。是 Lua 腳本的二進制文件，包含了用戶編寫的應(yīng)用程序代碼。文件格式為 LuaDB 格式存儲。

LuaDB 并非數(shù)據(jù)庫, 而是一種用于 LuatOS 固件的文件打包格式.

其作用相當于一個只讀文件系統(tǒng).

2.2.3 原始固件

原始固件是構(gòu)成 .soc 文件的核心數(shù)據(jù)部分，指由芯片原廠（如展銳、移芯）提供的底層系統(tǒng)映像文件。其格式依芯片平臺而定，常見后綴包括 .pac、.binpkg、.fls、.img 等。該固件包含了操作系統(tǒng)內(nèi)核、基礎(chǔ)驅(qū)動、通信協(xié)議棧等核心代碼，是設(shè)備功能運行的基石。

在 .soc 文件體系中，info.json 配置文件內(nèi)的 "rom" -> "file" 字段即指明了所包含的原始固件文件名（例如 "luatos.binpkg"）。該文件與 info.json、可選的 script.bin 一同被打包壓縮，最終形成統(tǒng)一的 .soc 分發(fā)文件。

展銳平臺：

展銳平臺的 4G 模組，當前我們用的是 8910 平臺，典型模組是Air724UG，編譯之后的文件后綴為 PAC， 可以用展銳提供的upgrade 固件燒錄工具燒錄，也可以用 Luatools 燒錄。

移芯平臺：

移芯平臺的 4G 模組，我們用的有 EC718、EC618、716 等。典型模組是 Air780EXX 系列、Air8000 系列。

移芯平臺編譯出來的固件，都是 binpkg 后綴結(jié)尾的固件，可以用移芯提供的 flashtool 工具燒錄，也可以用 Luatools 燒錄。

對于最終用戶和開發(fā)者而言，無論底層原始固件格式如何，均推薦使用 Luatools 配合 .soc 文件進行下載和升級。

所以，.soc文件的核心就在于，用一個外層的標準化包裝，封裝了內(nèi)部不同平臺的原生固件，讓用戶和工具都能用同一種方式處理它們。

2.3 soc 實際文件分析

soc 解壓后實際文件在不同的模組中也不盡相同，但是都是 info.json+ 原始固件 + 輔助文件 + 腳本數(shù)據(jù)文件組成。

下面以移芯系列固件為例：將 .soc 壓后會得到 7 個核心文件： comdb.txt 、 info.json 、 luat_conf_bsp.h 、 luatos.binpkg 、 luatos.elf 、 luatos_debug.map 、 mem_map.txt 。而使用 Luatools 生成量產(chǎn)文件后，還會多出兩個文件： core.binpkg 和 script.bin 。

這些文件各司其職，共同構(gòu)成了一個完整的固件系統(tǒng)。接下來，我們逐個分析它們的作用。

還是以 780ehm 為例，看下它的固件 soc 解壓后都有哪些文件：

info.json

第一個要介紹的是 info.json ，這是固件的核心配置文件，相當于固件的"身份證"。

這個文件主要包含有：

芯片類型（

ROM 文件信息及下載地址

腳本文件信息及下載地址

分區(qū)表配置

下載參數(shù)（波特率、強制波特率等）

luatos.binpkg

LuatOS 的核心二進制固件包，包含了系統(tǒng)運行所需的所有核心代碼。

.binpkg 為移芯系列芯片所生成的原始固件內(nèi)容，是移芯芯片特有的格式，不同的芯片會有不同的原始固件格式

其他輔助文件

mem_map.txt：這是設(shè)備內(nèi)存的"地圖"，內(nèi)存映射配置文件，定義了設(shè)備內(nèi)存的分區(qū)結(jié)構(gòu)和地址范圍。

luat_conf_bsp.h ：支持功能配置頭文件，定義了一些功能相關(guān)的配置宏，比如引腳定義、外設(shè)配置等。

luatos.elf ：包含完整調(diào)試信息的可執(zhí)行文件，開發(fā)通常用不到，出現(xiàn) ramdump 死機的時候用于解析死機日志時使用。

luatos_debug.map ：調(diào)試映射文件，記錄了函數(shù)和變量在內(nèi)存中的地址。

comdb.txt ：組件數(shù)據(jù)庫文件，記錄了固件中包含的各種組件信息，使用 EPAT 抓取日志時需要。

在 luatools 上點擊生成量產(chǎn)文件后，量產(chǎn)文件也是一個 soc 文件，解壓后除了上述內(nèi)容外還會多出兩個文件：core.binpkg、script.bin

core.binpkg ：核心固件包，包含了系統(tǒng)的核心功能。

script.bin ：Lua 腳本的二進制文件，包含了用戶編寫的應(yīng)用程序代碼。這是一個非常重要的文件，它支持單獨更新腳本，無需重新下載完整固件。

總的來說，.soc 文件就是一個集配置文件、核心固件、用戶腳本于一體的標準化容器。它解決了多平臺統(tǒng)一管理的問題，并通過 info.json 實現(xiàn)精細控制，實現(xiàn)固件燒錄、差分升級等功能。為后續(xù)的差分升級打下了堅實的基礎(chǔ)。那么，如何利用兩個不同版本的.soc 文件，生成一個體積小巧的升級包呢？這就是我們接下來要揭秘的——差分升級的奧秘

三、差分包生成原理以及差分升級原理

3.1 差分升級的基本概念

在 FOTA（無線固件升級）中，升級方式主要分為兩種：整包升級和差分升級。

整包升級：指將完整的新版本固件包全部下載至設(shè)備，并完全覆蓋設(shè)備上現(xiàn)有的舊版本固件。其過程直接，但數(shù)據(jù)量大。

差分升級：是一種增量更新技術(shù)。其核心在于，設(shè)備無需下載完整的新固件包，而是僅下載新舊兩個固件版本之間的差異部分（即“差分包”）。設(shè)備在本地利用此差分包與自身已有的舊版本固件進行合并，從而生成完整的新版本固件。

一個生動的比喻是：你手中有一本舊版的書籍，出版社發(fā)布了修訂版，但實際內(nèi)容只更改了其中的 30 頁。此時，你無需購買整本新書，只需獲取這 30 頁的修訂頁，并替換舊書中對應(yīng)的頁面即可。差分升級正是這一高效思路在固件更新上的體現(xiàn)。

傳統(tǒng)整包升級的痛點：

升級包體積大：消耗大量網(wǎng)絡(luò)帶寬與設(shè)備存儲空間。

升級耗時長：下載時間長，升級過程慢，影響用戶體驗。

流量成本高：對于部署量龐大的物聯(lián)網(wǎng)設(shè)備群，升級產(chǎn)生的總流量成本非常顯著。

差分升級的顯著優(yōu)勢：

體積極小：差分包通常僅為完整新固件包的 10%-30%，甚至更低。

速度極快：下載時間大幅縮短，升級效率顯著提升。

可靠性更高：傳輸數(shù)據(jù)量小，在弱網(wǎng)環(huán)境下傳輸失敗或出錯的概率降低。

成本大幅節(jié)省：在海量設(shè)備升級場景下，能節(jié)省可觀的流量費用與服務(wù)器帶寬成本。

3.2 差分升級原理：只傳"差異"，不傳"全部"

差分升級的技術(shù)本質(zhì)可概括為 “計算差異、傳輸差異、應(yīng)用差異”。其核心在于通過算法比對，僅處理和傳輸發(fā)生變化的數(shù)據(jù)塊，而非整個文件。

具體來說，在升級前，會使用專門的算法工具(luatools)，對舊固件（V1）和新固件（V2）的二進制內(nèi)容進行深度比對，精確找出所有被修改、新增或刪除的數(shù)據(jù)塊。然后，只將這些“差異”信息，打包成一個結(jié)構(gòu)化的差分包（Δ）。設(shè)備獲取這個小包后，在本地執(zhí)行反向操作，根據(jù)包內(nèi)的指引，將差異應(yīng)用到自身的 V1 版本上，從而重構(gòu)出 V2。

1. 差分包生成原理

差分升級的核心是 差異比較算法 ，常用的有：

BSDiff ：基于后綴排序的高效差異算法

HDiffPatch ：高性能的差異比較庫

Rsync 算法 ：用于網(wǎng)絡(luò)傳輸?shù)牟町愃惴?/p>

我們的 Luatools 等工具就集成了這類算法，能夠智能地比較兩個.soc 文件或原始固件，生成最優(yōu)的差分包。

2. 差分包的組成

一個標準的差分包（通常為.bin 文件）是一個精心設(shè)計的數(shù)據(jù)包，通常包含：：

差異數(shù)據(jù) ：新舊固件的二進制差異

元信息 ：版本號、校驗值、生成時間

合并指令 ：指導設(shè)備如何合并生成新固件

校驗機制 ：確保差分包完整性和安全性

3. 差分升級的工作流程

下面看一下差分升級的工作流程，具體流程如下：

流程詳解：

1、生成階段：在 luatools 上，指定新舊版本 V1 和 V2，生成一個包含合并指令和差異數(shù)據(jù)的差分包（Δ）。

2、傳輸階段：這個極小的差分包通過蜂窩網(wǎng)絡(luò)、以太網(wǎng)、藍牙、Wi-Fi 或本地串口等渠道，高效地下發(fā)到設(shè)備。

3、應(yīng)用階段：設(shè)備端在設(shè)備的固件升級功能模塊控制下，完成差分包校驗、新固件合并寫入與最終驗證后，重啟切換至新版本固件完成升級的過程。

四、單腳本升級以及 core+ 腳本升級 升級包制作

4.1 LuatOS 開發(fā)結(jié)構(gòu)

LuatOS 二次開發(fā)由兩部分組成：

Core 部分：既底層固件，底層 C 代碼編譯的二進制固件，包含操作系統(tǒng)內(nèi)核、驅(qū)動、基礎(chǔ)庫，文件較大，更新頻率較低。

Script 部分：上層 Lua 應(yīng)用腳本，包含業(yè)務(wù)邏輯、基礎(chǔ)配置、應(yīng)用功能等，文件較小，更新頻率較高。。

在設(shè)備使用過程中，升級的時候通常會碰到三種情況，一種是單腳本需要升級，一種是腳本 + 固件都需要升級。

在 4G 相關(guān)的模組中，比如 Air780Exx 系列、Air8000 系列模組中

單腳本升級時為全量升級，含 core 升級時為差分升級。

在 wifi 模組 Air8101 和 Air8101A 中

單腳本升級和含 core 升級都為全量升級

4.2 單腳本升級

4.2.1 為什么腳本升級使用全量模式？

單腳本升級采用全量升級模式，原因有三：

大小因素：腳本文件本身就很小，一般幾十到幾百 KB，即使全量傳輸消耗的流量和帶寬也很有限，差分計算帶來的收益不明顯。

變更模式：腳本更新頻繁，且可能完全重寫邏輯，相鄰版本之間可能沒有明顯的"差異"，而是完全不同的實現(xiàn)，這種情況下差分效果差。

實現(xiàn)復雜度：全量升級實現(xiàn)簡單，直接覆蓋文件即可，無需復雜的差分生成和合并算法，開發(fā)成本低。

4.2.2 單腳本升級升級包制作

在 luatools 中點擊生成量產(chǎn)文件，在生成的量產(chǎn)文件夾中，對應(yīng)的.bin 后綴的就是單腳本升級的升級包。

4.2.3 實際應(yīng)用場景

場景 1：快速迭代開發(fā)

在開發(fā)階段，業(yè)務(wù)邏輯頻繁調(diào)整，每次修改后直接全量更新腳本，簡單快捷。

場景 2：配置文件更新

當需要修改服務(wù)器地址、端口號、超時時間等配置參數(shù)時，直接替換整個配置文件即可。

4.2.4 工作流程

開發(fā)者編寫新腳本 → 打包為升級文件 → 通過 FOTA 平臺下發(fā) → 設(shè)備接收并覆蓋舊腳本 → 重啟后生效。

整個過程簡單直接，適合高頻次的業(yè)務(wù)邏輯更新。

4.3 含 core 升級

4.3.1 為什么必須用差分升級？

含 core 升級必須使用差分模式，主要原因如下：

1、文件大小因素：Core 固件通常很大（512KB~2MB+），全量傳輸消耗大量流量和時間。差分可以顯著減少傳輸數(shù)據(jù)量，通常減少 90% 以上。

2、變更模式特點：Core 固件更新頻率低，相鄰版本變化小，主要是 bug 修復和功能增強，大部分代碼不變，適合差分算法。

3、技術(shù)必要性：嵌入式設(shè)備存儲空間有限，無法同時存儲兩個完整固件；fota 分區(qū)通常比較小。

4.3.2 含 core 升級升級包制作

對于含 core 升級的話需要制作差分包，原始版本生成一次量產(chǎn)文件，新版本生成一次量產(chǎn)文件。

針對這兩個量產(chǎn)文件，制作一個差分文件，點擊到 luatools 的主界面，依次點擊圖中藍框所示意的地方(注：必須使用 luatools_3.0.9 及其以上版本，要不差分包升級的時候可能會出問題)

按下圖所示選擇低版本以及高版本的固件，然后點擊開始執(zhí)行即可，如果不想輸出的差分包在 luatools 根目錄下，可以自行選擇一個輸出路徑

在你選擇的目錄下看到如下所示，.bin 文件就是升級差分包。

4.3.3 Core 固件的變更特點

Core 固件的更新通常是增量式的：修復一個 bug、優(yōu)化某個驅(qū)動、增加一個小功能。比如 V1.0.0 到 V1.0.1，可能只是修復了網(wǎng)絡(luò)連接中的一個空指針異常，99% 的代碼都沒有變化。這種場景下，差分升級只需傳輸那 1% 的變化部分，效率極高。

4.3.4 含 core 升級各芯片差異

4G 模組：

移芯系列模組：780Exx 系列、8000 系列等用移芯芯片的模組，含 core 升級為差分升級，需要手動差分

展銳系列模組：724UG 系列、722UG 系列、795UG 等用展銳芯片的模組，含 core 升級為差分升級，不過如果使用的是我們 iot 平臺的話，可以上傳新版本的量產(chǎn)文件，差分過程可在服務(wù)器后臺自動進行，但是如果是第三方服務(wù)器升級需要手動差分，把差分包上傳到自己服務(wù)器中。

特殊情況：wifi 模組 8101 和 8101A，由于芯片不支持差分升級，單腳本升級或 core+ 腳本升級時都為全量升級。在 luatools 生成全量文件的時候，在指定目錄下會有兩個文件 full_fota 和 script_ota。full_fota 中為 core+ 腳本 升級的升級包，script_ota 中為單腳本的升級包。

4.4 升級類型對 Flash 分區(qū)影響與二次開發(fā)關(guān)系總結(jié)

4.4.1 升級類型對 Flash 分區(qū)的影響

4.4.2 各分區(qū)與二次開發(fā)的關(guān)系

4.4.3 升級包特點

單腳本升級：文件小，更新頻繁，直接生成.bin 文件

含 core 升級：文件大，更新頻率低，4G 模組需制作差分包，WiFi 模組為全量包

五、fota 升級相關(guān) api 簡介（libfota2 擴展庫和 fota 核心庫）

在 luatos 中，升級一般是有兩組接口都能實現(xiàn) fota 功能，分別是 libfota2 擴展庫和 fota 核心庫

5.1 libfota2 擴展庫與 fota 核心庫 如何選擇

5.1.1 核心區(qū)別總結(jié)

fota（底層核心庫）

定位： 基礎(chǔ)升級，提供最核心的固件寫入能力

核心能力：

支持兩種寫入方式：fota.run() 分段寫入 和 fota.file() 文件直接升級

支持內(nèi)部存儲和外部 SPI Flash

提供完整的升級流程控制：init → run/file → isDone → finish

fota2（libfota2 擴展庫）

定位： 完整的遠程升級解決方案，開箱即用

核心能力：

自動處理 HTTP/HTTPS 網(wǎng)絡(luò)下載

支持 IoT 平臺和自建服務(wù)器

內(nèi)置版本檢查、下載、驗證全流程

提供詳細錯誤碼和回調(diào)函數(shù)

代碼特點：

5.1.2 適用場景推薦

1、選擇 fota 的情況：

需要自定義升級數(shù)據(jù)源

通過串口接收升級包

通過 MQTT、TCP 等自定義協(xié)議傳輸

從 SD 卡、U 盤等外部存儲讀取

對升級流程有特殊控制需求：

需要在升級前后執(zhí)行特定操作

需要精細控制數(shù)據(jù)寫入時機

需要自定義進度監(jiān)控邏輯

資源極度受限環(huán)境

設(shè)備存儲空間極小,內(nèi)存緊張，無法加載額外庫

開發(fā)測試階段

需要調(diào)試升級過程的每個環(huán)節(jié)

需要驗證自定義升級方案

2、選擇 libfota2 的情況：

標準的 HTTP 遠程升級

從服務(wù)器下載升級包

使用 IoT 平臺服務(wù)

需要 HTTPS 安全下載

希望快速實現(xiàn)升級功能

不想處理網(wǎng)絡(luò)下載細節(jié)

需要自動版本檢查

希望簡單的錯誤處理

生產(chǎn)環(huán)境部署

需要穩(wěn)定的遠程升級方案

需要詳細的升級狀態(tài)反饋

支持定時自動檢查更新

5.1.3 實際選擇建議

新手用戶 → 直接選擇 libfota2

接口簡單，學習成本低

內(nèi)置完整錯誤處理

適合大多數(shù)物聯(lián)網(wǎng)應(yīng)用場景

高級用戶 → 根據(jù)需求選擇

標準網(wǎng)絡(luò)升級 → libfota2

自定義數(shù)據(jù)傳輸 → fota + 自定義邏輯

一句話總結(jié):

libfota2 擴展庫：適合絕大多數(shù)標準遠程升級場景。你只要給它一個服務(wù)器地址（合宙 iot 平臺甚至不用給），它自己就幫你完成版本檢查、HTTP 下載、校驗所有流程。一行代碼 libfota2.request(cb) 就能發(fā)起升級，省心省力。

fota 核心庫：給你最大的控制權(quán)。適合非標準升級渠道，比如通過串口、MQTT、TCP 自定義協(xié)議，或者從 SD 卡、U 盤讀取升級包。你需要自己控制數(shù)據(jù)流的接收和寫入過程。

5.2 libfota2 擴展庫 api 介紹

5.2.1 libfota2.request(cbFnc, opts)

功能

發(fā)起遠程升級

libfota2.request 是 LuatOS 為物聯(lián)網(wǎng)設(shè)備提供的一個強大、靈活且安全的遠程固件升級接口，它能極大簡化通過平臺或私有服務(wù)器實現(xiàn)設(shè)備 FOTA 功能的開發(fā)流程。

參數(shù)

cbFnc

opts

返回值

無

示例

本示例章節(jié)僅列舉一些常用功能的核心代碼片段

5.3 fota 核心庫 api 介紹

5.3.1 fota.init()

功能

初始化 fota 流程。

參數(shù)

無

返回值

local result = fota.init()

result

例子

5.3.2 fota.wait()

功能

等待底層 fota 流程準備好,等待底層固件升級流程初始化完成，包括存儲設(shè)備就緒、升級上下文準備等。

參數(shù)

無

返回值

local isDone = fota.wait()

isDone

例子

5.3.3 fota.run(buff, offset, len)

功能

寫入 fota 數(shù)據(jù)，支持逐段寫入升級包。

注意事項：如果傳入的是 zbuff，寫入成功后，請自行清空 zbuff 內(nèi)的數(shù)據(jù)

參數(shù)

buff

offset

len

返回值

local result, isDone, cache = fota.run(buff, offset, len)

result

isDone

cache

例子

5.3.4 fota.file(path)

功能

從指定文件讀取 fota 數(shù)據(jù)并寫入

參數(shù)

path

返回值

local result, isDone, cache = fota.file("/xxx.bin")

result

isDone

cache

例子

5.3.5 fota.isDone()

功能

等待底層 fota 流程完成

參數(shù)

無

返回值

local result, isDone = fota.isDone()

result

isDone

例子

5.3.6 fota.finish(is_ok)

功能

結(jié)束 fota 流程

參數(shù)

is_ok

返回值

local result = fota.finish(is_ok)

result

例子

六、LuatOS 上 FOTA 功能實際應(yīng)用示例

本部分將深入兩項具體實踐：使用 FOTA 核心庫進行固件升級和使用 libfota2 擴展庫進行固件升級。

6.1 使用 FOTA 核心庫的固件升級

6.1.1 分析項目代碼

1、文件說明

main.lua：主程序入口文件。

fota_file.lua：文件系統(tǒng) FOTA 升級功能實現(xiàn)，從文件系統(tǒng)直接讀取升級包進行固件升級。

fota_uart.lua：串口分段升級功能實現(xiàn)，通過串口接收升級包數(shù)據(jù)進行固件升級。

2、演示功能

文件系統(tǒng)直接升級：

通過模組文件系統(tǒng)中的文件直接升級

代碼演示通過 luatools 的燒錄文件系統(tǒng)功能將升級包文件直接燒錄到文件系統(tǒng)然后升級

適用于本地升級、批量生產(chǎn)等場景

串口分段升級：

通過串口將升級包文件分多個片段發(fā)送，每個片段接收并寫入

代碼演示使用 USB 虛擬串口分段寫入升級包升級

適用于非標準數(shù)據(jù)傳輸（串口、TCP、MQTT 等自定義通道升級）

支持流程精細控制，可自定義升級前后處理邏輯

3、注意事項：

升級包必須是針對當前硬件平臺的正確固件

升級過程中請勿斷電或中斷升級流程

串口升級時，需確保串口連接穩(wěn)定

升級成功后，設(shè)備會自動重啟，無需手動操作。

升級失敗時，可通過日志查看具體錯誤信息

6.2 使用 libfota2 擴展庫的固件升級

6.2.1 分析項目代碼

1、目錄結(jié)構(gòu)

2、文件說明

iot_server 目錄

main.lua ：主程序入口，

update.lua ：使用合宙 IoT 服務(wù)器簡單遠程升級模塊。

air_srv_fota.lua ：使用合宙 IoT 平臺遠程通過 tcp 下發(fā)指令控制升級功能模塊。

netdrv_device.lua ：網(wǎng)絡(luò)驅(qū)動設(shè)備配置，支持 4G、WIFI、以太網(wǎng)等多種網(wǎng)絡(luò)連接方式

psm_power_fota.lua ：PSM 低功耗模式下的 FOTA 升級實現(xiàn)，解決 PSM 狀態(tài)下升級中斷問題 TCP 客戶端 IoT 模塊

tcp_iot/tcp_iot_main.lua ：TCP 客戶端主應(yīng)用，處理 TCP 連接和升級指令接收

tcp_iot/tcp_iot_sender.lua ：TCP 數(shù)據(jù)發(fā)送功能，負責向服務(wù)器發(fā)送設(shè)備狀態(tài)和升級反饋

tcp_iot/tcp_iot_receiver.lua ：TCP 數(shù)據(jù)接收功能，解析服務(wù)器下發(fā)的升級指令 網(wǎng)絡(luò)驅(qū)動

netdrv/netdrv_4g.lua ：4G 網(wǎng)卡驅(qū)動實現(xiàn)，負責 4G 網(wǎng)絡(luò)連接管理

netdrv/netdrv_eth_spi.lua ：SPI 外掛 CH390H 芯片的以太網(wǎng)卡驅(qū)動

netdrv/netdrv_multiple.lua ：多網(wǎng)卡優(yōu)先級管理，支持配置多種網(wǎng)卡的連接優(yōu)先級

self_server 目錄

main.lua ：主程序入口。

update.lua ：自定義服務(wù)器遠程簡單升級功能模塊。

customer_srv_fota.lua ：自定義服務(wù)器通過 tcp 下發(fā)指令控制升級功能模塊。

psm_power_fota.lua ：PSM 低功耗模式下的 FOTA 升級實現(xiàn)，解決低功耗場景下的升級問題

netdrv_device.lua ：網(wǎng)絡(luò)驅(qū)動設(shè)備配置，支持多種網(wǎng)絡(luò)連接方式 TCP 自定義服務(wù)器模塊

tcp_self_server/tcp_self_main.lua ：TCP 客戶端主應(yīng)用，處理 TCP 連接和升級指令接收

tcp_self_server/tcp_self_sender.lua ：TCP 數(shù)據(jù)發(fā)送功能，負責向服務(wù)器發(fā)送設(shè)備狀態(tài)和升級反饋

tcp_self_server/tcp_self_receiver.lua ：TCP 數(shù)據(jù)接收功能，解析服務(wù)器下發(fā)的升級指令 網(wǎng)絡(luò)驅(qū)動

netdrv/netdrv_4g.lua ：4G 網(wǎng)卡驅(qū)動實現(xiàn)

netdrv/netdrv_eth_spi.lua ：SPI 以太網(wǎng)卡驅(qū)動

netdrv/netdrv_multiple.lua ：多網(wǎng)卡優(yōu)先級管理

3、演示功能

場景一： IoT 服務(wù)器簡單升級

使用 iot.openluat.com 服務(wù)器進行遠程升級

上電就檢查升級，支持版本號自動檢測和升級包下載

適用于快速部署和管理大量設(shè)備

場景二：TCP 服務(wù)器下發(fā)升級指令

通過 TCP 服務(wù)器下發(fā) JSON 格式升級指令

通控制設(shè)備使用 FOTA 功能模塊

場景三：PSM 低功耗 FOTA

針對 PSM 狀態(tài)下升級未完成就進入休眠導致升級失敗的情況

支持低功耗設(shè)備的可靠升級

4、注意事項

進行遠程升級時，版本號必須按照"XXX.YYY.ZZZ"三段格式定義

不同場景的功能模塊不要同時加載，否則會導致功能沖突

升級過程中需保持網(wǎng)絡(luò)連接穩(wěn)定

建議在升級前檢查設(shè)備電量，確保有足夠電量完成升級。

6.3 Air780EHM 開發(fā)板上演示項目功能

準備硬件環(huán)境

Air780EHM 開發(fā)板一塊

TYPE-C USB 數(shù)據(jù)線一根

可聯(lián)網(wǎng)的 SIM 卡（用于遠程升級場景）

ttl 小板（可選，用于物理串口升級）

準備軟件環(huán)境

Luatools燒錄工具

內(nèi)核固件

腳本文件：對應(yīng)場景的腳本文件

模擬工具

串口升級：Python 環(huán)境和 main.py 腳本

遠程升級

演示流程

文件系統(tǒng)升級演示：

使用 Luatools 燒錄升級包到文件系統(tǒng)

燒錄 fota_file.lua 相關(guān)腳本

觀察日志輸出，驗證升級是否成功

串口升級演示：

燒錄 fota_uart.lua 相關(guān)腳本

按下 Power 鍵啟動升級模式

運行 Python 腳本發(fā)送升級包

觀察串口輸出和升級進度

遠程升級演示：

在 IoT 平臺創(chuàng)建設(shè)備和升級任務(wù)

燒錄對應(yīng)場景的腳本

設(shè)備自動連接平臺并檢測升級

觀察升級進度和結(jié)果

6.4 升級擴展

支持藍牙功能的模塊比如 Air8000A 或者 Air8101 等模組，可以通過藍牙升級，具體升級可參考對應(yīng)教程文檔。

七、注意事項與常見問題

7.1 注意事項

1、版本號格式：

使用 IoT 平臺時，項目的 VERSION 必須為三段數(shù)字格式（如 "001.000.001"），否則平臺版本比對可能出錯。

2、PRODUCT_KEY：

使用 IoT 平臺時，必須在 main.lua 中正確定義全局變量 PRODUCT_KEY，其值需從 IoT 平臺的項目中獲取。

3、重啟時機：

下載升級包成功（result 為 0）后，通常需要調(diào)用 rtos.reboot() 重啟設(shè)備以更新。你可以根據(jù)需要延遲重啟。

4、自建服務(wù)器規(guī)則：

使用 libfota2 擴展庫的時候，填寫自建服務(wù)器 url 時候記得 url 前面拼上###

需要升級時，服務(wù)器應(yīng)返回 HTTP 200，消息體為升級文件內(nèi)容。

無需升級時，服務(wù)器應(yīng)返回 HTTP 300 或以上的狀態(tài)碼。

5、使用 iot 平臺需要注意：

設(shè)備在自己名下；

代碼中項目 key（PRODUCT_KEY）要填寫正確；

配置好升級包文件后需要指定升級設(shè)備，配置需要升級設(shè)備的 imei；

升級失敗可以在 iot 平臺中打開固件升級->升級日志頁面，輸入 iemi 來查看下升級失敗的原因是什么。

7.2 為什么升級后我的模塊沒有任何反應(yīng)了，像是變磚一樣

有多種可能，

7.2.1 檢查腳本

首先先檢查下用戶自己的腳本，有可能是引起重啟/死機的代碼寫在了最前面，例如新加的某個值或者函數(shù)為 nil 但是還是去做了些加減乘除或者判斷大小的邏輯。可以直接本地燒錄下新版本的 core+ 腳本驗證，如果有 fskv 等用到 flash 的代碼，可能需要仔細檢查才能排除問題，比如下載的時候勾選如下圖所示的兩個選項。

7.2.2 檢查 core

如果是僅腳本升級，但是沒注意使用了新 core 中才有的接口，就有可能引起循環(huán)重啟，如果重啟在代碼最開頭，模塊可能來不及打印任何日志就重啟了，可以直接本地燒錄下新版本的 core+ 腳本驗證，如果有 fskv 等用到 flash 的代碼，可能需要仔細檢查。

7.3 檢查過腳本和 core，沒問題，為什么會循環(huán)升級 6 次以后禁止升級

檢查下升級包是否正常，有時候因為人員誤操作，經(jīng)常會出現(xiàn)舊腳本 + 新 core 或者新腳本 + 舊 core 的意外組合，

例如：

本來應(yīng)該如下表描述的一樣

操作人員失誤后變成了如下

然后誤操作舊版本(1) 和誤操作新版本(1)進行差分，這樣雖然腳本版本號舊版本大于了新版本，但是 core 的舊版本小于新版本，所以升級平臺依舊認為是依次有效的升級，下發(fā)了升級包。

升級完成后，模塊內(nèi)部腳本版本號變成了 001.000.000 core 版本號為 V2004 ，下次模塊請求升級的時候，當前固件上報的腳本版本號(001.000.000)依舊小于云平臺存儲的腳本版本號(001.000.005)，然后繼續(xù)下發(fā)升級包，就這么循環(huán)升級，直到流量耗盡，建議可以做一個類似 iot 平臺的禁止升級規(guī)則

在正確生成差分包，并且上傳成功后，可以在 iot 平臺里解除禁止升級的限制

在"我的設(shè)備"中選擇升級 imei 所在的項目，然后點擊右邊的"解除禁止升級"，

確定“導致設(shè)備循環(huán)升級的異常”已經(jīng)處理完成后，點擊確定解除，即可解除限制升級

7.4 如何處理同個項目外面有多個版本設(shè)備的升級情況

7.4.1 場景 1：多種不同內(nèi)核固件版本都要升級為最新版本內(nèi)核固件 + 最新腳本

需要對每個版本都生成對應(yīng)的差分包

操作步驟：

7.4.2 場景 2：多種不同內(nèi)核固件版本 + 不同版本腳本都要升級為最新版本腳本，既只升級腳本。

操作步驟：

7.4.3 升級規(guī)則說明

內(nèi)核固件：需分情況對待，4G 模組系列比如 Air780EXX 系列、Air724UG、Air8000 系列等僅支持差分升級，wifi 模組 Air8101/Air8101A 是全量升級

腳本：支持全量升級，可一次性完成

7.5 fota 升級對 fskv 或文件系統(tǒng)的影響

7.5.1 遠程升級時，會清除 FSKV 中的數(shù)據(jù)嗎？

默認不會，F(xiàn)SKV 數(shù)據(jù)存儲在獨立分區(qū)，遠程升級主要操作 FOTA 專用分區(qū)、ap/cp 分區(qū)、用戶腳本分區(qū)，不會直接修改 FSKV 分區(qū)。

7.5.2 遠程升級時，自己創(chuàng)建的文件會被刪除嗎？

不會，用戶文件系統(tǒng)中自行創(chuàng)建的文件會保留，不會影響用戶文件。

八、fota 錯誤總結(jié)

8.1 差分包過大

8.2 iot 平臺升級沒有配置 imei

8.3 制作差分包時的舊固件不是模組中實際的固件

下面例子模組中實際固件是 2016_2 號固件

制作差分時用的 2020_1 號固件對 2016_1 號固件制作的差分包

平臺校驗版本通過，正常下發(fā)升級包

8.4 不同編號固件制作差分包

不同編號的固件制作差分包的時候通常制作的差分包過大，升級失敗，日志見 8.1

問題將會持續(xù)更新......

今天的內(nèi)容就分享到這里了~

審核編輯 黃宇