Ivan's Blog
项目实践

IsolaRail

IsolaRail 是当前 V3 四口 USB hub 的 owner-facing control plane 仓库。README.md 把它定义为 ESP32-S3 + CH335F + M24C64@0x50 + EN1..

  • ESP32 firmware
  • DC fan speed control
  • Project docs site

目录

技术栈

运行与交付

CI 工作流
  • check.yml
  • dev-release.yml
  • docs-pages.yml
  • notify-release-failure.yml
  • release.yml
能力标记
  • bun_lock
  • cargo_toml
  • github_actions
  • package_json
JSON

Purpose

IsolaRail 是当前 V3 四口 USB hub 的 owner-facing control plane 仓库。README.md 把它定义为 ESP32-S3 + CH335F + M24C64@0x50 + EN1..EN4 + PWREN#/OVCUR# + LCD/front panel 的整机控制面，并固定 isolarail / isolarail-devd 为 firmware、CLI 和 daemon 身份；这说明它不是单独的驱动 crate，也不是单独的 web 或 docs 仓库，而是“固件 + 本地 companion + 主站 web + 文档站”的一体交付面。

Taxonomy

  • Tags: ESP32 firmware, DC fan speed control, Project docs site

Repository map

  • src/ 是 ESP32-S3 firmware 主体，包含 boot/runtime、hardware_snapshot、fan、sideband 与设备状态输出逻辑。
  • tools/isolarail-companion/ 承载本地 CLI 与 isolarail-devd，仓库根 Justfile 把它们暴露成 normal developer entrypoints。
  • web/ 是 publishable primary site；README.md 明确组合静态产物里它占根路径 /。
  • docs-site/ 是 bilingual Rspress 文档站，发布时挂到 /docs/ 子路径。
  • gc9d01/ 是 vendored display driver submodule，说明显示控制器层仍被保留为独立维护边界，而不是完全埋进整机固件里。

Runtime and delivery

固件开发默认通过 just firmware-check、just firmware-build、just flash-monitor 与 cargo run --release 完成，其中 cargo run --release 被 .cargo/config.toml 和 tools/isolarail-runner 绑定到同一条 Local USB 安全边界；README 同时明确“previous Makefile、direct espflash flash --monitor、mcu-agentd flashing entrypoints are retired”。站点交付默认先 bun run docs:build 与 bun run --cwd web build，再通过根 package.json 的 site:assemble 组装 .site-publish。.github/workflows/docs-pages.yml 只构建一次，再把同一份 artifact 同时用于 GitHub Pages 与 npx edgeone makers deploy。

Architecture notes

README.md、docs/hardware_connection_overview.md 与 src/hardware_snapshot.rs 共同表明：这个仓库的控制面不是“给 USB hub 做个设置页”这么窄，而是覆盖 input power、I2C topology、CH335F sideband、front panel、fan control/telemetry、buzzer、boot self-check、per-port control gates 与 output-module telemetry 的整机诊断与操作边界。另一方面，README.md 又把发布面拆成三条 seam：本地 USB CLI/daemon、根路径 web/ 主站、以及 /docs/ product/engineering docs site。docs/specs/r6wfr-docs-site/IMPLEMENTATION.md 进一步说明，这三个 seam 在正式发布时会被组装进同一份静态 artifact，而不是各自独立部署。

Workflow and quality gates

.github/workflows/check.yml、dev-release.yml、release.yml、notify-release-failure.yml 与 docs-pages.yml 共同构成 firmware、release、failure alert 与站点发布门禁。README.md 的 validation status 又把 just tools-build、just web-check、just firmware-check、cargo +esp build --release 等本地验证入口显式列出，说明该仓库的质量门禁不是单一语言栈，而是 firmware + companion + site publish 的组合门禁。

Reusable decisions

  • 主站 web/ 和文档站 docs-site/ 默认共享一份组合静态产物：根路径 / 给 web app，/docs/ 给 docs site，再把同一份 artifact 同时发布到 EdgeOne 与 GitHub Pages 热备。
  • EdgeOne 相关 owner-side prerequisite 被刻意收口在最小合同：CI 只吃 EDGEONE_API_TOKEN 与 EDGEONE_PROJECT_NAME；项目、域名、证书、默认域名 smoke test 和 DNS 切流都留在 owner-side rollout。
  • 固件 flashing 路径被项目化为 just + isolarail / isolarail-devd 安全边界，而不是让维护者直接猜 espflash 或旧 daemon 命令。

Risks and open questions

  • 仓库仍包含部分 reference-only 硬件资料，例如 docs/esp32-s3fh4r2_gpio_assignment_guide.md 与 docs/pwm_fan_control_circuit_design.md；它们对 fan / GPIO 主题仍有价值，但不应被误读为全部 current truth。
  • cargo +esp build --release、just flash-monitor、设备串口日志与 front-panel 行为是不同层级的证明；只有编译通过并不等于整机行为已验证。
  • web/ 根路径与 docs-site/ /docs/ 子路径共用同一份 artifact，任何 SITE_BASE / DOCS_BASE 漂移都可能同时破坏 EdgeOne 正式入口与 GitHub Pages 回滚源。

Evidence index

  • README.md
  • Cargo.toml
  • Justfile
  • tools/isolarail-runner
  • package.json
  • .github/workflows/check.yml
  • .github/workflows/docs-pages.yml
  • .github/workflows/notify-release-failure.yml
  • docs/specs/r6wfr-docs-site/SPEC.md
  • docs/specs/r6wfr-docs-site/IMPLEMENTATION.md
  • docs/hardware_connection_overview.md
  • docs/pwm_fan_control_circuit_design.md
  • src/hardware_snapshot.rs
  • src/fan.rs

相关内容