Printing from the shop app¶

Status: approved phases 1–4 + work orders (owner 2026-10-04 "Ok work orders also") — phase 1–2 (owner 2026-10-04: "Let's start with 1, 2 for now not needed. We have a printer for letters connected to the network") — start with one shelf + part labels; Brother tape host question deferred; paper goes to the networked letter printer (Brother MFC-L3780CDW, CUPS queue on the server).

Open a part, shelf, order or board on your phone and tap Print.
See the label first, check the number of copies, then send it to the right printer.
Use the Zebra for bins, parts and bags; Brother tape for boards; the laser for paperwork.
Reuse the templates and printing tools we already have, with no new subscription.
Start with shelf/bin and part labels, then add receiving, paperwork and board reprints.

Decisions for the owner¶

Start with shelves and parts? Recommended: yes; one shelf first, then the rest.
Keep these supplies? Recommended: Zebra 2 × 1.5 in, Brother TZe 18 mm × 27 mm per board, Letter paper; confirm whether travelers need A4.
Which computer has the Brother USB cable? Confirm computer, operating system, exact printer suffix (P900/P900W), and whether it stays on during shop hours.
Who prints? Recommended: Production prints shop labels/travelers; Sales prints invoices/slips; Receiving/Purchasing prints received-stock labels; Engineering maintains layouts; Administration manages access.
What should the bag say? Confirm product/revision, permanent serial, quantity, and whether any customer-facing text is required. Internal QR links require a staff login.

What already exists¶

The FastAPI/Tabler app is the front door. Keep actions on their object's page; no new “Print tools” menu. Follow embeddedera-app: phone first, existing dialogs, department checks, preview/confirm and the UI release gate.
assistant/labels.py, labelprint.py, zebra.py already search/scan and print part, stock and location labels. Reuse their ERP render/poll path. Existing /tools is legacy UI, not the destination for new app buttons.
Zebra GX430t, 300 dpi, LAN 192.168.5.16:9100 is documented in zebra-gx430t; .20 in an old tester README is wrong. A prior network hang prompted ~HS readiness checks and bounded transmission. This session did not probe or print to hardware.
Brother PT-P900 uses USB in engineering/repos/Universal_Tester/host-api/universal_tester/printers/brother_ptp900.py (VID/PID 04f9:208e). It already renders board serials; physical host/OS remains unconfirmed. Do not assume the wireless P900W is the same device.
The server's CUPS has one queue: Brother_MFC_L3780CDW, a colour laser — lpstat -p on the host reported it idle and enabled on 2026-10-04 (Codex's sandbox could not reach the scheduler; that was the sandbox, not the printer).
erp-config/templates/ contains invoice, proposal, packing slip, PO, traveler, 62 × 29 mm stock and 25 × 25 mm serial templates. Those last two are not the 18 mm board tape layout.
Existing Zebra stock/location/part templates are IDs 9/10/11, with sources still in Notes/hardware/labels/. Move their source ownership into erp-config/templates/ during implementation, preserve history and update the uploader; do not create competing copies.
The ERP map records built-in inventreelabel, inventreelabelmachine and inventreelabelsheet enabled. Local templates target InvenTree 1.5.4; live version and plugin inventory must be read back before implementation. erp-print-templates is the template reference.
invoices.py already proxies ERP-generated PDFs; #invoice/<id> offers Download PDF. partedit.py and lifecycle.py demonstrate department-token selection and audited preview/confirm. Printing must not invoke their stock, payment or lifecycle mutations.

Existing solutions checked first¶

Research checked 2026-10-04. Versions below are upstream observations, not installed versions or upgrade instructions. Plugin compatibility still needs a sandbox proof.

