企业官网建设流程全解析

librealsense Viewer 软件与固件更新机制全解析：在线版本数据库、更新通知流程与 rs-fw-update 刷写实战

【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense

librealsense 的 RealSense Viewer 内置了一套完整的软件（SW）与固件（FW）更新通知与刷写体系：它既能通过在线版本数据库自动或手动检测新版本，也能在无网络环境下加载本地版本库，还支持通过图形界面或rs-fw-update命令行工具完成固件烧录。本文将围绕doc/viewer-sw-fw-update.md的说明，结合仓库源码（updates-model.cpp、device-model.cpp、rs-fw-update.cpp 等）深入讲解其触发方式、版本策略、底层实现与实战操作，读完即可完全掌握 Viewer 更新功能的使用与原理。

更新通知的两种触发方式

Viewer 支持手动触发与自动触发两种方式，源码中的入口统一收敛到device_model::check_for_device_updates（device-model.cpp）：

• 手动触发：用户在界面上点击Check for updates按钮，此时activated_by_user参数为true，Viewer 会立即发起一次更新检查。
• 自动触发：每当连接一台新设备时，Viewer 自动执行一次更新检查，并以通知（notification）的形式提示用户。

值得注意的一个细节是：check_for_device_updates会在独立的std::thread中执行（device-model.cpp），避免网络请求阻塞 UI 主线程；同时用std::weak_ptr持有updates_model、update_profile和notifications_model，防止线程生命周期与界面对象解绑时产生悬挂引用。

在线更新：版本数据库（Versions DB）

更新数据的来源

Viewer 进行在线更新检查时，会向一个**版本数据库（versions database）**发起下载请求，并基于"当前连接设备所对应的推荐版本"生成更新通知。版本数据库的默认地址定义在 device-model.h：

constexpr const char* server_versions_db_url = "https://librealsense.realsenseai.com/Releases/rs_versions_db.json";

该 URL 在 Viewer 启动时被写入配置文件默认值（ux-window.cpp）：

config_file::instance().set_default(configurations::update::sw_updates_url, server_versions_db_url); config_file::instance().set_default(configurations::update::sw_updates_official_server, true);

也就是说，配置键update.sw_update_url（device-model.h）决定了版本数据库的位置，默认指向官方服务器。

数据库的下载与解析

版本数据库的下载与解析由versions_db_manager完成（versions-db-manager.h）。该类的注释明确说明：版本文件既可以存放在本地文件系统，也可以放在 HTTP 服务器上。构造时传入use_url_as_local_path标志即可切换两种来源：

explicit versions_db_manager( const std::string & url, const bool use_url_as_local_path = false, http::user_callback_func_type download_callback = ... );

而check_for_device_updates中对 URL 的预处理展示了本地文件的具体用法（device-model.cpp）：

std::string server_url = config_file::instance().get( configurations::update::sw_updates_url ); bool use_local_file = false; const std::string local_file_prefix = "file://"; // If URL contain a "file://" prefix, we open it as local file and not downloading // it from a server if( server_url.find( local_file_prefix ) == 0 ) { use_local_file = true; server_url.erase( 0, local_file_prefix.length() ); } sw_update::dev_updates_profile updates_profile( dev, server_url, use_local_file );

只要在配置的 URL 前加上file://前缀，Viewer 就会把它当作本地文件路径读取，而不是去网络下载。这在离线环境或内网部署场景下非常实用。

网络层实现与编译开关

网络下载基于 libcurl 实现，见 http-downloader.cpp。其中设置了 5 秒的连接超时（CONNECT_TIMEOUT = 5L）以及 0.5 秒的用户回调间隔（HALF_SEC = 500000）。关键点是：整个在线更新链路受CHECK_FOR_UPDATES编译宏控制，未定义该宏时http_downloader的所有方法都是返回false的"哑实现"（http-downloader.cpp），Viewer 设置面板中的服务器配置入口也会被编译掉（见下文）。这意味着在线更新是一个可选特性，构建时可按需启用或裁剪。

