StarXpand SDK for Native Manual

Search for Printer

The procedure and the reference vary depending on the OS. Select the OS to display.

Use StarDeviceDiscoveryManager to asynchronously search for the printer.
When you start a search, events occur in the order they are found, which allows instant acquisition of the StarPrinter instance.

Memo
The StarPrinter instance provides the functions required to communicate with the printer.
There are two methods, including searching, to acquire the StarPrinter method.

Method to acquire by searching (Step 8 on this page)
Method to generate by passing interfaceType and identifier to the initializer of the StarPrinter class

By using this StarPrinter instance, you can send printing data to the printer and control POS peripheral devices.

The following description is based on the sample code. Search for the printer using the procedure below.
The sample code is available at the bottom of the page. Also, refer to the sample application in the SDK.

1 Prepare a StarDeviceDiscoveryManager type variable used for searching.

class ViewController: UIViewController, StarDeviceDiscoveryManagerDelegate {
    private var manager: StarDeviceDiscoveryManager? = nil

2 Select the target interface. Generate the InterfaceType array you would like to search for.

func startDiscovery() {
    var interfaceTypeArray : [InterfaceType] = [InterfaceType.lan, InterfaceType.bluetooth]

3 Acquire the StarDeviceDiscoveryManager instance using the array generated in Step2 as an argument.

do {
    try manager = StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)

4 Set the search time.

manager?.discoveryTime = 10000

5 Set the StarDeviceDiscoveryManagerDelegate protocol implementation (see Step8 and Step9) in the delegate property.

manager?.delegate = self

6 Call the startDiscovery method to start searching.
When the printer is found, the delegate method implemented in Step8is called, and when the search is finished, the delegate method implemented in Step9 is called.

try manager?.startDiscovery()

7 Implement the process for when an error occurs. You can identify the error based on the StarIO10Error value.
Possible errors are described in the API reference of the create method of the StarDeviceDiscoveryManagerFactory class and the startDiscovery method of the StarDeviceDiscoveryManager class.

} catch StarIO10Error.illegalDeviceState(message: let message, errorCode: let errorCode) {
    if errorCode == StarIO10ErrorCode.bluetoothUnavailable {
        // Example of error: Bluetooth capability of iOS device is disabled.
        // This may be due to the host device's Bluetooth being off. 
    }
} catch {
    print("Error: \(error)")
}

8 Implement the process for when the printer is found. Set the manager (_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) method of the StarDeviceDiscoveryManagerDelegate protocol.

func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) {        
    print("Found printer: \(printer.connectionSettings.identifier).")
}

9 Implement the process for when the search is finished. Set the managerDidFinishDiscovery (_ manager: StarDeviceDiscoveryManager) method of the StarDeviceDiscoveryManagerDelegate protocol.

func managerDidFinishDiscovery(_ manager: StarDeviceDiscoveryManager) {
    print("Discovery finished.")
}
}

Sample code


class ViewController: UIViewController, StarDeviceDiscoveryManagerDelegate {
    private var manager: StarDeviceDiscoveryManager? = nil

    func startDiscovery() {
        var interfaceTypeArray : [InterfaceType] = [InterfaceType.lan, InterfaceType.bluetooth]
        do {
            try manager = StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)
            manager?.discoveryTime = 10000
            manager?.delegate = self
            try manager?.startDiscovery()
			
        } catch StarIO10Error.illegalDeviceState(message: let message, errorCode: let errorCode) {
            if errorCode == StarIO10ErrorCode.bluetoothUnavailable {
                // Example of error: Bluetooth capability of iOS device is disabled.
                // This may be due to the host device's Bluetooth being off. 
            }
        } catch let error {
            print("Error: \(error)")
        }
    }

    func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) {        
        print("Found printer: \(printer.connectionSettings.identifier).")
    }
    
    func managerDidFinishDiscovery(_ manager: StarDeviceDiscoveryManager) {
        print("Discovery finished.")
    }
}

Monitoring the RSSI (Radio Signal Strength) of Bluetooth LE Devices

