127 lines
20 KiB
Markdown
127 lines
20 KiB
Markdown
# 杭研项目：集成、调试与交付
|
||
|
||
用于已确认的杭研项目（例如 HangYan、CMCC_HANGYAN 工程）。只开展当前任务涉及的检查；本章不扩大主 Skill 的修改、测试、发布或设备操作权限。
|
||
|
||
未另标日期的 YT42 案例来自 LY-SM-YT42_AI 在 2026-09-14 至 2026-09-16 的开发与打包记录；标为 2026-09-22 的内容来自本轮代码纠正、制包及证书生成记录。不同日期的 PSP 批次和分区布局分别看待。这些案例说明当时的问题，不代表当前代码仍存在同样问题。型号、分辨率、目录、分区容量、工具参数和驱动名称均不是杭研项目的统一默认值。引用历史结果时标明来源；历史日志不可用时，不得补造证据或声称已经重新核验。
|
||
|
||
## 1. 工程搭建与 PSP 集成
|
||
|
||
- 先确认目标工程、参考工程和 PSP 的归属。拉取前检查目标目录是否为空、是否已有独立仓库或子模块、是否存在本地修改；不能用覆盖整个目录的方式消除差异，也不能把普通克隆误报为已登记的子模块。
|
||
- 记录本次采用的 PSP 仓库、分支、提交、BSP 批次及本地适配差异。已有资源锁定清单时核对实际文件大小和哈希；没有清单时如实说明可核验范围，不凭文件名相同认定是同一批资源，不强制新建一套清单体系。
|
||
- 沿工程配置的复制映射核对输入来源与落点。绝对资源路径、共享资源软链接和版本目录都要检查实际可读性；配置 JSON 能解析不等于 BSP、媒体组件、驱动和模型已经齐全。
|
||
- 集成前对照用户已确认的产品要求，列出传感器数量、应用通道、媒体参数、驱动、分区及文件系统差异。远程版本更新不自动代表用户同意改变产品定义；冲突未解决时，不擅自改通道、分区或硬件能力来迁就新 PSP。
|
||
- 按确认范围处理必要集成改动，尽可能保持参考工程的目录和构建方式。发现与当前任务无关的旧问题，只说明，不顺带修复；不因一次核验就新增工程级校验脚本或中心跟踪文档。
|
||
|
||
YT42 案例：空 PSP 目录恢复后，新仓库提供了单 MIS40C1 配置、不同的分区布局和 BSP 批次，而应用侧还保留双通道设置。资源恢复、打包通过、产品拓扑一致是三项不同结论；单／双通道差异当时尚未完成设备验证，不能写成已经发生的设备故障。
|
||
|
||
## 2. 媒体通道与平台清晰度：同一路码流切换分辨率
|
||
|
||
- 根据用户已确认的杭研平台约定，平台切换清晰度时，本地在同一路码流对应的当前编码通道上切换分辨率，不是通过切换主／副码流实现清晰度切换。排查或适配时，沿平台清晰度指令、分辨率映射、本地支持范围校验到当前编码通道配置更新逐项核对；不能自行改成选择另一条码流。其他项目明确采用不同接口约定时，以该项目确认结果为准。
|
||
- 分清平台逻辑通道、传感器、VI／VPSS 通道和编码通道。“同一路码流切换分辨率”不代表整台设备只有一路码流，也不排斥多镜头同步。已确认需要同步的双镜头项目，是各镜头在各自对应的当前码流上同步调整分辨率，不能误解为在两个镜头或主／副码流之间切换。
|
||
- 用户确认的平台同步行为和本地分辨率白名单属于功能约束。平台可能下发本地媒体链不支持的分辨率，必须保留本地显式分辨率判断；不能仅因代码看似冗余，就删除清晰度同步或放开不支持的分辨率。
|
||
- 修改已授权的码流分辨率时，核对编码默认值、支持范围、VPSS 输出、缓冲池、同源抓图及应用能力声明。只调整实际受影响的依赖；AI、移动侦测、解码通道的尺寸可能独立，不能把所有相同数字批量替换。
|
||
- PSP 通道数变化时，对照直播、RTSP、录像、抓图和平台能力配置。编译通过不能证明旧通道编号仍有效；不通过虚构通道或固定成功返回补齐差异。
|
||
- 产品文档、平台 FAQ 与当前接口能力冲突时，区分“文档记载”“用户或平台确认”“设备实测”。按已确认需求处理并保留依据，不能单凭过期文档认定不兼容，也不能把一个产品的确认推广到所有 SDK 版本。
|
||
|
||
YT42 已确认约定：平台只下发一个通道的清晰度时，两个镜头仍需同步切换各自当前码流的分辨率，保留 syncCfg 同步逻辑及本地显式分辨率判断。副码流保持 640×360 是独立配置要求，不表示平台清晰度切换通过选择副码流实现；导入的 640×640 配置需要做关联核对，AI 通道尺寸不随之修改。双镜头同步、syncCfg 和上述固定尺寸均为该项目约定，不作为所有杭研产品的默认配置。这里记录的是用户确认的设计，不代表已经完成设备实测。
|
||
|
||
### AvPush、OSD 与 VoIP 分别核对
|
||
|
||
- AvPush：沿用已确认参考工程的流标识和当前 VENC 订阅。YT70 参考实现固定使用 `OVD_HIGH_STREAM`，清晰度由同一路 VENC 的分辨率决定；不能从“本地有副码流”推导出平台需要增加 `OVD_LOW_STREAM`、双路音频发送或按清晰度选择 VENC。发现双路代码时还要核对配置是否启用，不能把未启用的分支说成已发生的重复推流。
|
||
- OSD：当前推送通道的字体和 Logo 随该通道目标分辨率更新，核对 OSD 与 VENC 的实际绑定。参考工程为本地副码流同步文字、开关和位置，并按副码流尺寸设置字号及 Logo，是独立的本地处理；不能因为平台只推一路，就删除这部分已有功能。
|
||
- OSD 主、副码流需要分别修改参数时，避免复用可变对象。`MediaOsd::Param::array` 保存 `shared_ptr`，只复制外层容器仍会共享元素；需要逐项复制后再改字号和 Logo。检查当前镜头对应的副通道是否存在，不用“总通道数大于 1”代替具体通道检查。不额外引入没有需求依据的裁剪、文件命名约束或自动关闭 Logo 行为。
|
||
- VoIP：先查本模块的协商规则，不把安防 AvPush 的约定直接套到对讲。YT70 在协商参数匹配主码流时复用主码流，否则使用副码流并调整编码格式、保留副码流分辨率。没有新需求或当前问题证据时保留该实现；不要新增“必须完全匹配已有流才允许推送”的限制，导致接通后不发送视频。是否允许降分辨率由具体接口和已确认需求决定。
|
||
|
||
2026-09-22 纠正记录：YT42 移植曾新增 AvPush 双路推送、OSD 裁剪和 VoIP 完全匹配限制，随后按 YT70 基线纠正；VoIP 两个回调文件恢复到基线，OSD 保留本地副码流处理并隔离参数。这些改动完成了交叉编译，没有样机通话或画面实测证据，不能据此宣称功能联调通过。
|
||
|
||
## 3. 启动流程与网络驱动
|
||
|
||
- 区分驱动文件存在、设备枚举正常、模块可手动加载、接口可拉起、扫描可用和开机自动初始化成功。这些证据分别缩小排查范围，不能互相替代。
|
||
- 检查实际启动链：源加载脚本 → 复制映射 → 打包目录 → 包内脚本 → 启动调用点。修复应落在会被构建使用的源文件；只修改生成目录中的副本会被下次构建覆盖。
|
||
- 相对路径加载模块时核对工作目录。检查设备 ID／模块 alias、完整内核 vermagic、模块依赖及加载顺序；内核主版本相同或模块文件同名不足以证明兼容。
|
||
- 核对网络服务启动时接口是否已准备好。若手动加载成功而开机失败，先核对自动加载链；不能未经授权扩展为网络服务重试、驱动替换或硬件初始化重写。
|
||
- 打包任务中，从最终 ROM 提取加载脚本和相关驱动核验内容、哈希与顺序。没有设备启动日志时，只报告包内检查通过，不宣称开机网络恢复。
|
||
|
||
YT42 案例：设备手动加载 8188fu.ko 后能够创建 wlan0 并扫描 AP，但开机加载源脚本只包含电机模块。问题位于自动加载链；该项目修复后的顺序是先 Wi-Fi，再 MotorGpio，不能把这一顺序规定为所有产品的要求。
|
||
|
||
## 4. AI 插件与 DATA 资源
|
||
|
||
- ROM 过大时，先检查大文件归属和实际复制落点。PSP 已设计独立 DATA 存放 AIPlugin 时，应用打包应遵循该设计，排除 AI 库、模型重复或错误进入 firmware。先解决资源放错分区的问题，再判断压缩参数或容量是否需要调整；其他项目脚本中的固定参数不能直接代替当前 PSP 配置。
|
||
|
||
- 对照资源准备目录、插件配置、分区映射、启动挂载点和运行时路径，确认它们指向同一套资源。变量名为 aiData、目录名为 data 或 AiData，不足以判断实际打包与加载位置。
|
||
- 核对实际启用算法所需的插件库、模型、配置及依赖版本。模型目录或算法清单存在，不代表所有被引用文件都在包内；也不要把注册表列出的所有可选模型都无条件加入固件。
|
||
- 区分随包实体文件与指向设备可写目录的运行时软链接。按项目清单规则分别验证实体内容和链接语义；不要把指向设备运行时目录的链接当作主机上的普通目录递归遍历，也不能为消除哈希错误而忽略全部链接或删掉必要资源。
|
||
- 根据当前分区大小、页大小、PEB／LEB 几何参数、UBI 开销及坏块预留核对镜像工具参数和容量余量。不要直接沿用旧分区的最大 LEB 参数，也不要把“总块数减二”当作通用公式。检查实际生成结果及目标挂载方式。
|
||
- 普通 OTA、平台加密包和整片镜像可能覆盖不同分区。分别验证各包是否携带 AI 资源；普通 ROM 未携带 DATA 时，说明它不会更新该分区，并检查新应用对设备现存资源的版本要求。
|
||
|
||
YT42 案例：PSP 的 DATA 从 14 MiB 变为 36 MiB，旧容量参数已不能容纳新资源组合，需按新布局适配。普通 OTA 仍未包含 DATA，整片镜像则包含；不能用整片镜像内模型齐全来证明一次普通 OTA 会更新模型。
|
||
|
||
2026-09-22 制包记录：当时 YT42 使用 firmware 19 MiB、DATA 14 MiB，AIPlugin 误放 firmware 导致超限；按 PSP 设计移入 DATA 后打包通过。这与前述历史布局是不同批次，不能照搬容量和 UBIFS 参数。
|
||
|
||
## 5. 编译打包与版本凭证
|
||
|
||
### 构建前核对
|
||
|
||
- 阅读当前准备、编译、发布及其调用的镜像脚本，确认工作目录、必需参数、清理范围、版本策略和输出规则。历史成功命令只是线索；脚本可能已新增显式版本参数，不能直接照抄旧命令或自行按日期生成版本。
|
||
- 按已确认策略确定版本，检查同名输出是否存在，避免覆盖历史发布包。用户要求重新打包时，确认应用和镜像确由本次流程生成；文件存在或时间戳更新不能单独证明完成了全量构建。
|
||
- 构建脚本会重建目录时，先识别已有生成文件、缓存和正在使用的构建目录。只处理明确属于本次流程的目标；需要保留的旧内容使用可恢复备份，不清理无关修改。
|
||
- 在耗时制包前核对“实际镜像生成工具／参数 → 容器内文件系统 → BSP 启动挂载方式”。读取脚本和实际启动配置，必要时解析已有底层镜像；名为 ubi 的脚本或 UBI 容器不代表其中必然是 UBIFS。
|
||
|
||
### 执行、异常与重试
|
||
|
||
- 分别记录关键步骤的标准输出、标准错误、实际退出码、工作目录、开始和结束时间。使用重定向或管道时及时保存原命令状态，避免被 tee、tail 或后续命令的退出码替代。
|
||
- EmxGitInfo 等工具可能在 Git 命令失败后仍返回 0。区分“命令退出码”“有效提交凭证”“源码有本地改动”；不得伪造提交，不得为通过检查擅自提交或清理。用户允许缺少提交信息的开发验证时，说明凭证缺口；正式发布是否接受该缺口，按项目已确认的准入规则判断。
|
||
- 检查包装脚本是否忽略子命令状态。编译、安装、镜像生成、加密、复制及扫描需要结合各自日志和预期产物判定，不能只凭最外层退出码或“Build done”认定成功。
|
||
- 对空目录通配符等提示，核实对应资源是否本来就可选；对真实缺文件、容量超限、加密失败等错误，不能一概降为警告。用户只授权重打包时，先报告需要改动的原因和范围，不顺带修脚本。
|
||
- 遇到 binwalk 等扫描失败，保留每个包的独立结果，避免后一次扫描覆盖前一次证据。扫描命中需结合包格式分析，不能凭签名名称认定缺陷或误报；扫描无命中也不代表包内内容正确。
|
||
- 自动重试应有明确上限和停止条件。若根因不会随重试改变，停止本次受控流程并说明；不无限重包，不擅自关闭检查或反复换版本追求通过。停止进程前确认它确属本次构建，不影响其他任务。
|
||
- 已知不合格候选包与最终交付包分开放置，记录失败原因和真实执行结果；不得把旧包当作新包交付，也不凭顶层返回 0 放行已知格式错误的包。
|
||
|
||
### 最终产物核验
|
||
|
||
- 分清源码修正、目标程序编译、安装到打包目录、重新制包及包内核验。后续只编译了 `DxMain` 时，旧 ROM 不包含该次修正；不能沿用旧包的核验结果证明新代码已交付。请求生成的证书等独立文件也要检查实际存在，编译校验程序不能代替生成证书。
|
||
|
||
- 按项目实际格式检查 ROM 长度、校验字段、内部版本及镜像列表；适用时解密、提取并核对实际镜像及其中的文件。生成目录检查不能替代最终包内核验。
|
||
- 对当前修改涉及的启动脚本、驱动、媒体参数及 AI 资源做重点核对。遇到加密参数，核对解码后的实际配置；提取工具返回 0 后仍需确认目标文件存在且内容正确。
|
||
- 发布目录中的 devInfo 与 ROM 内信息交叉核对，明确哪个哈希对应哪个普通包或平台加密包。整片镜像另核对分区偏移、顺序、容量及 DATA 覆盖范围。
|
||
- 缺少解包工具或格式信息时，写明尚未完成的核验，不以检查源文件替代后宣称包内验证通过。不因本章要求而自动向工程新增校验器或单元测试。
|
||
|
||
YT42 案例：一轮候选包的发布脚本正常结束，但实际生成了 SquashFS，BSP 却按 UBIFS 挂载 firmware。该包不能交付。另有 EmxGitInfo 返回 0 但无法读取 HEAD 的情况。两者说明：进程结束、制包完整、可启动、可追溯是不同结论。
|
||
|
||
## 6. OTA 兼容性与 Windows 交付
|
||
|
||
### 升级前判断
|
||
|
||
- 使用当前目标设备实测的 SN、MAC、IP、inner、outer、hardware 信息，与最终产物逐项核对；网络地址不能替代设备身份。记录设备信息的来源和时间，不能沿用其他样机的记录或为了匹配而擅改产品类型。
|
||
- 硬件名称含通配形式，不等于兼容范围已有证明；inner 类型变化需要明确的迁移依据。区分文件哈希一致、硬件兼容、升级协议允许和设备侧验证，不凭型号前缀相似放行。
|
||
- 比较设备现有布局与目标 BSP 的分区大小、偏移、A/B 槽、启动环境、文件系统和挂载点。布局变化时核对升级机制是否具备经确认的迁移能力；普通 OTA 未携带 boot 或 DATA 时，不能推断它会自动完成分区或 AI 资源迁移。
|
||
- 分开给出构建结果与升级结论。构建结果可为“完整打包成功”“仅 ROM 可用”或“失败”；“仅 ROM 可用”也必须有该 ROM 自身的核验依据，不能只因生成了一个文件就使用该结论。
|
||
- 用户要求升级放行时，明确回复“允许升级”或“禁止升级”，列明设备、目标包和必要前提。关键兼容性证据不足时不得允许发送 ROM，应说明待确认项。只要求制包时报告已验证范围和升级限制，不代替用户执行刷机。
|
||
- 本地生成完整发布产物，不等于已上传、正式发布、通过设备验证或允许量产。Windows 端是否收到文件、哈希是否通过、是否完成升级，都需要独立证据。
|
||
|
||
### 交付信息
|
||
|
||
当前任务包含制包交付时，在回复中提供足够让接收端唯一识别本次产物的信息：
|
||
|
||
- 工程绝对路径、实际工作目录、完整构建命令，以及采用的 PSP／BSP 来源和本地适配。
|
||
- 最终 ROM、配套 devInfo 及需要交付的其他镜像的绝对路径；明确普通包和平台加密包的用途。
|
||
- 最终文件大小、MD5、SHA-256，inner／outer／hardware 类型及版本；哈希在最终文件生成完成后计算。
|
||
- 构建起止时间、关键步骤退出码、警告与日志位置；日志按已确认的项目记录方式保存，不擅自新增流程文档。
|
||
- 实际包内核验结果、尚未完成的检查、构建结论，以及适用时单独给出的升级结论和升级后重点检查项。
|
||
|
||
YT42 案例：新 PSP 的 ROOTFS 槽从 4 MiB 变为 3 MiB，DATA 从 14 MiB 变为 36 MiB；即使产品外部型号相同、完整打包通过，也不能直接把普通 OTA 包刷入仍采用旧布局的设备。应先确认设备当前布局及获准的迁移方案。
|
||
|
||
## 7. crtCheck 调试证书生成与交付
|
||
|
||
- 先读当前 `EmxModulesExt/crtCheck/readme.md`、`CMakeLists.txt` 和 `main.c`，分清生成与校验。2026-09-22 核对的版本只编译安装 `CrtChk`，没有自动生成 `.crt` 的步骤。用户要求生成证书时，需要执行模块说明中的 CSR 和自签名生成步骤，不能只加入 `ModuleList` 后就称证书已完成。
|
||
- 从当前产品配置和编译宏核对型号。模块规则把 `inner.type` 写入证书主题的 `emailAddress`，文件名需与 `CrtOuterType` 一致。README 使用 `outer.type`，工程也可能取 `outer.pack_type`；以实际编译配置核对两者，不套用其他型号的 CSR 或证书。
|
||
- 按模块规则复用仓库已有示例密钥，不为更换产品型号而重新生成密钥，也不覆盖公共示例 CSR。中间 CSR、日志放入已确认的构建目录。用户要求延长已有证书有效期时，保留型号与密钥，并备份原证书。
|
||
- 调试证书默认有效期为 10 年，使用 OpenSSL 时按 `-days 3650` 生成。用户可以自定义有效期，明确指定的天数或起止日期优先于默认值；模块 README 中的 365 天示例不覆盖此默认规则。交付时记录实际起止时间和时区，3650 天不保证与十个日历年的同月同日重合。
|
||
- 本地分别检查 CSR、型号字段、自签名、起止时间，以及需要保持密钥时的公钥一致性。核实当前 `CrtChk` 真正覆盖的校验：本轮版本调用了解析、`check_key_usage(..., 0)` 和 issuer 型号匹配，不能把它的成功返回当作签名和有效期均已验证。主机 OpenSSL 校验与设备端 `CrtChk` 实测分别报告。
|
||
- 上电系统时间为 1970 年时，先看实际校验接口是否检查有效期。当前版本的 `CrtChk` 没有时间检查，不能据此推断 TLS 或其他完整证书校验也不受影响；执行时间校验时，2026 年开始生效的证书会被判为尚未生效。延长到期时间不能解决系统时间早于生效时间的问题。需要时间校验的流程应结合设备校时顺序排查，不通过任意回填生效日期或关闭验证来绕过。
|
||
- 调试证书用于启动开关时，同时核对启动脚本是否读取并使用 `CrtChk` 退出码。证书文件存在、校验程序通过、启动脚本实际启用调试是不同结论；只调用程序不能证明返回值已生效。发现 PSP 脚本问题时说明事实，按底层修改边界处理。
|
||
- 沿用用户确认的交付位置。YT70／YT42 的调试证书作为独立文件放在工程根目录；不因生成证书而自行打入 ROM、部署到设备或开启调试。向设备部署、正式发布及其他外部操作仍按原授权规则执行。
|
||
- 交付时给出文件绝对路径、实际型号、有效期和已执行的校验结果。没有重新打包或设备验证时说明完成边界，不把独立证书生成写成设备验证通过。
|
||
|
||
2026-09-22 生成记录：YT42 的证书从 365 天延长到 3650 天，沿用同一密钥和内部型号；最终到期时间为 2036-09-19。已完成主机 OpenSSL 校验，未在样机执行 `CrtChk`。本案例不携带私钥或账号内容。
|