{"id":50927804,"url":"https://github.com/mkubicek/canon-cgiscsi","last_synced_at":"2026-06-17T01:02:11.489Z","repository":{"id":358520936,"uuid":"1234134397","full_name":"mkubicek/canon-cgiscsi","owner":"mkubicek","description":"Clean-room Python client for Canon's cgiscsi document scanner protocol","archived":false,"fork":false,"pushed_at":"2026-05-17T18:33:32.000Z","size":211,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T20:44:47.312Z","etag":null,"topics":["canon","document-scanner","ocr","python","reverse-engineering","scanner"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkubicek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-09T19:46:14.000Z","updated_at":"2026-05-09T19:46:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mkubicek/canon-cgiscsi","commit_stats":null,"previous_names":["mkubicek/canon-cgiscsi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mkubicek/canon-cgiscsi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkubicek%2Fcanon-cgiscsi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkubicek%2Fcanon-cgiscsi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkubicek%2Fcanon-cgiscsi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkubicek%2Fcanon-cgiscsi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkubicek","download_url":"https://codeload.github.com/mkubicek/canon-cgiscsi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkubicek%2Fcanon-cgiscsi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34429493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["canon","document-scanner","ocr","python","reverse-engineering","scanner"],"created_at":"2026-06-17T01:02:10.157Z","updated_at":"2026-06-17T01:02:11.479Z","avatar_url":"https://github.com/mkubicek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# canon-cgiscsi\n\n`canon-cgiscsi` is an unofficial Python client and protocol reference for\nCanon's `cgiscsi` network document scanner interface, exposed by some\nimageFORMULA DR scanners at:\n\n```text\nPOST /cgi-bin/cgiscsi\n```\n\nThe project was created to make otherwise unsupported network scanning usable on\nmodern systems. It contains clean-room protocol notes and a small executable\nharness for discovery, status checks, ADF scanning, compact PDF assembly, and\noptional searchable PDF output.\n\nThis repository is not affiliated with Canon.\n\n## Current Status\n\nLive-tested hardware:\n\n| Model | Firmware/revision | cgiscsi health | ADF simplex | ADF duplex | AirScan adapter | Notes |\n| --- | --- | --- | --- | --- | --- | --- |\n| Canon imageFORMULA DR-C225W II | `1.06` / `20140609` | yes | yes | yes | yes, experimental | Live-tested by maintainer. Discovery, status/control commands, JPEG capture, blank-back filtering, PDF assembly, and OCRmyPDF searchable output work. |\n\nLikely related but untested:\n\n- Canon DR-C225W and other networked imageFORMULA DR devices that expose\n  `/cgi-bin/cgiscsi`.\n- Other Canon DR network models may need per-model adjustments for scan-mode\n  pages, read-kind fields, or vendor-specific payloads.\n- Community reports are welcome, but unlisted models should be treated as\n  untested until someone verifies discovery, safe health checks, and scanning.\n\nNot supported:\n\n- USB-only Canon DR scanners. Use SANE's `canon_dr` backend instead.\n- PIXMA, CanoScan, imageCLASS, and other non-DR Canon product families.\n\n## Safety\n\nThis is low-level scanner control software. Malformed scan parameters can leave\nthe scanner's `cgiscsi` CGI unresponsive until the device is restarted. On the\ntested DR-C225W II, recovery was possible by power-cycling or opening:\n\n```text\nhttp://scanner-host-or-ip/eng/private/mainte/restart_main.htm\n```\n\nFor a new model, start with discovery, `INQUIRY`, and dry-run scan plans before\nsending a live `SCAN`.\n\n## Install\n\nThe harness uses `uv`:\n\n```sh\ncd harness\nuv sync\n```\n\nSearchable PDF output is the default, so install OCRmyPDF, Tesseract, and\nlanguage data. On macOS:\n\n```sh\nbrew install ocrmypdf tesseract-lang\n```\n\nUse `--no-ocr` when you want an image-only PDF or do not have OCR tools\ninstalled.\n\n## Quick Start\n\nSet your scanner host once:\n\n```sh\nexport CANON_CGISCSI_HOST=\"scanner-host-or-ip\"\n```\n\nConfirm that the device answers `cgiscsi`:\n\n```sh\nuv run python discover.py --candidate \"$CANON_CGISCSI_HOST\"\nuv run python cgiscsi.py inquiry\nuv run python cgiscsi.py status\n```\n\nPrint the scan plan without touching the scanner:\n\n```sh\nuv run python scan_to_pdf.py --scan-all --duplex --output-pdf captures/scan.pdf\n```\n\nScan all sheets currently in the ADF. This always scans duplex, stops when the\nADF is empty, drops blank backs by default, and writes one compact searchable\nPDF:\n\n```sh\nuv run python scan_to_pdf.py --execute-plan --experimental-scan \\\n  --scan-all --duplex \\\n  --output-dir captures/run-001 \\\n  --output-pdf captures/run-001/scan.pdf\n```\n\nDefaults are tuned for office documents:\n\n- A4 scan window at 300 DPI.\n- Grayscale JPEG from the scanner.\n- Direct JPEG embedding via `img2pdf`, avoiding a second JPEG encode.\n- PDF page rotation metadata instead of rewriting pixels.\n- Compact OCRmyPDF searchable output by default, with `deu+eng+fra`.\n- No raw streams, per-sheet PDFs, or extracted JPEGs are kept unless requested.\n\nUseful overrides:\n\n```sh\nuv run python scan_to_pdf.py --no-ocr ...\nuv run python scan_to_pdf.py --keep-intermediates ...\nuv run python scan_to_pdf.py --paper letter ...\nuv run python scan_to_pdf.py --scanner-compression-arg 2 ...\nuv run python scan_to_pdf.py --crop-margin-px 25 ...\nuv run python scan_to_pdf.py --keep-blank-pages ...\nuv run python scan_to_pdf.py --ocr-clean --ocr-deskew ...\n```\n\nSee [harness/README.md](harness/README.md) for the full command catalog.\nSee [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for practical recovery steps and\nAirScan adapter checks.\n\n## Protocol Documentation\n\n- [protocol-spec.md](protocol-spec.md) describes the HTTP envelope, request and\n  response framing, SCSI CDB layouts, Canon vendor-specific commands, and scan\n  workflows.\n- [harness/](harness/) contains the executable Python harness.\n- [notes/function-summaries/](notes/function-summaries/) contains concise\n  pseudocode summaries of the decoded Canon driver behavior.\n- [references.md](references.md) records upstream materials and driver artifact\n  hashes used during the interoperability analysis.\n\nCanon driver archives, extracted binaries, raw disassembly, local scans, OCR\noutput, and cached third-party sources are intentionally not included.\n\n## Development\n\nRun the offline tests:\n\n```sh\ncd harness\nuv run python -m unittest discover -s tests -v\n```\n\nCheck the lockfile and syntax:\n\n```sh\nuv lock --check\nuv run python -m py_compile cgiscsi.py commands.py discover.py mock_cgiscsi.py scan_to_pdf.py\n```\n\nBefore publishing a repository, run the checklist in\n[PUBLISHING.md](PUBLISHING.md).\n\n## Legal\n\nThe repository publishes protocol facts, clean-room summaries, and\nindependently written Python code for interoperability. It does not redistribute\nCanon binaries, extracted Canon code, raw proprietary disassembly, SANE source\nsnapshots, or private scan data.\n\nCanon and imageFORMULA are trademarks of Canon Inc. Their names are used here\nonly to identify compatible hardware.\n\n## References\n\nThis project cross-references:\n\n- SANE `canon_dr` backend: https://gitlab.com/sane-project/backends/-/blob/master/backend/canon_dr.c\n- SANE `sane-canon_dr` manpage: https://www.sane-project.org/man/sane-canon_dr.5.html\n- BasicCAT scanner reverse-engineering writeup: https://www.basiccat.org/reverse-engineer-document-scanner/\n\nSee [references.md](references.md) for the complete source list.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkubicek%2Fcanon-cgiscsi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkubicek%2Fcanon-cgiscsi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkubicek%2Fcanon-cgiscsi/lists"}