First this application is used to demonstrate Wi-Fi and Bluetooth communication between iPad applications and a Boca Systems Lemur printer. This is an application to test the printer. It is not intended to be a ticketing system. The intent of this document is to demonstrate how to use this application to test print text and images on a Boca Systems printer. Whether using Wi-Fi or Bluetooth it is necessary for the iPad to be connected to the Wi-Fi network or paired with Bluetooth printer through the IOS Settings screen, before running this application.

The second possible use is for developers that would like example code showing calls to the recently developed Boca Systems iPad SDK. For details see the Sample Code & SDK section below.

This application (Version 5.0) was written using Xcode Version 7.3.1 and was targeted and tested using iPads with IOS 7, 8, 9, 10.

Operating System Connection

In this case an infrastructure Wi-Fi connection has been established between the iPad and the local area network named MicrochipDemoAP.

Wi-Fi Settings Screen

In this case a Bluetooth paring has been connected between the iPad and the Boca Systems Bluetooth printer name Boca371954.

Bluetooth Settings Screen

WiFi or Bluetooth Connection

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 Wi-Fi or Bluetooth, the buttons performing read/write functions will be enabled.

In this document both Wi-Fi and Bluetooth connection examples are used.

To establish a connection to a Boca Systems Wi-Fi printer, enter the IP address of the printer and click on the Wi-Fi connect button. When writing code a call to the SDK method OpenSessionWiFi is needed.

A keyboard will appear whenever a user clicks on any text entry field such as IP and commands. The keyboard will disappear when the user clicks on the “Done” button, any function key or the main background.

To establish a connection to a Boca Systems Blue Tooth printer click on the Blue Tooth connect button. The application will open a Bluetooth session with the printer paired on the “Settings Screen” shown above. When writing code a call to the SDK method OpenSessionBT is needed.

When unable to connect, for whatever reason (printer off, not ready, out of range, wrong IP address, etc.), the iPad will display this alert message for Wi-Fi.

Or for Bluetooth this will be displayed.

Function Outline

Once connected to a Boca Systems printer, the “Connect” button changes to “Disconnect” and the disabled function buttons are enabled as shown here. From here a user can:

1. Configure the application with printer and ticket stock information such as printer path, resolution, BMP print orientation and stock size.

2. Enter and transmit FGL text commands to the printer. (Send String button)

3. Send TXT files to the printer, saved in the iPad, filled with text and FGL commands. (Select File & Print/Send Buttons)

4. View and print PNG, BMP or JPG images contained in the saved photo directory in the iPad. (Select Image & Print/Send Buttons)

5. View and print PDF files saved in the iPad. (Select File & Print/Send Buttons)

6. Download images and PDFs into printer “User Memory” as a logo and assign a logo number. (Select Image, Select File & Download Logo Buttons)

7. Print logos previously downloaded via FGL commands based on logo number. (Send String, Select File & Print/Send Buttons)

8. Scale and Dither options can be used or skipped for images printed or downloaded.

9. Read status messages returning from the printer via Wi-Fi or Bluetooth. (Read Status Button)

10. Display help screen. (Help Off/On Button)

Configure Printer Items

Certain printer configuration items and printer functions can be controlled through this application. The default settings, for each of these six items are highlighted in blue, such as “Printer Path 1”. These items include:

1. Printer Path – Most Boca Systems printers are manufactured with only one path. This item is only relevant to customers with a multipath printer. To print through path 2, 3 or 4 press the path button and a command such as <P2>, <P3> or <P4> is sent to the printer.

2. Resolution – The dots per inch (DPI) setting can be altered according to need. The majority of Boca Systems printers are shipped with 300 DPI print heads so that is the default. Should a printer be 200 DPI or 600 DPI, press the appropriate button to inform the application. This value affects positioning and scaling.

3. Orientation – This setting controls the images being printed in Landscape or Portrait mode. An FGL command <LM> or <PM> is sent to the printer before an image is printed.

4. Stock Size – Standard Boca System stock sizes can be identified to the application for image positioning, orientation and scaling. One of the most popular choices is Concert stock with Landscape orientation. The application would consider this to be a 2 x 5.5 inch ticket. In portrait mode the application would consider this to be 5.5 x 2 inch ticket and position images accordingly. Letter size stock is used only for custom stock, not one of the listed standard sizes. The following are the standard stock sizes currently available, all listed in landscape mode.

a. Concert (2 x 5.5) Stock Index value 0.

b. Cinema (3.25 X 2) Stock Index value 1.

c. Credit Card (2.13 x 3.37) Stock Index value 2.

d. Receipt (3.25 x 8) Stock Index value 3.

