The intention of this example project is to demonstrate Bluetooth/USB/WIFI communication between Android applications and a Boca Systems Lemur printer. This allows anyone to test the capabilities of their Boca Systems printer. This application, BocaPrinter, was written using Android Studio Version 2.2.3 and was targeted and tested on an Android tablet running version 6.0.1 know as Marshmallow. The Boca Systems Android SDK is used by this application to perform the lower level communication and conversion tasks needed. See the Boca Systems Sample Code & SDK section at the end of this document for more details.

The intent of this document is to demonstrate how to use this application to test a Boca Systems Bluetooth printer by printing text, test tickets and images. This is not intended to be a ticketing system. When the application is started, the first view to load is shown here with several buttons disabled. Once a user establishes a connection to a printer via Bluetooth/USB/WIFI, the buttons performing test functions will be enabled.

Bluetooth Pairing & Connecting

When using Bluetooth it is necessary for the tablet to be paired with a Boca Systems Bluetooth printer once running this application. Start by tapping on the Bluetooth Scan button shown above. A list of Bluetooth devices within range will be displayed on the right side of the screen as shown below. On some Android based tablets, it is necessary to go to “Settings/Bluetooth” and perform the pairings there before running this application and scanning for Bluetooth devices. If no Bluetooth devices are shown in the list, as shown below, go back to “Settings/Bluetooth” and pair them there. Then rerun this application. While in Scan mode the Bluetooth Scan button text will display Bluetooth Connect. To actually connect to a device, tap on one of the devices displayed in the list. Notice the prompt in the Printer Status text area.

Once a device is selected, this application will attempt to connect. When connecting for the first time since the printer is powered on, confirmation may be required. Click OK. As the connection is being established a message is displayed “Attempting to connect, please wait”, as shown below.

Upon successful completion of the connection, the status is displayed as shown below, the other connection buttons are disabled and the function buttons will be enabled. If by chance the connection is unsuccessful, try turning the printer off and then back on. After the printer finishes re-initialization, including Bluetooth, try to connect again.

USB Connecting

When intending to communicate via the USB port on the tablet, by connecting directly to a Boca Systems printer USB port, it is necessary to use an On-The-Go Adapter. Once the OTG adapter is plugged into the tablet, plug a standard USB cable into the adapter and the other end into the printer, as shown below.

Next, tap on the USB Connect button shown below. You may be prompted for permission to allow this application to access the USB device. Click OK to continue.

Once the connection is established the “Connected” message will be displayed in the status message area near the bottom of the screen.

WIFI Connecting

When intending to connect to a Wi-Fi capable Boca Systems printer it is necessary to first enter the printers IP address in the “FGL command or IP address” text field as shown below. Second tap on the WIFI Connect button. The attempting to connect message will be displayed as shown.

Once the connection is established the “Connected” message will be displayed in the status message area near the bottom of the screen.

Functional Testing

Once any of the three connections has been made functional testing can begin. To verify Bluetooth/USB/WIFI connections and printer functionality, there are multiple test functions that can be performed as well as printer configuration items that can be controlled. If by chance the printer being tested is a multi-path printer, be sure to select the Printer Path configuration item to use whichever of four possible paths that is desired. The examples below which include screen shots are performed via Bluetooth, however they work the same via USB or Wi-Fi.

1. Connect/Disconnect via Bluetooth/USB/WIFI

2. Transmit FGL Text

3. Print Test Ticket

4. Print Cut

5. Print No Cut

6. Print Image or Text file

7. Download Image File as Logo

8. Print Logo, previously downloaded

9. Scale Image

10. Dither Image

11. Select Printer Path

12. Control Stock Size

13. Set Resolution based on printer

14. Control orientation for image files

15. Clear Printer memory of previous downloads

16. Receive Status back from the printer

17. Display help screen (This file).

Test tickets and custom tickets are set up for Concert Stock (2.0 x 5.5 inches) and Receipt Stock (3.25 x 8.0 inches).

When testing is complete on one printer, tap on Disconnect and choose another Boca Systems printer, if needed.

FGL Text Commands

To transmit text commands to the printer, enter an FGL command such as <S1>, <S2> or and click on the “Transmit FGL Text” button. This will generate a response from the printer. If a command is sent, the printer will eject a ticket. An <S2> command is a request (from the printer) for the current ticket count and firmware version. Below you can see that 18 tickets have been printed since the printer was turned on. The current version of firmware in this printer’s PROM is FGL46M161. Two more Test Tickets were printed followed by the <S2> command again. Notice the ticket count after the two Ticket ACKs now shows 20. An <S1> command will generate an X-On response from a connected/ready Boca Systems printer.

