現代實驗技術－物理

課前準備——請在工作坊 1 之前完成（workbook 第 0 章）
Modern Experimental Techniques – Physics

工作坊 1（實驗物理學家的 AI）之前——workbook 第 0 章

工作坊 1 從一開始就動手實作。在簡短介紹 AI 與我們使用的工具之後，你會在 VS Code 中用 Claude Code 做出兩樣東西：專案 1，一個你自選的網頁應用程式——模擬器或遊戲——部署（deploy：發布上線）到公開網路；以及專案 2，一個透過 WiFi 控制你的 ESP32（課堂提供的小型 WiFi 微控制器（microcontroller）板）並從它讀取量測值的手機 App。所以這些工具與帳號必須事先在你的筆電上正常運作。 這份清單很短，而且大部分由 Claude 代勞。以下每個步驟都附有一個 ✔ 檢查，讓你確認該步驟是否成功。任何安裝設定問題卡住了，就求助：從步驟 5 起，先請 Claude Code 診斷錯誤； 還是解決不了，就記下錯誤訊息，寄給授課教師（s.p.bennetts@g.iams.sinica.edu.tw）。

小提示：只有步驟 1–4 需要自己動手。從步驟 5 起，由 Claude Code 負責安裝，你負責看與批准；Cloudflare 帳號（步驟 7） 是另外唯一一件它無法代勞的事。這不是作弊——這正是本課程的重點。

  1. 一台可以自行安裝軟體的筆電，以及一條 USB-C 線

    Windows 10/11、macOS 或 Linux。你需要管理員權限與至少 10 GB 的可用磁碟空間。ESP32 開發板（dev board：載著微控制器的小板子）由課堂提供，其接頭為 USB-C。 請自備一條適合你筆電的 USB-C 資料線——USB-C 對 USB-C，或 USB-A 對 USB-C；只能充電的線沒有資料功能。授課教師有備用。

    ✔ 檢查：你不必請示任何人就能在這台筆電上安裝程式、有 10 GB 可用空間，而且資料線已放進包包。

  2. 安裝 Visual Studio Code

    從 code.visualstudio.com/download 下載，並以預設選項安裝 （在 Windows 上，出現選項時請勾選「Add to PATH」與「Open with Code」）。

    ✔ 檢查：VS Code 能開啟。選單 Help → About 顯示版本編號。

  3. 安裝 Claude Code 擴充功能並登入

    在 VS Code 中按 Ctrl+Shift+X（macOS 為 Cmd+Shift+X），搜尋 Claude Code（發行者：Anthropic）並點選 Install—— 或從 marketplace 頁面安裝這個擴充功能（extension）。 文件：Claude Code in VS Code。

    所有修課學生皆可使用 Claude（Team standard）：本課程 Claude 組織的邀請已於 9月6日（日）以電子郵件寄出。請接受邀請，並在擴充功能要求登入時使用該帳號登入。 （若邀請尚未寄達，請先安裝擴充功能，之後再登入，並告知授課教師。）上課時 Claude Code 也是你的 Claude 家教（tutor）： 在班級儲存庫（repository）中輸入 /tutor L1，它會用英文或中文帶你走過 workbook 的章節。

    ✔ 檢查：VS Code 側邊欄出現 Claude 圖示；登入後輸入「hello」可以得到回應。

  4. 建立一個本機課程資料夾，並在 VS Code 中開啟

    建立一個空資料夾，例如家目錄下的 tigp-2026。不要放在 OneDrive、Google Drive 或 Dropbox 的同步資料夾內（同步程式會和 git——記錄資料夾檔案歷史的工具——互相干擾）， 路徑中也不要有任何空格（部分工具鏈——建置韌體的編譯器與輔助程式——無法處理）。在 VS Code 中選 File → Open Folder… 並選取它。

    ✔ 檢查：資料夾名稱出現在 VS Code 檔案總管的最上方，且 Terminal → New Terminal 會在該資料夾開啟終端機（terminal：輸入指令的文字視窗）。

  5. 其餘交給 Claude

    在該資料夾中開啟 Claude Code（側邊欄的 Claude 圖示），貼上以下文字（指令保持英文原文即可）：

    Read https://raw.githubusercontent.com/TIGP-Experimental-Methods/class-board-2026/main/SETUP.md and follow it step by step. Ask me before installing anything, and tell me what each step is for in one sentence.

    接著 Claude 會安裝 git 並設定你的姓名與電子郵件、透過 uv（一個快速的 Python 安裝與套件管理工具）安裝 Python、安裝 GitHub CLI（GitHub 的命令列工具 gh；若你沒有 GitHub 帳號，它會請你建立一個，並在瀏覽器中登入）； 檢查你是否已是班級組織 TIGP-Experimental-Methods 的成員；把班級儲存庫（由 git 保存完整歷史的共用專案資料夾，在 GitHub 上也有線上版）class-board-2026 複製（clone：下載完整副本）到該資料夾； 安裝 PlatformIO（建置並燒錄（flash）韌體（firmware：在微控制器上執行的程式）的工具）並建置一次韌體，讓工具鏈下載完成；最後印出一份 「toolchain OK」報告。每次安裝前它都會先問你。 它遵循的說明就在 SETUP.md——純文字，好奇的話可以自己讀。

    ✔ 檢查：Claude 的報告顯示 toolchain OK。若失敗：先請 Claude 診斷；還是解決不了，就把報告寄給授課教師（s.p.bennetts@g.iams.sinica.edu.tw）。

  6. Claude 幫你設定了什麼（想的話可自行檢查）

    步驟 5 做的就是你原本要親手完成的清單；完整指令都在 SETUP.md。儲存庫 class-board-2026 收納全班共用的課程工作： firmware/、host/（參考手機 App＋instrument.py）、hardware/（KiCad）、workbook/、tutor/，以及你自己的資料夾 docs/students/<name>/。 你在分支（branch：各自獨立的工作線，讓多人修改時不互相干擾）上工作並開拉取請求（pull request：請求把你的分支合併進共用專案；會先有人審查）；main（主分支，大家共同依據的版本）受保護，由授課教師合併（merge）。你的專案 1 與專案 2 各自放在自己的資料夾，以及你個人帳號下各自的公開 GitHub 儲存庫中，並各有一個放在 GitHub Pages 上的專案網站；家教會檢查，並在每個里程碑提醒你推送（push）。在終端機中（VS Code Terminal → New Terminal）：

    • ✔ git --version 會印出版本編號，且 git config --global user.email 印出的是你 GitHub 帳號的電子郵件——兩者必須相同，否則 GitHub 不會把你的提交（commit：你所做修改的存檔快照）記在你名下。
    • ✔ uv --version 會印出版本編號。
    • ✔ gh auth status 顯示你已登入。
    • ✔ 你的課程資料夾內有 class-board-2026 資料夾，且在其中執行 git status 顯示 On branch main。
    • ✔ 在該資料夾中執行 pio run -e esp32s3-sim，結尾顯示 SUCCESS。

    兩個容易忽略的地方：組織成員資格需要授課教師的邀請——若 Claude 回報你尚未是成員，請把你的 GitHub 使用者名稱寄給授課教師， 稍後再重新檢查。另外，第一次 pio run 會下載 ESP32 工具鏈（數百 MB）；它必須在工作坊 1 之前完成，因為當天教室網路由全班共用。

  7. 建立免費的 Cloudflare 帳號並連上 GitHub

    這一步要自己動手——Claude 可以告訴你該點哪裡，但無法替你註冊。工作坊 1 中，你會把你的專案部署到公開網路，而且你可能兩個主機都需要——兩個帳號都要準備好：靜態網頁（專案網站；完全在瀏覽器裡執行的 App）放在 GitHub Pages（把公開儲存庫變成公開網頁的免費服務——有 GitHub 帳號就夠）；任何有後端、機器人網頁掛鉤（webhook）或機密的東西（LINE 或 Telegram 機器人、API 金鑰、排程工作）放在 Cloudflare Pages＋Workers（免費方案；能執行伺服器端程式碼）。 到 dash.cloudflare.com/sign-up 註冊（免費方案；驗證電子郵件）。然後連上 GitHub 一次：在儀表板進入 Workers & Pages → Create → Pages → Connect to Git，授權 Cloudflare 存取你的 GitHub 帳號，到這裡就停——專案本身在課堂上建立。

    ✔ 檢查：已登入 Cloudflare 儀表板；「Connect to Git」畫面列出你的 GitHub 帳號。（若 Cloudflare 註冊失敗，工作坊 1 可以先只用 GitHub Pages——不需要再裝任何東西——但在你做任何有後端的東西之前，要先把帳號弄好。）

  8. 想一想你要做什麼！

    專案 1 是一個你自選的網頁應用程式——模擬器或遊戲。建議：貨運列車裝載遊戲 · 倒立擺模擬器 · 耦合擺的相位鎖定 · 不公平的高爾夫 · 撞球 · 為你研究中的某個題目做的計算器或模擬器。專案 2 是一個透過 WiFi 控制你的 ESP32 並從它讀取量測值的手機 App——例如先控制它 LED 的亮度與顏色，然後在手機上即時顯示一個量測值。想試做相機 App 的人，有一台 ESP32-S3-N16R8-CAM 開發板 + OV3660 鏡頭（金華 #41395）可用。

    班級板——每個人專案 3 儀器的共用平台——是一塊電路板、三個區塊（section）：A（類比輸入與 NMR 接收器）、B（訊號產生、時序與 NMR 發射器）與 C（前面板電路板）；你的區塊會在工作坊 2 開始時分配，所以事前沒有什麼需要選擇。不過，請帶著來自你自己實驗室的問題：有了這樣一台儀器，你會想監測、觸發、切換或自動化什麼？

    ✔ 檢查：你能用一句話說出你的專案 1 會是什麼，並說出一件自己實驗室裡想用手機控制或量測的事。

