ZEPIR — Raspberry Pi Zero Universal Linux Handheld HAT

Pi Zero + Zero extra chips. Fully transparent, fully yours.

ZEPIR is a minimal HAT that transforms a Raspberry Pi Zero (or Zero 2 W) into a complete pocket Linux computer — with a real keyboard, display, and speaker. No proprietary chips, no black boxes. Every component is standard, every line of code is visible and customizable. The perfect open foundation for handhelds, cyberdecks, and pocket terminals.

> ⚠️ This is not plug & play. It requires basic Linux experience — configuring overlays, editing config files, and running Python scripts. If you enjoy tinkering, you'll love it. When in doubt, feel free to ask!

✨ Why ZEPIR?

• Zero mystery chips — No dedicated keyboard controller, no display bridge IC, no audio DAC chip. Everything is handled in software by the Pi itself.
• Completely transparent — Full schematic available, keyboard driver is a readable Python script, all source code is open.
• Software-scanned keyboard — 7×10 GPIO matrix, fully customizable Python driver. Change any key, any layout, any function.
• PWM audio — Sound output driven directly by Pi GPIO — no audio chip required.
• SPI display — ST7789 IPS panel connected via standard SPI — works with mainline Linux kernel overlays.
• Ideal base for handhelds & cyberdecks — Minimal, hackable, and yours to extend however you want.
• Optimized for Pi Zero 2 W — Quad-core ARM, enough RAM for real Linux tasks, Wi-Fi included.
• KISS philosophy — One board, one order, one device. No complexity theater.

📦 What You Receive

• Main PCB with soldered 40-pin female header for Raspberry Pi
• All buttons and 2.8" SPI display pre-soldered
• Front panel cover (PCB material — no extra manufacturing needed)
• Choice of Black or White front cover
• Available bare or fully assembled & tested

> Raspberry Pi is NOT included (optional add-on at checkout)

🔧 Hardware Features

Compatible boards: - ✅ Raspberry Pi Zero W - ✅ Raspberry Pi Zero 2 W — RECOMMENDED - ✅ Raspberry Pi 4 (without 18650 holder, needs GPIO extension) - ✅ Raspberry Pi 5 (without 18650 holder, needs GPIO extension) - Audio not supported

🛠️ Bill of Materials

The bare PCB version requires soldering the 40-pin header and a few passives. Component values are printed directly on the PCB.

💻 What Can You Do With It?

ZEPIR runs full Raspberry Pi OS — it's a real Linux computer, not a toy terminal.

• 🐚 Shell & scripting — Python, Bash, Nano, Midnight Commander, Git
• 🌐 Web browsing — w3m text browser with image support
• 🎵 Music playback — MP3 (mpg123), MOD tracker (mikmod)
• 🖼️ Image viewer — framebuffer image display with fbi/fim
• 📡 SSH & remote admin — manage servers and IoT devices from your pocket
• 🤖 Local AI (optional, Pi 5 required) — run Ollama + small LLMs offline
• 🎮 Retro & fun — cmatrix, cowsay, fortune, sl...

📋 Installation Guide

Step 1 — Flash SD Card

Flash Raspberry Pi OS Lite using Raspberry Pi Imager.

In the Imager advanced settings: - Enable SSH - Set username, password, and Wi-Fi credentials

Step 2 — Configure Display & Audio

Edit /boot/firmware/config.txt and add:

# SPI display
dtparam=spi=on
dtoverlay=fbtft,spi0-0,st7789v,dc_pin=25,rotate=270,width=240,height=320,speed=62000000

# Audio
dtparam=audio=on
dtoverlay=audremap,pins_18_19
audio_pwm_mode=2

Edit /boot/firmware/cmdline.txt — append to the existing single line:

fbcon=map:10 fbcon=font:VGA8x8

Step 3 — First Boot

Connect via SSH. Then run:

sudo raspi-config

Configure: Expand filesystem → Enable autologin → Boot to terminal (CLI) → Finish.

Configure console font:

sudo dpkg-reconfigure console-setup

Select: UTF-8 → Guess optimal → Terminus → 6×12

Step 4 — Test Hardware

Test display: ls /dev/fb* sudo dd if=/dev/urandom of=/dev/fb1

Random pixels should appear on screen.

Test audio:

aplay -l
alsamixer
espeak-ng "Hello from ZEPIR"

Step 5 — Install Packages

sudo apt update

Core tools

sudo apt install mc w3m w3m-img mpg123 espeak-ng fbi fim python3-evdev

Extra fun & utilities

sudo apt install mikmod ranger nnn btop ncdu cmus cmatrix sl cowsay fortune

In sudo raspi-config, set sound output to PCM audio.

Step 6 — Set Up GPIO Keyboard

Copy the keyboard driver to /home/pi/gpiokeyboard/gpiokeyboard.py (download from the Source Code link below).

Edit /etc/rc.local and add before exit 0:

sudo python3 /home/pi/gpiokeyboard/gpiokeyboard.py &

The keyboard driver is plain Python using evdev — read it, modify it, make it yours.

🤖 Optional: Local AI (Raspberry Pi 5 required)

> Pi Zero 2 W is great for Linux tasks. For running local LLMs, a Raspberry Pi 5 with at least 4 GB RAM is required.

Install Ollama curl -fsSL https://ollama.com/install.sh | sh Run a small model ollama run qwen3:1.7b

Recommended lightweight models:

Voice pipeline (experimental):

ollama run qwen3:1.7b "Say hello" --nowordwrap | espeak-ng

📎 Links

• 🔗 Source Code & Keyboard Driver (Dropbox)
• 🔗 Datasheet & Schematics
• 🔗 PCBWay Project Page
• 🔗 Hackaday Project