Rfid Module

The Rfid Module is not included in the default RhoElements/RhoStudio installers. To be able to use the RFID module, a separate package must be downloaded and installed - please SEE REMARKS for how this can be obtained. Provides access to control the functionality of the device’s RFID reader. Currently the plug-in is supported on MC 3190Z and MC 9190Z devices.

• Syntax
• Methods
• Parameters
• Events
• Remarks
• Requirements
• HTML/JavaScript 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.

enumRFIDEvent

Enumerates the RFID readers present on the device (normally only one) along with their respective capabilities

rfParamsEvent

Returns RF Parameter values - Transmit Power and RF Mode of a selected antenna

rfModeInfoEvent

Returns the RF Characteristics for a particular RF Mode

tagEvent

Returns received RFID tag data from N tags, where N = reportTrigger. Typically methods like performInventory, tagLocate, readTag/writeTag/lockTag/killTag (performed on one or more tags) generate tagEvents with necessary data.

radioPowerStateEvent

Returns 1 if the radio is ON and 0 if the radio is off

statusEvent

Returns any error conditions where required

singulationEvent

Returns singulation values.

operationCompleteEvent

Indicates the currently running operation (Inventory/Access/Locationing) is complete and there are no more tags to report.

lastAccessResultEvent

Returns results of the last Access operation

Remarks

Installation

The RFID plug-in package for RhoElements 2.2 SP1 must be downloaded separately on Zebra Technologies Support Site and installed on the device. Please refer to the RFID plug-in release notes included with the download for installation instructions. You can find a sample app here to see how to use rfid as the RhoMobile framework expects it to be used. And you can find release notes for the rfid plug-in and the sample app here. Once you have the plug-in installed, you’ll also need to modify your config.xml setting PreloadLegacyActiveX and set it to ‘1’ as such:

<PreloadLegacyActiveX value="1"/>

General

By default the plug-in, when loaded, is already connected to RFID Module. In order to disconnect, one may use disconnect() method call on the rfid object. After a successful disconnection, the connect() method may be used to make a new connection to the RFID Module. For a plug-in method to be successfully invoked, all of its associated non-default properties must be successfully set prior to making the call.

Waiting for operationCompleteEvent

When RhoElements finishes execution of a plug-in method call, the corresponding RFID operation may not have been completed, rather it may have just been started. Specifically, for performInventory, tagLocate, tag access operations (readTag/writeTag/lockTag/killTag) using access-filter or performed on all tags, the corresponding method call just initiates the corresponding RFID operation. These operations generate Tag-reports, and once all the reports are completely sent to the application, the plug-in sends a operationCompleteEvent. The disconnect() method also gives an operationCompleteEvent back to the application. It is important that the application register for operationCompleteEvent and further method calls will have to be made only after the reception of this event.

Handling the TagEvent

TagEvent should be assigned to a Callback that handles the tag-reports arising out of Inventory/Locationing/Read/Write/Lock/Kill operations. Every tagEvent callback should usually result in JSON TagData Array object of length equalling to the reportTrigger property set. However, in the contingency that the RFID operation has ended and the plug-in hasn’t accumulated reportTrigger number of tagData objects, then the pending tags are all sent to the tagEvent callback.

Access Operation Status Codes

For an access operation performed by using an access filter or an access operation performed on all tags, the status code only indicates that the operation has been successfully started. Setting enableTagAccessStatus to true generates Tag reports with the tagID and status of the access operation on the corresponding tagID. However, for a single tag access operation, the statusEvent indicates the result of the access operation for the given tagID.

Handling the operationCompleteEvent

When RhoElements finishes execution of a plug-in method call, the corresponding RFID operation may not have been completed, rather it may have just been started. Specifically, for performInventory, tagLocate, tag access operations (readTag/writeTag/lockTag/killTag) using access-filter or performed on all tags, the corresponding method call just initiates the corresponding RFID operation. These operations generate Tag-reports, and once all the reports are completely sent to the application, the plug-in sends a operationCompleteEvent.

Plug-in Busy

The Plug-in can perform only one RFID protocol operation (Inventory/Read/Write/Locate/Kill) at a time. Trying to invoke a new operation when an existing one is still running, will generate a “Plugin Busy” error. Irrespective whether stop method is called or not, the plug-in is ready to initiate a new operation only after it sends the operationCompleteEvent. Trying to start a new operation before the event is received will return a “Plugin Busy error”.

Deleting Pre-filters

Once a pre-filter is added with a particular ID, the same ID should be used to reference it when deleting it.

Tag Locating

Tag Locating can be performed only a particular antennaID.

Access Operations On All Visible Tags

One can perform an access operation on all tags in the field of view by setting rfid.tagID to an empty string(“”)

Access Filters

