Skip to content

BLUETOOTH_IMAGE_TRANSFER.md

Latest commit

 

History

History
184 lines (141 loc) · 5.93 KB

BLUETOOTH_IMAGE_TRANSFER.md

File metadata and controls

184 lines (141 loc) · 5.93 KB

Bluetooth Image Transfer Guide

Overview

The BlueQ system now supports transferring images over the Bluetooth mesh network! Images are encoded using Base64 and sent in chunks to ensure reliable delivery over Bluetooth.

How It Works

Protocol

  1. Image Encoding: Images are Base64 encoded for safe transmission
  2. Chunking: Large images are split into manageable chunks (default 800 bytes each)
  3. Message Types:
    • IMG_START: Announces the start of an image transfer
    • IMG_CHUNK: Contains a piece of the Base64-encoded image
    • IMG_END: Signals completion and includes a checksum for verification

Message Format

[ID:sender:recipient:IMG_START] filename.ext|chunk_count|file_size|checksum
[ID:sender:recipient:IMG_CHUNK] chunk_index|base64_data
[ID:sender:recipient:IMG_END] filename.ext|checksum

Features

✅ Automatic chunking for images of any size
✅ Integrity verification using MD5 checksums
✅ Progress tracking during transfer
✅ Error handling for incomplete transfers
✅ Web interface integration - images sent via web are also transmitted over Bluetooth
✅ Duplicate detection to prevent message duplication

Usage

Via Web Interface

  1. Open the BlueQ web app
  2. Select a contact
  3. Click the image upload button (📸)
  4. Select your image file (PNG or JPEG, max 5MB)
  5. The image will be sent via the web interface AND the Bluetooth mesh

Via API

# Send image via Bluetooth
curl -X POST http://localhost:5000/api/bluetooth/send_image \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "destination": "RecipientName",
    "image_path": "/path/to/image.jpg"
  }'

Direct Bluetooth Client

If you're using the Python Bluetooth client directly:

from bluetooth_image_protocol import BluetoothImageTransfer

# Initialize
transfer = BluetoothImageTransfer()

# Prepare image for sending
chunks = transfer.prepare_image_for_transfer(
    "photo.jpg", 
    "YourName", 
    "RecipientName"
)

# Send each chunk over your Bluetooth socket
for chunk in chunks:
    socket.send(f"{chunk}\n".encode())

File Size Recommendations

Image Size Estimated Transfer Time* Recommended Use
< 100KB 5-15 seconds ✅ Profile pictures, small photos
100KB-500KB 30-90 seconds ⚠️ Medium photos (compressed recommended)
500KB-1MB 2-5 minutes ⚠️ Large photos (use sparingly)
> 1MB 5+ minutes ❌ Not recommended over Bluetooth

*Transfer times depend on Bluetooth connection quality and mesh network topology

Supported Formats

  • PNG - Recommended for graphics with transparency
  • JPEG/JPG - Recommended for photos (naturally compressed)
  • GIF - Supported but animated GIFs will be static
  • WEBP - Supported in web interface

Performance Tips

For Best Results:

  1. Compress images before sending (aim for < 200KB)
  2. Use JPEG for photos (better compression than PNG)
  3. Send during stable connections (avoid during mesh topology changes)
  4. Send one image at a time (don't queue multiple large transfers)

Image Compression Tools:

# Using ImageMagick (Linux/Mac)
convert original.jpg -quality 80 -resize 800x600 compressed.jpg

# Using Python (PIL)
from PIL import Image
img = Image.open('original.jpg')
img = img.resize((800, 600), Image.Lanczos)
img.save('compressed.jpg', 'JPEG', quality=80)

Troubleshooting

Image Transfer Failed

  • Check that both sender and receiver are connected to the mesh
  • Verify the image file exists and is readable
  • Try with a smaller image first
  • Check Bluetooth connection stability

Incomplete Transfer

  • The system will automatically detect missing chunks
  • Transfers will timeout and cleanup after failed attempts
  • Check the console logs for specific error messages

Slow Transfer

  • Large images take time - this is normal for Bluetooth
  • Reduce image size for faster transfers
  • Ensure stable mesh connections

Technical Details

Protocol Specifications

  • Encoding: Base64 (RFC 4648)
  • Checksum: MD5 hash (8 characters)
  • Max chunk size: 800 bytes (configurable)
  • Supported file size: Up to 5MB (web interface limit)

Error Handling

  • Checksum verification prevents corruption
  • Missing chunk detection and reporting
  • Automatic cleanup of incomplete transfers
  • Graceful fallback for protocol errors

Security Notes

  • Images are transmitted in Base64 (not encrypted)
  • Consider the privacy implications of mesh networking
  • Images are stored locally on receiving devices
  • No authentication is performed on image transfers

Integration with Web App

The image transfer feature is fully integrated with the existing BlueQ web interface:

  1. Dual Transmission: Images sent via web are also transmitted over Bluetooth
  2. Unified Storage: All images (web and Bluetooth) are stored in the same location
  3. Message History: Bluetooth-received images appear in chat history
  4. Progress Indication: Transfer progress is logged in the console

Testing

Use the included test script to verify functionality:

# Test with a specific image
python3 test_image_transfer.py path/to/your/image.jpg

# Test with auto-generated image (requires PIL)
python3 test_image_transfer.py

Future Enhancements

Potential improvements for future versions:

  • 📱 Compression: Automatic image compression before transfer
  • 🔐 Encryption: End-to-end encryption for sensitive images
  • 📊 Progress UI: Real-time transfer progress in web interface
  • 🔄 Retry Logic: Automatic retry of failed chunks
  • 📈 Statistics: Transfer speed and success rate tracking
  • 🎯 Smart Routing: Choose optimal mesh path for large transfers

This feature transforms BlueQ from a text-only mesh messenger into a multimedia communication platform, all without requiring internet connectivity!