react-native-esc-pos-printer

The PrinterStatusResponse interface provides a comprehensive snapshot of the printer's current state. It is composed of several status objects (e.g., connection, online, paper, errorStatus), each following a consistent structure:

{
  statusCode: number,
  status: string,
  message: string
}

Developers can use these fields to monitor hardware health, paper levels, battery life, and connectivity to ensure reliable printing operations.

When connecting on Android, keep the following in mind:

• Cleanup: Always call disconnect to terminate communication when it is no longer necessary.
• DHCP/IP: If using DHCP to assign the printer's IP, use the printer's MAC address or host name as the identifier.
• USB Connection:
  • Identifiers depend on the USB connector shape.
  • If the identifier is omitted, Android connects to the first USB device found.
  • If the Android terminal is in developer mode, you may be unable to connect via USB-A Device Charging.
• Recovery: If ERR_RECOVERY_FAILURE occurs, restart the printer.
• Locking: Devices other than printers are exclusively locked.

Install the library using your preferred package manager.

Important Version Note: If you are using a React Native version lower than 0.76.x, you must use react-native-esc-pos-printer version 4.3.3 or lower.

Required Step: You must also complete the additional required steps documented in ./docs/INSTALLATION.md for the library to function correctly.

### React Native

> [!WARNING]  
> For react-native lower than 0.76.x version, use react-native-esc-pos-printer 4.3.3 or lower

```sh
yarn add react-native-esc-pos-printer

Expo

npx expo install react-native-esc-pos-printer
npx expo prebuild

If your application targets Android 4.3.1 or lower and uses TCP for printing, you must add storage permissions to your AndroidManifest.xml.

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

For iOS, you must perform two configuration steps in your project's *.plist file (e.g., ProjectName-Info.plist) and run pod install.

1. Bluetooth Usage Description: For iOS 13 or later, add the Privacy-Bluetooth Always Usage Description key and provide a string explaining why the app uses Bluetooth (e.g., "Use this to communicate with the printer.").
2. External Accessory Protocols: To support Bluetooth or USB communication, add the Supported external accessory protocols key and set the value for Item 0 to com.epson.escpos.

Before running the application, you must start Metro, the JavaScript bundler that ships with React Native. Run this command from the root of your project.

# using npm
npm start

# OR using Yarn
yarn start

When using Expo, you must declare the required Android permissions in your app.json file under the android.permissions array.

{
  "android": {
    "permissions": [
     "android.permission.INTERNET",
     "android.permission.BLUETOOTH_SCAN",
     "android.permission.BLUETOOTH_CONNECT",
     "android.permission.BLUETOOTH",
     "android.permission.BLUETOOTH_ADMIN",
     "android.permission.ACCESS_FINE_LOCATION",
     "android.permission.ACCESS_COARSE_LOCATION",
     "android.permission.WRITE_EXTERNAL_STORAGE",
     "android.permission.READ_EXTERNAL_STORAGE"
     ]
  }
}

To launch the application on an iOS simulator or device, run the following command from the root of your project. Ensure the Metro server is already running in a separate terminal.

# using npm
npm run ios

# OR using Yarn
yarn ios

When connecting on iOS, keep the following in mind:

• Cleanup: Always call disconnect to terminate communication when it is no longer necessary.
• Bluetooth:
  • Complete pairing before calling the connect command.
  • Bluetooth communication may disconnect if the application runs in the background (depending on project settings).
  • If both Bluetooth and USB are used simultaneously, USB takes priority.
  • BLE Limitation: Do not use addImage with BLE connections, as sending/receiving large amounts of data is slow.
• TM-DT Series: MAC addresses cannot be specified for these devices.
• Recovery: If ERR_RECOVERY_FAILURE occurs, restart the printer.
• Locking: Devices other than printers are exclusively locked.