Citizen CL-S700 Owner's manual

Android Label Print SDK
Programming Manual
Version 1.04

CITIZEN Android Label Print SDK —Programming Manual
2
Revision History
Date
Version
Description
Sep 28, 2016
1.00
First issue.
Mar 15, 2017
1.01
- Renamed the namespace to “com.citizen.sdk.labelprint”.
- Added an explanation of ParallelErrorOutput to printerCheck method.
- Added the measurementUnit as a parameter of drawTextLocalFont method.
- Added the resolution and measurementUnit as a parameter of drawBitmap Method.
Sep 29, 2017
- Added CL-E300/CL-E303 to support model.
Jan 24, 2018
- Added CL-E321/CL-E331 to support model.
Sep 13, 2018
1.02
- Added Bluetooth as a interface of CL-E720/730 model.
- Modified the printer model name.
- Added a locale for Chinese model and Korean model to drawTextPtrFont.
- Added the Chinese model and the Korean model to the definition of the locale.
Apr 4, 2019
1.03
- Added binary data specification to drawQRCode method.
Jul 31, 2019
1.04
- Modified the setting contents of resolution and measurementUnit parameter of
drawTextLocalFont method.
- Modified the setting contents of measurementUnit parameter of drawBitmap
method.
Nov 12, 2019
- Added CL-S700II/703II, CL-S621II/631II and CL-S521II/531II to support model.
(Page 6)
June 2, 2020
- Added CL-E300EX/303EX and CL-E321EX/331EX to support model. (Page 7)

CITIZEN Android Label Print SDK —Programming Manual
3
Permission Notice
1. Unauthorized use of all or any part of this document is prohibited.
2. The information in this document is subject to change without prior notice.
3. This document has been created with full attention. If, however, you find an error or question,
please contact us.
4. We shall not be liable for any effect resulting from operation regardless of the above item 3.
5. If you do not agree with the above terms, you are not permitted to use this SDK.
Trademark
Android is registered trademarks of Google Inc. in the United States and/or other countries.
Java is a registered trademark of Oracle in the United States and/or other countries.
Company names and product names appearing on this document are trademarks and/or registered
trademarks of respective companies.
CITIZEN is a registered trademark of Citizen Watch Co., Ltd.

CITIZEN Android Label Print SDK —Programming Manual
4
Table of Contents
1. Introduction.................................................................................................................................................... 6
1.1. Who should read this document.................................................................................................................6
1.2. System summary ........................................................................................................................................6
1.3. Adding library to your .net project ............................................................................................................8
1.4. Program structure ....................................................................................................................................10
1.5. Class summary..........................................................................................................................................12
2. API specification........................................................................................................................................... 14
2.1. Return value..............................................................................................................................................14
2.2. LabelPrinter class.....................................................................................................................................15
2.2.1 Constructor .........................................................................................................................................15
2.2.2 setContext method .............................................................................................................................16
2.2.3 connect method...................................................................................................................................17
2.2.4 disconnect method ..............................................................................................................................19
2.2.5 printerCheck method .........................................................................................................................20
2.2.6 print method .......................................................................................................................................22
2.2.7 storeNVBitmap method .....................................................................................................................23
2.2.8 clearOutPut method ...........................................................................................................................24
2.2.9 sendData method................................................................................................................................25
2.2.10 searchCitizenPrinter method ..........................................................................................................26
2.2.11 searchLabelPrinter method .............................................................................................................28
2.2.12 setLog method...................................................................................................................................29
2.2.13 HorizontalMagnification property...................................................................................................30
2.2.14 VerticalMagnification property .......................................................................................................31
2.2.15 FormatAttribute property................................................................................................................32
2.2.16 ContinuousMediaLength property ..................................................................................................33
2.2.17 MeasurementUnit property.............................................................................................................34
2.2.18 PrintSpeed property .........................................................................................................................35
2.2.19 FeedSpeed property..........................................................................................................................36
2.2.20 SlewSpeed property..........................................................................................................................37
2.2.21 BackupSpeed property .....................................................................................................................38
2.2.22 PrintDarkness property ...................................................................................................................39
2.2.23 DoubleHeat property........................................................................................................................40
2.2.24 VerticalOffset property ....................................................................................................................41
2.2.25 HorizontalOffset property................................................................................................................42
2.2.26 MediaHandling property..................................................................................................................43
2.2.27 StartOffset property .........................................................................................................................44
2.2.28 StopOffset property ..........................................................................................................................45
2.2.29 LabelSensor property.......................................................................................................................46
2.2.30 PrintMethod property ......................................................................................................................47
2.2.31 SensorLocation property ..................................................................................................................48
2.2.32 CommandInterpreterInAction property .........................................................................................49
2.2.33 PaperError property.........................................................................................................................50
2.2.34 RibbonEnd property .........................................................................................................................51
2.2.35 BatchProcessing property ................................................................................................................52
2.2.36 Printing property..............................................................................................................................53
2.2.37 Pause property..................................................................................................................................54
2.2.38 WaitingForPeeling property ............................................................................................................55
2.3. LabelDesign class .....................................................................................................................................56