版本策略与组件类型

版本数据库的核心抽象定义在 versions-db-manager.h，它使用两组枚举描述更新维度：

更新策略（update_policy_type）：

组件类型（component_part_type）：

此外还有来源类型（FROM_FILE/FROM_SERVER）与查询状态（VERSION_FOUND/NO_VERSION_FOUND/DB_LOAD_FAILURE）。

数据库记录的每个版本条目包含以下字段（versions-db-manager.h）：policy（策略）、component（组件）、version（版本号）、platform（平台）、link（下载链接）、device_name（适用设备名）、rel_notes_link（发布说明链接）、desc（描述）。

设备更新档案（dev_updates_profile）

针对每一台具体设备，Viewer 会构建一个"设备更新档案"（dev_updates_profile，见 dev-updates-profile.h），它把数据库查询结果与设备自身信息整合成一个完整的update_profile：

• device_name、serial_number、fw_update_id：设备标识；
• software_version、firmware_version：设备当前的 SDK 版本与固件版本；
• software_versions、firmware_versions：数据库中各策略可用的候选版本集合。

其中当前软件版本直接取自编译期宏RS2_API_FULL_VERSION_STR，固件版本则从设备信息RS2_CAMERA_INFO_FIRMWARE_VERSION读取（dev-updates-profile.cpp）。

版本比较逻辑

retrieve_updates（dev-updates-profile.cpp）按EXPERIMENTAL → RECOMMENDED → ESSENTIAL三个策略依次查询数据库，并将数据库中版本高于当前版本的条目收录进候选集合。其中有两个值得注意的实现细节：

1. 软件版本忽略构建号：对于LIBREALSENSE组件，比较前会调用ver.without_build()，只比较主版本号、次版本号和补丁号（dev-updates-profile.cpp）；
2. 一次 DB 访问失败后不再重试：_keep_trying标志会在首次DB_LOAD_FAILURE后被置为false（dev-updates-profile.cpp），避免反复访问不可达的服务器。

当前retrieve_updates仅支持LIBREALSENSE与FIRMWARE两个组件，对其他组件会直接抛出std::runtime_error（"update component ... not supported"）。

更新通知逻辑流程

原文档给出了完整的更新判定时序图，其流程可概括为：

1. 用户连接设备或点击"Check For Updates"，触发更新检查；
2. Viewer 尝试下载版本数据库（Try Download DB）；
3. 数据库下载成功时，依次判定：
   • 是否存在SW/FW 必要更新（ESSENTIAL）→ 是则弹出"必要更新窗口（Show essential updates window）"，流程结束；
   • 否则判定是否存在SW 推荐更新→ 是则显示软件更新通知；
   • 否则判定是否存在FW 推荐更新→ 是则显示固件更新通知；
   • 否则进入"捆绑固件检查"环节。
4. 数据库下载失败时，进一步判断是否为用户手动触发：
   • 用户手动触发 → 直接进入"捆绑固件检查"；
   • 自动触发 → 显示"访问数据库错误"通知，流程结束。
5. 捆绑固件检查：对比设备固件版本与捆绑固件版本，不一致则显示固件更新通知。

图中的updates.png位于 doc/img/updates/updates.png，其可编辑源文件为同目录下的updates.drawio。

源码中的对应实现

上述流程在 device-model.cpp 中有完整对应：

bool sw_online_update_available = updates_profile.retrieve_updates( sw_update::LIBREALSENSE, fail_access_db); bool fw_online_update_available = updates_profile.retrieve_updates( sw_update::FIRMWARE, fail_access_db);

