3.1. StarIOPort

Class to communicate with a printer.

Model/Emulation

mC-Print2 mC-Print3 mPOP FVP10 TSP100IIIW TSP100IIIBITSP100IIIU TSP100ECO TSP100U TSP100GTTSP100LAN TSP650II TSP650IISK TSP700II TSP800IITUP500SM-S210i SM-S220i SM-S230i SM-T300i/T300 SM-T400i BSC10 SM-L200 SM-L300 SP700SK1-211/221/V211 SK1-211/221/V211 Presenter SK1-311/321/V311 SK1-311/V311 Presenter
StarPRNT StarPRNT StarPRNT StarLine StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarLine StarLine StarLine StarLine StarLine StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile EscPos StarPRNT StarPRNT StarDotImpact StarPRNT StarPRNT StarPRNT StarPRNT

getPort

releasePort

searchPrinter

writePort

readPort

retreiveStatus

beginCheckedBlock

[1] [1]

endCheckedBlock

[1] [1]

setEndCheckedBlockTimeoutMillis

setHoldPrintTimeoutMillis

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

getFirmwareInformation

[2] [2][3] [2][3] [2][3] [2][3] [2][3] [2][3] [2][3] [2] [2] [2] [2] [2] [4] [2]

getPortName

getPortSettings

getStarIOVersion

[1]

When using SM-S220i with firmware Ver 2.1 or earlier, the following limitation exists. When using SM-T300 with firmware Ver 2.4 or earlier, the following limitation exists. You can confirm the completion of transmission of print data but cannot confirm the completion of printing.

[2]

When using Apple AirMac Express with a USB printer, it returns an empty string.

[3]

The model name of TSP100IIIU, TSP100U, TSP100GT and TSP100ECO is TSP100.It is impossible to get the firmware version of TSP100U, TSP100GT, TSP100ECO and TSP100LAN. Library version 2.2.7 or later is required for TSP100IIILAN, TSP100IIIW and TSP100IIIU.

[4]

Library version 2.2.3 or later is required.

3.1.1. Printing flow

Using the SMPort class, print per the following procedure.

../_images/port_flow.png
  • Examples

    StarIOPort port = null;
    
    try {
        // Port open
        port = StarIOPort.getPort(portName, portSettings, 10000, context);
    
        // Print end monitoring -Start
        StarPrinterStatus status = port.beginCheckedBlock();
    
        byte[] command = PrinterFunctions.createTextReceiptData(emulation, localizeReceipts, false);
    
        // Send print data
        port.writePort(command, 0, command.length);
    
        // Print end monitoring -End
        status = port.endCheckedBlock();
    
        // Status judgment during printing completion monitoring
        if (status.offline == false) {
            // Print successful end (Printer Online)
        }
        else {
            // Printing is abnormal termination (no paper, printer cover open etc)
            // Notify user
        }
    }
    catch (StarIOPortException e) {
        // Error
    }
    finally {
        try {
            // Port close
            StarIOPort.releasePort(port);
        }
        catch (StarIOPortException e) {}
    }
    

    Refer to Communication.java.

3.1.2. getPort

Opens a port for communicating with the printer.

  • Declaration

    public static StarIOPort getPort(String portName, String portSettings, int ioTimeoutMillis, Context context) throws StarIOPortException;
    
    @Deprecated
    public static StarIOPort getPort(String portName, String portSettings, int ioTimeoutMillis) throws StarIOPortException;
    
  • Parameter

    Name Contents Type
    portName The printer port name String
    portSettings Specifies connection setting information. String
    ioTimeoutMillis The timeout time for internal control and API (unit: millisecond) int
    context context android.content.Context
  • Return value

    Contents Type
    StarIOPort object StarIOPort
  • Exception

    Contents Type
    When port open fails
    When an incorrect portName is passed
    StarIOPortException
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred
    StarResultCode.FAILURE_IN_USE Connection was refused by the printer (another host is connected or other reason)

Refer to Printing flow .

  1. portName Parameter

Interface

portName

Contents

Example

Library version

Bluetooth BT:
Communicates with the first Star printer found.
Pair only one Star printer.
"BT:"2.2.0+
BT:Device Name

To specify the Bluetooth device name

"BT:Star Micronics"2.2.2+
BT:MAC Address

To specify the MAC address