You can use the StarDeviceDiscoveryManager API to obtain the RSSI value of a Star Micronics Bluetooth LE device (*1) near the host device.
*1: For the list of Star Micronics Bluetooth LE devices that support this feature, refer to the StarPrinterInformationBluetoothLE.rssi API reference.

Use Case

Using the RSSI value of a Bluetooth LE device as a reference for determining whether the host device is near the target Bluetooth LE device, as well as any peripheral connected to it, such as a cash drawer.

Related APIs

Sample Code


func startDiscovery() {
    let interfaceTypeArray: [InterfaceType] = [InterfaceType.bluetoothLE]
    do {
        manager = try StarDeviceDiscoveryManagerFactory.create(interfaceTypes: interfaceTypeArray)
        manager?.isEnabledFindSameDevice = true // Enables continuous detection of the same device.
        manager?.discoveryTime = 10000
        manager?.delegate = self
        try manager?.startDiscovery()
    } catch let error {
        print("Error: (error)")
    }
}

func manager(_ manager: StarDeviceDiscoveryManager, didFind printer: StarPrinter) { // The detected Bluetooth LE device is passed to the property.
    if printer.connectionSettings.interfaceType == InterfaceType.bluetoothLE,
       printer.connectionSettings.identifier == "YourTargetIdentifier" {
        if let rssi = printer.information?.detail.bluetoothLE.rssi {
            print("RSSI: (rssi)") // You can obtain the RSSI value as shown here.
        }
    }
}

Notes

RSSI values are generally higher when devices are closer together. However, a value can vary depending on factors such as the models of the host device and the Bluetooth LE device, the radio characteristics of each device, the orientation of the Bluetooth LE device, and the surrounding environment (for example, radio interference or obstructions).
Before deploying an application that uses this API, test it thoroughly in the actual environment where it will run.
When using RSSI values to determine whether the host device is near the cash drawer, we do not recommend opening the cash drawer based solely on that determination without any user action, for security reasons.
We recommend designing your implementation to handle cases where the target Bluetooth LE device cannot be detected, for example due to radio interference or obstructions.

Use StarDeviceDiscoveryManager to asynchronously search for the printer.
When you start a search, events occur in the order where they are found, and you can acquire the StarPrinter instance instantly.

Memo
The StarPrinter instance provides the functions required to communicate with the printer.
There are two methods, including searching, to acquire the StarPrinter method.

Method to acquire by searching (Step 5 on this page)
Method to generate by passing interfaceType and identifier to the constructor of the StarPrinter class

By using this StarPrinter instance, you can send printing data to the printer and control POS peripheral devices.

1 Prepare a StarDeviceDiscoveryManager type variable used for searching.

private var _manager: StarDeviceDiscoveryManager? = null

2 Select the target interface. Generate the InterfaceType list you would like to search for.

private fun startDiscovery() {
    try {
        val interfaceTypes = listOf(InterfaceType.Lan, InterfaceType.Bluetooth)

3 Acquire the StarDeviceDiscoveryManager instance using the list generated in Step2 as an argument.

_manager = StarDeviceDiscoveryManagerFactory.create(
    interfaceTypes,
    applicationContext
)

4 Set the search time.

_manager?.discoveryTime = 10000

5 Implement the processes for when the printer is found and when the search is finished.
Set the StarDeviceDiscoveryManager.Callback interface implementation in the callback property. Implement the process for when the printer is found in the onPrinterFound method and the process for when the search is finished in the onDiscoveryFinished method.

_manager?.callback = object : StarDeviceDiscoveryManager.Callback {
    override fun onPrinterFound(printer: StarPrinter) {
        Log.d("Discovery", "Found printer: ${printer.connectionSettings.identifier}.")
    }

    override fun onDiscoveryFinished() {
        Log.d("Discovery", "Discovery finished.")
    }
}

6 Call the startDiscovery method to start searching.
When the printer is found, the onPrinterFound method implemented in Step5 is called. When the search is finished, the onDiscoveryFinished method is called.

_manager?.startDiscovery()

7 Implement the process for when an error occurs. You can identify the error cause based on the error type.
Possible errors are described in the API reference of the create method of the StarDeviceDiscoveryManagerFactory class and the startDiscovery method of the StarDeviceDiscoveryManager class.

} catch (e: StarIO10IllegalHostDeviceStateException) {
    if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
        // Example of error: Bluetooth capability of Android device is disabled.
        // This may be due to the Android device's Bluetooth being off. 
    }
} catch (e: Exception) {
    Log.d("Discovery", "Error: ${e}")
}
}