When writing one’s own code the SDK library method SendString will be used for this function. A string would be defined as a String and transmitted as shown below and in the example code.

String Test = ”<RC100,100><F11>This is a test”;

SendString (Test);

Returned Printer Status

Should the printer actually have a problem such as “Out Of Stock” or “Cutter Jam”, the status will be reported back to the application as shown here. In this example, the last three tickets successfully printed as the printer ran out of stock. A status check shows “Ticket ACK” three times, an “Out of Tickets” and an “X-Off”. A critical error message is typically followed by an X-OFF to signify the printer is no longer ready and is waiting for human intervention. Once the problem is solved (in this case the stock is reloaded), a status check will show that an X-On was transmitted from the printer to signify it is ready again. In the example displayed below once the printer is reloaded then the fourth ticket prints.

Load Images onto Android Tablet

If someone is interested in printing an image file as part of the test, it may be necessary to put some image files in the tablet. To transfer and store image files such as BMP, JPG and PDF onto the test Android tablet, we recommend either of two ways.

The first method is to simply email the files as an attachment to an email account used on the tablet and then save the attachment into the “Documents/” folder.

The second way is with the use of an OTG (On the go) adapter and a USB flash drive. This is convenient when transferring a large number of files. The OTG adapter and flash drive are both very inexpensive.

Once plugged in files can be transferred either way, to/from the flash drive.

There is one other option which involves taking a picture with the tablet, itself. The path may vary but typically pictures taken by the tablet itself can be found in the DCIM/Camera folder. This generates a color JPG file which can be quickly converted to a monochrome BMP file by this application. This works but the JPGs generated tend to be large. The Bluetooth transfer speeds are not very fast so tickets are delivered to the printer slowly which makes it seem like the tickets takes longer to print. The “Data” light on the side of the printer will continue to blink as the data is delivered from the tablet to the printer. Once the printer “Data” light stops blinking, all data has been transmitted and the printer prints the image quickly.

Printing Images

The Boca Systems printer prints in monochrome B&W only. The printer firmware interprets monochrome BMP files, so raw monochrome BMP can be delivered to the printer and printed without the use of a printer driver. This application will convert & dither color BMP, JPG, PNG and PDF files into monochrome BMP so that they can be printed as part of an effort to test the printer and the Bluetooth bi-directional communication.

Before selecting an image to print, there are two more configuration settings that can be used, if desired. A BMP, JPG, PNG or PDF image can be printed actual size, or scaled to fit the stock size chosen. Please adjust the Stock Size and Scale selection shown below. Currently selected and displayed is Concert stock size and actual image size. The option also exists to scale the image to fit the stock size currently selected. There is also control whether to Dither an image or not. For graphical/pictorial images dithering may produce a better printed image. For something like a barcode it is better not to dither as the sharper B&W lines make a better image for scanning. Before tapping on the Print Image or Text File button, select one of the two file types from the radio button provided.

When selecting a BMP, JPG or PNG file type, tapping on the Print Image or Text File button will cause the default images directory (as shown below) to be opened so that an image file can be selected.

When selecting radio button PDF or TXT file type, tapping on the Print Image or Text File button will bring a user to the tablets SDCARD directory system where folders/files are stored as shown here. From this screen, a user can select a directory leading to the stored PDF files.

In this example the “concert_stock_landscape.pdf” file was chosen and is displayed below. The PDF image is converted to monochrome BMP and then delivered to the printer. Once printed successfully a “Ticket ACK” is returned to the application and displayed in the printer status area, as shown below.

Scale Images or Not

When printing an image through this application it can be printed based on its actual size or scale up/down to fit the ticket size being used. The ticket size is control by the application “Stock Size” configuration item. When writing code a call to ChangeConfiguration, could precede calls to SendFile, DownloadLogo or PrintLogo.

Dither Images or Not

