paper-console
A small, self-hosted thermal printer for news, weather, puzzles, email, and more.
What is it?
What it is
A compact, self‑hosted thermal printer (PC‑1) that prints news, weather, puzzles, email, and more to physical paper, controlled by a rotary dial and button on a Raspberry Pi Zero 2 W.
Why it exists
To give users a tangible, subscription‑free way to receive curated information and entertainment without a screen, using only local hardware and open‑source software.
Who should use it
DIY makers, Raspberry Pi enthusiasts, hobbyists who enjoy building physical devices and want a low‑cost, screen‑less daily information printer
Who should avoid it
Users who need high‑volume printing, non‑technical users without basic Linux/command‑line skills, or those who prefer cloud‑based services
How it works
A quick walkthrough in plain English
How paper-console works
Step 1 of 3
You interact with it
Open paper-console, send a request, or connect it to your stack.
Features
Advantages
- Privacy‑first design (no cloud or API keys required)
- Low cost and low power (Pi Zero 2 W)
- Physical output eliminates screen fatigue
- Extensible module architecture allows adding new content types
- Easy local deployment and configuration
- Supports offline operation once data is cached
- Open source community contributions possible
- Built‑in Wi‑Fi setup and OTA update support
- Hardware‑centric design encourages learning electronics
- No subscription fees or recurring costs
Disadvantages
- Requires Raspberry Pi hardware and assembly skills
- Thermal paper is consumable and limited to 58 mm width
- Limited to Pi Zero 2 W (no native support for larger Pi models)
- No built‑in display or touch interface for complex interactions
- Printer reliability depends on power supply and serial connection
- Setup can be challenging for non‑technical users
- Limited to text/bitmap output (no high‑resolution graphics)
- Requires Wi‑Fi network for initial configuration and updates
- Hardware maintenance (printer, button, dial) may be needed over time
Installation
docker
1. Create a Dockerfile in the repo root: ```Dockerfile FROM python:3.12-bookworm WORKDIR /paper-console COPY . . RUN apt update && apt install -y sudo npm nodejs network-manager RUN pip install Pillow RUN pip install fastapi uvicorn[standard] pydantic requests RUN pip install feedparser icalendar pytz python-dateutil astral beautifulsoup4 RUN pip install pytest RUN python3 -m venv .venv; ./.venv/bin/python -m pip install -r requirements-dev.txt ENTRYPOINT ["./run.sh"] ``` 2. Build the image: ```bash docker buildx build -t local/pc-1 . ``` 3. Run the container: ```bash docker run --rm -it -p 8000:8000 local/pc-1 ``` 4. Access the app at `http://localhost:8000`. 5. Use the mock printer output in the terminal.
native
1. Install Python dependencies on the Pi: ```bash ./.venv/bin/python -m pip install -r requirements-pi.txt ``` 2. Run the setup script to configure hardware and services: ```bash cd ~/paper-console chmod +x scripts/setup_pi.sh sudo scripts/setup_pi.sh ``` The script sets the hostname, installs Nginx and Avahi, configures a systemd service, and adds the user to the `lp` group. 3. Start the application (handled by the systemd service `pc-1.service`). 4. Access the device via web UI at `http://pc-1.local` (or the chosen hostname).
FAQ
How do I set up PC‑1 on a Raspberry Pi Zero 2 W?
First connect the hardware following the wiring tables in the README: power the Pi and printer from a 5 V 5 A supply, wire the 58 mm thermal printer to the GPIO serial pins (TX, RX, DTR, GND), connect the 8‑position rotary switch to the designated GPIO pins, and attach the momentary push button. After wiring, run the setup script: ```bash cd ~/paper-console chmod +x scripts/setup_pi.sh sudo scripts/setup_pi.sh ``` The script configures the hostname, installs Nginx and Avahi for mDNS, sets up the systemd service, and adds the user to the `lp` group for printer access. Once the Pi reboots, you can access the device at `http://pc‑1.local` or `http://10.42.0.1` during setup.
Can I run PC‑1 without a Raspberry Pi, for example in Docker or on my laptop?
Yes. The repository includes a Dockerfile that builds a container with the same Python dependencies and a mock printer that outputs to the terminal. Build and run the image with: ```bash docker buildx build -t local/pc-1 . docker run --rm -it -p 8000:8000 local/pc-1 ``` The API is available at `http://localhost:8000` and the mock printer prints to the container’s console. For local development on a Unix‑like shell, simply run `./run.sh` or `uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload` after installing the dev requirements. Both methods allow you to test logic, view printed output, and run the web UI at `http://localhost:5173` after `npm run dev` in the `web` directory.
How do I configure channels, modules, and schedules using the web UI?
Open the settings UI at `http://pc‑1.local` (or `http://localhost:8000` if running locally). Under **Global Settings** you can set location, time format, and other system options. Channels are displayed as cards; each card represents a rotary dial position (1‑8). Use the up/down arrows next to a channel title to reorder entire channels. Inside a channel card, you can add modules (e.g., News, Weather, Sudoku) and reorder them with the arrow buttons. To schedule automatic printing, click the clock icon on a channel and set the desired times. All changes are auto‑saved to `config.json`. The UI also provides a **Reset All Settings** button that restores factory defaults.
What is the procedure for a factory reset or Wi‑Fi reset?
Press and hold the button for about 15 seconds to trigger a factory reset. This clears all settings, restores the default configuration, and reboots the device. For a Wi‑Fi reset, hold the button for ~5 seconds to bring up the Quick Actions menu, then press the option labeled "Reset WiFi" (usually option 4). The device will return to setup mode and print a new setup receipt with a fresh SSID and password.
What are the Quick Actions and how do I use them?
When you hold the button for ~5 seconds, a half‑line paper cue appears and the Quick Actions menu is printed. The options are: 1. Table of Contents 2. System Monitor 3. Reprint Setup Instructions 4. Reset WiFi 5. Reset Factory Settings 8. Cancel Select an option by pressing the corresponding number on the rotary dial. The menu exits automatically after a choice or after 2 minutes of inactivity. Holding the button for ~15 seconds bypasses the menu and performs a factory reset.
Featured in Videos
YouTube tutorials and walkthroughs for paper-console
s5
896,635 views
Starts at 00:00
Alternatives
Similar projects ranked by category, topics, and text overlap.
