Saturday, February 13, 2016

Printing on a white label BLE thermal printer from iOS - a quick story

Over at, we are building tools to help small merchants better connect with their customers. Check to see what we do, and do not forget to watch that video, we are sure you would love it :-)

While one of the core principles at OneGreenDiary is to be as paper less as possible, there are still places where a printed paper bill may be required. We avoided print support for our merchant apps, till one of our early adopters specifically asked for it. Since we are kind of cash strapped, and can not afford to spend on a damn printer that is iOS certified, we went over to and ordered this cheap Bluetooth enabled thermal printer that claimed to work with iOS :

Great. After the printer arrived, we though that it would magically connect to out iOS device and we did start printing instantly. Bummer. Ok, how about Android ? No luck. Apparently neither iOS nor Android provide native support for BLE printers. I tried to install the outdated Windows driver, and Linux cups drivers with no luck. Not even able to print on desktop. 

But then, Abhay C, a wanderer with us, found an iOS app called printer-x, that was a demo app to print on bluetooth enabled thermal printers. He printed this:  "hello, world!"

At this point we knew, it could be done. But how? All communications with the vendor didn't go anywhere. They send some sample iOS (Objective C) code, and some Android code, both of which didn't compile, and neither we could understand what was going on in the code. There were a few comments in Chinese that tried to be helpful. Chinese, not Swift. The programmers manual that came with printer reminded me of good old DOS assembly days. There was something, but didn't know where to start.

Next we tried to venture into programming our own BLE layer for printer communication. Instead of using the CoreBluetooth library we zeroed in on using BluetoothKit, which is Swift wrapper over CoreBluetooth library ( So basically it is this: BLE frameworks try to give you two interfaces: Peripherals and Central. Peripheral refers to a device which can be discovered, asked for data, or can receive data. Central on the other hand scans for Peripherals, discovers characteristics offered by Peripheral, receive / send data to the Peripheral. One of the important thing to enable discovery is the UUID of the Bluetooth device, this can be easily obtained by using a discovery code, or a number of BLE query apps available on the App store/ Play store. I used the LightBlue app from the App store for this purpose. Once this device was discovered, we needed to connect to the device. The BluetoothKit provides a elegant interface to connect. But the issue started after this: apparently BluetoothKit's connect call back returns an instance of BKRemotePeripheral class, and this class exposes API to only receive data, not send! Apparently the class was more designed for bluetooth sensors, that only transmit data, not receive anything. Digging into the BKRemotePeripheral class, I found out a way to expose the embedded CBPeripheral object along with capturing CBCharasteristic objects. These are the objects of CoreBluetooth iOS library that allow lower level controls.

Next is when the DOS assembly like programmer's manual, which came with the printer, came up for help. After this I could easily figure out the code to issue a line feed to the printer device:

let lineFeed = self.hexToNSData("0A")
let printer = self.connectedDevice!.getPeripheral()!
printer.writeValue(lineFeed, forCharacteristic: self.connectedDevice!.getCharacteristic()!, type: CBCharacteristicWriteType.WithResponse)
At this point, I knew, things were pretty much in control. The above code basically writes the hex code "0A" to the discovered characteristic. This initiates a line feed operation on the printer. Once this is done, it was a wow moment to print this:

and then this:

Since all of this code (written in Swift) was majorly based on BluetoothKit, we felt it was best to open up this part of the code, which is now hosted on GitHub:

Hope this is of some help, especially if you are trying to programatically access these kind of printers with iOS.

Note: Before you ask, I am still connected with VLife for all official (and practical) purposes. Once an officer at immigration and citizenship department in Oz told me, it is always good to be in love with two countries, you are contributing to both with your heart. Fits well here.