e. Ski (3.25 x 6) Stock Index value 4.

f. 4 x 6 Stock Index value 5.

g. Wristband 1 (11 x 1) Stock Index value 6.

h. Wristband 2 (11 x 1.328) Stock Index value 7.

i. Letter (8.5 x 11) Stock Index value 8.

5. Scale Image – Image sizes are typically controlled upon creation, not at print time. This application offers two options only. An image is printed based on its actual size or it can be adjusted to the stock size and orientation currently selected.

6. Dither Image – As a color image (PNG, JPG, BMP and PDF) is converted to monochrome black and white it is necessary to dither the image to make it look like grayscale. It makes the different between silhouettes of a person versus a black and white (grayscale) reproduction of that person. When printing artistic graphics, barcode and even text, dithering may not be wanted. Sometimes the sharp edges (barcode) are preferable to the gradual soft edges of a pseudo grayscale (image). Most tickets include images, text and barcodes. The dithering can be controlled by sending images separate from barcodes and text. This is covered in more detail in the Dithering section below.

When writing code calls to SDK method ChangeConfiguration will be used to accomplish what the application is demonstrating.

FGL Text Commands

Shown in multiple screen shots above the text field is initialized with the string:

<RC100,100><F11>This is a test

Using this string is the easiest way to quickly check the Wi-Fi or Bluetooth connection. Upon pressing the “Send String” button the text string will be transmitted via the current connection to the printer. A ticket will be ejected from the printer with “This is a test” printed on it at row 100, column 100, using the F11 resident font. To transmit other text commands such as printer status commands to the printer, enter an FGL command such as <S1>, <S2> or and click on the “Send String” 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. An <S1> command will generate an X-On response from a connected/ready Boca Systems printer. Press the “Read Status” button to read data returning from the printer. A “Ticket ACK” will be generated by the printer for each ticket successfully printed.

When writing one’s own code the SDK library method SendString will be used for this function. The above string (or any string) would be defined as a NSString* and transmitted as shown below and in the example code.

NSString *Test = @”<RC100,100><F11>This is a test”;

SendString(Test);

Load Image, PDF, Text Files onto iPad Tablet

In the test efforts, should someone want to include PNG, BMP, JPG, PDF or TXT files, the files will have to be transferred to the iPad. To accomplish this, files can be emailed to the iPad, use iTunes or an SD card reader. The obvious final alternative is to take the picture with the iPad camera. Image files are stored in the iPad “Photos Library” and are accessed through the application via the “Select Image” button. The PDF & TXT files when saved on the iPad from an email attachment will be stored in the application sandbox, by choosing the association when prompted. These files will be accessed through the application via the “Select File” button from the file name list displayed.

When printing images via the Bluetooth connection, it can be a bit slow. A Bluetooth connection is basically a wireless serial port. So even at its highest speed setting it will be slower than Wi-Fi. An alternative to transmitting images with each ticket printed, an image can be downloaded as a logo into the printer memory once and then printed many times, very quickly by using the FGL command <LD#> and referring to each image by the logo identification number. Details about downloading and printing logos are covered in the download and print logo sections below.

FGL Text Files

There are files included with this project that generate Boca Systems standard test tickets and other custom tickets. These are text file containing FGL text commands and printable strings. To print an FGL test ticket from one of these files:

1. Click on the “Select File” button. File names (TXT & PDF) saved, on the iPad, in the application sandbox will be displayed in the file picker view.

2. Scroll through the spinning wheel of file names listed, stopping with the TXT file of choice in the middle, between the two lines.

3. Click on the “Print/Send” button to deliver all the text commands to the printer.

The test ticket will demonstrate the printer capabilities with logos, barcodes and a variety of text fonts along with numerous printer configuration items showing the printer’s actual settings.

Also included in the zip file are a few text files which demonstrate printing previously downloaded logos, QR barcodes, etc. See logo sections below for more details. After any ticket has printed, click the read status button to see the “Ticket Ack” return from the printer, if interested.

View and Print Image Files

Any currently supported image file (PNG, JPG, JPEG and BMP) which can be selected from the iPad Photo Gallery can be displayed by this application in the box provided as shown below. Once displayed, it can then be converted to monochrome and printed.

1. Press “Select Image” button and the pop up photo gallery will be displayed.

2. Select an image from the photo gallery by tapping on it. The popup photo gallery will close and the selected image will be displayed in the image viewer box.

3. Press the “Print/Send” button to transmit the monochrome version of the image to the printer via the currently open port.

View and Print PDF files

