pos_bluetooth_thermal_printer/CHROME_BLUETOOTH_TROUBLESHOOTING.md

# Chrome Bluetooth Thermal Printer Connection Troubleshooting Guide

## Common Issue: Printer Cannot Connect in Chrome

If you're experiencing connection issues with your Bluetooth thermal printer in Chrome, follow this comprehensive troubleshooting guide.

## Quick Fix Checklist

✅ **Before You Start:**
1. Printer is powered ON
2. Printer is in pairing/discoverable mode (LED blinking)
3. Printer is within 1-2 meters of your device
4. Using Chrome 56+ or Edge (Chromium-based)
5. Accessing Odoo via HTTPS (or localhost)
6. Bluetooth is enabled on your device

## Step-by-Step Troubleshooting

### Step 1: Verify Chrome Bluetooth Support

1. Open Chrome and navigate to: `chrome://flags`
2. Search for "Web Bluetooth"
3. Ensure it's **Enabled** (should be by default)
4. If you changed anything, restart Chrome

**Test Bluetooth API:**
1. Press `F12` to open Developer Tools
2. Go to the **Console** tab
3. Type: `navigator.bluetooth.getAvailability()`
4. Press Enter
5. Should return a Promise that resolves to `true`

If it returns `false` or throws an error, your browser doesn't support Web Bluetooth.

### Step 2: Check System Bluetooth

**Windows 10/11:**
1. Open **Settings** > **Devices** > **Bluetooth & other devices**
2. Ensure Bluetooth is **ON**
3. If your printer appears in the list, click it and select **Remove device**
4. This ensures a fresh pairing attempt

**macOS:**
1. Open **System Preferences** > **Bluetooth**
2. Ensure Bluetooth is **ON**
3. If your printer appears, click the **X** to forget it
4. This ensures a fresh pairing attempt

**Linux:**
1. Ensure BlueZ 5.41+ is installed: `bluetoothctl --version`
2. Check Bluetooth status: `systemctl status bluetooth`
3. If printer is paired: `bluetoothctl remove [MAC_ADDRESS]`

### Step 3: Prepare Your Printer

**For RPP02 and Similar Printers:**
1. Turn OFF the printer
2. Press and HOLD the power button
3. Keep holding until the LED starts **blinking rapidly** (usually 3-5 seconds)
4. Release the button
5. The printer is now in pairing mode

**For Epson TM-Series:**
1. Consult your printer manual for pairing mode
2. Usually involves holding a specific button combination
3. LED should indicate pairing mode

**For Star Micronics:**
1. Check printer manual for pairing instructions
2. Some models have a dedicated pairing button

### Step 4: Clear Browser Data (If Needed)

If you've tried pairing before and it failed:

1. Open Chrome Settings
2. Go to **Privacy and security** > **Site Settings**
3. Scroll down to **Bluetooth**
4. Find your Odoo site in the list
5. Click it and **Clear data**
6. Alternatively, clear all browsing data:
   - Settings > Privacy and security > Clear browsing data
   - Select "Cookies and other site data"
   - Click "Clear data"

### Step 5: Proper Pairing Procedure

1. **In Odoo POS:**
   - Click the Bluetooth printer icon in the top bar
   - Click **"Scan for Devices"**

2. **Chrome will show a pairing dialog:**
   - You should see your printer in the list
   - The printer name might be: RPP02, Printer-XXXX, BT-XXXX, etc.
   - Click on your printer to select it
   - Click the **"Pair"** button

3. **Wait for connection:**
   - Status will show "Connecting..."
   - Should connect within 5-10 seconds
   - Status will turn green when connected

4. **Test the connection:**
   - Click **"Test Print"**
   - Printer should print a test receipt

### Step 6: If Printer Doesn't Appear in Scan

**Possible Causes:**

1. **Printer not in pairing mode**
   - Solution: Put printer in pairing mode (see Step 3)

2. **Printer already paired to another device**
   - Solution: Unpair from other device first
   - Or: Reset printer to factory settings (consult manual)

3. **Bluetooth interference**
   - Solution: Move away from other Bluetooth devices
   - Turn off nearby Bluetooth devices temporarily

4. **Printer out of range**
   - Solution: Move printer within 1-2 meters

5. **Printer battery low**
   - Solution: Charge the printer

### Step 7: If Connection Fails After Pairing

**Error: "Failed to connect to bluetooth device"**

**Possible Solutions:**

1. **Restart the printer:**
   - Turn OFF completely
   - Wait 10 seconds
   - Turn ON
   - Put in pairing mode again
   - Try connecting again

2. **Restart Bluetooth on your device:**
   - Turn OFF Bluetooth
   - Wait 10 seconds
   - Turn ON Bluetooth
   - Try connecting again

3. **Try a different USB Bluetooth adapter (if using one):**
   - Some USB Bluetooth adapters have compatibility issues
   - Try the built-in Bluetooth if available

4. **Check for Bluetooth driver updates:**
   - Windows: Device Manager > Bluetooth > Update driver
   - macOS: System updates usually include driver updates
   - Linux: Update BlueZ package

### Step 8: If Printer Connects But Doesn't Print

**Possible Causes:**

1. **No paper in printer**
   - Solution: Load paper correctly

2. **Paper jam**
   - Solution: Open printer and clear jam

3. **Printer in error state**
   - Solution: Check printer LED indicators
   - Consult printer manual for error codes
   - Try power cycling the printer

