Microvision SDK for BlackBerry®

Developer Articles

How to Buy

The SDK for BlackBerry allows developers to quickly and easily integrate bar code scanning into a BlackBerry application. The SDK package includes the Java API, JavaDoc documentation, and a sample project that demonstrates how to create a scanner interface. The SDK package contains:

BcsSdkBlackBerry
ReadMeFirst.pdf		This document
BcsSdkBlackBerry.alx		BlackBerry Application Descriptor
BcsSdkBlackBerry.cod		Compiled and packaged BlackBerry SDK
\BcsSdk
BcsSdkBlackBerry.jar		SDK classes: Java Archive
BcsSdkBlackBerry.jad		SDKclasses: Java Application Descriptor
\Docs		Documentation directory
EULA.txt		SDK End User License Agreement
DA0120591 Microvision Scanner Programming Guide.pdf		Detailed Scanner Programming and Interface Guide that includes scanner commands, communications protocols, and interface best practices
\JavaDoc
	Index.html	JavaDoc API entry point
	*.html	JavaDoc generated API documentation
\Samples
RovSimpleApp.*		Project that shows how to create a simple scanner interface

Start with the JavaDoc documentation at Docs\JavaDoc\index.html. This Help system describes the classes, methods, and constants in the SDK. Read the class descriptions in the JavaDoc before looking at the sample project. After reviewing the JavaDoc proceed to the BcsSimpleApp demo project. This Java application demonstrates how to use the SDK to create a ROV scanner interface.

The Scanner Interface

The Microvision SDK for BlackBerry allows you to easily create an interface between your host computer and the ROV Scanner. This section explains the integration process in detail and includes helpful examples. The scanner interface requires each of these steps described below. Please refer to the SDK JavaDoc documentation for more information and clarification about the classes and methods described here.

Connecting to the Scanner

The first step in the communication process is creating a connection:

Pair the scanner with the BlackBerry device. Refer to your BlackBerry manual for instructions on pair the ROV Scanner to your Bluetooth device. Device pairing is not part of the SDK.
Enumerate the scanners paired to the Blackberry device by calling the BcsEnumConnections()method.
Call BcsOpenConnection()to open a connection to a specific scanner. You can choose the scanner from the enumeration list from the previous step. Note that the SDK for BlackBerry only supports Bluetooth connections. Successfully opening a connection generates a “Connected” event.

Events and Event Handling

As part of the communication, the ROV Scanner generates a number of events for information and notifications. These events help the developer understand and monitor the behavior of the connected scanner. These events also aid in the design of the application. Some examples of events include BCS_BT_CONNECTED_EV (scanner is connected), BCS_BT_CONNECT_FAILED_EV (scanner connection failed), BCS_BARCODE_AVAILABLE_EV (a bar code is available to be read). The ROV scanner can generate nine different events.

How can these events be used and how do they aid in the design of the application?

Example 1: After receiving a Connected event, the application can display a status message indicating that the scanner is connected and ready. The application can also display an error message if it received a “Connection Failure” event.
Example 2: After receiving a Bar Code Available event the application could (1) retrieve the bar code data from the scanner, or (2) keep a count of the number of bar codes received and retrieve a batch of bar codes when this count reaches a desired value.

The SDK JavaDoc documentation provides descriptions of the methods used to retrieve and clear bar codes from the scanner.

Now that we know what can be done with events, how does the application receive these events?

The application needs a way to “listen” for an event (or be “notified” of an event). You do this by making at least one class that implements theBcsScannerListenerinterface. With the listener interface the onEventReceived() method is called after each event is generated. You are free to implement this method as required. This means that the onEventReceived() method can perform different operations depending on the event received.

To learn more about scanner events, please refer to the SDK JavaDoc documentation. To know more about implementing the BcsScannerListenerinterface and the onEventReceived()method, refer to the sample application included with this SDK package.

Scanner Configuration

The Microvision Scanner Programming Guide contains the complete list of scanner properties and their descriptions. It also contains a list of commands to get and set the scanner properties. The developer can get and/or set properties of a connected scanner in two ways:

The BcsCommand() method sends commands to the scanner. You can use this method to get and set scanner properties, send a download request, clear scanner data, etc.
The BcsGetProp() and BcsSetProp() methods get and set specific scanner properties. These methods require the property name to set or get. BcsSetProp()also requires the value of the property to set (see the Programming Guide for details).

Disconnect Scanner

The application calls BcsCloseConnection() to terminate the scanner connection.

Microvision sdk for Blackberry classes

The SDK for BlackBerry includes the following classes to enable you to perform the steps mentioned above:

BcsConnector	This class and its methods are used for enumerating scanners and for opening and closing connections. You must create an instance of this class.
BcsScanner	This class is returned by BcsOpenConnection()of the BcsConnector class after successfully opening a connection to scanner. Use this class to Get/Set scanner properties, send scanner commands and receiving responses, and to retrieve barcodes from the scanner. You will not need to create an instance of this class.
BcsScannerInfo	Contains the scanner connection information such as Bluetooth serial port properties. You do not need to create an instance of this class.
BcsBarcode	A BcsScanner object encapsulates barcode and associated data downloaded from a scanner. You do not need to create an instance of this class.
BcsException	The SDK Exception class indicates that an error occurred. This class contains the error code information as defined in the CBscErrorCode interface.
BcsScannerListener	This interface is used for event notifications and contains the details of events that can be generated by the scanner. It should be implemented by some class in your application to receive the events. The onEventReceived() method implementation can however be customized based on the events received.
BcsErrorCode	This interface contains the possible SDK return codes. You cannot create an instance of this interface but you will to use this to determine the type of error that occurred.

The Bcssimpleapp Demo Project

Microvision included a complete Java project that demonstrates how to create a ROV Scanner interface to a BlackBerry device. This project includes full source code. You may use this as an example or you may cut and paste source code into your project. The BcsConnectScreen.java file contains all of the scanner interface code.

Support

Contact Microvision Product Support
Telephone: 1(866) 333 3542
Email: scannersupport@microvision.com
Web: http://www.microvision.com/barcode/support

Additional Resources

Microvision SDK for BlackBerry product page	www.microvision.com/barcode/developer/sdk_bb.html
DC0119391	XSP – eXtensible Scanner Protocol Specification

^back to top