Before Workshop 1 (AI for experimentalists) — workbook chapter 0

Workshop 1 is hands-on from the start. After a short introduction to AI and the tools we use, you build two things with Claude Code in VS Code: Project 1, a web app you choose — a simulator or a game — deployed (published so it is live) on the public web; and Project 2, a phone app that controls and measures from your ESP32 (the small WiFi microcontroller board, provided) over WiFi. So the tools and accounts must already work on your laptop. This list is short, and Claude does most of it for you. Every step below has a ✔ check that tells you it worked. If you are stuck on any setup problem, ask for help: from step 5 on, ask Claude Code to diagnose the error first; if that does not fix it, note the error message and email it to the instructor (s.p.bennetts@g.iams.sinica.edu.tw).

Tip: only steps 1–4 are done by hand. From step 5 on, Claude Code does the installing while you watch and approve; the Cloudflare account (step 7) is the only other thing it cannot do for you. That is not cheating — it is the point of the course.

1. A laptop you can install software on, and a USB-C cable

   Windows 10/11, macOS or Linux. You need administrator rights and at least 10 GB of free disk space. The ESP32 dev board (the small board carrying the microcontroller) is provided; its connector is USB-C. Bring a USB-C data cable that fits your laptop — USB-C to USB-C, or USB-A to USB-C; charging-only cables do not carry data. The instructor has spares.

   ✔ check: You can install a program on this laptop without asking anyone, 10 GB are free, and the cable is in your bag.

2. Install Visual Studio Code

   Download from code.visualstudio.com/download and install with default options (on Windows, tick "Add to PATH" and "Open with Code" when offered).

   ✔ check: VS Code opens. In the menu Help → About shows a version number.

3. Install the Claude Code extension and sign in

   In VS Code press Ctrl+Shift+X (macOS Cmd+Shift+X), search for Claude Code (publisher: Anthropic) and click Install — or install from the marketplace page. Documentation: Claude Code in VS Code.

   Access to Claude (Team standard) is provided to all enrolled students: the invitation to the course's Claude organization was e-mailed on Sunday 6 September. Accept it and sign in with that account when the extension asks. (If the invitation has not arrived, install the extension now, sign in later, and tell the instructor.) In class, Claude Code is also your tutor: /tutor L1 in the class repository walks you through the workbook chapter, in English or Mandarin.

   ✔ check: A Claude icon appears in the VS Code side bar; after signing in you can type "hello" and get an answer.

4. Create a local course folder and open it in VS Code

   Make an empty folder, for example tigp-2026 in your home directory. Not inside a OneDrive, Google Drive or Dropbox sync folder (sync clients fight with git, the tool that records the history of a folder of files), and with no spaces anywhere in the path (some toolchains — the compiler and helper programs that build the firmware — choke on them). In VS Code choose File → Open Folder… and pick it.

   ✔ check: The folder name shows at the top of the VS Code Explorer, and Terminal → New Terminal opens a terminal (the text window where you type commands) in that folder.

