1000 lines
35 KiB
Markdown
1000 lines
35 KiB
Markdown
# POS Bluetooth Thermal Printer
|
|
|
|
## Overview
|
|
|
|
This module enables Odoo 18 Point of Sale systems to print receipts directly to bluetooth-connected thermal printers using the Web Bluetooth API and ESC/POS protocol. It provides a seamless wireless printing experience without requiring additional server-side hardware or drivers.
|
|
|
|
The module is designed for multi-device deployments where each tablet or workstation can maintain its own printer configuration independently. All bluetooth communication happens client-side in the browser, with device-specific settings stored in local storage.
|
|
|
|
## Features
|
|
|
|
- **Direct Bluetooth Connection**: Connect to thermal printers via Web Bluetooth API without additional drivers
|
|
- **Automatic Connection**: Auto-connect to configured printer on POS session start
|
|
- **Auto-Reconnection**: Automatic reconnection with exponential backoff (1s, 2s, 4s) on connection drops
|
|
- **Device-Specific Configuration**: Each device maintains its own printer settings in browser local storage
|
|
- **Multi-Device Support**: Different tablets/workstations can use different printers for the same POS configuration
|
|
- **ESC/POS Protocol**: Industry-standard command protocol for proper receipt formatting
|
|
- **Graceful Fallback**: Automatic fallback to browser print dialog on bluetooth failures
|
|
- **Real-Time Status**: Connection status indicator with detailed information tooltip
|
|
- **Test Print**: Verify printer connection with sample receipt before starting sales
|
|
- **Non-Blocking**: Print errors never prevent sale completion - sales always succeed
|
|
- **Timeout Handling**: 10-second timeout with automatic fallback
|
|
- **Error Notifications**: User-friendly error messages for common issues
|
|
|
|
## Requirements
|
|
|
|
### Software Requirements
|
|
|
|
**Odoo Version**
|
|
- Odoo 18.0 or higher
|
|
- `point_of_sale` module installed and configured
|
|
|
|
**Browser Requirements**
|
|
|
|
The module requires a browser with Web Bluetooth API support:
|
|
|
|
| Browser | Version | Support Status |
|
|
|---------|---------|----------------|
|
|
| Google Chrome | 56+ | ✅ Full Support (Recommended) |
|
|
| Microsoft Edge | Chromium-based | ✅ Full Support |
|
|
| Opera | 43+ | ✅ Full Support |
|
|
| Brave | Latest | ✅ Full Support |
|
|
| Firefox | All | ❌ Not Supported (API behind flag) |
|
|
| Safari | All | ❌ Not Supported |
|
|
|
|
**Connection Requirements**
|
|
- HTTPS connection required for Web Bluetooth API
|
|
- Exception: `localhost` and `127.0.0.1` work without HTTPS for testing
|
|
- Valid SSL certificate for production deployments
|
|
|
|
### Hardware Requirements
|
|
|
|
**Device Requirements**
|
|
- Bluetooth 4.0+ capable device (tablet, laptop, or desktop)
|
|
- Minimum 2GB RAM recommended
|
|
- Touch-screen device recommended for POS operations
|
|
|
|
**Printer Requirements**
|
|
- Bluetooth thermal printer with ESC/POS protocol support
|
|
- Bluetooth pairing capability
|
|
- 58mm or 80mm paper width (configurable)
|
|
- Sufficient bluetooth range (typically 10 meters)
|
|
|
|
## Installation
|
|
|
|
### Step 1: Add Module to Odoo
|
|
|
|
**Option A: Manual Installation**
|
|
1. Copy the `pos_bluetooth_thermal_printer` directory to your Odoo addons path
|
|
```bash
|
|
cp -r pos_bluetooth_thermal_printer /path/to/odoo/addons/
|
|
```
|
|
2. Restart the Odoo server
|
|
```bash
|
|
sudo systemctl restart odoo
|
|
```
|
|
|
|
**Option B: Custom Addons Path**
|
|
1. Place the module in your custom addons directory
|
|
2. Ensure the path is included in your `odoo.conf`:
|
|
```ini
|
|
[options]
|
|
addons_path = /path/to/odoo/addons,/path/to/custom/addons
|
|
```
|
|
3. Restart the Odoo server
|
|
|
|
### Step 2: Update Apps List
|
|
|
|
1. Log in to Odoo as an administrator
|
|
2. Navigate to **Apps** menu
|
|
3. Click **Update Apps List** (you may need to activate Developer Mode)
|
|
4. Confirm the update
|
|
|
|
### Step 3: Install the Module
|
|
|
|
1. In the **Apps** menu, search for "POS Bluetooth Thermal Printer"
|
|
2. Click **Install** on the module card
|
|
3. Wait for installation to complete
|
|
4. The module will automatically install dependencies (`point_of_sale`)
|
|
|
|
### Step 4: Verify Installation
|
|
|
|
1. Go to **Point of Sale > Configuration > Point of Sale**
|
|
2. Open any POS configuration
|
|
3. Verify that "Enable Bluetooth Printer" option is available in the settings
|
|
4. If visible, installation was successful
|
|
|
|
## Configuration
|
|
|
|
### Step 1: Enable Bluetooth Printer in POS Configuration
|
|
|
|
1. Navigate to **Point of Sale > Configuration > Point of Sale**
|
|
2. Select the POS configuration you want to enable bluetooth printing for
|
|
3. Scroll to the bluetooth printer section
|
|
4. Check the **Enable Bluetooth Printer** checkbox
|
|
5. Click **Save**
|
|
|
|
**Note**: Each POS configuration can be enabled independently. You can have some POS configurations using bluetooth printers and others using standard printing.
|
|
|
|
### Step 2: Prepare Your Bluetooth Printer
|
|
|
|
Before pairing, ensure your printer is ready:
|
|
|
|
1. **Power On**: Turn on your bluetooth thermal printer
|
|
2. **Pairing Mode**: Put the printer in pairing/discoverable mode
|
|
- For RPP02: Press and hold the power button until the LED blinks rapidly
|
|
- Consult your printer manual for specific instructions
|
|
3. **Proximity**: Keep the printer within 1-2 meters of the device during pairing
|
|
4. **Paper**: Load paper into the printer for test printing
|
|
|
|
### Step 3: Pair Printer with Device
|
|
|
|
**Important**: Pairing is device-specific. Each tablet or workstation needs to be paired individually.
|
|
|
|
1. Open a POS session on the device you want to configure
|
|
2. Look for the bluetooth printer icon in the POS interface (typically in the top bar)
|
|
3. Click the bluetooth printer configuration button
|
|
4. In the configuration dialog:
|
|
- Click **Scan for Devices**
|
|
- Wait for the scan to complete (5-10 seconds)
|
|
- Your printer should appear in the device list with signal strength
|
|
5. Click on your printer in the list to select it
|
|
6. The browser will show a pairing dialog - click **Pair**
|
|
7. Wait for the connection to establish (indicated by green status)
|
|
|
|
### Step 4: Configure Printer Settings (Optional)
|
|
|
|
After pairing, you can adjust printer-specific settings:
|
|
|
|
1. **Character Set**: Select the appropriate character encoding
|
|
- CP437: US English (default)
|
|
- CP850: Western European
|
|
- CP852: Central European
|
|
- CP858: Western European with Euro symbol
|
|
2. **Paper Width**: Set to match your printer
|
|
- 32 characters (58mm paper)
|
|
- 42 characters (80mm paper, normal font)
|
|
- 48 characters (80mm paper, condensed font)
|
|
3. **Auto-Reconnect**: Enable/disable automatic reconnection (enabled by default)
|
|
4. **Timeout**: Print timeout in milliseconds (default: 10000ms)
|
|
|
|
### Step 5: Test the Connection
|
|
|
|
1. Click the **Test Print** button in the configuration dialog
|
|
2. The printer should print a test receipt with sample data
|
|
3. Verify the receipt prints correctly with proper formatting
|
|
4. If successful, you'll see a success message
|
|
5. If it fails, check the troubleshooting section below
|
|
|
|
### Step 6: Start Using the POS
|
|
|
|
1. Close the configuration dialog
|
|
2. The connection status indicator should show green (connected)
|
|
3. Complete a sale as normal
|
|
4. The receipt will automatically print to the bluetooth printer
|
|
5. If printing fails, the system will automatically fall back to the browser print dialog
|
|
|
|
### Multi-Device Configuration
|
|
|
|
For deployments with multiple tablets or workstations:
|
|
|
|
1. **Each device maintains its own configuration**: Device A can use Printer A, Device B can use Printer B
|
|
2. **Same POS, different printers**: Multiple devices can access the same POS configuration but use different printers
|
|
3. **Configuration is stored locally**: Settings are saved in the browser's local storage, not on the server
|
|
4. **Repeat pairing for each device**: You must pair the printer on each device individually
|
|
|
|
**Example Scenario**:
|
|
- Tablet 1 at Counter A: Paired with Printer A
|
|
- Tablet 2 at Counter B: Paired with Printer B
|
|
- Both tablets use the same POS configuration in Odoo
|
|
- Each tablet prints to its own printer automatically
|
|
|
|
## Usage
|
|
|
|
### Normal Operation
|
|
|
|
Once configured, the module operates automatically:
|
|
|
|
1. **Session Start**: When you open a POS session, the system automatically connects to the configured printer
|
|
2. **Sale Completion**: When a sale is completed and payment is confirmed, the receipt prints automatically
|
|
3. **Status Monitoring**: The connection status indicator shows the current printer state
|
|
4. **Automatic Handling**: All connection and printing operations happen in the background
|
|
|
|
### Connection Status Indicator
|
|
|
|
The bluetooth icon in the POS interface shows the current connection state:
|
|
|
|
| Status | Color | Meaning |
|
|
|--------|-------|---------|
|
|
| Connected | Green | Printer is connected and ready |
|
|
| Disconnected | Red | Printer is not connected |
|
|
| Connecting | Yellow (animated) | Attempting to connect |
|
|
| Error | Red with icon | Connection error occurred |
|
|
|
|
**Tooltip**: Hover over the status indicator to see detailed connection information including printer name, connection time, and error details.
|
|
|
|
### Automatic Reconnection
|
|
|
|
If the bluetooth connection drops during a session:
|
|
|
|
1. The system detects the disconnection immediately
|
|
2. Status indicator changes to "Connecting" (yellow)
|
|
3. Automatic reconnection attempts begin with exponential backoff:
|
|
- Attempt 1: After 1 second
|
|
- Attempt 2: After 2 seconds
|
|
- Attempt 3: After 4 seconds
|
|
4. If reconnection succeeds, status returns to "Connected" (green)
|
|
5. If all attempts fail, status shows "Disconnected" (red) and fallback mode activates
|
|
|
|
### Fallback Printing
|
|
|
|
The system automatically falls back to the browser print dialog when:
|
|
|
|
- Bluetooth printer is not connected
|
|
- Print operation times out (after 10 seconds)
|
|
- Printer returns an error
|
|
- Connection drops during printing
|
|
- User manually requests standard printing
|
|
|
|
**Important**: Fallback printing ensures that print failures never prevent sale completion. The sale is always recorded successfully in Odoo, regardless of print status.
|
|
|
|
### Print Workflow
|
|
|
|
```
|
|
Sale Completed
|
|
↓
|
|
Bluetooth Printer Connected?
|
|
↓ Yes ↓ No
|
|
Send to Bluetooth Use Fallback
|
|
↓ ↓
|
|
Print Success? Browser Print Dialog
|
|
↓ Yes ↓ No ↓
|
|
Confirm Use Fallback Print Complete
|
|
↓ ↓ ↓
|
|
Sale Complete ← ← ← ← ← ← ← ←
|
|
```
|
|
|
|
### Session Management
|
|
|
|
**Opening a Session**:
|
|
- System loads printer configuration from local storage
|
|
- Automatic connection attempt to configured printer
|
|
- If no printer configured, user is prompted to set one up
|
|
- Session can proceed even if printer connection fails
|
|
|
|
**During a Session**:
|
|
- Connection status monitored continuously
|
|
- Automatic reconnection on connection drops
|
|
- Print operations handled transparently
|
|
- Status updates shown in real-time
|
|
|
|
**Closing a Session**:
|
|
- Bluetooth connection is gracefully disconnected
|
|
- Configuration remains saved for next session
|
|
- No manual cleanup required
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues and Solutions
|
|
|
|
#### Issue: Printer Not Found During Scanning
|
|
|
|
**Symptoms**: Printer doesn't appear in the device list when scanning
|
|
|
|
**Solutions**:
|
|
1. **Check Power**: Ensure the printer is powered on and has sufficient battery
|
|
2. **Pairing Mode**: Verify the printer is in pairing/discoverable mode
|
|
- LED should be blinking rapidly on most printers
|
|
- Consult printer manual for specific pairing mode instructions
|
|
3. **Bluetooth Enabled**: Confirm bluetooth is enabled on your device
|
|
- Check device bluetooth settings
|
|
- Try turning bluetooth off and on again
|
|
4. **Proximity**: Move the printer closer to the device (within 1-2 meters)
|
|
5. **Previous Pairing**: If previously paired, unpair the printer from device bluetooth settings and try again
|
|
6. **Scan Again**: Click "Scan for Devices" again - sometimes devices take time to appear
|
|
7. **Restart Printer**: Power cycle the printer and try scanning again
|
|
|
|
#### Issue: Connection Fails After Selecting Printer
|
|
|
|
**Symptoms**: Pairing dialog appears but connection fails, or "Connection Failed" error shown
|
|
|
|
**Solutions**:
|
|
1. **Bluetooth Range**: Ensure printer is within bluetooth range (typically 10 meters, but 1-2 meters recommended for pairing)
|
|
2. **Interference**: Check for bluetooth interference from other devices
|
|
- Move away from other bluetooth devices
|
|
- Turn off nearby bluetooth devices temporarily
|
|
3. **Restart Printer**: Power off the printer, wait 10 seconds, power on, and try again
|
|
4. **Clear Browser Cache**:
|
|
```
|
|
Chrome: Settings > Privacy and Security > Clear Browsing Data
|
|
Select "Cached images and files" and "Cookies and other site data"
|
|
```
|
|
5. **Unpair and Re-pair**:
|
|
- Go to device bluetooth settings
|
|
- Find the printer and select "Forget" or "Unpair"
|
|
- Return to POS and scan again
|
|
6. **Browser Permissions**: Ensure browser has bluetooth permissions
|
|
- Chrome: Settings > Privacy and Security > Site Settings > Bluetooth
|
|
- Verify your Odoo site has bluetooth access
|
|
7. **Try Different Browser**: If using Edge, try Chrome, or vice versa
|
|
|
|
#### Issue: Printer Connects But Doesn't Print
|
|
|
|
**Symptoms**: Status shows "Connected" but no output when printing
|
|
|
|
**Solutions**:
|
|
1. **Paper Check**: Ensure printer has paper loaded correctly
|
|
2. **Paper Jam**: Check for paper jams and clear if necessary
|
|
3. **Printer Error**: Check printer for error lights or indicators
|
|
4. **Test Print**: Use the "Test Print" button to verify basic functionality
|
|
5. **Restart Connection**: Disconnect and reconnect the printer
|
|
6. **Power Cycle**: Turn printer off and on again
|
|
7. **Check Printer Status**: Some printers have a status button - press it to print a status report
|
|
8. **Battery Level**: Ensure printer has sufficient battery charge
|
|
|
|
#### Issue: Print Quality Problems
|
|
|
|
**Symptoms**: Garbled text, incorrect characters, formatting issues
|
|
|
|
**Solutions**:
|
|
1. **Character Set**: Verify correct character set is selected in printer settings
|
|
- For English: Use CP437 or CP850
|
|
- For European languages: Use CP850 or CP858
|
|
- For special characters: Try different character sets
|
|
2. **Paper Width**: Ensure paper width setting matches your printer
|
|
- 58mm paper: Use 32 characters
|
|
- 80mm paper: Use 42 or 48 characters
|
|
3. **Printer Compatibility**: Verify printer supports ESC/POS protocol
|
|
4. **Test with Browser Print**: Print using browser print dialog to isolate if issue is printer-specific
|
|
5. **Firmware Update**: Check if printer firmware needs updating
|
|
6. **Thermal Head**: Clean the thermal print head with isopropyl alcohol
|
|
|
|
#### Issue: Fallback Always Triggered
|
|
|
|
**Symptoms**: Browser print dialog always appears instead of bluetooth printing
|
|
|
|
**Solutions**:
|
|
1. **Check Browser Console**:
|
|
- Press F12 to open developer tools
|
|
- Look for errors in the Console tab
|
|
- Common errors and solutions:
|
|
- "Bluetooth not available": Browser doesn't support Web Bluetooth API
|
|
- "HTTPS required": Site must use HTTPS (except localhost)
|
|
- "User cancelled": User cancelled pairing dialog
|
|
2. **Verify Web Bluetooth API**:
|
|
- Open browser console and type: `navigator.bluetooth`
|
|
- Should return an object, not `undefined`
|
|
- If undefined, browser doesn't support Web Bluetooth
|
|
3. **HTTPS Connection**: Ensure you're accessing Odoo via HTTPS
|
|
- Check URL starts with `https://`
|
|
- Exception: `localhost` and `127.0.0.1` work without HTTPS
|
|
- Get a valid SSL certificate for production
|
|
4. **Configuration Saved**: Verify printer configuration is saved
|
|
- Open configuration dialog
|
|
- Check if printer is shown as connected
|
|
- If not, re-pair the printer
|
|
5. **Local Storage**: Check browser local storage isn't full or disabled
|
|
- Chrome: F12 > Application > Local Storage
|
|
- Look for keys starting with `bluetooth_printer_`
|
|
6. **Browser Compatibility**: Verify you're using a supported browser (Chrome, Edge, Opera)
|
|
|
|
#### Issue: Connection Drops Frequently
|
|
|
|
**Symptoms**: Printer disconnects and reconnects repeatedly
|
|
|
|
**Solutions**:
|
|
1. **Bluetooth Range**: Keep printer within 5 meters of device
|
|
2. **Obstacles**: Remove physical obstacles between device and printer
|
|
3. **Interference**: Identify and eliminate sources of interference:
|
|
- Other bluetooth devices
|
|
- WiFi routers (especially 2.4GHz)
|
|
- Microwave ovens
|
|
- Cordless phones
|
|
4. **Battery Level**: Low battery can cause connection instability - charge printer
|
|
5. **Printer Firmware**: Update printer firmware if available
|
|
6. **Device Bluetooth**: Restart device bluetooth:
|
|
- Turn off bluetooth
|
|
- Wait 10 seconds
|
|
- Turn on bluetooth
|
|
- Reconnect printer
|
|
|
|
#### Issue: "No Printer Configured" Message
|
|
|
|
**Symptoms**: Message appears when opening POS session
|
|
|
|
**Solutions**:
|
|
1. **First Time Setup**: This is normal for first use - click to configure printer
|
|
2. **Configuration Lost**: Browser data may have been cleared
|
|
- Re-pair the printer following configuration steps
|
|
3. **Different Device**: Configuration is device-specific
|
|
- Each device needs its own pairing
|
|
- This is expected behavior for multi-device setups
|
|
4. **Different Browser**: Configuration is browser-specific
|
|
- If switching browsers, re-pair in the new browser
|
|
|
|
#### Issue: Slow Printing
|
|
|
|
**Symptoms**: Long delay between sale completion and print start
|
|
|
|
**Solutions**:
|
|
1. **Bluetooth Connection**: Weak bluetooth signal can slow transmission
|
|
- Move printer closer to device
|
|
2. **Printer Buffer**: Printer may be processing previous jobs
|
|
- Wait for printer to finish current job
|
|
3. **Large Receipts**: Receipts with many items take longer
|
|
- This is normal behavior
|
|
4. **Printer Speed**: Some printers are slower than others
|
|
- Check printer specifications
|
|
5. **Connection Quality**: Poor connection quality causes retransmissions
|
|
- Improve bluetooth signal strength
|
|
|
|
### Advanced Troubleshooting
|
|
|
|
#### Enable Debug Logging
|
|
|
|
To get detailed diagnostic information:
|
|
|
|
1. Open browser developer tools (F12)
|
|
2. Go to Console tab
|
|
3. Look for messages prefixed with `[BluetoothPrinter]`
|
|
4. These logs show connection attempts, errors, and status changes
|
|
|
|
#### Check Local Storage
|
|
|
|
To verify configuration is saved:
|
|
|
|
1. Open browser developer tools (F12)
|
|
2. Go to Application tab (Chrome) or Storage tab (Firefox)
|
|
3. Expand Local Storage
|
|
4. Look for keys starting with `bluetooth_printer_`
|
|
5. Verify your configuration is present
|
|
|
|
#### Test Web Bluetooth API
|
|
|
|
To verify browser support:
|
|
|
|
1. Open browser console (F12)
|
|
2. Run: `navigator.bluetooth.getAvailability()`
|
|
3. Should return `Promise {<pending>}` that resolves to `true`
|
|
4. If it returns `false` or throws error, Web Bluetooth is not available
|
|
|
|
#### Clear Printer Configuration
|
|
|
|
To reset printer configuration:
|
|
|
|
1. Open browser developer tools (F12)
|
|
2. Go to Application > Local Storage
|
|
3. Find keys starting with `bluetooth_printer_`
|
|
4. Right-click and delete them
|
|
5. Refresh the page
|
|
6. Re-configure the printer
|
|
|
|
### Getting Help
|
|
|
|
If you continue to experience issues:
|
|
|
|
1. **Check Browser Console**: Look for error messages (F12 > Console)
|
|
2. **Verify Requirements**: Ensure all requirements are met (browser, HTTPS, hardware)
|
|
3. **Test with Different Printer**: Try with another bluetooth printer if available
|
|
4. **Test with Different Device**: Try on another tablet or computer
|
|
5. **Contact Support**: Provide the following information:
|
|
- Odoo version
|
|
- Browser name and version
|
|
- Printer model
|
|
- Error messages from console
|
|
- Steps to reproduce the issue
|
|
|
|
## Supported Printers
|
|
|
|
### Compatibility
|
|
|
|
This module supports **ESC/POS compatible bluetooth thermal printers**. ESC/POS (Epson Standard Code for Point of Sale) is the industry-standard command protocol for thermal printers.
|
|
|
|
### Verified Compatible Printers
|
|
|
|
The following printers have been tested and verified to work with this module:
|
|
|
|
| Printer Model | Paper Width | Bluetooth Version | Status |
|
|
|---------------|-------------|-------------------|--------|
|
|
| RPP02 | 58mm | 4.0+ | ✅ Fully Tested |
|
|
| Epson TM-P20 | 58mm | 4.0+ | ✅ Compatible |
|
|
| Epson TM-P80 | 80mm | 4.0+ | ✅ Compatible |
|
|
| Star Micronics SM-L200 | 58mm | 4.0+ | ✅ Compatible |
|
|
| Star Micronics SM-L300 | 80mm | 4.0+ | ✅ Compatible |
|
|
|
|
### Likely Compatible Printers
|
|
|
|
Most bluetooth thermal printers that support ESC/POS should work, including:
|
|
|
|
**Epson Models**:
|
|
- TM-P series (TM-P20, TM-P60, TM-P80)
|
|
- TM-m series with bluetooth
|
|
- TM-T series with bluetooth adapter
|
|
|
|
**Star Micronics Models**:
|
|
- SM-L series (SM-L200, SM-L300)
|
|
- SM-S series with bluetooth
|
|
- TSP series with bluetooth
|
|
|
|
**Citizen Models**:
|
|
- CMP series with bluetooth
|
|
- CT-S series with bluetooth
|
|
|
|
**Bixolon Models**:
|
|
- SPP-R series
|
|
- SPP-L series
|
|
|
|
**Generic ESC/POS Printers**:
|
|
- Most Chinese-manufactured ESC/POS bluetooth printers
|
|
- Printers marketed as "ESC/POS compatible"
|
|
|
|
### Printer Requirements
|
|
|
|
For a printer to work with this module, it must:
|
|
|
|
1. **Support Bluetooth**: Bluetooth 4.0 or higher
|
|
2. **Support ESC/POS**: Must understand ESC/POS command protocol
|
|
3. **Be Discoverable**: Must support bluetooth pairing/discovery
|
|
4. **Support Serial Port Profile**: Must support SPP (Serial Port Profile) or similar
|
|
|
|
### Checking Printer Compatibility
|
|
|
|
To verify if your printer is compatible:
|
|
|
|
1. **Check Specifications**: Look for "ESC/POS" or "ESC/POS compatible" in printer specifications
|
|
2. **Check Bluetooth**: Verify printer has bluetooth capability (not just USB)
|
|
3. **Test Pairing**: Try pairing with your device via device bluetooth settings
|
|
4. **Test Print**: Use the module's test print feature to verify functionality
|
|
|
|
### Unsupported Printers
|
|
|
|
The following types of printers are **NOT** supported:
|
|
|
|
- **WiFi-only printers**: Module requires bluetooth connection
|
|
- **USB-only printers**: Module requires wireless bluetooth connection
|
|
- **Proprietary protocol printers**: Printers that don't support ESC/POS
|
|
- **Inkjet/Laser printers**: Module is designed for thermal printers
|
|
- **Non-receipt printers**: Module is optimized for receipt printing
|
|
|
|
### Paper Specifications
|
|
|
|
Supported paper widths:
|
|
- **58mm**: Most common for mobile/portable printers (32 characters per line)
|
|
- **80mm**: Standard for counter-top printers (42-48 characters per line)
|
|
|
|
Paper type:
|
|
- **Thermal paper**: Required (no ink or ribbon needed)
|
|
- **BPA-free options**: Recommended for food service applications
|
|
|
|
### Adding Support for New Printers
|
|
|
|
If you have a printer that should be compatible but isn't working:
|
|
|
|
1. Verify the printer supports ESC/POS protocol
|
|
2. Check the printer's bluetooth implementation
|
|
3. Try different character set configurations
|
|
4. Test with the browser's Web Bluetooth API directly
|
|
5. Contact support with printer model and error details
|
|
|
|
### Printer Recommendations
|
|
|
|
For best results, we recommend:
|
|
|
|
**For Mobile/Portable Use**:
|
|
- RPP02 (budget-friendly, reliable)
|
|
- Epson TM-P20 (premium, very reliable)
|
|
- Star Micronics SM-L200 (compact, durable)
|
|
|
|
**For Counter-Top Use**:
|
|
- Epson TM-P80 (fast, reliable)
|
|
- Star Micronics SM-L300 (versatile, good quality)
|
|
|
|
**Key Features to Look For**:
|
|
- Bluetooth 4.0 or higher (better range and stability)
|
|
- Long battery life (for mobile printers)
|
|
- Fast print speed (50mm/s or higher)
|
|
- Auto-cutter (for clean receipt edges)
|
|
- Drop-in paper loading (for easy paper changes)
|
|
|
|
## Browser Compatibility
|
|
|
|
### Detailed Browser Support
|
|
|
|
The module relies on the Web Bluetooth API, which has varying support across browsers:
|
|
|
|
#### ✅ Fully Supported Browsers
|
|
|
|
**Google Chrome**
|
|
- **Desktop**: Version 56+ (Windows, macOS, Linux, Chrome OS)
|
|
- **Android**: Version 56+
|
|
- **Status**: Full support, recommended browser
|
|
- **Notes**: Best performance and stability
|
|
|
|
**Microsoft Edge**
|
|
- **Desktop**: Chromium-based versions (79+)
|
|
- **Status**: Full support
|
|
- **Notes**: Equivalent to Chrome, excellent compatibility
|
|
|
|
**Opera**
|
|
- **Desktop**: Version 43+
|
|
- **Android**: Version 43+
|
|
- **Status**: Full support
|
|
- **Notes**: Based on Chromium, works well
|
|
|
|
**Brave**
|
|
- **Desktop**: Latest versions
|
|
- **Status**: Full support
|
|
- **Notes**: Privacy-focused, Web Bluetooth enabled by default
|
|
|
|
#### ❌ Unsupported Browsers
|
|
|
|
**Mozilla Firefox**
|
|
- **Status**: Not supported
|
|
- **Reason**: Web Bluetooth API behind experimental flag
|
|
- **Workaround**: None - use Chrome or Edge instead
|
|
- **Future**: May be supported in future versions
|
|
|
|
**Apple Safari**
|
|
- **Status**: Not supported
|
|
- **Reason**: Web Bluetooth API not implemented
|
|
- **Workaround**: None - use Chrome or Edge instead
|
|
- **Future**: No announced plans for support
|
|
|
|
**Internet Explorer**
|
|
- **Status**: Not supported
|
|
- **Reason**: Legacy browser, no Web Bluetooth support
|
|
- **Workaround**: Use Edge instead
|
|
|
|
#### 📱 Mobile Browser Support
|
|
|
|
**Android**
|
|
- Chrome: ✅ Supported (version 56+)
|
|
- Firefox: ❌ Not supported
|
|
- Samsung Internet: ✅ Supported (version 6.4+)
|
|
- Opera: ✅ Supported
|
|
|
|
**iOS/iPadOS**
|
|
- Safari: ❌ Not supported
|
|
- Chrome: ❌ Not supported (uses Safari engine)
|
|
- Firefox: ❌ Not supported (uses Safari engine)
|
|
- **Note**: No iOS browsers support Web Bluetooth due to Apple's restrictions
|
|
|
|
### Checking Browser Compatibility
|
|
|
|
To verify if your browser supports Web Bluetooth:
|
|
|
|
1. Open your browser
|
|
2. Navigate to: `chrome://flags` (Chrome/Edge) or `opera://flags` (Opera)
|
|
3. Search for "Web Bluetooth"
|
|
4. Verify it's enabled
|
|
|
|
Or test directly:
|
|
1. Open browser console (F12)
|
|
2. Type: `navigator.bluetooth`
|
|
3. If it returns an object, Web Bluetooth is available
|
|
4. If it returns `undefined`, Web Bluetooth is not supported
|
|
|
|
### Browser Configuration
|
|
|
|
**Chrome/Edge**:
|
|
- Web Bluetooth is enabled by default
|
|
- No additional configuration needed
|
|
- Ensure site has bluetooth permissions
|
|
|
|
**Opera**:
|
|
- Web Bluetooth is enabled by default
|
|
- No additional configuration needed
|
|
|
|
**Brave**:
|
|
- Web Bluetooth is enabled by default
|
|
- Check Shields settings if issues occur
|
|
|
|
### Platform-Specific Notes
|
|
|
|
**Windows**
|
|
- Requires Windows 10 version 1703 (Creators Update) or later
|
|
- Bluetooth adapter must support Bluetooth 4.0+
|
|
- Works with built-in or USB bluetooth adapters
|
|
|
|
**macOS**
|
|
- Requires macOS 10.12 (Sierra) or later
|
|
- Works with built-in bluetooth
|
|
- External bluetooth adapters may have limited support
|
|
|
|
**Linux**
|
|
- Requires BlueZ 5.41 or later
|
|
- Chrome must be run with `--enable-features=WebBluetooth` flag (usually default)
|
|
- May require additional bluetooth permissions
|
|
|
|
**Chrome OS**
|
|
- Full support out of the box
|
|
- Excellent for POS deployments on Chromebooks
|
|
|
|
**Android**
|
|
- Requires Android 6.0 (Marshmallow) or later
|
|
- Location permission required for bluetooth scanning
|
|
- Works well on tablets for POS use
|
|
|
|
### HTTPS Requirement
|
|
|
|
Web Bluetooth API requires a secure context (HTTPS) with these exceptions:
|
|
|
|
**Allowed without HTTPS**:
|
|
- `localhost`
|
|
- `127.0.0.1`
|
|
- `*.localhost` (e.g., `pos.localhost`)
|
|
|
|
**Requires HTTPS**:
|
|
- All other domains and IP addresses
|
|
- Production deployments
|
|
- Remote access
|
|
|
|
**Getting HTTPS**:
|
|
- Use Let's Encrypt for free SSL certificates
|
|
- Use a reverse proxy (nginx, Apache) with SSL
|
|
- Use Odoo's built-in SSL support
|
|
|
|
## Technical Details
|
|
|
|
### Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Browser (Client) │
|
|
│ │
|
|
│ ┌────────────────┐ ┌──────────────────┐ ┌─────────────┐ │
|
|
│ │ POS Interface │ │ Connection Status│ │ Config UI │ │
|
|
│ └────────┬───────┘ └────────┬─────────┘ └──────┬──────┘ │
|
|
│ │ │ │ │
|
|
│ └───────────────────┼────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────────────────────────▼──────────────────────────┐ │
|
|
│ │ Bluetooth Printer Manager Service │ │
|
|
│ │ - Device scanning & pairing │ │
|
|
│ │ - Connection management │ │
|
|
│ │ - Auto-reconnection with backoff │ │
|
|
│ │ - Status monitoring │ │
|
|
│ └────────────────┬──────────────────┬──────────────────┘ │
|
|
│ │ │ │
|
|
│ ┌────────────────▼────────┐ ┌──────▼──────────────────┐ │
|
|
│ │ ESC/POS Generator │ │ Local Storage Manager │ │
|
|
│ │ - Command generation │ │ - Config persistence │ │
|
|
│ │ - Text encoding │ │ - Device-specific keys │ │
|
|
│ │ - Receipt formatting │ │ - Multi-device support │ │
|
|
│ └────────────────┬────────┘ └─────────────────────────┘ │
|
|
│ │ │
|
|
└───────────────────┼──────────────────────────────────────────┘
|
|
│
|
|
│ Web Bluetooth API
|
|
│ (ESC/POS Commands)
|
|
▼
|
|
┌──────────────────────┐
|
|
│ Bluetooth Thermal │
|
|
│ Printer │
|
|
│ (ESC/POS Device) │
|
|
└──────────────────────┘
|
|
```
|
|
|
|
### Component Architecture
|
|
|
|
**Client-Side Only**:
|
|
- All bluetooth communication happens in the browser
|
|
- No server-side components required
|
|
- No additional drivers or services needed
|
|
- Direct browser-to-printer communication
|
|
|
|
**Key Components**:
|
|
|
|
1. **Bluetooth Printer Manager** (`bluetooth_printer_manager.js`)
|
|
- Manages device discovery and pairing
|
|
- Maintains active connections
|
|
- Handles reconnection logic
|
|
- Provides status updates
|
|
|
|
2. **ESC/POS Generator** (`escpos_generator.js`)
|
|
- Converts receipt data to ESC/POS commands
|
|
- Handles text formatting and encoding
|
|
- Generates printer control commands
|
|
|
|
3. **Local Storage Manager** (`storage_manager.js`)
|
|
- Stores device-specific configurations
|
|
- Uses composite keys (device_id + pos_config_id)
|
|
- Handles configuration persistence
|
|
|
|
4. **Configuration UI** (`bluetooth_printer_config.js`)
|
|
- Device scanning interface
|
|
- Printer selection and pairing
|
|
- Test print functionality
|
|
|
|
5. **Connection Status Widget** (`connection_status_widget.js`)
|
|
- Real-time status display
|
|
- Connection state monitoring
|
|
- User notifications
|
|
|
|
### Data Flow
|
|
|
|
**Print Flow**:
|
|
```
|
|
Sale Completed
|
|
↓
|
|
Receipt Data Generated (Odoo Format)
|
|
↓
|
|
ESC/POS Generator Converts to Commands
|
|
↓
|
|
Bluetooth Manager Sends to Printer
|
|
↓
|
|
Printer Prints Receipt
|
|
```
|
|
|
|
**Connection Flow**:
|
|
```
|
|
POS Session Start
|
|
↓
|
|
Load Configuration from Local Storage
|
|
↓
|
|
Attempt Bluetooth Connection
|
|
↓
|
|
Connection Success? ─No→ Retry (3x with backoff)
|
|
↓ Yes ↓
|
|
Connected State Fallback Mode
|
|
```
|
|
|
|
### Storage Schema
|
|
|
|
**Local Storage Key Format**:
|
|
```
|
|
bluetooth_printer_{device_id}_{pos_config_id}
|
|
```
|
|
|
|
**Configuration Object**:
|
|
```javascript
|
|
{
|
|
deviceId: "ABC123...", // Bluetooth device ID
|
|
deviceName: "RPP02-1234", // Human-readable name
|
|
macAddress: "00:11:22:33:44:55", // Bluetooth MAC
|
|
lastConnected: 1234567890, // Unix timestamp
|
|
settings: {
|
|
characterSet: "CP437", // Character encoding
|
|
paperWidth: 32, // Characters per line
|
|
autoReconnect: true, // Enable auto-reconnect
|
|
timeout: 10000 // Print timeout (ms)
|
|
}
|
|
}
|
|
```
|
|
|
|
### ESC/POS Protocol
|
|
|
|
**Command Structure**:
|
|
- Commands are byte sequences sent to the printer
|
|
- Start with escape characters (ESC=0x1B, GS=0x1D)
|
|
- Followed by command codes and parameters
|
|
|
|
**Common Commands**:
|
|
```javascript
|
|
INIT: [0x1B, 0x40] // Initialize printer
|
|
ALIGN_LEFT: [0x1B, 0x61, 0x00] // Left align text
|
|
ALIGN_CENTER: [0x1B, 0x61, 0x01] // Center align text
|
|
ALIGN_RIGHT: [0x1B, 0x61, 0x02] // Right align text
|
|
BOLD_ON: [0x1B, 0x45, 0x01] // Enable bold
|
|
BOLD_OFF: [0x1B, 0x45, 0x00] // Disable bold
|
|
CUT_PAPER: [0x1D, 0x56, 0x00] // Cut paper
|
|
LINE_FEED: [0x0A] // Feed one line
|
|
```
|
|
|
|
### Security Considerations
|
|
|
|
**User Permissions**:
|
|
- Web Bluetooth requires HTTPS (except localhost)
|
|
- User must explicitly grant bluetooth access via browser dialog
|
|
- Pairing requires user interaction (cannot be automated)
|
|
- Permissions are per-origin (domain-specific)
|
|
|
|
**Data Privacy**:
|
|
- Printer configurations stored locally in browser
|
|
- No configuration data sent to Odoo server
|
|
- MAC addresses stored locally only
|
|
- Receipt data transmitted only to paired printer
|
|
|
|
**Access Control**:
|
|
- Only paired devices can connect
|
|
- Bluetooth pairing provides device authentication
|
|
- No unauthorized access to printer possible
|
|
|
|
### Performance Characteristics
|
|
|
|
**Connection Times**:
|
|
- Initial pairing: 2-5 seconds
|
|
- Auto-connection: 1-3 seconds
|
|
- Reconnection: 1-7 seconds (with backoff)
|
|
|
|
**Print Times**:
|
|
- Small receipt (5 items): 1-2 seconds
|
|
- Medium receipt (20 items): 2-4 seconds
|
|
- Large receipt (50+ items): 4-8 seconds
|
|
- Times vary by printer model and bluetooth quality
|
|
|
|
**Resource Usage**:
|
|
- Minimal CPU usage (< 1% during printing)
|
|
- Minimal memory usage (< 10MB)
|
|
- No server resources required
|
|
- Local storage: < 1KB per configuration
|
|
|
|
### Error Handling Strategy
|
|
|
|
**Graceful Degradation**:
|
|
1. Primary: Bluetooth thermal printer
|
|
2. Fallback: Browser print dialog
|
|
3. Guarantee: Sale always completes
|
|
|
|
**Retry Logic**:
|
|
- Exponential backoff: 1s, 2s, 4s
|
|
- Maximum 3 attempts
|
|
- Automatic fallback after failures
|
|
|
|
**Timeout Handling**:
|
|
- 10-second timeout for print operations
|
|
- Automatic fallback on timeout
|
|
- Connection cleanup on timeout
|
|
|
|
### Odoo Integration
|
|
|
|
**Module Structure**:
|
|
```
|
|
pos_bluetooth_thermal_printer/
|
|
├── __init__.py
|
|
├── __manifest__.py
|
|
├── models/
|
|
│ ├── __init__.py
|
|
│ └── pos_config.py # Backend model extension
|
|
├── views/
|
|
│ └── pos_config_views.xml # Configuration UI
|
|
├── security/
|
|
│ └── ir.model.access.csv # Access rights
|
|
└── static/src/
|
|
├── js/ # JavaScript components
|
|
├── xml/ # QWeb templates
|
|
└── css/ # Stylesheets
|
|
```
|
|
|
|
**Asset Loading**:
|
|
- Assets loaded via `point_of_sale._assets_pos` bundle
|
|
- Automatic loading when POS session starts
|
|
- No manual script inclusion needed
|
|
|
|
**Backend Extension**:
|
|
- Extends `pos.config` model
|
|
- Adds `bluetooth_printer_enabled` boolean field
|
|
- No database schema changes for printer configurations
|
|
- All printer data stored client-side
|
|
|
|
### Development and Testing
|
|
|
|
**Testing Framework**:
|
|
- Jest for unit tests
|
|
- fast-check for property-based tests
|
|
- Manual testing with real hardware
|
|
|
|
**Test Coverage**:
|
|
- ESC/POS command generation
|
|
- Storage operations
|
|
- Connection management
|
|
- Error handling
|
|
- Fallback behavior
|
|
|
|
**Development Tools**:
|
|
- Browser DevTools for debugging
|
|
- Web Bluetooth API testing
|
|
- Console logging for diagnostics
|
|
|
|
## License
|
|
|
|
LGPL-3
|
|
|
|
## Author
|
|
|
|
Suherdy Yacob
|
|
|
|
## Version
|
|
|
|
18.0.1.0.0
|