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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

特點：具有持久化存儲，斷電不丟失 、可動態(tài)寫入和讀取、支持文件系統(tǒng) API 訪問、可隨時創(chuàng)建和刪除的特性?？梢杂脕韮Υ嬗脩襞渲梦募⒃O備運行日志、網絡配置信息、臨時數據和緩存、用戶生成的文件。

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

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

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

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

特點：

持久化存儲：斷電后數據不丟失

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

固定大?。和ǔ?64KB

輕量級：適合存儲少量關鍵配置，如網絡參數、設備 ID、運行狀態(tài)等

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

存儲設備唯一標識符

保存網絡連接參數（APN、服務器地址等）

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

存儲用戶自定義配置

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

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

1.4.1 分區(qū)介紹

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

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

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

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

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

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

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

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

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

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

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

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

1.4.2 升級流程

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

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

1、升級包寫入流程：

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

下載升級包：

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

寫入 FOTA 分區(qū)：

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

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

完成寫入，驗證升級包：

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

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

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

2、重啟后升級流程：

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

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

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

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

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

Air7xx 系列模組 LuatOS 多固件版本

Air8000 系列固件版本

二、soc 軟件包文件分析

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

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

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

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

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

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

下面講解一下模組所用固件包.soc 文件的組成以及格式相關內容。

2.1 soc 簡介

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

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

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

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

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

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

2.2 SoC 組成部分

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

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

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

2.2.1 info.json 的內容

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

2.2.2 腳本數據文件 script.bin

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

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

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

2.2.3 原始固件

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

在 .soc 文件體系中，info.json 配置文件內的 "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 后綴結尾的固件，可以用移芯提供的 flashtool 工具燒錄，也可以用 Luatools 燒錄。

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

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

2.3 soc 實際文件分析

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

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

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

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

info.json

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

這個文件主要包含有：

芯片類型（

ROM 文件信息及下載地址

腳本文件信息及下載地址

分區(qū)表配置

下載參數（波特率、強制波特率等）

luatos.binpkg

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

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

其他輔助文件

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

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

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

luatos_debug.map ：調試映射文件，記錄了函數和變量在內存中的地址。

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

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

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

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

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

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

3.1 差分升級的基本概念

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

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

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

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

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

升級包體積大：消耗大量網絡帶寬與設備存儲空間。

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

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

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

體積極?。翰罘职ǔH為完整新固件包的 10%-30%，甚至更低。

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

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

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

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

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

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

1. 差分包生成原理

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

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

HDiffPatch ：高性能的差異比較庫

Rsync 算法 ：用于網絡傳輸的差異算法

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

2. 差分包的組成

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

差異數據 ：新舊固件的二進制差異

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

合并指令 ：指導設備如何合并生成新固件

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

3. 差分升級的工作流程

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

流程詳解：

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

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

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

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

4.1 LuatOS 開發(fā)結構

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

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

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

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

在 4G 相關的模組中，比如 Air780Exx 系列、Air8000 系列模組中

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

在 wifi 模組 Air8101 和 Air8101A 中

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

4.2 單腳本升級

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

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

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

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

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

4.2.2 單腳本升級升級包制作

在 luatools 中點擊生成量產文件，在生成的量產文件夾中，對應的.bin 后綴的就是單腳本升級的升級包。

4.2.3 實際應用場景

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

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

場景 2：配置文件更新

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

4.2.4 工作流程

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

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

4.3 含 core 升級

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

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

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

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

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

4.3.2 含 core 升級升級包制作

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

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

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

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

4.3.3 Core 固件的變更特點

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

4.3.4 含 core 升級各芯片差異

4G 模組：

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

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

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

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

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

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

4.4.3 升級包特點

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

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

五、fota 升級相關 api 簡介（libfota2 擴展庫和 fota 核心庫）

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

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

5.1.1 核心區(qū)別總結

fota（底層核心庫）

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

核心能力：

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

支持內部存儲和外部 SPI Flash

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

fota2（libfota2 擴展庫）

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

核心能力：

自動處理 HTTP/HTTPS 網絡下載

支持 IoT 平臺和自建服務器

內置版本檢查、下載、驗證全流程

提供詳細錯誤碼和回調函數

代碼特點：

5.1.2 適用場景推薦

1、選擇 fota 的情況：

需要自定義升級數據源

通過串口接收升級包

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

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

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

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

需要精細控制數據寫入時機

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

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

設備存儲空間極小,內存緊張，無法加載額外庫

開發(fā)測試階段

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

需要驗證自定義升級方案

2、選擇 libfota2 的情況：

標準的 HTTP 遠程升級

從服務器下載升級包

使用 IoT 平臺服務

需要 HTTPS 安全下載

希望快速實現升級功能

不想處理網絡下載細節(jié)

需要自動版本檢查

希望簡單的錯誤處理

生產環(huán)境部署

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

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

支持定時自動檢查更新

5.1.3 實際選擇建議

新手用戶 → 直接選擇 libfota2

接口簡單，學習成本低

內置完整錯誤處理

適合大多數物聯(lián)網應用場景

高級用戶 → 根據需求選擇

標準網絡升級 → libfota2

自定義數據傳輸 → fota + 自定義邏輯

一句話總結:

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

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

