react-native-brother-print/README.md

React Native module for printing with Brother printers via WiFi and Bluetooth

# react-native-brother-print

A React Native module for printing labels on Brother printers via WiFi and Bluetooth. Supports QL series and other Brother label printers with advanced image processing options.

## Installation

```bash
npm install react-native-brother-print
```

or using yarn:

```bash
yarn add react-native-brother-print
```

### Brother SDK Setup (Android Only)

This library requires the Brother Print SDK, which must be provided by your application due to licensing requirements.

1. Visit [Brother's Developer Program](https://developerprogram.brother-usa.com/sdk-download)
2. Register/Login and download the Brother Print SDK for Android
3. Extract the .aar file from the SDK
4. Create a `libs` directory in your app's android directory:
   ```bash
   mkdir -p android/app/libs
   ```
5. Copy the Brother SDK .aar file to this directory
6. Add the following to your app's `android/app/build.gradle`:

```gradle
android {
    // ... your existing android config
}

repositories {
    // ... your existing repositories
    flatDir {
        dirs 'libs'
    }
}

dependencies {
    // ... your existing dependencies
    implementation files('libs/BrotherPrintLibrary.aar')  // Use the actual filename of your .aar file
}
```

7. (Optional) If you placed the Brother SDK in a different location, you can configure the path in your app's root `android/build.gradle`:

```gradle
buildscript {
    ext {
        // ... your other ext properties
        brotherSdkPath = "${rootProject.projectDir}/some/path/to/libs" // Adjust this if you placed the SDK somewhere else
    }
    // ... rest of your buildscript
}
```

### iOS Setup

Run pod install:

```bash
cd ios && pod install
```

### Required Permissions

#### iOS
Add the following permissions to your `Info.plist`:

```xml
<!-- Bluetooth permissions -->
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Find paired Brother printers</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Find paired Brother printers</string>

<!-- WiFi permissions -->
<key>NSLocalNetworkUsageDescription</key>
<string>Find Brother printers installed in the local network</string>
<key>NSBonjourServices</key>
<array>
    <string>_pdl-datastream._tcp</string>
    <string>_printer._tcp</string>
    <string>_ipp._tcp</string>
</array>
```

#### Android
Add the following permissions to your `AndroidManifest.xml`:

```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_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

<!-- WiFi permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

## Usage

### Basic Print via WiFi

```javascript
import { printImageViaWifi } from "react-native-brother-print";

try {
  const ipAddress = '192.168.1.100';  // Your printer's IP address
  const modelName = 'QL-820NWB';      // Your printer's model name
  const imageUri = 'file:///path/to/your/image.png';  // Local file URI
  
  await printImageViaWifi(imageUri, ipAddress, modelName);
  console.log('Print successful');
} catch (error) {
  console.error('Print failed:', error);
}
```

### Basic Print via Bluetooth

```javascript
import { printImageViaBluetooth } from "react-native-brother-print";

try {
  const modelName = 'QL-820NWB';      // Your printer's model name
  const imageUri = 'file:///path/to/your/image.png';  // Local file URI
  
  await printImageViaBluetooth(imageUri, modelName);
  console.log('Print successful');
} catch (error) {
  console.error('Print failed:', error);
}
```

### Black-and-White Conversion Options

For badge printing or scenarios where you need pure black-and-white output, you can use the `halftone` and `thresholdingValue` options to control how color images are converted to black-and-white:

```javascript
import { printImageViaWifi } from "react-native-brother-print";

try {
  const ipAddress = '192.168.1.100';
  const modelName = 'QL-820NWB';
  const imageUri = 'file:///path/to/your/badge-image.png';
  
  // Convert to pure black-and-white with adjustable contrast
  const options = {
    halftone: 'THRESHOLD',        // Force binary cutoff
    thresholdingValue: 128        // Adjust cutoff point (0-255)
  };
  
  await printImageViaWifi(imageUri, ipAddress, modelName, options);
  console.log('Black-and-white print successful');
} catch (error) {
  console.error('Print failed:', error);
}
```

#### Print Options

| Option | Type | Values | Description |
|--------|------|---------|-------------|
| `halftone` | string | `'THRESHOLD'`, `'ERROR_DIFFUSION'`, `'PATTERN_DITHER'` | Controls how images are converted to black-and-white |
| `thresholdingValue` | number | 0-255 | Adjusts the black-white cutoff point (lower = more black, higher = more white) |

#### Halftone Methods

- **`THRESHOLD`**: Creates pure black-and-white output with a hard cutoff. Best for badge printing and text.
- **`ERROR_DIFFUSION`**: Uses dithering to create the appearance of gradients. Better for photos.
- **`PATTERN_DITHER`**: Uses pattern-based dithering. Alternative method for gradients.

#### Examples for Different Use Cases

**Badge/ID Card Printing (Pure B&W):**
```javascript
const badgeOptions = {
  halftone: 'THRESHOLD',
  thresholdingValue: 128  // Balanced cutoff
};
```

**High Contrast Badge (More Black):**
```javascript
const highContrastOptions = {
  halftone: 'THRESHOLD',
  thresholdingValue: 100  // Lower value = more pixels become black
};
```

**Photo Printing with Dithering:**
```javascript
const photoOptions = {
  halftone: 'ERROR_DIFFUSION',
  thresholdingValue: 128
};
```

## Supported Printer Models

This module supports the following Brother printer models:

- **QL Series**: QL-820NWB, QL-820NWBc, QL-1110NWB, QL-1110NWBc
- **PJ Series**: PJ-763MFi, PJ-862, PJ-863, PJ-883
- **MW Series**: MW-145MFi, MW-260MFi
- **RJ Series**: RJ-2035B, RJ-2050, RJ-2150, RJ-3035B, RJ-3050Ai, RJ-3150Ai, RJ-3230B, RJ-3250WB, RJ-4030Ai, RJ-4230B, RJ-4250WB
- **TD Series**: TD-2125NWB, TD-2135NWB, TD-4550DNWB
- **PT Series**: PT-P910BT

## Notes

- This module is a wrapper around the official Brother Print SDK
- For more information about the Brother SDK, visit [Brother's Developer Program](https://developerprogram.brother-usa.com/sdk-download)
- Based on [react-native-brother-printers](https://github.com/Avery246813579/react-native-brother-printers)

## License

MIT