Skip to content

Scanner Setup

Jump to bottom
0neShot edited this page Sep 9, 2026 · 6 revisions

Hardware Barcode Scanner Setup

This guide explains how to configure physical 2D barcode scanners to transmit ANSI MH10.8.2 / ISO/IEC 15434 DataMatrix barcodes into InvenTree without data loss, how SmartParts captures keystroke wedge bursts, and how native InvenTree barcode discrimination and context-aware panel suppression operate.

⚠️ The Keyboard Wedge Challenge

When scanning component packaging from distributors (Mouser, DigiKey, LCSC, element14, TME) or semiconductor reels (Texas Instruments, STMicroelectronics, Microchip), data fields (MPN, Quantity, Batch, Supplier SKU) are delimited by an invisible ASCII control character: the Group Separator (GS), represented as \x1D (ASCII 29).

The Problem with Default Scanner Modes

By default, most handheld 2D barcode scanners (e.g., Netum L8BL Pro, Zebra DS2208, Honeywell Xenon) operate in USB Keyboard Emulation (HID Wedge) mode. Because \x1D is an invisible non-printable control character, standard operating systems (Windows, macOS, Linux) swallow it entirely.

Without delimiters, a barcode containing:

[)>06 1PSTM32F103C8T6 Q10 1T2134 30PMSR123

Arrives at the host browser as an unbroken string:

[)>061PSTM32F103C8T6Q101T213430PMSR123

While SmartParts includes a fallback heuristic parser capable of isolating strong prefix boundaries (1P, Q, 1T, 30P), configuring hardware character replacement ensures instant, 100% deterministic parsing.

🔧 The Solution: Character Replacement

Configure your physical scanner firmware to intercept the invisible \x1D character internally and convert it into a printable character before transmitting keystrokes over USB or Bluetooth.

SmartParts natively supports the Tilde (~) as the standard replacement for the Group Separator.

📋 Step-by-Step Configuration

Netum Scanners (L8BL Pro, DS7500, etc.)

  1. Refer to the official Netum Edit - Replace Plugin Documentation.
  2. Scan the setup barcode to enter Program Mode.
  3. Scan the barcode to enable the Character Replace feature.
  4. Set the replacement rule:
    • Target Character (HEX): 1D (Invisible ASCII Group Separator)
    • Replacement Character (HEX): 7E (Printable ASCII Tilde ~)
  5. Scan the Save & Exit barcode on your scanner programming card.

Zebra / Symbol Scanners (DS2208, DS3608, DS8108)

  1. Open Zebra 123Scan on your workstation.
  2. Create or modify a configuration profile for your scanner model.
  3. In Modify Data > Advanced Data Formatting (ADF), add an action:
    • Replace String: \x1D with ~
  4. Load the configuration profile onto the scanner via USB or print the generated programming barcode sheet.

Honeywell Scanners (Xenon 1900, Voyager 1400g)

  1. Open Honeywell EZConfig for Scanning.
  2. Navigate to Data Formatting > Format Editor.
  3. Create a replacement rule replacing ASCII character 29 (0x1D) with ASCII character 126 (0x7E, ~).
  4. Save and transmit to the scanner.

Datalogic Scanners (Gryphon, QuickScan)

  1. Open Datalogic Aladdin.
  2. Navigate to Data Editing > Character Replacement.
  3. Map character 0x1D to 0x7E.
  4. Apply the configuration.

🧪 Verifying Scanner Configuration

Verify your hardware setup directly inside SmartParts without opening an external serial terminal:

  1. In InvenTree, navigate to SmartParts Dashboard (/plugin/smartparts/).
  2. Open API Settings > Scanner Diagnostics.
  3. Scan a component label or distributor reel barcode.
  4. Confirm that tilde (~) delimiters appear between vendor fields: 
    [)>06~1PSTM32F103C8T6~Q10~1T2134~30PMSR123
  5. When verified, SmartParts' stage-1 ANSI parser extracts MPN, quantity, batch, and SKU instantaneously.