"BT:00:12:F3:1E:2B:72"2.2.2+
Ethernet/Wireless LAN TCP:IP Address

To specify the IP address

"TCP:192.168.1.100"2.2.2+
USB USB:
Communicates with the first Star printer found.
Connect only one Star USB printer with.
"USB:" 2.2.2+
USB:SN:USB Serial Number

Specifying USB serial number

"USB:SN:1234ABCD" 2.2.2+
USB:searchPrinter Result
PortName obtained by searching with the searchPrinter method.
It can be obtained by getPortName method of PortInfo class.
"USB:1-3" 2.2.2+
USB/Bluetooth/LAN AutoSwitch:

Using AutoSwitch Interface

"AutoSwitch:"2.9.0+
  • AutoSwitch Interface

    This function automatically detects ports for connecting to a printer. It detects connectable ports according to the following order of priority.

    1. USB
    2. Bluetooth
    3. LAN

    The procedure for this function is as follow.

    1. Prepare an environment so that Android Device can be connected with the printer via Bluetooth or LAN.

      • Pair Android Device with the printer via Bluetooth.
      • Connect Android Device and the printer to the same network (same segment).
    2. Connect Android Device with the printer via USB.

    3. Specify “AutoSwitch:” for portName, and then execute this method.

    4. If Android Device is successfully connected with the printer via USB, Step 3 is succeeded. If not, check the USB connection of Android Device and the printer, and then try Step 3 again.

    5. Specifying “AutoSwitch:” for portName can help Android Device automatically connect using other interfaces even if it is not connected with the printer via USB.

    If you want to change the printer to use, start over from Step 1.

    We recommend using this function in the following cases.

    • When you can prepare an environment so that multiple interfaces including USB can be used.
    • When the connected interface is frequently changed during operation.
    • When you do not want to know the connected port in the program.

    Important

    • Enable the USB serial number setting for the printer.
    • Do not perform the USB connection and Bleutooth pairing with any other printers except for the connected printer.
    • If using a LAN interface, prepare the environment so that UDP port 22222 can be used.

    Warning

    • This function may require more time until you can start printing than specifying a port directly.

    Following models support this function.

    Model Firmware version
    mC-Print2 1.0+
    mC-Print3 1.0+

    Warning

    • Not support MCP20/MCP30
  1. portSettings Parameter

    The portSettings string is specified using the format shown below.

    The identifier that should be used with that model + option specification strings delimited by ‘;’.

    The identifier that should be used with each model is as shown below.

    Model

    Emulation

    Identifier

    mC-Print2 StarPRNT ""
    mC-Print3 StarPRNT ""
    mPOP StarPRNT ""
    FVP10 StarLine ""
    TSP100IIIW StarGraphic ""
    TSP100IIIBI StarGraphic ""
    TSP100IIIU StarGraphic ""
    TSP100ECO StarGraphic ""
    TSP100U StarGraphic ""
    TSP100GT StarGraphic ""
    TSP100LAN StarGraphic ""
    TSP650II StarLine ""
    TSP650IISK StarLine ""
    TSP700II StarLine ""
    TSP800II StarLine ""
    TUP500 StarLine ""
    SM-S210i StarPRNT "Portable"
    EscPosMobile"Portable;escpos" or "mini"
    SM-S220i StarPRNT "Portable"
    EscPosMobile"Portable;escpos" or "mini"
    SM-S230i StarPRNT "Portable"
    EscPosMobile"Portable;escpos" or "mini"
    SM-T300i/T300 StarPRNT "Portable"
    EscPosMobile"Portable;escpos" or "mini"
    SM-T400i StarPRNT "Portable"
    EscPosMobile"Portable;escpos" or "mini"
    BSC10 EscPos "escpos"
    SM-L200 StarPRNT "Portable"
    SM-L300 StarPRNT "Portable"
    SP700 StarDotImpact ""
    SK1-211/221/V211 StarPRNT ""
    SK1-211/221/V211 Presenter StarPRNT ""
    SK1-311/321/V311 StarPRNT ""
    SK1-311/V311 Presenter StarPRNT ""

    The option specification strings are shown below.

    Interface

    Option type

    Contents

    Example

    Library version

    Bluetooth

    d[value]

    Data timeout function timeout value setting.

    If the d option is not specified with a model that supports the data timeout function, the data timeout function is enabled and the timeout value is set to 3 seconds.

    The method for specifying the timeout time is the following.

    1. If a value from 1 to 255 was specified for [value]: Time that was specified for [value]
    2. If 0 was specified for [value] : Data timeout function is ignored
    3. Other than the above: 3 seconds
    "d10"2.2.2+

    l[value](lower case “L”)

    Connection retry will be performed.

    The method for specifying the retry time is the following.

    1. If a value will not be specified (“l” only) : Timeout time specified by the getPort
    2. If a value from 0 to 300000 was specified for [value]: Time that was specified for [value] (units: milliseconds).
    3. If a value of 300001 or more was specified for [value] : Timeout time specified by the getPort
    4. Other than the above: Retry is not performed.
    "l10000"2.2.2+
    Ethernet/Wireless LAN

    l[value](lower case “L”)

    Connection retry will be performed when the target printer is in use by another host.

    The method for specifying the retry time is the following.

    1. If a value will not be specified (“l” only) : Timeout time specified by the getPort
    2. If a value from 0 to 300000 was specified for [value]: Time that was specified for [value] (units: milliseconds).
    3. If a value of 300001 or more was specified for [value] : Timeout time specified by the getPort
    4. Other than the above: Retry is not performed.
    "l10000"2.3.0+

    [Port number]

    Port number(Only when using AirPort)

    "9100"2.2.2+
    • Data timeout function

      The data timeout function is a function which ignores the remaining print data when data was not sent to the printer within the specified length of time during printing.
      This function prevents corruption of the next print contents after the Bluetooth connection was disconnected during data sending.
      For usable models, refer to below.
      Model Firmware version
      mC-Print2 1.0+
      mC-Print3 1.0+
      mPOP 1.0+
      FVP10 2.0+
      TSP100IIIBI 1.0+
      TSP650II 2.0+
      TSP650IISK 1.0+
      TSP700II 5.0+
      TSP800II 2.0+
    • Example of portSettings

    Printer connection environment portSettings
    Uses TSP650II as the default setting. “”
    Uses mC-Print3 with retry enabled by Ethernet interface. “;l10000”
    Uses SM-L200 as the default setting “Portable”
    If data is not sent for 10 seconds during printing withTSP650II, it operates the data canceling function. “;d10”
  1. ioTimeoutMillis Parameter

    timeout is a ioTimeoutMillis timeout controlled internally and is used for communication in the APIs This parameter guarantees that all of the below APIs will complete in a bounded amount of time, but does NOT guarantee the exact timeout length.

    Timeout length is 10 seconds if specified less than 10 seconds.

    .

  1. Use share printer function with Apple AirPort Express

    Set AirPort Express IP Address for portName.

    Ex. TCP:192.168.1.2

    Set port number for portSettings.

    Increase the port number in sequential order from 9100 to 9109 until communication is successful.

  1. getPort Retry Flow

    In case your application prints to bluetooth printers, the getPort method may sometimes fail to get status or print as the result of failing to connect with the Android Device depending on Android Device and a use environment.

    When getPort fails a StarIOPortException is thrown. Please repeat the operations mentioned in article II and III below.

    ../_images/get_port_retry_flow.png
    1. getPort fails (StarIOPortException is thrown)
    2. Wait for certain time (e.g. 500ms)
    3. Execute getPort again
    4. When getPort is successful, go to procedures such as printing or getting status

    Important

    The number of attempts to execute getPort to obtain a port handle depends on the Android Device . Some devices have a higher failure rate than others, and may require additional attempts to getPort. Please decide based on tests conducted with your Android Device .