Access-filter can take up to tag-patterns. By default, match pattern used is Pattern-A alone and settings for tagPattern B are not considered unless specified by the appropriate matchPattern.

Requirements

HTML/JavaScript Examples

This example starts an inventory using HTTP Meta Tags and tags are sent to a JavaScript function “TagHandler”.

<META HTTP-Equiv="rfid" content="statusEvent:url('javascript:statusHandler(%json)')">
<META HTTP-Equiv="rfid" content="tagEvent:url('javascript:TagHandler(%json)')">
<META HTTP-Equiv="rfid" content="performInventory">
<script>
    // Function to handle a tagReport containing only tagID field
    function TagHandler(tagReportJSON){
       objGeneric.Log("TagID read:"+tagReportJSON.TagData[0].tagID,3);
    }
</script>

This example runs inventory as long as trigger button is pressed. By default, the plug-in reports unique tags to tagEvent callback in JSON format and beeps for every unique tag encountered. By default, only one tagID is reported per the JSON tagReport. Besides, this JSON contains only the field tagID.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    objGeneric.InvokeMETAFunction("OnTrigger", "javascript:doTrigger('%s')");
    rfid.statusEvent = "statusHandler(%json)";

    function doTrigger(state){

      if(state == 0){
          rfid.stop();
      }
      else{
          rfid.tagEvent =  "TagHandler(%json)";
          rfid.performInventory();
      }
    }

    // Function to handle a tagReport containing only tagID field
    function TagHandler(tagReportJSON){
       objGeneric.Log("TagID read:"+tagReportJSON.TagData[0].tagID,3);
    }

    function statusHandler(statusJSON){
      objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example performs inventory with start and stop triggers configured. Here all the tag-reads are reported to tagEvent callback with 5 reports per callback. Besides, the tagSeenCount and the UTCTtimestamp at which tag was first seen is also reported. Note:It will still beep for only unique tags read.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";

    function performAdvancedInventory1(){
        rfid.tagEvent =  "TagHandlerAdvanced1(%json)";
        rfid.reportUniqueTags = false;
        rfid.reportTrigger = 5;
        rfid.enableTagSeenCount = true;
        rfid.enableTagUTCTimeStamp = true;
        rfid.startTriggerType = "triggerPress";
        rfid.stopTriggerType = "duration";
        rfid.stopDuration = 10000;// Duration in milliseconds.
        rfid.performInventory();
    }

    // Function to handle tagReports containing tagID, seenCount and firstSeenTimeStamp fields.
    function TagHandlerAdvanced1(tagReportJSON){
       objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID+" Seen Count: "+tagReportJSON.TagData[0].tagSeenCount+" First seen Timestamp:"+tagReportJSON.TagData[0].firstSeenTimeStamp,3);
       objGeneric.Log("TagID :"+tagReportJSON.TagData[1].tagID+" Seen Count: "+tagReportJSON.TagData[1].tagSeenCount+" First seen Timestamp:"+tagReportJSON.TagData[1].firstSeenTimeStamp,3);
       objGeneric.Log("TagID :"+tagReportJSON.TagData[2].tagID+" Seen Count: "+tagReportJSON.TagData[2].tagSeenCount+" First seen Timestamp:"+tagReportJSON.TagData[2].firstSeenTimeStamp,3);
       objGeneric.Log("TagID :"+tagReportJSON.TagData[3].tagID+" Seen Count: "+tagReportJSON.TagData[3].tagSeenCount+" First seen Timestamp:"+tagReportJSON.TagData[3].firstSeenTimeStamp,3);
       objGeneric.Log("TagID :"+tagReportJSON.TagData[4].tagID+" Seen Count: "+tagReportJSON.TagData[4].tagSeenCount+" First seen Timestamp:"+tagReportJSON.TagData[4].firstSeenTimeStamp,3);
    }

    function statusHandler(statusJSON){
       objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example performs inventory and reads the Reserved memory Bank of all tags inventoried. The tags are selected to match a particular pre-filter pattern (EPC starts with “9742”) The tagEvent handler extracts both tagID and memoryBankData fields. Inventory is stopped after 10 tag-reads are observed

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";

    function performAdvancedInventory2(){
        rfid.tagEvent =  "TagHandlerAdvanced2(%json)";
        rfid.stopTriggerType = "tagObservation";
        rfid.stopObservationCount = 10;
        rfid.preFilterID = 1;
        rfid.preFilterMemBank = "EPC";
        rfid.preFilterBitOffset = 32;
        rfid.preFilterHexPattern = "9742";
        rfid.preFilterBitCount = 16;
        rfid.addPreFilter();
        rfid.invMemBank = "Reserved";
        rfid.performInventory();
    }

    // Function to handle tagReports containing tagID, seenCount and firstSeenTimeStamp fields.
    function TagHandlerAdvanced2(tagReportJSON){
       objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID+" Reserved MemoryBank Data: "+tagReportJSON.TagData[0].memoryBankData,1);
    }

    function statusHandler(statusJSON){
       objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example gets the capabilities of the local RFID Module and configures the antenna’s RF and Singulation parameters. The application should register JavaScript callbacks for the enumRFIDEvent and rfParamsEvent events.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";

    function EnumerateRFIDModule(){
      rfid.enumRFIDEvent = "enumerateRFIDHandler(%json)";
      objGeneric.Log("In EnumerateRFIDModule :",3);
      rfid.enumerate();
      ConfigureRFIDModule();
    }

    function enumerateRFIDHandler(enumRFIDJSON){
      objGeneric.Log("Number of Devices:"+enumRFIDJSON.numberOfDevices,3);
      objGeneric.Log("Reader ID:"+enumRFIDJSON.readerID,3);
      objGeneric.Log("Firmware version:"+enumRFIDJSON.firmwareVersion,3);
      objGeneric.Log("Model Name:"+enumRFIDJSON.modelName,3);
      objGeneric.Log("Number of Antennas:"+enumRFIDJSON.numberOfAntennas,3);
      objGeneric.Log("Number of Prefilters:"+enumRFIDJSON.numberOfPreFilters,3);
      objGeneric.Log("Country code:"+enumRFIDJSON.countryCode,3);
      objGeneric.Log("Communication standard:"+enumRFIDJSON.communicationStandard,3);
      objGeneric.Log("Minimum Transmit Power:"+enumRFIDJSON.transmitPowerMin,3);
      objGeneric.Log("Maximum Transmit Power:"+enumRFIDJSON.transmitPowerMax,3);
      objGeneric.Log("Step Transmit Power:"+enumRFIDJSON.transmitPowerStep,3);
      objGeneric.Log("Supported RF Modes:"+enumRFIDJSON.numberOfRFModes,3);
      objGeneric.Log("State Aware Singulation:"+enumRFIDJSON.stateAwareSingulationSupported,3);
    }

    function ConfigureRFIDModule(){
      rfid.singulationEvent = "getSingulationHandler(%json)";
      rfid.rfParamsEvent = "getRFParamsHandler(%json)";

      rfid.singulationSession  = "1";
      rfid.singulationTagPopulation = "100";

      rfid.RFMode = "4";             // Mode table Index
      rfid.transmitPower = "25.20";  // Transmit Power in dbM

      rfid.setSingulation(); // Applies on both the antennas.
      rfid.setRFParams();

      rfid.antennaSelected = 1;  // To verify if the settings have indeed been applied.
      rfid.getSingulation();
      rfid.getRFParams();
    }

    function getRFParamsHandler(RFParamsJSON){
      objGeneric.Log("RFMode of Antenna 1:"+RFParamsJSON.RFMode,3);
      objGeneric.Log("Transmit Power of Antenna 1:"+RFParamsJSON.transmitPower,3);
    }

    function getSingulationHandler(singulationJSON){
      objGeneric.Log("Session of Antenna 1:"+singulationJSON.singulationSession,3);
      objGeneric.Log("Tag Population of Antenna 1:"+singulationJSON.singulationTagPopulation,3);
    }

    function statusHandler(statusJSON){
      objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example performs TagLocationing operation and reports the real-time relative distance information of the tag being located.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";

    function TagLocationing(){
        rfid.tagEvent = "TagLocateHandler(%json)";
        rfid.antennaSelected = 1;
        rfid.tagID = "97427423111111111111111111111111111111111111111111111111";
        rfid.locateTag();
        setTimeout("stopRunningLocate()",10000);
    }

    function stopRunningLocate(){
        rfid.stop();

    }

    function TagLocateHandler(tagReportJSON){
        objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID+" Relative Distance: "+tagReportJSON.TagData[0].relativeDistance,1);
    }

    function statusHandler(statusJSON){
       objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example performs Read operation on a particular tagID.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";

    function readSingleTag(){
        rfid.tagID = "97427423111111111111111111111111111111111111111111111111";
        rfid.tagEvent =  "TagMemBankHandler(%json)";
        rfid.tagByteOffset = 4;
        rfid.tagMemBank = "Reserved";
        rfid.tagReadSize = 4;
        rfid.tagRead();
    }

    function TagMemBankHandler(tagReportJSON){
      objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID+" Access Password: "+tagReportJSON.TagData[0].memoryBankData,1);
    }

    function statusHandler(statusJSON){
       objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example performs Read operation on all tags that match a particular tagPattern(access-filter). Reads User memory bank of all tags whose EPC start with “9742”.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    rfid.statusEvent = "statusHandler(%json)";
    function testReadMultipleTags(){
      var selectedTagPattern = "9742";
      var hexMaskStr = "";var i =0;
      for(i =0;i < selectedTagPattern.length;i++)
      hexMaskStr += "F";

      rfid.useAccessFilter = true;
      rfid.matchPattern = "A";
      rfid.tagPatternAMemBank = "EPC";
      rfid.tagPatternAByteOffset = 4;
      rfid.tagPatternAHexPattern = selectedTagPattern;
      rfid.tagPatternAHexMask = hexMaskStr.toString();
      hexMaskStr = "";
      for(i=0;i < selectedTagPattern.length;i++)
      hexMaskStr += "F";

      rfid.tagByteOffset = 0;
      rfid.tagMemBank = "User";
      rfid.tagReadSize = 0;
      rfid.tagEvent =  "TagMemBankHandler(%json)";
      rfid.tagRead();
    }

    function TagMemBankHandler(tagReportJSON){
      objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID+" User Memory Data: "+tagReportJSON.TagData[0].memoryBankData,1);
    }

    function statusHandler(statusJSON){
      objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example shows the usage of State aware pre-filters and operationCompleteEvent. This function tries to search for a tag whose EPC starts with “56780000”

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    var tagCount = 0;

    function testStateAwarePreFilter(){
      rfid.tagEvent =  "TagHandler(%json)";
      rfid.statusEvent = "statusHandler(%json)";
      rfid.operationCompleteEvent = "operCompleteHandler()";

      rfid.performStateAwareSingulation = true;

      rfid.singulationSLFlag = "SL_ASSERTED";
      rfid.singulationInventoryState = "INV_B";
      rfid.setSingulation();

      rfid.preFilterID = 0;
      rfid.preFilterHexPattern = "0000";
      rfid.preFilterMemBank = "EPC";
      rfid.preFilterBitOffset = 48;
      rfid.preFilterStateAwareAction = "INV_B_NOT_INV_A";
      rfid.preFilterTarget = "INV_S0";
      rfid.addPreFilter();

      rfid.preFilterID = 1;
      rfid.preFilterHexPattern = "5678";
      rfid.preFilterBitOffset = 32;
      rfid.preFilterStateAwareAction = "ASRT_SL_NOT_DSRT_SL";
      rfid.preFilterTarget = "SL";
      rfid.addPreFilter();

      rfid.reportUniqueTags = false;
      rfid.beepOnRead = true;
      rfid.stopTriggerType = "tagObservation";
      rfid.stopObservationCount = 10;
      rfid.performInventory();
    }

    function operCompleteHandler(){
        alert('Operation Complete. Total tags received:'+tagCount.toString());
    }

    function TagHandler(tagReportJSON){
        tagCount += tagReportJSON.TagData.length;
        objGeneric.Log("TagID :"+tagReportJSON.TagData[0].tagID,1);

    }

    function statusHandler(statusJSON){
      objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>

This example shows the usage of getLastAccessResult method. At the completion of a multiple tag Write operation, the latter method is called to find out how many tags the operation succeeded and failed.

<script>
    var objGeneric = new ActiveXObject("PocketBrowser.Generic");
    var tagCount = 0;
    function writeMultipleTags(){
      rfid.tagEvent =  "TagAccessStatusFieldHandler(%json)";
      rfid.statusEvent = "statusHandler(%json)";
      rfid.operationCompleteEvent = "operCompleteHandler()";
      rfid.lastAccessResultEvent = "lastAccessResultHandler(%json)";
      clear();

      var hexMaskStr = "";var i =0;
      for(i =0;i<8;i++)
      hexMaskStr += "F";
      rfid.enableTagAccessStatus = true;
      rfid.useAccessFilter = true;
      rfid.tagPatternAMemBank = "Reserved";
      rfid.tagPatternAByteOffset = 4;
      rfid.tagPatternAHexPattern = "FFFFFFFF";
      rfid.tagPatternAHexMask = hexMaskStr.toString();
      rfid.tagByteOffset = 4;
      rfid.tagMemBank = "EPC";
      rfid.tagWriteData = "EEEEAAAA";
      rfid.tagWrite();
    }

    function TagAccessStatusFieldHandler(tagReportJSON){
        objGeneric.Log("TagID:"tagReportJSON.TagData[0].tagID+" Access Status "+tagReportJSON.TagData[0].accessStatus);
    }

    function operCompleteHandler(){
        rfid.getLastAccessResult();
    }

    function lastAccessResultHandler(accessResultJSON){
        alert("Success: "+accessResultJSON.tagsSucceeded.toString()+" Failures: "+accessResultJSON.tagsFailed.toString());
    }

    function statusHandler(statusJSON){
      objGeneric.Log("Status:"+statusJSON.method+'  '+statusJSON.errorCode,1);
    }
</script>