starxpand_sdk_wrapper

A Flutter plugin that provides a simple interface to Star Micronics receipt printers using the official StarXpand SDK for Android and iOS. This plugin supports modern development workflows, including Swift Package Manager (SPM) on iOS.

Features

Device discovery: automatically discover Star printers on your network or connected via USB/Bluetooth.
Image and PDF printing: convert and print PDFs or native layout byte streams directly to thermal receipt sheets.
Cash drawer control: open cash drawers connected via peripheral drive ports.
Status monitoring: receive real-time peripheral state changes (paper levels, lid openings, power drops).
Multiple interfaces: unified support for LAN, USB, and Bluetooth architectures.

Supported Printers

This plugin supports Star Micronics printers compatible with the StarXpand SDK. It has been tested explicitly on models like TSP100III and TSP143IV, but any model using the underlying StarIO10 framework should work.

Platform Requirements

iOS 14.0 or higher
Android API 26 (Android 8.0) or higher

Installation

Add this to your project's pubspec.yaml file:

dependencies:
  starxpand_sdk_wrapper: ^1.0.2

Then run:

flutter pub get

iOS Setup

Add these keys to ios/Runner/Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth to connect to Star printers</string>

<key>NSLocalNetworkUsageDescription</key>
<string>Use Local Network for communication with and discovery of Star printers.</string>

<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>jp.star-m.starpro</string>
</array>

Android Setup

Add these permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

<uses-feature android:name="android.hardware.usb.host" />

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Usage

Import the package:

import 'package:starxpand_sdk_wrapper/starxpand_sdk_wrapper.dart';

Discover Printers

Assign callback handlers to the singleton engine instance before triggering a scan:

final xp = StarXpand.instance;

xp.deviceFound = (StarDevice device) {
  print('Found printer: ${device.identifier}');
  print('Model: ${device.model ?? "Unknown"}');
  print('Interface type: ${device.interface.name}');
};

xp.discoveryDone = () {
  print('Discovery time window completed.');
};

await xp.startDiscovery(
  interfaces: {StarInterfaceType.usb, StarInterfaceType.bluetooth},
  timeout: const Duration(seconds: 10),
);

// Stop scanning manually if needed.
await xp.stopDiscovery();

Connect And Monitor Hardware State

Configure status listeners to receive hardware updates in real time:

final xp = StarXpand.instance;

xp.connectionComplete = (bool success) {
  print('Connection attempt response: ${success ? "SUCCESS" : "FAILURE"}');
};

xp.statusChanged = (StarStatus status) {
  if (status.coverOpen) {
    print('Warning: The printer cover lid was opened!');
  }
  if (status.paperEmpty) {
    print('Warning: Out of paper roll matching assets.');
  }
  if (!status.online) {
    print('Hardware is currently offline or unpowered.');
  }
};

await xp.connect(myDiscoveredDevice, monitor: true);

Print A PDF Asset

bool printSuccess = await StarXpand.instance.printPdf(
  myPdfBytes,
  width: 576, // 576 dots = 80mm standard paper width at 203 DPI
);

if (printSuccess) {
  print('Print command fully delivered and executed.');
}

Disconnect

await StarXpand.instance.disconnect();

API Reference

Methods

Method	Description	Returns
`startDiscovery({interfaces, timeout})`	Sweeps local networks/buses for hardware.	`Future<void>`
`stopDiscovery()`	Halts active background scanning routines.	`Future<void>`
`connect(device, {monitor})`	Links to a printer target and optionally mounts listeners.	`Future<void>`
`disconnect()`	Safely severs peripheral socket lines.	`Future<void>`
`printPdf(pdfBytes, {width})`	Rasters page definitions to binary thermal matrices.	`Future<bool>`
`openCashDrawer()`	Fires a peripheral drive pulse on Channel 1.	`Future<bool>`
`getStatus()`	Retrieves an immediate peripheral status snapshot.	`Future<StarStatus>`

Callback Properties

Callback Property	Signature	Emitted Context
`deviceFound`	`void Function(StarDevice)`	Triggers immediately when a matching model answers.
`discoveryDone`	`void Function()`	Triggers when the scanning duration window elapses.
`statusChanged`	`void Function(StarStatus)`	Triggers when an operational or telemetry parameter shifts.
`connectionComplete`	`void Function(bool)`	Triggers when an open socket attempt succeeds or drops.