3.1. SMPort

Class to communicate with a printer.

  • Method

    Name

    Contents

    getPort

    Opens a port for communicating with the printer.

    releasePort

    Closes a port for communicating with the printer.

    searchPrinter

    Search for printers that can connect to devices.

    writePort

    Write data to the printer.

    readPort

    Read data from the printer.

    getParsedStatus

    Get printer status.

    beginCheckedBlock

    Starts to check completion of printing.

    endCheckedBlock

    Terminates to check completion of printing.

    disconnect

    Disconnects the specified Bluetooth device.

    getFirmwareInformation

    Gets printer model name and firmware version.

    portName

    Get the portName when the port is opened.

    portSettings

    Get the portSettings when the port is opened.

    timeoutMillis

    Acquires the timeout time for internal control and API. (unit: millisecond)

    connected

    Acquires the connection status with the iOS device of the specified Bluetooth/Bluetooth Low Energy printer.

    StarIOVersion

    Get the version number of the StarIO library.

  • Model: SMPort class

Model/Emulation

mC-Print2 mC-Print3 mPOP FVP10 TSP100IIIW TSP100IIIBITSP100IIIU TSP100ECO TSP100U TSP100GTTSP100LAN TSP650II TSP650IISK TSP700II TSP800IISM-S210i SM-S220i SM-S230i SM-T300i/T300 SM-T400i BSC10 SM-L200 SM-L300 SP700
StarPRNT StarPRNT StarPRNT StarLine StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarGraphic StarLine StarLine StarLine StarLine StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile StarPRNT EscPosMobile EscPos StarPRNT StarPRNT StarDotImpact

getPort

releasePort

searchPrinter

writePort

readPort

getParsedStatus

beginCheckedBlock

[1] [1]

endCheckedBlock

[1] [1]

disconnect

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

holdPrintTimeoutMillis

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

getFirmwareInformation

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

portName

portSettings

timeoutMillis

connected

- - - - - - -

StarIOVersion

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

3.1.1. Printing flow

Using the SMPort class, print per the following procedure.

../_images/port_flow.png
  • Examples

    unsigned char command[] = {0x41, 0x42, 0x43, 0x44, 0x1B, 0x7A, 0x00, 0x1B, 0x64, 0x02};
    
    StarPrinterStatus_2 printerStatus;
    SMPort *port = nil;
    
    while (YES) {
        NSError *error = nil;
    
        // Open port
        port = [SMPort getPort: "BT:Star Micronics" :@"" :10000 :&error];
    
        if (port == nil) {    break;  /* Some error occurred. */    }
    
        // Start to check the completion of printing
        [port beginCheckedBlock:&printerStatus :2 :&error];
    
        if (error != nil) {    break;  /* Some error occurred. */    }
    
        if (printerStatus.offline == SM_TRUE) {
        break;    // The printer is offline.
        }
    
        uint32_t total = 0;
    
        while (total < (uint32_t) commands.length) {
        // Send print data
        uint32_t written = [port writePort:command :total : sizeof(command) - total :&error];
    
        if (error != nil) {    break;  /* Some error occurred. */    }
    
        total += written;
        }
    
        // Stop to check the completion of printing
        [port endCheckedBlock:&printerStatus :2 :&error];
    
        if (error != nil) {    break;  /* Some error occurred. */    }
    
        if (printerStatus.offline == SM_TRUE) {
        break;    // The printer is offline.
        }
    
        // Success
        break;
    }
    
    if (port != nil) {
        // Close port
        [SMPort releasePort:port];
        port = nil;
    }
    

    Refer to Communication.m

3.1.2. endCheckedBlockTimeoutMillis

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

    @property (assign, readwrite, nonatomic) u_int32_t endCheckedBlockTimeoutMillis;
    

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.3. holdPrintTimeoutMillis

added in version 2.8.0

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

  • Declaration

    @property(assign, readwrite, nonatomic) u_int32_t holdPrintTimeoutMillis;
    

