Build Your Own 2D Bar Code Key Emulator: Hardware & Software WalkthroughA 2D bar code key emulator reads, interprets, and reproduces the behavior of a 2D barcode-based access credential (such as a QR-code ticket or pass) and presents equivalent data to an access control system. Building your own 2D Bar Code Key Emulator is a useful learning project for understanding barcode encoding, secure credential storage, and device interfacing. This article walks through hardware selection, software design, barcode decoding/encoding, emulation strategies, security considerations, and practical examples.
Who this is for
This walkthrough is intended for hobbyists, makers, and security researchers with intermediate skills in embedded systems and programming. You should be comfortable with a microcontroller, basic electronics, and a language such as Python, C, or C++. Do not use this knowledge to bypass security or violate terms of service — emulate only credentials you own or have explicit permission to emulate.
Overview of components and workflow
A 2D bar code key emulator typically involves three core components:
- A barcode input method (camera or file).
- Processing hardware/software to decode and re-encode barcodes and manage credentials.
- An output or presentation method to emulate the credential to the target reader (e.g., display, printed barcode, or interfaced HID emulation).
Common workflows:
- Acquire the barcode (scan camera, import image, or capture from an electronic pass).
- Decode the 2D barcode to extract payload data and any metadata (format, error correction, version).
- Optionally parse, store, and transform payload data (e.g., apply cryptographic signing if the system expects it).
- Present the credential in an acceptable form (display on screen, print, or send via an interface like USB HID, BLE, or NFC if the reader supports such methods).
Hardware options
Choose hardware based on how you plan to present the credential and on portability needs.
- Smartphone or Tablet
- Pros: Built-in camera, display, network, and GPU acceleration for decoding.
- Cons: Limited ability to present alternative physical interfaces (unless using screen or Bluetooth).
- Single-board computers (Raspberry Pi, Odroid)
- Pros: Flexible I/O (GPIO, USB, BLE), full Linux stack, camera support.
- Cons: Larger footprint, higher power use than microcontrollers.
- Microcontrollers with Camera + Display (ESP32-S3, Raspberry Pi Pico + camera modules)
- Pros: Small, low power; can act as USB HID if supported.
- Cons: Limited processing power for heavy decoding tasks; more development effort.
- USB HID / Programmable Keyboards (Teensy, Arduino Leonardo)
- Use for presenting decoded payloads as keyboard input (if access system accepts pasted codes).
- Pros: Simple emulation of keyboard input, low-cost.
- Cons: May not match scanner expectations; not suitable for optical-only systems.
- Dedicated e-ink or OLED display + battery
- Useful when the emulator must show a barcode visually to a scanner.
Hardware recommendation for most hobbyist builds:
- Raspberry Pi 4 or Raspberry Pi Zero 2 W (for camera, display, and BLE/USB options).
- Pi Camera Module or a USB camera.
- Small touchscreen or e-ink display for presenting the barcode visually.
- Optional: USB-C power bank for portability.
Software stack
Primary responsibilities:
- Barcode decoding/encoding (supporting QR, Data Matrix, Aztec, etc.).
- Credential management (secure local storage, versioning).
- Presentation layer (rendering barcode images, emulating HID/BLE/NFC as needed).
- Optional: cryptographic operations (HMAC, RSA/ECC verification, token renewal).
Suggested languages/libraries:
- Python: zxing, pyzbar, Pillow, qrcode, OpenCV
- C/C++: libzbar, ZXing-C++, OpenCV
- JavaScript (Node.js / Electron): node-zxing, qr-image, jsQR (for web-based GUI)
- For Raspberry Pi: use Python with OpenCV and pyzbar for fast prototyping.
Example Python libraries:
- pyzbar — simple wrapper for zbar for decoding barcodes from images.
- qrcode or segno — generate QR codes.
- Pillow — image handling.
- OpenCV — camera frame capture, pre-processing (thresholding, perspective transform) for better decoding results.
Decoding barcodes: practical steps
- Capture image from camera or load file.
- Preprocess:
- Convert to grayscale.
- Apply adaptive thresholding or contrast enhancement.
- Correct perspective if the barcode is skewed (detect quadrilateral corners).
- Resize to improve decoder success rate.
- Decode with a library (pyzbar, ZXing).
- Verify payload format and structure.
Example Python decoding flow (conceptual):
import cv2 from pyzbar.pyzbar import decode from PIL import Image img = cv2.imread('scan.jpg') gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # optional preprocessing... pil_img = Image.fromarray(gray) decoded = decode(pil_img) for d in decoded: print(d.type, d.data.decode('utf-8')) Encoding / rendering barcodes
When presenting the credential visually, generate a barcode image that matches the reader’s expected format and quality:
- Match error correction levels (e.g., QR L/M/Q/H).
- Match size and quiet zone (margin) requirements.
- Use high-contrast (black on white) and sufficient resolution for the reader’s optics.
Example generation with segno (Python):
import segno qr = segno.make('your-payload-here', error='h') qr.save('out.png', scale=10, border=4) For displays, convert the generated PNG to the display’s required format and resolution. For e-ink screens, consider dithering for better contrast.
Emulation strategies
- Visual Display Emulation
- Render barcode on screen or e-ink and present it to an optical scanner.
- Best when target system uses cameras or laser scanners expecting a printed barcode.
- USB HID Keyboard Emulation
- Emulate keyboard and send the decoded payload as keystrokes to the host system (useful for systems that accept manual entry).
- Often implemented with microcontrollers that support USB HID (Teensy, Arduino Leonardo, Raspberry Pi Pico USB).
- Network/Socket Emulation
- For systems that accept remote authentication via API, send payload over network with proper protocol.
- BLE (Bluetooth Low Energy) Emulation
- Some modern readers accept credentials via BLE GATT profiles. Implement a GATT server that provides the credential when requested.
- NFC / Smartcard Emulation
- If the credential system is based on NFC or smartcards (and the payload is simply a token), use a device that supports card emulation (some smartphones and specialized hardware). Note: NFC emulation has legal and security implications.
Choose the method that best matches the target reader’s expected input.
Credential lifecycle and security
Even for benign testing, treat credentials with care.
- Store secrets encrypted at rest (AES-256 using a local key derived from a passphrase).
- Protect access to emulator controls with authentication.
- Implement secure deletion and audit logs if you’ll track usage.
- Respect replay protections: many modern systems use time-based or single-use tokens. Emulation must handle token refresh or fail gracefully.
- Avoid sharing or publishing real credential payloads; redact or use sample/test tokens.
Example of simple local encryption (Python, cryptography library):
from cryptography.fernet import Fernet key = Fernet.generate_key() f = Fernet(key) token = f.encrypt(b'my-secret-payload') Example project: Raspberry Pi QR Emulator (visual + HID fallback)
Materials:
- Raspberry Pi 4 or Zero 2 W
- Pi Camera or USB camera
- 3.5” TFT or e-ink display
- MicroSD card with Raspberry Pi OS
- Optional: USB HID-capable microcontroller for keyboard emulation
High-level steps:
- Set up Raspberry Pi OS and enable camera support.
- Install Python dependencies: opencv-python, pyzbar, segno, pillow.
- Build a GUI (Tkinter, PyQt, or simple fullscreen browser with a local web app) to manage credentials and display barcodes.
- Implement a decoder module to import and verify existing barcodes.
- Implement a generator module to render barcodes with configurable size and error correction.
- Add a toggle to present as visual barcode or send as simulated keystrokes (HID) to a connected host via USB gadget mode (Pi Zero can do USB gadget emulation).
- Add optional encryption for stored credentials and a PIN to unlock the app.
Sample flow for presenting a code:
- User selects a credential from the GUI, authenticates with PIN.
- App renders rendered barcode at full-screen with recommended margins.
- If visual scan fails, toggle to HID mode to send payload as keyboard input.
Troubleshooting tips
- Reader rejects visual barcode: increase scale, reduce glare, improve contrast, ensure correct quiet zone.
- Decoding fails on camera: use more light, reduce motion blur, apply image preprocessing (bilateral filter, adaptive threshold).
- HID input not accepted: check device enumeration, correct keyboard layout, add delay between keystrokes.
- Tokens expire: check whether credential uses timestamps or one-time codes; implement refresh flow or accept that replay won’t work.
Legal and ethical note
Emulating access credentials may violate laws, terms of service, or allow unauthorized access. Only emulate barcodes and credentials you own or have explicit permission to use. Use this knowledge for legitimate testing, education, or system integration.
Further enhancements and ideas
- Integrate with hardware secure element (e.g., ATECC608A) for safe key storage and signing.
- Add camera-based live-preview with alignment guides to help users position physical passes for copying.
- Implement a token refresh client for services using OAuth-like flows or time-based codes.
- Support multiple barcode formats and automatic format detection.
- Add logging and removable audit export for compliance testing.
This walkthrough provides a complete roadmap: choose appropriate hardware, use reliable decoding/encoding libraries, implement secure storage and presentation options, and test carefully against target readers.
Leave a Reply