Dithering is an intentionally applied form of noise used to randomize quantization error, preventing large-scale patterns such as color banding in images. When an image is converted from color to monochrome B&W dithering is needed to smooth out the transition of color to something that looks like grayscale. The dithering process is useful for images, but not so much for text and barcodes. In the case of barcodes the sharp edges from black to white is desirable. For example, if someone intends to create a PDF file containing an image, text and barcodes in color, then use this application to convert the entire PDF page to monochrome it will be noticeable that the dithering does not satisfy all three parts. With dithering on, the image may look fine, the text OK, but the barcodes will not have sharp edges. With dithering off, the image may look like a silhouette (not very recognizable), the text pretty sharp, but the barcodes will be sharp. To achieve the best results an image can be sent to the printer and dithered separately. Remember an image, text and barcodes can be sent individually all followed by a form feed. When writing code calls to the SDK library can vary. Using SendString with FGL commands can replace all other SDK library method call, but the puts the burden of knowing all the FGL commands on the programmer. Using some of the other SDK methods simplifies that. To build a semi generic ticket with specific row and seat numbers which change on each ticket, the code could look something like this:

ChangeConfiguration (”<P1>”,300, false, true, 0,”<LM>”); //Turn dither on

DownloadLogo (filename, 1); //Download JPG as Logo #1

ChangeConfiguration (”<P1>”,300, false, false, 0, ”<LM>”);//Turn dither off

//Pseudo code - Loop to print multiple tickets incrementing row and seat

SendFile (filename, 50, 80); //Send PDF with barcode & some text

PrintLogo (1, 200, 150); //Print logo #1

SendString (”<RC300,10>ROW: <RC300,100> SEAT:”); //Labels for row and seat

//Build outgoing string

String outgoing = ”<RC300,30>” + String.valueOf(row);

SendString (outgoing); //Send row assignment

outgoing = ”<RC300,130>” + String.valueOf(seat);

SendString (outgoing); // Send seat assignment

PrintNoCut (); //Form feed no cut

// Pseudo code - End loop here

PrintCut (); //Cut after last ticket if desired

FGL Text Files

Text files that are useful to a Boca Systems printer are typically filled with FGL commands and strings to be printed. This is the fasted way to print tickets, since the data transmitted to the printer is limited to raw text instead of large graphical files. By first downloading logo/graphical files into the printer memory once (covered in logo section) and then using FGL text commands to print them multiple times response is much faster. Color graphical files (PDF, BMP, JPEG and PNG) are only converted to monochrome B&W BMP files once and transmitted to the printer only once. Then by transmitting just text strings and commands for each ticket printed, very little redundant data is transmitted from the tablet to the printer. The current FGL Users guide can be downloaded from this link.

http://www.bocasystems.com/documents/fgl46.doc

Through this application there are two ways to send a text file to the printer. One is to print a file included in the assets folder with the project. The other is to print a text file saved on the tablet.

The quickest and easiest way to test the printer connection is to print a test ticket. There are three text files included with this project that generate Boca Systems standard test tickets. To print an FGL test ticket, click on the Print Test Ticket button. NOTE - The Logo ID# field has a second function which comes into play here. This data entry field can also be used to control the number of Test Tickets printed. The valid range is 1 to 1000. If you change this field to a 5 and then press the Print Test Ticket button, five test tickets will be printed. The application will check the current resolution (200/300/600 DPI) setting to determine which text file is to be transmitted to the printer. In this example the printer being tested has a resolution of 300 DPI. Should the printer being tested be 200 DPI or 600 DPI, select that radio button first and then tap on the Print Test Ticket button. The test ticket will demonstrate the printer capabilities with logos, barcodes and a variety of text fonts along with numerous printer configuration items that will inform the user of the printer’s actual settings.

The second way to print a text file is to select the “PDF or TXT” file type radio button as shown below and then tap on Print Image or Text File button. This will bring a user to the tablets SDCARD directory system where folders/files are stored as previously shown above. From this screen, a user can select a directory leading to the stored text files. A text file filled with FGL commands will not be displayed on the screen like jpg, png, bmp and pdf files. Once the text file is sent to the printer and the ticket is generated, then status can be read.

Download Image & PDF Files as Logos

There is user memory space available in the printer itself which can be used for downloading graphic files as logos. This can be advantageous when printing certain images on multiple tickets. The slowest part of the entire printing process is the transmission of data from a PC, Phone or Tablet, to the printer. Regardless of port selection and hardware used the transmission of the data is always the slowest link in the chain. By downloading/transmitting logos into the printer memory once and then printing the logo image many times from the printer memory, a substantial amount of time can be saved.

For example, it can take a second to convert a color JPG into a monochrome BMP image, depending on the size of the file and dithering options. Let’s assume it takes eight seconds to transmit that image from a tablet via Bluetooth to the printer. Depending on the amount of data to process it typically takes a little over a second for the printer to actually print one ticket. The entire process described could take up to ten seconds to print one ticket. That doesn’t sound too bad, unless your ticketing system intends to do that for a hundred tickets. This method could potentially take up to 1000 seconds (16 minutes) to print 100 tickets. Instead of transmitting the image data for each ticket printed, the image is downloaded into the printer once and then via an FGL command such as <LD1>, the image is called up from the printers internal memory for printing, the time to print 100 tickets could be reduced to close to 100 seconds. If you printed an image when reading the section above you may have noticed how long the data light on the printer blinked. When blinking, the data is being transmitted from the tablet to the printer. Try it again via logo and the delay only happens once per image, not once per ticket.

As previously mentioned Bluetooth is not known for speed. Printing images means transmitting a lot of data between the Android tablet and the printer. Sometimes speed is not an issue. If printing just one or two tickets with a specific image on each, via Bluetooth, it may not matter that it might take 5 to 10 seconds just to transmit the image per ticket. If however a generic image is to be printed on a lot of tickets it, is advisable to download the image into printer memory once and then use it repeatedly. With a monochrome image (or many monochrome images) stored inside the printer it is not necessary to transmit the image with each ticket printed. With the use of the FGL logo command <LD#> an image can be called up repeatedly from the printer memory and placed on each ticket in less than a second. The first two steps to download and image or PDF as a logo, are the same as printing them.

1. First select file type.

2. The Image/PDF file will be displayed in the image viewer box.

3. Enter a Logo ID# in the text field provided, or use the “1” provided. When planning to download multiple logos, for example, five logos then use numbers 1 through 5. If a logo number is reused, the old logo will be overwritten by the new logo. When downloading multiple logos Boca Systems suggest the logo filenames and logo numbers be recorded to be easily recalled when used.

4. Press “Download Logo” button and choose the image/file as described above. If the Boca Systems printer came with an LCD, “DOWNLOADING!” will be displayed as the data is downloaded. Once completed the LCD will display “DOWNLOAD OK!” The DATA light will also be blinking quickly as the data is being transmitted.

When writing code SDK calls to DownloadLogo, ChangeConfiguration, PrintLogo and ClearMemory. ClearMemory send the FGL command “ESC c” to the printer which will clear the user space in the printer flash memory of all downloaded logos and fonts. DownloadLogo would need the filename and Logo ID number provided as parameters.

ChangeConfiguration (@”<P1>”,300, false, true, 0,@”<LM>”); //Turn dither on

DownloadLogo (filename, 1); //Download JPG as Logo #1

ChangeConfiguration (@”<P1>”,300, false, false, 0, @”<LM>”);//Turn dither off

Each logo downloaded into the printer memory is assigned a logo ID number. When downloading multiple logos, assign each a unique ID number between 1 and 1000. It is important to keep track of the logo ID numbers used and the logos associated with each number. That logo ID number is then used to identify a specific logo to print. This can all be tested using the Download Logo and Print Logo buttons shown in the picture above. Also notice the Clear Printer Memory button down near the bottom of the screen. This button calls the SDK function ClearMemory which will delete all user previously downloaded content from the user download space.

Print Logos

Then a simple FGL text command can be used to print the image from the printer’s internal memory, which is much faster. After successfully downloading a logo, this step can be tested by entering an FGL string in the text field. It can also be completed through a text file filled with FGL commands. This application can be used to test. When writing an application calls to SDK methods such as PrintLogo, SendString and SendFile will accomplish what this application is demonstrating.

Test. First enter a logo ID number in the field provided, tap Download Logo button, select the image file as described above and the file will be transmitted to the printer. Nothing will be printed at this time. Repeat the process multiple times to load the printer with several logos, each time changing the logo ID number, such as 1 through 5. Once completed test print each logo by entering the associated logo ID and tap Print Logo button. The logos print quickly now. Now if writing a ticketing system the FGL commands/SDK calls can be used to print multiple tickets quickly, by transmitting a small amount of changing text per ticket with logos already in the printer.

When writing one’s own code the SDK library methods SendString and/or PrintLogo can be used for this function. Any string would be defined as a String and transmitted as shown below and in the example code, assuming a logo #1 has been downloaded.

