Node-RED USB Barcode Scanner

A Node-RED node for reading barcodes and QR codes from USB scanner devices using TLV (Type-Length-Value) protocol communication.

Features

• ✅ Automatic USB device detection and connection
• ✅ Real-time barcode/QR code scanning
• ✅ TLV protocol support with CRC verification
• ✅ Configurable USB Vendor ID and Product ID
• ✅ Visual status indicators
• ✅ Error handling and logging
• ✅ Clean disconnect on Node-RED shutdown

Installation

Prerequisites

Make sure you have the required system dependencies for USB communication:

Linux/Ubuntu:

sudo apt-get install libusb-1.0-0-dev libudev-dev

macOS:

brew install libusb

Windows:

• Install Windows Build Tools
• May require driver installation for your specific USB device

Install the Node

1. Via Node-RED Palette Manager:

   • Go to Menu → Manage Palette → Install
   • Search for node-red-contrib-usb-barcode-scanner
   • Click Install

2. Via npm (in your Node-RED directory):

   npm install node-red-contrib-usb-barcode-scanner

3. Manual Installation:

   • Copy the node files to your Node-RED user directory
   • Install dependencies: npm install usb
   • Restart Node-RED

Usage

1. Drag and Drop: Add the "barcode scanner" node from the input category to your flow

2. Configure: Double-click the node to configure:

   • Name: Optional descriptive name
   • Vendor ID: USB Vendor ID (default: 1317 for 0x0525)
   • Product ID: USB Product ID (default: 42156 for 0xA4AC)

3. Connect: Wire the output to other nodes to process scanned data

4. Deploy: Deploy your flow and start scanning!

Output Format

When a barcode or QR code is scanned, the node outputs a message with this structure:

{
  "payload": {
    "data": "1234567890123",           // Scanned content as string
    "cmd": "A6",                       // Command byte from device
    "result": "00",                    // Result byte (00 = success)
    "raw": "55AAA6001000...",          // Raw hex data received
    "timestamp": "2025-08-27T10:30:45.123Z"  // Scan timestamp
  }
}

Status Indicators

The node shows its current status through colored indicators:

• 🟢 Green dot: Scanner connected and ready
• 🔵 Blue dot: Processing scanned data
• 🔴 Red ring: Error occurred (check debug log)
• ⚪ Grey ring: Scanner disconnected

Example Flow

[
  {
    "id": "scanner1",
    "type": "barcode-scanner",
    "name": "My Scanner",
    "vid": "1317",
    "pid": "42156",
    "wires": [["debug1"]]
  },
  {
    "id": "debug1",
    "type": "debug",
    "name": "",
    "active": true,
    "tosidebar": true,
    "console": false,
    "complete": "payload",
    "wires": []
  }
]

Troubleshooting

Device Not Found

• Verify the USB device is connected
• Check Vendor ID and Product ID are correct
• On Linux, you may need udev rules for device permissions

Permission Denied

• On Linux/macOS, run Node-RED with sudo or configure proper udev rules
• Add your user to the appropriate groups (dialout, plugdev)

Multiple Devices

• The node will error if multiple matching devices are found
• Disconnect unnecessary devices or modify the code to handle device selection

CRC Verification Failed

• This indicates corrupted data transmission
• Check USB cable connection
• Verify the TLV protocol implementation matches your device

Udev Rules (Linux)

Create /etc/udev/rules.d/99-barcode-scanner.rules:

# USB Barcode Scanner
SUBSYSTEM=="usb", ATTRS{idVendor}=="0525", ATTRS{idProduct}=="a4ac", MODE="0666", GROUP="plugdev"

Then reload udev rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Development

File Structure

├── barcode-scanner.js      # Main node implementation
├── barcode-scanner.html    # Node configuration UI
├── package.json           # Node package definition
└── README.md             # This file

Key Components

• USB Communication: Uses the usb npm package for low-level USB access
• TLV Protocol: Implements parsing for Type-Length-Value formatted data
• CRC Verification: Validates data integrity with XOR checksum
• Node-RED Integration: Follows Node-RED node development standards

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Create an issue on GitHub for bugs or feature requests
• Check Node-RED community forums for general help
• Ensure your USB device uses compatible TLV protocol

Note: This node is designed for USB barcode scanners that communicate using the TLV protocol as implemented in the source files. It may need modifications for different scanner protocols or communication methods.