sandTable/pi/README.md

Gyre on a Raspberry Pi Zero 2 W

A Raspberry Pi Zero 2 W inside the table runs the Gyre software by itself, so you don't need a computer. Open http://gyre.local on any phone or computer on your Wi-Fi.

What you need

• A Raspberry Pi Zero 2 W and a microSD card (8 GB or more).
• Power: a 12 V to 5 V (3 A) step-down converter with a micro-USB plug. Its input goes to the 12 V terminal on the CNC shield, beside the supply wires; the plug goes into the Pi's PWR port. The table keeps one power plug.
• To the Uno: a micro-USB (male) to USB-B (male) cable, or a micro-USB OTG adapter plus the Uno's usual cable. It goes in the Pi's USB port, not PWR. It also powers the Uno.
• Wi-Fi: a 2.4 GHz network. The Pi Zero 2 W has no 5 GHz radio.

Build the card image

pi/build-image.sh              # work dir ~/Documents/gyre-pi (or give another one)

1. First run: it copies settings.example.env to ~/Documents/gyre-pi/settings.env and stops. Fill in your Wi-Fi name, password and country.
2. Run it again. In about a minute it writes ~/Documents/gyre-pi/out/gyre-pi.img.xz.
   • What it does: it downloads Raspberry Pi OS Lite (2026-10-06, 64-bit) and 12 small packages (pyserial and Pillow), all checksum-checked. Then it puts the Gyre software, the packages and the first-boot settings into the image.
   • No root needed.
   • Login details: a password for the gyre user and an SSH key (~/.ssh/gyre_pi) are made for you. Both are written to ~/Documents/gyre-pi/CREDENTIALS.txt.
   • Kept out of the repository: your Wi-Fi password and the credentials.

Write and start it

1. Write the card: in Raspberry Pi Imager, choose Raspberry Pi Zero 2 W, then Choose OS → Use custom and pick gyre-pi.img.xz. When it offers OS customisation, answer No; everything is already set.
2. Start it: put the card in the Pi and power the table. The first start takes a few minutes. The Pi:
   • joins your Wi-Fi as gyre;
   • creates the gyre user;
   • installs the packages from the card;
   • starts the Gyre service, which restarts itself if it ever stops.
3. Open the page: go to http://gyre.local. If your device doesn't support .local names, use the Pi's address from your router.

On the page

• Power off and Restart: links at the bottom, shown only on the Pi. Use Power off before unplugging the table. Pulling the plug on a running Pi can corrupt its card. Power off stops any design and switches the motors off first.
• Everything else works as on a computer. See ../software/README.md.

Maintenance

• Log in: ssh -i ~/.ssh/gyre_pi gyre@gyre.local (key only). The password in CREDENTIALS.txt is for the console and sudo.
• Service commands:
  • systemctl status gyre
  • journalctl -u gyre -f
  • sudo systemctl restart gyre
• Files: the software is in /opt/gyre/software; your uploads go to /opt/gyre/software/patterns/uploads.
• Settings:
  • config.txt puts the Pi Zero 2 W's micro-USB data port in USB host mode. So any micro-USB to USB-B cable works, not only "OTG" ones.
  • The service runs as gyre (in the dialout group, for the Uno's port). It's allowed onto port 80, and allowed sudo only for power off and restart.