Scanner Module

The Scanner Module provides access to control the functionality of the device’s scanner.

• Syntax
• Methods
• Parameters
• Events
• Multi Instance
• Remarks
• Requirements
• HTML/Javascript Examples
• Ruby Examples

Syntax

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a Javascript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or javascript arrays. Event parameters can be accessed either directly or via JSON objects.

decodeEvent

A decode event is sent by the Scanner whenever a barcode is decoded.

bluetoothStatusEvent

A bluetoothStatusEvent is sent whenever a bluetooth connection / disconnection event occurs. If you are connected to a bluetooth scanner and have not registered to receive this event the status message will be sent as the sixth return value of the decodeEvent.

enumScannerEvent

The Enum Scanner Event is used to ascertain the scanners present on the device.

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: Only the foreground RhoElements application is given access to the device scanner, when an application is sent to the background its state will be saved and it will automatically relinquish control of the Scanner. When brought back to the foreground, an application previously using the scanner will have its previous configuration (eg. selected decoders) reapplied to the scanner automatically.

Remarks

General

If the Scanner Meta Tag is used without DecodeEvent, the data will be output as keystrokes. On unlicensed devices it is not recommended to enable the Scanner on the application’s startup page, this can interfere with the the license screen.

Use Meta Tags Instead of Scanner Object

Prefer Meta Tags instead of Scanner Object, if an application is designed to perform continuos scanning on reload of the page with certain properties(exposed by scanner object).

Scanning and Image Capture Interaction

In some device configurations the scanner and imager share the same hardware, e.g. the blockbuster scanner and top mounted imager on the MC75a. Where two modules share the same physical hardware they cannot be enabled simultaneously, once the scanner is enabled it must be disabled before the imager can be used, and vice versa.

AutoEnter and AutoTab

AutoEnter and AutoTab are mutually exclusive, only one can be enabled at any one time. If both are enabled then AutoEnter will take priority.

Bluetooth Scanner Overview

Once associated with the Device a Bluetooth Scanner will remain associated even after losing the BT connection. In order to associate a different Bluetooth scanner with the device it is necessary to scan the ‘unpairing’ barcode and then invoke the ‘disabled’ meta tag followed by the ‘enabled’ meta tag, this will allow you to scan the BT association barcode with a different scanner. You can override this default behaviour using the disconnectBtOnDisable parameter.

The following messages will be received from the Bluetooth Scanner in the bluetoothStatus event:

* 'BTScanAssociationBarcode' 
   Means the device is ready to be associated with a BT scanner.  You must scan the 
   association barcode.  It is only necessary to scan the association 
   barcode when you first associate a scanner with the device, this pairing will be remembered until
   you scan the unpairing barcode.

* 'BluetoothConnected'
   The remote scanner has successfully connected to the device.
    
* 'BluetoothDisconnected'
   The remote scanner has become disconnected from the device, this may be due to loss of battery, being out
   of range or scanning the 'unpairing' barcode.  The scanner will attempt to reconnect automatically for
   a period of time once it regains power or goes out of range, if it fails to reconnect after the specified
   timeout the reconnect button on the device should be pushed.  Once the unpairing barcode is scanned
   it is necessary to disable the scanner and then re-enable it before another scanner can be associated.

ScannerArray attribute

The ScannerArray attribute returned from Scanner tag with parameter “EnumScannerEvent” will enumerate each scanner present on the device in a 2D array, associating each scanner’s device name with a user friendly name. The device ID can be passed as a parameter to “Scanner” “Enabled:<deviceID>”, the friendly name is a user readable description of the scanner, e.g:

"SCN1", "1D Scanner Driver"
"SCN2", "Camera"
"SCN3", "Bluetooth SSI Scanner Driver"

Viewfinder Position Parameters

The scanner viewfinder window is not infinitely resizable, when setting ViewFinderX, ViewFinderY, ViewFinderWidth and ViewFinderHeight ensure you do not exceed the size of the screen and it is recommended to use the same aspect ratio as your device. For applications designed to handle screen rotation it is recommended to use a scan window whose longest side will fit within both the screen width and screen height. If your viewfinder position fails to be applied it is recommended you query your log file to see which parameter is causing trouble, or reposition the window away from the edges of the screen.

DataWedge Interaction With Native Apps

In order to use the scanner with RhoElements Native Apps you will need to either disable DataWedge or create a DataWedge profile for your app.

