nebula_flutter_plugin

Nebula Flutter Plugin is a wrapper of the Nebula Android SDK for Flutter, allowing you to interface with POS terminals seamlessly via TCP, Bluetooth, USB, or Cloud (MQTT).

This plugin provides a comprehensive Dart API to connect to the terminal and initiate transactions like Sale, Refund, Void, and Settle.

Getting Started

Add nebula_flutter_plugin directly from pub.dev. Add it to your pubspec.yaml file:

dependencies:
  nebula_flutter_plugin: ^1.0.0

Then run:

flutter pub get

This will fetch the latest stable version of the plugin and allow you to start integrating with PAX POS terminals immediately, without needing a local SDK dependency.

Android Setup Requirements

The Nebula Flutter Plugin significantly simplifies the Android integration process for your application:

1. Permissions: The SDK's AndroidManifest.xml already declares all necessary permissions (including Bluetooth and Network access). Client applications do NOT need to add these permissions manually; they will be automatically merged into your app's Manifest during the build process.
2. Proguard / Obfuscation: The SDK already includes and bundles its own Proguard rules internally. Client applications do NOT need to configure obfuscation rules manually for this plugin to be protected or functional.

Integration

Initialization & Setup Callbacks

Before connecting to a terminal or performing transactions, initialize the NebulaFlutterPlugin and set up the necessary callbacks.

import 'package:nebula_flutter_plugin/nebula_flutter_plugin.dart';

// 1. Initialize the plugin instance
final NebulaFlutterPlugin _plugin = NebulaFlutterPlugin();

// 2. Listen to connection status changes
_plugin.setOnConnectionStatusCallback((bool isConnected) {
  print('Connection status: ${isConnected ? "Connected" : "Disconnected"}');
});

// 3. Listen to messages received from the terminal
_plugin.setOnMessageReceivedCallback((String? packageName, String? message) {
  print('Message from $packageName: $message');
});

// 4. Handle application selection (Required for multi-app setups)
_plugin.setOnChooseAppCallback((List<Map<String, dynamic>> apps) async {
  // Show a UI dialog for the user to select an app, 
  // or return the default application's package name automatically.
  // Example: 
  // return apps.first['packageName'];
  return null; 
});

Establishing a Connection

You can connect to a POS terminal using one of the following methods, depending on your hardware environment:

1. TCP (WiFi)

// Connect using terminal's IP address
await _plugin.connectTcp('192.168.8.101', port: 30999, timeout: 20000);

2. Bluetooth

// Connect using terminal's Bluetooth MAC address
await _plugin.connectBluetooth('A0:44:B7:DC:3E:0D', timeout: 20000);

3. USB

await _plugin.connectUsb(timeout: 20000);

4. Cloud (MQTT)

First, bind the device using your Cloud platform parameters:

final config = CloudConfig(
  baseUrl: 'https://uat.posplatform.com/api/',
  bindCode: '62719',
  eid: '495572',
  appId: '600052',
);
await _plugin.bindDeviceByCloud(config, timeout: 20000);

Once bound successfully, establish the cloud connection:

await _plugin.connectCloud(timeout: 20000);

Performing Transactions

Once connected, you can start financial transactions using strictly typed request classes (e.g., SaleRequest, RefundRequest).

Example: Sale Transaction

try {
  // Build a Sale request
  final request = SaleRequest(
    amount: 100, // e.g. $1.00 depending on currency scaling configuration
    tipAmount: 0,
    currencyCode: 'USD',
  );
  
  // Starting the transaction will trigger your device flow.
  // Wait for the result:
  final TransResponse response = await _plugin.startSaleTransaction(request);
  print('Sale Result: ${response.toJson()}');
  
} catch (e) {
  print('Transaction failed: $e');
}

Other available transaction APIs include:

• startRefundTransaction(RefundRequest request)
• startVoidTransaction(VoidRequest request)
• startSettleTransaction(SettleRequest request)
• startTransaction(String category, Map<String, dynamic> request) (Use this for unmapped, raw transactions)

Messaging

Send unstructured messages to specific packages installed on the connected device:

await _plugin.sendMessage('com.example.pkg', 'Hello Custom Terminal App!');

Disconnecting

Disconnect safely when destroying the app or halting service:

await _plugin.disconnect();

Example Application

An extensive example demonstrating how to correctly initialize the plugin, manage connection states across different protocols, handle transaction callbacks, and render a basic UI is available in the example directory.

To run the example:

1. cd example
2. flutter run