Printer—Developer Documentation
SUNMI External Printer
Developer Documentation
1
Printer—Developer Documentation
Introduction ........................................................................................................................................... 3
Quick Start .............................................................................................................................................3
Introduction to API: ...............................................................................................................................5
1. Specify the printer of current SDK for operation ...........................................................................5
2. Connect the printer ......................................................................................................................... 5
3. Disconnect the printer .................................................................................................................... 5
4. Get the printer’s mac address list bound to Bluetooth ................................................................... 5
5. The connection status of the printer with specified enumeration type ...........................................5
6. Printer initialization ........................................................................................................................5
7. Move the paper according to line height ........................................................................................ 5
8. Move the paper according to pixels ............................................................................................... 6
9. Refresh buffer area ......................................................................................................................... 6
10. Horizontal anchor ......................................................................................................................... 6
11. Set the horizontal anchor .............................................................................................................. 6
12. Print text ....................................................................................................................................... 6
13. Set gb18030 character set coding .................................................................................................6
14. Set printer’s mapping page table .................................................................................................. 7
15. Set the international character set encoding ................................................................................. 7
16. Set the right spacing of characters ................................................................................................7
17. Set the left and right spacing between Chinese characters ...........................................................7
18. Set font size .................................................................................................................................. 7
19. Set alignment mode ...................................................................................................................... 7
20. Set absolute position .....................................................................................................................7
21. Set relative position ...................................................................................................................... 8
22. Enable or disable underline .......................................................................................................... 8
23. Enable or disable bold .................................................................................................................. 8
24. Enable or disable overlap effect (usually the same as bold) ........................................................ 8
25. Set the line spacing for the printer ................................................................................................8
26. Set the left spacing of the printer ..................................................................................................8
27. Set printing width ......................................................................................................................... 8
28. Print a barcode ..............................................................................................................................8
29. Print a QR code ............................................................................................................................ 9
30. Method 1 for printing an image ....................................................................................................9
31. Method 2 for printing an image ....................................................................................................9
32. Cutter cutting paper ...................................................................................................................... 9
33. Print a form ...................................................................................................................................9
34. Send data instructions .................................................................................................................10
35. Get printer status ........................................................................................................................ 10
36. LAN transaction printing interface of cloud printer ...................................................................10
Enable transaction mode ......................................................................................................................10
Submit transaction mode ..................................................................................................................... 10
Exit transaction mode .......................................................................................................................... 11
2
Printer—Developer Documentation
Introduction
There are two main SUNMI printer types: inbuilt printer and external printer. This document introduces how to use
APIs we provided to get your external printers ready for use quickly. For inbuilt printer documentation, please see
Inbuilt Printer Documentation.
You can call various print interface libraries in a fast way through simple API integration, and the interface libraries
basically have all the functions including printing layout, pattern setting, etc., and will be updated regularly to save your
time on learning printer configuration, ESC commands, etc.
Currently, printers supported by SDK for connection include 58mm Cloud Printer, 80mm Kitchen Cloud Printer, 58mm
Thermal Receipt Printer and so on.
Quick Start
1. Automatic integration:
Add dependencies and attributes configuration in the program build.gradle file:
dependencies{
compile ‘com.sunmi:external-printerlibrary:1.0.9’
}
Note: the dependency library is located in the maven central repository, so mavenCentral() support is required.
2. To avoid obfuscation, add the following configuration to proguard-rules.pro obfuscation file:
-dontwarn com.sunmi.externalprinteribrary.**
-keep public class com.sunmi.externalprinterlibrary.**{*;}
3. Select the corresponding enumeration type for SUNMI printer and specify it as the operation object of SDK.
The available types are:
//enumeration types for a printer connected via a USB interface
SunmiPrinter.SunmiCloudPrinter -- connect a SUNMI 58mm Cloud Printer
SunmiPrinter.SunmiKitchenPrinter-- connect to SUNMI 80mm Kitchen Cloud Printer
SunmiPrinter.SunmiNTPrinter -- connect to SUNMI 58mm Thermal Receipt Printer
//enumeration type for a printer connected via a LAN
SunmiPrinter.SunmiNetPrinter -- all SUNMI cloud printers connected via a LAN
//enumeration type for a printer connected via Bluetooth
SunmiPrinter.SummiBlueToothPrinter – all SUNMI cloud printers connected via Bluetooth
4. Specify a printer to print
//1. Specify 58mm Thermal Receipt Printer as the operation object of SDK
SunmiPrinterApi.gtInstance.setPrinter(SunmiPrinter.SunmiNTPrinter);
//2. Connect printer
SunmiPrinterApi.getInstance().connectPrinter(context, new
ConnectCallback{
void onFound(){
//If the printer is found, it will call back this method
}
void onUnfound(){
//If the printer is not found, it will call back this method
3
Printer—Developer Documentation
}
void onConnect(){
//It will call back this method after successful connection, and the printer is ready
}
void onDisconnect(){
//It will call back this method if the printer is disconnected during the connection, and the printing task will be
interrupted
}
});
//3. Call the printing interface and complete the printing task
SunmiPrinterApi.getInstance().printInit();
SunmiPrinterApi.getInstance().printText(“123456789\n”);
SunmiPrinterApi.getInstance().printQrCode(“123456789, 4, 0);
//4. Complete and disconnect the printer
SunmiPrinterApi.getInstance().disconnectPrinter(context);
5. Specify multiple printers connected via a LAN to print (same for the printers connected via Bluetooth)
//1. Specify and connect multiple IP printers connected via LAN
SunmiPrinterApi.getInstance().setPrinter(SunmiPrinter.SunmiNetPrinter,
“192.168.1.90”);
SunmiPrinterApi.getInstance().connectPrinter(context,new ConnectCallback{
void onFound(){
//If the printer is found, it will call back this method
}
void onUnfound(){
//If the printer is not found, it will call back this method
}
void onConnect(){
//It will call back this method after successful connection, and printing is ready
}
void onDisconnect(){
//It will call back this method if the printer is disconnected during the connection, and the printing task will be
interrupted
}
});
SunmiPrinterApi.getInstance().setPrinter(SunmiPrinter.SunmiNetPrinter,
“192.168.1.91”);
SunmiPrinterApi.getInstance().connectPrinter(…);
//2. Specify all the printers connected via LAN to print after successful connection
SunmiPrinterApi.setPrinter(SunmiPrinter.SunmiNetPrinter);
//3. Call the printing interface and complete printing task
SunmiPrinterApi.getInstance().printInit();
SunmiPrinterApi.getInstance().printText(“123456789\n”);
SunmiPrinterApi.getInstance().printQrCode(“123456789, 4, 0);
//4. Disconnect all the printers in turn after completion
SunmiPrinterApi.getInstance().setPrinter(SunmiPrinter.SunmiNetPrinter,
“192.168.1.90”);
SunmiPrinterApi.getInstance().disconnect(context);
SunmiPrinterApi.getInstance().setPrinter(SunmiPrinter.SunmiNetPrinter,
4
Printer—Developer Documentation
“192.168.1.91”);
SunmiPrinterApi.getInstance().disconnect(context);
Introduction to APIs:
1. Specify a printer for the SDK
Method void setPrinter(SunmiPrinter sunmiPrinter，String… address)
Description Specify a printer for the SDK;
You can specify the printer connected via the specified LAN or Bluetooth, and if so, a specific
LAN or Bluetooth address is needed first.
Input sunmiPrinter: specify the printer’s enumeration type;
address: when the enumeration type is SunmiPrinter.SunmiNetPrinter or
SunmiPrinter.SunmiBlueTooth:
Control a printer when specifying the specific operation address;
Control all the printers connected via LAN or Bluetooth when not specifying the specific address.
2. Connect to the printer
Method void connectPrinter(Context context, ConnectCallback callback)
Description Connect to the printer specified by the SDK.
Input Context: dialog context;
Callback: printer connection result callback.
3. Disconnect the printer
Method void disconnectPrinter(Context context)
Description Complete and disconnect the printer with specified enumeration type, and release resource.
Input Context: dialog context
4. Get the mac address list of printers connected via Bluetooth
Method void disconnectPrinter(Context context)
Description Get the Bluetooth address of SUNMI cloud printer bound to the device.
Input Context: dialog context
Return Bluetooth address of the SUNMI cloud printer connected
5. Get the connection status of the printer with specified enumeration type
Method boolean isConnected()
Description Whether the printer with the specified enumeration type is being connected;
The LAN/Bluetooth printer without a specified address cannot be returned.
Input void
Return True connecting
False not connected
6. Printer initialization
Method void printerInit()
Description Initialize the printer and restore the attributes previously set to default status.
Input None
Return None
7. Move the paper according to line height
- 5-
Printer—Developer Documentation
Method void lineWrap(int n)
Description The printer moves the paper for n lines;
If there is data in the printer buffer area, the printer will output the data and move the paper for n
lines;
The moving distance is 0 if the line height is set to 0.
Input Number of lines (0<n<256)
Return None
8. Move the paper according to pixels
Method void pixelWrap(int n)
Description The printer moves the paper for n lines;
If there is data in the printer buffer area, the printer will output the data and move the paper for n
lines.
Input Number of pixels (0<n<256)
Return None
9. Refresh buffer area
Method void flush()
Description Refresh printer buffer area. Output when there’s data in buffer area, and feed a line of paper when
there’s no data.
Input None
Return None
10. Horizontal anchor
Method void tab()
Description Move the printing position to the next horizontal anchor;
If the horizontal anchor exceeds the printing area, move to the end of the line;
If it’s already at the end of a line, a linefeed will be implemented.
Input None
Return None
11. Set the horizontal anchor
Method void setHorizontalTab(int[] k)
Description Mark the horizontal anchor, and each anchor is specified by k[n] ascii characters width, 8 ascii
characters width by default.
Input k: horizontal anchors array k[n], with the biggest value for n being 32, and 0<k[n]<256;
The array must be in ascending order, or an exception will happen;
The default anchor will be restored when k is set to null, and by default there is an 8-characher
wide interval between two anchors.
Return None
12. Print text
Method void printText(String text)
Description It will convert the text into a hexadecimal byte stream with corresponding characters encoding;
Printing service will convert text into gb18030 code by default.
Input text: the text to be printed
Return None
13. Set gb18030 character set encoding
Method void setGb18030CharSet(boolean set)
Description The printer can recognize gb18030 character set by default, and it can’t recognize it when turning
6
Printer—Developer Documentation
off the setting, and will process it as a single byte.
Input Whether to recognize the gb18030 character set.
Return None
14. Set printer’s mapping page table
Method void setPageTable(int n)
Description This method is only valid when setGb18030CharSet（false）when mapping single-byte code
0x80-0xff on different pages.
Input n: corresponding page table
Return None
15. Set the international character set encoding
Method void setInterCharSet(int n)
Description Some special characters in ascii code vary in different countries, and you select a country to print
its corresponding characters.
Input n: corresponding country
Return None
16. Set the right sidebearing of characters
Method void setCharRightSpace(int n)
Description Set the right spacing of characters, and it is only valid for ascii code, invalid for other characters.
Input n: number of pixels indicating the sidebearing
Return None
17. Set the left and right sidebearing between Chinese characters
Method void setHanziSpace(int m，int n)
Description Set the left and right spacing between Chinese characters.
Input m: left sidebearing
n: right sidebearing
Return None
18. Set font size
Method void setFontZoom(int hori, int veri)
Description Due to the limitation of the printer's dot matrix fonts, the font size can only be multiplied, so this
method can control the font magnification in horizontal and vertical directions.
Input The range of hori and veri is 1-8, indicating the times the font can be multiplied horizontally and
vertically. If it is set outside the range, an error parameter will be returned.
Return None
19. Set alignment mode
Method void setAlignMode(int type)
Description Set the alignment mode of the printing content
Input 0: left (default), 1: center, 2: right
Return None
20. Set absolute position
Method void moveAbsolutePos(int pos)
Description Move the printing position to the specified pixel from the starting position.
Input Pos: pixel from the starting position
- 7-
Printer—Developer Documentation
Return None
21. Set relative position
Method void moveRelativePos(int pos)
Description Move the printing position to the specified pixel relative to the current position.
Input Pos: pixel from the current position
Return None
22. Enable or disable underline
Method void enableUnderline(boolean enable)
Description Enable or disable the underline function of characters.
Input Is ‘enable’ on or off
Return None
23. Enable or disable bold
Method void enableBold(boolean enable)
Description Enable or disable the bold function of characters.
Input Is ‘enable’ on or off
Return None
24. Enable or disable overlap effect (usually the same as bold)
Method void enableBold(boolean enable)
Description Enable or disable the bold function of characters.
Input Is ‘enable’ on or off
Return None
25. Set the line spacing for the printer
Method void setLineSpace(int value)
Description Set the line spacing for the printer;
When the line spacing is smaller than the character height, the character height will be adopted.
Input value: when the value is smaller than 0, it will restore the default line spacing, otherwise it will
set the line spacing to the corresponding value.
Return None
26. Set the left margin for the printer
Method void setLeftSpace(int value)
Description Set the number of pixels indicating the left margin
If the value is too big, the printing area may be invalid.
Input value: the size of left margin
Return None
27. Set print width
Method void setPrintWidth(int width)
Description Set the number of pixels indicating the print width.
Input width: print width
Return None
28. Print a barcode
Method void printBarCode(String code, int type, int width, int height, int hriPos)
8
Printer—Developer Documentation
Description Print a custom barcode.
Input code: barcode (it shall be in the format as required by the specified barcode type);
type: barcode type 0: UPC-A, 1: UPC-E, 2: EAN13, 3: EAN8, 4: CODE39, 5: ITF, 6:
CODABAR, 7: CODE93, 8: CODE128, See barcode type remark;
width: barcode width 2-6 pixels (a too wide barcode won’t be printed);
height: barcode height 1 – 255 pixels;
hriPos: HRI position 0: No print, 1: Above the barcode, 2: Below the barcode, 3: Above and
below the barcode
Return None
29. Print a QR code
Method void printQrCode(String code, int modeSize, int errorlevel)
Description Print a QR code.
Input code: QR code to be printed, utf-8 character set by default;
modeSize: size of QR code, 1-16 pixels;
errorlevel: error correction level of QR code, four levels: 0, 1, 2, 3.
Return None
30. Method 1 for printing an image
Method void printBitmap(Bitmap bitmap, int mode)
Description The bitmap is converted into raster bitmap for printing;
This method is suitable for printing images with width within the printing paper;
Note that if the data is too large, the sending may fail. In this case, you can use mode to set
multiple magnification.
Input bitmap: the opaque bitmap image to be printed;
mode: 0: common, 1: double width, 2: double height, 3: double height double width
Return None
31. Method 2 for printing an image
Method void printBitmap2(Bitmap bitmap, int mode)
Description Convert the image into bitmap for printing;
You need to set the line spacing to 0 when using this method;
This method differs from printBitmap in that it does not cause printer uninitialized gibberish after
data failure;
Note: if the data is too large, the sending may fail. In this case, you can use mode to set multiple
magnification.
Input bitmap: the opaque bitmap image to be printed;
mode: 0:8 point single density 1:8 point double density 32:24 point single density 33:24 point
double density (original size)
Return None
32. Cutter cutting paper
Method void cutPaper(int m, int n)
Description Paper cutting.
Input m: paper cutting mode, 0: full cut, 1: partial cut, 2: cut when feeding the paper
n: paper feeding distance, this parameter will be valid only when m=2. Due to different types of
printers, the distance from cutter to print head varies. Only when n=0, automatic paper feeding
will take this distance, and extra distance set will be taken when n>0.
Return None
33. Print a form
Method void printColumnsText(String[] colsTextArr, int[] colsWidthArr, int[] colsAlign)
- 9-
Printer—Developer Documentation
Description Output the printing result in a form format, and each array represents the data and format on this
column. You need to call this method for several times to achieve the form format.
! Note: calling this method will initialize the mode set before.
Input colsTextArr: the content to be printed in each column, Chinese and ascii code supported;
colsWidthArr: the maximum number of characters that can be contained in a column, and the
characters are expressed in ascii code (one Chinese character is equal to two ascii characters).
When the text exceeds the maximum number of characters that can be contained in a column, the
text will be moved to the next row of the column. When the maximum number of characters in all
columns exceeds the maximum number of characters that can be contained in a row, the text will
not be printed;
colsAlign: the alignment of the content of each column, and it is only effective when the number
of text characters is less than the maximum number of characters.
Return None
34. Send data commands
Method void sendRawData(byte[] cmd)
Description Send raw esc control commands.
Input cmd: epson commands sent
Return None
35. Get printer status
Method int getPrinterStatus()
Description Get printer’s operating status;
The operating status of LAN/Bluetooth printers without specified address cannot be obtained.
Input None
Return -1 Printer is off-line or the printing service is not connected to the printer;
0 Pinter is under normal operation;
1 Cover is open;
2 Out of paper;
3 Low on paper;
4 Printer is overheated.
36. LAN transaction printing interface of cloud printer
For scenarios requiring LAN printing, we provide the following extension methods. You can enable and submit
the information before and after printing to obtain the actual printing results.
You can call by the following method:
Enable transaction - > Print SDK - > Submit transaction - > Wait for The printing result callback
The detailed methods are as follows:
Enable transaction mode
Method void startTransBuffer(boolean isClear)
Description Enable transaction mode to control the implementation order and implementation status of
printing task. You can only get the printing result accurately under the transaction mode.
After enabling transaction mode, all the printing commands will be cached, and will be sent to
printer when submitting. The printer will not print when the data is not submitted.
Note: currently only LAN printing of cloud printer supports transaction mode.
Input isClear: whether to clear the cached data not submitted.
Return None
Submit transaction mode
Method void commitTransBuffer(TransCallback callback)
Description Submit this transaction and get the implementation result of this transaction printing;
It’s suggested to wait for the submission result before submitting the next transaction;
10
Printer—Developer Documentation
Note: currently only LAN printing of cloud printer supports transaction mode.
Input Callback: the transaction submission result
Return None
Exit transaction mode
Method void endTransBuffer()
Description Exit transaction mode;
The subsequent printing commands will be directly sent to the printer.
Note: currently only LAN printing of cloud printer supports transaction mode.
Input None
Return None
- 11 -
