6.1. ISCBBuilder Migration Guide (A Function Incorporated in the StarPRNT V5)
This is an ISCBBuilder migration guide to minimize printer-model dependency.
ISCBBuilder is a function that enables human-readable command creation instead of conventional binary command creation and incorporated in the extension library of StarPRNT V5.0 or later (hereinafter, StarIO_Extension )
Until now, developers had to create commands after understanding the specifications of printer emulation, however this function can reduce learning costs and man-hours for adding printer models
Please use ISCBBuilder referring to this guide.
6.1.1. Required Work Contents
The works required to migrate to ISCBBuilder and add a printer model are as follows.
Important
Depending on the combination of printer models, it may be necessary to change the portSettings specification .
6.1.2. Implement StarIO_Extension
Make sure that your project includes StarIO_Extension. Use libraries of the same SDK version.
1. Using CocoaPods
PodFilepod 'StarIO', 'StarIOVersion' pod 'StarIO_Extension', 'StarIOExtensionVersion' pod 'SMCloudServices', 'SMCloudServicesVersion'
2. Using Framework
Make sure that your project includes following.
StarIO.xcframework
StarIO_Extension.xcframework
SMCloudServices.xcframework
Details of the library installation procedure are described in How to add the library .
6.1.3. How to change API and command creation method (Introduction of ICommandBuilder)
Differences in overall flow
As shown in the following flow, no changes other than the command creation method are required to use ISCBBuilder .
Changes in print data creation program (printer built-in font)
The code for printing the printer built-in font used for characters on receipts will change as shown in the sample below. Please make the necessary change according to the function you are using.
See ISCBBuilder for a list of supported features.
Note
The TSP100 series does not support printer fonts. Please see Changes in Changes in print data creation program (image data)
NSMutableData *commands = [NSMutableData new];
Byte initial[] = {0x1b, 0x40}; // Initialization
[commands appendBytes:initial length:2];
Byte alignment[] = {0x1b, 0x1d, 0x61, 0x01}; // Alignment
[commands appendBytes:alignment length:4];
[commands appendData:[@"Hello World" dataUsingEncoding:NSASCIIStringEncoding]];
Byte alignment[] = {0x1b, 0x64, 0x02}; // Cut paper
ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];
[builder beginDocument];
[builder appendAlignment:SCBAlignmentPositionRight];
NSData *textData = [@"Hello World" dataUsingEncoding:NSASCIIStringEncoding];
[builder appendData:textData];
[builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
[builder endDocument];
[builder.commands copy];
Changes in print data creation program (image data)
The code for printing image data used for store logos etc.
See ISCBBuilder for a list of supported features.
ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];
[builder beginDocument];
[builder appendBitmap:bitmap_image diffusion:YES]; // create Star command from bitmap data
[builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
[builder endDocument];
[builder.commands copy];
6.1.4. How to add a printer model
When adding or migrating a printer model, if you are using ISCBBuilder to create printer commands, you will only need to change the emulation in most cases.
However, in some situations, additional changes are required. Please make the necessary changes referring to the information below.
How to change the emulation ( ISCBBuilder )
The mC-Print3 and other printers may support different emulations.
Check the supported emulation on the StarIoExtEmulation page and change the emulation when creating an ISCBBuilder instance.
For example, in case of TSP100/TSP650II and mC-Print3, it is necessary to change the emulation according to the table below.
Printer |
StarIoExtEmulation |
---|---|
TSP650II |
StarIoExtEmulationStarLine |
TSP100 |
StarIoExtEmulationStarGraphic |
mC-Print3 |
StarIoExtEmulationStarPRNT |
// TSP650II (StarLine)
// StarIoExtEmulation emulation = StarIoExtEmulationStarLine
// TSP100 (StarGraphic)
// StarIoExtEmulation emulation = StarIoExtEmulationStarGraphic
// mC-Print3 (StarPRNT)
StarIoExtEmulation emulation = StarIoExtEmulationStarPRNT
ISCBBuilder *builder = [StarIoExt createCommandBuilder:emulation];
How to search for printers ( searchPrinter )
The printer search method by searchPrinter is the same.
If the model name obtained from the search is used for some determination in the application, it is necessary to change it
For example, The printer model names included in the search results are as follows.
LAN interfaces
Printer
Model Name (PortInfo)
mC-Print2
“MCP21”, “MCP20”
mC-Print3
“MCP31”, “MCP30”
mC-Label3
“MCL32”
TSP100IV
“TSP143IV”
TSP100IV SK
“TSP143IV”
TSP100IIILAN
“TSP143IIILAN”, “TSP143IIIW”
TSP650II
“TSP654”
TSP700II
“TSP743II”
TSP800II
“TSP847II”
BSC10II
“BSC10II”
SP700
“SP712”, “SP742”, “SP717”, “SP747”
Bluetooth/Lightning interface
Printer
Model Name (PortInfo)
mC-Print2
“MCP21LB””, “MCP20B”, “MCP20L”
mC-Print3
“MCP31L”, “MCP31LB”, “MCP31CI”, “MCP31CBI”
mC-Label3
“MCL32CI”, “MCL32CBI”
mPOP
“POP10CBI”, “POP10CI”, “POP10 BLK”, “POP10 WHT”
TSP100III
“TSP143IIIU WT”, “TSP143IIIU GY”, “TSP143IIIBI WT”, “TSP143IIIBI GY”
TSP650II
“Star Micronics”
TSP700II
“Star Micronics”
TSP800II
“Star Micronics”
SP700
“Star Micronics”
SM-S210i
"SM-S210"[3], "SM-S210I"[4] SM-S230i
"SM-S230"[3], "SM-S230I"[4] SM-T300i
"SM-T300"[3], "SM-T300I"[4] SM-T400i
"SM-T400"[3], "SM-T400I"[4] SM-L200
“SM-L200”
SM-L300
“SM-L300”
[3] | Firmware version less than 5.0 |
[4] | Firmware version 5.0 or later |
How to specify getPort - portName parameter
Bluetooth/Lightning interface
If the return value of searchPrinter ( PortInfo ) is used to specify portName , there is no need to change the parameter.
However, if the parameter is specified directly (fixed value, etc.), the default value of the device name differs between mC-Print3 and other models, so the parameter may need to be changed.
For example, the default values of TSP100/TSP650II and mC-Print3 are as follows.
Printer |
iOS Port Name |
---|---|
TSP100 |
“TSP100” |
TSP650II |
“Star Micronics” |
mC-Print3 |
“mC-Print3” |
SMPort *port = nil;
NSString *portSettings = "";
// TSP650II (Bluetooth)
// NSString *portName = "BT:Star Micronics";
// TSP100 (Bluetooth)
// NSString *portName = "BT:TSP100";
// mC-Print3 (Bluetooth)
// NSString *portName = "BT:mC-Print3";
// No changes required if used "BT:"
NSString *portName = "BT:";
port = [SMPort getPort:portName :portSettings :(uint32_t) timeout :&error];
Other interfaces
No specific device names are specified for each printer. Refer to the getPort page and set the appropriate portName for each interface.
How to specify getPort - portSettings parameter
The identifier that should be used with each model may be different. Please change it referring to 2. portSettings Parameter of getPort .
For example, the identifiers of portSettings
of TSP100/TSP650II and mC-Print3 are the same.
Printer |
portSettings |
---|---|
TSP100 |
“” |
TSP650II |
“” |
mC-Print3 |
“” |
SMPort port = nil;
NSString *portName = "BT:";
// NSString *portSettings = "l10000"
NSString *portSettings = "";
port = [SMPort getPort:portName :portSettings :(uint32_t) timeout :&error];
How to specify the printable area
The initial value of the printable area setting differs depending on the printer models. Specify the printable area with appendPrintableArea as necessary.
If graphic data is printed by using appendBitmap etc., please change the layout according to the printable area of the printer model you want to migrate to.
6.1.5. Code flow from command creation to data transmission
The following is the flow from command creation to writing. In actual operation, execute the following function in a non-UI thread.
-(void) printSample {
ISCBBuilder *builder = [StarIoExt createCommandBuilder:StarIoExtEmulationStarPRNT];
[builder beginDocument];
[builder appendData:[@"Hello World" dataUsingEncoding:NSASCIIStringEncoding]];
[builder appendCutPaper:SCBCutPaperActionPartialCutWithFeed];
[builder endDocument];
Byte commands[] = [builder.commands copy];
NSString *portName = "BT:";
NSString *portSettings = "";
SMPort *port = [SMPort getPort:portName :portSettings :10000 :&error];
if (port == nil) {
// ERROR
code = error.code;
}
StarPrinterStatus_2 printerStatus;
result = CommResultErrorBeginCheckedBlock;
[port beginCheckedBlock:&printerStatus :2 :&error];
if (error != nil) {
// ERROR
code = error.code;
}
uint32_t total = 0;
while (total < (uint32_t) commands.length) {
uint32_t written = [port writePort:(unsigned char *) commands.bytes :total :(uint32_t) commands.length - total :&error];
if (error != nil) {
// ERROR
code = error.code;
}
total += written;
}
port.endCheckedBlockTimeoutMillis = 30000;
result = CommResultErrorEndCheckedBlock;
[port endCheckedBlock:&printerStatus :2 :&error];
if (error != nil) {
// ERROR
code = error.code;
}
if (printerStatus.offline == SM_TRUE) {
// OFFLINE
}
result = CommResultSuccess;
code = SMStarIOResultCodeSuccess;
}