scar-chat/android_client/README.md

Android Chat Client

This is the Android client for the SCAR Chat application.

Requirements

• Android SDK 24+ (API level 24)
• Android Studio 4.0+ or Gradle 8.1+
• Java JDK 11+
• Minimum Android device: Android 7.0 (API 24)

Project Structure

android_client/
├── app/
│   ├── src/
│   │   └── main/
│   │       ├── java/com/scar/chat/
│   │       │   ├── MainActivity.java           # Main activity with tabs
│   │       │   ├── ChatConnection.java         # SSL/TLS connection handler
│   │       │   ├── ChatFragment.java           # Chat UI fragment
│   │       │   ├── VideoFragment.java          # Video/camera UI fragment
│   │       │   └── TabLayoutMediator.java      # Tab mediator
│   │       ├── res/
│   │       │   ├── layout/
│   │       │   │   ├── activity_main.xml       # Main activity layout
│   │       │   │   ├── fragment_chat.xml       # Chat tab layout
│   │       │   │   └── fragment_video.xml      # Video tab layout
│   │       │   └── values/
│   │       │       ├── strings.xml             # String resources
│   │       │       └── colors.xml              # Color resources
│   │       └── AndroidManifest.xml             # App manifest
│   └── build.gradle                            # App-level build config
├── build.gradle                                # Project-level build config
├── settings.gradle                             # Gradle settings
├── gradle/wrapper/                             # Gradle wrapper
└── build.sh                                    # Build script

Features

• TLS/SSL Encryption: Secure connection to chat server
• Multi-tab Interface: Chat tab for messaging, Video tab for camera
• Camera Support: Enable/disable camera with device selection
• Real-time Chat: Send and receive messages in real-time
• Customization: Background color, text color, and transparency controls (UI ready)
• Multi-client Support: Connect multiple Android devices to same server

Building

Prerequisites

1. Install Android Studio or Android SDK + Gradle
2. Java JDK 11+ installed and in PATH
3. ANDROID_HOME environment variable set to SDK location

On Linux/macOS:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

On Windows (PowerShell):

$env:ANDROID_HOME = "$env:USERPROFILE\AppData\Local\Android\Sdk"
$env:PATH += ";$env:ANDROID_HOME\tools;$env:ANDROID_HOME\platform-tools"

Using Android Studio (Recommended)

1. Open Android Studio
2. File → Open and select android_client/ directory
3. Wait for Gradle sync to complete
4. Select "Build" → "Make Project"
5. APK will be generated in app/build/outputs/apk/debug/

Using Gradle (Command Line)

Linux/macOS:

cd android_client
./gradlew build

Windows:

cd android_client
gradlew.bat build

If you don't have Gradle installed system-wide, the wrapper will handle it.

Running

On Physical Device

1. Enable USB debugging on your Android device (Settings → Developer Options)
2. Connect via USB
3. Run:

   ./gradlew installDebug        # Linux/macOS
   gradlew.bat installDebug      # Windows
   

4. App will be installed automatically
5. Launch "SCAR Chat" from your app drawer

On Emulator

1. Start Android Emulator from Android Studio (AVD Manager)
2. Wait for emulator to fully boot
3. Run:

   ./gradlew installDebug        # Linux/macOS
   gradlew.bat installDebug      # Windows
   

4. App will be installed automatically
5. Launch "SCAR Chat" from emulator app drawer

Usage

1. Connect to Server:

   • Enter server hostname (e.g., 192.168.1.100 or localhost)
   • Enter port (default: 42317)
   • Tap "Connect"

2. Chat:

   • Go to "Chat" tab
   • Type message in text field
   • Tap "Send"
   • View chat history in display area

3. Camera:

   • Go to "Video" tab
   • Select camera from dropdown (if multiple available)
   • Check "Enable Camera" to start camera
   • Server will receive CAMERA_ENABLE message
   • Remote users will see camera status

Permissions

The app requires the following permissions (Android 6.0+):

• INTERNET: Network communication with server
• CAMERA: Camera access for video capture
• RECORD_AUDIO: Audio recording capability

Permissions are requested at runtime on Android 6.0+.

Connection Protocol

• Protocol: TLS/SSL over TCP
• Port: 42317 (default)
• Message Format: Text messages ending with newline (\n)
• Camera Status: CAMERA_ENABLE / CAMERA_DISABLE messages

Dependencies

• androidx.appcompat: Support library for backward compatibility
• com.google.android.material: Material Design components
• androidx.constraintlayout: Layout constraints
• androidx.recyclerview: List/grid view components
• androidx.viewpager2: Tab paging
• org.bouncycastle: SSL/TLS support

Troubleshooting

Connection Failed

• Verify server is running and accessible
• Check hostname/IP and port number
• Ensure firewall allows connection to port 42317
• Check SSL certificate is valid (app accepts self-signed certs)

Camera Not Working

• Verify camera permission is granted (Settings → Permissions)
• Check device has a camera
• Try reconnecting or restarting app

Build Errors

• Update Android Studio to latest version
• Run ./gradlew clean before rebuilding
• Delete build/ and .gradle/ directories
• Ensure Java JDK 11+ is installed

Security Notes

• The app currently accepts self-signed SSL certificates (for development)
• For production, implement proper certificate validation
• Enable ProGuard/R8 obfuscation in release builds (configured)

Future Enhancements

• Full video frame encoding/transmission (H.264)
• Video frame decoding and display
• Audio/VoIP support
• Message persistence/history
• User authentication
• Emoji/sticker support
• File transfer
• Group chat support
• Certificate pinning for enhanced security

Building APK for Distribution

cd android_client

# Create signed release build
./gradlew bundleRelease
# OR for APK
./gradlew assembleRelease

Output files:

• AAB: app/build/outputs/bundle/release/app-release.aab
• APK: app/build/outputs/apk/release/app-release.apk

License

Part of the SCAR Chat project. See main project README for details.