npm package: @leonardojc/capacitor-ioboard
Description: A comprehensive Capacitor plugin for IOBoard devices with integrated serial communication and complete MTC3P08L protocol support including OTA updates
Author: Leonardo JC
Latest version: 2.1.1

# 🚀 IOBoard Plugin v2.0 - Integrated Serial + Protocol

**@leonardojc/capacitor-ioboard v2.0.0** - Complete IOBoard control with integrated serial communication

## ✨ What's New in v2.0

- **🔗 Integrated Serial Communication** - No need for separate serial plugin
- **🎯 Simplified API** - Single plugin handles everything
- **⚡ Real-time Events** - Connection state, data received, error handling
- **🎨 Enhanced Color Control** - Predefined colors and custom RGB support
- **🚀 Complete OTA Support** - Firmware updates with progress tracking
- **🌐 Web Compatible** - Works in browser with simulation mode

## 📦 Installation

```bash
npm install @leonardojc/capacitor-ioboard@2.0.0
npx cap sync
```

## 🚀 Quick Start

```typescript
import { ioboard } from '@leonardojc/capacitor-ioboard';

// Connect to device
const result = await ioboard.connect('/dev/ttyS2', 115200);

// Unlock pallet with green color
await ioboard.unlockPallet(1, 3, 'GREEN', {
  intensity: 100,
  blinkTimes: 3,
  blinkSpeed: 2
});

// Set all pallets to red
await ioboard.setAllPalletsColor(1, 'RED');

// Get device status
const status = await ioboard.getStatus(1);
console.log(\`Firmware: \${status.status.firmwareVersion}\`);
```

## 📚 Complete API Reference

### 🔌 Connection Methods

#### `connect(portPath?, baudRate?)`
Connect to IOBoard device
```typescript
await ioboard.connect('/dev/ttyS2', 115200);
```

#### `disconnect()`
Disconnect from device
```typescript
await ioboard.disconnect();
```

#### `isDeviceConnected()`
Check connection status
```typescript
const status = await ioboard.isDeviceConnected();
console.log(status.connected); // true/false
```

#### `listPorts()`
List available serial ports
```typescript
const result = await ioboard.listPorts();
console.log(result.ports); // ['/dev/ttyS0', '/dev/ttyS1', ...]
```

### 🎮 IOBoard Device Methods

#### `getStatus(address)`
Get device status and information
```typescript
const result = await ioboard.getStatus(1);
console.log(result.status);
// {
//   address: 1,
//   connected: true,
//   firmwareVersion: "2.1.0",
//   palletStates: [false, false, ...], // 8 pallets
//   temperature: 25.5,
//   voltage: 12.0,
//   uptime: 86400
// }
```

#### `unlockPallet(address, palletNumber, color, options?)`
Unlock specific pallet with color and effects
```typescript
await ioboard.unlockPallet(1, 3, 'GREEN', {
  intensity: 100,      // 0-100
  blinkTimes: 3,       // Number of blinks (0 = solid)
  blinkSpeed: 2        // Blink speed (1-5)
});

// Using custom RGB color
await ioboard.unlockPallet(1, 5, { red: 255, green: 128, blue: 0 });
```

#### `setAllPalletsColor(address, color, options?)`
Set color for all 8 pallets
```typescript
await ioboard.setAllPalletsColor(1, 'BLUE', {
  intensity: 80,
  blinkTimes: 0  // Solid color
});
```

#### `controlMultipleLEDs(address, ledConfigs)`
Control each pallet individually
```typescript
const configs = [
  { color: 'RED', intensity: 100 },
  { color: 'GREEN', intensity: 90 },
  { color: 'BLUE', intensity: 80 },
  { color: { red: 255, green: 128, blue: 0 }, intensity: 70 },
  // ... up to 8 configurations
];

await ioboard.controlMultipleLEDs(1, configs);
```

### 🎨 Predefined Colors

Available color presets:
- `RED`, `GREEN`, `BLUE`
- `YELLOW`, `MAGENTA`, `CYAN`
- `WHITE`, `OFF`
- `ORANGE`, `PURPLE`, `PINK`, `LIME`

```typescript
// Using predefined colors
await ioboard.unlockPallet(1, 0, 'PURPLE');

// Using custom RGB
await ioboard.unlockPallet(1, 1, { red: 128, green: 64, blue: 192 });

// Get available colors
const colors = ioboard.getColorPresets();
```

### 🚀 OTA Firmware Update

#### `startOTAUpdate(address, fileName, fileSize)`
Initialize OTA update process
```typescript
await ioboard.startOTAUpdate(1, 'firmware.bin', 32768);
```

#### `sendOTAData(address, packetNumber, data)`
Send OTA data packet
```typescript
await ioboard.sendOTAData(1, 0, [0x48, 0x65, 0x6C, 0x6C, 0x6F]); // "Hello"
```

