ckochandClaude Opus 5.5
8a377af116
pi/build-image.sh makes a ready-to-flash card: Raspberry Pi OS Lite 2026-10-06 + the Gyre software as a service on http://gyre.local (port 80), first-boot setup through cloud-init (user, SSH key, Wi-Fi, packages from the card), USB host mode on the Zero 2's data port. No root: mtools for the boot partition, debugfs for the root filesystem. Wi-Fi and credentials stay in the work dir. Web page: Power off / Restart links when GYRE_POWER_BUTTONS=1 (set by the Pi service); thumbnails keyed by file contents so pre-made ones ship on the card; stale thumbnails pruned. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
45 lines
3.2 KiB
Markdown
45 lines
3.2 KiB
Markdown
# 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.
|