即使你是FOTA新手，也能通過本教程掌握遠程固件升級的核心實現。我們以libfota2為客戶端核心，結合自建第三方服務器，提供一份零基礎可上手的完整FOTA服務搭建指南。從服務端部署到設備端響應升級指令，每一步都配有詳細說明與示例代碼，真正做到“手把手”教學，助你快速實現固件遠程更新。

一、FOTA 概述

FOTA 即遠程升級功能，此功能可以讓用戶在不方便大量線刷升級(設備不在身邊/量產 PCB 沒引出 USB/需要大批量進行功能升級)的情況下，快速進行底層固件/腳本/腳本 + 底層固件的遠程更新。

LuatOS 開發模式下，固件分為兩部分：core 和 script

遠程升級時：升級 script 和 core+script ，僅 script 腳本升級時為全量升級，core+script 都升級時為差分升級

遠程升級時：可以僅升級 script；也可以同時升級 core+script

支持 iot 平臺升級和自建第三方服務器(HTTP)升級

二、演示功能概述

本文將詳細講述如何使用自建服務器服務器進行遠程升級。另外此教程演示了自建服務器的三種升級相關場景：

(1) fota 升級簡單演示：使用 iot 服務器進行遠程升級功能模塊，簡單升級演示；

(2) tcp 服務器下發升級指令：通過 tcp 服務器下發升級指令（指令格式使用 json 字符串，包含是否升級參數），控制設備使用 fota 功能模塊；

(3) psm 低功耗 fota：低功耗 fota 功能模塊，此場景是針對 psm 狀態下升級沒完成就進入休眠導致升級失敗的情況寫的一個示例。

三、自有服務器 FOTA

FOTA 有多種方式，可以使用我們的 iot 平臺進行升級，也可以使用用戶自建平臺升級，可以只升級 core，可以只升級用戶腳本，也可以 core+ 腳本一起升級，接下來介紹自建服務器的升級。

3.1 網卡切換

fota 功能需要聯網去下載升級包，所以需要選擇一種聯網方式：

netdrv_device：配置連接外網使用的網卡，目前支持以下四種選擇（三選一）

(1) netdrv_4g：4G 網卡

(2) netdrv_eth_spi：通過 SPI 外掛 CH390H 芯片的以太網卡

(3) netdrv_multiple：支持以上三種網卡，可以配置三種網卡的優先級

在 netdrv_device.lua 文件中選擇一種使用即可。

3.2 云平臺配置

每一家的云平臺都不一樣，但是本質上都一樣，都是給模塊下發正確的升級文件。建議平臺做一些驗證，比如 imei 驗證、版本號驗證，循環請求驗證，這樣能夠有效的避免因為升級包下載不對導致的模塊循環升級，不跑代碼其他邏輯，引起的假死機現象。

3.3 升級包制作并上傳

自建服務器可以使用此服務器來做測試：http://airtest.openluat.com/download，該服務器只能上傳文件，上傳后可以獲得一個下載鏈接，復制的鏈接用作自建服務器的 url。

所以我們在最開始先要生成一個鏈接，步驟如下：在進行腳本改動前，需要在你的電腦上隨便生成一個.bin 后綴，大小不為 0 的文件(可以隨便往里面寫點什么)，然后將這個 bin 文件上傳到模塊請求的地址去，目的是為了獲取升級的 url。

比如我的 bin 文件升級 url 為”http://airtest.openluat.com/download/FOTA2_DEMO_001.000.001_LuatOS-SoC_V2012_Air780EPM_1.soc“

3.3.1 單腳本升級

3.3.1.1 舊版本軟件本地燒錄

如果用戶只是新增一些自己的腳本邏輯，沒有更新底層，可以選擇僅腳本升級

1.腳本中修改 url 為自己的升級 url，然后打開 luatools 的項目管理界面，點擊生成量產文件，默認放在 luatools 根目錄下的"SOC 量產及遠程升級文件Air8000"目錄下

