BluetoothChat is a complete, production-grade, 100% offline peer-to-peer messaging and media transfer mobile application for Android. Built with Flutter, Dart, and Bluetooth Classic (RFCOMM Sockets), it allows two Android devices to communicate, exchange messages, and transfer files without internet access, cellular networks, or Wi-Fi routers.
In areas with cellular outages, underground facilities, natural disasters, or remote locations, standard messengers (WhatsApp, Telegram) become completely non-functional.
BluetoothChat establishes a direct hardware-to-hardware RFCOMM socket stream over the standard Serial Port Profile (SPP):
- 100% Offline Resilience: Operates without any cellular data, local Wi-Fi router, or external servers.
- Bi-directional RFCOMM Streams: Direct socket communication using standard SPP UUID
00001101-0000-1000-8000-00805F9B34FB. - Stream Framing Architecture: Implements newline-delimited JSON (
\n) tokenization to prevent socket fragmentation and TCP-style packet concatenation crashes. - Chunked Binary File Transfer: Slices images and media into 4KB data chunks with SHA-256 integrity checksums, reassembly verification, and real-time transfer progress bars.
- Local SQLite Persistence: Encrypted local database (
sqflite) storing contacts, conversation threads, message delivery receipts, and timestamps. - Android 12+ Permission Compliance: Adheres to modern Android Nearby Devices permissions (
BLUETOOTH_SCAN,BLUETOOTH_CONNECT,BLUETOOTH_ADVERTISE) withneverForLocationflags and legacy location fallbacks for older devices.
RFCOMM sockets provide an unformatted raw byte stream. Without protocol framing, messages sent in rapid succession merge into a single buffer, leading to JSON parse exceptions.
Every payload transmitted across the RFCOMM stream is suffixed with a newline character \n:
{"type":"TEXT","id":"msg-101","content":"Hello World","sender":"DeviceA"}\n
The incoming receiver stream runs through a continuous stream buffer that yields tokens only upon encountering \n, guaranteeing 100% message isolation.
For transferring photos and files:
- Handshake Header: Sender transmits metadata payload (filename, file size in bytes, total chunks count, SHA-256 hash).
- Chunk Streaming: File bytes are partitioned into 4KB segments encoded as base64 or raw binary packets with sequence indices (
chunk_index/total_chunks). - Reassembly & Checksum Verification: Receiver reassembles binary chunks in memory/temporary cache and validates the final SHA-256 checksum before writing to persistent storage.
BluetoothChat/
├── flutter_bluetooth_chat/ # Production Flutter Mobile Codebase
│ ├── android/ # Native Android configuration & Manifest (API 21-35)
│ ├── ios/ # iOS Runner files
│ ├── lib/
│ │ ├── main.dart # Application entry point & service initialization
│ │ ├── app/ # App routing, navigation, and Material 3 theme
│ │ ├── core/ # Constants, exceptions, permission handlers & utilities
│ │ ├── models/ # Data models (Message, Device, Transfer, Conversation)
│ │ ├── database/ # SQLite DB helper & Data Access Objects (DAOs)
│ │ ├── services/ # RFCOMM client/server sockets & protocol framing
│ │ ├── providers/ # State management (BluetoothProvider, ChatProvider)
│ │ ├── screens/ # Splash, Discovery, Host, Chat, Settings, About
│ │ └── widgets/ # Message bubbles, transfer progress indicators
│ ├── test/ # Unit tests for framing, models, and chunking
│ │ ├── file_transfer_chunking_test.dart
│ │ ├── message_protocol_test.dart
│ │ └── models_test.dart
│ └── pubspec.yaml # Production dependencies & assets
├── src/ # Interactive React 19 + Vite Web Application & Showcase
│ ├── App.tsx # Web emulator and interactive presentation UI
│ └── main.tsx # Web entry point
├── distribution/ # App Store & Play Store distribution assets
│ ├── play_store/ # Data safety form, privacy policy, release notes
│ └── app_store/ # iOS privacy nutrition labels & review notes
├── FEATURE_COMPLETION_MATRIX.md # Comprehensive feature verification matrix
├── PROJECT_REPORT.md # 22-section academic project report (SRS, UML, DFD)
├── TEST_REPORT.md # 15 physical device test cases & results
└── VIVA_PREPARATION.md # In-depth viva voce examination study guide
- Flutter SDK: Version 3.19.0 or higher (flutter.dev)
- Android Studio: With Android SDK Command-line Tools and Platform 34/35
- Java JDK: OpenJDK 17
- Two Physical Android Devices: With Bluetooth turned ON and Developer Options / USB Debugging enabled.
# 1. Navigate to Flutter project directory
cd flutter_bluetooth_chat
# 2. Install dependencies
flutter pub get
# 3. Execute automated unit tests
flutter test
# 4. Inspect connected devices
flutter devices
# 5. Launch Host on Phone 1
flutter run -d <DEVICE_ID_1>
# 6. Launch Client on Phone 2 (in a separate terminal)
flutter run -d <DEVICE_ID_2>cd flutter_bluetooth_chat
flutter build apk --release
# The compiled APK is located at:
# flutter_bluetooth_chat/build/app/outputs/flutter-apk/app-release.apkTo run the interactive React/Vite demonstration and project overview in a web browser:
# Navigate to repository root
cd BluetoothChat
# Install dependencies
npm install
# Start local Vite server
npm run dev
# Open in browser: http://localhost:3000This repository includes a complete academic documentation package prepared according to university standards:
FEATURE_COMPLETION_MATRIX.md: Detailed status matrix mapping requirements to source files and test verification.PROJECT_REPORT.md: Academic report covering problem statement, literature review, and UML diagrams (Use-Case, Sequence, Activity, DFD).VIVA_PREPARATION.md: Comprehensive viva defense guide covering RFCOMM sockets, SPP, framing, Android 12 permissions, and database design.TEST_REPORT.md: Real-device verification logs covering distance, packet loss, and transfer benchmarks.
Muhammad Talha
- GitHub: @MTLab1122
- LinkedIn: Muhammad Talha
- Email: muhammadtalhapro1@gmail.com
- Portfolio: talha-portfolio-gules.vercel.app
This project is licensed under the MIT License — see repository for details.