Ivan's Blog
项目实践

IsolaPurr USB Hub

IsolaPurr USB Hub 是带 USB-C 上行、USB-C 下行和 USB-A 下行的有源 USB 集线器/供电模块。README.md 记录 CH334P、URB2405S、CH224Q、TPS55288、SW2303/IP6557、DC5025 输入和理想二极管 OR-ing 等硬件方案，说明这是硬件/固件/Web/文档一体的 device mono-repo。

  • Device mono-repo
  • Progressive web app
  • Application icon
  • Web demo
  • ESP32 firmware
  • Embedded device control plane
  • GitHub Actions scheduling

目录

技术栈

运行与交付

CI 工作流
  • ci.yml
  • dependency-review.yml
  • desktop.yml
  • firmware.yml
  • lint-pr-title.yml
  • pages.yml
能力标记
  • bun_lock
  • cargo_toml
  • github_actions
  • package_json
JSON

Purpose

IsolaPurr USB Hub 是带 USB-C 上行、USB-C 下行和 USB-A 下行的有源 USB 集线器/供电模块。README.md 记录 CH334P、URB2405S、CH224Q、TPS55288、SW2303/IP6557、DC5025 输入和理想二极管 OR-ing 等硬件方案，说明这是硬件/固件/Web/文档一体的 device mono-repo。

Taxonomy

  • Tags: Device mono-repo, Progressive web app, Application icon, Web demo, ESP32 firmware, Embedded device control plane, GitHub Actions scheduling

Repository map

  • hardware/、docs/hardware-variants.md 和 vendor/ 保存硬件资料。
  • src/ 是 ESP32-S3 firmware，Cargo.toml 使用 esp-hal、gc9307-async、ina226 等 embedded/display/current-sense 依赖。
  • web/ 是 React/Vite UI，包含 PWA manifest/service worker、Storybook、Playwright e2e 和 unit tests。
  • mcu-agentd.toml 声明 usb_hub espflash target。

Runtime and delivery

固件通过 Cargo/espflash 构建烧录；web dev 默认 45173，preview 45175，Storybook 46006，test-storybook 静态服务 46106。.github/workflows/pages.yml、web/README.md 与 docs/web-ui-interaction-spec.md 还把 GitHub Pages、PNA/CORS、Base URL、installable PWA app shell、prompt 型 service worker 更新，以及 install icon 的内容哈希版本后缀写成正式运行 contract，说明这个前端不仅是本地工具，也承担 owner-facing / public-facing 的正式演示与安装 surface。这些端口属于项目脚本默认，不代表当前 Codex 预览可直接复用。

Architecture notes

架构由电源路径和 USB data path 决定：上行供电/数据、隔离 DC/DC、下行 PD 可调输出和双电源 OR-ing 必须保持文档/固件/UI 对齐。ESP32-S3 firmware 负责显示、测量、控制或状态上报，Web UI 是开发/展示辅助面。

证据锚点：README.md。

Workflow and quality gates

.github/workflows/ci.yml、dependency-review.yml、desktop.yml、firmware.yml、pages.yml、lint-pr-title.yml 拆分 firmware/web/docs/desktop/依赖审查。根 package.json 负责 commitlint，web 子项目负责前端质量。

.github/workflows/pages.yml 同时响应 PR、merge_group 和 workflow_dispatch，却使用全局 pages concurrency group 且允许取消在途运行；PR build、merge-queue gate 和手工 backfill 不应互相抢占。这个跨事件调度风险由 GitHub Actions scheduling 记录，Quality gates 负责保留可见的交付门禁。

Reusable decisions

  • 硬件 variant 写进 docs，而不是只靠 README 列表。
  • mcu-agentd 配置固定 ESP32-S3 flashing，方便多 Agent 操作。
  • Web UI 端口脚本明确，但预览必须遵守全局端口租约。
  • Web demo 直接复用正式 dashboard/device routes，再通过 Pages 托管与 Base URL / PNA 接入保持真实产品体验，不把演示面退化成文档页或组件画廊。
  • PWA install metadata 视为 runtime contract，而不是纯视觉资源：manifest、theme-color、favicon、apple-touch-icon、offline app shell 与更新提示都需要和真实路由、真实部署入口一起维护；install icon 变更时必须让 URL 一起变化，避免 Chrome/macOS 已安装 surface 长期复用旧缓存。
  • regular 与 maskable install icon 分别生成并拥有内容版本 URL；产品 mark 的视觉几何、maskable 安全区和 Apple 派生物由 Application icon Topic 约束，PWA 运行时只消费这些明确角色的资产。

Risks and open questions

  • 硬件方案存在多 variant，Topic 不能只说“USB hub”。
  • PD/PPS/AVS 能力由具体芯片侧控制，不能从标签自动推断实现完整。
  • Storybook component QA 不等于硬件验证。

Evidence index

  • README.md
  • Cargo.toml
  • hardware/
  • docs/hardware-variants.md
  • mcu-agentd.toml
  • web/package.json
  • web/vite.config.ts
  • web/src/pwa/sw.ts
  • web/scripts/check-pwa-assets.py
  • web/public/manifest.webmanifest
  • web/README.md
  • docs/web-ui-interaction-spec.md
  • web/.storybook/main.ts
  • .github/workflows/firmware.yml
  • .github/workflows/pages.yml
  • .github/workflows/ci.yml

相关内容