@munchi_oy/react-native-epson-printer

Epson printer SDK bridge for React Native (iOS + Android).

Installation (version-pinned recommended)

Use an explicit version instead of latest to keep production builds predictable.

npm install @munchi_oy/[email protected]
# or
pnpm add @munchi_oy/[email protected]
# or
yarn add @munchi_oy/[email protected]

Recommended policy:

• Pin to an exact version in production.
• Upgrade intentionally after validating printers on staging.

Overview

This package provides:

• Epson discovery (discoverPrinters)
• OS-known device lookup (getKnownDevices)
• Epson connection lifecycle (connect, disconnect, connection events)
• Serialized print queue with retry + recovery behavior
• Receipt printing via generic PrintJob commands
• Embedded payload printing (printEmbedded)
• Cash drawer pulse (openDrawer)

This package does not include Star or Sunmi drivers.

Runtime Contract

For both iOS and Android, the SDK aims to provide this behavior:

• Native printer work may take time, especially for Bluetooth connection, status checks, and image printing.
• Slow printer operations are acceptable; visible app hangs are not.
• Printer work must not block the app UI/main thread while running.
• Errors from native printer operations must reject back to JS and must not be swallowed.
• Image and logo printing may be more expensive than text-only receipts, but must still remain asynchronous from the app's point of view.

Observed Performance Expectations

These are real-device expectations, not strict guarantees:

• iOS: around 3s end-to-end can be acceptable if the app UI remains responsive.
• Android: the first print may take around 5-6s, with later warm prints often dropping to around 2-3s.
• Actual timing depends on connection state, Bluetooth behavior, printer readiness, and whether the receipt includes images.
• Responsiveness and correct JS error propagation matter more than raw duration.

Behavior Support (implemented)

| Behavior | Status | Details | | :--- | :--- | :--- | | Session-isolated instances | Implemented | Each getPrinter(...) instance owns a native sessionId; events are routed by session. | | Target conflict protection | Implemented | Concurrent active usage of the same target returns TARGET_IN_USE. | | Serialized job queue | Implemented | connect, print, and disconnect are queued to avoid race conditions per instance. | | Hardware-error pause/resume | Implemented | Hardware failures pause queue; queue resumes when recovery is detected via status events and polling. | | Retry for transient busy/timeout states | Implemented | Native operations retry for retryable states (BUSY, IN_USE, timeout-family errors). | | Print receive timeout guard | Implemented | Native print call fails with PRINT_TIMEOUT if printer callback does not return within 30s. | | iOS stale-session recovery | Implemented | One-shot session recovery + reconnect + retry for stale/busy/offline connection scenarios. | | Non-blocking native printer execution | Implemented | Native connect / print / status work is executed off the app UI thread on both iOS and Android. | | Post-print auto-disconnect | Implemented | JS driver schedules disconnect after 5s idle after print completion. | | Android warm reconnect cache | Implemented | Native Android keeps a short-lived connection cache (up to 120s) for faster reconnect. | | Discovery cleanup/filtering | Implemented | Duplicate targets are deduped and Epson sub-devices such as [local_display] are filtered out. |

Multi-instance (one tablet -> many printers)

Yes, this is supported.

• Create one printer instance per physical target.
• Run them in parallel if needed.
• Do not connect two active instances to the same target at the same time (TARGET_IN_USE).

import { EpsonModel, getPrinter } from '@munchi_oy/react-native-epson-printer';

const kitchenPrinter = getPrinter({
  target: 'BT:00:01:90:7B:5A:11',
  model: EpsonModel.TM_M30III,
});

const receiptPrinter = getPrinter({
  target: 'TCP:192.168.1.50',
  model: EpsonModel.TM_M30III,
});

await Promise.all([
  kitchenPrinter.connect(),
  receiptPrinter.connect(),
]);

await Promise.all([
  kitchenPrinter.print({ commands: [{ type: 'text', text: 'Kitchen ticket\n' }, { type: 'cut' }] }),
  receiptPrinter.print({ commands: [{ type: 'text', text: 'Customer receipt\n' }, { type: 'cut' }] }),
]);

await Promise.all([
  kitchenPrinter.disconnect(),
  receiptPrinter.disconnect(),
]);

iOS Setup

1. Install the package.
2. Run CocoaPods install:

cd ios && pod install

3. Configure Info.plist permissions based on your connection method (Bluetooth/TCP).

Android Setup

1. Install the package and sync Gradle.
2. Request runtime permissions before discovery/connection:

• Android 12+ (API 31+): BLUETOOTH_SCAN, BLUETOOTH_CONNECT
• Android 11 and below: ACCESS_FINE_LOCATION (Bluetooth discovery)

3. Rebuild the app.

Quick Start

import { EpsonModel, getPrinter } from '@munchi_oy/react-native-epson-printer';

const printer = getPrinter({
  target: 'BT:00:01:90:7B:5A:11',
  model: EpsonModel.TM_M30III,
});

await printer.connect();
await printer.print({
  commands: [
    { type: 'text', text: 'Hello\n', align: 'center', bold: true },
    { type: 'feed', lines: 2 },
    { type: 'cut' },
  ],
});
await printer.disconnect();

