Pocket Pi

What this project actually is

This is not a big software repo with a custom app at the center of it. Pocket Pi is really a hardware setup guide. Most of the value is in the setup order, the exact boot configuration, and the way I connect a few solid existing tools into one small handheld build.

The repo is intentionally small. The two most important parts are the README and the bootfs folder. That folder is what makes the first boot much smoother, because it gives me a ready-to-copy config.txt, a cmdline.txt with USB gadget networking enabled, and an empty ssh file so I can connect to the Pi right away without needing a separate display first.

• bootfs/config.txt sets the display-related boot options and GPIO pull-ups I need for the LCD HAT and controls.
• bootfs/cmdline.txt adds modules-load=dwc2,g_ether, which lets the Pi expose Ethernet over USB.
• bootfs/ssh enables SSH on first boot.

Why I made it this way

I like small projects that still feel like full computers. The Pi Zero 2 W is a great fit for that. It is tiny, inexpensive, and still capable enough to run full Raspberry Pi OS. The hard part is not the board itself. The hard part is getting the display, input, power, and first-boot workflow to play nicely together.

That is what Pocket Pi is for. I wanted one place that shows the whole path from empty microSD card to a usable handheld Pi. No guesswork, no bouncing between forum threads, and no mystery settings hidden inside screenshots.

I also kept the process transparent. Instead of hiding everything behind a giant setup script, I spelled out the actual steps. That makes the build easier to understand and easier to change later.

How the system works

The flow is pretty straightforward. I start by flashing Raspberry Pi Imager with Raspberry Pi OS Legacy (Bullseye, 32-bit), with SSH enabled and the hostname, username, password, and Wi-Fi set during imaging. After that, I copy the repository's bootfs files onto the SD card's boot partition.

From there, the first boot is already pointed in the right direction. The Pi comes up with SSH enabled, USB gadget networking available, and the display boot settings in place. That lets me plug the Pi Zero 2 W into my computer with a USB cable and connect over:

ssh code@pocketpi.local

Once I am in, I increase swap to 2GiB. On a 512MB Pi Zero 2 W, that makes package upgrades and compilation much less painful. After that I update the system, enable the right interfaces, and bring each hardware piece online one at a time.

What drives the display, controls, and power

The display side is built around the Waveshare 1.3-inch LCD HAT. I enable SPI, make sure the user has access to the SPI and GPIO groups, and then build fbcp-ili9341 with the Waveshare ST7789 configuration enabled. That project is what makes the tiny SPI screen usable as a live mirror of the main Raspberry Pi framebuffer.

git clone https://github.com/juj/fbcp-ili9341.git
cd fbcp-ili9341
mkdir build
cd build
cmake -DSPI_BUS_CLOCK_DIVISOR=6 -DWAVESHARE_ST7789VW_HAT=ON -DBACKLIGHT_CONTROL=ON ..
make -j

After the build finishes, I add the binary to /etc/rc.local so it starts automatically at boot. That means the screen comes alive on its own instead of needing to be started manually every time.

For the joystick and buttons, I use the software package referenced in the LCD HAT setup and run the included mouse.py script. In practice, that turns the physical controls into mouse movement and clicks, which is a simple but effective way to navigate the small Raspberry Pi OS interface without adding a keyboard or touchscreen.

For portable power, I use the Waveshare UPS HAT. I enable I2C, install the vendor package, and run INA219.py to read power data. That gives me a quick way to check whether the batteries are charging or actively feeding the Pi.

What the repository is really wiring together

Pocket Pi is mostly glue, but that is exactly why I like it. The build works because each layer has a clear job:

• The Raspberry Pi Imager handles OS installation and first-boot account setup.
• The repo's bootfs files handle early boot configuration and headless access.
• fbcp-ili9341 handles framebuffer mirroring to the SPI LCD.
• The Waveshare input script handles joystick and button events as mouse input.
• The UPS HAT tools handle battery and current monitoring over I2C.

There is no hidden magic here. It is just a clean chain of boot settings, Linux interfaces, and a few well-chosen external tools.

How I build it from scratch

1. Flash Raspberry Pi OS Legacy (Bullseye, 32-bit) with Raspberry Pi Imager, and enable SSH during setup.
2. Copy everything from the repo's bootfs folder to the SD card boot partition.
3. Insert the card into the Pi Zero 2 W and connect the board to a computer over USB.
4. SSH into the Pi over hostname.local.
5. Increase swap, then run sudo apt-get update && sudo apt-get full-upgrade -y.
6. Enable SPI and build the LCD driver stack.
7. Install and autostart the joystick and button script.
8. Enable I2C and install the UPS HAT monitoring tools.

That is the whole project in a nutshell. It is not a one-command install, but it is a very understandable build. If something breaks, I know exactly which layer to inspect.

What it looks like in practice

Once everything is up, Pocket Pi behaves like a very small Linux handheld. The LCD mirrors the Raspberry Pi desktop, the joystick and buttons act as input, and the UPS board keeps the build portable. It is still a Pi Zero 2 W, so I keep expectations realistic, but that is part of the fun. The whole point is getting a complete Raspberry Pi OS environment into a tiny footprint.

I like that the finished result feels more like a tiny computer than a parts pile. It boots into something immediately usable, and every piece of the setup is visible and tweakable.

How I would extend it

Because the repo stays close to the metal, it is easy to customize. I can change boot display settings in config.txt, swap the startup approach from rc.local to a proper service, replace the input script, or layer my own software on top once the hardware stack is stable.

I also see room around the physical build. The parts list already hints at a 3D-printed case, and that is exactly the kind of next step that makes sense here. Once the software path is repeatable, the enclosure becomes the fun part.

Closing thoughts

Pocket Pi is not the most practical thing I have built, and that is part of why I enjoyed it. I like projects like this because they take familiar hardware and force me to think through every layer, from power and input to display output and boot setup.

This project gave me a compact Raspberry Pi build that feels complete. It boots into a full desktop OS, runs on battery power, and has just enough controls to make the whole thing usable. That was really the goal from the start.

If you want to build your own, start with the repository, then check the display docs for the 1.3-inch LCD HAT and the battery docs for the UPS HAT. I released it under Apache-2.0, so you can use it as a base, change it, and take it in your own direction.