• 发现必要更新（ESSENTIAL）时，直接add_profile加入更新列表，Viewer 会弹出Updates Window 模态窗口，同时向日志系统写入警告级别的设备名、序列号、当前版本与必要版本信息（device-model.cpp）；
• 只有推荐更新时，且当前没有必要更新窗口打开（!viewer_updates->has_updates()），才生成软件/固件更新通知，避免弹窗叠加；
• 用户手动触发且数据库访问失败时，会显示"无法获取更新，请检查网络连接"的错误通知（Unable to retrieve updates. Please check your network connection.，device-model.cpp）；
• 手动触发且无可用更新时，会显示"已是最新"（up to date）提示，该通知带delay_id = "no_updates_alert.<serial>"，同一设备一段时间内不会重复打扰。

Viewer 更新窗口与固件刷写状态机

Updates Window 界面

更新窗口由updates_model::draw渲染（updates-model.cpp），窗口以SOFTWARE UPDATES为标题弹出，尺寸为窗口宽度的 60%、高度 600 像素，不可缩放、不可移动。窗口分上下两个面板：

• 上方面板（Software）：显示 SDK 当前版本、"Essential update is available. Please install!" / "Recommended update available!" / "Up to date." 等状态文案、内容说明、目的说明、候选版本下拉框（多于一个版本时）、Release 链接与描述，以及Download按钮（点击后调用open_url打开下载链接，updates-model.cpp）。
• 下方面板（Firmware）：显示设备名称与序列号、当前固件版本、"Signed Firmware Image (.bin file)" 内容说明、候选版本选择与Download & Install按钮。

窗口底部的关闭逻辑体现了"必要更新"的强制语义（updates-model.cpp）：只要存在必要更新，就必须勾选"I understand and would like to proceed anyway without updating"复选框才能关闭窗口；不勾选时点击 Close 只会让提示文字以红色高亮强调（emphasize_dismiss_text），并弹出工具提示 "To close this window you must install all essential update or agree to the warning of closing without it"。

固件刷写状态机

固件刷写的完整生命周期由updates_model中的状态机驱动（updates-model.h）：

点击Download & Install后（updates-model.cpp），Viewer 会在独立线程中用http_downloader把固件镜像下载到内存字节数组_fw_image，并通过回调实时更新下载进度（_fw_download_progress）。下载完成后进入started状态，创建firmware_update_manager（fw-update-helper.h）执行实际刷写，进度条此时显示刷写进度；失败状态下界面会给出 "Firmware download failed, check connection and press to retry" 或 "Firmware update process failed, press to retry" 的重试按钮。

firmware_update_manager::process_flow（fw-update-helper.cpp）在刷写前会做几件关键工作：检查是否为 MIPI 设备（走专门的process_mipi_signed_fw流程）、清空旧的更新通知、以及调用check_fw_compatibility校验固件与设备的兼容性，不兼容时中止并提示 "The firmware version is not compatible with ..."。

固件获取：SDK 不再内置固件二进制

原文档明确指出一个重要的版本策略变化：SDK 不再随安装包附带（bundled）固件二进制文件。也就是说，你无法再从 SDK 安装目录中直接找到可用的固件文件，而需要：

1. 前往RealSense 固件发布页，根据设备型号下载对应的.bin固件镜像文件（注意仅使用已签名的正式发布固件）；
2. 通过以下任一方式刷写：
   • Viewer 图形界面：在Update Firmware...菜单中加载下载好的.bin文件；
   • 命令行工具：rs-fw-update -f <path-to-bin>。

由于固件发布页属于外部站点，具体链接请以 RealSense 官方固件发布渠道为准；建议在下载前先核对发布说明，确认固件版本与你的设备型号及当前固件版本的兼容关系。

Viewer 手动固件更新

Viewer 中通过Update Firmware...菜单手动刷写时（device-model.cpp），会创建firmware_update_manager并生成一个名为 "Manual Update requested" 的更新通知，随后在一个回调中启动刷写流程。如果用户中途取消，流程会在确认后安全退出，不写入任何数据。

rs-fw-update 命令行刷写工具实战

rs-fw-update是独立于 Viewer 的命令行固件管理工具，源码位于 tools/fw-update/rs-fw-update.cpp，构建后可直接调用。其完整的命令行参数定义如下（rs-fw-update.cpp）：