#### `performOTAUpdate(address, file, onProgress?)`
Complete OTA update with progress callback
```typescript
const file = new File([firmwareData], 'firmware.bin');

await ioboard.performOTAUpdate(1, file, (progress, packet, total) => {
  console.log(\`Progress: \${progress.toFixed(1)}% (\${packet}/\${total})\`);
});
```

### 📡 Event Handling

#### `addDataReceivedListener(callback)`
Listen for data received from device
```typescript
await ioboard.addDataReceivedListener((event) => {
  console.log('Data received:', event);
});
```

#### `addConnectionStateListener(callback)`
Listen for connection state changes
```typescript
await ioboard.addConnectionStateListener((event) => {
  console.log(\`Connection: \${event.connected}\`);
});
```

#### `addSerialErrorListener(callback)`
Listen for serial communication errors
```typescript
await ioboard.addSerialErrorListener((event) => {
  console.error('Serial error:', event.error);
});
```

#### `removeAllListeners()`
Remove all event listeners
```typescript
await ioboard.removeAllListeners();
```

## 🛠️ Utility Methods

#### `getConnectionInfo()`
Get current connection information
```typescript
const info = ioboard.getConnectionInfo();
console.log(info.isConnected, info.currentPort);
```

#### `createColor(red, green, blue)`
Create RGB color object
```typescript
const orange = ioboard.createColor(255, 165, 0);
await ioboard.unlockPallet(1, 0, orange);
```

## 🌟 React Component Example

```jsx
import React, { useState, useEffect } from 'react';
import { ioboard } from '@leonardojc/capacitor-ioboard';

const IOBoardController = () => {
  const [isConnected, setIsConnected] = useState(false);

  useEffect(() => {
    // Setup event listeners
    ioboard.addConnectionStateListener((event) => {
      setIsConnected(event.connected);
    });

    return () => {
      ioboard.removeAllListeners();
    };
  }, []);

  const handleConnect = async () => {
    const result = await ioboard.connect('/dev/ttyS2');
    if (result.success) {
      console.log('Connected successfully!');
    }
  };

  const handleUnlockPallet = async (pallet) => {
    await ioboard.unlockPallet(1, pallet, 'GREEN', {
      intensity: 100,
      blinkTimes: 3
    });
  };

  return (
    <div>
      <button onClick={handleConnect} disabled={isConnected}>
        {isConnected ? 'Connected' : 'Connect'}
      </button>
      
      {isConnected && (
        <div>
          {[0,1,2,3,4,5,6,7].map(pallet => (
            <button 
              key={pallet} 
              onClick={() => handleUnlockPallet(pallet)}
            >
              Unlock Pallet {pallet}
            </button>
          ))}
        </div>
      )}
    </div>
  );
};
```

## 📋 MTC3P08L Protocol

The plugin implements the complete MTC3P08L protocol:

- **Device Status** - Get firmware version, temperature, voltage
- **Pallet Control** - Individual pallet unlock with RGB LEDs
- **Multiple Control** - Control all 8 pallets simultaneously  
- **OTA Updates** - Complete firmware update support
- **Error Handling** - Comprehensive error reporting

## 🔧 Configuration

Default connection settings:
- **Baud Rate**: 115200
- **Data Bits**: 8
- **Stop Bits**: 1
- **Parity**: None
- **Default Port**: '/dev/ttyS2'

## 🌐 Platform Support

- ✅ **Android** - Full native support
- ✅ **iOS** - Full native support  
- ✅ **Web** - Simulation mode for testing

## 🆚 Migration from v1.x

Version 2.0 is a complete rewrite with breaking changes:

### Before (v1.x - Two plugins)
```typescript
// Required two separate plugins
import { CapacitorSerialPort } from '@leonardojc/capacitor-serial-port';
import { CapacitorIoboard } from '@leonardojc/capacitor-ioboard';

// Complex coordination required
await CapacitorSerialPort.connect({...});
await CapacitorIoboard.unlockPallet({...});
```

### After (v2.0 - Single plugin)
```typescript
// Single integrated plugin
import { ioboard } from '@leonardojc/capacitor-ioboard';

// Simple, unified API
await ioboard.connect('/dev/ttyS2');
await ioboard.unlockPallet(1, 3, 'GREEN');
```

## 🔗 Links

- **NPM Package**: [@leonardojc/capacitor-ioboard](https://www.npmjs.com/package/@leonardojc/capacitor-ioboard)
- **GitHub**: [IOBoard Plugin Repository](#)
- **Documentation**: [Complete API Docs](#)

## 📄 License

MIT License - see LICENSE file for details.

---

### 🎉 IOBoard v2.0 - Simplified, Powerful, Complete!

Single plugin, comprehensive control, zero hassle. Everything you need for IOBoard device integration.