3.1.4. getPort

added in version 2.6.0

Opens a port for communicating with the printer.

  • Declaration

    + (SMPort *)getPort:(NSString *)portName :(NSString *)portSettings :(u_int32_t)ioTimeoutMillis :(NSError **)error;
    
  • Parameter

    Name Contents Type
    portName The printer port name NSString *
    portSettings Specifies connection setting information. NSString *
    ioTimeoutMillis The timeout time for internal control and API (unit: millisecond) u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • Return value

    Contents Type
    SMPort object
    It returns nil if it fails to generate communication port.
    SMPort
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred
    SMStarIOResultCodeInUseError 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:iOS Port Name

To specify the iOS Port Name

"BT:Star Micronics" 2.2.3+
BT:Serial Number

To specify the printer using the serial number

"BT:2580217090400032" 2.4.0+
Bluetooth Low Energy BLE:Device Name

To specify the Bluetooth device name

"BLE:STAR L200-00001" 2.2.3+
BLE:MAC Address

To specify the MAC address

"BLE:00:11:62:00:00:00" 2.2.3+
Ethernet/Wireless LAN TCP:IP Address

To specify the IP address

"TCP:192.168.1.100"2.2.3+
USB USB:Device Name

To specify the iOS Port Name

"USB:TSP100" 2.2.3+
USB:Serial Number

To specify the printer using the serial number

"USB:2580217090400032" 2.4.0+
USB/Bluetooth/LAN AutoSwitch:

Using AutoSwitch Interface

"AutoSwitch:"2.8.0+

Important

With models that support both Bluetooth and USB (Lightning), there is no differentiation between Bluetooth and USB, and the same behavior occurs in both cases. If the Lightning cable is connected while a Bluetooth connection is active, Bluetooth will be automatically disconnected and communication will occur via Lightning. However it is not necessary to change portName from "BT" to "USB" at this time.

  • 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 iOS Device can be connected with the printer via Bluetooth or LAN.

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

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

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

    5. Specifying “AutoSwitch:” for portName can help iOS 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 ""
    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 ""

    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.3+
    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.4.0+

    [Port number]

    Port number(Only when using AirPort)

    "9100" 2.2.3+
    • 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. Notification in case of SM-L Series

    It could take some time when an iOS Device tries to connect to a printer via “Bluetooth Low Energy”. If the connection fails, retry until the connection is successful.

    If the connection time must be reduced, please design your application as the connection to a printer always keeps opening.

    In this case, the printer cannot be detected by any other applications and iOS Device .

3.1.5. releasePort

Closes a port for communicating with the printer.

  • Declaration

    + (void) releasePort:(SMPort *)port;
    
  • Parameter

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

    None

Refer to Printing flow .

Warning

After executing getPort, please do not forget releasePort before executing the next getPort. Otherwise the communication may return nil .

3.1.6. searchPrinter

added in version 2.6.0

Search the Star printer and return search results.

  • Declaration

    + (NSArray *)searchPrinter:(NSString *)target :(NSError **)error;
    
  • Parameter

    Name Contents Type
    target
    All interface types: "All:"
    Bluetooth: "BT:"
    Bluetooth Low Energy: "BLE:"
    Ethernet/Wireless LAN: "TCP:"
    USB: "USB:"
    NSString *
    error
    Connection failure error information
    An error code is set in the code property.
    NSError *
  • Return value

    Contents Type
    Search result of Star printer
    Refer to PortInfo class.
    NSArray *
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.
  • Examples

    NSArray *portInfoArray;
    
    NSError *error = nil;
    
    portInfoArray = [SMPort searchPrinter:@"ALL:" :&error];
    
    if (error != nil) {
        // Some error occurred.
    }
    
    if (portInfoArray == nil) {
        return;
    }
    
    for (PortInfo *portInfo in portInfoArray) {
        NSLog(@"Port Name: %@", portInfo.portName);
        NSLog(@"MAC Address: %@", portInfo.macAddress);
        NSLog(@"Model Name: %@", portInfo.modelName);
    }
    

    Refer to SearchPortViewController.m.