5.2 libfota2 擴展庫 api 介紹

5.2.1 libfota2.request(cbFnc, opts)

功能

發(fā)起遠程升級

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

參數

cbFnc

opts

返回值

無

示例

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

5.3 fota 核心庫 api 介紹

5.3.1 fota.init()

功能

初始化 fota 流程。

參數

無

返回值

local result = fota.init()

result

例子

5.3.2 fota.wait()

功能

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

參數

無

返回值

local isDone = fota.wait()

isDone

例子

5.3.3 fota.run(buff, offset, len)

功能

寫入 fota 數據，支持逐段寫入升級包。

注意事項：如果傳入的是 zbuff，寫入成功后，請自行清空 zbuff 內的數據

參數

buff

offset

len

返回值

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

result

isDone

cache

例子

5.3.4 fota.file(path)

功能

從指定文件讀取 fota 數據并寫入

參數

path

返回值

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

result

isDone

cache

例子

5.3.5 fota.isDone()

功能

等待底層 fota 流程完成

參數

無

返回值

local result, isDone = fota.isDone()

result

isDone

例子

5.3.6 fota.finish(is_ok)

功能

結束 fota 流程

參數

is_ok

返回值

local result = fota.finish(is_ok)

result

例子

六、LuatOS 上 FOTA 功能實際應用示例

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

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

6.1.1 分析項目代碼

1、文件說明

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

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

fota_uart.lua：串口分段升級功能實現，通過串口接收升級包數據進行固件升級。

2、演示功能

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

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

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

適用于本地升級、批量生產等場景

串口分段升級：

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

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

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

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

3、注意事項：

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

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

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

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

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

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

6.2.1 分析項目代碼

1、目錄結構

2、文件說明

iot_server 目錄

main.lua ：主程序入口，

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

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

netdrv_device.lua ：網絡驅動設備配置，支持 4G、WIFI、以太網等多種網絡連接方式

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

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

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

tcp_iot/tcp_iot_receiver.lua ：TCP 數據接收功能，解析服務器下發(fā)的升級指令 網絡驅動

netdrv/netdrv_4g.lua ：4G 網卡驅動實現，負責 4G 網絡連接管理

netdrv/netdrv_eth_spi.lua ：SPI 外掛 CH390H 芯片的以太網卡驅動

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

self_server 目錄

main.lua ：主程序入口。

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

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

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

netdrv_device.lua ：網絡驅動設備配置，支持多種網絡連接方式 TCP 自定義服務器模塊

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

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

tcp_self_server/tcp_self_receiver.lua ：TCP 數據接收功能，解析服務器下發(fā)的升級指令 網絡驅動

netdrv/netdrv_4g.lua ：4G 網卡驅動實現

netdrv/netdrv_eth_spi.lua ：SPI 以太網卡驅動

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

3、演示功能

場景一： IoT 服務器簡單升級

使用 iot.openluat.com 服務器進行遠程升級

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

適用于快速部署和管理大量設備

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

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

通控制設備使用 FOTA 功能模塊

場景三：PSM 低功耗 FOTA

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

支持低功耗設備的可靠升級

4、注意事項

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

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

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

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

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

準備硬件環(huán)境

Air780EHM 開發(fā)板一塊

TYPE-C USB 數據線一根

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

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

準備軟件環(huán)境

Luatools燒錄工具

內核固件

腳本文件：對應場景的腳本文件

模擬工具

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

遠程升級

演示流程

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

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

燒錄 fota_file.lua 相關腳本

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

串口升級演示：

燒錄 fota_uart.lua 相關腳本

按下 Power 鍵啟動升級模式

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

觀察串口輸出和升級進度

遠程升級演示：

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

燒錄對應場景的腳本

設備自動連接平臺并檢測升級

觀察升級進度和結果

6.4 升級擴展

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

七、注意事項與常見問題

7.1 注意事項

1、版本號格式：

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

2、PRODUCT_KEY：

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

3、重啟時機：

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

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

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

需要升級時，服務器應返回 HTTP 200，消息體為升級文件內容。

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

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

設備在自己名下；

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

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

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

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

有多種可能，

7.2.1 檢查腳本

首先先檢查下用戶自己的腳本，有可能是引起重啟/死機的代碼寫在了最前面，例如新加的某個值或者函數為 nil 但是還是去做了些加減乘除或者判斷大小的邏輯?？梢灾苯颖镜責浵滦掳姹镜?core+ 腳本驗證，如果有 fskv 等用到 flash 的代碼，可能需要仔細檢查才能排除問題，比如下載的時候勾選如下圖所示的兩個選項。

7.2.2 檢查 core

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

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

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

例如：

本來應該如下表描述的一樣

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

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

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

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

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

確定“導致設備循環(huán)升級的異?！币呀浱幚硗瓿珊?，點擊確定解除，即可解除限制升級

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

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

需要對每個版本都生成對應的差分包

操作步驟：

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

操作步驟：

7.4.3 升級規(guī)則說明

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

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

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

7.5.1 遠程升級時，會清除 FSKV 中的數據嗎？

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

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

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

八、fota 錯誤總結

8.1 差分包過大

8.2 iot 平臺升級沒有配置 imei

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

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

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

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

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

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

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

今天的內容就分享到這里了~

審核編輯 黃宇