CITIZEN Android Label Print SDK —Programming Manual
5
2.3.1 Constructor .........................................................................................................................................56
2.3.2 drawTextPtrFont method ..................................................................................................................57
2.3.3 drawTextDLFont method ..................................................................................................................59
2.3.4 drawTextLocalFont method...............................................................................................................61
2.3.5 drawNVBitmap method .....................................................................................................................63
2.3.6 drawBitmap method...........................................................................................................................64
2.3.7 drawBarCode method.........................................................................................................................66
2.3.8 drawMaxiCode method ......................................................................................................................71
2.3.9 drawPDF417 method .........................................................................................................................72
2.3.10 drawDataMatrix method .................................................................................................................73
2.3.11 drawQRCode method .......................................................................................................................74
2.3.12 drawAztec method............................................................................................................................75
2.3.13 drawGS1DataBar method ...............................................................................................................76
2.3.14 drawLine method .............................................................................................................................78
2.3.15 drawRect method..............................................................................................................................79
2.3.16 fillRect method..................................................................................................................................80
2.3.17 drawCircle method ...........................................................................................................................81
2.3.18 fillCircle method ...............................................................................................................................82
2.3.19 drawPolygon method........................................................................................................................83
2.3.20 fillPolygon method............................................................................................................................84
2.3.21 embedRawDesignCommand method ..............................................................................................85
3. Appendix....................................................................................................................................................... 86
3.1. Specifying object position .........................................................................................................................86
3.2. Logging function .......................................................................................................................................87
3.3. Predefined Constants ...............................................................................................................................89

CITIZEN Android Label Print SDK —Programming Manual
6
1. Introduction
This document is a programming manual for the CITIZEN Android Label Print SDK.
1.1. Who should read this document
This document is intended for developers who integrate their Android application programs with Citizen
label printers.
1.2. System summary
This SDK is referred by Android application program to control Citizen Label printers.
System diagram of the SDK
Supported terminals
Below is a list of supported terminals for the SDK.
Android OS version:
Supported interfaces:
Android 2.3.3 (API Level 10) or newer
Wi-Fi, Bluetooth
Android 3.1 (API Level 12) or newer
Wi-Fi, Bluetooth, USB Host
Supported printer models
Object Model
Interface
Print Method
CL-S700/703
Wired/Wireless LAN, USB
Direct thermal/Thermal transfer
CL-S700II/703II
Wired/Wireless LAN, USB
Direct thermal/Thermal transfer
CL-E720/730
Wired/Wireless LAN, USB, Bluetooth
Direct thermal/Thermal transfer
CL-S621/631
Wired/Wireless LAN, USB
Direct thermal/Thermal tranfer
CL-S621II/631II
Wired/Wireless LAN, USB
Direct thermal/Thermal tranfer
CL-S521/531
Wired/Wireless LAN, USB
Direct thermal
CL-S521II/531II
Wired/Wireless LAN, USB
Direct thermal
CL-S400DT
Wired/Wireless LAN, USB, Bluetooth
Direct thermal
CL-E300/303
Wired LAN, USB
Direct thermal
Android OS
Printer
Windows Application
CITIZEN Android Label Print SDK
Wi-Fi / Bluetooth /
USB Host

CITIZEN Android Label Print SDK —Programming Manual
7
CL-E300EX/303EX
Wired/Wireless LAN, USB, Bluetooth
Direct thermal
CL-E321/331
Wired LAN, USB
Direct thermal/Thermal tranfer
CL-E321EX/331EX
Wired/Wireless LAN, USB, Bluetooth
Direct thermal/Thermal tranfer
Refer to each user’s manual for more details.

CITIZEN Android Label Print SDK —Programming Manual
8
1.3.Adding library to your .net project
Adding Library
Place the library file in the “<project>\app\libs” folder as below.
Start up the AndroidStudio, Right-click the CSJLabelLib_Android.jar of libs in the folder, please select
the “Add As Library …”.