Important

With models that support both Bluetooth and USB (Lightning), there is no differentiation between Bluetooth and USB.

Regardless of the actual connection method, when a target is not specified or when "BT:" is specified, the printer is detected as a Bluetooth printer, and when "USB" is specified it is detected as a USB printer.

  1. Restrictions

    This API do not guarantee the discovery of devices.

  2. Notes with the Bluetooth Low Energy interface

    When getting the printer device name using searchPriner method for the first time, sometimes portName will be "BLE:" .

    In those cases, please connect the printer using getPort method. Once you have got the Device name, searchPrinter method works correctly.

3.1.7. writePort

Write data to the printer.

  • Declaration

    - (u_int32_t)writePort:(u_int8_t const *)writeBuffer :(u_int32_t)offset :(u_int32_t)size :(NSError **)error;
    
  • Parameter

    Name Contents Type
    writeBuffer Contains the output data in a byte array u_int8_t const *
    offset Specifies where to begin pulling data from writeBuffer. u_int32_t
    size Number of bytes to write u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • Return value

    Contents Type
    Bluetooth/Ethernet/Wireless LAN/USB I/F
    The number of bytes that were actually written.
    This method is successful even when all of the data cannot be written. Your application should call this function a limited number of times until all the data has been written out or until an application determined retry threshold has been reached.

    Bluetooth Low Energy I/F
    It returns a transmission data size when it succeeded and “0” when it failed.
    u_int32_t
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.

Refer to Printing flow .

3.1.8. readPort

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

  • Declaration

    - (u_int32_t)readPort:(u_int8_t *)readBuffer :(u_int32_t)offset :(u_int32_t)size :(NSError **)error;
    
  • Parameter

    Name Contents Type
    readBuffer A Byte Array buffer into which data is read. u_int8_t *
    offset specifies where to begin writing data into the readBuffer u_int32_t
    size Total number of bytes to read u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • 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.
    u_int32_t
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.

Important

Beginning from StarIO.framework v2.4.0 (StarPRNT SDK v5.6.0), the readPort behavior when a LAN printer is used has been changed as shown below.

When the data that should be received when readPort is executed does not exist
  • v2.3.3 and before: Throws a PortException .
  • v2.4.0 and later: Returns 0 .

3.1.9. getParsedStatus

Get printer status.

  • Declaration

    - (NSUInteger)getParsedStatus:(void *)starPrinterStatus :(u_int32_t)level :(NSError **)error;
    
  • Parameter

    Name Contents Type
    starPrinterStatus
    Giving the current device status.
    For the type of status that can be obtained, refer to the StarPrinterStatus structure.
    void *
    level
    StarPrinterStatus structure level
    (Possible to specify a value of 0, 1 or 2. Normally 2 is specified.)
    u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • Return value

    Contents Type
    Successful: 1
    Failure: 0
    NSUInteger
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.
  • Examples

    StarPrinterStatus_2 printerStatus;
    NSError *error = nil;
    
    [port getParsedStatus: &printerStatus : 2 : &error];
    
    if (error != nil) {
        // Some error occurred.
    }
    if (printerStatus.offline == SM_TRUE) {
        if (printerStatus.coverOpen == SM_TRUE) {
            // Cover is open.
        }
        else if (printerStatus.receiptPaperEmpty == SM_TRUE) {
            // Receipt paper is empty.
        }
        else {
            // The printer is offline.
        }
    }
    else {
        // The printer is online.
    }
    

    Refer to DeviceStatusViewController.m.