基本用法示例

列出所有可用设备：

rs-fw-update -l

向指定设备刷写固件：

rs-fw-update -f <path-to-bin> -s <serial_number>

备份相机固件：

rs-fw-update -b <backup-path>

恢复恢复模式设备：

rs-fw-update -r -f <path-to-bin>

使用注意事项

• 多设备场景：当同时连接多台相机时，未指定-s会提示"请使用序列号参数指定需要更新固件的设备"（rs-fw-update.cpp），因此务必带上序列号，避免刷错设备；
• 固件文件校验：工具在读取固件文件时会校验文件可读性与大小，失败会直接报 "Error reading firmware file" 并退出；
• 兼容性检查：与 Viewer 相同，工具在刷写前会校验固件与设备的兼容性（"This firmware version is not compatible with ..."），不兼容时中止；
• 设备重连等待：刷写过程中设备会重启，工具默认有 15 秒的设备等待超时（WAIT_FOR_DEVICE_TIMEOUT 15，rs-fw-update.cpp）；
• 执行刷写前建议先备份固件（-b），以便在需要时恢复。

服务器配置与离线场景

在 Viewer 的设置界面（受CHECK_FOR_UPDATES宏保护，viewer.cpp）中，可以通过 "SW/FW Updates From Server:" 区域配置版本数据库来源：

• Official Server（官方服务器）：默认选项，使用内置的官方版本数据库地址；
• Custom Server（自定义服务器）：可输入任意 HTTP(S) 地址，在地址前添加file://前缀即可改用本地数据库文件（界面工具提示 "Add file:// prefix to use a local DB file"）。

修改配置后点击 OK，若检测到更新源发生变化，Viewer 会重新触发各设备的通知刷新（refresh_updates，viewer.cpp）。

这一设计为以下场景提供了完整支持：

1. 内网/离线环境：把rs_versions_db.json放到本地或内网服务器，通过自定义 URL 指向它，Viewer 依然能提供完整的更新检查体验；
2. 企业统一管控：由运维侧维护版本数据库，统一指定各设备的推荐版本与必要版本；
3. 开发调试：自定义数据库便于验证不同策略（ESSENTIAL/RECOMMENDED）组合下的界面行为。

常见问题与排查建议

• 点击检查更新后提示 "Unable to retrieve updates. Please check your network connection."：说明版本数据库下载失败（DB_LOAD_FAILURE）。请检查网络连通性、代理设置，或改用file://本地数据库；
• 始终显示 "No online SW / FW updates available"：说明数据库可访问但当前设备版本已不低于数据库中的所有候选版本（含without_build版本比较逻辑）；
• 固件下载失败：检查网络连接后，可在更新窗口中直接点击重试按钮，状态机会从failed_downloading回到ready并重新下载；
• 固件刷写失败：确认.bin文件与设备型号匹配、固件已正确签名（未解锁设备只能刷签名固件），必要时用rs-fw-update -b先备份，再尝试恢复模式（-r）刷写；
• 更新窗口无法关闭：存在必要更新（ESSENTIAL）时，需要勾选底部的免责声明复选框才能关闭——这是有意设计，用于确保用户知悉设备处于低于必要版本的状态。

小结

librealsense Viewer 的 SW/FW 更新体系是一条完整、可配置、有状态机保障的链路：版本数据库（versions DB）→ 设备更新档案（dev_updates_profile）→ 更新窗口（updates_model）→ 固件刷写（firmware_update_manager）。理解 ESSENTIAL/RECOMMENDED/EXPERIMENTAL 三级策略、file://本地数据库能力以及rs-fw-update的完整参数，即可在常规联网、离线内网乃至设备故障恢复等多种场景下，安全可靠地完成 RealSense 相机的软件与固件维护。

相关参考资料：viewer-sw-fw-update.md、updates-model.cpp、dev-updates-profile.cpp、versions-db-manager.h、rs-fw-update.cpp。

【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense