Objective-C SDK

The Objective-C SDK is designed for native iOS applications and connects to printers over Bluetooth Low Energy (BLE).

Installation

1. Download frameworks

Download the frameworks from GitHub: Package Center

2. Import frameworks

Required frameworks:

• adapter.framework - Device adapter
• father.framework - Core framework

Optional frameworks:

• cpcl.framework - CPCL commands
• esc.framework - ESC commands
• tspl.framework - TSPL commands

3. Select an API

Import the APIs for your printer’s command language:

Command language	Import headers
ESC	IbridgeBleApi
CPCL	FscBleApi
TSPL	applebleApi

Quick start

Initialize

@interface PrinterVC ()
@property (nonatomic, strong) CBPeripheral *currentConnectedPeripheral;
@property (nonatomic, strong) Lifecycle *lifeCycle;
@end

@implementation PrinterVC

- (void)viewDidLoad {
    [super viewDidLoad];

    // Initialize lifecycle
    _lifeCycle = [[Lifecycle alloc] init];
    _lifeCycle.connectedDevice(self.device);
}

ESC command usage

ESC commands are widely used by thermal receipt printers. See the ESC command reference for details.

Initialize ESC

#import <esc/esc.h>

@property (nonatomic, strong) AYEscCommand *esc;

- (void)setupESC {
    _esc = [AYEscCommand new];
}

Complete printing workflow

Recommended sequence:

1. Wake the printer
2. Enable the printer
3. Print the image
4. Position the paper (not needed for continuous paper)
5. End the print job

// Initialize ESC Command object
AYEscCommand *esc = [AYEscCommand new];
// Wakeup command
[esc wake];
// Enable the printer
[esc enable];
// Print an image
[esc image:[UIImage imageNamed:@"label.png"] compress:NO mode:Normal];
// Label positioning (No positioning needed for continuous paper!)
[esc position];
// End the print job
[esc stopPrintJob];
// Send commands over Bluetooth
[self.bleHelper writeCommands:esc.commands];

Print commands

Wake the printer

[esc wake];

Enable the printer

[esc enable];

Print an image

typedef NS_ENUM(NSInteger, EImageMode) {
    Normal = 0,      // Normal printing
    DoubleWidth,     // Double-width printing
    DoubleHeight,    // Double-height printing
    DoubleAll        // Double-width and double-height printing
};

/**
 * Print an image
 * @param image Image
 * @param compress Enable compression
 * @param mode Print mode
 */
[esc image:image compress:NO mode:Normal];

Position the paper

[esc position];

End the print job

[esc stopPrintJob];

Configuration commands

Set shutdown timeout

/**
 * Set shutdown timeout
 * @param time Shutdown timeout, Units: Minutes, Pass this value to disable shutdown: 0
 */
AYEscCommand *esc = [AYEscCommand new];
[esc shutTime:10];
[self.bleHelper writeCommands:esc.commands];
// A successful setting invokes the callback escSettingChange

Set density

typedef NS_ENUM(NSInteger, EThickness) {
    EThicknessLow,      // Low density
    EThicknessMedium,   // Medium density
    EThicknessHigh      // High density
};

AYEscCommand *esc = [AYEscCommand new];
[esc thickness:EThicknessMedium];
[self.bleHelper writeCommands:esc.commands];

Set paper type (A4)

typedef NS_ENUM(NSInteger, EPaperType) {
    EPaperTypeBlackMark = 0,    // Black mark paper mode
    EPaperTypeContinuous,       // Continuous paper mode
    EPaperTypeGap,              // Gap paper mode
    EPaperTypeHole,             // Punched paper mode
    EPaperTypeTattoo,           // Tattoo paper mode
    EPaperTypeTattooWrinkles,   // Tattoo paper (Anti-wrinkle mode)
};

AYEscCommand *esc = [AYEscCommand new];
[esc paperType:EPaperTypeContinuous];
[self.bleHelper writeCommands:esc.commands];

Set paper type (Q1/Q2/Q3/D11/D30/B21/B22)

typedef NS_ENUM(NSInteger, EPaperTypeQX) {
    EPaperTypeQXGap,              // Gap paper mode
    EPaperTypeQXBlackMark,        // Black mark paper mode
    EPaperTypeQXContinuous,       // Continuous paper mode
};

