librealsense Viewer 软件与固件更新机制全解析在线版本数据库、更新通知流程与 rs-fw-update 刷写实战【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsenselibrealsense 的 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_updatesdevice-model.cpp手动触发用户在界面上点击Check for updates按钮此时activated_by_user参数为trueViewer 会立即发起一次更新检查。自动触发每当连接一台新设备时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.hconstexpr const char* server_versions_db_url https://librealsense.realsenseai.com/Releases/rs_versions_db.json;该 URL 在 Viewer 启动时被写入配置文件默认值ux-window.cppconfig_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_urldevice-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.cppstd::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.cppViewer 设置面板中的服务器配置入口也会被编译掉见下文。这意味着在线更新是一个可选特性构建时可按需启用或裁剪。版本策略与组件类型版本数据库的核心抽象定义在 versions-db-manager.h它使用两组枚举描述更新维度更新策略update_policy_type策略含义EXPERIMENTAL实验版本不主动推荐RECOMMENDED推荐版本常规升级目标ESSENTIAL必要版本低于该版本将影响设备正常使用组件类型component_part_type组件说明LIBREALSENSElibrealsense SDK 本体VIEWERRealSense Viewer 工具DEPTH_QUALITY_TOOLDepth Quality ToolFIRMWARE相机固件此外还有来源类型FROM_FILE/FROM_SERVER与查询状态VERSION_FOUND/NO_VERSION_FOUND/DB_LOAD_FAILURE。数据库记录的每个版本条目包含以下字段versions-db-manager.hpolicy策略、component组件、version版本号、platform平台、link下载链接、device_name适用设备名、rel_notes_link发布说明链接、desc描述。设备更新档案dev_updates_profile针对每一台具体设备Viewer 会构建一个设备更新档案dev_updates_profile见 dev-updates-profile.h它把数据库查询结果与设备自身信息整合成一个完整的update_profiledevice_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_updatesdev-updates-profile.cpp按EXPERIMENTAL → RECOMMENDED → ESSENTIAL三个策略依次查询数据库并将数据库中版本高于当前版本的条目收录进候选集合。其中有两个值得注意的实现细节软件版本忽略构建号对于LIBREALSENSE组件比较前会调用ver.without_build()只比较主版本号、次版本号和补丁号dev-updates-profile.cpp一次 DB 访问失败后不再重试_keep_trying标志会在首次DB_LOAD_FAILURE后被置为falsedev-updates-profile.cpp避免反复访问不可达的服务器。当前retrieve_updates仅支持LIBREALSENSE与FIRMWARE两个组件对其他组件会直接抛出std::runtime_errorupdate component ... not supported。更新通知逻辑流程原文档给出了完整的更新判定时序图其流程可概括为用户连接设备或点击Check For Updates触发更新检查Viewer 尝试下载版本数据库Try Download DB数据库下载成功时依次判定是否存在SW/FW 必要更新ESSENTIAL→ 是则弹出必要更新窗口Show essential updates window流程结束否则判定是否存在SW 推荐更新→ 是则显示软件更新通知否则判定是否存在FW 推荐更新→ 是则显示固件更新通知否则进入捆绑固件检查环节。数据库下载失败时进一步判断是否为用户手动触发用户手动触发 → 直接进入捆绑固件检查自动触发 → 显示访问数据库错误通知流程结束。捆绑固件检查对比设备固件版本与捆绑固件版本不一致则显示固件更新通知。图中的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状态含义ready就绪等待触发downloading正在下载固件镜像started下载完成开始刷写设备completed刷写完成failed_downloading固件下载失败failed_updating固件刷写失败点击Download Install后updates-model.cppViewer 会在独立线程中用http_downloader把固件镜像下载到内存字节数组_fw_image并通过回调实时更新下载进度_fw_download_progress。下载完成后进入started状态创建firmware_update_managerfw-update-helper.h执行实际刷写进度条此时显示刷写进度失败状态下界面会给出 Firmware download failed, check connection and press to retry 或 Firmware update process failed, press to retry 的重试按钮。firmware_update_manager::process_flowfw-update-helper.cpp在刷写前会做几件关键工作检查是否为 MIPI 设备走专门的process_mipi_signed_fw流程、清空旧的更新通知、以及调用check_fw_compatibility校验固件与设备的兼容性不兼容时中止并提示 The firmware version is not compatible with ...。固件获取SDK 不再内置固件二进制原文档明确指出一个重要的版本策略变化SDK 不再随安装包附带bundled固件二进制文件。也就是说你无法再从 SDK 安装目录中直接找到可用的固件文件而需要前往RealSense 固件发布页根据设备型号下载对应的.bin固件镜像文件注意仅使用已签名的正式发布固件通过以下任一方式刷写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短参数长参数参数值说明-l--list_devices—列出所有可用设备-r--recover—恢复所有处于恢复模式recovery mode的连接设备-u--unsigned—更新未签名固件仅适用于已解锁unlocked的相机-b--backuppath将相机 flash 备份到指定路径-f--filepath固件镜像文件路径.bin-s--serial_numberstring目标设备序列号连接多台设备时必填基本用法示例列出所有可用设备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 15rs-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_updatesviewer.cpp。这一设计为以下场景提供了完整支持内网/离线环境把rs_versions_db.json放到本地或内网服务器通过自定义 URL 指向它Viewer 依然能提供完整的更新检查体验企业统一管控由运维侧维护版本数据库统一指定各设备的推荐版本与必要版本开发调试自定义数据库便于验证不同策略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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考