InvenTree core — preferred renderer. MIT; latest listed release 1.5.6, September 26, 2026, with ongoing maintenance. Built-in Django/WeasyPrint label/report templates, API rendering, PDF output and sheet printing cover the layouts; use these before any custom renderer. Releases, licence/project, label templates, reports.
InvenTree machine registry — preferred plugin interface. Already documented locally; evaluate its printer drivers through the API without exposing ERP screens. Built-in label-machine plugin, community catalogue.
inventree-zebra-plugin — preferred replacement candidate for transport. MIT, 0.9.0, December 23, 2025; published releases, but current ERP compatibility is unproven. Supports raster and ZPL templates, USB/network and copies. Compare its timeout/status behavior with our existing sender before switching. Keep preview local: its optional Labelary preview sends data to another service. Package, source.
inventree-zpl-plugin — alternative, not first choice. MIT; small repository (five commits observed), with no current release version verified. Jinja2-to-ZPL avoids raster conversion but adds another layout format and maintenance uncertainty. Source and example.
inventree-brother-plugin — test exact model first. MIT, 2.0.6, May 9, 2026; recent release. Lists PT-P900W/PT-P950NW plus QL printers, not the plain PT-P900. Uses brother-ql-inventree; this does not prove compatibility with USB PID 208e. Package, supported models.
brother_ql — not a PT-P900 solution by assumption. GPL-3.0; published 0.9.4, January 13, 2019, with later source work but an old packaged release. Original supported models are QL; distinguish it from InvenTree's fork. Package, source/model list.
ptouch-print — Linux USB candidate. GPLv3; upstream source identifies 1.7 and shows 2026 work. Exact PT-P900/PID support and tape cutting remain unverified, so no recommendation to replace the working tester driver yet. Upstream, version/activity, licence.
Brother b-PAC — Windows fallback. Vendor SDK, proprietary terms rather than open source; 3.4.017, August 31, 2026, actively updated. Requires a Windows host, matching driver/SDK architecture and model verification. Prefer the existing USB implementation or a proven open-source driver; no paid service is justified. SDK downloads/history, Brother model/tool matrix.
CUPS/IPP — preferred paper queue. OpenPrinting CUPS 2.4.19 is the latest listed release; Apache-2.0 with GPL2-linking exception, maintained. Reuse the existing laser queue; IPP provides submission/status rather than browser access to printer sockets. Releases, licence.
Browser/PDF — universal fallback. Existing browser capability, no added package/version. Opens a system print dialog; cannot guarantee silent printing, selected media or physical delivery. Exact-size PDF is the portable artifact. Browser print API.
Mobile label apps — optional emergency tools. Brother iPrint&Label supports wireless models including P900W; Zebra PrintConnect integrates Android apps. Vendor/EULA software, not our open-source/API-first workflow; current app build numbers and exact shop-device compatibility were not verified. They leave the app and fragment templates/audit, so do not make them the normal route. Brother supported apps, Zebra PrintConnect guide.

Recommendation: extend the app's existing printing integration, keep InvenTree templates as the main renderer, and prefer a proven plugin over new transport code. Retain working local adapters only where a plugin cannot match exact hardware, reliability or station behavior. No separate label designer, inventory database or subscription.

Print choices, on the thing's own page¶

All QR paths below use https://home.embeddedera.com/ plus the shown fragment. QR carries identity, never stock quantity, credentials or customer details. Quantity is printed text and a dated snapshot; scanning reads the current record.

Invoice - Laser, Letter paper. Existing invoice number, customer/billing details, issued date, terms/due date, lines, quantities, prices, totals and approved payment/tax wording; optional staff QR #invoice/<order-id>. - Print invoice on #invoice/<id>; selected invoices from the Invoices list. Reuse ee_invoice.html and the existing invoice PDF endpoint. Printing never issues, emails or records payment; preserve the issued artifact for exact reprints.

Packing slip - Laser, Letter proposed; source currently inherits its ERP base page size, so verify before changing. Customer/ship-to, order/shipment reference, shipment date/tracking, actual shipped quantities and serials; no prices. - Print packing slip inside the invoice/order's shipment section, choosing the exact shipment; bulk selected shipments. Reuse ee_packing_slip.html bound to salesordershipment. QR opens #invoice/<order-id>; proposed shipment selection must retain the shipment ID, not aggregate all deliveries.

Part label - Zebra, 50.8 × 38.1 mm. IPN, name, revision/MPN when helpful; QR #part/<part-id>. No changing on-hand total on this permanent part identifier. - Print label on #part/<id> and Parts selection; reuse template 11 in InvenTree, with app QR content.

Stock item label - Zebra, same roll. IPN/name, stock ID, quantity with units, lot or serial, full location/path and printed date; QR #unit/<stock-id> for both serialized and nonserialized items. - Print inventory label on the stock item's #unit/<id> page, part Stock tab and selected Stock rows. Reuse template 9. Expand grouped part/location rows into actual stock IDs; never lose lot distinctions.

Shelf/bin/location label - Zebra, same roll. Large shelf/bin name, parent path and optional purpose; QR #stock?location_id=<id>&cascade=false. - Print location label on the selected location card in #stock; Print this shelf's bin labels and Print stock labels here are separate bulk choices with an explicit include-sublocations switch. Reuse template 10; shelf labels do not print stock totals.