AYEscCommand *esc = [AYEscCommand new];
[esc paperTypeQX:EPaperTypeQXGap];
[self.bleHelper writeCommands:esc.commands];

Query commands

Callback handling

A successful query invokes the escQueryChange callback with the configured type and data.

AYEscCommand *esc = [AYEscCommand new];

// Query printer information
[esc printerInfo];

// Query printer status
[esc state];

// Query battery level
[esc batteryVol];

// Query Bluetooth name
[esc btName];

// Query printer firmware version
[esc printerVersion];

// Query MAC Address
[esc mac];

// Query SN Number
[esc sn];

// Query printer model
[esc printerModel];

// Send commands
[self.bleHelper writeCommands:esc.commands];

Unsolicited reports

Device status reports

When an abnormal condition occurs, the printer sends a two-byte status message to the application. See the demo’s onPrinterAutoReport callback for the result.

Header	Status type	Meaning
0xFF	0x00	Printer normal
0xFF	0x01	Overheated
0xFF	0x02	Cover open
0xFF	0x04	Out of paper
0xFF	0x08	Low voltage

Paper type reports

The device sends a report when the detected paper does not match the paper type configured by the application:

Header	Status type	Meaning
0xFE	0x01	Fanfold black mark paper
0xFE	0x02	Continuous roll paper
0xFE	0x03	Adhesive gap labels

Print cancellation reports

Header	Status type	Meaning
0xFD	0x01	Start clearing the current page’s print job
0xFD	0x02	Current print job cleared

TSPL command usage

TSPL commands are used by label and barcode printers. See the TSPL command reference for details.

Initialize

#import <tspl/tspl.h>
#import <tspl/GenericTSPL.h>

@property (nonatomic, strong) BasicTSPL *basicTspl;

- (void)setupTSPL {
    _basicTspl = [[BasicTSPL alloc] init];
    _basicTspl.BasicTSPL(_lifeCycle, TSPLPrinter_GENERIC);

    // Set callbacks
    __weak typeof(self) weakSelf = self;
    _basicTspl.read = ^(NSData *revData, NSError *error) {
        NSLog(@"Printer response: %@", revData);
    };

    _basicTspl.bleDidConnectPeripheral = ^(CBPeripheral *peripheral) {
        NSLog(@"Connected: %@", peripheral.name);
    };

    _basicTspl.bleDidDisconnectPeripheral = ^(CBPeripheral *peripheral, NSError *error) {
        NSLog(@"Disconnected: %@", error);
    };
}

Print a label

- (void)printLabel {
    _basicTspl
        // Page setup
        .page([[TPage alloc] init].width(100).height(180))
        .direction([[TDirection alloc] init].direction(UP_OUT).mirror(NO_MIRROR))
        .gap(true)
        .cut(true)
        .speed(6)
        .density(6)
        .cls()

        // Draw content
        .bar([[TBar alloc] init].x(300).y(10).width(4).height(90))
        .bar([[TBar alloc] init].x(30).y(100).width(740).height(4))

        // Print text
        .text([[TText alloc] init]
            .x(400).y(25)
            .font(TSS24)
            .xmulti(3).ymulti(3)
            .content(@"上海浦东"))

        // Print a barcode
        .barcode([[TBarcode alloc] init]
            .x(50).y(300)
            .type(@"128")
            .height(60)
            .content(@"1234567890"))

        // Execute print
        .print(1);
}

CPCL command usage

CPCL commands are used by portable label printers. See the CPCL command reference for details.

Initialize

#import <cpcl/cpcl.h>

@property (nonatomic, strong) BasicCPCL *basicCpcl;

- (void)setupCPCL {
    _basicCpcl = [[BasicCPCL alloc] init];
    _basicCpcl.BasicCPCL(_lifeCycle);
}

Print a label

_basicCpcl
    .page([[CPCLPage alloc] init].width(576).height(400))
    .text([[CPCLText alloc] init].x(50).y(50).content(@"商品标签"))
    .barcode([[CPCLBarcode alloc] init].x(50).y(150).content(@"1234567890"))
    .print();

Permission configuration

Add the following to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth permission is required to connect to the printer</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth permission is required to connect to the printer</string>

Example projects

For complete examples, see:

• iOS Demo (Objective-C)
• psdk-examples

References

• Complete ESC command reference (PDF)
• iOS Bluetooth documentation