zebra_handheld_scanner #

A Flutter plugin for easily integrating and communicating with Zebra Bluetooth BLE/SPP handheld barcode scanners natively on iOS and Android.

This plugin abstracts away the complex underlying native Bluetooth connection logic and exposes a clean, easy-to-use Dart API to discover, connect, listen to barcode scans, and send configuration commands to Zebra scanners.

Features #

• Auto-Connect via BLE: Automatically scan and pair with nearby Zebra BLE scanners using a simple QR code prompt mechanism.
• Connection State Listening: Keep track of the active connection state of your scanner directly in Flutter.
• Real-time Barcode Scanning: Listen to incoming barcode data instantly as soon as a barcode is scanned.
• Read Device Information: Fetch connected scanner details such as its Bluetooth Name, Firmware Version, and Battery Level percentage.
• Hardware Feedback Control: Programmatically trigger the scanner's Buzzer, Vibrator, and LED indicator lights with predefined enums.
• Configuration Commands: Send deep setting codes (SpecCode) or raw laser commands over Bluetooth directly from your app.

Getting Started #

1. Installation #

Add zebra_handheld_scanner to your pubspec.yaml dependencies:

dependencies:
  zebra_handheld_scanner: ^0.0.1

2. Permissions #

The plugin automatically requests the necessary runtime permissions on both Android and iOS when you call requestPermissions(). Ensure you have the appropriate declarations in your platform manifest files.

Android (android/app/src/main/AndroidManifest.xml)

The necessary Bluetooth and Location permissions are bundled in the plugin's manifest. You do not need to add anything extra unless your specific use-case requires it.

iOS (ios/Runner/Info.plist)

You must include the following Bluetooth usage descriptions in your app's Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs access to Bluetooth to connect to and communicate with the Zebra Scanner.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app needs access to Bluetooth to connect to and communicate with the Zebra Scanner.</string>
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

Usage Example #

Initialization & Permissions #

First, initialize the plugin and request the necessary Bluetooth permissions from the user. Set up your connection listeners so your UI updates when the scanner connects/disconnects or scans a barcode.

import 'package:zebra_handheld_scanner/zebra_handheld_scanner.dart';

final _zebraScannerPlugin = ZebraHandheldScanner();

@override
void initState() {
  super.initState();
  
  // 1. Request Bluetooth/Location permissions
  _zebraScannerPlugin.requestPermissions();
  
  // 2. Setup listeners for the scanner
  _zebraScannerPlugin.setListeners(
    onScannerConnected: (bool isConnected) {
      print(isConnected ? "Scanner Connected!" : "Scanner Disconnected");
    },
    onBarcodeScanned: (String barcode) {
      print("Scanned Barcode: $barcode");
    },
    onScannerAutoConnectStep: (int step) {
      print("Auto-connect step: $step");
    },
  );
}

Connecting to a Scanner #

You can either connect to a previously bonded scanner (Android), or initiate an Auto-Connect sequence.

Auto Connect (BLE):

// Initiates scanning for nearby BLE scanners.
// It returns instructions or a QR Code text string that needs to be scanned by the physical Zebra scanner to pair.
String pairingQrText = await _zebraScannerPlugin.autoConnectBle();

Reading Device Info #

Once connected, you can fetch metadata from the Zebra scanner:

String? name = await _zebraScannerPlugin.getDeviceName();
String? version = await _zebraScannerPlugin.getVersion();
int? battery = await _zebraScannerPlugin.getBatteryLevel(); // Returns 0-100 percentage

Hardware Feedback & Commands #

You can control the physical feedback mechanisms of the scanner directly using the provided Dart Enums.

Buzzer:

await _zebraScannerPlugin.setBuzzer(BuzzerType.normalScan); // Emits a low-pitched beep
await _zebraScannerPlugin.setBuzzer(BuzzerType.errorAlert); // Emits three rapid low-pitched beeps

Vibrator:

await _zebraScannerPlugin.setVibrator(VibratorType.short);

LED:

// Flash the Red and Green LED twice, holding for 500ms each time.
await _zebraScannerPlugin.setLed(LedColor.redAndGreen, durationMs: 500, blinkCount: 2);

Custom Setting Codes:

// Send a configuration setting code (e.g. Volume to High)
await _zebraScannerPlugin.sendSpecCode("HighVolume");

Disconnecting #

When you are done communicating with the device:

await _zebraScannerPlugin.disconnect();