ED-IPC和ED-HMI的OTA升级配置

1 概述

介绍ED-IPC和ED-HMI的OTA升级配置的背景、适用对象和适用范围。

1.1 背景

Raspberry Pi官方已发布Raspberry Pi Connect，支持通过远程推送更新的方式更新设备。受此影响，越来越多的ED-IPC和ED-HMI用户提出了远程升级的需求。为此，我司工程师已完成相关功能的开发与验证，并输出配套指导文档，助力用户顺利实现设备的OTA升级。

本文介绍如何通过rpi-image-gen创建A/B镜像，生成OTA升级包，并最终上传升级包完成设备更新，从而实现完整的OTA升级流程。

1.2 适用对象

熟悉Raspberry Pi产品的工程师
熟悉Raspberry Pi Connect服务的工程师

1.3 适用范围

本应用适用的产品型号如下：

软件范围	产品型号
标准的Raspberry Pi OS（Trixie）	基于Raspberry Pi 5的ED-IPC和ED-HMI： ED-IPC3020 ED-HMI3020-070C/101C ED-HMI3010-070C/101C/116C/133C/156C/185C/215C 基于Raspberry Pi 4的ED-HMI: ED-HMI2002-070C/101C 基于Raspberry Pi CM5的ED-IPC和ED-HMI： ED-IPC3100 ED-IPC3200 ED-IPC3400 ED-IPC3630 ED-HMI3120-070C/101C/116C/133C/156C/185C/215C ED-HMI3630-101C/116C/133C/156C 基于Raspberry Pi CM4的ED-IPC和ED-HMI： ED-IPC2000 ED-IPC2100 ED-IPC2200 ED-IPC2400 ED-IPC260 ED-HMI2020-070C/101C ED-HMI2120-070C/101C ED-HMI2220-070C/101C ED-HMI2630-101C

软件范围

产品型号

标准的Raspberry Pi OS（Trixie）

基于Raspberry Pi 5的ED-IPC和ED-HMI：
ED-IPC3020
ED-HMI3020-070C/101C
ED-HMI3010-070C/101C/116C/133C/156C/185C/215C
基于Raspberry Pi 4的ED-HMI:
ED-HMI2002-070C/101C
基于Raspberry Pi CM5的ED-IPC和ED-HMI：
ED-IPC3100
ED-IPC3200
ED-IPC3400
ED-IPC3630
ED-HMI3120-070C/101C/116C/133C/156C/185C/215C
ED-HMI3630-101C/116C/133C/156C
基于Raspberry Pi CM4的ED-IPC和ED-HMI：
ED-IPC2000
ED-IPC2100
ED-IPC2200
ED-IPC2400
ED-IPC260
ED-HMI2020-070C/101C
ED-HMI2120-070C/101C
ED-HMI2220-070C/101C
ED-HMI2630-101C

2. 配置指南

OTA升级配置的整体流程分为4个主要阶段：首先制作初始A/B镜像，然后基于该镜像生成增量OTA升级包，接着将升级包托管至云端并完成注册，最后远程下发更新并进行验证。

下文以Raspberry Pi 5为例，详细介绍这4个阶段的具体配置方法。

2.1 制作初始A/B镜像

在Raspberry Pi 5上制作A/B镜像包含以下4个步骤，请依次执行：

注册Raspberry Pi Connect账号并登录。
在Raspberry Pi 5上安装系统依赖。
在Raspberry Pi 5上通过rpi-image-gen生成镜像。
将生成的A/B镜像烧录至SD卡，进行备份。

2.1.1 登录Raspberry Pi账号并获取Connect密钥

前提条件：

已准备一台Windows电脑，正常启动后接入网络。

操作步骤：

在Windows PC的浏览器中输入网址：https://connect.raspberrypi.com/devices，进入Raspberry Pi ID登录界面。
通过Raspberry Pi账号进行登录。

提示

若未注册过Raspberry Pi账户，则单击“create one for free”来注册账户。