工作坊 2（設計印刷電路板）需要——課間

下一場工作坊之前：完成課前準備、改進你的 App、動手做、玩得開心。課前準備——工作坊 2 之前有兩件事必須就緒：

  1. 安裝 KiCad 10 並開啟一次

    KiCad 是我們用來畫電路圖（schematic：電路繪圖）與佈局印刷電路板（PCB）的免費軟體；工作坊 2 時它必須能在你的筆電上執行。從 kicad.org/download 下載目前的穩定版（第 10 版），連同預設程式庫一併安裝。 安裝後先啟動一次，讓它完成符號庫與封裝庫的設定（符號（symbol）是零件在電路圖中的圖形；封裝（footprint）是零件焊上去的銅箔圖形）。然後開啟班級專案：班級儲存庫 hardware/ 內的 class-board.kicad_pro——專案零件庫已在裡面，不需要解壓縮任何東西。

    ✔ 檢查：KiCad 能開啟；File → New Project 可用，且能開啟 Schematic Editor（電路圖編輯器）；班級專案開啟時沒有缺少程式庫的警告。

  2. 建立 JLCPCB 帳號

    JLCPCB 負責製造與組裝班級板，零件來自它自己的零件庫（料號形如 C12345）。只需要一個免費帳號；不需要 LCSC 帳號。現在不需要付款。

    ✔ 檢查：兩個網站你都能登入。

