Skip to content

About

Offline peer-to-peer messaging and file transfer mobile app for Android built with Flutter, Dart, RFCOMM sockets, and SQLite.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BluetoothChat — Offline Peer-to-Peer Android Messenger

Platform Framework Language Protocol Database Web Showcase

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.


Executive Overview & Problem Statement

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) with neverForLocation flags and legacy location fallbacks for older devices.

Bluetooth Protocol & Framing Architecture

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.

1. Newline-Delimited Framing

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.

2. Binary Chunking Protocol

For transferring photos and files:

  1. Handshake Header: Sender transmits metadata payload (filename, file size in bytes, total chunks count, SHA-256 hash).
  2. Chunk Streaming: File bytes are partitioned into 4KB segments encoded as base64 or raw binary packets with sequence indices (chunk_index / total_chunks).
  3. Reassembly & Checksum Verification: Receiver reassembles binary chunks in memory/temporary cache and validates the final SHA-256 checksum before writing to persistent storage.

Source Code Architecture

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

Running on Physical Android Devices

Prerequisites

  • 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.

Setup Instructions

# 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>

Building a Release APK

cd flutter_bluetooth_chat
flutter build apk --release

# The compiled APK is located at:
# flutter_bluetooth_chat/build/app/outputs/flutter-apk/app-release.apk

Interactive Web Showcase & Presentation

To 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:3000

Academic Project Documentation

This 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.

Author & Contact

Muhammad Talha


License

This project is licensed under the MIT License — see repository for details.

About

Offline peer-to-peer messaging and file transfer mobile app for Android built with Flutter, Dart, RFCOMM sockets, and SQLite.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages