Barcode Scanner Terminal Documentation

The app is found here: https://play.google.com/store/apps/details?id=no.winternet.barcodescannerterminal3

Need help?
Please contact us if you need more help. We also develop custom systems, including custom apps, business website systems, Intranet servers etc. Have rich experience handling both simple and complex business processes, and integrating between systems.

Processing mode

The Barcode Scanner Terminal has 5 different processing modes. What happens after scanning the barcode is explained here for each of the modes:

Always only send to server The barcode is always only sent through the network to the server. If server cannot be reached (eg. no Internet connection or server down) the barcode is not processed and simply discarded. Default
Always only store on device The barcode is always only stored on device (on internal memory or SD card, depending on Android version) on the device, regardless of whether or not the device is online and the server is reachable. No server is contacted at any time.  
Always both send and store The barcode is always both sent through the network to the server and always stored on device (on internal memory or SD card, depending on Android version). If server cannot be reached (eg. no Internet connection or server down) the barcode is still stored on device.  
Online: send, Offline: store First we attempt to send it to the server and if we succeed we don't store the barcode. If we cannot reach the server, then it's stored on device (on internal memory or SD card, depending on Android version).  
Validate against Excel on device The barcode is only checked against an Excel spreadsheet stored on device (on internal memory or SD card, depending on Android version). It is not sent to the server and it is not stored within the usual 'processed' and 'unprocessed' folders. But it is stored within the Excel spreadsheet though. See the related section for details.  

Storing on device

When the app is storing the scanned barcodes on the device (on internal memory or SD card, depending on Android version) they are stored in the folder /no.winternet.barcodescannerterminal3. If the barcode was also sent to the server for processing it will be stored in /no.winternet.barcodescannerterminal3/processed/. If the barcode was NOT sent to the server for processing it will be stored in /no.winternet.barcodescannerterminal3/unprocessed/. You can easily access these folders and do whatever you want with the data.

Each time you scan a barcode it will be stored in a new file (even if you scan the same barcode multiple times). The file name will be the timestamp in the format:

yyyy-mm-dd_hh-mm-ss-msec.json

The content of the file will be a string representing a JSON object, for example:

{"barcode":"987654321098","scannerID":"door1","time":"2013-02-13 12:34:59.724"}

Or if GPS coordinates are stored as well:

{"barcode":"987654321098","scannerID":"door1","time":"2013-02-13 12:34:59.724","lat":45.527826,"long":-122.601107}
Or if scan points and quantities are enabled as well: 
{"barcode":"987654321098","scannerID":"door1","time":"2013-02-13 12:34:59.724","scanpoint":"IN","qty":"5"}

Send unprocessed barcodes to server

If you want to send all unprocessed barcodes stored on the device to the server go to the Local Storage tab in the app and press Send to server. This will collect all the barcodes in the unprocessed folder and put them into a JSON array to make one long string with all barcodes to send to the server in one single request. Each item in the JSON array will be a JSON object identical to the sample shown above. The URL used is the same as the normal one (see related section) but now it will be a POST request instead of a GET request (the non-applicable query string variable will just be empty). The name of the POSTed name/value pair is 'batch'. This means that in eg. PHP you can get the entire string with JSON data using $_POST['batch'] and then you run it through json_decode() to get it into a variable you can easily work with.

Alternatively, if you rather want to do a pure JSON POST having Content-Type: application/json you can add &postdata=json to the URL in the app settings. In PHP you would then get the JSON string with file_get_contents('php://input').

An example of the JSON data could look like this (line-breaks only added for easy reading):

[
{"barcode":"987654321098","scannerID":"door1","time":"2013-02-13 12:34:59.724","scanpoint":"IN","qty":"40"},
{"barcode":"987655687565","scannerID":"door1","time":"2013-02-13 12:35:12.002","scanpoint":"OUT","qty":"20"},
{"barcode":"987654765446","scannerID":"door1","time":"2013-02-13 12:35:15.211","scanpoint":"","qty":""}
]
The server response must be of the same type as when sending a single barcode (see the section "Server Response") - by sending a success or failure message covering the entire batch. Any result message or error message will be shown in the app, eg. "Batch of 2 barcodes transferred successfully." Please note that the special property "open_url" will be ignored in this case - only "result_msg", "show_html", and "err_msg" can be used. If a success message is received by the app it will automatically move the submitted barcodes from the unprocessed folder to the processed folder. If a failure message is received nothing is done and the user is able to try and send the batch to the server again.

Validate against Excel on device

