Noureddine RAMDI / paper-console: modular thermal printer IoT with dual-mode Raspberry Pi integration

Created Mon, 04 May 2026 10:23:01 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1012 Words
github-stars python iot raspberry-pi fastapi thermal-printer gpio

travmiller/paper-console

paper-console tackles a specific niche in IoT: delivering curated content like news, weather, puzzles, and emails printed on thermal paper through a Raspberry Pi Zero 2 W. This project cleverly abstracts hardware control so the same codebase runs both on actual hardware and in a mock terminal mode for development. The neat part is how it handles modular content channels controlled through hardware inputs, while offering a web UI for configuration.

What paper-console does and its architecture

At its core, paper-console (PC-1) is a self-hosted IoT device that prints short bursts of curated content onto 58mm thermal paper rolls. It uses a Raspberry Pi Zero 2 W as the main controller running a FastAPI backend with uvicorn. This backend serves a frontend UI built with a combination of Vue and Svelte, accessible locally via mDNS at http://pc-1.local, where users can configure content channels and settings.

The content sources are modular and channel-based, allowing users to select what kind of content prints via a 1-pole 8-position rotary switch. The hardware also includes a momentary push button for triggering prints or quick actions. A TTL thermal printer (compatible with QR204/CSN-A2 style printers) physically prints the output.

Under the hood, the software manages two distinct modes: a mock mode that prints to a terminal emulator for development environments without hardware, and a hardware mode that interfaces with Raspberry Pi GPIO pins to read the rotary switch and button inputs and control the printer. This dual-mode design is supported by separate requirements files (requirements-dev.txt vs requirements-pi.txt), which helps keep development dependencies lightweight and avoids installing hardware-specific libraries on non-Pi machines.

Configuration data is stored in a config.json file that is gitignored to avoid accidental commits, with support for factory resets. The system supports OTA (over-the-air) updates and uses mDNS for local network discovery, which simplifies access without needing to know the Pi’s IP address.

What sets paper-console apart technically

The standout technical design is the abstraction of the printing and input logic to work seamlessly in two environments: a developer machine terminal and the actual Raspberry Pi hardware. This is a solid example of designing for DX (developer experience) while respecting hardware constraints.

By separating dependencies into dev vs Pi-specific, the codebase avoids the common pitfall where GPIO libraries force hardware installs, complicating local development. This means you can build and test channels, frontend UI, and backend logic on your laptop without needing a Raspberry Pi or thermal printer.

The modular channel architecture is also well thought out. Each content channel (news, weather, puzzles, email) can be configured and managed through the web UI, and the rotary switch hardware lets users physically select which channel to print. This hardware-software integration is not trivial — reading GPIO inputs reliably and mapping those to channel switching requires careful debounce handling and state management, which the repo addresses.

The use of FastAPI with uvicorn ensures a performant, async-capable backend that can handle the web UI and print commands efficiently. The frontend’s mix of Vue and Svelte is an interesting choice, likely balancing the strengths of both frameworks for reactive UI and lightweight components.

The tradeoff is that full functionality requires the specific hardware setup: Raspberry Pi Zero 2 W, compatible thermal printer, rotary switch, and button. Without these, you only get the mock terminal mode, which is useful but obviously less exciting.

Installation prerequisites for paper-console

To get paper-console running on real hardware, you’ll need the following:

  1. Raspberry Pi Zero 2 W running Raspberry Pi OS Lite
  2. A 58mm TTL thermal printer compatible with QR204/CSN-A2 (max paper roll diameter 30mm)
  3. A 1-pole 8-position rotary switch to select content channels
  4. A momentary push button for print triggers or quick actions
  5. A 5V 5A power supply connected via barrel jack and terminal adapter

This hardware list is specific and requires some experience soldering and wiring GPIO pins on the Pi. Software setup involves installing the dependencies from requirements-pi.txt on the Pi, while developers working on their laptops would use requirements-dev.txt.

verdict: who should consider paper-console

paper-console is a neat project for hobbyists and makers interested in IoT devices that combine hardware with software in a modular way. Its dual-mode design is a good example of balancing developer experience with hardware integration, making it approachable to test and extend without immediate access to the physical device.

That said, it’s aimed at users comfortable with Raspberry Pi hardware, thermal printers, and some electronics assembly. The reliance on specific hardware peripherals means it’s not a plug-and-play solution but rather a build-it-yourself platform.

The modular channel architecture and web UI for settings make it flexible and extensible, but the project’s scope is intentionally narrow: printing curated content on thermal paper. If you want a compact, self-hosted IoT print device that’s configurable and designed with clean separation of hardware/software concerns, paper-console is worth a look.

Limitations include the hardware dependencies, the need for manual wiring and setup, and the relatively simple print content format. The codebase is surprisingly clean for a hobbyist project, and its OTA update support shows some attention to long-term maintenance. Overall, paper-console fills a nice niche and shows how to build IoT devices with good DX and modular design.

→ GitHub Repo: travmiller/paper-console ⭐ 277 · Python