react-native-urovo-scanner/README.md

React Native package for Urovo Scanner SDK integration - Official SDK implementation

# React Native Urovo Scanner

[![npm version](https://badge.fury.io/js/react-native-urovo-scanner.svg)](https://badge.fury.io/js/react-native-urovo-scanner)
[![Platform](https://img.shields.io/badge/platform-android-green.svg)](https://www.android.com)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)

React Native package for Urovo Scanner SDK integration using the **official Urovo SDK v4.1.0326**. This package provides a complete TypeScript interface for barcode scanning functionality on Urovo handheld devices.

## 📱 Features

- ✅ **Official Urovo SDK Integration** - Uses the official Urovo SDK v4.1.0326
- ✅ **Complete TypeScript Support** - Full type definitions and IntelliSense
- ✅ **Multiple Trigger Modes** - ONESHOT, CONTINUOUS, PULSE
- ✅ **Comprehensive Barcode Support** - QR, Code128, Code39, EAN13, EAN8, UPC-A, UPC-E, DataMatrix, PDF417, Aztec
- ✅ **Advanced Configuration** - Sound, vibration, keyboard wedge, and more
- ✅ **Manual Laser Control** - Press/release laser control
- ✅ **React Hooks** - Modern React patterns with custom hooks
- ✅ **Configuration UI Component** - Ready-to-use configuration interface

## 🔧 Installation

```bash
npm install react-native-urovo-scanner
```

### Android Setup

1. Add the following to your `android/app/build.gradle`:

```gradle
dependencies {
    implementation project(':react-native-urovo-scanner')
}
```

2. Add the package to your `MainApplication.java`:

```java
import com.reactnativeurovoscanner.UrovoScannerPackage;

public class MainApplication extends Application implements ReactApplication {
    // ...
    
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            new UrovoScannerPackage() // Add this line
        );
    }
}
```

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

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />
```

## 🚀 Usage

### Basic Usage

```tsx
import React, { useEffect, useState } from 'react';
import { View, Text, Alert } from 'react-native';
import { useUrovoScanner, ScanResult } from 'react-native-urovo-scanner';

const App = () => {
  const [scanResults, setScanResults] = useState<ScanResult[]>([]);

  const handleScan = (result: ScanResult) => {
    setScanResults(prev => [result, ...prev]);
    Alert.alert('Scanned', `Value: ${result.value}\nType: ${result.symbology}`);
  };

  const { isOpened } = useUrovoScanner({
    onScanResult: handleScan,
    autoOpen: true,
  });

  return (
    <View style={{ flex: 1, padding: 20 }}>
      <Text>Scanner Status: {isOpened ? 'Ready' : 'Not Available'}</Text>
      {scanResults.map((result, index) => (
        <Text key={index}>
          {result.value} ({result.symbology})
        </Text>
      ))}
    </View>
  );
};
```

### Advanced Usage with Configuration

```tsx
import React, { useState } from 'react';
import { View, Button, Modal } from 'react-native';
import { 
  useUrovoScanner, 
  ScannerConfiguration, 
  TRIGGER_MODES 
} from 'react-native-urovo-scanner';

const App = () => {
  const [showConfig, setShowConfig] = useState(false);
  
  const { isOpened, startScan, stopScan } = useUrovoScanner({
    onScanResult: (result) => {
      console.log('Scan result:', result);
    },
  });

  return (
    <View style={{ flex: 1, padding: 20 }}>
      <Button 
        title="Open Configuration" 
        onPress={() => setShowConfig(true)} 
      />
      
      <Button 
        title="Start Manual Scan" 
        onPress={startScan}
        disabled={!isOpened}
      />
      
      <Button 
        title="Stop Manual Scan" 
        onPress={stopScan}
        disabled={!isOpened}
      />

      <Modal visible={showConfig} animationType="slide">
        <ScannerConfiguration onClose={() => setShowConfig(false)} />
      </Modal>
    </View>
  );
};
```

## 📚 API Reference

### Hooks

#### `useUrovoScanner(options)`

Main hook for scanner functionality.

**Parameters:**
- `options.onScanResult?: (result: ScanResult) => void` - Callback for scan results
- `options.onScanError?: (error: ScanError) => void` - Callback for scan errors
- `options.autoOpen?: boolean` - Auto-open scanner on mount (default: true)

**Returns:**
- `isOpened: boolean` - Scanner availability status
- `isScanning: boolean` - Current scanning status
- `openScanner: () => Promise<boolean>` - Open scanner function
- `closeScanner: () => Promise<boolean>` - Close scanner function
- `startScan: () => Promise<boolean>` - Start scanning function
- `stopScan: () => Promise<boolean>` - Stop scanning function
- `error: string | null` - Current error state

#### `useScannerConfiguration()`

Hook for advanced scanner configuration.

**Returns:**
- `config: ScannerConfiguration | null` - Current configuration
- `constants: PropertyIDConstants | null` - PropertyID constants
- `loading: boolean` - Loading state
- `error: string | null` - Error state
- `updateParameter: (propertyId: number, value: number) => Promise<boolean>` - Update parameter function
- `refreshConfiguration: () => Promise<void>` - Refresh configuration function

### Components

#### `ScannerConfiguration`

Ready-to-use configuration component with UI for all scanner settings.

**Props:**
- `onClose?: () => void` - Callback when closing the configuration

### Constants

#### `TRIGGER_MODES`

```tsx
export const TRIGGER_MODES = {
  SCAN_TRIGGER_MODE_ONESHOT: 0,    // One scan per trigger
  SCAN_TRIGGER_MODE_CONTINUOUS: 1,  // Continuous scanning
  SCAN_TRIGGER_MODE_PULSE: 2,       // Pulse scanning
};
```

#### `SCAN_MODES`

```tsx
export const SCAN_MODES = {
  SCAN_MODE_BROADCAST: 0,  // Broadcast mode
  SCAN_MODE_STORAGE: 1,    // Storage mode
  SCAN_MODE_WEDGE: 2,      // Keyboard wedge mode
};
```

### Types

#### `ScanResult`

```tsx
interface ScanResult {
  value: string;      // Scanned barcode value
  symbology: string;  // Barcode type (QR, CODE128, etc.)
}
```

#### `ScannerConfiguration`

```tsx
interface ScannerConfiguration {
  qrCode: number;
  code128: number;
  code39: number;
  ean13: number;
  ean8: number;
  upca: number;
  upce: number;
  dataMatrix: number;
  pdf417: number;
  aztec: number;
  keyboardWedge: number;
  beepEnabled: number;
  vibrateEnabled: number;
}
```

## 🎯 Supported Barcode Types

- **QR Code** - Quick Response codes
- **Code 128** - High-density linear barcode
- **Code 39** - Alphanumeric barcode
- **EAN-13** - European Article Number
- **EAN-8** - Short EAN barcode
- **UPC-A** - Universal Product Code
- **UPC-E** - Compressed UPC
- **Data Matrix** - 2D matrix barcode
- **PDF417** - Stacked linear barcode
- **Aztec** - 2D matrix barcode

## 📱 Compatible Devices

- **Urovo CT58** - Handheld terminal
- **Urovo CT60** - Handheld terminal
- **Urovo RT40** - Rugged tablet
- **Other Urovo Android devices** with built-in scanners

## 🔧 Configuration Options

### Trigger Modes

- **ONESHOT**: Single scan per trigger activation
- **CONTINUOUS**: Continuous scanning while trigger is held
- **PULSE**: Rapid pulse scanning

### Barcode Types

Enable/disable specific barcode types:
- QR Code, Code 128, Code 39
- EAN-13, EAN-8, UPC-A, UPC-E
- Data Matrix, PDF417, Aztec

### Behavior Settings

- **Sound**: Enable/disable scan success beep
- **Vibration**: Enable/disable scan success vibration
- **Keyboard Wedge**: Enable/disable keyboard input mode

## 🛠️ Development

### Requirements

- React Native 0.60+
- Android SDK 21+
- Urovo device with official SDK support

### Building

```bash
git clone https://github.com/gglibaak/react-native-urovo-scanner.git
cd react-native-urovo-scanner
npm install
npm run build
```

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details.

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/gglibaak/react-native-urovo-scanner/issues)
- **Email**: gglibaak@gmail.com

## 🙏 Acknowledgments

- Built with the official Urovo SDK v4.1.0326
- Designed for professional barcode scanning applications
- Optimized for Urovo handheld devices

---

**Made with ❤️ for the Urovo developer community**