3.1.10. 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 holdPrintTimeoutMillis, the error is occured.

  • Declaration

    - (NSUInteger)beginCheckedBlock:(void *)starPrinterStatus :(u_int32_t)level :(NSError **)error;
    
  • Parameter

    Name Contents Type
    starPrinterStatus
    A pointer to StarPrinterStatus structure
    (Possible to specify StarPrinterStatus, StarPrinterStatus_1 of StarPrinterStatus_2. Normally StarPrinterStatus_2 is specified.)
    When this method is successful, the status of the current printer is stored.
    void *
    level
    StarPrinterStatus structure level
    (Possible to specify a value of 0, 1 or 2. Normally 2 is specified.)
    u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • Return value

    Contents Type
    Successful: 1
    Failure: 0
    NSUInteger
  • Error code

    Value

    Contents

    Library version

    SMStarIOResultCodePaperPresentError

    Paper was not removed within the timeout.

    2.8.0+

    SMStarIOResultCodeFailedError

    Some kind of error occurred.

    2.2.3+

  • Examples

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

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

    - (NSUInteger)endCheckedBlock:(void *)starPrinterStatus :(u_int32_t)level :(NSError **)error;
    
  • Parameter

    Name Contents Type
    starPrinterStatus
    A pointer to StarPrinterStatus structure
    (Possible to specify StarPrinterStatus, StarPrinterStatus_1 of StarPrinterStatus_2. Normally StarPrinterStatus_2 is specified.)
    When this method is successful, the status of the current printer is stored.
    void *
    level
    StarPrinterStatus structure level
    (Possible to specify a value of 0, 1 or 2. Normally 2 is specified.)
    u_int32_t
    error
    Connection failure error information
    An error code is set in the code property.
    NSError **
  • Return value

    Contents Type
    Successful: 1
    Failure: 0
    NSUInteger
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.
  • Examples

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

3.1.12. disconnect

Disconnects the specified Bluetooth device.

After the disconnection, the Bluetooth device can be connected by other iOS Device .

  • Declaration

    - (BOOL)disconnect:(NSError **)error;
    
  • Parameter

    Name Contents Type
    error
    Connection failure error information
    An error code is set in the code property.
    NSError *
  • Return value

    Contents Type
    Disconnect success and fail

    This method fails in the following cases:
    * when the disconnection has not been completed within the timeout specified by getPort
    * when the disconnection function is not supported by a printer (such like portable printers).

    This method has no effect on Ethernet devices.
    It always returns YES when it was run with the Ethernet device.
    BOOL
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.

3.1.13. getFirmwareInformation

Gets printer model name and firmware version.

  • Declaration

    - (NSDictionary *)getFirmwareInformation:(NSError **)error;
    
  • Parameter

    Name Contents Type
    error
    Connection failure error information
    An error code is set in the code property.
    NSError *
  • Return value

    Contents Type
    An acquisition result of firmware information

    The return value can get the model name by setting the NSDictionary object key of the return value to "@ModelName" and get the firmware version by setting "@FirmwareVersion" .
    NSDictionary *
  • Error code

    Value Contents
    SMStarIOResultCodeFailedError Some kind of error occurred.

3.1.14. portName

Get the portName when the port is opened.

  • Declaration

    - (NSString *) portName;
    

3.1.15. portSettings

Get the portSettings when the port is opened.

  • Declaration

    - (NSString *) portSettings;
    

3.1.16. timeoutMillis

Get the portSettings specified by getPort method.

  • Declaration

    - (u_int32_t) timeoutMillis;
    

3.1.17. connected

If the printer is connected to an iOS device, it returns YES. If the printer is not connected to an iOS device, it returns NO.

  • Declaration

    - (BOOL) connected;
    

Important

Only Bluetooth/Bluetooth Low Energy interfaces are supported. For non-supported interfaces, it constantly returns YES.

Due to the restrictions of the iOS device, it takes approximately 5 seconds from Bluetooth/Bluetooth Low Energy communication disconnecting until being reflected in this property.

3.1.18. StarIOVersion

Get the version number of the StarIO library.

  • Declaration

    + (NSString *)StarIOVersion;
    
  • Parameter

    None

  • Return value

    Contents Type
    StarIO library version NSString *