# CLAUDE.md — Blanton TTL Script (Diag)

## 專案簡介

Blanton（Project Helios）交換器平台在 **Diag OS**（ODM 診斷映像，非 SONiC）下的驗證自動化腳本組。
Windows 端用 **Tera Term TTL macro** 透過 COM console 驅動 DUT，
A / B / C 三支腳本分別跑「功能掃描 → 壓力 soak → 收工判定」，全程存 log。
取數能力全部來自 Diag image **內建的 `acc_*` 指令集** 與 `swutil`，**本專案是純 TTL，沒有 bash 工具庫**。

姊妹專案 [`Blanton_TTL_Script`](../Blanton_TTL_Script) 是同一片硬體的 **SONiC 版**（有 bash 工具庫）。
**兩邊不共用檔案**，`config.ttl` 同名但 prompt 不同，不要互相複製。

完整架構見 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 技術棧

- **Host**：Tera Term 5.x TTL macro（`.ttl`），Windows
- **DUT**：ODM Diag OS（busybox 風格），提示字元 `root@(none):~#`，**直接 root、無登入互動**
- **診斷指令**：`acc_<domain>_<device> <subcmd>` 家族 —— domain 有
  `misc / pld / pwr / bmc / iai / dram / fs / scy / net / temp / cool / time / led`
- **交換晶片**：`swutil`（`*:` = 全 unit、`1:` = unit 1、`dsh -c` 轉發 Broadcom drivshell）
- **板級 EEPROM**：`onie-syseeprom -t cpu`（ONIE TLV）
- **無編譯步驟**：TTL 直譯執行，「build」= 把 `src/Script_ABC_Blanton_Diag/` 複製到 Tera Term 工作目錄

## 常用指令

**Host 端跑一輪測試：**

```
Tera Term 連 diag console COM port (115200-8-N-1)
→ 先按一次 Enter，確認提示字元是 root@(none):~#     ← 不符就改 config.ttl 的 prompt_diag
→ 確認工作目錄下有 Logs\                            ← logopen 不會自建目錄
→ Control → Macro → 1_Blanton_Script_A.ttl          (功能掃描，目前唯一完整的一支)
→ 手動跑 2_Blanton_Script_B.ttl                     (壓力 soak，while 1，泡到時間到停掉)
→ 手動跑 3_Blanton_Script_C.ttl                     (收工判定)
→ 檢查 Logs\Blanton_Margin_<ts>.log
→ 收工還原：風扇回 auto、config.yml 的 AUTO 與 extphy_init_LT.soc 復原
```

**DUT 端煙霧測試（跑 Script A 前先手動敲）：**

```bash
version                    # 有輸出 = console 通了
acc_iai_i2c device         # I2C 列舉，對照 golden list
acc_iai_pcie device        # PCIe 列舉
acc_misc_liquid info       # 漏液狀態，異常就別往下跑
```

**Script A 涵蓋的主要指令（依執行順序）：**

```bash
version ; acc_misc_version bios|i210|mac ; acc_pld util cb 0 0x0
acc_pwr_mon show d2d ; acc_bmc_board info
acc_misc_liquid info                      # 漏液
onie-syseeprom -t cpu                     # ONIE EEPROM
acc_iai_i2c device ; acc_iai_pcie device  # 匯流排列舉
acc_dram_cpu info|rw|chkecc               # DDR
acc_bmc_iai i2c_device ; acc_bmc_net usb_ping ; acc_bmc_fs spi_test
acc_bmc_dram rw ; acc_bmc_e2p bmc_r       # BMC 子系統
acc_fs_ssd info|rw|selftest short ; acc_fs_usb rw
acc_scy_tpm ; acc_scy_nfc test            # 安全元件
acc_net_cpu traffic mgmtp                 # MGMT 埠流量
acc_temp_thermal ddr|cpu|sensor ; acc_cool_fan speed 30 ; acc_time_rtc test
100init.sh ; acc_net_mac 100G             # 100G
swutil *:ps cd ; swutil *:port cd en=0|1  # 埠狀態 / down-up
acc_net_mac ber -m berproj -p all
acc_net_mac fec -p all
acc_net_mac fdr -m fdr -u all
# TH6：改 config.yml AUTO 0→1、停用 extphy_init_LT.soc、swutil -C -r、dsh 'tr 39'/'tr 55'
```

## 開發慣例

- **執行單位**：`src/Script_ABC_Blanton_Diag/` 整包給測試員（Tera Term 工作目錄）
- **TTL 分層**：`config.ttl` 放設定 → 三支主腳本編排流程 → `utils/*.ttl` 是可 include 的無狀態片段
  （只做 `wait prompt_diag` + `sendln`，不設變數、不 logopen）
