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

   cp -r pos_bluetooth_thermal_printer /path/to/odoo/addons/
   

2. Restart the Odoo server

   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:

   [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:

{
  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:

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