DISABLING DATAWEDGE
1.  Start the DataWedge app
2.  Click the menu button > "Settings" and untick "DataWedge enabled". 
RHOELEMENTS DATAWEDGE PROFILE
1.  Install your RhoElements native app,
2.  Start the DataWedge app
3.  Click the menu button > "New Profile" and enter a name,
4.  Click on the link to the new profile in the profile list,
5.  Click on "Associated apps" in the "Applications" section,
6.  Click the menu button > "New app/activity",
7.  Select the package name for your app,
8.  Select "*",
9.  Click the "Back" capacitive button,
10. Make sure the "Profile enabled" checkbox is ticked.
11. Uncheck all three "Enabled" checkboxes under the sections of:
    "Barcode input", "Keystroke output" and "Intent output".

Requirements

HTML/Javascript Examples

The following example enables the scanner, turns on autoenter and performs a soft trigger start:

<META HTTP-Equiv="scanner" Content="Enable">
<META HTTP-Equiv="scanner" Content="AutoEnter:Enabled">
<META HTTP-Equiv="scanner" Content="Start">

The following example sets up the scanner on a page to submit the scanned data to an asp page upon successful decoding

<META HTTP-Equiv="scanner" Content="enabled">
<META HTTP-Equiv="scanner" Content="DecodeEvent:url('mypage.asp?Data=%s&Source=%s&Type=%s&Time=%s&Length=%s')">

The following example sets up the scanner on a page to call a javascript function upon successful decoding:

<META HTTP-Equiv="scanner" Content="enable">
<META HTTP-Equiv="scanner" Content="DecodeEvent:url('javascript:doScan(%json);')">

<script>
   function doScan(jsonObject)
   {
      if(jsonObject.type == 0x35) //ean 13
      {
         alert('Please scan a non EAN 13 code!');
      }
      else
      {
         alert('You scanned: ' + jsonObject.data);
      }
   }
</script>

The following example demonstrates how to set a device into presentation mode.

<HTML>
<HEAD>
  <Meta http-equiv="scanner" content="aimType:presentation">
  <Meta http-equiv="scanner" content="DecodeEvent:url('Javascript:doScan('%s');')">
  <Meta http-equiv="scanner" content="enable">
</HEAD>
<BODY onLoad="doSoftScan();">
  <SCRIPT LANGUAGE="JavaScript">

    function doSoftScan()
    {
        scanner.start();
    }

    function doScan(jsonObject)
    {
        bcode.innerHTML = jsonObject.data;
        doSoftScan();
    }
  </SCRIPT>
  <div id="bcode"></div>
</BODY>
</HTML>

The following example shows how an application might handle a Bluetooth Scanner whose ID is SCN2:

<HTML>
<HEAD>
<!-- Status Updates are received via bluetoothStatusEvent -->
<META HTTP-Equiv="Scanner" Content="BluetoothStatusEvent:url('Javascript:BTStatusFunc(%json);')">
<META HTTP-Equiv="Scanner" Content="DecodeEvent:url('Javascript:ScanFunc(%json);')">
<!-- Enable the Bluetooth Scanner, this will commence the BT pairing -->
<META HTTP-Equiv="Scanner" Content="Enabled:SCN2">
</HEAD>

Barcode Data: <DIV ID="bcode"> </DIV>
User Message: <DIV ID="message"> </DIV>
<P><INPUT TYPE="button" VALUE="Change Associated Scanner" ONCLICK="onChangeScanner();"></P>
</BODY>
</HTML>

<SCRIPT LANGUAGE="JavaScript">

//  Whether or not the next barcode data we receive will be the unpairing barcode
var expectingUnpairingBarcode = false;

function ScanFunc(jsonObject)
{
    //  Output the scanned barcode
    bcode.innerHTML = data;
}

function BTStatusFunc(jsonObject)
{
    if (expectingUnpairingBarcode)
    {
        //  restart the scanner component so it is ready
        //  to accept a different Bluetooth Scanner
        expectingUnpairingBarcode = false;
        scanner.disable();
        scanner.enabled = 'SCN2';
        return;
    }

    if (jsonObject.status == 'BTScanAssociationBarcode')
    {
        //  Instruct the User to scan the association barcode
        alert('Scan Association Barcode');
    }
    else if(jsonObject.status == 'BluetoothConnected')
    {
        message.innerHTML = "Bluetooth Scanner Connected";
    }
    else if(jsonObject.status == 'BluetoothDisconnected')
    {
        message.innerHTML = "Bluetooth Disconnected, Please Reconnect";
    }
}