String Test = ”<RC100,100><F11>This is a test<SP200,200><LD1>”;

SendString (Test);

This will cause logo #1 to be put in the graphic space starting at row 200 and column 200 along with the text. Or printing the string and logo could be accomplished as follows using less raw FGL.

SendString (RC100,100><F11>This is a test”);

PrintLogo (1,200,200);

Boca Systems Sample Code & SDK

Contained in this HTML document are some short snippets of code from the sample project. The sample project source code in its entirety is also available from the Boca Systems web site. See the following link to download a zip file with a copy of the sample source code named BocaLibTester and the SDK file named libBocaAndroidSDK.aar.

http://www.bocasystems.com/documents/android_sample.zip

The zip file provides the sample code project, the SDK library file, this HTML file and an assortment of text, image and PDF files to use for testing. The sample source code is available “AS-IS”. It demonstrates calls to the Boca Systems Android SDK. The sample code is available to Boca Systems customers who intend to write their own code. The SDK provides multiple methods to open, close, write and read between an Android tablet and a Boca Systems printer equipped with Bluetooth interfaces. It also provides methods needed for converting color images to monochrome (black and white) BMP images for the printer. Using the SDK simplifies the code development process by handling most of the low level communication and conversion tasks in the methods provided. Most of the SDK methods allow a coder to perform certain functions without knowing much of the FGL command language. The use of the SendString and the SendFile (for TXT files) SDK methods allows the coder to execute any FGL commands not covered by the other SDK methods.

The Boca Systems Android SDK library (Version 1.0) methods are highlighted in bold below.

Boca Systems SDK Library Routines

_____________________________________________________________________________________________________________________

Start or end a Bluetooth session

BOOL OpenSessionBT (String device, Context context);

void CloseSessionBT ();

_____________________________________________________________________________________________________________________

Start or end a USB session

BOOL OpenSessionUSB (Context context);

void CloseSessionUSB ();

_____________________________________________________________________________________________________________________

Start or end a Wi-Fi session

BOOL OpenSessionWIFI (String Ipaddress, Context context);

void CloseSessionWIFI ();

_____________________________________________________________________________________________________________________

Alter printer configuration items from their default values. . It is advisable to maintain a current copy of each of the parameters below in the main application. When a call to ChangeConfiguration is needed, change the variable of current interest and then make the call.

Parameter values and limits are:

Path <P1> to <P4>

Resolution 200, 300 and 600

Scaled true or false

Dithered true or false

Stocksizeindex 0 to 8

Orientation <LM> or <PM>

void ChangeConfiguration (NSString *path, int resolution, bool scaled, bool dithered, int stocksizeindex, NSString *orientation);

_____________________________________________________________________________________________________________________

Send string to the printer. This can be character data to be printed on the ticket or it can be FGL commands to be executed by the printer

void SendString (NSString *string);

_____________________________________________________________________________________________________________________

Send a file to the printer for printing. Supported file formats include suffix *.txt, *.bmp, *.png, *.jpg, *.jpeg and *.pdf. When transmitting a text file the row and column parameters will not be used. With any of the other file they will be used for positioning. Limits for row and column vary based on the size of the stock used, orientation and the DPI resolution. For example using receipt stock (3.25 x 8) in landscape mode on a 300 DPI printer, the limits can be calculated as:

RowMax = 3.25 * 300 = 975

ColMax = 8.0 * 300 = 2400

bool SendFile (NSURL *filename, int row, int column);

_____________________________________________________________________________________________________________________

Send an image file to the printer to be stored in user space as a logo. Supported file formats include suffix *.bmp, *.png, *.jpg, *.jpeg and *.pdf. The logo ID number range is 1 to 1000.

bool DownloadLogo (NSURL *filename, int idnum);

_____________________________________________________________________________________________________________________

Print a previously downloaded logo. When printing a logo on a ticket, the row and column parameters will be used for positioning.

bool PrintLogo (int idnum, int row, int column);

_____________________________________________________________________________________________________________________

Clear all user space memory.

void ClearMemory ();

_____________________________________________________________________________________________________________________

Force printer to eject ticket with printed material (data, text and images) including cutting the ticket.

void PrintCut ();

_____________________________________________________________________________________________________________________

Force printer to eject ticket with printed material (data, text and images) without cutting the ticket.

void PrintNoCut ();

_____________________________________________________________________________________________________________________

Read status back from printer in the form of a string.

NSString *ReadPrinter ();