機房溫濕度監測器：從需求、採購、建模、切片到上線的跨域協作紀錄

01發想：為什麼是「可列印模組＋網路 API」

起因只有一句話：機房需要溫濕度網路監控設備。

需求方一開始就把範圍收得很窄：只量溫濕度，走內網 Wi‑Fi 提供資料；不控制除濕機或加濕機，也不接智慧插座。機房溫度約 25 °C，現場用 USB 5V 供電。這幾個條件決定了後面的做法：

• 自己列印外殼。家裡有一台 Ender‑3，只用 PLA。外殼要能免支撐一次印完，滑蓋開合方便維修，還要能鎖螺絲、綁束帶或用背膠固定在機櫃上。
• 裝置只提供 API。第一版韌體會在裝置上判斷異常（溫度門檻、連續失敗），後來改成裝置只負責量測，資料交給自建的巡檢服務判斷（見第 06 節）。之後要加監測點、改門檻或接到其他告警管道，都不必重燒韌體。
• 零件用市售模組。開發板和感測器都用現成模組加杜邦線連接，不必焊接，壞了直接換。

02採購：從規劃清單到實際落地的 BOM

清單換過一次，現在的版本以實際買到、裝進殼裡的零件為準。

第一版清單（11/10 下午，採購端列出）：ESP32‑C3 SuperMini 開發板＋GY‑SHT31‑D 溫濕度模組（I²C），每個監測點一組，需求方已有母對母杜邦線與 Type‑C 充電頭。依這組硬體做的第一代滑蓋殼，已經做到切片和 CAD 核對。

實際落地：同一天，需求方在桃園的健新電子材料行直接買到 ESP32 開發板和 DHT11，當晚硬體就改用這組。代價是外殼得重新設計，而且買回來時板子還在防靜電袋裡，看不出是 30 腳還是 38 腳（見第 04 節）。DHT11 的規格精度是 25 °C 時 ±2 °C、±5 %RH，用來看機房趨勢夠用；限制見第 10 節。

比價摘要：一組開發板＋感測器（不含運費與 PLA）

加上 PLA 估算：實機材料約 NT$514（420＋80＋14）；網路同等品約 NT$287（台灣物聯科技）或 NT$271（酷澎市集），運費另計。杜邦線、USB 線與充電頭、固定件都是已有的，不計入。

價格說明：網路價是 11/11（三）早上查到的公開標價，屬於同等規格的網路商品，不是健新實購的同一批貨，也不保證板型或 USB 晶片完全相同；NT$420／NT$80 是 11/10（二）在健新的實購標價。依需求方的決定，這次詢價改用網路同等品的現價完成，沒有再向門市電話或書面詢價，也沒有加入購物車或下單。比價時排除了規格對不上的低價選項：同一個酷澎商品頁上 NT$145 的選項其實是天線；酷澎上 NT$35 的 DHT11 是裸探頭，不是模組（另一家 NT$35 的模組已售完）；另一家 NT$140 的 DevKit‑32E 沒寫腳位，這個型號通常是 38 腳，裝不進本篇的 30 腳殼。

03接線圖：用現成元件庫產生，而不是從零畫

需求方的要求是「不要從 0 到 1，去找現成的套件繪製，讓我很容易接線」。

AI 選了 Wokwi 的開源元件庫 @wokwi/elements（MIT 授權）：30 腳板用 wokwi-esp32-devkit-v1，感測器借用 wokwi-dht22 的外形（腳位功能與 DHT11 相同，改成藍色並標 DHT11）。元件在無頭瀏覽器裡算繪成 SVG，線端座標直接取元件自帶的腳位定義，再用 Python 組成接線圖，因此每條線都畫在真實的腳位上。同一組接線也輸出成 Wokwi 的 diagram.json，可以直接拿去模擬。

接法只有三條線，都在 USB 那一端的右排：

38 腳 DevKitC 版也畫了一張，但那張板圖的來源 repo 沒有附授權檔，只能內部參考，本文不收錄。

04建模：OpenSCAD 參數化兩件式滑蓋殼

殼身＋滑蓋兩件，一盤印完、免支撐；板型尺寸放在一張查表裡，換板子只改一列。

外殼用 OpenSCAD 寫成參數化原始檔，AI 協助建模，用 Manifold 後端輸出 STL。從前一代（C3＋SHT31）沿用了幾個已驗證過的特徵：45° 燕尾滑蓋沿長軸滑入、配合間隙 0.30 mm、滑蓋貼床面做 0.3 mm 防象腳倒角、前端彈片加兩側 1.0 mm 切縫（根部 R0.5），以及安裝耳上的沉頭孔和束帶槽。這次重新設計的部分：