在打开的Raspberry Pi Connect界面选择“Settings”页签，再在“Auth key”右侧，单击“Create auth key”，创建Connect授权密钥。

将密钥复制后进行本地存储。

提示

密钥的有效使用时间为6小时，请提前计划好使用时间。

2.1.2 安装系统依赖

介绍在Raspberry Pi 5上安装系统依赖的操作步骤。

前提条件：

Raspberry Pi 5已正常启动并接入网络。
确保Raspberry Pi 5可以访问Github。

操作步骤：

更新软件源。

a. 打开Raspberry Pi 5的终端命令窗格，执行如下命令，打开/etc/apt/sources.list文件。

sudo nano /etc/apt/sources.list

b. 删除原文件中的所有内容，再添加以下内容。

deb https://mirrors.tuna.tsinghua.edu.cn/debian trixie main contrib non-free-firmware
deb https://mirrors.tuna.tsinghua.edu.cn/debian-security trixie-security main contrib non-free-firmware
deb https://mirrors.tuna.tsinghua.edu.cn/debian trixie-updates main contrib non-free-firmware

c. 输入ctrl+o保存文件，再按Enter，最后输入ctrl+x退出文件编辑模式。

更新系统源。
a. 打开Raspberry Pi 5的终端命令窗格，执行如下命令，打开/etc/apt/sources.list.d/raspi.list文件。
```
sudo nano /etc/apt/sources.list.d/raspi.list
```
b. 在文件中添加以下内容。
```
deb https://mirrors.tuna.tsinghua.edu.cn/raspberrypi trixie main
```
c. 输入ctrl+o保存文件，再按Enter，最后输入ctrl+x退出文件编辑模式。

在Raspberry Pi 5的终端命令窗格，依次执行如下命令，拉取rpi-image-gen工程并安装全套依赖。

git clone https://github.com/raspberrypi/rpi-image-gen.git
cd rpi-image-gen
sudo apt update
sudo ./install_deps.sh

2.1.3 生成A/B镜像

介绍通过rpi-image-gen生成镜像的操作步骤。

前提条件：

已获取Raspberry Pi Connect授权密钥。
Raspberry Pi 5已安装系统依赖。
已准备1张SD卡和1个读卡器。

操作步骤：

打开Raspberry Pi 5的终端命令窗格，执行如下命令，打开rpi-image-gen/examples/ota/config/ota.yaml文件。

sudo nano rpi-image-gen/examples/ota/config/ota.yaml

按需配置OTA参数。

version：镜像初始版本，首次填“1.0.0”；
hostname：设备唯一主机名，自定义设置；
packages：填写需要预装的工具。（第一次构建镜像无需填写，后续需要升级时再添加）

示例：

packages:
- python3
- iproute2
- ./local_pkgs/firmware.deb #软件包名

device：填写账户名和密码（第一次构建镜像需要填写，密码要包含字母大小写、数字、符号）。

示例：

device:
user1: pi
user1pass: Raspberry1!
user1sudo: passwd

locale：是系统区域本地化全套配置，设置语言、时区、键盘。（第一次需要填写）

示例：

locale:
default: en_US.UTF-8
keyboard_keymap: us
keyboard_layout: English (US)
timezone: Asia/Shanghai

输入ctrl+o保存文件，再按Enter，最后输入ctrl+x退出文件编辑模式。
执行如下命令，构建A/B镜像。

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_connect_authkey=rpuak_xxxx

其中rpuak_xxxx为前面步骤中保存的Raspberry Pi Connect密钥。

提示

通过./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_connect_authkey=rpuak_xxxx命令构建的A/B镜像只能用在基于Raspberry Pi 5和Raspberry Pi CM5的ED-IPC和ED_HMI上。
若需要构建用在基于Raspberry Pi 4/CM4的ED-IPC和ED-HMI上的A/B镜像，则可以使用如下命令。

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_device_layer=rpi4 IGconf_connect_authkey=rpuak_xxxx

A/B镜像构建完成后，在Raspberry Pi 5的/home/pi/rpi-image-gen/work/image-myapp/目录下获取镜像，其中镜像文件为myapp.img。

