PrinterService Logo

Print from your Android phone or any device over Wi-Fi to your USB printer

CI

A lightweight, self-hosted network printing service built with Python and FastAPI. It turns any standard USB-connected printer (such as the Epson L3210) attached to a Windows PC into a wireless network printer accessible directly from your Android phone or any browser on your local Wi-Fi network—no manufacturer cloud services, vendor apps, or specialized mobile drivers required.

Most entry-level desktop inkjets (like the Epson L3210) connect only via USB and lack built-in Wi-Fi or network capabilities. Mobile printing from Android typically requires proprietary manufacturer cloud apps, AirPrint/IPP hardware support, or complex network setups.

Printer Service acts as a lightweight software bridge running on a host Windows PC (even low-spec / old PCs). It exposes a mobile-friendly web application and REST API on your local network. When you select a document or image on your phone, the service accepts the upload, standardizes it into a print-ready PDF via dedicated format processors, and silently submits it to the Windows print queue using SumatraPDF. Windows and the official Epson driver handle the low-level USB communication and physical printing.

┌─────────────────────────┐
│ Android Phone / Client │
│ (Browser / Web UI) │
└────────────┬────────────┘
 │ Wi-Fi (HTTP POST /port 8000)
 ▼
┌─────────────────────────────────────────────────────────────┐
│ Windows Host PC (Printer Service) │
│ │
│ 1. FastAPI Web Server & REST API (`/`, `/print`, `/jobs`) │
│ 2. Validation & Security (Magic bytes, Size, PIN Auth) │
│ 3. Format Processors (Normalize all inputs to PDF): │
│ • Images (Pillow) ────► PDF │
│ • Office (LibreOffice) ► PDF │
│ • TXT / CSV (ReportLab)► PDF │
│ • PDF ────────────────► Pass-through │
│ 4. Print Pipeline & Job Engine (SQLite state tracking) │
│ 5. SumatraPDF CLI (`-print-to` / `-print-settings`) │
└────────────┬────────────────────────────────────────────────┘
 │ Windows Spooler API
 ▼
┌─────────────────────────┐
│ Windows Print Queue │
│ Epson L3210 Driver │
└────────────┬────────────┘
 │ USB Cable
 ▼
┌─────────────────────────┐
│ Epson L3210 Printer │
│ (Paper Output) │
└─────────────────────────┘

• 📱 Zero-Install Mobile Printing: Open http://<server-ip>:8000 in Chrome/Firefox on your phone to upload and print instantly.
• 📄 Multi-Format Conversion: Seamlessly print PDFs, Photos/Images, Microsoft Office documents, OpenDocument files, and plain text/CSV tables.
• ⚙️ Configurable Print Options: Set number of copies (1–99), specific page ranges (e.g., 2-6, odd/even), paper sizes (A4, Letter, Legal, Long Bond, A3, A5), and Color vs. Monochrome modes.
• 🛡️ Pre-Flight Hardware Checks: Queries Windows spooler status flags (offline, out of paper, door open, jam) before dispatching jobs, preventing silent print failures.
• 🔄 Robust Job Lifecycle & Recovery: Durable job tracking backed by SQLite (logs/jobs.sqlite3), with one-click 🔁 Retry for failed jobs and support for cancellation.
• 🔒 Local Network Security: Restricted to private LAN profiles, optional PIN authentication (API_PIN), strict file magic-byte validation, and process-tree cleanup.
• 🧪 Comprehensive Testing: 190+ automated tests (~97% coverage) with faked OS/spooler boundaries running in CI, accompanied by standalone hardware diagnostic spikes (T1–T7).

Download and run the official MSI installer using PowerShell:

curl.exe -L -o "$env:TEMP\LibreOffice.msi" "https://download.documentfoundation.org/libreoffice/stable/26.8.0/win/x86_64/LibreOffice_26.8.0_Win_x86-64.msi"
msiexec /i "$env:TEMP\LibreOffice.msi"

A default "Typical" installation installs to C:\Program Files\LibreOffice\program\soffice.exe, which the service detects automatically (set LO_PATH in .env only if installed in a custom path).

• Zero installation needed: Any modern mobile browser (Chrome, Safari, Firefox).
• Network requirement: Must be connected to the same Wi-Fi network as the server PC (note: guest Wi-Fi networks usually isolate devices and prevent connection).

Clone or copy the repository to your host PC, open a terminal in the project root folder, and follow the instructions for your preferred shell:

# 1. Create an isolated virtual environment
python -m venv .venv
# 2. Activate the virtual environment
.venv\Scripts\activate
# 3. Install required Python packages
pip install -r requirements.txt
# 4. Create your local configuration file
copy .env.example .env

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 1. Create an isolated virtual environment
python -m venv .venv
# 2. Activate the virtual environment (use 'source' and forward slashes)
source .venv/Scripts/activate
# 3. Install required Python packages
pip install -r requirements.txt
# 4. Create your local configuration file
cp .env.example .env

From the project root folder:

.venv\Scripts\activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

Or via the direct one-liner (without manual activation):

.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000

source .venv/Scripts/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

Or via the direct one-liner (without manual activation):

.venv/Scripts/python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000

• Keep the terminal window open—the service runs as long as the process is active. Press Ctrl+C to stop it.
• --host 0.0.0.0 is mandatory because it instructs the server to listen on all local network interfaces so your phone can reach it.
• A successful startup output looks like: INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
• Self-Check: On the host PC, open http://localhost:8000/health in your browser to verify it returns {"status":"ok"}.

1. Find the PC's Local IP Address:
   • Open Command Prompt/PowerShell on the server PC and run ipconfig.
   • Note the IPv4 Address (e.g., 192.168.1.5).
   • (Recommended) Set a DHCP reservation in your home router settings so this IP address never changes.
