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
  • Embedded Rust
  • TypeScript web
  • React app
  • Progressive web app
  • Application icon
  • Storybook component QA
  • Playwright e2e
  • Web demo
  • ESP32 firmware
  • Display driver
  • USB PD
  • MCU flashing integration
  • Embedded device control plane
  • Quality gates
  • 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, Embedded Rust, TypeScript web, React app, Progressive web app, Application icon, Storybook component QA, Playwright e2e, Web demo, ESP32 firmware, Display driver, USB PD, MCU flashing integration, Embedded device control plane, Quality gates, GitHub Actions scheduling
  • Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括 README.md、Cargo.toml、hardware/、docs/hardware-variants.md、web/package.json、web/.storybook/main.ts、.github/workflows/firmware.yml。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。

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。

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 列表。
  • 硬件 target 与操作参数应和项目文档、构建脚本及验证记录保持一致，方便多 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
  • 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

相关内容