react-native-bluetooth-datecs-printer/README.md

Module to printer in a Datecs bluetooth Printer

clear# react-native-bluetooth-datecs-printer

Module to print on Datecs bluetooth printers.

**✨ Now compatible with Expo SDK 54 and Android SDK 36!**

## 📚 Documentation

- **[HOW_TO_TEST.md](./HOW_TO_TEST.md)** - 🧪 Como testar a biblioteca em outra aplicação
- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - ⚠️ Soluções para problemas comuns
- **[EXPO_SETUP.md](./EXPO_SETUP.md)** - Complete Expo SDK 54 setup guide
- **[QUICK_START.md](./QUICK_START.md)** - Quick start in 5 minutes
- **[TESTING_GUIDE.md](./TESTING_GUIDE.md)** - Comprehensive testing guide
- **[examples/ExpoExample.tsx](./examples/ExpoExample.tsx)** - Complete working example

## Requirements

- React Native 0.76+
- React 18.3+
- Android SDK 36
- Android 8.0+ (API 26+)
- Expo SDK 54 (if using Expo)

## Installation

```bash
npm install react-native-bluetooth-datecs-printer --save
```

or

```bash
yarn add react-native-bluetooth-datecs-printer
```

## Setup

### For Expo Projects (SDK 54)

**📖 [Complete Expo Setup Guide](./EXPO_SETUP.md)**

1. Install `expo-build-properties`:
```bash
npx expo install expo-build-properties
```

2. Configure `app.json`:
```json
{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 36,
            "targetSdkVersion": 36,
            "minSdkVersion": 26,
            "buildToolsVersion": "35.0.0"
          }
        }
      ]
    ],
    "android": {
      "permissions": [
        "BLUETOOTH",
        "BLUETOOTH_ADMIN",
        "BLUETOOTH_CONNECT",
        "BLUETOOTH_SCAN",
        "ACCESS_FINE_LOCATION",
        "ACCESS_COARSE_LOCATION"
      ]
    }
  }
}
```

3. Run prebuild:
```bash
npx expo prebuild --clean
```

4. Run the app:
```bash
npx expo run:android
```

**⚠️ Note:** This library does NOT work with Expo Go. You must use Expo Prebuild or Development Build.

### For React Native CLI Projects

The library uses autolinking, so no manual linking is required for React Native 0.60+.

#### Android Permissions

Add to your `android/app/src/main/AndroidManifest.xml`:

```xml
<!-- Bluetooth permissions for Android 11 and below -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<!-- Bluetooth permissions for Android 12 and above -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />

<!-- Location permissions (needed for Bluetooth scanning on Android 11 and below) -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
```

## Usage

```javascript
import { RNBluetoothDatecsPrinter } from 'react-native-bluetooth-datecs-printer';
import { PermissionsAndroid, Platform } from 'react-native';

// Request Bluetooth permissions (Android 12+)
async function requestBluetoothPermissions() {
  if (Platform.OS === 'android' && Platform.Version >= 31) {
    const granted = await PermissionsAndroid.requestMultiple([
      PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
      PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
    ]);
    return (
      granted['android.permission.BLUETOOTH_CONNECT'] === 'granted' &&
      granted['android.permission.BLUETOOTH_SCAN'] === 'granted'
    );
  }
  return true;
}

// Scan for paired devices
async function scanDevices() {
  await requestBluetoothPermissions();
  const devices = await RNBluetoothDatecsPrinter.getDeviceList();
  console.log('Devices:', devices);
}

// Connect to a device
async function connect(deviceAddress) {
  await RNBluetoothDatecsPrinter.connect(deviceAddress);
  console.log('Connected!');
}

// Print text
async function print() {
  await RNBluetoothDatecsPrinter.printText('Hello World!\n');
}

// Disconnect
async function disconnect() {
  await RNBluetoothDatecsPrinter.disconnect();
}
```

### Complete Example

See [examples/ExpoExample.tsx](./examples/ExpoExample.tsx) for a complete working example with UI.

## API

### Methods

- `getDeviceList()`: Returns a list of paired Bluetooth devices
- `connect(address: string)`: Connect to a device by MAC address
- `disconnect()`: Disconnect from the current device
- `printText(text: string)`: Print text
- `printQRCode(data: string, size?: number)`: Print QR code
- `printBarcode(data: string, type?: number)`: Print barcode
- `feedPaper(lines?: number)`: Feed paper

## Troubleshooting

### Common Issues

1. **"Namespace not specified" error**: Make sure you're using the latest version of the library
2. **Bluetooth permissions denied**: Request runtime permissions on Android 12+
3. **Build fails**: Clean the project with `./gradlew clean` or `npx expo prebuild --clean`
4. **Printer not found**: Make sure the printer is paired in Android Bluetooth settings

For more help, see [EXPO_SETUP.md](./EXPO_SETUP.md)

## Compatibility

| Package Version | Expo SDK | React Native | Android SDK |
|----------------|----------|--------------|-------------|
| 1.0.22+        | 54+      | 0.76+        | 36          |
| < 1.0.22       | -        | 0.72         | 30          |

## License

MIT