Serial-number board label - PT-P900, TZe 18 mm, 27 mm physical length. Permanent MMYY#### serial and existing board/product identifier; compact serial barcode only if bench tests prove space/readability. Scan/search resolves the permanent serial through existing #serial/<serial> to the unit. Keep readable serial text even if no barcode fits. - First printing remains part of the tester's serial/traceability process; Reprint board label on #unit/<id> and a controlled selected-output action on #build/<id>. Never allocate a new serial when printing. - Reuse the tested station renderer/USB driver initially; evaluate an InvenTree tape template plus Brother plugin only after exact-model and feed/cut proof. The 25 × 25 mm ERP serial template is unsuitable as-is.

Bag label - Zebra, 2 × 1.5 in. Product IPN/name/revision, same permanent serial as the board, quantity (normally 1), optional lot; QR #unit/<stock-id>. - Print bag label on the unit and selected completed build outputs; packing view may select allocated units. Reuse tester content/eligibility rules; express the approved bag layout as an InvenTree stock-item template, then use the chosen Zebra transport. - Do not label failed/quarantined stock as finished goods. Keep quarantine labeling and disabled-by-operator station evidence intact.

Purchase-order receiving label - Zebra, same roll. Stock-label fields plus PO reference, supplier, received quantity/date and lot/date code where supplied; QR #unit/<received-stock-id> (PO remains a related link). - Print received labels on #po/<id> after a successful receipt, per receipt or selected received lines. Reuse/extend template 9 as a receipt variant; bulk resolves resulting stock IDs, including split lots and partial deliveries. Never print ordered quantity as received quantity or receive again to recover a failed print.

Build traveler - Laser, A4 existing template; Letter only after layout proof/owner choice. Build reference, part/revision, target quantity, kit list, existing operation × panel sign-off grid, deviations and closing counts; QR #build/<id>. - Print traveler on #build/<id> and selected Build orders. Reuse ee_work_order_traveler.html; update its ERP-native QR to the app route. Printed sign-offs do not silently complete ERP operations.

Phone to printer: transport choices¶

Option	Fit and tradeoff
App server → ERP template → Zebra LAN	Recommended first slice; already implemented. Phone sends authenticated HTTPS, server sends ZPL to the shop. No phone driver or local-network access needed.
ERP machine/plugin → Zebra LAN	Preferred transport consolidation if sandbox proves compatibility, status handling and container-to-printer reachability. API calls stay behind the app.
App server → CUPS/IPP → laser	Recommended paper path once existing queue is reachable; spooler job ID and status available. Print PDF, not screenshots of app pages.
Existing tester host → USB Brother	Recommended board path initially. For phone reprints, first inspect the station API; add only a narrow authenticated job handoff if none exists. Host must be awake; serialize access with tester printing.
Dedicated Linux USB print host/CUPS	Alternative if the tester host cannot serve jobs reliably. Adds a device/service and USB/driver ownership; defer until exact model works with an existing driver.
Windows host + b-PAC bridge	Conditional fallback when a proven Windows driver is the only reliable match; adds host maintenance and a small app-to-SDK bridge. Not the default.
Phone system print / vendor app	PDF/AirPrint where available, or emergency vendor tool; manual choices and weaker audit. No assumption that the Zebra or USB Brother advertises AirPrint.

Zebra's raw ZPL socket is TCP 9100, not HTTP/IPP; a phone browser cannot send it a PDF directly. Raster conversion at 300 dpi or native ZPL must happen server-side. Keep the printer LAN-only and destinations allowlisted. ZPL commands, default port.

Preview, scanning and reliable reprints¶

