Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
NDK_project
ext
sample_application
LICENSE
README.md
files.png
screenshot1.png
screenshot2.png
screenshot3.png
screenshot4.png

README.md

Barcode Scanner

This BlackBerry 10 WebWorks extension scans all types of barcodes supported by the ZXing library. The Rear Camera is used and it paints a viewfinder onto a Canvas for the user to target the barcode.

** Tested On **

BlackBerry 10 Dev Alpha B 10.0.10.263

BlackBerry Z10 10.1.0.1622

BlackBerry Q10 10.1.0.1020

** Authors **

Tim Windsor

Alex Kwan

Mike Delong

Building and Testing the Sample

  1. Deploy the extension into your BB10 WebWorks SDK by copying the community.barcodescanner folder from the ext folder to the Framework/ext folder in your WebWorks SDK, or run the Ant build script in the /ext folder to do so.
  2. Package the sample in the sample_application folder. Use the Ant Build Script, or you can do this with the WebWorks packager command: bbwp sample_application -g signingpassword
  3. Load it on your phone using the Ant Build Script, or with the blackberry-deploy command found in the dependencies/tools folder of your WebWorks SDK.
  4. When the application runs, two buttons will appear on a white background. Press Scan to start scanning, and the background becomes a viewfinder. Press Stop to stop scanning. If a barcode is detected, a toast will appear with the data. To Scan 1D barcodes (ie UPC product codes) you will have to turn so the lines are horizontal as shown below.

Screenshot   Screenshot   Screenshot   Screenshot

Including the feature in your application

This feature depends on the blackberry.io feature as well, so both must be included in your applications config.xml file. Also, permission for the camera is required.

<feature id="blackberry.io" />
<feature id="community.barcodescanner" />

<rim:permissions>
	<rim:permit>use_camera</rim:permit>
</rim:permissions>

It's also recommended that you stop scanning if the app goes into the background. To respond to app state, include the following feature:

<feature id="blackberry.app" />

When you start scanning, you can make the experience better for your users with the Prevent Sleep Extension. If you include Prevent Sleep in your app, the BarcodeScanner will automatically use it as needed to keep the screen on. Instructions for installing are in the Preven Sleep README

<feature id="community.preventsleep" />

The Extension API

The Barcode Scanner Extension provides the following API:

	// Start Scanning for Barcodes
	// "myCanvas" is the ID of a Canvas element for displaying the viewfinder
	// the viewfinder will be resized to the size of the Canvas given
	community.barcodescanner.startRead(codeFound, errorFound, "myCanvas", onStartRead);

	function errorFound(data){
		console.log("Error : "+data.error + " description : "+ data.description);
	}

	function codeFound(data) {
		if (gotCode === false) {
			gotCode = true;
			stopBarcodeRead();
			blackberry.ui.toast.show("Detected : "+data.value);
		}
	}

	function onStartRead(data){
		console.log("Started : "+data.successful);
	}

	// Stop Scanning for Barcodes
	community.barcodescanner.stopRead(onStopRead, errorFound);

	function onStopRead(data){
		console.log("Stopped : " +data.successful);
	}

Known Issues

  1. Follow the best practices in the Sample Application for shutting of the scanner when going the background or leaving the part of your app which is doing the scanning. It's also recommended to timeout the scan. Scanning is an intensive operation and will continue until stopRead() is called, but starting and stopping is quick, so don't hesitate to shut it down.

  2. 1D Barcodes like UPC product codes need to be scanned with the bar lines running horizontally, so the code looks something like a stack of paper.

  3. Scanning for a very long time time or repeatedly scanning does seem to use up device memory slowly, so there's also some optimization to be done yet.

Implementation Details

There are two parts to this Barcode Scanner - 1. Scanning camera frames for Barcodes, and 2. Showing the user what they are aiming at. The first part works identically to any native implementation and takes advantage of BlackBerry 10's capabilities with the camera, continuous macro focus, and high speed barcode interpretation.

The second part is a little trickier. It's not possible to send video data from the viewfinder through to the webview directly. In native barcode scanners, the viewfinder is able to paint right onto it's own window, but that approach is not possible in WebWorks. Instead, the camera is operated in burst mode and frames are captured at 1/3rd the speed of the barcode scanning. These frames are scaled down, rotated as necessary, and saved to the filesystem. Then the WebWorks side of the extension is notified of the file path so it can load the image and paint it to a Canvas. These images are slightly delayed, lower quality, and at a reduced framerate from native video solutions, so be forewarned that the solution does not compare well.

Building the extension from source

Copy the extension folder to a location on your computer to start working with it.

Momentics NDK setup

  1. Open the Momentics IDE. Navigate to the workbench and from the program menu select File -> Import and choose "Existing Projects into Workspace".
  2. Choose "Select root directory: " and browse to the NDK_project directory where you copied the extension. Select the BarcodeScanner project in the Projects list and uncheck "Copy projects into workspace". Click Finish.
  3. Follow these next steps to build the extension to be sure the setup is working.

How to build your native Extension

  1. Right click your project and select the Clean Project option.
  2. Right click your project again and select Build Configurations -> Build Selected... .
  3. A window will appear that shows all the available build configurations for the project. Select Device-Release and Simulator-Debug and click ok.
  4. You should see the shared libraries generated in the folders for each Build Configuration that you selected.
  5. Copy the .so file(s) to the device and simulator folders under the ext/community.barcodescanner directory. Or you can use the Ant build script to do so.

Copying the Extension to the SDK

  1. Under the ext folder in this project should be the community.barcodescanner folder with the following file structure underneath it:

Screenshot

If you wish to do the copying manually, continue with these steps:

  1. The device and simulator folders should contain the libBarcodeScanner.so files built by the NDK.
  2. Copy the community.barcodescanner folder into your WebWorks SDK, placing it in the Framework/ext directory.

If you have Ant installed and would like to use the build script provided, edit the script as follows (you will find it in the /ext directory, called build.xml ).

  1. Change the project name to match the extension name in manifest.json.
  2. Change the bbwp.native.dir value to match the SDK you want to deploy to.
  3. Type ant at a command prompt while in the /ext directory of the Extension.

The build script will clean any old extension from your SDK, copy the .so files build by the NDK into the correct locations, and finally copy the whole extension into the SDK.

Using the Extension in an Application

With the extension copied into your WebWorks SDK as explained above, you can use it in your applications by referencing it as a feature in your config.xml file.

<feature id="community.barcodescanner" />

All the methods in the extension will be prefixed by that feature id, so a method called startRead() supplied in the community.barcodescanner extension will be called in JavaScript like so:

community.barcodescanner.startRead(codeFound, errorFound, "myCanvas", onStartRead);

Modifying the Extension

See the examples in the Template Extension for how to add additional features to this extension

Rebuild

When making changes, rebuild regularly so you don't make a really hard to find typo.

Follow the steps above to:

  1. Build the native portion,
  2. Copy the extension to your SDK, and
  3. Use the extension in your test app.

To contribute code to this repository you must be signed up as an official contributor.

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Analytics