You can also validate a scanned barcode against an Excel spreadsheet (saved in the XML format, not the standard binary format) you have put on the device. In this case the barcode is not sent to the server and not stored in the usual folders 'processed' and 'unprocessed'. It will be stored within the Excel spreadsheet though. This is a good option when you cannot be online (or don't have a server) but still need to validate whether or not the barcode is valid.

The list of valid barcodes must be listed in column A - one barcode per row for as many rows as you need (the validation will be case sensitive). Column B needs to contain the number of times that the given barcode in column A is allowed to be scanned. If you write 1 the app will scan the barcode once successfully but the next time you scan the same barcode it will say it is invalid and will not register it. If you don't care about how many times a barcode is scanned just set this to a high number, eg. 9999. Make sure that there is no other data in the spreadshee, and to ensure a stable processing keep the document free from any formatting and any other non-standard elements. An example Excel file looks like this:

  A B
1 9876543210 1
2 1234567890 1
3 2345678901 1
4 A587UP4044 9999

Make sure that you save the spreadsheet in the XML format (select XML Spreadsheet (*.xml) as the type when you save the document) and not the standard binary xls or xlsx format. Here is an example. The file must be put on the device (on internal memory or SD card, depending on Android version) in the folder /no.winternet.barcodescannerterminal3. When you select this scanning mode you will be asked to select an Excel XML file within this folder.

When a barcode is scanned and the given barcode hasn't already been scanned the max number of times the barcode is stored within the spreadsheet. Column C will contain the number of times it has been scanned, and column D will contain a comma-separated value with the fields in the following order:

  1. The timestamp (in the format yyyy-mm-dd hh:mm:ss.msec where msec is milliseconds) for when it was scanned.
  2. Latitude (if GPS is enabled)
  3. Longitude is also enabled those values will also be stored.
  4. The scanning point, whether scanning IN or OUT (if enabled)
  5. The quantity entered on the keypad (if enabled)

On subsequent scans column C is of course incremented and the same comma-sep. list of values is added to column D, with two underscores (__) separating it from the previous value. For example if 4 of the barcodes have been scanned and if GPS location was recorded for the second one and quantity for the third one the spreadsheet will look like this:

  A B C D
1 9876543210
1
1
 2013-02-26 19:29:35.536
2 1234567890
1
1
 2013-02-28 19:31:48.095,45.527826,-122.601107
3 8451394755
1
1
 2013-02-28 19:31:48.095,,,,15
4 2345678901
1
 
5 A587UP4044
9999
2
 2013-02-28 19:31:48.095__2013-02-28 19:32:00.280

You can do anything you want with the file between each scan - as long as you strictly adhere to these rules.

Send barcode to a PC

You can also connect Barcode Scanner Terminal directly to you PC (instead of connecting to a web server) over a TCP/IP connection when both the PC and the device is connected to the same network.

By running the PC Connector for BST (a free application, no install) it can receive the barcodes from the app and they will be entered where the cursor is located as if you were typing the barcode yourself on the keyboard.

For example, you could have a webpage open with the cursor put in a text input field where the barcode needs to be entered, you then scan the barcode with your device, and it is entered into the field and the form is submitted. Or, you could open Excel and have the barcodes entered on a spreadsheet.

The PC Connector takes up to two arguments, which are both optional:

  1. The port to listen on (default is 84). This needs to match the URL you specify with the app.
  2. The text 'EnterAfter' to make the connector send an Enter key press after entering the barcode. By default it does nothing after entering the barcode.

Example command line with arguments where we listen on port 4800 and send the Enter key press after entering barcode (go to Start and type "cmd" and hit Enter to get to the command line prompt):

BST-PC-Connector-1.2.exe 4800 EnterAfter

When you run the connector it will tell you which URL to enter into the settings of your app. For example it could look like this:

http://192.168.1.100:84?data=%barcode%&scid=%scannerID%&lat=%lat%&long=%long%&loc=%scanpoint%&qty=%qty%

The IP address of course need to match the one of your computer.

The PC Connector runs in your system tray. You can right-click the tray icon and exit the application from there. You can also pause the application (so that it won't be entering barcode sent from the device) and it shows you which port it is listening on as well.

If you need a customized connector application to do other things please contact us.

Custom typing sequence

In case you want to enter other parameters than just the barcode (eg. scan point or quantity) you can define a custom sequence of values and characters to type. The sequence can be defined either in the app or on the command line when starting the PC Connector by defining a sequence of special keywords separated by a dash.

In the app it is done by appending this to the URL:

&typeseq=BARCODE-TAB-QTY-ENTER

On command line you can add a third parameter when starting the PC Connector, eg.:

BST-PC-Connector-1.2.exe 4800 none BARCODE-TAB-QTY-ENTER

The sequence entered on the command line has priority over what is defined in the app.

The special keywords available are:

Send to server

The request

You need to set the server URL in the app to which the information should be sent after scanning. Use the following placeholders for the places where you want to insert the information:

%barcode% (req.) : the scanned barcode
%scannerID% (req.) : ID of the scanner inserted
%lat% and %long% (opt.) : latitude and longitude if you retrieve GPS coordinates as well
%scanpoint% (opt.) : the scanning point selected for the current scan, IN or OUT (if enabled)
%qty% (opt.) : the number that has been entered using the keypad (if enabled)

For example:

https://www.yourdomain.com/scan.php?data=%barcode%&id=%scannerID%&lat=%lat%&long=%long%&op=%scanpoint%&qty=%qty%

Both http and https is supported.

To ensure no caching of requests the following timestamp (a Unix timestamp, which is the number of milliseconds since Jan 1, 1970) is appended to the end of the URL:

&time=[timestamp]

Also the app version number is appended to the end of the URL, eg:

&ver=2.4

If the scanned barcode is 987654321098, the scanner ID is door1, latitude is 45.527826, and longitude is -122.601107 (always in decimal format) it would resolve to this URL:

https://www.yourdomain.com/scan.php?data=987654321098&id=door1&time=1360356028991&lat=45.527826&long=-122.601107
&scanpoint=&qty=

Special characters will be properly escaped.

About GPS coordinates

If latitude/longitude are not available (when not enabled in the app settings) but the placeholders are still present in the URL the last part of the above URL would be like this: &lat=&long=
If GPS coordinates are enabled in the app settings but the device is not able to determine it's location the barcode is not processed at all (neither stored nor sent).

Server Response

The format of the response from the backend server should be a JSON string (properly formatted, UTF-8 etc.) with a couple of properties. Make sure nothing else is outputted, otherwise the app will not interpret the response.

For a successful response it should be like this (a simple string of text):

{"status":"ok","result_msg":"Your own message you want to display on the device (if any) goes here."}

In case of an error the following should be returned:

{"status":"error","err_msg":"Your own descriptive error message to display on the device goes here."}

Additional properties and structures can exist in the response as long as the ones above are always defined. The additional properties and structures will just be ignored by the app.

Different sounds will be played on the device depending on the result of the scan, whether it's an "ok" or an "error" message. See Custom sound files for more information.

Please note that this type of response can be max 1000 characters long. The exception is for the HTML type below (where "show_html" is used) where the max response length is 1 Mb.

To test your server response you can temporarily select "Open in device browser" as the processing mode which will enable you to see the actual response of your server.

Opening a URL or show HTML

(Note that it doesn't make sense to use these options if you are using continuous scanning as the HTML won't be seen.)

If you instead want to show HTML code make a response like this:

{"status":"ok","show_html":"<html><head><meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\" /><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" /><style type=\"text/css\">body { margin: 20px; background-color: black; 
	color: white }</style></head><body>We have got you <b style=\"color: blue\">covered!</b></body></html>"}

Remember to specifically set the background and/or text colors - otherwise you might be showing black text on black background!

Or if you want to open and display a webpage you can pass the URL like this:

{"status":"ok","open_url":"https://www.example.com/thankyou.html"}

These are also processed if you set "status":"error", in which case you don't need to set "err_msg".

Sample PHP script

For a sample backend script in PHP click here.

Send to a Google Docs spreadsheet

If you don't know how to make your own receiving script but still want to send the barcode to the cloud you can send it to a Google Docs spreadsheet. It requires though that you have a website somewhere that supports PHP and where you can put this PHP file. Before uploading it to your server you need to modify it according to the following simple instructions:

  1. Go to Google Docs.
  2. Click Create and select Form.
  3. Name it whatever you want.
  4. Add as many questions as you want columns in your spreadsheet. Make sure the Question Type is "Text". See PHP file for which values the app will be sending. Normally you will want to make the same number of columns.
  5. Then click "Choose response destination" in the top and select your desired preferences.
  6. Click "View live form".
  7. Retrieve the ID of the form by taking the part of the URL between the last two slashes. Eg. if you URL looks like this:

    https://docs.google.com/forms/d/1uSrajQiDt2W7pAaYh-k7y2-JYsXX5lKTZbWyhiWpfok/viewform

    ...your form ID is 1uSrajQiDt2W7pAaYh-k7y2-JYsXX5lKTZbWyhiWpfok.
  8. In the PHP file replace INSERT-FORM-ID-HERE with your form ID.
  9. From the live form we also need to retrieve the name of each input field and insert that into the PHP file. To find the name right-click on the given input field and select "Inspect element". You should then see something like this:

    <input type="text" name="entry.867567824" value="" id="entry_867567824" ... >

    For this field your form input name is entry.867567824 according to name attribute in the HTML element.
  10. For each of your fields in the form find the name and insert it into the matching field in the PHP file where it says INSERT-FORM-INPUT-NAME-HERE.
  11. Upload the PHP file to your website and set the server URL in the app to point to that address - using the same parameters (like 'data', 'id', etc) as suggested in the Send to server section. The server must support minimum PHP 5.2 (or 5.0 if you remove the json_encode() call and manually generate the JSON string).

Use of external scanner

You can connect a USB or bluetooth scanner (or basically any device that will type the barcode as regular keyboard input) instead of using the in-built camera on the phone to do the scanning. To enable this go to the Settings tab and under "Scanning device" select "External USB/Bluetooth or manual". When you go back to the Scan tab you will instead see a text input field. Your external device will be entering the barcode into this field and when it sends a Carriage Return (like when you press Enter) the app will send the entered barcoce to the server.

Custom sound files

Different sounds will be played on the device depending on the result of the scan whether it's an "ok" or "error" message. A third sound is played if something else goes wrong and the validity of the barcode couldn't be determined - eg. error in reading Excel file, server could not be reached, or server returned invalid data etc.

If you don't like the default sounds you can put your own sound files into the /no.winternet.barcodescannerterminal3/sound_files/ folder on the device (on internal memory or SD card, depending on Android version). In the Settings tab within the app you can then select which sound you want for each of the 3 responses.

The sound files can be in one of the following formats:

The internal scanner can also be set to give an audible notification (or to vibrate) at the time a barcode is recognized (before it is sent off for validation or to be stored). See here.

Launch app from browser

If you want to launch the app from a link on a page in the browser you can use one of the following methods:

<a href="intent://scan/#Intent;scheme=bst;package=no.winternet.barcodescannerterminal3;end">Launch</a>
<a href="bst://scan/?">Launch</a>

Change Log

4.0.2 -- April 20, 2020

* Clarified how to cancel a subscription

4.0.1 -- April 7, 2020

* Always check that app has permission to use external storage before accessing it

4.0.0 -- April 5, 2020

* Ensure compatibility with the latest Android versions

3.8 -- June 30, 2016

* Bugfix in subscription handling
* Ensure app works on newer Android versions 5.0 and 6.0
* Automatically scale page to fit when response is an HTML page
* No longer allow https with untrusted certificates (Google Play requirement)
* Minor bug fixes

3.7 -- February 25, 2016

* Option to auto-launch scanning when app starts

3.6 -- June 26, 2015

* Option to launch the app from the browser and via intents
* Disabled autocorrect on inputs for manually entered barcode and scanner ID

3.5 -- June 24, 2015

* Adjusted font sizes on high density screens

3.4 -- November 23, 2014

* Minor improvements

3.3 -- October 12, 2014

* Option to set scan points (whether scanning in or out)
* Option to enter a number (eg. a quantity) and send/store along with the barcode

3.2 -- September 25, 2014

* Allow scanning of any type of barcode, not only text

3.1 -- September 7, 2014

* Ensure continuous scan works properly. Made it much faster as well.
* Option to enable/disable sound at the time when the barcode is recognized by the scanning module
* Option to vibrate when barcode is recognized by the scanning module
* Option to limit scanning to only certain barcode formats (to make scanning faster)

3.0 -- August 24, 2014

* Option to use LED light when scanning
* Option to use front-facing camera when scanning
* Support all the latest Android devices

2.5 -- March 17, 2014

* Prohibit scanning new barcodes while processing

2.4 -- February 26, 2014

* Option to use Barcode Scanner app from the ZXing Team for barcode recognition
* Option to use https in server URL
* Automatically append app version to server URL

2.3 -- November 8, 2013

* Fixed bug that caused the Scan button not to show up until "Use external scanner" had been toggled

2.2 -- October 31, 2013

* Option to use your own custom sounds

2.1 -- March 3, 2013

* Validate against local Excel spreadsheet

2.0 -- February 25, 2013

* Export stored barcodes to Excel or CSV
* Send stored unprocessed barcodes to server in batch
* Option to store/send GPS coordinates together with barcode

1.2 -- February 16, 2013

* Option to store scanned barcodes on the device
* Allow up to 1 Mb response for HTML responses

1.1 -- January 27, 2013

* external/Bluetooth scanner option
* HTML response option
* URL response option

1.0 -- December 2011

* Initial version