• 佈局：DHT 端牆 → DHT11 艙 → 1.6 mm 實心隔牆 → 12 mm 天線淨空區 → ESP32 艙 → USB 端牆。壁掛時 DHT 端朝下，感測器在 ESP32 熱源的下方（上游）。
• 走線空間：排針朝下，板下預留杜邦母頭（約 14 mm）加 9 mm 彎線空間；3 條線從隔牆底部側邊的 6×8 mm 孔穿到 DHT 艙，不經過天線正下方。
• 固定：開發板沒有螺絲孔，靠兩側牆夾住板寬、天線端的角塊楔口壓住板角，USB 端由滑蓋擋住；DHT11 板平放在兩條支撐軌上，底下留 4 mm 讓空氣流通。
• 通風與天線：DHT 艙四周、背面、蓋上都有格柵（開口 2.0 mm、肋 ≥1.6 mm）；天線上方只有 2.2 mm 厚的滑蓋，蓋上另開兩條槽。
• 不開蓋可操作：USB 端開 U 型缺口直接插線；蓋上有兩個 Ø3.2 小孔，可用牙籤按 BOOT／EN。插著線時，插頭會擋住蓋尾，等於多一道鎖。

板型不確定，所以兩種都做。買回來時無法從照片判斷板型，查不到店家頁面，也還沒有實物可以量。殼體預設做 38 腳 DevKitC（尺寸取自 Espressif 官方圖面與 DXF），另出一套 30 腳 DOIT 版（尺寸取自第三方實測圖）。實物確認是 30 腳 DOIT 後，就改印這一版：殼身約 35 × 124 × 36 mm，含安裝耳長 142 mm。

檢查自動化，而且要能抓到錯。建置腳本對兩種板型各跑 15 項檢查，包括：STL 封閉流形、參考零件與殼身干涉、閉合與整段滑出時的滑蓋干涉、楔口間隙、USB 端斜插角度、杜邦線路徑、天線淨空、切縫寬度、扣點實測尺寸、最小肋厚，以及 0.28 mm 層高量化後的實際間隙。結果全部 PASS。為了確認檢查本身有效，也刻意把參數改壞（走線孔縮小、楔口伸進模組、插頭開口縮小、滑蓋壓低等），結果都如預期判為干涉。STL 也曾匯入雲端 CAD 平台，核對外框與體積，數字與 STL 一致。

過程中真的出過的錯：

• 前一代殼的楔口間隙設 0.35 mm，換算 0.28 mm 層高後實際只剩 0.12 mm，因此改成 0.50（實得約 0.36–0.40）。改完後殼身多了 6 條非流形邊，原因是兩個共面方塊的浮點誤差，後來改成單一截面一次擠出才修好。
• DHT 端牆的格柵把端擋塊切出一片 0.1 mm 薄片，最後拿掉端擋塊，改由螺絲柱和定位塊定位。
• 扣點梯形的底邊多延伸了一點，底寬只有 1.385 mm（目標 1.4）。修正斜率後，STL 實測 1.399。
• USB‑C 開口較寬，會切到 USB 端的支撐。後來改成支撐自動避開開口。

可旋轉的 3D 模型（30 腳 DOIT 版，殼身＋滑蓋）

模型檔（相對路徑，隨本頁一起提供）：GLB（殼身、滑蓋為兩個獨立零件）・STL（組裝態，單一網格）。檢視器以 three.js r160（MIT）實作。模型本身沒有動畫，滑開時程式只沿長軸平移滑蓋零件，沒有修改模型檔。

05切片：Cura 產生 G-code，三版逐步調整

PLA、層高 0.28 mm、免支撐、一盤約 6 小時。

切片用 Cura 5.6（CuraEngine 5.6.0），機型 Creality Ender‑3，0.4 mm 噴嘴，沿用需求方原本的 Low 0.28 mm 設定：2 道牆 0.8 mm，不加支撐。設計時就把牆厚做成 0.8 的倍數，懸空都 ≤45°，橋接只出現在 2.0 mm 通風槽頂與 6 mm 走線孔頂。印表機設定裡的噴頭 Y offset −20 是刻意的，任務單寫明不要補償；熱床後緣 20 mm 不放零件。

第三版主要在加強附著：零件細長、底面大，brim、較高的熱床溫度和前幾層關風扇，都是為了降低翹邊的機率。第一版 G-code 另外做了逐層檢查：滑蓋兩條切縫在 8 層裡都沒有被擠出線填住，彈片能獨立彎曲；楔口在 0.28 mm 層高下的實際間隙是 0.36 mm。

06韌體：從「會告警」改成「只量測＋API」

韌體只用 arduino-cli 編譯，過程不需要 sudo；在主機端寫測試，有板子之前先把邏輯驗完。