注：一定要注意 url 前的"###"標志位，如果不加###，模塊進行 HTTP 請求時，會在請求頭里加上 version、project_key,imei,firmware_name 等參數

2、將對應生成的 2010 版本，001.000.000 的 SOC 的固件燒錄到模組中。

3.3.1.2 新版本軟件級包制作并上傳

1、因為模塊燒錄的是 001.000.000 版本，所以我們需要給腳本里的版本號改一下，改為 001.000.001 版本

2、再將腳本中增加幾行打印(為了模擬用戶修改腳本的動作)

3、然后重新生成一次量產固件：

4、將升級文件改名成上面 url 中的文件名字 FOTA2_DEMO_001.000.001_LuatOS-SoC_V2010_Air780EPM_1.soc 。然后上傳到服務器對應的地址。

3.3.2 含 core 升級

注意：對于不同后綴的固件，不能直接升級，分區有差異，強行升級可能無法啟動。比如：LuatOS-SoC_V2012_Air780EPM_1.soc 只能升級LuatOS-SoC_V2014_Air780EPM_1.soc 后綴的固件，不能升級 LuatOS-SoC_V2014_Air780EPM_2.soc 后綴的固件。

3.3.2.1 舊版本軟件本地燒錄

每一次 core 的升級都會帶來一些網絡上的優化(例如信號差時的網絡穩定性)以及一些 bug 修復，所以在發布新版本以后，用戶可以先測試下 core 對自己腳本有無明顯影響或性能提升，然后進行遠程 FOTA。

1、本次選擇腳本版本是 001.000.000，升級到 001.000.001；固件版本從 2010 升級到 2012 版本，

按照生成量產固件的步驟，001.000.000 版本腳本搭配 V2010 版本固件生成量產文件如下圖：

2、將對應生成的 2010 版本，001.000.000 的 SOC 的固件燒錄到模組中。

3.3.2.2 新版本軟件級包制作并上傳

1、修改腳本版本后以及固件版本后重新生成量產固件如下：

需要注意的是：生成了這個版本以后，再去腳本中改動腳本版本號為 001.000.002(只要前后兩位有一位大于 1，一位大于 0 即可(當然第一位大于 1 的時候，整個版本號自然大于 001.000.001)，如 002.000.200；001.000.001；030.000.311 等)

腳本版本號分為 A.B.C 三段；

因為歷史原因，中間這一段 B 沒有任何意義，但是必須存在；

假設舊的腳本版本號為 A1.B1.C1，新的腳本版本號為 A2.B2.C2；

當新舊腳本版本號滿足以下任何一種條件時，版本號允許升級：

（1）、A2 等于 A1，同時 C2 大于 C1；

（2）、A2 大于 A1，同時 C2 大于或者等于 C1；

（3）、B1 B2 無意義

2、接下來就是針對這兩個量產文件，制作一個差分文件，用來遠程升級(注：遠程升級中 core 為差分，腳本為全量升級)

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

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

4、在你選擇的目錄下看到如下所示，帶著腳本的 PROJECT core 版本號 腳本版本號的 bin 后綴的差分文件。

5、將升級文件上傳完成以后，為了防止模塊當前固件不是最早的版本，可以點擊 luatools 主界面右邊的"下載固件"選擇最早的 001.000.000 版本，按住 boot 重啟模塊，然后點擊下載，將最早的固件下載進模塊里即可

6、將升級文件改名成上面 url 中的文件名字 FOTA2_DEMO_001.000.001_LuatOS-SoC_V2012_Air780EPM_1.soc 。然后上傳到服務器對應的地址。

7、將對應生成的 2010 版本，001.000.000 的 SOC 的量產固件燒錄到模組中。

3.4 示例結果展示

本 demo 將會演示三種場景下的 fota 升級，場景在 main.lua 中切換。

3.4.1 場景一：fota 升級簡單演示

主要代碼如下：

