OTA 指南
概述
ameba_ota 通过调用方提供的字节流下载新的应用固件,并将其写入非活动的 A/B 槽位。它仅覆盖下载与写入这部分流程:槽位选择、签名校验,以及启动时在 OTA1/OTA2 之间的选择由 bootloader 负责。该 crate 从不接触 boot.bin——它写入固件后会保持 manifest 的 Pattern 字段未设置,直到写入通过校验,因此在真正提交(commit)落地之前,bootloader 会一直保持启动当前固件。
备注
使用 OTA 前,请先参阅 Flash 分区布局 了解 OTA1/OTA2 槽位的分区方式,以及 OTA 指南 了解该 crate 所依赖的 bootloader 侧选择与签名校验机制。
适用范围与限制
ameba_ota 有意保持较小的功能范围:
仅支持应用固件。 Sub-header 中的
ImgID会被检查是否为应用固件 ID,bootloader 固件会被OtaError::UnsupportedImageId拒绝,而不会被写入。每个文件仅支持一个固件。 如果一个文件声明了多个固件,会被
OtaError::MultiImageUnsupported直接拒绝——本项目的固件是逐个编译和发布的。仅支持 NOR flash。
OtaWriter按 sector 粒度擦写,不包含 NAND 的分页缓冲或坏块处理。该 crate 本身不做固件真实性校验。 提交前仅验证一个针对 sub-header
Checksum字段的普通回绕求和校验。防篡改能力完全依赖 bootloader 下次启动时自身的 ECC 签名校验——如果攻击者重新计算了校验和使其匹配,被篡改或恶意的固件依然能通过该 crate 的校验和检查,但无法通过启动校验。
架构
Transport (trait) 字节来源:HTTP、文件系统,或调用方驱动的数据流
│
▼
OtaSession::run() core.rs — 解析文件头/子头,流式处理固件主体
│
▼
OtaWriter storage.rs — NOR 擦写、校验和验证、manifest 提交
│
▼
FlashStorage (ameba-storage)
slot 通过读取 bootloader 启动时的 remap 快照来判断 OTA1/OTA2 中哪个槽位当前正在运行,并将目标指向另一个槽位,layout 保存四个槽位固定的 flash 地址和大小,manifest 负责解析固件主体前的文件头/子头/manifest 字节布局。
Flash 存储(ameba-storage)
ameba-storage 在同一个 FlashStorage 句柄上暴露了两档 API;ameba_ota::OtaWriter 只用严格对齐这一档,因为它在每次写入前已经自行缓冲了完整一个 sector:
严格对齐、带对齐检查(
read_nor/write_nor/erase)。 读写的 offset/length 必须 4 字节对齐,擦除必须 4 KiB 对齐,且write_nor前目标区域必须已处于擦除状态。这一档对应实现了embedded_storage::nor_flash::NorFlash/ReadNorFlash。任意对齐、Read-Modify-Write(
read/write)。 接受任意 offset/length,内部会透明地读取所在 sector、在栈缓冲区中修改、擦除、再写回——适合不想自己管理 sector 缓冲的应用代码,代价是每次调用都隐含一次擦除。ameba_ota不使用这条路径。
下方 Quick Start 中用到的 Flash::steal() 是 unsafe 的,因为进程生命周期内必须只存在一个 Flash token——由调用方自行保证不会构造出第二个。此外还有一个更底层、不做任何检查的 ll 模块(裸 spiflash_read/spiflash_write/擦除函数,无对齐检查、无边界检查、无加锁),面向自行管理前置条件的 bootloader 或 OTA writer 类代码;ameba_ota 同样没有使用它,因为上面按 sector 缓冲的严格对齐档已经覆盖了它的需求。
快速入门
use ameba_ota::core::{OTA_BUF_SIZE, OtaSession};
use ameba_ota::storage::OtaWriteBuf;
use ameba_storage::{Flash, FlashStorage};
...
static OTA_BUF: StaticCell<[u8; OTA_BUF_SIZE]> = StaticCell::new();
static WRITE_BUF: StaticCell<OtaWriteBuf> = StaticCell::new();
...
let ota_buf = OTA_BUF.init([0u8; OTA_BUF_SIZE]);
let write_buf = WRITE_BUF.init([0u8; ameba_ota::storage::CHUNK_LEN]);
...
let mut flash = FlashStorage::new(unsafe { Flash::steal() });
let session = OtaSession::new(transport);
match session.run(&mut flash, ota_buf, write_buf).await {
Ok(report) => {
println!(
"[ota] programmed: fw_ver={} img_id={} body_len={} bytes",
report.fw_ver, report.img_id as u32, report.body_len
);
println!("[PASS] ota-http: image committed to inactive slot, resetting");
// Give LOGUART time to flush before the reset cuts it off.
Timer::after_millis(20).await;
cortex_m::peripheral::SCB::sys_reset();
}
Err(e) => {
println!("[FAIL] ota-http: {:?}", e);
}
}
transport 可以是任何实现了 ameba_ota::transport::Transport 的类型,例如下文的 HTTP transport。返回 Ok 时槽位已提交,复位后由 bootloader 选中新固件;返回 Err 时槽位保持未提交,当前运行的固件不受影响。
ota_buf 和 write_buf 放在 static 中而非局部变量:两者合计有几 KB,如果放在局部变量中会使调用方 async task 的 future 体积膨胀。
Transport
OtaSession 从不直接与网络栈或文件系统交互——它只从任何实现了 Transport trait 的对象中读取字节:
pub trait Transport {
/// Transport-specific failure (socket error, HTTP status, short read…).
type Error;
...
fn read(
&mut self,
buf: &mut [u8],
) -> impl core::future::Future<Output = Result<usize, Self::Error>>;
}
read 在流结束时返回 Ok(0),且不能忙等待——这是异步 transport 在等待下一个数据包到达时让出给 executor 的位置。直接实现该 trait,即可从文件系统、BLE 链路或任意调用方驱动的字节源为 OTA 提供数据。
HTTP Transport
启用 http-reqwless feature 即可获得基于 reqwless 实现的现成 HTTP GET transport:
ameba-ota = { path = "../../ameba-ota", features = ["http-reqwless"] }
use ameba_ota::http::{self, HEADER_BUF_SIZE, LiteralDns};
...
let tcp_client = embassy_net::tcp::client::TcpClient::new(stack, tcp_state);
let dns = LiteralDns;
let mut client = reqwless::client::HttpClient::new(&tcp_client, &dns);
...
let mut resource =
match embassy_time::with_timeout(Duration::from_secs(15), client.resource(url.as_str()))
.await
{
Ok(Ok(r)) => r,
...
};
let transport = match embassy_time::with_timeout(
Duration::from_secs(15),
http::http_get(&mut resource, OTA_PATH, header_buf),
)
.await
{
Ok(Ok(t)) => t,
...
};
以上摘自 examples/ota-http,其中 tcp_state 和 header_buf 来自 static 的 StaticCell, url 为服务器的基础 URL( http://<OTA_SERVER_IP>:<OTA_SERVER_PORT> )。连接和 GET 都包在 15 s 的 with_timeout 中:向不可达的服务器发送 TCP SYN 会持续重传数分钟而不报错,不加超时的话升级流程会一直卡住、不给出任何结果。
这个 transport 有三处限制,均为有意设计:
不支持 TLS。
reqwless使用default-features = false引入,去掉了embedded-tls。传输层的机密性并不是这里让升级安全的关键——真正拒绝被篡改固件的是 bootloader 下次启动时的 ECC 签名校验,而不是下载通道本身。不支持重定向。
reqwless不会跟随 3xx 响应,重定向的 URL 会以HttpError::Status的形式暴露出来,而不会被静默跟随。请直接指向目标 URL。不支持 DNS。
LiteralDns只接受 IPv4 字面地址——引入真正的解析器意味着在升级路径上多一个 socket 和一种新的失败模式。使用主机名的 URL 会立即以HttpError::NotAnIpLiteral失败。
响应状态码在 http_get 返回之前就会被检查,因此 404 会在那里直接失败,而不会被当作固件写入 flash。
应用示例
Rust SDK 提供了一个示例项目 ota-http,它从局域网中的普通 HTTP 服务器下载固件,并将其写入非活动槽位:
启用系统看门狗(5 s 超时),并启动一个每 500 ms 刷新一次的任务(见下文 OTA 过程中的看门狗 )。
连接 Wi-Fi(WPA2-PSK)并等待 DHCP 完成。
使用
http-reqwlesstransport 通过 HTTPGET获取固件。将响应主体通过
OtaSession::run流式写入非活动槽位。成功后提交槽位并复位,由 bootloader 启动新固件。失败时槽位保持未提交状态,设备进入空闲——当前运行的固件始终不受影响。
编译前请在 src/main.rs 顶部设置以下常量:
常量 |
含义 |
|---|---|
|
要连接的 2.4 GHz WPA2-PSK 网络 |
|
HTTP 服务器地址,必须是 IPv4 字面地址 |
|
HTTP 服务器端口 |
|
OTA 固件在服务器上的路径 |
|
本次启动是否尝试升级 |
|
启动时打印,用于区分当前运行的是哪个固件 |
执行一次升级
要下载的固件是 cargo xtask build 在 app.bin 旁边生成的 ota_all.bin。每个固件的版本号由 ameba-flash/src/pack.rs 中的 IMG_VER_MAJOR 和 IMG_VER_MINOR 决定。每次启动时 bootloader 会比较两个槽位的版本号并启动较高的那个(相同时选第一个槽位),因此下载的固件版本号必须高于当前运行的固件,否则升级本身会成功,但开发板仍会启动旧固件。
设置 Wi-Fi 与服务器相关常量,保持
REQUEST_OTA_UPDATE = true,编译并烧录该固件。它是执行升级的那一个。编译要下载的固件:设置
REQUEST_OTA_UPDATE = false(避免它首次启动时再次发起升级),修改BUILD_MARKER,并调高IMG_VER_MINOR。将生成的build/rtl8721f/ota_all.bin复制到服务器主机上的某个目录。不要烧录这一份。通过 HTTP 提供该目录,例如:
$ python3 -m http.server 8000
第 1 步固件中的
OTA_SERVER_PORT和OTA_PATH必须与之一致(此处为端口8000、路径/ota_all.bin)。复位开发板。下载完成后它会自动复位,并打印新的
BUILD_MARKER。
当前运行的固件执行升级时的预期输出(省略 [wifi] join_status=... 行):
[build] <build timestamp>
[marker] A (currently running)
[wdg] enabled, timeout=5000ms
[wifi] on: 0
[wifi] connecting to "<ssid>" ...
[wifi] connect returned: 0
[NET] WiFi connected
[NET] MAC: xx:xx:xx:xx:xx:xx
[NET] waiting for DHCP ...
[NET] DHCP: IP=192.168.x.x
[ota] GET http://192.168.x.y:8000/ota_all.bin
[ota] programmed: fw_ver=... img_id=... body_len=... bytes
[PASS] ota-http: image committed to inactive slot, resetting
复位后,下载的固件的预期输出:
[build] <build timestamp>
[marker] <your new BUILD_MARKER>
[wdg] enabled, timeout=5000ms
[ota] REQUEST_OTA_UPDATE=false, skipping OTA this boot
fw_ver 取自 OTA 头的 version 字段,恒为 4294967295``(``0xFFFFFFFF),并不是固件版本号。Bootloader 打印的 IMG2 BOOT from OTA 2, Version: ... 才是固件自身的版本。中间还会夹杂 Wi-Fi 核和驱动打印的 [api]、[blk_api]、[WLAN-A] 等调试行。
服务器所在主机可达、但对应端口没有服务监听时,连接被拒绝:
[FAIL] ota-http: connect failed: Network(ConnectionReset)
当前网络无法到达服务器所在主机时,连接尝试会超时:
[FAIL] ota-http: connect to http://192.168.x.y:8000 timed out after 15s (server unreachable from this network?)
两种情况下,非活动槽都不会被提交,设备继续使用当前运行的固件。
OTA 过程中的看门狗
OTA 下载是该固件中耗时最长且不可中断的一段工作,值得明确地围绕它来设定看门狗刷新间隔,而不是靠试错。每次 flash 擦除/写入调用都会持有跨核 IPC 硬件锁,并在此期间**关闭中断**——每次写入前缓冲满一个 sector(参见 ameba_ota::storage::CHUNK_LEN)可以把这段时间控制在硬件实测最坏约 7 ms 以内(RTL8721F,100 MHz flash 时钟:sector 擦除 0.9–1.4 ms,sector 写入 4.8–7.1 ms)。刷新任务的周期只要明显大于这个数值——示例中使用的是相对 5 s 看门狗超时的 500 ms 刷新周期——就不会因为 flash 访问而被拖过截止时间。如果改用比一个 sector 更小的分块写入,只会增加持锁次数,并不会缩短单次持锁时长,反而会让 starvation 风险变得更糟。
看门狗还必须在任何触发 OTA 的判断逻辑*之前*启用,而不是之后:一旦启用,看门狗在软件层面不可逆,因此通过 OTA 到达的固件会发现看门狗已经在运行,必须从它的第一次启动开始就持续刷新,无论这次启动是否真的执行 OTA 相关工作。如果把看门狗的初始化放在"这次启动是否需要 OTA"的判断之后,就会产生重启死循环——刚下载的固件停在判断点,从未开始刷新,还没来得及自己启用看门狗就被(上一个固件启用的)看门狗复位。