Raspberry Pi (HP) Print Server & Dashboard

This repository contains the configuration and software for transforming a Raspberry Pi into a headless print server and web-based scanning dashboard. The system provides a centralized interface for printing and scanning

Dashboard

The printer web dashboard enables:

• Initiating Scans
• Managing Scanned Documents
• Viewing Storage Usage
• Monitoring Ink/Toner Levels
• Restarting CUPS or the Pi

It can be accessed via either:

• http://<hostname>.local
• http://<pi-ip>.local

If you do not want to use the default port 80 - edit the last line of ./print-dashboard/app.py to your preferred port e.g. 5000

Technical Architecture

• Hardware Mutex: Uses threading.Lock() to prevent ink polling conflicts during scanning.
• Data Persistence: Dual-layer cache ensures hardware info remains visible during low-power states.
• Pre-Scan Routine: Automatically terminates background status processes (pkill) to clear the USB interface.

Hardware Requirements

• Raspberry Pi: Optimized for the Raspberry Pi Zero 2W, but compatible with Pi 4/5
• Printer: HP DeskJet 2300 Series (or any HP printer supported by HPLIP)
• Connectivity: The printer must be plugged directly into the Raspberry Pi via a USB OTG adapter or standard USB cable

Project Structure

📦Print-Server
 ┣ 📂images
 ┃ ┗ 📜screenshot.jpeg
 ┣ 📂print-dashboard
 ┃ ┣ 📂static
 ┃ ┃ ┣ 📂css
 ┃ ┃ ┃ ┗ 📜style.css
 ┃ ┃ ┣ 📂js
 ┃ ┃ ┃ ┗ 📜script.js
 ┃ ┃ ┗ 📂scans
 ┃ ┃ ┃ ┗ 📜.gitkeep
 ┃ ┣ 📂templates
 ┃ ┃ ┗ 📜index.html
 ┃ ┣ 📜app.py
 ┃ ┗ 📜utils.py
 ┣ 📜.gitignore
 ┣ 📜install.sh
 ┣ 📜LICENSE
 ┗ 📜README.md

Table of Contents

• Step 1: OS & Hardware Setup
  • 1. Identity & Root Access
  • 2. Software Installation & Permissions
  • 3. Check Printer via CUPS Management Page
  • 4. Hardware Discovery & HP URI Generation
  • 5. Add Printer via CUPS Management Page
• Step 2: Client Connection (Windows Setup)
  • Manually Add via URI (If Automatic Discovery/Adding Fails)
  • Select The Printer Driver
  • Driver Troubleshooting (The ".inf" Extraction Trick)
• Step 3: Dashboard Installation
  • 1. Automatic Install (Recommended)
  • 2. Manual Setup (Alternative)
  • 3. Verifying the Service
  • 4. Housekeeping

Step 1: OS & Hardware Setup

Networking Note: It is highly recommended to assign a static IP to your Pi via your router's DHCP reservation settings. In addition to using the hostname configured below (e.g., http://print-server.local)

1. Identity & Root Access

Note: Not required if you already configured the hostname during imaging

sudo raspi-config # Navigate to System Options -> Hostname

Enabling Root SSH Access:

Note: Not required if configured during imaging or using direct monitor access

1. Install micro (highly recommended over nano):
   sudo apt install micro
2. Set a password:
   sudo passwd root
3. Modify the SSH configuration:
   sudo micro /etc/ssh/sshd_config
4. Locate PermitRootLogin and change it to yes
5. Restart the SSH service:
   sudo systemctl restart ssh

2. Software Installation & Permissions

Note: Some of these packages are installed with the default Pi image and will be "set to manually installed" - included for completeness

sudo apt update && sudo apt upgrade -y
sudo apt install cups hplip sane-utils imagemagick python3-flask micro git -y

# Add user to administrative groups
sudo usermod -a -G lpadmin $USER
sudo usermod -a -G scanner $USER

# Allow remote management
sudo cupsctl --remote-any
sudo systemctl restart cups