3.1.3. releasePort

Closes a port for communicating with the printer.

  • Declaration

    public static void releasePort(StarIOPort port);
    
  • Parameter

    Name Contents Type
    port A StarIOPort object previously created by the getPort method StarIOPort
  • Return value

    None

Refer to Printing flow .

Important

  1. Notes

    When do not send the data, release (close) ports. Leaving a port open will cause future calls to open the port to fail.

  2. For Ethernet Interface

    The getPort method may fail if you run it just after running releasePort.

    You must run the getPort method after 500msec from releasePort.

  3. Notes on compatibility

    Beginning from StarIOPort3.1.jar V2.6.0 (StarPRNT SDK V5.11.0), the readPort method behavior has been changed as shown below.

    • StarIOPort3.1.jar Version 2.5.0 and before

      In the case of calling getPort method multiple times before calling releasePort method, the port is released by calling releasePort method the same number of times as the getPort method was called.

    • StarIOPort3.1.jar Version 2.6.0 and later

      The port is always released when releasePort method is called.

3.1.4. searchPrinter

Search the Star printer and return search results.

  • Declaration

    public static ArrayList<PortInfo> searchPrinter(String target, Context context) throws StarIOPortException;
    public static ArrayList<PortInfo> searchPrinter(String target) throws StarIOPortException;
    
  • Parameter

    Name Contents Type
    target
    Specify the interface type of the Star printer to be searched.
    * Bluetooth I/F : BT:
    * Ethernet / Wireless LAN I/F : TCP:
    * USB I/F : USB:
    StarIOPort
    context
    context
    Required when specifying USB: for target.
    android.context.Contex
  • Return value

    Contents Type
    Search result of Star printer
    Refer to PortInfo class.
    ArrayList<PortInfo>
  • Exception

    Contents Type
    When port open fails.
    When an incorrect target is passed.
    StarIOPortException
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.
  • Examples

    try {
        //Searches for an Ethernet / Wireless LAN interface Star printer on the same network.
        List<PortInfo> portList = StarIOPort.searchPrinter("TCP:");
    
        for (PortInfo port : portList) {
            Log.i ("LOG", "Port Name: " + port.getPortName());
            Log.i ("LOG", "MAC Address: " + port.getMacAddress());
            Log.i ("LOG", "Model Name: " + port.getModelName());
        }
    }
    catch (StarIOPortException e) {
        // An error occurred.
    }
    

    Refer to SearchPortFragment.java.

