Universal Capacitor plugin for raw data hardware transport over USB, Bluetooth (BLE), and Network (TCP) interfaces.

This plugin provides a unified API to discover, connect, and communicate with hardware peripherals across Android, iOS, and the Web. It is designed for "raw" transport, meaning you can send any byte sequence (EscPos, ZPL, custom protocols) to the connected hardware.

• Multi-Interface Support: Connect via USB, Bluetooth Low Energy (BLE), or TCP/IP (Network).
• Device Discovery: Unified scanning API for all supported interfaces.
• Raw Data Transport: Send Uint8Array, number[], or Base64 strings directly.
• Internal Queuing: Optional internal command queuing for thread-safe operations.
• Cross-Platform: Consistent API across Android, iOS, and Web.

*Web support for Network (TCP) requires a WebSocket-to-TCP proxy running on the target address (Default Port: 9100).

npm install @opuu/capacitor-hardware-transport
npx cap sync

Add the following permissions to your AndroidManifest.xml:

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

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

<!-- Network Permissions -->
<uses-permission android:name="android.permission.INTERNET" />

Add the following keys to your Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth access to connect to hardware peripherals.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app needs Bluetooth access to connect to hardware peripherals.</string>

import { HardwareTransport } from '@opuu/capacitor-hardware-transport';

// 1. Request Permissions
await HardwareTransport.requestPermissions();

// 2. Discover Devices (e.g., Bluetooth)
const { devices } = await HardwareTransport.discoverDevices({
  type: 'BLUETOOTH',
});

const device = devices[0];

// 3. Connect
await HardwareTransport.connect({
  type: 'BLUETOOTH',
  address: device.address,
});

// 4. Write Raw Data (e.g., ESC/POS)
const data = new Uint8Array([0x1b, 0x40, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x0a]);
await HardwareTransport.write({ data });

// 5. Disconnect
await HardwareTransport.disconnect();

You can automatically re-establish a connection to the last successfully connected hardware device (useful on app startup). On Android and iOS, this works natively. On Web, USB requires the device to be in the browser's previously granted list.

Note on Web Bluetooth: Auto-reconnecting to Web Bluetooth devices requires the experimental navigator.bluetooth.getDevices() API. In most browsers (including many versions of Chrome), this feature is completely unsupported or hidden behind flags (e.g. chrome://flags/#enable-web-bluetooth-new-permissions-backend). If unsupported, autoReconnect() will safely return false or throw, allowing you to gracefully prompt the user to select the device again.

// On app startup:
try {
  const reconnected = await HardwareTransport.autoReconnect({ maxRetries: 3 });
  if (reconnected) {
    console.log("Reconnected to last device!");
  } else {
    console.log("No previous device found — need to scan.");
  }
} catch (err) {
  console.error("Auto-reconnect failed (device off/out of range):", err);
}

// To inspect the last connected device:
const lastDevice = await HardwareTransport.getLastDevice();
console.log(lastDevice); // { type: 'BLUETOOTH', address: '...', ... }

// To forget the last device (prevents autoReconnect):
await HardwareTransport.clearLastDevice();

• checkPermissions()
• requestPermissions()
• discoverDevices(...)
• connect(...)
• disconnect()
• write(...)
• getLastDevice()
• clearLastDevice()
• autoReconnect(...)
• Interfaces
• Type Aliases

checkPermissions() => Promise<PermissionStatus>

Checks the status of specific hardware connection permissions natively.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions() => Promise<PermissionStatus>

Requests necessary hardware discovery/connection permissions from the user. Prompts platform-specific system dialogs.

Returns: Promise<PermissionStatus>

Since: 0.0.1

discoverDevices(options: DiscoverOptions) => Promise<{ devices: DeviceInfo[]; }>

Triggers a hardware scan for the specified connection type. Yields a list of devices available for connection.

Returns: Promise<{ devices: DeviceInfo[]; }>

Since: 0.0.1

connect(options: ConnectOptions) => Promise<void>

Attempts to establish an Input/Output stream with the specified hardware peripheral.

Since: 0.0.1

disconnect() => Promise<void>

Severs all active streams and closes hardware sockets. Retains the "Last Device" record in memory for autoReconnect().

Since: 0.0.1

write(options: WriteOptions) => Promise<void>

Enqueues a payload into the active hardware stream buffer. The underlying native plugins expect a Base64 encoded string payload. If using HardwareTransportClient, bytes are encoded automatically.

Since: 0.0.1

getLastDevice() => Promise<ConnectOptions | null>

Returns the last successfully connected device options, or null if no device has been connected. Useful for UI state restoration (e.g. displaying "Last Connected Printer").

Returns: Promise<ConnectOptions | null>

Since: 0.0.2

clearLastDevice() => Promise<void>

Removes the persisted last device, preventing future auto-reconnect calls from using it. Call this explicitly when the user requests to "Forget Device" or disconnects intentionally.

Since: 0.0.2

autoReconnect(options?: AutoReconnectOptions | undefined) => Promise<boolean>

Attempts to automatically reconnect to the last successfully connected device. Uses localStorage persistence under the hood. Fails safely if no previous device exists.

Returns: Promise<boolean>

Since: 0.0.2

A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the requested number of bytes could not be allocated an exception is raised.

Allowed ArrayBuffer types for the buffer of an ArrayBufferView and related Typed Arrays.

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ArrayBufferTypes[keyof ArrayBufferTypes]