CITIZEN Android Label Print SDK —Programming Manual
9
Declaration of Import
Add the library file that is provided, if you use this SDK, please import the following three classes.
import com.citizen.sdk.labelprint.LabelConst;
import com.citizen.sdk.labelprint.LabelPrinter;
import com.citizen.sdk.labelprint.LabelDesign;

CITIZEN Android Label Print SDK —Programming Manual
10
1.4. Program structure
Here is an example program in Java which uses the SDK.
// Create an instance( LabelDesign class )
LabelDesign design = new LabelDesign();
// Text
design.drawTextPtrFont("Sample Print",
LabelConst.CLS_LOCALE_JP, LabelConst.CLS_PRT_FNT_TRIUMVIRATE_B,
LabelConst.CLS_RT_NORMAL, 1, 1, LabelConst.CLS_PRT_FNT_SIZE_24, 20,
300);
// QRCode
design.drawQRCode("DrawQRCode",
LabelConst.CLS_ENC_CDPG_US_ASCII, LabelConst.CLS_RT_NORMAL, 4,
LabelConst.CLS_QRCODE_EC_LEVEL_H, 20, 220);
// Rect(fill)
design.fillRect(20, 150, 350, 40, LabelConst.CLS_SHADED_PTN_11);
// BarCode
design.drawBarCode("0123456789",
LabelConst.CLS_BCS_CODE128, LabelConst.CLS_RT_NORMAL,
3, 3, 30, 20, 70, LabelConst.CLS_BCS_TEXT_SHOW);
// Create an instance( LabelPrinter class )
LabelPrinter printer = new LabelPrinter();
// Connect printer
int result = printer.connect(LabelConst.CLS_PORT_WiFi,
"192.168.128.212")
if (LabelConst.CLS_SUCCESS == result)
{
// Get Properties
int printDarkness = printer.getPrintDarkness();
if (LabelConst.CLS_PROPERTY_DEFAULT == printDarkness)
{
// Set Properties
printer.setPrintDarkness(10);
}
// Print Label
result = printer.print(design, 0001);
// Disconnect
printer.disconnect();
if (LabelConst.CLS_SUCCESS != result)
{
// Print Error
Toast.makeText(MainActivity.this, "Print Error :" +
Integer.toString(result), Toast.LENGTH_LONG ).show();
}
}
else
{
// Connect Error
Toast.makeText(MainActivity.this, "Connect or Printer Error :" +
Integer.toString(result), Toast.LENGTH_LONG ).show();
}
Design of the
label
Print of the
label
(Connect,
Print,
Disconnect)

CITIZEN Android Label Print SDK —Programming Manual
11
Printing result

CITIZEN Android Label Print SDK —Programming Manual
12
1.5. Class summary
Methods (LabelPrinter class)
No
Method
Description
1
LabelPrinter
Constructor.
2
setContext
Set the context.
3
connect
Connects to a printer.
4
disconnect
Disconnects with a printer.
5
printerCheck
Gets status of a printer.
6
print
Prints labels.
7
storeNVBitmap
Stores a bitmap image into the flash memory.
8
clearOutput
Clears all data in the printer buffer.
9
sendData
Sends binary data to a printer.
10
searchCitizenPrinter
Searches available printers and gets printer information.
11
searchLabelPrinter
Searches available printers and gets addresses.
12
setLog
Sets the log function.
Properties (LabelPrinter class)
No
Property
Attribute
Description
1
HorizontalMagnification
R/W
Horizontal magnification of the label.
2
VerticalMagnification
R/W
Vertical magnification of the label.
3
FormatAttribute
R/W
Specifies how to print overlapped objects.
4
ContinuousMediaLength
R/W
Label length for continuous paper.
5
MeasurementUnit
R/W
Measurement unit. Inches or millimeters.
6
PrintSpeed
R/W
Print speed.
7
FeedSpeed
R/W
Feed speed.
8
SlewSpeed
R/W
Slew speed.
9
BackupSpeed
R/W
Backup speed.
10
PrintDarkness
R/W
Print darkness.
11
DoubleHeat
R/W
Double heat.
12
VerticalOffset
R/W
Vertical offset of the printing position.
13
HorizontalOffset
R/W
Horizontal offset of the printing position.
14
MediaHandling
R/W
Media handling after print. (Pause, Cut or Peel)
15
StartOffset
R/W
Vertical offset of the paper position when start
printing.
16
StopOffset
R/W
Vertical offset of the paper position when stop
printing.
17
LabelSensor
R/W
Label sensor type. (See through, Reflect or None)
18
PrintMethod
R/W
Thermal transfer or Direct thermal.
19
SensorLocation
R/W
Front or Rear. (for the models which have multiple
sensors)
20
CommandInterpreterInAction
R
Status: CommandInterpreterInAction
21
PaperError
R
Status: PaperError
22
RibbonEnd
R
Status: RibbonEnd
23
BatchProcessing
R
Status: BatchProcessing
24
Printing
R
Status: Printing
25
Pause
R
Status: Pause
26
WaitingForPeeling
R
Status: WaitingForPeeling

