onScan.js - hardware barcode and RFID scanners in web apps

• Introduction
• Online-Demo
• Quick-Start
• Setting up the scanner
• API-Documentation

Introduction

Most barcode and RFID scanners connected via USB or Bluetooth or built into mobile devices work like external keyboards. They simply "type" whatever they scan. This makes them easy to use with just about any application without any special drivers, connectors, etc. On the other hand, there is no way to react to scans specifically - it's just typed input.

onScan.js allows Javascript code to distinguish between regular typing and scan input. It measures typing speed, looks for prefix and suffix characters, that are often sent by scanners along with the data, etc. If a scan is detected, onScan.js fires a custom DOM event called scan.

Online Demo

Use the onScan.js playground to test your scanner with various configuration options. 

Quick Start

1. Install via npm install onscan.js or bower install onscan-js or clone the official GitHub repo.
2. Include onscan.min.js in your script
3. Add the following initialization script anywhere, where it will be run when the page loads (e.g. at the end of your other JavaScript includes)
4. Play around with the options in the playground.

// Enable scan events for the entire document
onScan.attachTo(document);
// Register event listener
document.addEventListener('scan', function(sScancode, iQuatity) {
    alert(iQuantity + 'x ' + sScancode); 
});

Refer to the documentation for a detailed description of settings, events and methods available.

Setting up your scanner

onScan.js has two operating modes: collecting typed input from a scanner emulating a keyboard (typical for USB an Bluetooth-Scanners) and listening to paste-events (a common operation mode of scanners built into mobile devices). In both cases, the library produces identical scan-events, so all you need to do is set it up according to the way your scanner works.

Bluetooth and USB-scanners

External scanners mostly have two operating modes: HID-mode (emulating a keyboard) and serial-mode (emulating a serial interface like good old COM-connectors).

You will need HID-mode for onScan.js to work. Refer to the documentation of your scanner for instructions. USB scanners mostly use HID-mode by default.

Built-in scanners

Imagers built into mobile devices mostly work in HID-mode only - they can be used with onScan.js right away. However, many of them support two different operation styles - often referred to as keyboard-wedge (keyboard emulation) and clipboard (pasting all scanned data at once). onScan.js can be configured to work with both of them by setting reactToKeydown and reactToPaste respectively.

Also note, that the hardware key used to trigger scanning often has it's own key code (typically an F-key like F11 or similar). onScan.js needs to know this key code: on one the hand, it must be filtered away in the data, on the other hand it can be used to hook secondary actions to long pressing the scan button - a very handy feature!

RFID scanners

The majority of Bluetooth RFID scanners also support HID-mode and, thus, can be used with onScan.js. However, they can scan multiple tags (= codes) at a time, so it is important to have a delimiting character - e.g. enter, comma, semicolon or similar.

Prefix and suffix characters

Most scanners can be configured to send prefix and suffix characters with every scanned code. onScan.js does not have any special requirements here, but if you do use a prefix or a suffix, you must configure the respective options in onScan.js to make sure, they are not treated as part of the scanned code.

Generally speaking, it is a good idea to have a suffix following the code to make sure multiple codes scanned in sequence can be held apart reliably. This is really important for RFID scanners, as noted above, but it also makes sense for fast barcode scanners.

Finding the correct settings

The easiest way to find out, how to configure onScan.js to work best with your scanner is to play around with the settings in the playground. Activate the callback onKeyDetect to see every keycode detected by the library - this will help you to find prefix and suffix characters, as well as button keycodes for built-in scanners. The following table shows typical settings for scanners and mobile devices, that I've come across so far.