編譯環境：用 Homebrew 裝 arduino-cli 1.5.1，再裝 Espressif 官方 ESP32 Arduino core 3.3.12，函式庫用 Adafruit DHT sensor library 1.4.7 與 Adafruit Unified Sensor 1.1.15。macOS 已內建 CP210x 與 CH34x 的驅動，不必另外安裝。Wi‑Fi 帳密放在 secrets.h，這個檔被 .gitignore 排除，不進版本控制；沒有這個檔也能編譯，此時進入離線模式。

v0.1.0（11/10 晚間）：每 5 秒讀一次 DHT11，讀取失敗時重試，取最近 6 筆做滑動平均。溫度超過門檻或連續讀取失敗時，在序列埠印出警示。另提供 /metrics 與 /json。這時還沒有板子，只做了編譯。

需求轉折（11/10 21:43），需求方原話：

「韌體變成持續量測，但是有 API 接口，讓我自己開發服務去巡數據，巡到異常我再處理。」

v0.2.0 據此重寫：

• 拿掉裝置端所有告警與滑動平均，只保留原始值和健康計數：成功／失敗次數、最後一次錯誤、最後一次成功。
• 固定每 5 秒取樣一筆，失敗也記一筆並帶狀態碼。取樣間隔可在 2–5 秒之間調整；下限 2 秒是 DHT11 規格書的取樣週期，用 static_assert 擋住設太短的值。
• RAM 環形緩衝 720 筆，每筆 24 B，共 17,280 B，約可存 1 小時。
• 每筆帶 seq，開機從 1 起算；另有開機時以硬體亂數產生的 boot_id，巡檢端靠它分辨重開機。
• 時間用 NTP 校時，API 一律回 UTC epoch 秒；尚未校時則回 null。

# GET /api/v1/latest（API 文件中的範例，由主機端模擬器產生）
{
  "api_version": 1, "boot_id": "a21982ee",
  "seq": 5, "uptime_ms": 27000, "epoch": 1794318632,
  "temp_c": null, "humidity_pct": null, "status": "read_error",
  "time_utc": "2026-11-10T13:50:32Z",
  "last_ok": { "seq": 4, "temp_c": 25.4, "humidity_pct": 49.0, "status": "ok", ... }
}

先在主機上驗證：核心邏輯（環形緩衝、history 的視窗與缺口判斷、參數檢查、JSON 輸出）抽成一份與平台無關的標頭檔，韌體和 Mac 上的測試共用同一份程式。測試用 clang 加 AddressSanitizer 與 UBSan 編譯，結果單元測試 158 項、假裝置情境測試 47 項全數通過。為了確認測試真的抓得到錯，也刻意植入 4 種錯誤（例如缺口計算差一、has_more 恆為 false），每一種都會被測出來。

v0.3.0（11/11 凌晨）：secrets.h 最多可設 4 組 Wi‑Fi，支援一般密碼（WPA2／WPA3‑Personal）和企業帳號（WPA2‑Enterprise，PEAP／TTLS）。開機時用非同步掃描，取樣不受影響，自動連到訊號最強的已設定網路；某組連不上就扣分，改試下一組。實機測過第 1 組密碼錯誤的情況：連線失敗後，韌體自動改連第 2 組。主機端測試增加到 181＋47 項，Flash 用量 83%、RAM 20%。

實機驗收：板子上的晶片是 ESP32‑D0WD‑V3、4MB flash，有自動重置，燒錄時不用按 BOOT。API 驗收 30/30 通過：取樣間隔 4,998–5,002 ms，60 秒內 seq 增加 12，heap 最低剩 189,444 B；用 RTS 重開機後 boot_id 改變，巡檢範例程式也偵測到重開機。另外發現 mDNS 名稱在 Mac 上第一次解析要約 5 秒，因此建議巡檢服務改用 DHCP 保留的固定位址。

07即時監看頁：一個 HTML 檔，直接打 API

不需要後端，也不依賴任何外部資源；用瀏覽器打開檔案，輸入裝置位址就能看。

監看頁是單一 HTML 檔，AI 協助實作。它直接呼叫裝置的 API，因為裝置回應都帶 Access-Control-Allow-Origin: *，瀏覽器可以跨來源讀取。運作方式：