Config

getPrinter(config) requires EpsonPrinterConfig.

| Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | model | EpsonModel | Yes | Epson printer series passed to native init | | target | string | No | Default target used by connect() when no target is passed | | lang | Epos2Lang | No | Language enum for native printer object | | logger | PrinterLogger | No | Per-instance logger (error, optional info) |

Language mode and locale mapping

Epos2Lang is an Epson printer language mode, not a full ISO locale list.
Available values are:

• EN
• JA
• ZH_CN
• ZH_TW
• KO
• TH
• VI
• MULTI

Use resolveEpos2Lang(...) to map app locale strings to the Epson enum:

import { EpsonModel, getPrinter, resolveEpos2Lang } from '@munchi_oy/react-native-epson-printer';

const locale = 'fi-FI';
const lang = resolveEpos2Lang(locale, { model: EpsonModel.TM_M30III });

const printer = getPrinter({
  target: 'BT:00:01:90:7B:5A:11',
  model: EpsonModel.TM_M30III,
  lang,
});

Expected mapping behavior:

• fi-FI -> Epos2Lang.EN
• vi-VN -> Epos2Lang.VI
• ar-SA -> Epos2Lang.MULTI
• unknown locale -> Epos2Lang.EN (or custom fallbackLang)

Model note:

• Some legacy models have reduced multibyte/script coverage.
• If model is provided, resolver applies conservative fallback to fallbackLang for TH/VI/MULTI on known-limited models.
• For mixed-language receipts, use per-command textLang where needed.

Discovery

Use discovery as a standalone API:

import { discoverPrinters } from '@munchi_oy/react-native-epson-printer';

const printers = await discoverPrinters({
  timeout: 5000,
  connectionType: 'bluetooth',
});

Supported connectionType filters:

• bluetooth -> BT:
• tcp -> TCP:, TCPS:
• usb -> USB:

Known devices

Use getKnownDevices() to read devices already visible to the OS:

import { getKnownDevices } from '@munchi_oy/react-native-epson-printer';

const devices = await getKnownDevices();

Returned devices are filtered to Epson-compatible names and include:

• id
• name
• source
• optional target

The name value comes directly from the OS/native layer. The SDK does not rewrite or derive it.

Platform behavior:

• Android returns bonded Bluetooth devices and includes target as BT:<mac-address>.
• iOS returns accessories visible through ExternalAccessory. These entries may not include an Epson target, so use them for OS-level visibility, not as a full replacement for discoverPrinters().

If you need to detect Epson printers from the OS-provided name, use:

import { isEpsonBluetoothDeviceName, resolveModelFromBluetoothName } from '@munchi_oy/react-native-epson-printer';

const isEpson = isEpsonBluetoothDeviceName(device.name);
const model = resolveModelFromBluetoothName(device.name);

Merged device lookup

Use findDevices() when you want both OS-known devices and Epson discovery results in one list:

import { findDevices } from '@munchi_oy/react-native-epson-printer';

const devices = await findDevices({
  timeout: 5000,
});

Behavior:

• Keeps the existing discoverPrinters() logic unchanged and calls it as-is.
• Merges entries by target when both known-device lookup and discovery refer to the same printer.
• Still returns discovery-only devices such as TCP/IP printers that do not exist at the OS-known layer.
• Returns partial results if one lookup fails and the other succeeds.

Connection Lifecycle

• connect(target?, timeout?)
• disconnect()
• onConnectionChange(callback)
• onStatusChange(callback)

Example:

await printer.connect(); // uses config.target
await printer.connect('TCP:192.168.1.50', 7000); // override target

const off = printer.onConnectionChange((status) => {
  console.log('connection', status);
});

Printing

Generic PrintJob

await printer.print({
  commands: [
    { type: 'align', align: 'left' },
    { type: 'text', text: 'Order #123\n' },
    { type: 'separator' },
    { type: 'cut' },
  ],
});

Embedded payload

await printer.printEmbedded({
  id: 'Ord-123',
  ts: '12:00 PM',
  lines: [{ t: '1x Burger' }],
});

Image printing expectations

• Image printing is supported.
• Image printing can take longer than text-only receipts because the image may need decode, resize, rasterization, and transport work.
• This extra work should not block the app UI.
• If image printing fails, the error should still reject back to JS like any other print failure.

Cash drawer

await printer.openDrawer();

Logging

You can set a global logger:

import { setGlobalLogger } from '@munchi_oy/react-native-epson-printer';

setGlobalLogger({
  info: (message) => console.log(message),
  error: (message, error) => console.error(message, error),
});

React Helpers

The package exports:

• PrinterProvider
• usePrinter()
• usePrinterStatus({ enabled?: boolean })

usePrinterStatus handles connect/disconnect behavior based on enabled, subscribes to connection + hardware status events, and exposes error state.

Supported Epson Models

The following printer series are natively supported by the underlying Epson ePOS SDK and can be passed to the model configuration using the EpsonModel enum:

