A Raspberry Pi kiosk system for National Parks, museums, and similar venues. Upload up to 10 images and videos through a browser-based interface — they either loop as a kiosk slideshow or play on demand when a visitor presses a physical button. Supports up to 7 buttons.
| Mode | Setup | Behavior |
|---|---|---|
| Kiosk slideshow | Upload images and/or videos; leave all unassigned | Media loops continuously as a slideshow — no buttons needed. Videos play to completion; images display for 10 seconds each. |
| Kiosk + buttons | Upload media; assign some to buttons, leave the rest unassigned | Unassigned media loops as a kiosk slideshow. A button press interrupts the slideshow and plays the assigned video. Returns to the slideshow when done. |
| Buttons only | Upload videos; assign all to buttons | Screen is black until a visitor presses a button. The assigned video plays fullscreen, then the screen returns to black. |
- Low cost, durable hardware. A Raspberry Pi costs a fraction of a full computer and is easy to replace if damaged.
- No moving parts. No fan, no spinning hard drive — nothing to wear out or fail in a dusty exhibit environment.
- Self-contained storage. A 32 GB SD card holds roughly 8–30 hours of video content depending on resolution and bitrate — more than enough for a typical kiosk deployment.
A selector interface is planned to support more than 7 videos on the same hardware: a menu with up/down navigation and a play button would let visitors browse a larger library without needing additional GPIO pins.
A printable enclosure is available: OpenSCAD source · STL
For architecture, build, and fork instructions see DEVELOPER.md.
See the Pi Imager Setup Guide for a step-by-step walkthrough with screenshots.
Insert the SD card, power on the Pi, and wait about 2 minutes. First boot runs a full system update before the unit comes online.
Connect momentary push buttons between each GPIO pin and any GND pin. The Pi's GPIO pins have internal pull-up resistors that the daemon enables at startup — no external pull-up resistors or other components are needed for the switch circuit.
See wiring.svg for the full diagram. For optional LED illumination on the buttons, see wiring-led.svg.
| Button | GPIO | Physical Pin |
|---|---|---|
| 1 | 4 | 7 |
| 2 | 17 | 11 |
| 3 | 22 | 15 |
| 4 | 23 | 16 |
| 5 | 24 | 18 |
| 6 | 25 | 22 |
| 7 | 27 | 13 |
All buttons share a common ground. Connect the ground side of each button to a ground bus (terminal block strip), then run a single wire from the bus to any GND terminal on the HAT (pins 6, 9, 14, 20, 25…).
If you are using illuminated buttons, use a second terminal strip as a 3.3V power bus — run one wire from Pi Pin 1 or Pin 17 (3.3V) to the strip, then a short wire from the strip to each button's LED+ terminal. This keeps wiring tidy and avoids running seven individual wires back to the Pi.
Important: The GND bus and the LED power bus carry different voltages. Keep them physically separated — they must not touch. Secure both strips so they cannot shift or vibrate into contact with each other (hot glue, cable ties, or mounting to the enclosure wall all work well).
The GPIO Screw Terminal HAT plugs directly onto the Pi's 40-pin header. Each GPIO pin becomes a labeled screw terminal — no soldering required.
- Press the HAT onto the 40-pin header
- Run a wire from the GPIO terminal to one side of the button
- Run a wire from the GND terminal to the other side of the button
- Tighten with a small flathead screwdriver
For arcade-style buttons, use 0.25" quick-connect wires — they slip directly onto the button's spade terminals, no crimping or soldering needed.
Open a browser and go to http://<hostname>.local:8080.
The page shows a media library (up to 10 files). Each entry displays the filename, file size, and a dropdown to assign it to a button or leave it in the kiosk rotation.
- Upload — select an image or video file; it is added to the library immediately
- Assign to button — use the dropdown next to any media entry to assign it to a button (1–7). Assigned media plays on button press instead of appearing in the kiosk slideshow.
- Delete — remove a file from the library and disk
Changes take effect instantly — no restart required.
1080p H.264 .mp4 is recommended for video. The Raspberry Pi hardware decoder handles 1080p smoothly with minimal CPU load. 4K is not recommended — it requires software decoding and will stutter.
| Type | Format | Extension(s) |
|---|---|---|
| Video | MPEG-4 | .mp4, .m4v |
| Video | Matroska | .mkv |
| Video | QuickTime | .mov |
| Video | WebM | .webm |
| Video | AVI | .avi |
| Video | Flash Video | .flv |
| Video | Windows Media | .wmv |
| Video | MPEG | .mpg, .mpeg |
| Video | Transport Stream | .ts, .m2ts |
| Video | Mobile | .3gp |
| Image | JPEG | .jpg, .jpeg |
| Image | PNG | .png |
| Image | WebP | .webp |
| Image | BMP | .bmp |
| Image | GIF | .gif |
Keep a folder on your admin machine named after each Pi's hostname. This makes it easy to manage multiple deployments and re-upload media if a Pi needs to be reflashed.
~/pivideo/
glacier-visitor-center/
glacier_intro.mp4 → assigned to Button 1
wildlife.mp4 → assigned to Button 2
trail_map.jpg → kiosk rotation
welcome_loop.mp4 → kiosk rotation
canyon-trailhead/
welcome.mp4 → assigned to Button 1
safety.mp4 → assigned to Button 2
canyon_panorama.jpg → kiosk rotation
Everything needed to build a working 3-button kiosk. Adjust the power supply and HDMI cable to match whichever Pi model you buy.
| Item | Qty | Notes |
|---|---|---|
| Raspberry Pi (3 B+, 4, or 5 — whichever is in stock) | 1 | Any of these models works; buy what's available |
| 32 GB microSD card (Class 10 / A1 rated) | 1 | |
| Official Pi 4 USB-C power supply (3A) | 1 | |
| micro-HDMI to HDMI cable | 1 | |
| GPIO Screw Terminal HAT | 1 | |
| 16mm metal pushbutton | 3 | Any color; LED ring optional |
| Spade connector wire 3ft female (2-pack) | 3 | 6 wires needed — 1 signal + 1 GND per button |
| 22 AWG stranded hookup wire | 1 spool | Two colors recommended. Cut short lengths for: HAT GND terminal → ground bus, and HAT 3.3V terminal → power bus (if using LEDs). |
| Ground bus / terminal strip | 1 | For shared GND; add a second if using LEDs |
If using the LED ring on the buttons, also add:
| Item | Qty | Notes |
|---|---|---|
| Spade connector wire 3ft female (2-pack) | 2 | 3 more wires for LED+ connections |
| Ground bus / terminal strip | 1 | Serves as the 3.3V power bus |
Tools needed:
| Tool | Notes |
|---|---|
| Small flathead screwdriver | For screw terminal HAT |
| Wire stripper (22–24 AWG) | |
| Spade terminal crimper | Only if crimping your own terminals instead of using pre-made wires |
| 16mm metric hole saw | For mounting buttons; panel must be ≤ 1/2" (13mm) thick. No US fractional equivalent — 5/8" is slightly undersized and won't fit. |
Available from raspberrypi.com and authorized resellers. The Pi 3 B+, Pi 4 B, or Pi 5 (2GB or 4GB) are the recommended choices — right balance of performance and cost. Older models (Pi 1, Pi 2) are not recommended; video playback will be sluggish.
Availability varies — some models are frequently out of stock. Any model in the table below will work; buy whichever is in stock and within budget at the time.
| Model | Power | HDMI | Notes |
|---|---|---|---|
| Pi 3 Model B | Micro USB, 5V 2.5A | Full-size HDMI | |
| Pi 3 Model B+ | Micro USB, 5V 2.5A | Full-size HDMI | Recommended |
| Pi 4 Model B | USB-C, 5V 3A | micro-HDMI | Recommended |
| Pi 5 (2GB) | USB-C, 5V 5A | micro-HDMI | Recommended |
| Pi 5 (4GB) | USB-C, 5V 5A | micro-HDMI | Recommended |
| Pi 5 (8GB) | USB-C, 5V 5A | micro-HDMI | More than needed |
| Pi 5 (16GB) | USB-C, 5V 5A | micro-HDMI | Overkill |
| Pi Zero 2 W | Micro USB, 5V 2.5A | mini-HDMI | Budget option; adequate for 1080p |
Where to buy:
| Model | Adafruit | Sparkfun |
|---|---|---|
| Pi 3 Model B | Adafruit | — |
| Pi 3 Model B+ | Adafruit | Sparkfun |
| Pi 4 Model B (1 GB) | Adafruit | Sparkfun |
| Pi 4 Model B (2 GB) | Adafruit | Sparkfun |
| Pi 4 Model B (4 GB) | Adafruit | Sparkfun |
| Pi 4 Model B (8 GB) | Adafruit | Sparkfun |
| Pi 5 (2GB) | Adafruit | Sparkfun |
| Pi 5 (4GB) | Adafruit | Sparkfun |
| Pi 5 (8GB) | Adafruit | Sparkfun |
| Pi 5 (16GB) | Adafruit | Sparkfun |
Use the official Raspberry Pi power supply for your model. Third-party supplies that skimp on current cause instability under video load.
| Pi Model | Connector | Adafruit | Sparkfun |
|---|---|---|---|
| Pi 3 Model B / B+ / Pi Zero 2 W | Micro USB 2.5A | Adafruit | Sparkfun |
| Pi 4 Model B | USB-C 3A | Adafruit | Sparkfun |
| Pi 5 | USB-C 5A (27W) | Adafruit | Sparkfun |
Match the cable to your Pi model.
| Pi Model | Cable needed | Buy |
|---|---|---|
| Pi 3 Model B / B+ | Standard HDMI to HDMI | Adafruit · Sparkfun |
| Pi 4 Model B | micro-HDMI to HDMI | Adafruit · Sparkfun |
| Pi 5 | micro-HDMI to HDMI | Adafruit · Sparkfun |
| Pi Zero 2 W | mini-HDMI to HDMI | Adafruit · Sparkfun |
Plugs onto the Pi's 40-pin header; every pin becomes a labeled screw terminal. No soldering required.
- Adafruit — Pi-EzConnect Terminal Block Breakout HAT
- CZH Labs — Ultra Small RPi GPIO Terminal Block Breakout Board
If using the Pi-EzConnect, also add:
| Item | Qty | Notes |
|---|---|---|
| Nylon standoff M2.5×12mm F-F | 4 | Mounts the HAT above the Pi |
| Nylon screw M2.5×6mm | 4 | Secures HAT to standoffs |
| Nylon nut M2.5 | 4 | |
| Washer M2.5 | 4 |
The Adafruit White Nylon Machine Screw and Stand-off Set (#3658) contains all of the above.
One per button-assigned video, up to 7. Any normally-open momentary contact switch works. Three common options:
Metal pushbuttons with LED ring (recommended) — chrome-plated, 16mm panel-mount, rated for heavy use. The built-in LED is optional; the switch works without it. See wiring-led.svg for LED wiring details (connect LED+ to 3.3V, LED− to GND — LEDs are always on, no software changes needed). The Sparkfun and Adafruit buttons listed below have a built-in current-limiting resistor, so no external resistor is required. If you use a different LED switch that lacks one, add a 150 Ω resistor in series with LED+.
| Color | Adafruit | Sparkfun |
|---|---|---|
| Red | Adafruit | Sparkfun |
| Blue | Adafruit | Sparkfun |
| Green | Adafruit | Sparkfun |
| White | Adafruit | Sparkfun |
| Yellow | — | Sparkfun |
Arcade-style buttons — large, colorful, satisfying click. Popular for kiosks. Simple two-wire connection, no resistors needed. Available with or without LED illumination.
| Color | Sparkfun (no LED) | Adafruit (with or without LED) |
|---|---|---|
| Red | Sparkfun | Adafruit multi-pack |
| Blue | Sparkfun | Adafruit multi-pack |
| Yellow | Sparkfun | Adafruit multi-pack |
| Black | Sparkfun | Adafruit multi-pack |
| White | Sparkfun | Adafruit multi-pack |
| Green | Sparkfun | Adafruit multi-pack |
The Adafruit link sells a pack of multiple colors, with and without LED rings. Arcade buttons use 0.25" (6.35mm) quick-connect terminals — pre-made 0.25" female quick-connect wires slip on directly, no crimping needed.
Any momentary switch — any normally-open momentary contact switch works. If it has two terminals and closes a circuit when pressed, it will work.
The 16mm metal pushbuttons use 2.8mm (0.110") female spade terminals. Two wires per button: one for signal, one for ground.
Pre-made option — spade connector wires with the terminal already attached, just slip onto the button and run to the screw terminal HAT:
Crimp your own — use 22 AWG stranded wire cut to length with 2.8mm female spade terminals crimped on one end. Requires a spade terminal crimper (search: "2.8mm female spade terminal crimper") and a bag of 2.8mm female spade terminals.
22 AWG stranded hookup wire. Buy two colors — one for signal, one for ground.
- Flexible enough to route through an enclosure
- Seats cleanly in screw terminals
- 24 AWG works too; avoid solid-core (fatigues at screw terminals)
All button ground wires meet at a ground bus, then a single wire runs from the bus to a GND terminal on the HAT. If using illuminated buttons, a second identical strip serves as the 3.3V bus.
- Square D 9-Terminal Ground Bar Kit (Home Depot) — solid, screw-terminal ground bar; more than enough for 7 buttons
- Search: "barrier strip terminal block" for smaller alternatives
- Wire stripper (22–24 AWG range)
- Small flathead screwdriver (for screw terminal HAT)
- Spade terminal crimper (if crimping your own 2.8mm terminals)
- 16mm metric hole saw (for mounting buttons; panel must be ≤ 1/2" / 13mm thick — 5/8" US bits are slightly undersized and won't fit)