A headless scanning service for HP Officejet 3831 that runs in Docker. This service provides a REST API for network-based scanning using SANE's airscan backend.

Features

REST API for remote scanning
Multiple output formats (PNG, JPEG, PDF)
Configurable resolution and scan modes
Auto-generated timestamped filenames
Docker-based deployment with multi-stage build
Automatic scanner discovery via eSCL protocol

Quick Start

Configure Scanner IP: Update the scanner IP address in docker-compose.yml:

args:
  SCANNER_IP: 192.168.0.249  # Change to your scanner's IP

Build and run:

docker-compose up --build

Test the service:

curl http://localhost:6001/health

API Endpoints

GET /

Returns service information and available endpoints.

GET /health

Check if the scanner is available.

Response:

{
  "status": "healthy",
  "scanner_available": true
}

GET /devices

List all available scanning devices.

POST /scan

Scan a document with optional parameters.

Example:

curl -X POST http://localhost:6001/scan \
  -H "Content-Type: application/json" \
  -d '{"resolution": 300, "mode": "Color", "format": "png"}' \
  --output scan.png

Parameters:

resolution: 75, 150, 300, 600 DPI (default: 300)
mode: "Color", "Gray", "Lineart" (default: "Color")
format: "png", "jpg", "pdf" (default: "png")

Response: Binary file with auto-generated filename scan_YYYYMMDD_HHMMSS.{ext}

Configuration

Scanner IP Address

The scanner IP must be configured in two places:

docker-compose.yml - Build argument
scanner_api.py:18 - HPScannerService.IP_ADDRESS

Port Configuration

Default port: 6001
Configure in scanner_api.py:15 and docker-compose.yml

Volume Mapping

Scanned files are saved to ./scans which maps to /mnt/general/paperless/consume inside the container. Adjust this in docker-compose.yml as needed.

Architecture

Backend: Flask REST API
Scanning: Python-SANE with sane-airscan backend
Image Processing: Pillow (PIL)
Container: Multi-stage Docker build for optimized image size
Network: Host mode for direct scanner access

Requirements

Scanner Requirements

Ensure your HP Officejet 3831 is:

Connected to the same network as the Docker host
Has a static IP address (or DHCP reservation)
Supports eSCL protocol (AirPrint/eSCL scanning)
Is powered on and accessible

System Requirements

Docker and Docker Compose
Network access to the scanner
USB device access (for USB scanning mode)

Troubleshooting

Scanner Not Found

Verify scanner is powered on and connected to network
Check scanner IP: ping <scanner_ip>
Test eSCL endpoint: curl http://<scanner_ip>/eSCL/ScannerCapabilities
Check container logs: docker-compose logs -f
Test SANE detection: docker exec <container> scanimage -L

Connection Issues

Ensure host network mode is enabled in docker-compose.yml
Verify firewall rules allow access to scanner
Check scanner's network discovery settings
Restart the scanner and container

Scan Quality Issues

Adjust resolution parameter (higher = better quality, slower scan)
Try different mode settings based on document type
For documents: Use "Gray" or "Lineart" modes
For photos: Use "Color" mode with 300+ DPI