• 輪詢：每 5 秒呼叫 /api/v1/history?since=<上次的 seq> 增量拉資料，每 3 輪（約 15 秒）讀一次 /api/v1/health。分頁切到背景時暫停，回來時一次補齊；裝置只保留約 1 小時，離開更久就會出現缺口。
• 事件：boot_id 改變代表重開機，會從第 1 筆重新載入；API 回報 gap 時，會在事件欄記下漏了幾筆。
• 畫面：溫度與濕度大數字、感測器狀態（開機以來成功／失敗次數）、最新樣本距今幾秒；10 分鐘／30 分鐘／1 小時趨勢圖附十字線與 tooltip，沒資料的地方斷線，讀取失敗在底部標 ▲；另有裝置健康、事件與資料表。
• 不做判斷：頁面只顯示資料，沒有任何告警邏輯。裝置位址只存在瀏覽器的 localStorage，不寫進任何檔案。

驗證：對實機用 Playwright 跑 Chromium 與 WebKit，兩者直接開本機檔案 28/28 通過；對假裝置模擬讀取失敗、重開機、NTP 未同步，7/7 通過；淺色、深色與手機版都截圖檢查過。

08列印、接線、組裝、上線：閉環證據

實體的部分都由需求方本人完成；每一步都有照片或 log 可以對照。

第一次燒錄就失敗：兩條白線插反

11/10 22:49 第一次燒錄 v0.2.0（離線模式）。韌體正常開機，每 5.00 秒取樣、seq 也照常遞增，但每一筆都是 read_error。AI 另寫了一支診斷程式，只讀取各腳位電位並記錄 GPIO4 的回應波形，結果發現：

• GPIO4 被外部拉到地，連晶片內建的上拉都拉不起來。
• 送出啟動訊號後，感測器完全沒有回應（0 個訊號邊緣）。

由此判斷問題在模組那端的接線。請需求方拍照後確認：板子是 30 腳 DOIT（USB‑C、CP2102），模組絲印是 + out −，紫線接 3V3→+ 沒錯；兩條白線在模組端插反了（D4 接到 −、GND 接到 out）。23:04 對調後，診斷程式讀到 83 個邊緣、checksum 正確、26.7 °C／64 %RH；燒回主程式後，連續 8 筆都是 ok。之後文件補上「同色線容易插反，請對照絲印或換不同顏色的線」。

把時間串起來：11/11 清晨殼體印完（圖 10），約 06:00 裝好板子與感測器（圖 12）、上電；07:18 闔蓋的外觀（圖 13）與監看頁（圖 11）顯示這次開機已連續取樣 923 筆（約 77 分鐘），失敗 0 筆。從需求到上線形成閉環。

09技術與職能分工

一個人加幾個各管一段的 AI 協作者；每段都有書面任務單，明定範圍與驗收標準。

• OpenSCAD（Manifold）
• Python STL／干涉檢查
• 雲端 CAD 核對
• Cura 5.6／CuraEngine
• G-code 逐層分析
• Wokwi Elements＋無頭瀏覽器
• arduino-cli／ESP32 Arduino core
• Adafruit DHT
• C++ 主機端測試（ASan／UBSan）
• Python 假裝置與巡檢範例
• NTP／mDNS
• Prometheus 格式
• HTML＋SVG 監看頁
• Playwright
• three.js（本頁 3D）
• git

幾個讓協作順利的做法：

• 平行但不互踩。殼體和接線／韌體兩條線同時開工，任務單各自限定可寫入的目錄。殼體那邊只讀接線端的腳位表，對齊用詞，不改對方的檔案。
• 不確定就標出來。每個尺寸都標「官方／第三方實測／估計」；板型無法確認時兩種都做，並列出卡尺量測的優先順序，不把猜測當成定案。
• 驗證要能失敗。殼體檢查和韌體測試都刻意改壞過一次，確認檢查真的抓得到錯；實機驗收另外列清單逐項打勾。
• 實體環節留給人做。買料、列印、接線、拍照由需求方本人完成；AI 根據照片與診斷數據回饋問題，例如兩條白線插反。

10限制與後續

• 精度：DHT11 在 25 °C 時精度為 ±2 °C、±5 %RH，適合看趨勢；ESP32 也會自熱。建議和參考溫濕度計並放 30 分鐘，做一次偏移校正。
• 材料：一般 PLA 不阻燃，約 55–60 °C 開始軟化。放在 25 °C 的機房沒問題，但不要裝在設備出風口或陽光直射處。
• 資料只存在 RAM：裝置只保留約 1 小時，重開機就清空，長期資料要由巡檢服務保存。
• 還沒驗證的項目：緩衝存滿 720 筆時約 70 KB 的完整回應、連續一天的 heap 穩定性、實際關掉 AP 時的 Wi‑Fi 重連。
• 採購資料：BOM 已依實物更新，並在 11/11（三）以網路同等規格商品的現價完成詢價（見第 02 節）。網路標價會變動，也不保證和實購同批；要再做幾台時，下單前先確認是 30 腳板、USB 接頭與晶片，以及運費門檻。