- **新增取數項目** = 新增一支 `utils/show_xxx.ttl`，再在主腳本 `include`，不要往主腳本塞指令
  （目前 Script A 還是一整條直線，Phase 2 才會拆 —— 新東西直接照新慣例寫）
- **開關用旗標不用註解**：要不要跑某個區塊，用 `config.ttl` 的 `EN_*` 控制
  （現在 LED 測試是用註解關掉的，這是要修的反例）
- **版本紀錄**：`1_Blanton_Script_A.ttl` 檔頭的 `Version History` 是三支腳本的集中紀錄，
  改動時**在檔頭補一行**（`V1.0.1  YYYY-MM-DD  <做了什麼>`），不要只改版號
- **換行符**：`.ttl` 維持 **CRLF**（只在 Windows 上跑），`.gitattributes` 已標 `-text`；
  `.sh` / `.md` / `.py` 一律 LF
- **Commit**：Conventional Commits，**英文**。scope 用 `ttl` / `diag` / `bmc` / `net` / `th6` / `docs`

## 注意事項

- ⚠️ **`Logs\` 資料夾必須先存在**，`logopen` 不會自建。缺了就整支 macro 在第一步失敗，
  而且**因為還沒開 log，失敗現場什麼都不會留下**。repo 內用 `.gitkeep` 保留這個目錄。
- ⚠️ **`prompt_diag = "root@(none):~#"` 是全專案唯一的同步基準**。Diag image 換版、
  hostname 被設定、prompt 客製化 → 整組腳本卡在第一個 `wait`，畫面上看起來像「當掉」。
  換 image 先手動按 Enter 確認這一行。
- ⚠️ **`wait` 沒有 timeout 就是無限等**。`acc_fs_ssd selftest short`、`acc_net_mac ber`、
  `acc_dram_cpu rw`、`acc_bmc_dram rw` 都可能跑很久或掛住，
  現行腳本沒有逾時保護 —— macro 會永遠停在那一行，且看不出是還在跑還是死了。
- 🔴 **`utils/show_margin_status.ttl` 目前不存在，但 `2_Blanton_Script_B.ttl` 已經 include 它。**
  `EN_Margin=1` 時 Script B 會失敗。修好之前，現場請先在 `config.ttl` 設 `EN_Margin=0`。
- ⚠️ **Script B 的 `while 1` 迴圈裡沒有 `pause`**，註解寫「Get data every 10mins」但實際上是
  全速空轉，取樣間隔取決於指令執行時間。（Phase 3 要補 `EN_LoopInterval`。）
- ⚠️ **TH6 段落會改 DUT 的檔案且不還原**：`sed -i` 把 `config.yml` 的 `AUTO: 0` 改成 `1`、
  把 `extphy_init_LT.soc` 改名成 `.temp`。**跑完的 DUT 不是出廠狀態**，交機前要手動復原。
- ⚠️ **`acc_cool_fan speed 30` 之後沒有還原**成自動控制。高負載 soak 時有過熱風險，測完要確認。
- ⚠️ **`swutil *:port cd en=0` 會把埠打掉**。用 SSH 而非 COM console 操作時會斷線。
- ⚠️ **一堆 `rw` 是寫入測試**（`acc_dram_cpu rw`、`acc_bmc_dram rw`、`acc_fs_ssd rw`、
  `acc_fs_usb rw`），**只能對測試機跑，絕不可對客戶已上線的機器執行**。
- ⚠️ **漏液檢查優先於一切**（液冷平台）。`acc_misc_liquid info` 異常時直接中止，別繼續往下測。
- ⚠️ **A → B → C 必須同一個 Tera Term session**：只有 A 會 `logopen`，B / C 是 `logwrite` 續寫。
  中途關掉 window，log 就斷了。
- ⚠️ **`tr 39` / `tr 55` 的測項定義還沒留檔**（Broadcom SDK 內建編號）。
  log 裡只看得到編號，看不出測了什麼 —— 拿到 SDK 文件請補進 `docs/`。
- 🔒 **Gitea 上本 repo 依指示設為 public**。`docs/` 放客戶提供的文件前**務必再確認一次**，
  只有可公開的內容才進 repo。

## 資料夾說明

- `src/Script_ABC_Blanton_Diag/` — 可執行內容（Tera Term 工作目錄，整包給測試員）
- `docs/` — 規格與狀態文件（待放：Diag 指令手冊、`tr <n>` 對照、逐項 Status 表）
- `tools/` — Host / 離線端輔助腳本（待放：log 解析器）
- `publish/` — 交付用打包輸出（`Blanton_Script_ABC_Diag_v<ver>_<date>/` + zip）
- `secret/` — 🚫 gitignored（除 `README.md` 與 `*.example`）：COM 設定、per-unit 覆寫、未公開附件
- `For_AI/` — 🚫 gitignored：AI 協作素材（截圖、草稿筆記）