permissionlesstech/bitchat-android
1
0
Fork 0
mirror of https://github.com/permissionlesstech/bitchat-android.git synced 2026-07-25 11:45:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
callebtc
2025-07-08 22:26:19 +02:00
parent d6a4e122b4
commit febcc8e2b2
1 changed files with 184 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+184 -48
View File
@@ -1,62 +1,99 @@
![ChatGPT Image Jul 5, 2025 at 06_07_31 PM](https://github.com/user-attachments/assets/2660f828-49c7-444d-beca-d8b01854667a) # bitchat for Android
# bitchat
A secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. No internet required, no servers, no phone numbers - just pure encrypted communication. A secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. No internet required, no servers, no phone numbers - just pure encrypted communication.
This is the **Android port** of the original [bitchat iOS app](https://github.com/jackjackbits/bitchat), maintaining 100% protocol compatibility for cross-platform communication.
## About This Port
This Android implementation maintains full protocol compatibility with the original iOS version, allowing seamless communication between iPhone and Android users in the same mesh network. All core features including encryption, channels, private messaging, and mesh networking work identically across platforms.
**Original iOS Version**: [github.com/jackjackbits/bitchat](https://github.com/jackjackbits/bitchat)
## License ## License
This project is released into the public domain. See the [LICENSE](LICENSE) file for details. This project is released into the public domain. See the [LICENSE](LICENSE) file for details.
## Features ## Features
- **Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE - **✅ Cross-Platform Compatible**: Full protocol compatibility with iOS bitchat
- **End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages - **✅ Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE
- **Channel-Based Chats**: Topic-based group messaging with optional password protection - **✅ End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages
- **Store & Forward**: Messages cached for offline peers and delivered when they reconnect - **✅ Channel-Based Chats**: Topic-based group messaging with optional password protection
- **Privacy First**: No accounts, no phone numbers, no persistent identifiers - **✅ Store & Forward**: Messages cached for offline peers and delivered when they reconnect
- **IRC-Style Commands**: Familiar `/join`, `/msg`, `/who` style interface - **✅ Privacy First**: No accounts, no phone numbers, no persistent identifiers
- **Message Retention**: Optional channel-wide message saving controlled by channel owners - **✅ IRC-Style Commands**: Familiar `/join`, `/msg`, `/who` style interface
- **Universal App**: Native support for iOS and macOS - **✅ Message Retention**: Optional channel-wide message saving controlled by channel owners
- **Cover Traffic**: Timing obfuscation and dummy messages for enhanced privacy - **✅ Emergency Wipe**: Triple-tap logo to instantly clear all data
- **Emergency Wipe**: Triple-tap to instantly clear all data - **✅ Modern Android UI**: Jetpack Compose with Material Design 3
- **Performance Optimizations**: LZ4 message compression, adaptive battery modes, and optimized networking - **✅ Dark/Light Themes**: Terminal-inspired aesthetic matching iOS version
- **✅ Battery Optimization**: Adaptive scanning and power management
## Setup ## Android Setup
### Option 1: Using XcodeGen (Recommended) ### Prerequisites
1. Install XcodeGen if you haven't already: - **Android Studio**: Arctic Fox (2020.3.1) or newer
- **Android SDK**: API level 26 (Android 8.0) or higher
- **Kotlin**: 1.8.0 or newer
- **Gradle**: 7.0 or newer
### Build Instructions
1. **Clone the repository:**
```bash ```bash
brew install xcodegen git clone https://github.com/your-username/bitchat-android.git
cd bitchat-android
``` ```
2. Generate the Xcode project: 2. **Open in Android Studio:**
```bash ```bash
cd bitchat # Open Android Studio and select "Open an Existing Project"
xcodegen generate # Navigate to the bitchat-android directory
``` ```
3. Open the generated project: 3. **Build the project:**
```bash ```bash
open bitchat.xcodeproj ./gradlew build
``` ```
### Option 2: Using Swift Package Manager 4. **Install on device:**
1. Open the project in Xcode:
```bash ```bash
cd bitchat ./gradlew installDebug
open Package.swift
``` ```
2. Select your target device and run ### Development Build
### Option 3: Manual Xcode Project For development builds with debugging enabled:
1. Open Xcode and create a new iOS/macOS App ```bash
2. Copy all Swift files from the `bitchat` directory into your project ./gradlew assembleDebug
3. Update Info.plist with Bluetooth permissions adb install -r app/build/outputs/apk/debug/app-debug.apk
4. Set deployment target to iOS 16.0 / macOS 13.0 ```
### Release Build
For production releases:
```bash
./gradlew assembleRelease
```
## Android-Specific Requirements
### Permissions
The app requires the following permissions (automatically requested):
- **Bluetooth**: Core BLE functionality
- **Location**: Required for BLE scanning on Android
- **Notifications**: Message alerts and background updates
### Hardware Requirements
- **Bluetooth LE (BLE)**: Required for mesh networking
- **Android 8.0+**: API level 26 minimum
- **RAM**: 2GB recommended for optimal performance
## Usage ## Usage
@@ -76,11 +113,22 @@ This project is released into the public domain. See the [LICENSE](LICENSE) file
### Getting Started ### Getting Started
1. Launch bitchat on your device 1. **Install the app** on your Android device (requires Android 8.0+)
2. Set your nickname (or use the auto-generated one) 2. **Grant permissions** for Bluetooth and location when prompted
3. You'll automatically connect to nearby peers 3. **Launch bitchat** - it will auto-start mesh networking
4. Join a channel with `/j #general` or start chatting in public 4. **Set your nickname** or use the auto-generated one
5. Messages relay through the mesh network to reach distant peers 5. **Connect automatically** to nearby iOS and Android bitchat users
6. **Join a channel** with `/j #general` or start chatting in public
7. **Messages relay** through the mesh network to reach distant peers
### Android UI Features
- **Jetpack Compose UI**: Modern Material Design 3 interface
- **Dark/Light Themes**: Terminal-inspired aesthetic matching iOS
- **Haptic Feedback**: Vibrations for interactions and notifications
- **Adaptive Layout**: Optimized for various Android screen sizes
- **Message Status**: Real-time delivery and read receipts
- **RSSI Indicators**: Signal strength colors for each peer
### Channel Features ### Channel Features
@@ -140,17 +188,105 @@ bitchat uses an efficient binary protocol optimized for Bluetooth LE:
- Store-and-forward for offline message delivery - Store-and-forward for offline message delivery
- Adaptive duty cycling for battery optimization - Adaptive duty cycling for battery optimization
For detailed protocol documentation, see the [Technical Whitepaper](WHITEPAPER.md). ### Android-Specific Optimizations
- **Coroutine Architecture**: Asynchronous operations for mesh networking
- **Kotlin Coroutines**: Thread-safe concurrent mesh operations
- **EncryptedSharedPreferences**: Secure storage for user settings
- **Lifecycle-Aware**: Proper handling of Android app lifecycle
- **Battery Optimization**: Foreground service and adaptive scanning
## Building for Production ## Android Technical Architecture
1. Set your development team in project settings ### Core Components
2. Configure code signing
3. Archive and distribute through App Store or TestFlight
## Android Compatibility 1. **BitchatApplication.kt**: Application-level initialization and dependency injection
2. **MainActivity.kt**: Main activity handling permissions and UI hosting
3. **ChatViewModel.kt**: MVVM pattern managing app state and business logic
4. **BluetoothMeshService.kt**: Core BLE mesh networking (central + peripheral roles)
5. **EncryptionService.kt**: Cryptographic operations using BouncyCastle
6. **BinaryProtocol.kt**: Binary packet encoding/decoding matching iOS format
7. **ChatScreen.kt**: Jetpack Compose UI with Material Design 3
The protocol is designed to be platform-agnostic. An Android client can be built using: ### Dependencies
- Bluetooth LE APIs
- Same packet structure and encryption - **Jetpack Compose**: Modern declarative UI
- Compatible service/characteristic UUIDs - **BouncyCastle**: Cryptographic operations (X25519, Ed25519, AES-GCM)
- **Nordic BLE Library**: Reliable Bluetooth LE operations
- **Kotlin Coroutines**: Asynchronous programming
- **LZ4**: Message compression (when enabled)
- **EncryptedSharedPreferences**: Secure local storage
### Binary Protocol Compatibility
The Android implementation maintains 100% binary protocol compatibility with iOS:
- **Header Format**: Identical 13-byte header structure
- **Packet Types**: Same message types and routing logic
- **Encryption**: Identical cryptographic algorithms and key exchange
- **UUIDs**: Same Bluetooth service and characteristic identifiers
- **Fragmentation**: Compatible message fragmentation for large content
## Publishing to Google Play
### Preparation
1. **Update version information:**
```kotlin
// In app/build.gradle.kts
defaultConfig {
versionCode = 2 // Increment for each release
versionName = "1.1.0" // User-visible version
}
```
2. **Create a signed release build:**
```bash
./gradlew assembleRelease
```
3. **Generate app bundle (recommended for Play Store):**
```bash
./gradlew bundleRelease
```
### Play Store Requirements
- **Target API**: Latest Android API (currently 34)
- **Privacy Policy**: Required for apps requesting sensitive permissions
- **App Permissions**: Justify Bluetooth and location usage
- **Content Rating**: Complete questionnaire for age-appropriate content
### Distribution
- **Google Play Store**: Main distribution channel
- **F-Droid**: For open-source distribution
- **Direct APK**: For testing and development
## Cross-Platform Communication
This Android port enables seamless communication with the original iOS bitchat app:
- **iPhone ↔ Android**: Full bidirectional messaging
- **Mixed Groups**: iOS and Android users in same channels
- **Feature Parity**: All commands and encryption work across platforms
- **Protocol Sync**: Identical message format and routing behavior
**iOS Version**: For iPhone/iPad users, get the original bitchat at [github.com/jackjackbits/bitchat](https://github.com/jackjackbits/bitchat)
## Contributing
Contributions are welcome! Key areas for enhancement:
1. **Performance**: Battery optimization and connection reliability
2. **UI/UX**: Additional Material Design 3 features
3. **Security**: Enhanced cryptographic features
4. **Testing**: Unit and integration test coverage
5. **Documentation**: API documentation and development guides
## Support & Issues
- **Bug Reports**: [Create an issue](../../issues) with device info and logs
- **Feature Requests**: [Start a discussion](../../discussions)
- **Security Issues**: Email security concerns privately
- **iOS Compatibility**: Cross-reference with [original iOS repo](https://github.com/jackjackbits/bitchat)
For iOS-specific issues, please refer to the [original iOS bitchat repository](https://github.com/jackjackbits/bitchat).