2.1.4 将A/B镜像烧录至SD卡

介绍将A/B镜像烧录至SD卡的操作步骤。

前提条件：

已在Raspberry Pi 5上完成A/B镜像的构建。
已准备1张SD卡和1个读卡器。

操作步骤：

将SD卡插入读卡器，再将读卡器插入Raspberry Pi 5的USB接口。
打开Raspberry Pi 5的终端命令窗格，执行如下命令，安装Raspberry Pi Imager。

sudo apt install rpi-imager

执行如下命令，启动Raspberry Pi Imager工具。

sudo rpi-imager

在左侧菜单栏中选择“OS”，在右侧的“Choose operating system”镜像文件列表的底部单击“Use custom”，再在/home/pi/rpi-image-gen/work/image-myapp/目录A/B镜像文件，再单击“OPEN”。

在左侧菜单栏中选择“Storage”，在右侧的“Select your storage device”中选择SD卡对应的盘符，再单击“NEXT”。
在左侧菜单栏中选择“Writing”，在右侧的“Write image”中确认镜像信息，再单击“NEXT”。
在弹出的提示框中单击“NEXT”，开始写入镜像。
待镜像写入完成后，会自动进行文件的验证。
文件验证完成后，“Done”菜单的右侧界面会显示“Write complete”，再单击右下角的“FINISH”，完成烧录。
断开读卡器与Raspberry Pi 5之间的连接，从读卡器中拔出SD卡。

提示

此处的烧录至SD卡仅为一种场景的示例。
若待升级的ED-IPC或ED-HMI不支持SD卡启动，可以将A/B镜像拷贝下来，再将A/B镜像通过eMMC烧录至待升级的ED-IPC或ED-HMI。

2.2 将待升级的ED-IPC或ED-HMI设备绑定至云端

介绍待升级的ED-IPC或ED-HMI设备绑定至云端的操作步骤。

前提条件：

已获取待升级的ED-IPC或ED-HMI设备（支持从SD卡启动）。
已获取被烧录A/B镜像的SD卡。

操作步骤：

将SD卡插入待升级的ED-IPC或ED-HMI设备的卡槽。
给ED-IPC或ED-HMI设备上电，正常启动设备，再输入用户名和密码登录设备。

提示

此处登录的用户名和密码，是在生成A/B镜像时通过OTA参数配置的。