One shared in-app Print sheet: object/title, preview, printer/media, quantity shown on each label, number of identical labels, total labels/pages and Confirm. Default one copy; bounded batches with selected count and progress. Keep existing BOX QTY override distinct from inventory labels; printing changes no stock.
Render once for preview and send those same bytes (or verified equivalent printer raster). If record/template changes before Confirm, require refreshed preview. Keep UI inside the app; operating-system Print/Save PDF is an explicit fallback.
Store a protected PDF for every new label/report job, including failures; add equivalent preview for existing direct-ZPL box labels. Label PDF pages match physical dimensions, print at 100%, no fit-to-page. Paper documents select Letter/A4 explicitly. Built-in sheet plugin is an optional laser-label-sheet fallback only with measured matching adhesive stock.
Existing photo scan uses zxing-cpp and recognizes ERP URLs, INV-SI/SL/PA and JSON IDs. Reuse it inside app search; add allowlisted app fragments, serial/build/order routes and permission checks. This integration is proposed, not already working for all new QR types.
Keep old printed labels usable: decode their ERP links in app Scan and route internally. A phone's external camera still opens an old ERP URL unless a deliberate redirect is added later; do not promise new behavior for existing stickers.
Use durable job IDs/idempotency keys and per-printer serialization, including coordination with tester jobs. Snapshot all selected IDs across pagination; validate count/limit rather than silently truncating a shelf or PO.
Audit actor, role, object IDs, template git revision, source snapshot/hash, printer/media, copies, timestamps, spooler/ERP IDs and outcome. Reuse existing audit storage/patterns; print history appears on the object's page. Keep issued invoices and exact-reprint artifacts under the existing document-retention policy; ERP temporary output cleanup is not an archive.
States: Preview → Queued → Sent/Accepted → operator-confirmed output, or Failed/Outcome unknown. TCP acknowledgement and CUPS acceptance are not proof that paper emerged. Never automatically retry an ambiguous send; check the printer and explicitly reprint with reason/original job reference.
Reprint original retains original data; Print current label uses current quantity/location and tells the user to replace the old label. Printed material cannot be undone: cancel only unsent jobs; log spoiled labels/replacements rather than promising Undo after dispatch.
Board tape EE-K-0004 is 27 mm per label, bag label EE-K-0003 is 1 piece; both remain BOM consumables. Printing must not double-consume build allocations. Log extra/rejected media for a separate authorized stock adjustment; never regenerate serials or complete a build as a printing side effect.

Permissions and template ownership¶

Enforce Cloudflare identity and object access on preview, print, PDF download, history and reprint APIs; hidden buttons alone are insufficient. Choose the relevant department ERP token, including for admins; do not turn the engineering “admin” token into an unrestricted service account.
Current label endpoints allow Production/Administration; invoices allow Sales/Administration. Proposed Receiving/Purchasing and Engineering print access requires explicit role mapping through existing People & access. Read-only access does not automatically permit print dispatch; Sales must not gain general stock-edit rights.
Engineering maintains versioned templates/printer profiles in erp-config, with model binding, dimensions, DPI, printable margins, filename pattern and version pins. Administration controls printer destinations; departmental owners approve content. No arbitrary HTML/ZPL/printer address from a phone request.
Use logical template names/config mapping with environment-specific IDs; 9/10/11 are observed IDs, not a portable assumption. Reuse erp-templates deployment under SOP-029; migrate its Zebra paths. Keep secrets and issued customer PDFs out of git.

SOP changes: one procedure, one home¶

This proposal changes no SOP now. Implementation must update these owners, bump versions/dates and add revision history under SOP-000 Document Control; walkthrough precedes active status. Cross-reference steps instead of copying them.

SOP	Sole home / planned change
SOP-003 Stock Locations and Movement	Shared operator print/preview/reprint/recovery procedure for part, stock and location labels; new app entry points, scan compatibility, copies versus quantity.
SOP-002 Part Creation	When to apply a part identifier; link to SOP-003 for printing.
SOP-004 Purchase Orders	Point receipt labeling to SOP-005; do not duplicate receipt/print steps.
SOP-005 Goods Receiving	Choose the actual receipt/stock lots for bulk labels after counting; reference SOP-003 for printing and recovery.
SOP-006 Assembly Builds	Traveler use, station-owned serial assignment, board/bag association and consumables; links to shared printing and existing quarantine handling in SOP-003.
SOP-007 Sales Orders and Invoicing	Print existing invoice versus shipment-specific packing slip; retained issued copy, no print-triggered issuing/sending/payment.
SOP-023 Opening Stock Count	Print after confirmed count; links to SOP-003, no second scan/reprint procedure.
SOP-029 Print Templates	Engineering-only template lifecycle, consolidated git source, plugin/profile compatibility, sandbox proof and rollback.
SOP-009 Personnel Onboarding / SOP-031 Internal Tool Interfaces	Reference approved print roles and object-page UI/gate respectively; do not repeat operator instructions.

Rollout and acceptance¶

Estimates are engineering days, including review/testing/SOP edits, excluding hardware waiting time. No implementation is authorized by this proposal.

