update readme

2026-07-24 22:25:19 +00:00 · 2025-07-08 22:26:19 +02:00
parent d6a4e122b4
commit febcc8e2b2
1 changed files with 184 additions and 48 deletions
@@ -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
+# bitchat for Android

 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

 This project is released into the public domain. See the [LICENSE](LICENSE) file for details.

 ## Features

- **Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE
- **End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages
- **Channel-Based Chats**: Topic-based group messaging with optional password protection
- **Store & Forward**: Messages cached for offline peers and delivered when they reconnect
- **Privacy First**: No accounts, no phone numbers, no persistent identifiers
- **IRC-Style Commands**: Familiar `/join`, `/msg`, `/who` style interface
- **Message Retention**: Optional channel-wide message saving controlled by channel owners
- **Universal App**: Native support for iOS and macOS
- **Cover Traffic**: Timing obfuscation and dummy messages for enhanced privacy
- **Emergency Wipe**: Triple-tap to instantly clear all data
- **Performance Optimizations**: LZ4 message compression, adaptive battery modes, and optimized networking
+- **✅ Cross-Platform Compatible**: Full protocol compatibility with iOS bitchat
+- **✅ Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE
+- **✅ End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages
+- **✅ Channel-Based Chats**: Topic-based group messaging with optional password protection
+- **✅ Store & Forward**: Messages cached for offline peers and delivered when they reconnect
+- **✅ Privacy First**: No accounts, no phone numbers, no persistent identifiers
+- **✅ IRC-Style Commands**: Familiar `/join`, `/msg`, `/who` style interface
+- **✅ Message Retention**: Optional channel-wide message saving controlled by channel owners
+- **✅ Emergency Wipe**: Triple-tap logo to instantly clear all data
+- **✅ Modern Android UI**: Jetpack Compose with Material Design 3
+- **✅ 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
-   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
-   cd bitchat
-   xcodegen generate
+   # Open Android Studio and select "Open an Existing Project"
+   # Navigate to the bitchat-android directory
   ```

-3. Open the generated project:
+3. **Build the project:**
   ```bash
-   open bitchat.xcodeproj
+   ./gradlew build
   ```

-### Option 2: Using Swift Package Manager
-
-1. Open the project in Xcode:
+4. **Install on device:**
   ```bash
-   cd bitchat
-   open Package.swift
+   ./gradlew installDebug
   ```

-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
-2. Copy all Swift files from the `bitchat` directory into your project
-3. Update Info.plist with Bluetooth permissions
-4. Set deployment target to iOS 16.0 / macOS 13.0
+```bash
+./gradlew assembleDebug
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+### 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

@@ -76,11 +113,22 @@ This project is released into the public domain. See the [LICENSE](LICENSE) file

 ### Getting Started

-1. Launch bitchat on your device
-2. Set your nickname (or use the auto-generated one)
-3. You'll automatically connect to nearby peers
-4. Join a channel with `/j #general` or start chatting in public
-5. Messages relay through the mesh network to reach distant peers
+1. **Install the app** on your Android device (requires Android 8.0+)
+2. **Grant permissions** for Bluetooth and location when prompted
+3. **Launch bitchat** - it will auto-start mesh networking
+4. **Set your nickname** or use the auto-generated one
+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

@@ -140,17 +188,105 @@ bitchat uses an efficient binary protocol optimized for Bluetooth LE:
 - Store-and-forward for offline message delivery
 - 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
-2. Configure code signing
-3. Archive and distribute through App Store or TestFlight
+### Core Components

-## 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:
- Bluetooth LE APIs
- Same packet structure and encryption
- Compatible service/characteristic UUIDs
+### Dependencies
+
+- **Jetpack Compose**: Modern declarative UI
+- **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).