4. **Wrong printer model/protocol**
   - Solution: Verify your printer supports ESC/POS protocol
   - Check printer specifications

## Advanced Troubleshooting

### Enable Chrome Bluetooth Logging

1. Close all Chrome windows
2. Open Command Prompt (Windows) or Terminal (Mac/Linux)
3. Run Chrome with logging:

**Windows:**
```cmd
"C:\Program Files\Google\Chrome\Application\chrome.exe" --enable-logging --v=1
```

**macOS:**
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --enable-logging --v=1
```

**Linux:**
```bash
google-chrome --enable-logging --v=1
```

4. Try connecting to the printer
5. Check the log file for errors:
   - Windows: `%LOCALAPPDATA%\Google\Chrome\User Data\chrome_debug.log`
   - macOS/Linux: `~/Library/Application Support/Google/Chrome/chrome_debug.log`

### Check Bluetooth Service UUIDs

The module now tries multiple common Bluetooth service UUIDs:
- `00001101-0000-1000-8000-00805f9b34fb` (Serial Port Profile - SPP)
- `000018f0-0000-1000-8000-00805f9b34fb` (Alternative serial service)
- `49535343-fe7d-4ae5-8fa9-9fafd205e455` (Microchip transparent UART)
- `0000ffe0-0000-1000-8000-00805f9b34fb` (Common serial service)
- `6e400001-b5a3-f393-e0a9-e50e24dcca9e` (Nordic UART Service)

If your printer uses a different UUID, you may need to add it to the code.

### Test with Chrome's Bluetooth Internals

1. Open Chrome and navigate to: `chrome://bluetooth-internals`
2. Click **"Devices"** tab
3. Click **"Start Scan"**
4. Look for your printer in the list
5. Click on your printer
6. Click **"Connect"**
7. Explore available services and characteristics

This helps identify if the issue is with Chrome's Bluetooth or the module.

## Known Limitations

### Chrome Web Bluetooth API Limitations

1. **Serial Port Profile (SPP) Support:**
   - Chrome's Web Bluetooth API primarily supports GATT services
   - Many thermal printers use SPP which is not fully supported
   - The module now includes fallback logic to find writable characteristics

2. **Platform Differences:**
   - **Windows:** Best support, most reliable
   - **macOS:** Good support, some printer models may have issues
   - **Linux:** Requires BlueZ 5.41+, may need additional permissions
   - **Chrome OS:** Excellent support
   - **Android:** Good support, requires location permission

3. **HTTPS Requirement:**
   - Web Bluetooth only works over HTTPS
   - Exception: localhost and 127.0.0.1
   - Self-signed certificates may cause issues

## Alternative Solutions

### If Chrome Bluetooth Doesn't Work

1. **Use a different browser:**
   - Try Microsoft Edge (Chromium-based)
   - Try Opera browser
   - Both support Web Bluetooth API

2. **Use USB connection:**
   - Connect printer via USB cable
   - Use browser's standard print dialog
   - Less convenient but more reliable

3. **Use a Bluetooth-to-USB adapter:**
   - Some adapters create a virtual serial port
   - Printer appears as USB device
   - Use standard printing methods

4. **Use a dedicated POS terminal:**
   - Hardware POS terminals often have better Bluetooth support
   - More expensive but more reliable

## Printer-Specific Notes

### RPP02 Thermal Printer

- **Pairing Mode:** Hold power button until LED blinks rapidly
- **Service UUID:** Usually uses standard SPP
- **Compatibility:** Good with Chrome on Windows and macOS
- **Common Issue:** Sometimes needs to be unpaired and re-paired

### Epson TM-P20/P80

- **Pairing Mode:** Consult manual (varies by model)
- **Service UUID:** Standard ESC/POS services
- **Compatibility:** Excellent with Chrome
- **Common Issue:** May need firmware update

### Star Micronics SM-L200/L300

- **Pairing Mode:** Dedicated pairing button
- **Service UUID:** Standard ESC/POS services
- **Compatibility:** Excellent with Chrome
- **Common Issue:** Battery level affects connection stability

## Getting Additional Help

If you've tried all the above and still can't connect:

1. **Check browser console for errors:**
   - Press F12
   - Go to Console tab
   - Look for error messages
   - Take a screenshot

2. **Gather information:**
   - Chrome version: `chrome://version`
   - Operating system and version
   - Printer model and firmware version
   - Error messages from console
   - Steps you've already tried

3. **Test with a different device:**
   - Try on another computer/tablet
   - Helps isolate if issue is device-specific

4. **Contact support with:**
   - All information gathered above
   - Screenshots of errors
   - Printer specifications
   - Bluetooth adapter information (if using external)

## Recent Improvements (Latest Version)

The module has been updated with the following improvements:

1. **Multiple Service UUID Support:**
   - Now tries 5 different common Bluetooth service UUIDs
   - Automatically falls back to alternative services

2. **Automatic Characteristic Discovery:**
   - If standard services aren't found, scans all services
   - Finds any writable characteristic automatically

3. **Better Error Messages:**
   - More descriptive error messages
   - Helps identify specific connection issues

4. **Improved Chunk Handling:**
   - Reduced chunk size to 20 bytes for maximum compatibility
   - Supports both write and writeWithoutResponse methods
   - Better timing between chunks

5. **Enhanced Device Filtering:**
   - Filters for common thermal printer name patterns
   - Falls back to showing all devices if filters don't match

These improvements should resolve most connection issues with Chrome and Bluetooth thermal printers.