5. Let Claude prepare the rest

   Open Claude Code in that folder (the Claude icon in the side bar) and paste:

   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 then installs git and sets your name and e-mail, Python via uv (a fast installer and package manager for Python), and the GitHub CLI (GitHub's command-line tool, gh; it will ask you to create a GitHub account if you have none, and to log in in the browser); checks that you are a member of the class organization TIGP-Experimental-Methods; clones (downloads a full copy of) the class repository (the shared project folder whose complete history git keeps; it also lives online on GitHub) class-board-2026 into the folder; installs PlatformIO (the tool that builds and flashes the firmware — the program that runs on the microcontroller) and builds the firmware once so the toolchain is downloaded; and prints a "toolchain OK" report. It asks before every install. The instructions it follows are in SETUP.md — plain text, read them yourself if you are curious.

   ✔ check: Claude's report says toolchain OK. If it fails: ask Claude to diagnose it first; if that does not fix it, e-mail the report to the instructor (s.p.bennetts@g.iams.sinica.edu.tw).

6. What Claude set up (check it yourself if you like)

   Step 5 is the same list you would otherwise work through by hand; the exact commands are in SETUP.md. The repository class-board-2026 holds the shared course work: firmware/, host/ (the reference phone app + instrument.py), hardware/ (KiCad), workbook/, tutor/, and your own folder docs/students/<name>/. You work on branches (separate lines of work, so several people can change things without treading on each other) and open pull requests (a request to merge your branch into the shared project; someone reviews it first); main (the main branch, the version everyone builds on) is protected and the instructor merges. Your Project 1 and Project 2 each live in their own folder and their own public GitHub repository under your personal account, each with a project website on GitHub Pages; the tutor checks this and prompts you to push at every milestone. In a terminal (VS Code Terminal → New Terminal):

   • ✔ git --version prints a version, and git config --global user.email prints the e-mail of your GitHub account — they must match, or GitHub will not credit your commits (saved snapshots of your changes).
   • ✔ uv --version prints a version.
   • ✔ gh auth status says you are logged in.
   • ✔ The folder class-board-2026 exists inside your course folder, and git status in it says On branch main.
   • ✔ pio run -e esp32s3-sim in that folder ends with SUCCESS.

   Two things that are easy to miss: organization membership needs an invitation from the instructor — if Claude reports that you are not a member yet, send your GitHub username to the instructor and rerun the check later. And the first pio run downloads the ESP32 toolchain (several hundred MB); it must finish before Workshop 1, when the classroom network is shared by everyone.

7. Create a free Cloudflare account and connect it to GitHub

   This one you do by hand — Claude can tell you where to click but cannot sign up for you. In Workshop 1 you deploy your projects to the public web, and you may need both hosts — have both accounts ready: a static page (the project website; an app that runs entirely in the browser) goes on GitHub Pages (a free service that turns a public repository into a public web page — your GitHub account is enough); anything with a backend, a bot webhook or a secret (a LINE or Telegram bot, an API key, a scheduled task) goes on Cloudflare Pages + Workers (free tier; runs server-side code). Sign up at dash.cloudflare.com/sign-up (free plan; verify the email). Then, once, connect GitHub: in the dashboard go to Workers & Pages → Create → Pages → Connect to Git, authorise Cloudflare for your GitHub account, and stop there — you create the project itself in class.

   ✔ check: Signed in to the Cloudflare dashboard; the "Connect to Git" screen lists your GitHub account. (If Cloudflare sign-up fails, Workshop 1 can start on GitHub Pages alone — nothing else to install — but sort the account out before you build anything with a backend.)

8. Think about what you want to make!

   Project 1 is a web app of your choice — a simulator or a game. Suggestions: loading a freight train game · an inverted pendulum simulator · phase-locking coupled pendula · unfair golf · billiards · a calculator or simulator for something from your research. Project 2 is a phone app that controls and measures from your ESP32 over WiFi — for example the brightness and colour of its LED first, then a measurement shown live on the phone. For anyone who wants to try a camera app, one ESP32-S3-N16R8-CAM 開發板 + OV3660 鏡頭 (Jinhua #41395) is available.

   The class board — the shared platform of every Project 3 instrument — is one board in three sections — A (the analog inputs and the NMR receiver), B (signal generation, timing and the NMR transmitter) and C (the front panel board); your section is assigned at the start of Workshop 2, so there is nothing to choose beforehand. Do come with a problem from your own lab, though: what would you monitor, trigger, switch or automate with such an instrument?

   ✔ check: You can say in one sentence what your Project 1 will be, and name one thing in your own lab you would control or measure with your phone.

Needed at Workshop 2 (Designing printed circuit boards) — between the workshops

Before the next workshop: complete the preparation, improve your apps, build and have fun. The preparation — two things that must be ready before Workshop 2:

1. Install KiCad 10 and open it once

   KiCad is the free program we draw the schematic (circuit drawing) and lay out the printed circuit board in; it must be running on your laptop at Workshop 2. Download the current stable release (version 10) from kicad.org/download. Install with the default libraries. Start it once so it finishes configuring the symbol and footprint libraries (a symbol is a part's drawing in the schematic; a footprint is the copper pattern it is soldered onto). Then open the class project, class-board.kicad_pro in hardware/ of the class repository — the project library is already there, nothing to unzip.

   ✔ check: KiCad opens; File → New Project works and you can open the Schematic Editor; the class project opens without missing-library warnings.

2. Create a JLCPCB account

   JLCPCB manufactures and assembles the class board, and its own parts library is where our parts come from (the part numbers look like C12345). One free account is all you need; no LCSC account. No payment needed now.

   ✔ check: You can log in to both sites.

Before Workshop 3 (Firmware and basic mechanical design)

1. Let the tutor install OpenSCAD 2021.01, then open it once

   Part of Project 3 is a housing for your instrument. Its geometry is written in OpenSCAD (free; a part is a short text file of shapes: Claude Code writes it, you read it and change the numbers). Open the class repository in VS Code and run /tutor L3: the tutor updates your repository and installs OpenSCAD (the stable release, 2021.01), its BOSL2 library and Bambu Studio, asking your approval for each command; or install them yourself from the links. Open OpenSCAD once, choose New, and turn on Design → Automatic Reload and Preview (the preview redraws whenever the file is saved) and Window → Customizer (the panel that turns the variables at the top of a file into sliders). Then look at the boards one at a time: a new file saved in your folder docs/students/<name>/housing/ with the single line import("../../../../hardware/release/front-panel.stl");, F5, and the front panel appears; the same line with class-board.stl shows the main board (SETUP.md Step 11a).

   ✔ check: Help → About OpenSCAD shows 2021.01; the preview shows the housing with the two boards transparent inside it, and the console shows no Can't open import file warning.

2. Bambu Studio, and open it once

   Bambu Studio is the slicer (the program that turns a 3D model into the layers and paths the printer follows) for the lab's Bambu Lab P1S printers. In the first-start wizard choose the printer Bambu Lab P1S with the 0.4 mm nozzle. The institute prints and cuts the housings; you slice yours to check it before you hand it in.

   ✔ check: Bambu Studio opens with the P1S plate (256 × 256 mm); File → Import of an STL (the 3D-print file) lays the part on the plate.

   Both installs are setup step 11 in the class repository's SETUP.md.

3. Optional: another CAD program

   If you already design in another CAD program (computer-aided design: the program a part is drawn in), you may draw your housing there instead, around the board models in hardware/release/ (STEP and STL), as long as it fits the boards and meets the deadline; you export an STL for printing and/or a DXF (the laser-cutting drawing). Free options: FreeCAD 1.1 (a full CAD program with sketches, assemblies and drawings), CadQuery and build123d (Python libraries with exact geometry and STEP export; the AI writes them well; viewer: the OCP CAD Viewer extension of VS Code). Onshape or SolidWorks are fine if you already use them. The tutor can set any of these up on request (setup step 11c).