工作坊 3（韌體與基礎機械設計）之前

  1. 讓家教幫你安裝 OpenSCAD 2021.01，然後開啟一次

    在 VS Code 開啟班級儲存庫並執行 /tutor L3：家教會更新你的儲存庫，並安裝 OpenSCAD（穩定版 2021.01）、它的 BOSL2 函式庫與 Bambu Studio，每個指令都會先徵求你的同意；你也可以自己從連結安裝。專案 3 的一部分是為你的儀器做一個外殼（housing）。它的幾何形狀用 OpenSCAD 撰寫（免費；零件是一個由形狀構成的短文字檔：Claude Code 寫它，你讀它並修改數字）。請安裝穩定版 2021.01，不要裝開發快照版（development snapshot）。開啟一次，選 New，並打開 Design → Automatic Reload and Preview（每次存檔預覽就會重畫）與 Window → Customizer（把檔案開頭的變數變成滑桿的面板）。接著一次看一塊板子：在你的資料夾 docs/students/<name>/housing/ 存一個新檔，只寫一行 import("../../../../hardware/release/front-panel.stl");，按 F5，前面板就會出現；把檔名換成 class-board.stl 就是主板（SETUP.md 第 11a 步）。

    ✔ 檢查：Help → About OpenSCAD 顯示 2021.01；預覽中看得到外殼，兩塊板子以透明方式在裡面，主控台（console）沒有 Can't open import file 警告。

  2. 安裝 Bambu Studio 並開啟一次

    Bambu Studio 是實驗室 Bambu Lab P1S 印表機用的切片軟體（slicer：把 3D 模型轉成印表機要走的層與路徑的程式）。在首次啟動精靈中選擇印表機 Bambu Lab P1S 與 0.4 mm 噴嘴。外殼由研究所負責列印與切割；你先自己切片，在交出前檢查它。

    ✔ 檢查：Bambu Studio 開啟時顯示 P1S 的列印板（256 × 256 mm）；用 File → Import 匯入一個 STL（3D 列印檔），零件會放到列印板上。

    家教（tutor）會帶你完成兩項安裝：班級儲存庫 SETUP.md 的設定步驟 11。

  3. 可選：其他 CAD 軟體

    如果你已經在用其他 CAD 軟體（computer-aided design，電腦輔助設計：畫零件用的程式），可以改用它來畫外殼，以 hardware/release/ 裡的電路板模型（STEP 與 STL）為準，只要裝得下兩塊板子並趕上截止日期；匯出列印用的 STL 及／或雷射切割用的 DXF 圖檔即可。免費選項：FreeCAD 1.1（完整的 CAD 軟體，有草圖、組合件與工程圖）、CadQuery 與 build123d（Python 函式庫，精確幾何、可匯出 STEP；AI 寫得很好；檢視器用 VS Code 的 OCP CAD Viewer 擴充功能）。已經在用 Onshape 或 SolidWorks 的人也可以直接用。需要的話家教可以幫你設定（設定步驟 11c）。