Confirm inventory and compatibility — 0.5–1 day. Read actual ERP/plugin versions and configured paper queue; confirm USB host/media; reconcile current templates against git. Compare Zebra plugin with current sender. Exit: documented driver choice, sample dimensions and rollback path.
Smallest useful slice: one shelf + part labels — 1.5–2.5 days. Add Print on location/part, preview/PDF, audit/idempotency and one-shelf bulk selection; consolidate Zebra templates and app QR/legacy scan handling. Use existing sender if plugin reliability remains unproven. Exit: owner prints/scans a bin and part from phone without leaving the app.
Stock and PO receiving — 1–2 days. Stock-item page/bulk, grouped-row expansion, received-lot selection, stale quantity safeguards. Exit: partial receipt and split-lot labels print correctly without duplicate receipt/count mutations.
Paper documents — 1–2 days. Invoice/slip/traveler Print actions, in-app preview and CUPS/IPP submission, protected retained artifacts. Exit: multi-page documents and shipment serials verified on the laser.
Board/bag integration — 2–4 days. Reuse tester printing, add controlled phone reprints and per-printer coordination; test exact USB model before any plugin replacement. Exit: matching board/bag serial, correct cuts and no extra serial/BOM consumption.

Total: 6–11.5 days, plus 1–3 days only if an unsupported Brother needs a new host bridge. Release each accepted slice separately; do not make useful Zebra printing wait for Brother integration.

Use a sandbox branch and sandbox ERP snapshot first; never merge sandbox data back. Mock/deny production printer and mutation endpoints during automated tests. Physical tests use sandbox records visibly marked TEST, a deliberately selected shop printer and a supervised short run.
Test all nine types: long names/IPNs, absent optional fields, serial/lot splits, zero/decimal quantities, multi-page reports, wrong media, cut margins, 300 dpi readability, QR scan after login and denied-role scans/downloads.
Exercise printer off, paper/tape out, hung TCP accepting connections without ~HS, host asleep, render timeout, partial bulk success, double taps and app reconnect. Prove no duplicate job, false physical-success message or hidden auto-retry.
Verify actual-label size with a ruler; scan on owner phones; compare quantities/serials against sandbox records. Test bag/board pairing and station disabled-by-operator behavior; failed/quarantine boards must retain their correct status.
Run focused backend tests plus ~/.local/bin/app-ui-check [worktree] for new sheets/routes on WebKit iPhone 13/SE, keyboard viewport and end-of-page scrolling. Follow app-release and embeddedera-app for release; preserve previous template/profile revision and PDF fallback for rollback.

Remaining risks and questions¶

Confirm Brother host/OS/exact model and whether phone reprints may queue while the tester is busy. Existing USB code proves the intended transport, not today's cable placement.
Verify CUPS availability and laser tray sizes; confirm whether Zebra uses ribbon/thermal-transfer or direct-thermal stock and whether labels survive intended handling. Do not invent a supply MPN.
Quantity/location text becomes stale after stock moves; QR remains identity. Choose whether to offer a replacement-label prompt after an existing successful move/count, without automatic dispatch.
Legacy ERP QR links, expired login, short-lived ERP PDFs and partial print failures need the explicit handling above. Plugin catalogue inclusion is not a compatibility guarantee.
Ask the owner to approve bag wording, role access and first shelf. Template/model context can differ from REST field names; a blank rendered field must fail acceptance when required.

Planning record¶

2026-10-04: Read local app/ERP/template/printer/SOP sources and researched upstream options. Only this proposal was written; no code, installs, printer tests, ERP writes, sync or deployment. notes-sync was deliberately not run because it can change files beyond this note; publication/Waiting-on-you visibility is not claimed. Capacity status was missing; no helper model ran because this route offered no enforceable read-only helper tool scope. Primary Codex performed the investigation locally. - 2026-10-04: Owner approved phase 1-2 (one shelf + part labels), Brother tape deferred, paper -> networked letter printer (Brother MFC-L3780CDW, CUPS on server). Phase 1 checks: InvenTree 1.5.4 (latest 1.5.6), label plugins inventreelabel/labelmachine/labelsheet active, Zebra templates 9/10/11 enabled (50.8x38.1); Zebra 192.168.5.16:9100 'No route to host' at 11:xx Sunday (off?). Phase 2 handed to Codex (high effort) in assistant-sandbox. - 2026-10-04: Phase 2 released in app v2026.10.8 (Codex built, Claude gated: 2136 tests, 437 UI checks). Not yet proven on the real Zebra (printer unreachable Sunday) — first live print with the owner. Next: phase 3 stock + PO receiving labels; phase 4 paper on the networked letter printer.