# QR Code Scanner
A Python library for reading QR codes from both HID (Human Interface Device) scanners and Serial devices. This library supports multiple connection types to accommodate different QR code scanner configurations.
## Features
- **HID Support**: Treats QR code scanners as keyboard input devices and decodes their scanned data
- **Serial Support**: Direct serial communication for devices that output raw text data
- Support for multiple keyboard layouts (HID mode)
- Automatic character decoding
- Robust error handling
- Non-blocking and blocking read operations
- Device discovery utilities
## Installation
Install using pip:
```bash
pip install qrcode-scanner
```
Or using Poetry:
```bash
poetry add qrcode-scanner
```
## Requirements
- Python 3.10+
- hidapi (for HID devices)
- pyserial (for Serial devices)
## Quick Start
### HID Scanner Usage
```python
from qrcode_scanner import HIDScanner
from qrcode_scanner.exceptions import DeviceConnectionError, DeviceNotFoundError, DeviceReadError
# Replace with your device's vendor ID and product ID
VENDOR_ID = 0x1D82
PRODUCT_ID = 0x5CA0
try:
# Initialize and connect to the scanner
scanner = HIDScanner(vendor_id=VENDOR_ID, product_id=PRODUCT_ID)
scanner.connect()
print("Connected to device")
print("Manufacturer:", scanner.device.get_manufacturer_string())
print("Product:", scanner.device.get_product_string())
# Start reading QR codes
while True:
try:
print("Listening for scans...")
scanned_text = scanner.read() # Blocking read operation
if scanned_text:
print("=== SCAN COMPLETE ===")
print("Scanned text:", scanned_text)
except DeviceNotFoundError:
print("Device not found or not connected")
break
except (DeviceReadError, DeviceConnectionError) as e:
print(f"Device error: {e}")
break
except KeyboardInterrupt:
print("Program terminated by user")
finally:
scanner.close()
print("HID device closed")
```
### Serial Scanner Usage
```python
from qrcode_scanner import SerialScanner, serial_ports
from qrcode_scanner.exceptions import DeviceConnectionError, DeviceNotConnectedError
# List available serial ports
print("Available serial ports:")
ports = serial_ports()
for port in ports:
print(f" - {port}")
# Configure the serial connection
port = "/dev/ttyACM0" # Adjust for your system (Windows: "COM3", etc.)
baudrate = 9600
try:
# Create and connect to the serial scanner
scanner = SerialScanner(
port=port,
baudrate=baudrate,
timeout=1 # timeout in seconds
)
scanner.connect()
print(f"Connected to serial device on {port}")
while True:
print("Waiting for data...")
try:
# Read data from the scanner (blocking call)
scanned_text = scanner.read()
if scanned_text:
print("=== SCAN COMPLETE ===")
print("Scanned text:", scanned_text)
else:
print("No data received (timeout)")
except DeviceNotConnectedError:
print("Device not connected")
break
except DeviceConnectionError as e:
print(f"Device connection error: {e}")
break
except KeyboardInterrupt:
print("Program terminated by user")
except DeviceConnectionError as e:
print(f"Failed to connect to serial device: {e}")
finally:
scanner.close()
print("Serial device closed")
```
## Serial Scanner Configuration
The `SerialScanner` class supports various configuration options:
```python
scanner = SerialScanner(
port="/dev/ttyACM0", # Serial port
baudrate=9600, # Baud rate (default: 9600)
parity=serial.PARITY_NONE, # Parity (default: NONE)
stopbits=serial.STOPBITS_ONE, # Stop bits (default: 1)
bytesize=serial.EIGHTBITS, # Byte size (default: 8)
timeout=1 # Read timeout in seconds (default: 1)
)
```
Common baud rates for QR scanners: 9600, 19200, 38400, 115200
## Error Handling
The library includes several exception classes to handle different error scenarios:
- `DeviceNotFoundError`: When the specified device cannot be found
- `DeviceConnectionError`: When there are issues connecting to the device
- `DeviceNotConnectedError`: When trying to read from a disconnected device
- `DeviceReadError`: When reading from the device fails
- `UnknownCharacterError`: When encountering unknown character codes (HID only)
## Device Discovery
### Finding HID Device IDs
To find your HID device's vendor and product IDs:
```python
from qrcode_scanner import devices
# List all connected HID devices
for device in devices():
print(f"Vendor ID: 0x{device['vendor_id']:04X}")
print(f"Product ID: 0x{device['product_id']:04X}")
print(f"Product Name: {device.get('product_string', 'N/A')}")
print("---")
```
### Finding Serial Ports
To discover available serial ports:
```python
from qrcode_scanner import serial_ports
# List all available serial ports
ports = serial_ports()
for port in ports:
print(f"Available port: {port}")
```
## Choosing Between HID and Serial
**Use HID Scanner when:**
- Your QR scanner emulates a keyboard
- Scanner appears as an HID device in your system
- You need to decode keyboard scan codes
**Use Serial Scanner when:**
- Your QR scanner outputs raw text data over serial
- Scanner connects via USB-to-Serial adapter
- Device sends complete text strings followed by newline characters
- You want simpler, more direct communication
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/medram/qrcode-scanner",
"name": "qrcode-scanner",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "Qr Code, qr code scanner, hid, usb qr code scanner, qrcode scanner, hidapi",
"author": "medram",
"author_email": "mramouchy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/52/da/3b362e8f2327fea1f3975e59c9c0d0bb51de4a7ac3b8b59a61020540da7c/qrcode_scanner-0.0.4.tar.gz",
"platform": null,
"description": "# QR Code Scanner\n\nA Python library for reading QR codes from both HID (Human Interface Device) scanners and Serial devices. This library supports multiple connection types to accommodate different QR code scanner configurations.\n\n## Features\n\n- **HID Support**: Treats QR code scanners as keyboard input devices and decodes their scanned data\n- **Serial Support**: Direct serial communication for devices that output raw text data\n- Support for multiple keyboard layouts (HID mode)\n- Automatic character decoding\n- Robust error handling\n- Non-blocking and blocking read operations\n- Device discovery utilities\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install qrcode-scanner\n```\n\nOr using Poetry:\n\n```bash\npoetry add qrcode-scanner\n```\n\n## Requirements\n\n- Python 3.10+\n- hidapi (for HID devices)\n- pyserial (for Serial devices)\n\n## Quick Start\n\n### HID Scanner Usage\n\n```python\nfrom qrcode_scanner import HIDScanner\nfrom qrcode_scanner.exceptions import DeviceConnectionError, DeviceNotFoundError, DeviceReadError\n\n# Replace with your device's vendor ID and product ID\nVENDOR_ID = 0x1D82\nPRODUCT_ID = 0x5CA0\n\ntry:\n # Initialize and connect to the scanner\n scanner = HIDScanner(vendor_id=VENDOR_ID, product_id=PRODUCT_ID)\n scanner.connect()\n\n print(\"Connected to device\")\n print(\"Manufacturer:\", scanner.device.get_manufacturer_string())\n print(\"Product:\", scanner.device.get_product_string())\n\n # Start reading QR codes\n while True:\n try:\n print(\"Listening for scans...\")\n scanned_text = scanner.read() # Blocking read operation\n if scanned_text:\n print(\"=== SCAN COMPLETE ===\")\n print(\"Scanned text:\", scanned_text)\n except DeviceNotFoundError:\n print(\"Device not found or not connected\")\n break\n except (DeviceReadError, DeviceConnectionError) as e:\n print(f\"Device error: {e}\")\n break\n\nexcept KeyboardInterrupt:\n print(\"Program terminated by user\")\nfinally:\n scanner.close()\n print(\"HID device closed\")\n```\n\n### Serial Scanner Usage\n\n```python\nfrom qrcode_scanner import SerialScanner, serial_ports\nfrom qrcode_scanner.exceptions import DeviceConnectionError, DeviceNotConnectedError\n\n# List available serial ports\nprint(\"Available serial ports:\")\nports = serial_ports()\nfor port in ports:\n print(f\" - {port}\")\n\n# Configure the serial connection\nport = \"/dev/ttyACM0\" # Adjust for your system (Windows: \"COM3\", etc.)\nbaudrate = 9600\n\ntry:\n # Create and connect to the serial scanner\n scanner = SerialScanner(\n port=port,\n baudrate=baudrate,\n timeout=1 # timeout in seconds\n )\n\n scanner.connect()\n print(f\"Connected to serial device on {port}\")\n\n while True:\n print(\"Waiting for data...\")\n try:\n # Read data from the scanner (blocking call)\n scanned_text = scanner.read()\n if scanned_text:\n print(\"=== SCAN COMPLETE ===\")\n print(\"Scanned text:\", scanned_text)\n else:\n print(\"No data received (timeout)\")\n except DeviceNotConnectedError:\n print(\"Device not connected\")\n break\n except DeviceConnectionError as e:\n print(f\"Device connection error: {e}\")\n break\n\nexcept KeyboardInterrupt:\n print(\"Program terminated by user\")\nexcept DeviceConnectionError as e:\n print(f\"Failed to connect to serial device: {e}\")\nfinally:\n scanner.close()\n print(\"Serial device closed\")\n```\n\n## Serial Scanner Configuration\n\nThe `SerialScanner` class supports various configuration options:\n\n```python\nscanner = SerialScanner(\n port=\"/dev/ttyACM0\", # Serial port\n baudrate=9600, # Baud rate (default: 9600)\n parity=serial.PARITY_NONE, # Parity (default: NONE)\n stopbits=serial.STOPBITS_ONE, # Stop bits (default: 1)\n bytesize=serial.EIGHTBITS, # Byte size (default: 8)\n timeout=1 # Read timeout in seconds (default: 1)\n)\n```\n\nCommon baud rates for QR scanners: 9600, 19200, 38400, 115200\n\n## Error Handling\n\nThe library includes several exception classes to handle different error scenarios:\n\n- `DeviceNotFoundError`: When the specified device cannot be found\n- `DeviceConnectionError`: When there are issues connecting to the device\n- `DeviceNotConnectedError`: When trying to read from a disconnected device\n- `DeviceReadError`: When reading from the device fails\n- `UnknownCharacterError`: When encountering unknown character codes (HID only)\n\n## Device Discovery\n\n### Finding HID Device IDs\n\nTo find your HID device's vendor and product IDs:\n\n```python\nfrom qrcode_scanner import devices\n\n# List all connected HID devices\nfor device in devices():\n print(f\"Vendor ID: 0x{device['vendor_id']:04X}\")\n print(f\"Product ID: 0x{device['product_id']:04X}\")\n print(f\"Product Name: {device.get('product_string', 'N/A')}\")\n print(\"---\")\n```\n\n### Finding Serial Ports\n\nTo discover available serial ports:\n\n```python\nfrom qrcode_scanner import serial_ports\n\n# List all available serial ports\nports = serial_ports()\nfor port in ports:\n print(f\"Available port: {port}\")\n```\n\n## Choosing Between HID and Serial\n\n**Use HID Scanner when:**\n\n- Your QR scanner emulates a keyboard\n- Scanner appears as an HID device in your system\n- You need to decode keyboard scan codes\n\n**Use Serial Scanner when:**\n\n- Your QR scanner outputs raw text data over serial\n- Scanner connects via USB-to-Serial adapter\n- Device sends complete text strings followed by newline characters\n- You want simpler, more direct communication\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Read QR codes from HID devices",
"version": "0.0.4",
"project_urls": {
"Documentation": "https://github.com/medram/qrcode-scanner",
"Homepage": "https://github.com/medram/qrcode-scanner",
"Repository": "https://github.com/medram/qrcode-scanner"
},
"split_keywords": [
"qr code",
" qr code scanner",
" hid",
" usb qr code scanner",
" qrcode scanner",
" hidapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ca205a849bf2f93063f51e2f557efc8ebf15c95d1ad51ed6c1d5ef6d1123409",
"md5": "0958a97fc614309e54b082d693fd1075",
"sha256": "d19fd6934d8d7079eb1e806ae4a3cc983eb5deca24678f5498ebc426cb67d4ab"
},
"downloads": -1,
"filename": "qrcode_scanner-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0958a97fc614309e54b082d693fd1075",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5908,
"upload_time": "2025-07-09T17:14:34",
"upload_time_iso_8601": "2025-07-09T17:14:34.337210Z",
"url": "https://files.pythonhosted.org/packages/4c/a2/05a849bf2f93063f51e2f557efc8ebf15c95d1ad51ed6c1d5ef6d1123409/qrcode_scanner-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "52da3b362e8f2327fea1f3975e59c9c0d0bb51de4a7ac3b8b59a61020540da7c",
"md5": "c5de1491d96771f39712583f2da50ca8",
"sha256": "a4799e04f19672b6dfd6d07fbbc4aacd5dcce1ea2f68a4e21a7af2f99a67c821"
},
"downloads": -1,
"filename": "qrcode_scanner-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "c5de1491d96771f39712583f2da50ca8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 5223,
"upload_time": "2025-07-09T17:14:35",
"upload_time_iso_8601": "2025-07-09T17:14:35.787829Z",
"url": "https://files.pythonhosted.org/packages/52/da/3b362e8f2327fea1f3975e59c9c0d0bb51de4a7ac3b8b59a61020540da7c/qrcode_scanner-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 17:14:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "medram",
"github_project": "qrcode-scanner",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "qrcode-scanner"
}
JSON