Sample code


private var _manager: StarDeviceDiscoveryManager? = null
private fun startDiscovery() {
    try {
        this._manager?.stopDiscovery()
        _manager = StarDeviceDiscoveryManagerFactory.create(
            interfaceTypes,
            applicationContext
        )

        _manager?.discoveryTime = 10000
        _manager?.callback = object : StarDeviceDiscoveryManager.Callback {
            override fun onPrinterFound(printer: StarPrinter) {
                Log.d("Discovery", "Found printer: ${printer.connectionSettings.identifier}.")
            }

            override fun onDiscoveryFinished() {
                Log.d("Discovery", "Discovery finished.")
            }
        }
        _manager?.startDiscovery()
		
    } catch (e: StarIO10IllegalHostDeviceStateException) {
        if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
            // Example of error: Bluetooth capability of Android device is disabled.
            // This may be due to the Android device's Bluetooth being off. 
        }
    } catch (e: Exception) {
        Log.d("Discovery", "Error: ${e}")
    }
}

Monitoring the RSSI (Radio Signal Strength) of Bluetooth LE Devices

Use Case

Using the RSSI value of a Bluetooth LE device as a reference for determining whether the host device is near the target Bluetooth LE device, as well as any peripheral connected to it, such as a cash drawer.

Related APIs

Sample Code


private var _manager: StarDeviceDiscoveryManager? = null
    private fun startDiscovery() {
        try {
            this._manager?.stopDiscovery()
            _manager = StarDeviceDiscoveryManagerFactory.create(
                listOf<InterfaceType>(InterfaceType.BluetoothLE),
                applicationContext
            )

            _manager?.isEnabledFindSameDevice = true // Enables continuous detection of the same device.
            _manager?.discoveryTime = 10000
            _manager?.callback = object : StarDeviceDiscoveryManager.Callback {
                override fun onPrinterFound(printer: StarPrinter) {
                    // The detected Bluetooth LE device is passed to the property.
                    if (printer.connectionSettings.interfaceType == InterfaceType.BluetoothLE &&
                    printer.connectionSettings.identifier == "YourTargetIdentifier") {
                        val rssi = printer.information?.detail?.bluetoothLE?.rssi ?: return
                        Log.d("Discovery", "RSSI: $rssi") // You can obtain the RSSI value as shown here.
                    }
                }

                override fun onDiscoveryFinished() {
                    Log.d("Discovery", "Discovery finished.")
                }
            }
            _manager?.startDiscovery()

        } catch (e: StarIO10IllegalHostDeviceStateException) {
            if (e.errorCode == StarIO10ErrorCode.BluetoothUnavailable) {
                // Example of error: Bluetooth capability of Android device is disabled.
                // This may be due to the Android device's Bluetooth being off.
            }
        } catch (e: Exception) {
            Log.d("Discovery", "Error: ${e}")
        }
    }

Notes

RSSI values are generally higher when devices are closer together. However, a value can vary depending on factors such as the models of the host device and the Bluetooth LE device, the radio characteristics of each device, the orientation of the Bluetooth LE device, and the surrounding environment (for example, radio interference or obstructions).
Before deploying an application that uses this API, test it thoroughly in the actual environment where it will run.
When using RSSI values to determine whether the host device is near the cash drawer, we do not recommend opening the cash drawer based solely on that determination without any user action, for security reasons.
We recommend designing your implementation to handle cases where the target Bluetooth LE device cannot be detected, for example due to radio interference or obstructions.