2. Open the Web UI on your Phone:
   • Make sure your phone is connected to the same Wi-Fi.
   • Open your mobile browser and navigate to http://<server-ip>:8000 (e.g., http://192.168.1.5:8000).
3. Upload and Print:
   • Select a document or image (PDF, JPG/PNG/WebP, DOCX/XLSX/PPTX, or TXT/CSV).
   • Tap Print.
   • Watch the live progress status: 📨 Queued... → ⏳ status: converting... → 🖨️ status: printing... → ✅ Printed to EPSON L3210 Series!
4. Formatting Behaviors:
   • Images: Automatically fitted and centered on an A4 page with white margins; camera EXIF orientation is respected.
   • Office Files: Converted via LibreOffice headless (typically 10–30s); UI indicates converting state during processing.
   • TXT & CSV: TXT prints formatted monospace text with automatic line-wrapping; CSV renders a structured, bordered grid table.
5. Job Retries & Cancellation:
   • If a job fails (e.g., printer out of paper), the uploaded source file is preserved. Tap the 🔁 Retry button on the web page or call POST /jobs/{id}/retry.
   • Active jobs can be cancelled while queued, converting, or printing (best-effort once handed to the Windows spooler).
6. Print Options Dialog (Expandable on the web page):
   • Copies: 1 to 99 copies.
   • Page Range: Custom ranges (2-6, 1,3,5), odd, or even.
   • Paper Size: A4, Short Bond (Letter), Long Bond (×ばつ13 / Folio), Legal, A3, A5.
   • Color Mode: Full Color or Monochrome (Black & White).
   • Options apply across all document formats and are retained when retrying a job.

The service provides a full REST API, also browsable interactively via Swagger UI at http://<server-ip>:8000/docs:

Copy .env.example to .env to configure optional server settings. All keys are optional—the default configuration is ready for immediate use:

If printing ever fails or you want to verify your setup before launching the service, use the standalone diagnostic spike scripts:

Run from the project root (requires pywin32):

python spike_print_test.py

This diagnostic systematically checks each layer:

• T1: Verifies printer visibility through win32print.
• T2: Tests RAW text submission to the Windows spooler.
• T3: Checks the Windows "print" shell verb.
• T4: Tests silent PDF printing through SumatraPDF to the physical printer.
• Result: T4 PASS with a printed test page confirms the entire Python → SumatraPDF → Spooler → USB chain is functional.

• spike_t5_images.py: Tests ImageProcessor conversion (JPEG, PNG with transparency, WebP, EXIF orientation) and prints to paper.
• spike_t6_office.py: Tests OfficeProcessor (DOCX tables, landscape XLSX with print areas, 16:9 PPTX) using LibreOffice.
• spike_t7_text.py: Tests TextProcessor rendering of wrapped text and CSV tables.

Follow these steps when setting up the service permanently on your print-server machine:

1. Install Prerequisites: Install Python 3.12+, SumatraPDF, printer drivers, and optionally LibreOffice (§1).
2. Obtain the Code: Clone the repository with git clone or copy the project folder (ensure you delete any existing .venv folder before copying).
3. Set Up Virtual Environment:

   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements.txt
   copy .env.example .env

4. Configure Firewall: Run allow_firewall_8000.bat as Administrator to open TCP port 8000.
5. Run Diagnostics: Run python spike_print_test.py to confirm physical paper prints successfully.
6. Start the Server: Launch the service using the instructions in §3 and verify connectivity from your phone.
7. Reserve Static IP: In your home router configuration, create a DHCP reservation for the PC's MAC address to keep its IP permanent.
8. Configure Auto-Start on Boot (Optional via Windows Task Scheduler):
   • Open Task Scheduler → Create Task.
   • General: Name the task (e.g., PrinterService), check Run whether user is logged on or not.
   • Triggers: Set trigger to At startup.
   • Actions: Set action to Start a program:
     • Program/script: C:\path\to\printerService\.venv\Scripts\python.exe
     • Add arguments: -m uvicorn app.main:app --host 0.0.0.0 --port 8000
     • Start in: C:\path\to\printerService\

Verify code quality and ensure test coverage before committing changes (mirrors CI workflow):

.venv\Scripts\activate
pip install -r requirements-dev.txt # Install testing dependencies (once)
ruff check . # Linting: unused imports, style rules, bugs
pytest # Executes full test suite with coverage report (≥90% gate)

source .venv/Scripts/activate
pip install -r requirements-dev.txt # Install testing dependencies (once)
ruff check . # Linting: unused imports, style rules, bugs
pytest # Executes full test suite with coverage report (≥90% gate)

• Unit Tests (tests/unit/): Verify file validation, magic-byte detection, format processors, and pipeline state transitions with all OS interactions (subprocess, file system, win32print) completely faked.
• API Tests (tests/api/): Simulate real client and phone requests against FastAPI endpoints using httpx and TestClient without network overhead.
• Hardware Isolation: Automated tests never touch the real printer or filesystem state, enabling the exact same test suite to run identically on Windows development machines and Ubuntu CI runners.
• CI Automation: GitHub Actions runs ruff check and pytest with a 90% coverage threshold on every push and pull request (.github/workflows/ci.yml).

For deep dives into architectural decisions, roadmap phases, and design rationales, refer to the project documentation:

• docs/SOURCE_OF_TRUTH.md : The authoritative architecture document, technology stack rationale, network security rules, and detailed failure diagnostic guides.
• docs/MULTI_FORMAT_PLAN.md : Multi-format design record, decision logs (Pillow, LibreOffice, ReportLab), and the T5–T7 spike protocols.
• tests/conftest.py : Reference for test fixture implementations and Windows printing mocks.