Important

  1. When reconnecting the USB printer

    When reconnecting the USB printer, re-execute the searchPrinter method and get the latest printer information.

  2. Restrictions

    This API do not guarantee the discovery of devices.

  3. Restrictions in Android 7.0 or higher

    In Android 7.0 or higher, portName which is got by searchPriner method, (for example, USB:1-3) has some limitations. It changes everytime the USB printer is connected. Set portName to USB: to use only one printer and USB:SN:serial number to use multiple printers.

3.1.5. writePort

Write data to the printer.

  • Declaration

    public void writePort(byte[] writeBuffer, int offset, int size) throws StarIOPortException;
    
  • Parameter

    Name Contents Type
    writeBuffer Contains the output data in a byte array byte[]
    offset Specifies where to begin pulling data from writeBuffer. int
    size Number of bytes to write int
  • Return value

    None

  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.

Refer to Printing flow .

3.1.6. readPort

Read data from the printer. Please use it only when it is necessary to read Raw byte from the printer.

  • Declaration

    public void readPort(byte[] readBuffer, int offset, int size) throws StarIOPortException;
    
  • Parameter

    Name Contents Type
    readBuffer A Byte Array buffer into which data is read. byte[]
    offset specifies where to begin writing data into the readBuffer int
    size Total number of bytes to read int
  • Return value

    Contents Type
    The number of bytes that were read
    This method will succeed even when no all data was read in. Your application should call this function a limited number of times until the expected data has been read in or until an application determined retry threshold has been reached.
    int
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.

3.1.7. retreiveStatus

Get printer status.

  • Declaration

    public StarPrinterStatus retreiveStatus() throws StarIOPortException;
    
  • Parameter

    None

  • Return value

    Contents Type
    Current printer status
    For the type of status that can be obtained, refer to the StarPrinterStatus structure.
    StarPrinterStatus
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.
  • Examples

    if (status.offline == false) {
        // Printer OnLine
        if (status.paperDetectionError == true) {
            // Paper detection error
        }
        if (status.compulsionSwitch == true) {
            // Cashdrawer Open
        }
        else {
            // Cashdrawer Close
        }
    }
    else {
        // Printer Offline
    }
    

    Refer to Communication.java.

3.1.8. beginCheckedBlock

This method is used in combination with endCheckedBlock and checks the completion of printing.

To check if the whole data is completely printed, you need to run this method just before sending print data and endCheckedBlock just after sending print data.