3. Check Printer via CUPS Management Page

Access at: http://<hostname>.local:631 or http://<pi-ip>:631

1. Click Administration in the navbar (log in with your Pi user/password)
2. Click Manage Printers
3. You should see your printer there

If you do not see your printer continue to the next step below

4. Hardware Discovery & HP URI Generation

YOU DO NOT NEED TO DO THIS IF THE PRINTER WAS AUTOMATICALLY ADDED

CUPS should detect the USB printers automatically. If it does not, generating a specific HP URI (via the HPLIP drivers) is the most reliable way to do so

1. Identify the USB Bus: Run lsusb and look for your HP Printer.
   Example output:
   Bus 001 Device 002: ID 03f0:ef11 HP, Inc DeskJet 2300 series

2. Generate the URI: Use the Bus and Device numbers found above.

   sudo hp-makeuri 001:002 # Replace 001:002 with your specific IDs

3. Note the Output: Copy the string (e.g. hp:/usb/DeskJet_2300_series?serial=CN5815BKBQ) - you'll need it for the CUPS web interface

5. Add Printer via CUPS Management Page

Go back to the cups Administration page - as in 3. Check Printer via CUPS Management Page

1. Click Add Printer
2. Select Other Network Printers > AppSocket/HP JetDirect or paste your URI directly into the connection field
3. Ensure "Share This Printer" is checked
4. Note: You cannot change the name of the printer after creation, so choose something you will be happy with

Step 2: Client Connection (Windows Setup)

1. Open Printers & Scanners and click Add device
2. Find your printer and click Add Device

Manually Add via URI (If Automatic Discovery/Adding Fails)

1. Click "The printer that I want isn't listed"
2. Select "Select a shared printer by name"
3. Enter URI: http://<your-pi-ip>:631/printers/<printer_name_in_cups>
   Note: this is why we want the printer to have a static IP

Select The Printer Driver

1. Find your model under the manufacturer's tab
2. If not present, click Windows Update - this will take a while so be patient
3. Select the correct driver from the updated list

Driver Troubleshooting (The ".inf" Extraction Trick)

If the driver is missing even after a Windows Update:

1. Download the HP Driver Installer for your model
2. Press Win + R, type %temp%, and hit Enter
3. Optionally: Delete all the files you can to simplify the search (skip those you can't)
4. Run the HP Driver Installer - while the installer is open, return to the %temp% folder
5. Search for *.inf and locate the folder containing your driver (e.g., HPWia_DJ2300.inf) - open the file properties and look at the location in the window
6. In the Windows Add Printer wizard, click Have Disk... and browse to that the folder's location seen in the file properties

Step 3: Dashboard Installation

1. Automatic Install (Recommended)

git clone <your-repo-url>
cd Print-Server
chmod +x install.sh
sudo ./install.sh

2. Manual Setup (Alternative)

If you prefer to set it up manually, copy the files to /opt and create the service:

sudo mkdir -p /opt/print-dashboard
sudo cp -r ./print-dashboard/* /opt/print-dashboard/
sudo micro /etc/systemd/system/print-monitor.service

Paste and save the following:

[Unit]
Description=Print and Scan Dashboard
After=network.target

[Service]
ExecStart=/usr/bin/python3 /opt/print-dashboard/app.py
WorkingDirectory=/opt/print-dashboard
User=root
Restart=always

[Install]
WantedBy=multi-user.target

Finalize the service:

sudo systemctl daemon-reload
sudo systemctl enable print-monitor
sudo systemctl start print-monitor

3. Verifying the Service

# Check if the service is active
sudo systemctl status print-monitor

# Watch real-time logs for debugging
sudo journalctl -u print-monitor -f

4. Housekeeping

• Permissions:
  Ensure the scan directory is writable: sudo chmod -R 777 /opt/print-dashboard/static/scans
  (This is done in the install.sh script for you)
• Headless Operations:
  Hardware status warnings are redirected to /dev/null to keep logs clean