Cordova SDK

The U Grok It SDK for Cordova enables easy integration of RFID functionality into a Cordova app for iOS or Android. Cordova (formerly named PhoneGap) is a platform for building native mobile applications using HTML, CSS and JavaScript.

Cordova is an open source Apache project available here.

This SDK is implemented as a Cordova plug-in, and has been tested with Cordova 6.5.0. The plug-in is built on the U Grok It iOS and Android SDKs. Cordova requires iOS 8 by default, but does work with iOS 7 (using XCode 7).

Downloading and Installation

The SDK is distributed as a ZIP file and includes:

  • com.ugrokit.cordova.ugrokit (folder)
    The Cordova plug-in.
  • CordovaApiDemo (folder)
    Contains the CordovaApiDemo sample application that demonstrates use of the API.
  • html (folder)
    The HTML documentation
Download the SDKs
iOS, Android, Windows, Cordova, Xamarin
The CordovaApiDemo sample app

The CordovaApiDemo application demonstrates use of the API. It is built for both the iOS and Android platforms. In standard Cordova style, the iOS app is in CordovaApiDemo/platforms/ios and the Android app is in CordovaApiDemo/platforms/android.

Integrating the API into an existing Cordova project

To integrate the U Grok It API into your app, use the cordova tool:

cordova plugin add UGrokItCordovaSdk/com.ugrokit.cordova.ugrokit

Or you can get the plugin from the Cordova plugin registry:

  cordova plugin add com-ugrokit-cordova-ugrokit
Accessing the API

The API is accessed through the ugi singleton object in the global scope (window.ugi) and is automatically loaded by Cordova, as are a few supporting classes:

  • UgiTag
    Encapsulation of an RFID tag. Objects of this type are returned when tags are found.
  • UgiInventoryDelegate
    This class exists mainly for documentation, it documents the methods called in the delegate object passed to startInventory.
  • UgiRfidConfiguration
    This class exists mainly for documentation, it documents the fields in the object passed to startInventory() to run inventory.
  • UgiBatteryInfo
    This class exists mainly for documentation, it documents the fields in the object returned by ugi.getBatteryInfo().
Logging
For development is it useful to turn on logging in the onDeviceReady function:
  ugi.setLogging(ugi.LoggingTypes.STATE | ugi.LoggingTypes.INVENTORY);
Opening a connection to the grokker

Communication with the grokker is done via the audio port. For an application that uses U Grok It functionality all the time, this is done in the onDeviceReady function.

  ugi.openConnection();

openConnection returns immediately, it does not wait for a connection to the grokker to actually be established. If a grokker is connected, the connection takes 400-500ms (just under half a second) for the connection sequence. Your app can get notification of connection state changes vis ugi.addConnectionStateCallback():

  ugi.addConnectionStateCallback(function(connectionState) {
    if (connectionState == ugi.ConnectionStates.CONNECTED) {
      // Connection was established...
    }
  });
Inventory

Finding RFID tags is accomplished by running inventory. Once inventory is started, the grokker continually looks for RFID tags and reports them back to the iOS or Android device.

Starting inventory returns a UgiInventory object that holds the results of the inventory. The application can either save the UgiInventory object or can use ugi.activeInventory to get to it.

UgiInventory does some useful aggregation of the raw data from the grokker and reports back to your application via an InventoryDelegate object. Inventory can be run either with a configuration built from one of the pre-defined inventory types or with a custom UgiRfidConfiguration object.

The application can tell the grokker to report all RFID tags it finds:

  var config = UgiRfidConfiguration.configWithInventoryType(UgiRfidConfiguration.InventoryTypes.LOCATE_DISTANCE);
  ugi.startInventory(app, config);

Or the application can pass a specific tag 9or set of tags) to find:

  var config = UgiRfidConfiguration.configWithInventoryType(UgiRfidConfiguration.InventoryTypes.LOCATE_DISTANCE);
  ugi.startInventory(app, config, ["35fffffff99c70a063405c48"]);

Inventory runs until the application stops it.

  ugi.activeInventory.stopInventory();
Inventory Delegate methods

The inventory code reports back to the application via the inventory delegate object. All methods in the inventory delete are optional - the delegate just implements what it needs. The delegate methods are documented in the UgiInventoryDelegate class. Only a subset of the inventory delegate methods are discussed here.

New tag found

When a new tag is found, the delegate is notified via:

ugiInventoryTagFound: function(tag) {
  // tag was found for the first time, and is a UgiTag object
}

The UgiTag object contains information about the tag including:

  • Its EPC code
  • The time the tag was first read, the time the tag was most recently read
  • The total number of times this tag has been read
  • A history of how many times this tags has been read in recent time intervals (the default being the number of reads per 500ms going back 10 seconds, but this is configurable)
Subsequent finds of previously found tag

When a tag is found again, the delegate is notified via:

ugiInventoryTagSubsequentFinds: function(tag, count) {
  // tag found count more times
}
Tag visibility changed

When a tag is first found, has not been seen for a while (by default 10 seconds, but configurable), or is seen again after not being seen for awhile, the delegate is notified via:

ugiInventoryTagChanged: function(tag, firstFind) {
  if (firstFind) {
    // tag was found for the first time
  } else if (tag.isVisible) {
    // tag was not visible, is now visible again
  } else {
    // tag is no longer visible
  }
}

Usually the delegate either implements ugiInventoryTagChanged, or implements ugiInventoryTagFound (and sometimes ugiInventoryTagSubsequentFinds).

Tag Access (read, write, ...)

Methods in UgiInventory allow tag access for reading, writing and locking. All of these functions work similarly.

Tag programming (changing tag EPC)

While inventory is running, the app can program tags via:

	ugi.activeInventory.programTag("1234567890abcdef12345678", "35fffffff956734504747454", UgiInventory.NO_PASSWORD,
                                 function(tag, result) {
                                   if (result == UGI_TAG_ACCESS_OK) {
                                     // tag programmed successfully
                                   } else {
                                     // tag programming was unsuccessful
                                   }
                                 });

Sometime after the programTag method is called, the completion will be with the success or failure of the programming.

Grokker Configuration
Inventory

The UgiRfidConfiguration object holds the configuration to be used during inventory. Several pre-defined types can be used, defined in the UgiInventoryTypes enum. Values that can be configured include:

  • Power level
    Initial, minimum and maximum power levels can be set. If a range is provided (minimum != maximum), then the power level is varied over this range.
  • Q value
    Initial, minimum and maximum Q values can be set. If a range is provided (minimum != maximum), then the Q value is dynamically adjusted based on the number of tags in range
  • Session
    The inventory session (0, 1, 2, or 3)
  • Power level and sensitivity for writing tags
    The power level and sensitivity used when writing data to tags
  • Sensitivity
    The reader sensitivity

For more detailed information about RFID and configuration, see RFID Configuration

SDK Internet Usage

The SDK uses the Internet in a few cases, see SDK Internet Usage for details.

Localization

The SDK contains user visible strings for updating firmware, setting region of the world, and UI building blocks. It is localized into Spanish, French and German. If you are interested in localizations to other languages, contact us.