When the control of hold print control is enabled, this method blocks until the paper is removed, and returns control to the application when it is removed. If paper is not removed within the timeout specified by the setHoldPrintTimeoutMillis, the error is occured.

  • Declaration

    public StarPrinterStatus beginCheckedBlock() throws StarIOPortException;
    
  • Parameter

    None

  • Return value

    Contents Type
    Current printer status
    For the type of status that can be obtained, refer to the StarPrinterStatus structure.
    StarPrinterStatus
  • Exception

    Contents Type
    when a communication failure occurs
    when the printer is off line
    StarIOPortException
  • Error code

    Value

    Contents

    Library version

    StarResultCode.FAILURE_PAPER_PRESENT

    Paper was not removed within the timeout.

    2.7.0+

    StarResultCode.FAILURE

    Some kind of error occurred.

    2.2.2+

  • Examples

    Refer to Printing flow about the procedure of the print end monitoring process by beginCheckedBlock / endCheckedBlock.

3.1.9. endCheckedBlock

This method is used together with the beginCheckedBlock method as a pair.

This method monitors printer status and when the transferred data is printed completely, it returns control to the application.

  • Declaration

    public StarPrinterStatus endCheckedBlock() throws StarIOPortException;
    
  • Parameter

    None

  • Return value

    Contents Type
    Current printer status
    For the type of status that can be obtained, refer to the StarPrinterStatus structure.
    StarPrinterStatus
  • Exception

    Contents Type
    when a communication failure occurs
    No response for the completion of printing from a printer within the timeout
    StarIOPortException
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.
  • Examples

    Refer to Printing flow about the procedure of the print end monitoring process by beginCheckedBlock / endCheckedBlock.

3.1.10. setEndCheckedBlockTimeoutMillis

This method sets the endCheckedBlock method’s timeout value [unit: ms]

If it takes a long time to print, please increase this value to allow for enough time to complete the print job.

  • Declaration

    public void setEndCheckedBlockTimeoutMillis(int endCheckedBlockTimeoutMillis);
    
  • Parameter

    Name Contents Type
    endCheckedBlockTimeoutMillis Sets the endCheckedBlock method’s timeout value [unit: ms] int
  • Return value

    None

Important

Default value of endCheckedBlock method timeout value is the timeout value designated by StarIOPort_getPort method. Timeout length is 10 seconds if specified less than 10 seconds.

When [Data timeout function setting] is used in the portSetting parameter of the getPort method, it should be at least 3 seconds longer than the time specified for the data timeout function. If it is set to less than 3 seconds, it will be controlled internally to be 3 seconds longer automatically.

3.1.11. setHoldPrintTimeoutMillis

added in version 2.7.0

Timeout value for hold print control. [unit: ms]

  • Declaration

    public void setHoldPrintTimeoutMillis(int holdPrintTimeoutMillis);
    
  • Parameter

    Name Contents Type
    holdPrintTimeoutMillis Timeout value for hold print control. [unit: ms] int
  • Return value

    None

3.1.12. getFirmwareInformation

Gets printer model name and firmware version.

  • Declaration

    public Map<String, String> getFirmwareInformation() throws StarIOPortException;
    
  • Parameter

    None

  • Return value

    Contents Type
    The Map object of the firmware information acquisition result

    The return value can get the model name by setting the Map object key of the return value to “ModelName” and get the firmware version by setting “FirmwareVersion”.
    Map<String, String>
  • Error code

    Value Contents
    StarResultCode.FAILURE Some kind of error occurred.
  • Examples

    try {
        Map<String, String> firmwareInformationMap = port.getFirmwareInformation();
    
        Log.i ("LOG", "Model Name: " + firmwareInformationMap.get("ModelName"));
        Log.i ("LOG", "Firmware Version: " + firmwareInformationMap.get("FirmwareVersion"));
    }
    catch (StarIOPortException e) {
        // Error
    }
    

    Refer to DeviceStatusFragment.java and Communication.java.

3.1.13. getPortName

Get the portName when the port is opened.

  • Declaration

    public String getPortName();
    
  • Parameter

    None

  • Return value

    Contents Type
    The portName parameter passed to the getPort method String

3.1.14. getPortSettings

Get the portSettings when the port is opened.

  • Declaration

    public String getPortSettings();
    
  • Parameter

    None

  • Return value

    Contents Type
    The portSettings parameter passed to the getPort method String

3.1.15. getStarIOVersion

Get the version number of the StarIO library.

  • Declaration

    public String getStarIOVersion();
    
  • Parameter

    None

  • Return value

    Contents Type
    StarIO library version String