🌐 Global UI Scanner Wedge (scanner_global.js)

SmartParts injects a global hardware scanner wedge listener into the InvenTree web frontend (/web/...). Users can scan barcodes from any page (part details, stock views, purchase orders, dashboards, or settings) without clicking an input field or opening a modal first.

1. Keystroke Burst Detection & Active Field Protection

Hardware scanners transmit characters at rates far exceeding human typing speeds:

  • Inter-Key Threshold (MAX_INTER_KEY_MS): Keystrokes occurring less than 50ms apart are flagged as scanner activity.
  • Burst Ratio Gate: At least 80% of keystroke intervals in a sequence must be < 50ms.
  • Minimum Scan Length (MIN_SCAN_LENGTH): Minimum 4 characters before evaluation.
  • Termination: Scans complete when the scanner emits a carriage return / enter (Enter).
  • Idle Timeout (IDLE_RESET_MS): A pause of 600ms resets the internal buffer if a scan was interrupted.
  • Active Input Element Protection: If the user has cursor focus in an <input> or <textarea> when a barcode is scanned, scanner_global.js snapshots the field's initial content and restores it once the scan is recognized. This prevents high-speed barcode characters from corrupting forms.

2. Native InvenTree Barcode Discrimination

When internal InvenTree barcodes or QR codes are scanned, SmartParts discriminates internal database objects from distributor MPNs. Internal payloads are routed immediately to the native React UI without opening the SmartParts part creation wizard:

Payload Format Internal Object Navigation Route
{"stocklocation": <id>} or INV-SL<id> Stock Location /web/stock/location/<id>/
{"stockitem": <id>} or INV-SI<id> Stock Item /web/stock/item/<id>/
{"part": <id>} or INV-PA<id> Internal Part /web/part/<id>/
{"purchaseorder": <id>} or {"purchase_order": <id>} Purchase Order /web/purchasing/purchase-order/<id>/
{"build": <id>} or {"build_order": <id>} Manufacturing Build Order /web/manufacturing/build-order/<id>/
{"salesorder": <id>} or {"sales_order": <id>} Sales Order /web/sales/sales-order/<id>/
{"returnorder": <id>} or {"return_order": <id>} Return Order /web/sales/return-order/<id>/
{"supplierpart": <id>} or {"supplier_part": <id>} Supplier Part /web/purchasing/supplier-part/<id>/
{"manufacturerpart": <id>} or {"manufacturer_part": <id>} Manufacturer Part /web/part/manufacturer-part/<id>/

Important

Internal Payload Protection: Any payload formatted with internal JSON keys ({"purchaseorder": ...}, {"stocklocation": ...}) or INV- short codes is strictly classified as internal. If the referenced object has been deleted or cannot be found, an informational warning toast is displayed. Under no circumstances will SmartParts attempt to look up or create an internal JSON string as a component MPN.

3. Context-Aware Modal Suppression

When scanning distributor component packaging (Mouser, DigiKey, etc.):

  • On General InvenTree Pages: If the component exists in InvenTree, the user is navigated directly to /web/part/<id>/. If unknown, a confirmation modal appears prompting to import the part via SmartParts.
  • On SmartParts Pages & Panels (isSmartPartsActive()): When already viewing the SmartParts Dashboard (/plugin/smartparts/) or an embedded panel (#sp-root, data-smartparts-panel, #searchForm), the global redirect/modal prompt is completely suppressed. The scanned MPN is forwarded directly to the active panel's search input (#sp-mpn) or search function (_smartparts_panel_search(mpn)), initiating lookup without intrusive popups.

4. Coexistence with PureScan Terminal & Local Scanners

  • PureScan Terminal Exclusion: On the dedicated kiosk route (/plugin/smartparts/purescan/), scanner_global.js yields immediately, allowing PureScan's zero-click terminal engine to take exclusive control.
  • Event Deduplication: Events flagged with e._handledBySmartParts = true or window._smartparts_local_scanner_active = true are bypassed by the global listener to prevent double-processing.

Next Steps

Clone this wiki locally