function onChangeScanner()
{
    //  Change the BT Scanner associated with the device, the logic to do this is handled
    //  once the 'unpairing' barcode is scanned.
    message.innerHTML = "Please Scan Unpairing Barcode";
    expectingUnpairingBarcode = true;
}
</SCRIPT>

The following example displays the available scanners on screen and enables the Bluetooth Scanner (if available)

<HTML>
<HEAD>
<META HTTP-Equiv="Scanner" Content="DecodeEvent:url('Javascript:ScanFunc(%json);')">
<META HTTP-Equiv="Scanner" Content="BluetoothStatusEvent:url('Javascript:BTFunc(%json);')">
<META HTTP-Equiv="Scanner" Content="EnumScannerEvent:url('Javascript:EnumScanners(%json);')">
</HEAD>

<BODY onLoad="setEnumScannerTimer();">
<DIV ID="message"></DIV>
</BODY>
</HTML>

<SCRIPT LANGUAGE="JavaScript">
function ScanFunc(jsonObject) {message.innerHTML = jsonObject.data;}

function BTFunc(jsonObject) {message.innerHTML = jsonObject.status;}

function EnumScanners(jsonObject)
{
    var scannerInfo = "Scanners On Device: " + jsonObject.scannerArray.length + "<BR>ID  --  Name<BR>" 
    for (i=0; i < jsonObject.scannerArray.length; i++)
    {
        scannerInfo = scannerInfo + jsonObject.scannerArray[i].deviceName + ' -- '
        + jsonObject.scannerArray[i].friendlyName + '<BR>';
        //  See if this is the Bluetooth Scanner
        if (jsonObject.scannerArray[i].friendlyName.indexOf("Bluetooth") >= 0)
        {
            //  This is the Bluetooth Scanner, Enable it
            scanner.enabled = jsonObject.scannerArray[i].deviceName;
        }
    }
    message.innerHTML = scannerInfo;
}

//  Wait for the DOM to fully load before we enumerate the scanners
function setEnumScannerTimer()
{
    setTimeout("onScannerEnable()", 3000);
}
function onScannerEnable()
{
    scanner.enumerate();
}
</SCRIPT>

Ruby Examples

The following example lists the available scanners on a device. It first detaches the listeners to ‘enumScannerEvent’ (if any), then attaches it to a listner and makes a call to ‘enumerate’ which fires the ‘enumScannerEvent’. This piece of code should be placed in the controller

def registerEnumEvent
    Scanner.enumScannerEvent = ''
    Scanner.enumScannerEvent = url_for(:action => :enumScannerEventListener)
    Scanner.enumerate
end

To call the this function from HTML, use the following code:

<li onclick="enumerateScanner();">Enumerate Scanners</li>

Where ‘enumerateScanner()’ is a JavaScript function which looks like:

function enumerateScanner() {
    $.get('/app/ScannerModule/registerEnumEvent', { });
    return false;
}

The following piece of code captures the array of scanners returned from the ‘enumScannerEvent’ and constructs a string to be displayed on an HTML div:

def enumScannerEventListener
    scanners = @params

    String buf = "Available scanners: <BR>"    
    if scanners    
      scanners['scannerArray'].each {|scanner| buf += '' + scanner["deviceName"] + " : " + scanner["friendlyName"] + "<BR>"}
      WebView.execute_js("setFieldValue('"+buf+"');")
    else
      WebView.execute_js("setFieldValue('No Scanners found! ');")
    end    
end

The following example enables the scanner and attaches a listener to the decode event. This can be called from HTML in a similar fashion to the one described above.

def enableScanner
    Scanner.enable
    Scanner.decodeEvent = url_for(:action => :scannerEventListener)
    WebView.execute_js("setFieldValue('Scanner Enabled');")
end

The following example populates an HTML div with scanned data upon successful decoding of a barcode:

def scannerEventListener
    scanResult = @params
    WebView.execute_js("setFieldValue('You scanned: <BR>" + scanResult['data'] +"<BR>');")
end

The following example disables the scanner and detaches any listeners attached to the decode event. This can be called from HTML in a similar fashion to the one described above.

def disableScanner
    Scanner.disable
    Scanner.decodeEvent = ''
    WebView.execute_js("setFieldValue('Scanner Disabled.');")
end 

For all the examples described above, the ‘setFieldValue()’ JavaScript function looks like:

function setFieldValue(returnval){
    document.getElementById("result").innerHTML=returnval;
}