• TM-M Series: TM-m10, TM-m30, TM-m30II, TM-m30III, TM-m50, TM-m50II, TM-m55
• TM-P Series: TM-P20, TM-P20II, TM-P60, TM-P60II, TM-P80, TM-P80II
• TM-T Series: TM-T20, TM-T60, TM-T70, TM-T81, TM-T82, TM-T83, TM-T83III, TM-T88, TM-T88VII, TM-T90, TM-T90KP, TM-T100
• TM-U Series: TM-U220, TM-U220II, TM-U330
• TM-L Series: TM-L90, TM-L90LFC, TM-L100
• TM-H Series: TM-H6000
• Others: TS-100, SB-H50, SB-M30

International character-set coverage (Epson reference only, not SDK API)

This matrix is Epson reference information mapped to this SDK model enum list.

Important:

• This SDK currently does not expose an API to select Epson international charset IDs (0..17, 66..75, 82).
• Current language control in SDK is only Epos2Lang (0..7: EN..MULTI).
• Therefore, SDK API availability for charset-ID control is Not available for all models below.

| SDK enum | Epson family (from initWithPrinterSeries) | Intl set status (Epson ref) | SDK API availability | | :--- | :--- | :--- | :--- | | TM_M10 | TM-m10 | 0-17 | Not available | | TM_M30 | TM-m30 | 0-17 | Not available | | TM_P20 | TM-P20 | 0-17 (others), 0-17,66-75,82 (South Asia) | Not available | | TM_P60 | TM-P60 | 0-15 | Not available | | TM_P60II | TM-P60II | 0-17 | Not available | | TM_P80 | TM-P80 | 0-17 | Not available | | TM_T20 | TM-T20/T20II/T20III/T20IV/T20X family | 0-17 | Not available | | TM_T60 | TM-T60 | Not listed in Epson table (check exact TRG) | Not available | | TM_T70 | TM-T70/T70-i/T70II/T70II-DT/DT2 | Mixed: T70=0-15 (or 0,16 South Asia), T70II/DT2=0-17 | Not available | | TM_T81 | TM-T81II/T81III | T81III=0-17, T81II not explicit | Not available | | TM_T82 | TM-T82/T82II/T82III/T82IV/T82X family | 0-17 | Not available | | TM_T83 | TM-T83II-i | Not explicit in Epson table | Not available | | TM_T83III | TM-T83III/T83IV | 0-17 | Not available | | TM_T88 | TM-T88IV/V/VI family (+ i/DT) | Mixed: T88IV=0-15 (or 0,16 South Asia), T88V/VI=0-17 | Not available | | TM_T88VII | TM-T88VII | 0-17 | Not available | | TM_T90 | TM-T90 | 0-13 | Not available | | TM_T90KP | TM-T90KP | Not explicit (likely T90-family limits) | Not available | | TM_U220 | TM-U220/U220-i | 0-15 | Not available | | TM_U220II | TM-U220II/U220IIB-i | 0-16 | Not available | | TM_U330 | TM-U330 | 0-13 | Not available | | TM_L90 | TM-L90 | Mixed: some SKUs 0-17, others 0-13 | Not available | | TM_L90LFC | TM-L90 liner-free | Not explicit in Epson table | Not available | | TM_L100 | TM-L100 | 0-17 | Not available | | TM_H6000 | TM-H6000IV/V/IV-DT | 0-13 | Not available | | TM_T100 | TM-T100 | 0-17 | Not available | | TM_M30II | TM-m30II family | 0-17 | Not available | | TM_M50 | TM-m50 | 0-17 | Not available | | TM_P20II | TM-P20II | 0-17,66-75,82 | Not available | | TM_P80II | TM-P80II | 0-17,66-75,82 | Not available | | TM_M30III | TM-m30III family | 0-17 | Not available | | TM_M50II | TM-m50II family | 0-17 | Not available | | TM_M55 | TM-m55 | Not explicit in Epson pages yet | Not available |

Vendor and Platform Support

| Vendor | Support | | :--- | :--- | | Epson | Yes | | Star | No | | Sunmi | No |

| Platform | Status | | :--- | :--- | | iOS | Supported | | Android | Supported |

Known Limitations

• Epson-only scope.
• model must be known at getPrinter(...) creation time.
• Model/language are immutable per instance; create a new instance to change them.
• Underlying behavior is constrained by Epson ePOS2 SDK.

Troubleshooting

1. Native module not found

• iOS: reinstall pods and rebuild.
• Android: clean/sync Gradle and rebuild.

2. Printer target is required

• Pass target in config or connect(target).

3. TARGET_IN_USE

• Another active session is using the same target. Disconnect old owner first.

4. Busy/timeouts during peak usage

• Keep one active owner per target and avoid overlapping connect/print flows from different instances.

Migration Notes (already shipped)

If upgrading from older adapter-based versions:

1. Epson-only scope

• Removed Star/Sunmi and PrinterType factory behavior.

2. Config updates

• model is required in getPrinter({ ... }).

3. Connect signature

• Before: connect(target, timeout, model, lang)
• Now: connect(target?, timeout?) (model/lang come from instance config).