\n\n**`node-hp-scan-to`** is a Node.js application that replicates HP's \"_Scan to Computer_\" functionality by [reverse engineering HP's proprietary protocols](protocol_doc/HP%20Officejet%206500%20E710n-z.md) and supporting the standardized [eSCL protocol](protocol_doc/HP%20PageWide%20Pro%20477dw%20MFP.md), allowing you to scan documents directly from your HP printer's scanner to your Linux, Windows, or macOS computer.\n\nUnlike the original HP program, `node-hp-scan-to` is cross-platform and can be run on a bare-metal desktop or server, or in a container on Docker or Kubernetes. It can also be integrated with third-party document management solutions such as [Paperless-ngx](https://docs.paperless-ngx.com/) and [Nextcloud](https://Nextcloud.com/).\n\n**Disclaimer:** _This project is neither endorsed by nor affiliated with Hewlett-Packard (HP). Any mention or reference to HP is purely descriptive and non-commercial. All reverse engineering of HP's official Windows application and its interaction with devices has been performed independently without cooperation from HP. **This software is provided as-is for educational and personal use only**._\n\n\n\n- [Features](#features)\n - [Supported Devices](#supported-devices)\n - [Supported Functions](#supported-functions)\n - [App Features](#app-features)\n - [Protocol Support](#protocol-support)\n - [Emulated Duplex Scanning Feature](#emulated-duplex-scanning-feature)\n- [Installation](#installation)\n - [Using NodeJS](#using-nodejs)\n - [Using Docker](#using-docker)\n- [Usage](#usage)\n - [Command Line (CLI)](#command-line-cli)\n - [CLI Options](#cli-options)\n - [CLI Commands](#cli-commands)\n - [Run with Docker](#run-with-docker)\n - [Public Pre-Built Docker image](#public-pre-built-docker-image)\n - [Docker Environment Variables](#docker-environment-variables)\n - [Example for Docker](#example-for-docker)\n - [Example for Docker Compose](#example-for-docker-compose)\n - [Run with Kubernetes](#run-with-kubernetes)\n - [Configure](#Configure)\n- [Build Source Code](#build-source-code)\n - [Debugging](#debugging)\n- [π Support this project](#-support-this-project)\n- [π Special Thanks](#-special-thanks)\n- [License](#license)\n\n\n\n## Features\n\n### Supported Devices\n\nThis app has been developed and tested with the following HP All-in-One Printers:\n\n- HP DeskJet 3520\n- HP OfficeJet 6500A Plus\n- HP Smart Tank Plus 570 series\n- HP OfficeJet Pro 9019e\n\nUsers have reported it also working on additional devices. See\n[SUPPORTED_DEVICES.md](SUPPORTED_DEVICES.md) for the full community-reported list\nand the process for adding a new printer report.\n\nThere is a good chance it also works on other unlisted HP All-in-One Printer.\n\n### Supported Functions\n\n- βοΈ JPG and PDF document scan output\n- βοΈ Automatic document feeder (ADF) support with dual-side scanning\n- βοΈ Multi-page platen scanning\n- βοΈ Automatic IP address discovery\n\n### App Features\n\n- βοΈ Multi-platform: Linux, Windows, and macOS\n- βοΈ Prebuilt Docker images (multi-architecture)\n- βοΈ Command line (CLI) support\n- βοΈ Customizable file names, resolutions, and device labels\n- βοΈ Clear all registered targets\n- βοΈ Emulated double side scan\n- βοΈ Multiple output target support:\n - Local folders\n - [Paperless-ngx API](https://docs.paperless-ngx.com/api/) upload\n - [Nextcloud WebDAV](https://docs.Nextcloud.com/server/latest/user_manual/en/files/access_webdav.html) upload\n\n### Protocol Support\n\nSupports both HP proprietary protocols (WalkupScanToComp, WalkupScan, ScanJob) and the standardized eSCL protocol.\n\n- **eSCL-only devices** (e.g., HP ScanJet Pro 4500 fn1): Automatically detected and supported ([#1307](https://github.com/manuc66/node-hp-scan-to/issues/1307))\n- **Dual-protocol devices**: Uses HP protocols by default; add `--prefer-eSCL` flag to use eSCL instead\n- See [eSCL protocol documentation](protocol_doc/HP%20PageWide%20Pro%20477dw%20MFP.md) for technical details\n\n### Emulated Duplex Scanning Feature\n\nThe emulated duplex scanning feature allows users to efficiently scan both sides of a document, even on devices that do\nnot natively support duplex scanning. However, please note that this feature is only available in listen mode and is not supported with ADF-autoscan.\n\nWhen enabled (as an opt-in feature), it adds an extra entry in the list of scan destinations, labeled with the \"duplex\"\nsuffix. When you select this option for the first time, the device scans the front side of the document.\n\nAfter the front side is scanned, if you choose the duplex option again, the device will trigger a second scan and\nproduce an assembled output.\n\nIf you decide not to scan the back side immediately, the front side scan will be saved in the system and will remain\nthere until you either scan the back side or perform a single side scan instead.\n\n## Installation\n\n### Using NodeJS\n\n- You must have [NodeJS installed](https://nodejs.org/en/download)\n\n- In a Terminal, run: `npm install node-hp-scan-to`\n\n### Using standalone binaries (Windows, macOS, Linux)\n\nEach [release](https://github.com/manuc66/node-hp-scan-to/releases/latest) ships self-contained executables (no NodeJS required):\n\n| File | Platform |\n| --------------------------------------- | ------------------------------------------------------------------ |\n| `setup-node-hp-scan-to-v*.exe` | Windows 10/11 x64 installer (per-user autostart or system service) |\n| `node-hp-scan-to-v*-windows-x64.zip` | Windows 10/11 x64 portable |\n| `node-hp-scan-to-v*-darwin-arm64.zip` | Apple Silicon |\n| `node-hp-scan-to-v*-darwin-x64.zip` | Intel Mac |\n| `node-hp-scan-to-v*-linux-x64.tar.gz` | Linux x64 |\n| `node-hp-scan-to-v*-linux-arm64.tar.gz` | Linux ARM64 |\n\nExtract the archive anywhere and run `node-hp-scan-to` from its folder. It automatically reads the `config/default.json` shipped next to the binary; edit it to your needs.\n\nThe Windows installer offers two modes:\n\n- _For me_ (default, no admin rights): installs to `%LOCALAPPDATA%\\Programs\\node-hp-scan-to`, saves scans to the `hp-scan` folder inside your Documents (follows OneDrive redirection) and starts hidden at login via a scheduled task, with a persistent log in `%APPDATA%\\node-hp-scan-to\\logs\\scan.log`\n- _Windows service for all users_: installs to `Program Files`, runs as a service via [WinSW](https://github.com/winsw/winsw) and saves scans to `C:\\ProgramData\\node-hp-scan-to\\scans`\n\nBoth modes also let you pick the startup behaviour: waiting for scan jobs triggered from the printer panel, or scanning automatically each time paper is loaded into the document feeder (`adf-autoscan`).\n\nNotes:\n\n- **Windows**: SmartScreen may warn about an unsigned executable β click _More info_ β _Run anyway_\n- **macOS**: the binary is unsigned, so Gatekeeper may block it on first run. Either right-click β _Open_, or clear the quarantine flag with `xattr -cr node-hp-scan-to`\n\n### Using Debian / RPM packages\n\n`.deb` and `.rpm` packages (`amd64`/`arm64`) are attached to each [release](https://github.com/manuc66/node-hp-scan-to/releases/latest). They install `/usr/bin/node-hp-scan-to`, a `node-hp-scan-to.service` systemd unit (enabled with `systemctl enable --now node-hp-scan-to`) and an example configuration in `/etc/node-hp-scan-to/default.json`:\n\n```bash\nsudo apt install ./node-hp-scan-to_*_amd64.deb\n# or\nsudo rpm -i node-hp-scan-to-*.x86_64.rpm\n```\n\nScans are saved under `/var/lib/node-hp-scan-to` by default when running as a service.\n\nLinux networking notes:\n\n- the service only makes **outbound** connections: mDNS discovery (UDP 5353 multicast), plain HTTP calls to the printer itself on port 80 (discovery tree, scan job creation and polling), and HTTPS uploads to Paperless-ngx/Nextcloud when configured β nothing listens for the scanning flow itself\n- `--health-check` listens on **all interfaces** (port 3000 by default); restrict it with a local firewall rule if that matters to you, or drop the flag from `/usr/lib/systemd/system/node-hp-scan-to.service`\n- the packaged systemd unit runs under a dynamic non-root user with `PrivateTmp`, read-only system paths and an empty capability set\n\n#### Alpine Linux\n\n`.apk` packages (`x86_64`/`aarch64`) are attached to each [release](https://github.com/manuc66/node-hp-scan-to/releases/latest). They ship a **musl** build, install the binary, an OpenRC service and `/etc/node-hp-scan-to/default.json`, and create a `node-scan` system user (scans land in `/var/lib/node-hp-scan-to`):\n\n```sh\napk add ./node-hp-scan-to_*_x86_64.apk\nrc-update add node-hp-scan-to default\nrc-service node-hp-scan-to start\n```\n\n#### Saving scans in your own user folder\n\nThe system service is sandboxed on purpose, so point it at your home folder this way:\n\n1. set `\"directory\"` in `/etc/node-hp-scan-to/default.json` to your folder\n2. allow writes through the sandbox and to the dynamic user:\n\n```bash\nsudo systemctl edit node-hp-scan-to\n# add:\n# [Service]\n# ReadWritePaths=/home/YOU/Documents/scans\n# SupplementaryGroups=users\n# then: sudo chmod g+w /home/YOU/Documents/scans\n```\n\nSimpler alternative β run the app **as yourself** with the shipped per-user unit:\n\n```bash\nmkdir -p ~/.config/node-hp-scan-to\ncp /etc/node-hp-scan-to/default.json ~/.config/node-hp-scan-to/\nsystemctl --user enable --now node-hp-scan-to\n# optional: also start at boot without being logged in\nsudo loginctl enable-linger \"$USER\"\n```\n\n#### Verifying release artifacts\n\nEvery release artifact ships with a Sigstore build provenance attestation bound to the exact commit and workflow that produced it, plus a dependency SBOM (CycloneDX), and a checksum file:\n\n```bash\ngh attestation verify node-hp-scan-to_*_amd64.deb -R manuc66/node-hp-scan-to\ngh attestation verify release/node-hp-scan-to.sbom.json -R manuc66/node-hp-scan-to --predicate-type https://cyclonedx.org/bom\nsha256sum -c SHA256SUMS.txt\n```\n\n### Using Docker\n\n- You must have [Docker installed](https://www.docker.com/get-started/)\n\n- In a Terminal, run: `docker run -d -e IP=\"IP_ADDRESS_OF_PRINTER\" -e PGID=1000 -e PUID=1000 docker.io/manuc66/node-hp-scan-to`\n\n- For more Docker options, see the [Run with Docker](#run-with-docker) section\n\n- For running with Docker Compose, see the [Example for Docker Compose](#example-for-docker-compose) section\n\n### Using Arch Linux (AUR)\n\n- The package is available in the Arch User Repository (AUR) as `node-hp-scan-to`\n\n- Install it using your preferred AUR helper, for example:\n ```bash\n yay -S node-hp-scan-to\n ```\n or\n ```bash\n paru -S node-hp-scan-to\n ```\n\n## Usage\n\n### Command Line (CLI)\n\nRunning the app with NodeJS using the `npx` command:\n\n`npx node-hp-scan-to`\n\nMain options:\n\n- `-a, --address `: Printer IP (e.g., `192.168.0.5`)\n- `-d, --directory `: Save scans to (e.g., `~/scans`)\n\nExample usage:\n\n`npx node-hp-scan-to -a 192.168.0.5 -d ~/scans`\n\n#### Discovering devices\n\n`npx node-hp-scan-to discover`\n\nLists every HP scan-capable device found on the network, one `nameip` pair per line. Devices are discovered through mDNS and verified against the printer's proprietary `DiscoveryTree.xml` endpoint, so other network gadgets are filtered out. Useful to pick the right `-n/--name` value (recommended over a fixed IP, since it keeps working when the printer's DHCP lease changes).\n\nOptions: `--timeout ` (browsing window, default 5), `--json` (machine-readable array), `--ip ` (verify a single address), `--name ` (only keep matching names). Exit code is `0` when at least one device was found.\n\n#### CLI Options\n\nRun `npx node-hp-scan-to --help` to see the full list of options below:\n\n| Option | Description | Example/Default |\n| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |\n| `-a`, `--address` | Printer IP address. | `-a 192.168.0.5` (no default) |\n| `-d`, `--directory` | Directory to save scanned documents. Defaults to `/tmp/scan-to-pc` if not set. | `-d /tmp/scan-to-pc1234` |\n| `-D`, `--debug` | Enable debug logging. | `-D` (disabled by default) |\n| `-f`, `--image-format` | Image format for scans (when not PDF). | `-f Jpeg` (choices: Jpeg, Bmp) |\n| `-h`, `--height` | Scan height in pixels. Defaults to 3507. | `-h 3507` |\n| `-k`, `--keep-files` | Retain scanned files after uploading to Paperless-ngx or Nextcloud (disabled by default). | `-k` (disabled by default) |\n| `-l`, `--label` | The name of the computer running this app. Defaults to the hostname. | `-l ` (default: system hostname) |\n| `-n`, `--name` | Printer name (quote if it contains spaces). | `-n \"Officejet 6500 E710n-z\"` (no default) |\n| `-o`, `--paperless-token` | The paperless token. Required unless `----paperless-token-file` is used. Overrides if both are provided. | `-o xxxxxxxxxxxx` (no default) |\n| `--paperless-token-file` | File name that contains the paperless token. Required unless `---paperless-token` is used. Takes precedence if both are provided. | `--paperless-token-file some/path/to/file` (no default) |\n| `-p`, `--pattern` | Filename pattern (no extension). Use quotes for static text, supports date/time masks (see [dateformat docs](https://www.npmjs.com/package/dateformat#mask-options)). Defaults to `scan_page`. | `-p scan1_page1` |\n| `-r`, `--resolution` | Scan resolution in DPI. Defaults to 200. | `-r 200` |\n| `--mode ` | Selects the scan mode (default: Color) (choices: \"Gray\", \"Color\"). | `--mode Gray` |\n| `--paper-size ` | Paper size preset: A4 (default), Letter, Legal, A5, B5, or Max (case-insensitive). Cannot be used with `--paper-dim`. | `--paper-size Letter` |\n| `--paper-orientation ` | Paper orientation: portrait (default) or landscape. Applied to `--paper-size` only. | `--paper-orientation landscape` |\n| `--paper-dim ` | Custom paper dimensions with unit (e.g., 21x29.7cm, 8.5x11in, 210x297mm). Cannot be used with `--paper-size`. | `--paper-dim 8.5x11in` |\n| `-s`, `--paperless-post-document-url` | Paperless-ngx API URL for uploading documents. | `-s https://domain.tld/api/documents/post_document/` (no default) |\n| `-t`, `--temp-directory` | Temporary directory for processing. Defaults to `/tmp/scan-to-pc` if not set. | `-t /tmp/scan-to-pc5678` |\n| `-w`, `--width` | Scan width in pixels. Defaults to 2481. | `-w 2481` |\n| `--device-up-polling-interval` | Polling interval (in milliseconds) to check if the printer is online. | `--device-up-polling-interval 5000` (no default) |\n| `--nextcloud-password` | Nextcloud app password. Required unless `--nextcloud-password-file` is used. Overrides if both are provided. | `--nextcloud-password mypassword` (no default) |\n| `--nextcloud-password-file` | File containing the Nextcloud app password. Required unless `--nextcloud-password` is used. Takes precedence if both are provided. | `--nextcloud-password-file /path/to/file` (no default) |\n| `--nextcloud-upload-folder` | Nextcloud folder for uploads. Defaults to `scan`. | `--nextcloud-upload-folder scan` |\n| `--nextcloud-url` | Nextcloud instance URL. | `--nextcloud-url https://domain.tld` (no default) |\n| `--nextcloud-username` | Nextcloud username with write access to the upload folder. | `--nextcloud-username user` (no default) |\n\n**Notes:**\n\n- Date/time patterns for `--pattern` follow the [dateformat](https://www.npmjs.com/package/dateformat) library's \"Mask options\" section.\n\n- Defaults like `/tmp/scan-to-pc` include a random suffix in practice (e.g., `/tmp/scan-to-pc1234`).\n\n#### Paper Size Configuration\n\nBy default, scans use **A4 paper size** (210Γ297 mm). You can specify a different paper size or custom dimensions via CLI flags, environment variables, or the config file.\n\n##### Preset Paper Sizes\n\nThe following preset sizes are available (case-insensitive):\n\n| Preset | Dimensions | Use Case |\n| ---------------- | -------------- | ---------------------------------------------------------- |\n| **A4** (default) | 210Γ297 mm | Standard European paper size |\n| **Letter** | 215.9Γ279.4 mm | Standard US letter size |\n| **Legal** | 215.9Γ355.6 mm | Standard US legal size |\n| **A5** | 148Γ210 mm | Half of A4 size |\n| **B5** | 176Γ250 mm | Between A4 and A5 |\n| **Max** | Device maximum | Uses the device's maximum scannable area (not auto-detect) |\n\n##### Custom Sizes\n\nYou can specify custom paper dimensions with explicit units using the `--paper-dim` option:\n\n```bash\n# Centimeters\nnpx node-hp-scan-to single-scan --paper-dim 21x29.7cm\n\n# Inches\nnpx node-hp-scan-to single-scan --paper-dim 8.5x11in\n\n# Millimeters\nnpx node-hp-scan-to single-scan --paper-dim 210x297mm\n```\n\n**Supported units:** `cm`, `mm`, `in` (inches). Units are **required** and **case-insensitive**.\n\n##### Configuration Precedence\n\nPaper size is resolved in the following order (highest to lowest priority):\n\n1. **CLI flags**: `--paper-size` or `--paper-dim`\n2. **Environment variables**: `PAPER_SIZE` or `PAPER_DIM`\n3. **Config file**: `paper_size` or `paper_dim` in `config/default.json`\n4. **Default**: A4 (210Γ297 mm)\n\n##### Important Rules\n\n- **Cannot specify both `--paper-size` and `--paper-dim` simultaneously.** You must choose one; attempting to use both will result in an error.\n- **Resolution (DPI) is independent** of paper size. You can specify both independently:\n ```bash\n npx node-hp-scan-to single-scan --paper-size Letter --resolution 300\n ```\n- **Device maximum is respected.** If your custom size exceeds the device's maximum scannable area, the scan will be clamped to the device's limits.\n- **\"Max\" uses device capabilities, not auto-detection.** The `Max` preset uses the device's reported maximum scan area; it does **not** automatically detect the actual paper size in the scanner.\n\n##### Examples\n\n```bash\n# Use Letter size\nnpx node-hp-scan-to single-scan --paper-size Letter\n\n# Use A5 (smaller) size\nnpx node-hp-scan-to single-scan --paper-size A5\n\n# Use maximum scannable area\nnpx node-hp-scan-to single-scan --paper-size Max\n\n# Use custom size in centimeters\nnpx node-hp-scan-to single-scan --paper-dim 21x29.7cm\n\n# Use custom size in inches (8.5\" Γ 11\")\nnpx node-hp-scan-to single-scan --paper-dim 8.5x11in\n\n# With Docker (environment variable)\ndocker run -e PAPER_SIZE=Letter manuc66/node-hp-scan-to\n\n# With Docker Compose\nenvironment:\n PAPER_SIZE: \"Letter\"\n PAPER_DIM: null # Must be null if not using custom dimensions\n\n# In config file (config/default.json)\n{\n \"paper_size\": \"A4\",\n \"paper_dim\": null\n}\n```\n\n##### `listen`\n\nBy default, this app runs the `listen` command as the default mode. It will listen to the print for new job and trigger based on the selection on the device.\n\nRun `npx node-hp-scan-to listen --help` to get the full list of command options.\n\n\n\n```text\nUsage: listen [options]\n\nListen the device for new scan job to save to this target\n\nOutput Options:\n -d, --directory Directory where scans are saved (default: /tmp/scan-to-pcRANDOM)\n -p, --pattern Pattern for filename (i.e. \"scan\"_dd.mm.yyyy_hh:MM:ss, default would be scanPageNUMBER), make sure that the pattern is enclosed in extra quotes\n -f, --image-format Image format for scans (when not PDF): Jpeg (default) or Bmp\n -k, --keep-files Keep the scan files on the file system when sent to external systems for local backup and easy access (default: false)\n\nScan Options:\n -r, --resolution Resolution in DPI of the scans (default: 200)\n --mode Selects the scan mode (default: Color) (choices: \"Gray\", \"Color\")\n -w, --width Width in pixels of the scans (default: max)\n -h, --height Height in pixels of the scans (default: max)\n --paper-size Paper size preset: A4 (default), Letter, Legal, A5, B5, or Max (case-insensitive)\n --paper-orientation Paper orientation: portrait (default) or landscape. Applied to --paper-size only. (choices: \"portrait\", \"landscape\")\n --paper-dim Custom paper dimensions with unit (e.g., 21x29.7cm, 8.5x11in, 210x297mm). Cannot be used with --paper-size.\n -t, --temp-directory Temp directory used for processing (default: /tmp/scan-to-pcRANDOM)\n --prefer-eSCL Prefer eSCL protocol if available\n\nOptions:\n --device-up-polling-interval Device up polling interval in milliseconds\n --help display help for command\n\nPaperless Options:\n -s, --paperless-post-document-url The paperless post document url (example: https://domain.tld/api/documents/post_document/)\n -o, --paperless-token The paperless token. Either this or paperless-token-file is required for paperless integration.\n --paperless-token-file File name that contains the paperless token. Either this or paperless-token is required for paperless integration.\n --paperless-group-multi-page-scan-into-a-pdf Combine multiple scanned images into a single PDF document\n --paperless-always-send-as-pdf-file Always convert scan job to pdf before sending to paperless\n\nNextcloud Options:\n --nextcloud-url The nextcloud url (example: https://domain.tld)\n --nextcloud-username The nextcloud username\n --nextcloud-password The nextcloud app password for username. Either this or nextcloud-password-file is required for nextcloud integration.\n --nextcloud-password-file File name that contains the nextcloud app password for username. Either this or nextcloud-password is required for nextcloud integration.\n --nextcloud-upload-folder The upload folder where documents or images are uploaded (default: scan)\n\nDevice Control Screen Options:\n -l, --label
![\"node-hp-scan-to](\"assets/banner.png\")
\n