From 9d3cd4271b21b073d6084b2ab90419eda8465a33 Mon Sep 17 00:00:00 2001 From: Mahocke Date: Sun, 20 Sep 2026 20:42:56 +0200 Subject: [PATCH] README: Contributing section; issue templates for other printers, destinations and boards Co-Authored-By: Claude Fable 5.1 --- .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/other-board.yml | 35 ++++++++++++++ .github/ISSUE_TEMPLATE/other-destination.yml | 38 +++++++++++++++ .github/ISSUE_TEMPLATE/other-printer.yml | 50 ++++++++++++++++++++ README.md | 20 ++++++++ 5 files changed, 144 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/other-board.yml create mode 100644 .github/ISSUE_TEMPLATE/other-destination.yml create mode 100644 .github/ISSUE_TEMPLATE/other-printer.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/other-board.yml b/.github/ISSUE_TEMPLATE/other-board.yml new file mode 100644 index 0000000..4e6ef70 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other-board.yml @@ -0,0 +1,35 @@ +name: Other board +description: Port to a board other than the LILYGO T-Dongle-S3 +title: "[board] " +labels: [board] +body: + - type: input + id: board + attributes: + label: Board + placeholder: e.g. Espressif ESP32-S3-USB-OTG, Waveshare ESP32-S3-... + validations: + required: true + - type: checkboxes + id: features + attributes: + label: What does the board have? + options: + - label: ESP32-S3 (native USB - required) + - label: microSD/SD card slot on SD_MMC + - label: USB-A plug (fits the printer directly) + - label: Display + - label: Status LED + - type: textarea + id: pins + attributes: + label: Pins and build settings + description: SD pins, display pins, LED pins, flash size, FQBN / partition scheme you used + render: text + - type: textarea + id: state + attributes: + label: State + description: Does it compile, does the printer see it, does a scan arrive? What is missing? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/other-destination.yml b/.github/ISSUE_TEMPLATE/other-destination.yml new file mode 100644 index 0000000..9ef70a5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other-destination.yml @@ -0,0 +1,38 @@ +name: Other destination +description: A receiver for another storage target (cloud, mail, DMS, NAS ...) +title: "[receiver] " +labels: [receiver] +body: + - type: input + id: target + attributes: + label: Destination + placeholder: e.g. Nextcloud via WebDAV, Paperless-ngx, mail + validations: + required: true + - type: dropdown + id: state + attributes: + label: State + options: + - Idea or wish + - Built it, want to share (link or pull request) + - Built it, but something with the stick side is missing + validations: + required: true + - type: textarea + id: details + attributes: + label: Details + description: How the receiver works, what the stick would need to send differently, link to your code if any + validations: + required: true + - type: checkboxes + id: contract + attributes: + label: Contract with the stick + description: A receiver must keep these rules so the stick does not delete a scan that did not arrive + options: + - label: Only answers 200 after the file is safely stored + - label: Rejects incomplete uploads (Content-Length mismatch, missing %%EOF) + - label: Recognizes repeated uploads by the id parameter and answers with the word "duplicate" diff --git a/.github/ISSUE_TEMPLATE/other-printer.yml b/.github/ISSUE_TEMPLATE/other-printer.yml new file mode 100644 index 0000000..fb03871 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other-printer.yml @@ -0,0 +1,50 @@ +name: Other printer +description: Report how the stick behaves on a printer other than the HP PageWide 780 +title: "[printer] " +labels: [printer] +body: + - type: input + id: model + attributes: + label: Printer model and firmware version + placeholder: e.g. Brother MFC-L8900CDW, firmware ZA1234 + validations: + required: true + - type: input + id: version + attributes: + label: Stick firmware version + description: Shown on the status page and on the display at power-on + placeholder: e.g. v40 + validations: + required: true + - type: dropdown + id: result + attributes: + label: What works? + options: + - Printer does not recognize the stick at all + - Printer recognizes the stick, but the scan fails + - Scan is written, but the stick does not detect it (no upload) + - Everything works, just reporting a success + - Something else (describe below) + validations: + required: true + - type: textarea + id: observed + attributes: + label: What did you see? + description: Printer messages and error codes, what the stick display showed, timing + validations: + required: true + - type: textarea + id: log + attributes: + label: Stick log + description: Copy the log page (/log) after the scan. Please remove anything private (IPs, names). + render: text + - type: input + id: card + attributes: + label: Card + placeholder: size, brand, formatted with the stick (yes/no) diff --git a/README.md b/README.md index bba53b6..31f40a6 100644 --- a/README.md +++ b/README.md @@ -444,6 +444,26 @@ sudo systemctl enable --now scan-receiver - Further boards, in particular ones without a card slot (there the internal flash would have to serve as storage) +## Contributing + +The stick has been developed on a single printer, a single receiver and a single board. +Three areas are waiting for experience from other setups - please open an issue, the +templates ask for what is needed: + +- **Other printers.** Every printer talks to a USB stick a little differently (see + "Pitfalls"). If yours behaves differently, the stick log (`/log`) during a scan and the + printer model and firmware version are the most valuable input. +- **Other destinations.** The stick only knows a URL; `empfaenger/scan-receiver.py` is a + minimal example. Receivers for cloud storage, mail, DMS or a NAS are welcome - as a + separate script or as a pointer to your own repository. +- **Other boards.** Requirements: an ESP32-S3 (native USB for the mass-storage role), + a card slot on SD_MMC and ideally a USB-A plug so it fits a printer directly. Pin + tables and build settings (FQBN) for further boards are welcome. + +Pull requests are welcome too. Please keep them small and describe how you tested; the +CI build runs automatically. Do not put private IPs, hostnames or credentials into the +code or the pull request text. + ## License MIT, see `LICENSE`.