The PDF files are printed in a similar fashion. The biggest difference is the PDF files are not stored in the iPad photo gallery. Through file type/application association PDF files can be stored in the application sandbox and then retrieved from there.

1. Press “Select File” button and the file picker viewer will be populated just below the “File Names” label.

2. Scroll through the spinning wheel of file names listed, stopping with the PDF file of choice in the middle, between the two lines. The PDF file image will be displayed in the image viewer box.

3. Press the “Print/Send” button to transmit the monochrome version of the PDF image to the printer via the currently open port.

Any of the three sections above could be coded with the use of SDK methods ChangeConfiguration and SendFile. This is demonstrated in detail in the sample project code.

Download Image & PDF Files as Logos

As previously mentioned Wi-Fi and Bluetooth are not known for speed, especially Bluetooth. Printing images means transmitting a lot of data between the iPad 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. Press “Select Image” or “Select File” button and choose the image/file as described above.

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. 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 using a Wi-Fi connection, the data light will blink slowly as random network traffic is ignored by the printer. Do not be fooled. When real data is transmitted the data light will blink much quicker.

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.

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. An example FGL command, which can be added to the text field, that will print a new test ticket, assuming a logo #1 has been downloaded is:

<RC100,100><F11>This is a test<SP200,200><LD1>

When writing one’s own code the SDK library method SendString can be used for this function. The above string (or any string) would be defined as a NSString* and transmitted as shown below and in the example code.

NSString *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.

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

PrintLogo (1,200,200);

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 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

NSString *outgoing = [NSString stringwithformat:@”%@%d”, @”<RC300,30>,row];

SendString (outgoing); //Send row assignment

outgoing = [NSString stringwithformat:@”%@%d”, @”<RC300,130>,seat];

SendString (outgoing); // Send seat assignment

PrintNoCut (); //Form feed no cut

// Pseudo code - End loop here

PrintCut (); //Cut after last if desired

Returned Printer Status

After a ticket is printed, after a command (or series of commands) is sent, click on the “Read Status” button, to retrieve and display the answer from the printer, as shown here. In this case, the printer response to an <S2> and then three tickets printed is displayed. The current ticket count is initially displayed as 1. The ticket count represents the number of tickets printed since the printer was powered on. The current firmware version in this Boca Systems printer is FGL-46M125.

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 four of five tickets successfully printed as the printer ran out of stock. A status check shows “Ticket Ack” four times, an “Out Of Stock” and an X-Off. A critical error message, such as “Out Of Stock”, is typically followed by an X-Off to signify the printer is waiting for human intervention. In this not ready state, he printer will not respond to any commands until the problem is solved. 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. Then the fifth ticket will successfully print as shown by the fifth “Ticket Ack”. When writing code calls to SDK library method ReadPrinter will read whatever status is available in the printer buffer. Some ticketing systems skip this step as it is optional. Either the ticket prints or it does not. If the stock runs out in the printer this is easily determined and fixed. The calls can take place inside a loop, so that status is read in between each ticket printed or at the end after multiple tickets have printed.

Disconnect WiFi or Bluetooth

Finally tap on the “Disconnect” button to break the connection to the printer to return to the start up screen. To leave the application, press on the iPad main button. This will return the user to the main iPad screen. When writing code the application will need to call either CloseSessionWiFi or CloseSessionBT.

End of Direct Printer/iPad Communication

Network Based Communication (printer/iPad)

While the main purpose of this document is to assist the user in communicating directly with the printer from an iPad, it is possible to communicate to the printer via a network. You can accomplish this task from the Image Printer screen, once the image has been selected. With the use of a third party Air Print Emulation software running on a PC/MAC on a LAN, any shared networked Boca Systems printer on that LAN can be reached using the Air Print capabilities already in the IPad. Air Print emulation software such as Printopia, FingerPrint, HandyPrint and many others are inexpensive and available from the web. Once the image is displayed clicking on the “Driver Print” button will cause the Air Print printer options screen to be displayed as shown here.

Pick a printer, number of copies and click on the Print button and the Air Print Emulation execution screen will be displayed.

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 libBocaIpadSDK.a.

http://www.bocasystems.com/documents/ipad_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 iPad 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 iPad and a Boca Systems printer equipped with Wi-Fi or Bluetooth interfaces. It also provides methods needed for converting color images to monochrome black and white 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 iPad SDK library (Version 1.0) methods are highlighted in bold below.

Boca Systems SDK Library Routines

Start or end a Wi-Fi session

BOOL OpenSessionWiFi (NSString *ipaddress);

void CloseSessionWiFi ();

Start or end a Bluetooth session

BOOL OpenSessionBT ();

void CloseSessionBT ();

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 ();