再将ED-IPC或ED-HMI设备接入网络，使其可以正常上网。
在Windows电脑上登录Raspberry Pi Connect页面(https://connect.raspberrypi.com/devices)。在“Devices”页面的设备列表中查看ED-IPC或ED-HMI设备。

若包含ED-IPC或ED-HMI设备，则表示绑定成功。

在ED-IPC或ED-HMI设备的终端命令窗格，执行如下命令，查看系统版本信息。

cat /etc/rpi-issue

返回信息包含如下类似的内容，表示镜像部署正常：

Generated using rpi-image-gen e3828f885c860f15991468883d3b8484b0eaf9d8 on 2025-12-09
Artefact version: 1.0.0

2.3 生成OTA升级包

介绍在Raspberry Pi 5上生成OTA升级包的操作步骤。

前提条件：

已在Raspberry Pi 5上完成A/B镜像的构建。

操作步骤：

打开Raspberry Pi 5的终端命令窗格，执行如下命令，打开rpi-image-gen/examples/ota/config/ota.yaml文件。

sudo nano rpi-image-gen/examples/ota/config/ota.yaml

按需修改OTA参数。

version：建议从1.0.0升级为1.0.1。
packages: 需要添加升级的内容和所需的工具。

示例：

packages:
- python3
- iproute2
- ./local_pkgs/firmware.deb

python3和iproute2表示所需的apt包名。./local_pkgs/firmware.deb表示待升级的文件的本地路径。其中待升级的文件的目录参考如下：

rpi-image-gen/
└── examples/
    └── ota/                # -S 指定根目录
        ├── config/
        │   └── ota.yaml
        └── local_pkgs/     
            └── firmware.deb   # 私有deb放这里

执行如下命令，清理缓存。

sudo rm -rf ./work

执行如下命令，构建OTA升级包。

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml

提示

通过./rpi-image-gen build -S ./examples/ota/ -c ota.yaml命令构建的OTA升级包只能用在基于Raspberry Pi 5和Raspberry Pi CM5的ED-IPC和ED-HMI上。
若需要构建用在基于Raspberry Pi 4/CM4的ED-IPC和ED-HMI上的OTA升级包，则可以使用如下命令。

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_device_layer=rpi4

OTA升级包构建完成后，在Raspberry Pi 5的/home/pi/rpi-image-gen/work/image-myapp/目录下获取文件，其中文件为myapp.update.tar.zst。

2.4 OTA升级

介绍通过Raspberry Pi Connect进行OTA升级的操作步骤。

前提条件：

待升级的ED-IPC或者ED-HMI设备已正常启动并接入网络。
待升级的ED-IPC或者ED-HMI设备已在Raspberry Pi Connect页面的设备列表中显示。
已获取OTA升级包文件，并拷贝至Windows电脑的指定目录下。

操作步骤：

在Windows电脑上登录Raspberry Pi Connect页面(https://connect.raspberrypi.com/devices)。在“Devices”页面的设备列表中找到待升级的ED-IPC或ED-HMI设备。
单击设备信息右侧的“Deploy”。

在打开的“New deployment”界面的“File”区域上传OTA升级包（myapp.update.tar.zst文件）。

文件上传完成后，再单击“Deploy”。

在“Deployments”界面查看升级状态，若状态为“Succeeded”，则表示升级成功。

在升级的ED-IPC或者ED-HMI上，打开命令窗格，执行如下命令，查看版本信息。

cat /etc/rpi-issue

若返回信息中的Artefact version为新版本号，则表示升级成功。

3 常见问题

Q1：`authkey`密钥过期导致联网绑定失败

现象：

第一次构建A/B镜像时，报错信息显示验证密钥拒绝，无法登录云端

原因：

个人rpuak密钥的有效使用时间仅为6小时，备份后放置过久导致过期，故云端校验不通过。

解决方法：

在Raspberry Pi Connect页面重新生成新的authkey密钥，再重新构建A/B镜像。

Q2：构建A/B镜像时前未配置用户名和密码，设备开机后SSH/本地终端无法登录

现象：

烧录A/B镜像和OTA升级后重启设备，SSH输入任意密码均提示认证失败。
外接显示器和键盘后，通过用户名pi登录，密码错误。
构建日志打印 [SKIP] IGconf_device_user1pass，图层未写入用户登录密码。

原因：

构建A/B镜像时，ota.yaml 未填写 user1pass 密码配置。
配置中开启 openssh.pubkey_only=y，仅允许密钥登录，未预置SSH公钥，密码登录直接失效。
构建参数缺失用户配置项，镜像中pi用户为空密码/禁用密码登录。

解决方法：

修改examples/ota/config/ota.yaml中用户和密码的完整信息，如下面示例中的user1、user1pass和user1sudo的信息。

device:  
	user1: pi  
	user1pass: Raspberry1!  
	user1sudo: passwd 
openssh:  
	pubkey_only: n

重新构建A/B镜像和OTA升级包，再对设备进行重新烧录和升级。

Q3：升级后的设备dpkg查询升级的deb包

现象：

进行OTA升级的设备，通过dpkg查询不到升级的deb包，但是本地deb包的功能生效。

原因：

在image-rota的A/B分区架构中，/var 按系统槽位独立存储于持久化分区中，并在设备首次烧录镜像时创建。默认的OTA升级仅包含boot和system分区内容，不会同步更新对应的/var数据。因此OTA升级后，dpkg 数据库仍可能保留初始镜像的软件包记录，与当前运行的系统不一致；但新系统中的程序文件不受影响，仍可正常运行。