项目实践

IsolaRail

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

Embedded Rust
ESP32 firmware
Async embedded
Display driver
DC fan speed control
MCU flashing integration
Project docs site
Release failure notification
EdgeOne Makers static-site deploy

技术栈

CI 工作流

check.yml
dev-release.yml
docs-pages.yml
notify-release-failure.yml
release.yml

能力标记

bun_lock
cargo_toml
github_actions
package_json

JSON

{
  "cargo": {
    "deps_main": [
      "defmt",
      "embassy-embedded-hal",
      "embassy-executor",
      "embassy-futures",
      "embassy-net",
      "embassy-sync",
      "embassy-time",
      "embassy-time-net",
      "embedded-graphics",
      "embedded-hal",
      "embedded-hal-async",
      "embedded-hal-bus",
      "embedded-io-async",
      "esp-alloc",
      "esp-backtrace",
      "esp-bootloader-esp-idf",
      "esp-hal",
      "esp-hal-embassy",
      "esp-println",
      "esp-wifi"
    ]
  },
  "ci_workflows": [
    "check.yml",
    "dev-release.yml",
    "docs-pages.yml",
    "notify-release-failure.yml",
    "release.yml"
  ],
  "configs_root": [
    ".gitignore",
    ".gitmodules",
    ".markdownlint-cli2.yaml",
    "Cargo.toml",
    "lefthook.yml",
    "package.json",
    "rust-toolchain.toml"
  ],
  "markers_present": [
    "bun_lock",
    "cargo_toml",
    "github_actions",
    "package_json"
  ],
  "package_json": {
    "deps_dev": [
      "@commitlint/cli",
      "@commitlint/config-conventional",
      "commitlint-plugin-function-rules"
    ],
    "scripts": [
      "commitlint",
      "docs:build",
      "docs:dev",
      "docs:preview",
      "site:assemble"
    ]
  }
}

技术栈完整数据（无需 JavaScript）

{
  "cargo": {
    "deps_main": [
      "defmt",
      "embassy-embedded-hal",
      "embassy-executor",
      "embassy-futures",
      "embassy-net",
      "embassy-sync",
      "embassy-time",
      "embassy-time-net",
      "embedded-graphics",
      "embedded-hal",
      "embedded-hal-async",
      "embedded-hal-bus",
      "embedded-io-async",
      "esp-alloc",
      "esp-backtrace",
      "esp-bootloader-esp-idf",
      "esp-hal",
      "esp-hal-embassy",
      "esp-println",
      "esp-wifi"
    ]
  },
  "ci_workflows": [
    "check.yml",
    "dev-release.yml",
    "docs-pages.yml",
    "notify-release-failure.yml",
    "release.yml"
  ],
  "configs_root": [
    ".gitignore",
    ".gitmodules",
    ".markdownlint-cli2.yaml",
    "Cargo.toml",
    "lefthook.yml",
    "package.json",
    "rust-toolchain.toml"
  ],
  "markers_present": [
    "bun_lock",
    "cargo_toml",
    "github_actions",
    "package_json"
  ],
  "package_json": {
    "deps_dev": [
      "@commitlint/cli",
      "@commitlint/config-conventional",
      "commitlint-plugin-function-rules"
    ],
    "scripts": [
      "commitlint",
      "docs:build",
      "docs:dev",
      "docs:preview",
      "site:assemble"
    ]
  }
}

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: Embedded Rust, ESP32 firmware, Async embedded, Display driver, DC fan speed control, MCU flashing integration, Project docs site, Release failure notification, EdgeOne Makers static-site deploy
Why / evidence: 这些 tags 来自当前仓库的 checked-in evidence。Cargo.toml 展示 esp-hal、Embassy、embedded-hal-async 和本地 gc9d01 driver；docs/pwm_fan_control_circuit_design.md 与 src/fan.rs 共同证明两线 DC 风扇的模拟调压控制路径与温控逻辑；Justfile 与 tools/isolarail-runner 固定了 Local USB flashing/monitor 入口；package.json、README.md、.github/workflows/docs-pages.yml 与 docs/specs/r6wfr-docs-site/* 共同证明 web/ 根站点、docs-site/ /docs/ 子站点、单一 .site-publish 组合产物，以及 GitHub Pages 热备 + EdgeOne Makers 正式发布合同。

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 安全边界。站点交付默认先 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

IsolaRail

目录

目录

技术栈

Purpose

Taxonomy

Repository map

Runtime and delivery

Architecture notes

Workflow and quality gates

Reusable decisions

Risks and open questions

Evidence index

Async embedded

DC fan speed control

Display driver

EdgeOne Makers static-site deploy

Embedded Rust

ESP32 firmware

Manual version release delivery

MCU flashing integration

Project docs site

Release failure notification

目录

技术栈

运行与交付

依赖与工具

配置与质量

其他信息

Purpose

Taxonomy

Repository map

Runtime and delivery

Architecture notes

Workflow and quality gates

Reusable decisions

Risks and open questions

Evidence index

相关内容

Async embedded

DC fan speed control

Display driver

EdgeOne Makers static-site deploy

Embedded Rust

ESP32 firmware

Manual version release delivery

MCU flashing integration

Project docs site

Release failure notification