升級中：模塊請求升級，下載完升級包以后會進行 MD5 驗證升級包有無問題，如果沒問題，就會啟動重啟程序，然后進行升級工作

升級后：升級成功后按我們之前的腳本，每隔 5S，打印一次"降功耗,找合宙"以及當前腳本版本號，可以看出，當前版本號已經由原來的 001.000.000 變為了 001.000.001，固件版本從 2010 變為 2012。

3.4.2 場景二：tcp 服務器下發升級指令

通過 tcp 服務器下發升級指令（指令格式使用 json 字符串，包含是否升級參數），控制設備使用 fota 功能模塊。此場景下，設備會先連接到 TCP 服務器，等待服務器下發升級指令。在 air_srv_fota.lua 中會有一個參數控制，防止升級過程中重復下載升級包。

測試服務器鏈接：https://netlab.luatos.com/，打開一個 tcp 服務器，

在 tcp_self_main.lua 中配置 tcp 服務器信息：

升級前：設備連接到 TCP 服務器，等待指令下發：{"fota": "true", "url": "http://airtest.openluat.com/download/FOTA2_DEMO_001.000.001_LuatOS-SoC_V2012_Air780EPM_1.soc"}

升級中：模組收到服務器下發的升級指令后，設備開始下載升級包并進行驗證

升級后：升級包下載完成后設備重啟升級，并循環打印新的版本號信息

3.4.3 場景三：psm 低功耗 fota

此場景是防止 psm 狀態下升級沒完成就進入休眠導致升級失敗的情況寫的一個例子。需要注意的是要等待升級成功后再去進入休眠。

主要代碼如下：

升級前：設備會在開機的時候去請求下配置的 url 的升級包，定期喚醒檢查是否有升級任務

在此過程中模組會保持喚醒狀態并等待升級包下載成功并校驗通過，以及檢查版本是否一致。如果版本不一致或升級包檢驗沒通過則進入休眠等待下次喚醒檢查升級包。沒問題的話升級包下載成功后會重啟并升級，升級流程如下：

升級后：升級完成后設備顯示新的版本號，并重新去請求升級包，沒有新的升級包則會進入 PSM 狀態

四、常見問題與注意事項

4.1 注意事項：

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

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

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

4、自建服務器規則：

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

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

5、固件類型：使用 IoT 平臺進行腳本升級時，使用 Luatools 生成的 .bin 量產文件。

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

有多種可能，

4.2.1 檢查腳本

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

4.2.2 檢查 core

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

4.3 檢查過腳本和 core，沒問題，為什么會循環升級 6 次以后禁止升級

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

例如：

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

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

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

升級完成后，模塊內部腳本版本號變成了 001.000.000 core 版本號為 V2008，下次模塊請求升級的時候，當前固件上報的腳本版本號(001.000.000)依舊小于云平臺存儲的腳本版本號(001.000.001)，然后繼續下發升級包，就這么循環 6 次，然后觸發 iot 平臺的禁止升級規則

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

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

確定“導致設備循環升級的異常”已經處理完成后，點擊確定解除，即可解除限制升級

4.4 我想在服務器發送特定的字符串如"update"時再觸發升級，應該怎么做

只需要在你希望的升級升級邏輯后面加上升級語句即可，例如mqtt 的 demo里增加幾句話

又或者希望按鍵升級：

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

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

需要對每個版本都生成對應的差分包操作步驟： 現有A1、A2、A3三種內核固件需升級為B+新腳本： - 生成3個升級包：A1→B差分包+新腳本、A2→B差分包+新腳本、A3→B差分包+新腳本- 在合宙IoT平臺創建3個升級配置，分別對應三類設備IMEI

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

操作步驟： 1. 準備完整的最新腳本（無需內核差分包） 2. 在IoT平臺創建一個升級配置，指定所有需升級設備IMEI列表

4.5.3 升級規則說明

內核固件：僅支持差分升級

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

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

審核編輯 黃宇