CITIZEN Android Label Print SDK —Programming Manual
13
Methods (LabelDesign class)
No
Method
Description
1
LabelDesign
Constructor.
2
drawTextPtrFont
Draws text by using a printer device font.
3
drawTextDLFont
Draws text by using a downloaded font.
4
drawTextLocalFont
Draws text by using a font installed in the terminal.
5
drawNVBitmap
Draws a bitmap image stored in the flash memory of the printer.
6
drawBitmap
Draws a bitmap file in the computer.
7
drawBarCode
Draws a barcode.
8
drawMaxiCode
9
drawPDF417
10
drawDataMatrix
11
drawQRCode
12
drawAztec
13
drawGS1DataBar
14
drawLine
Draws a line.
15
drawRect
Draws a rectangular.
16
fillRect
Draws a rectangular filled with a specified pattern.
17
drawCircle
Draws a circle.
18
fillCircle
Draws a circle filled with a specified pattern.
19
drawPolygon
Draws a polygon.
20
fillPolygon
Draws a polygon filled with a specified pattern.
21
embedRawDesignCommand
Embeds raw printer commands.

CITIZEN Android Label Print SDK —Programming Manual
14
2. API specification
2.1. Return value
Return value
Description
CLS_SUCCESS (0)
The operation has been done successfully.
CLS_E_CONNECTED (1001)
The printer is already connected.
CLS_E_DISCONNECT (1002)
The printer is not connected.
CLS_E_NOTCONNECT (1003)
Failed to connect to the printer.
CLS_E_CONNECT_NOTFOUND (1004)
Failed to confirm the model name after connecting to the printer.
CLS_E_NOCONTEXT (1006)
No context is specified.
CLS_E_BT_DISABLE (1007)
The Bluetooth device setting is invalid.
CLS_E_BT_NODEVICE (1008)
The Bluetooth device is not found.
CLS_E_ILLEGAL (1101)
The operation is not supported by the printer or an invalid parameter
was used.
CLS_E_OFFLINE (1102)
The printer is offline.
CLS_E_NOEXIST (1103)
The file name does not exist.
CLS_E_FAILURE (1104)
The service could not perform the requested procedure.
CLS_E_TIMEOUT (1105)
The service has been timed out waiting for a response from the printer.
CLS_E_NO_LIST (1106)
A printer could not be found for the printer search.
CLS_EPTR_BADFORMAT (1203)
The file format is not supported.

CITIZEN Android Label Print SDK —Programming Manual
15
2.2. LabelPrinter class
2.2.1 Constructor
Syntax
LabelPrinter ()
Parameters
none
Description
Creates an instance of the LabelPrinter class.
Return value
none
Example
LabelPrinter printer = new LabelPrinter();

CITIZEN Android Label Print SDK —Programming Manual
16
2.2.2 setContext method
Syntax
int setContext( Context context )
Parameters
値
[IN/OUT]
意味
設定可能範囲
context
[IN]
Context
(android.content.Context)
Context ：
Description
This method is used to the USB connection and the search printer. Specify the context.
Must be executed this method before the connect method on the USB connection and the
searchLabelPrinter method.
If you want to connect with other interfaces, you do not need this method.
Return value
Returns CLS_SUCCESS(0) on success, an error code otherwise. See "2.1 Return value" for the error
codes.
Example
printer.setContext (this);
printer.setContext (getApplicationContext());

