scanner docs

README.md

@@ -1,4 +1,5 @@
 # CDSS Common Documentation
+> [https://berkeley-cdss.github.io/docs/](https://berkeley-cdss.github.io/docs/)
 
 [![Deploy Jekyll site to Pages](https://github.com/berkeley-cdss/docs/actions/workflows/jekyll.yml/badge.svg)](https://github.com/berkeley-cdss/docs/actions/workflows/jekyll.yml)
 

course-logistics/exams/index.md

@@ -9,5 +9,11 @@ parent: Course Logistics
 
 ## Quick Links
 
-- [How 2 Scan Good](https://docs.google.com/document/d/1WTF5LQXpsJ7E0EwEVHKZAkXZVcsNrw6XVVBdjRNzHnQ/edit?usp=sharing) (shortlink: [eecs.link/scangood](https://eecs.link/scangood)), a guide to scanning paper exams by Weston Hughes, edits by Lisa Yan, Michael Ball, Peyrin Kao
 - [Proctoring Script Template](https://docs.google.com/document/d/1JGrZr7OUUDWw8vi7lcaiYhvBGQLxyy4bF7K4u65giHQ/edit?usp=sharing)
+
+## Printing & Scanning
+
+* [How 2 Scan Good](https://docs.google.com/document/d/1WTF5LQXpsJ7E0EwEVHKZAkXZVcsNrw6XVVBdjRNzHnQ/edit?usp=sharing) (shortlink: [eecs.link/scangood](https://eecs.link/scangood)), a guide to scanning paper exams by Weston Hughes, edits by Lisa Yan, Michael Ball, Peyrin Kao
+* [Printing to Soda Copiers via USB](/course-logistics/printing/printing-from-usb)
+* [Scanning Station Overview](/course-logistics/scanning)
+  * [Exam Scanning README](/course-logistics/scanning/exam-scanning) (details on the `scan-exams` command, filename conventions, batch numbering, and semester detection)

course-logistics/printing/printing-from-usb.md

@@ -0,0 +1,101 @@
+---
+title: Printing to Soda Copiers via USB
+layout: default
+nav_order: 1
+parent: Course Logistics
+permalink: /course-logistics/printing/printing-from-usb
+---
+
+# Printing to Soda Copiers via USB
+
+The copiers in Soda are Canon iR-ADV 8786i. They support USB printing, but you need to install the drivers on your computer first. The drivers are available on Canon's website, and you can download the UFRII_v10.19.21_mac.zip file for macOS.
+
+## Get Drivers from Canon
+
+https://www.usa.canon.com/support/p/imagerunner-advance-dx-8786i?srsltid=AfmBOoqs8k-hEBSw8mmbcC18N7j8l8HqhC0QRlNzt_2ASrGxvh4qxenM
+
+Look for the file: UFRII_v10.19.21_mac.zip
+
+## Adding the printer
+* Install the drivers by running the installer package in the zip file
+* Open System Preferences > Printers & Scanners
+* Click the + button to add a new printer
+* Select the Canon iR-ADV 8786/8795 UFR II printer from the list of available printers
+* Set a custom name for the printer, such as "Canon_iR_ADV_8786_8795_UFR_II_Front"
+* Click Add to add the printer to your system
+
+**Tell macOS there's a stapler**
+* Open the Printers & Scanners settings
+* Select the Canon iR-ADV 8786/8795 UFR II printer from
+* Click on "Options & Supplies"
+* Go to the "Options" tab
+* Find the row for "Paper Deck Unit" and select "Paper Deck Unit E1"
+* Find the row for "Output Options" and select "Staple Finisher W1 Pro"
+
+Click OK to save the settings.
+
+![Printer Options Screenshot](./1-setup-add-stapler.png)
+
+## Printing with the Print UI
+* Open the file you want to print
+* Press Command + P to open the print dialog
+* Select the Canon iR-ADV 8786/8795 UFR II printer from the list of available printers
+* Click on the "Show Details" button to access the printer options
+* Set the number of copies you want to print
+* Ensure double-sided printing is enabled
+* Click on "Printer Options" to access additional settings
+  * Click on the "Finishing" (the "i" icon on the right) tab and enable "Staple" if you want to staple the copies together
+  * Click on "Finishing Details…" to enable Copy Set Numbering if you want to add copy numbers on the bottom corner of each page.
+
+#### Images
+
+![Print Dialog Screenshot](./2-print-dialog.png)
+![Finishing Options Screenshot](./3-finishing-options.png)
+![Finishing Details Screenshot](./4-finishing-details.png)
+
+## Check stapling options
+
+```sh
+lpoptions -p Canon_iR_ADV_8786_8795_UFR_II -l | grep Staple
+```
+
+  CNStaple/Staple: False *True Stapleless
+  StapleLocation/Position: *TopLeft BottomLeft Left TopRight BottomRight Right Top Bottom
+  Paper Source = Cas2
+
+# Set default to staple
+
+```sh
+lpoptions -p Canon_iR_ADV_8786_8795_UFR_II -o CNStaple=True
+```
+
+# Print One file
+
+```sh
+lpr -P Canon_iR_ADV_8786_8795_UFR_II -o Staple=True "Final_Exam_A__printouts_253_to_288_Part2.pdf"
+```
+
+## Printing multiple copies of a file
+
+```
+lpr -P Canon_iR_ADV_8786_8795_UFR_II -o Staple=True -o NumCopies=3 "Final_Exam_A__printouts_253_to_288_Part2.pdf"
+```
+
+### Adding Copyset Numbering to the Output
+
+**TODO**
+```sh
+lpr -P Canon_iR_ADV_8786_8795_UFR_II .... "file.pdf"
+```
+
+## Schedule a batch
+on macOS this immediately sends the file to queue, which you can view by opening the printer app.
+
+```sh
+PRINTER='Canon_iR_ADV_8786_8795_UFR_II_Front'
+for pdffile in $(ls *.pdf | sort -V); do
+  lpr -P $PRINTER -o InputSlot=Cas2 -o CNStaple=True "$pdffile";
+  mv $pdffile printed/;
+  echo $pdffile;
+done
+```

course-logistics/scanning/exam-scanning.md

@@ -0,0 +1,90 @@
+---
+title: Exam Scanning
+layout: default
+nav_order: 1
+parent: Scanning Station Overview
+permalink: /course-logistics/scanning/exam-scanning
+---
+
+# Exam Scanning
+
+The `scan-exams` command is a batch scanning tool for the CDSS [scanning station](scanning). It scans exams from the Canon DR-G2110 ADF and produces compressed, timestamped PDFs.
+
+For general scanning station info, see the [Scanning Station Overview](scanning).
+
+## Usage
+
+```
+scan-exams              # interactive prompts
+scan-exams -o           # scan and open PDF when done
+scan-exams -r -o        # reuse last course/exam, open when done
+scan-exams -q           # no prompts, just scan and save
+scan-exams -h           # show help
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-o` | Open the PDF automatically after scanning |
+| `-r` | Reuse course/exam metadata from the last scan |
+| `-q` | Quiet mode — no prompts, auto batch number and timestamp |
+| `-h` | Show help |
+
+## Output filename
+
+```
+20260429-143022-SP26-cs169-mt1-batch-01-240pg.pdf
+│              │    │     │    │        └─ page count
+│              │    │     │    └─ auto-incrementing batch number
+│              │    │     └─ exam type (mt, mt1, mt2, final, quiz)
+│              │    └─ course number
+│              └─ semester (SP/SU/FA + 2-digit year)
+└─ timestamp (YYYYMMDD-HHMMSS)
+```
+
+## Semester detection
+
+Automatically determined from the current date:
+
+| Months | Semester |
+|--------|----------|
+| January–May | SP (Spring) |
+| June–August | SU (Summer) |
+| September–December | FA (Fall) |
+
+## Batch numbering
+
+The batch number auto-increments based on existing files in `~/scans/` matching the same course and exam type. Scanning `cs169-mt1` when `batch-01` and `batch-02` already exist produces `batch-03`.
+
+## Reusing metadata (`-r`)
+
+After each scan, the course, exam type, expected copies, pages per exam, and rotation setting are saved to `~/.scan-exams-last`. Use `-r` to reuse these values for the next scan without re-entering them — useful when scanning the same exam in multiple batches.
+
+## Scan settings
+
+| Setting | Value |
+|---------|-------|
+| Mode | Duplex (double-sided) |
+| Color | Grayscale |
+| Resolution | 200 DPI |
+| Paper size | Letter (8.5" × 11") |
+| Compression | JPEG quality 85 |
+| Output | Single PDF per batch |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `setup.sh` | Install Canon SANE driver, NAPS2, AirSane, and `scan-exams` command |
+| `setup_apps.sh` | Install general dev tools (VS Code, Docker, mise, PostgreSQL, etc.) |
+| `scan-exams.sh` | The `scan-exams` bash function |
+
+Source: [berkeley-cdss/docs/scanning-scripts](https://github.com/berkeley-cdss/docs/tree/main/scanning-scripts)
+
+## Data handling
+
+**Scanned files may contain sensitive data (exams, student work, etc.).**
+
+- Copy your PDFs to your own device after scanning.
+- **Delete your files from `~/scans/` when you're done.**

course-logistics/scanning/index.md

@@ -0,0 +1,164 @@
+---
+title: Scanning Station Overview
+layout: default
+nav_order: 3
+parent: Course Logistics
+---
+
+# Scanning Station Overview
+
+The CDSS document scanning station is a 2018 Mac Mini running Ubuntu 24.04 LTS, connected to a Canon imageFORMULA DR-G2110 production scanner via USB 3.0. Macs on the same network can also scan directly via AirSane.
+
+## Location & Access
+
+The scanning station is located in **TODO: room/building**. (Currently Michae's office, but will move to a more normal location once the Gateway finally opens.)
+
+- **Username:** `oski`
+- **Password:** Posted near the computer
+
+This is a shared local account. Do not store sensitive files on this machine — save scans to your own device, or upload to Gradescope, and clean up `~/scans` when you're done.
+
+## Using the Scanner
+
+**[Jump to the Exam Scanning README](/course-logistics/scanning/exam-scanning) for detailed instructions on using the `scan-exams` command, filename conventions, batch numbering, and semester detection.**
+
+### `scan-exams` (recommended for exams)
+
+Open a terminal and type:
+
+```
+scan-exams
+```
+
+This walks you through scanning a batch of exams: course number, exam type, expected copies, and pages per exam. It scans duplex at 200 DPI grayscale, compresses the output, and saves a single PDF to `~/scans/`.
+
+Common options:
+
+| Flag | Description |
+|------|-------------|
+| `-o` | Open the PDF automatically after scanning |
+| `-r` | Reuse course/exam metadata from the last scan |
+| `-q` | Quiet mode — no prompts, just scan and save |
+| `-h` | Show help |
+
+Examples:
+
+```
+scan-exams -o           # scan and open the PDF when done
+scan-exams -r -o        # another batch of the same exam
+scan-exams -h           # full usage info
+```
+
+For details on filenames, batch numbering, and semester detection, see the [Exam Scanning README](exam-scanning).
+
+### NAPS2 (GUI scanning)
+
+NAPS2 is a graphical scanning app linked on the desktop. You can also launch it from a terminal:
+
+```
+naps2
+```
+
+Select **SANE Driver**, choose the Canon DR-G2110, and save directly to PDF.
+
+### `scanimage` (advanced CLI)
+
+For more control over scan settings:
+
+```
+scanimage -L                    # list scanners
+scanimage -A                    # show all scanner options
+scanimage --format=tiff --resolution 200 --mode Gray --source="Duplex" --batch=scan_%04d.tiff
+img2pdf scan_*.tiff -o output.pdf
+```
+
+### Network scanning from a Mac
+
+The scanner is published on the local network via AirSane. On any Mac on the same network:
+(This is currently the internal EECS network, and may not be accessible from campus Wi-Fi.)
+
+1. Open **Image Capture** (or **Preview → File → Import from Scanner**)
+2. The Canon DR-G2110 should appear in the sidebar
+3. Select scan settings and scan — files go directly to your Mac
+
+AirSane also provides a web interface at `http://TODO-HOSTNAME:8090/`.
+
+### After scanning
+
+**Scanned files may contain sensitive data (exams, student work, etc.).**
+
+- Copy your PDFs from `~/scans/` to your own device.
+- **Delete your files from `~/scans/` when you're done.** This is a shared machine.
+- The workstation does not share files over the network — only the scanner device is exposed via AirSane.
+
+## Equipment
+
+- **Scanner:** Canon imageFORMULA DR-G2110 (USB 3.0)
+- **Computer:** 2018 Mac Mini, Intel, 64 GB RAM, Ubuntu 24.04 LTS
+- **Network scanning:** AirSane (eSCL/AirScan protocol, auto-discovered by macOS)
+
+## Setup & Maintenance
+
+The setup scripts and scanning tools are maintained in the [berkeley-cdss/docs](https://github.com/berkeley-cdss/docs) repository:
+
+- [scanning-scripts/](https://github.com/berkeley-cdss/docs/tree/main/course-logistics/scanning/) — setup scripts, scan-exams tool, and documentation
+
+To re-run the workstation setup from scratch:
+
+```
+git clone https://github.com/berkeley-cdss/docs.git
+cd docs/course-logistics/scanning
+bash setup.sh        # scanner driver, NAPS2, AirSane, scan-exams command
+bash setup_apps.sh   # general dev tools and apps
+```
+
+Setup installs scripts and docs to `~/scanner/` and adds `scan-exams` to `~/.bashrc`.
+
+### Installed files
+
+| Location | Contents |
+|----------|----------|
+| `~/scanner/scan-exams.sh` | The `scan-exams` function (sourced by `.bashrc`) |
+| `~/scanner/README.md` | This documentation |
+| `~/scans/` | Default scan output directory |
+| `~/.scan-exams-last` | Saved metadata for `scan-exams -r` |
+
+## Troubleshooting
+
+### Scanner not detected
+
+```
+lsusb | grep -i canon           # check USB connection
+scanimage -L                    # check SANE detection
+dpkg -l | grep canon            # check driver installation
+```
+
+### Scan source options
+
+The scanner uses `--source="Duplex"` for double-sided and `--source="Simplex"` for single-sided. Check available options:
+
+```
+scanimage -A | grep -i source
+```
+
+### Scanning pauses or is slow
+
+- Confirm USB 3.0 connection (not USB 2.0)
+- Check disk write speed — scan output should go to an SSD/NVMe
+- Lower resolution (200 DPI is usually sufficient for exams)
+- Use grayscale instead of color
+
+### AirSane not visible on Mac
+
+- Ensure both machines are on the same network/subnet
+- Check AirSane is running: `sudo systemctl status airsaned`
+- Check Avahi is running: `sudo systemctl status avahi-daemon`
+- Try the web interface: `http://TODO-HOSTNAME.local:8090/`
+
+### Managing services
+
+```
+sudo systemctl status airsaned      # AirSane status
+sudo systemctl restart airsaned     # restart AirSane
+sudo journalctl -u airsaned -f      # AirSane logs
+```