CITIZEN Android Label Print SDK —Programming Manual
17
2.2.3 connect method
Syntax
1) int connect (int connectType, String address)
2) int connect (int connectType, String address, int port)
3) int connect (int connectType, String address, int port, int timeout)
4) int connect (int connectType, UsbDevice device)
Parameters
Parameter
[IN/OUT]
Description
Setting range
connectType
[IN]
Interface type
CLS_PORT_WiFi
CLS_PORT_Bluetooth
CLS_PORT_Bluetooth_Insecure
CLS_PORT_USB
address
[IN]
IP address to connect or
Bluetooth device address or
Bluetooth device name
WiFi: 0.0.0.0～255.255.255.255
Bluetooth:
00:00:00:00:00:00～
FF:FF:FF:FF:FF:FF
Device name (Automatic detection)
device
[IN]
UsbDevice class
(android.hardware.usb.UsbDevice)
null: Automatic detection
UsbDevice: Any USB device
port
[IN]
Port number
timeout
[IN]
Timeout (msec)
Description
This method is to connect to a printer. Specify an interface type and address.
The Bluetooth device address must be written in upper case.
When the Bluetooth device name is specified, it looks for a paired device which matches up.
When the Bluetooth device name is not specified, it looks for a paired/supported device automatically.
In case of using the Insecure Bluetooth connection after Android 2.3.3, use
CLS_PORT_Bluetooth_Insecure as connectType.
In case of USB device, the setContext method must be called beforehand.
The port number is effective only when CLS_PORT_WiFi is specified as connectType. The default
port number is 9100.
The timeout is to specify the maximum amount of time (in millisecond) to wait while attempting to
connect to the printer. This is not effective when CLS_PORT_USB is specified as connectType. The
default values are 4000 ms when WiFi, 8000 ms when Bluetooth.
When connecting, this method checks if the printer model is supported.
When the connection is no longer used, the disconnect method must be called. The next connection
will be failed otherwise.
Note
When connecting via USB for the first time, a dialog message for user permission pops up. Press OK
to continue.
A dialog message for user permission (example).

CITIZEN Android Label Print SDK —Programming Manual
18
Return value
Returns CLS_SUCCESS (0) on success, an error code otherwise. See below for the error codes.
"2.1 Return value" describes all error codes.
Error code
Description
CLS_E_CONNECTED (1001)
The printer is already connected.
CLS_E_NOTCONNECT (1003)
Failed to connec to the printer.
(1) The printer is not connected.
(2) The printer is not turned on.
(3) The port handle could not be obtained.
CLS_E_CONNECT_NOTFOUND (1004)
Failed to confirm if the printer is a supported model.
(1) The printer model is not supported.
CLS_E_NOCONTEXT (1006)
No context is specified.
CLS_E_BT_DISABLE (1007)
The Bluetooth device setting is invalid.
CLS_E_BT_NODEVICE (1008)
The Bluetooth device is not found.
Example
printer.connect(LabelConst.CLS_PORT_WiFi, "192.168.129.130");
printer.connect(LabelConst.CLS_PORT_Bluetooth, "");
UsbDevice usbDevice = null;
printer.connect(LabelConst.CLS_PORT_USB, usbDevice);

CITIZEN Android Label Print SDK —Programming Manual
19
2.2.4 disconnect method
Syntax
int disconnect ()
Parameters
none
Description
Disconnects a printer.
This must be called when a connection is no longer needed or when an error occurs.
Return value
Returns CLS_SUCCESS(0) on success, an error code otherwise. See "2.1 Return value" for the error
codes.
Example
printer.disconnect();

CITIZEN Android Label Print SDK —Programming Manual
20
2.2.5 printerCheck method
Syntax
int printerCheck ()
Parameters
none
Description
Gets the status of the printer and stores information into the properties, CommandInterpreterInAction,
PaperError, RibbonEnd, BatchProcessing, Printing, Pause and WaitingForPeeling.
When this method returns an error, a communication failure or a device error might occur. The
connection should be reestablished by using disconnect/connect methods in this case.
This method should be used to check the printer status before printing especially after a long idle.
This method can also be used to keep a network connection by calling it periodically.
In case of network connection with the CL - S5xx / 6xx / 70x, set "Parallel Error Output" to OFF
beforehand. In case of parallel connection with all models, set "Parallel Error Output" to OFF. This can
be done in the "Advanced" tab of the Label Printer Utility.
Return value
Returns CLS_SUCCESS (0) on success. See "2.1 Return value" for the error codes.
Example
// PrinterCheck
if (LabelConst.CLS_SUCCESS == printer.printerCheck())
{
// CommandInterpreterInAction Property
if ( printer.getCommandInterpreterInAction() == 1 ) {
// Command interpreter in action
}
// PaperError Property
if ( printer.getPaperError() == 1 ) {
// Paper error
}
// RibbonEnd Property
if ( printer.getRibbonEnd() == 1 ) {
// Ribbon end
}
// BatchProcessing Property
if ( printer.getBatchProcessing() == 1 ) {
// Batch processing
}
// Printing Property
if ( printer.getPrinting() == 1 ) {
// Printing
}
// Pause Property
if ( printer.getPause() == 1 ) {
// Pause