https://github.com/bxdoan/py-bitchat
bluetooth mesh chat, IRC vibes
https://github.com/bxdoan/py-bitchat
bitchat bitchat-cli bitchat-python bluetooth encryption p2p
Last synced: 9 months ago
JSON representation
bluetooth mesh chat, IRC vibes
- Host: GitHub
- URL: https://github.com/bxdoan/py-bitchat
- Owner: bxdoan
- Created: 2025-07-14T07:57:49.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-07-14T09:14:30.000Z (11 months ago)
- Last Synced: 2025-07-14T12:07:10.396Z (11 months ago)
- Topics: bitchat, bitchat-cli, bitchat-python, bluetooth, encryption, p2p
- Language: Python
- Homepage:
- Size: 75.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
##\ ##\ ##\ ##\ ##\
## | \__| ## | ## | ## |
#######\ ##\ ######\ #######\ #######\ ######\ ######\
## __##\ ## |\_## _| ## _____|## __##\ \____##\\_## _|
## | ## |## | ## | ## / ## | ## | ####### | ## |
## | ## |## | ## |##\ ## | ## | ## |## __## | ## |##\
####### |## | \#### |\#######\ ## | ## |\####### | \#### |
\_______/ \__| \____/ \_______|\___| \__| \_______| \____/
**_bitchat the terminal v1.0.0_**
**Decentralized • Encrypted • Peer-to-Peer • Open Source | Written in Python**
---
# BitChat Terminal - Python Implementation
Python implementation of BitChat Terminal - a decentralized, encrypted, peer-to-peer chat application over Bluetooth LE.
## Features
- **Decentralized**: No central server required
- **End-to-end Encryption**: Uses X25519 + Ed25519 + ChaCha20-Poly1305
- **Peer-to-Peer**: Direct connection via Bluetooth LE
- **Cross-platform**: Compatible with Rust, iOS and Android versions
- **Password-protected Channels**: Support for private channels
- **Message Fragmentation**: Handles large messages
- **Delivery Confirmation**: Message delivery acknowledgments
- **Terminal Interface**: Simple command-line interface
## Installation
### System Requirements
- Python 3.11 or newer
- Bluetooth LE hardware
- Windows 10/11, macOS or Linux
### Install Dependencies
```bash
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # Linux/macOS
# or
venv\Scripts\activate # Windows
# Install dependencies
pip install -e .
```
## Usage
### Launch Application
```bash
# Run normally
python -m src.main
# Or with debug mode
python -m src.main -d # Basic debug
python -m src.main -dd # Verbose debug
```
### Basic Commands
#### Chat Commands
- `/help` - Show help
- `/exit` - Exit application
- `/clear` - Clear screen
- `/status` - Show connection status
#### User Management
- `/name ` - Change nickname
- `/online` - See who's online
- `/block @user` - Block user
- `/unblock @user` - Unblock user
#### Channels
- `/j #channel` - Join public channel
- `/j #channel ` - Join password-protected channel
- `/channels` - List discovered channels
- `/leave` - Leave current channel
- `/pass ` - Set channel password (owner only)
- `/transfer @user` - Transfer channel ownership
#### Private Messages
- `/dm ` - Start DM with user
- `/dm ` - Send direct private message
- `/reply` - Reply to last private message
#### Conversation Management
- `/list` - Show active conversations
- `/switch` - Interactive conversation switching
- `1`, `2`, `3`... - Quick switch by number
#### Sending Messages
Simply type your message and press Enter to send to current context (public, channel, or DM).
## Project Structure
```
src/
├── __init__.py # Package initialization
├── main.py # Entry point and main logic
├── encryption.py # Encryption handling (X25519, Ed25519, ChaCha20)
├── compression.py # Data compression (Zstandard)
├── fragmentation.py # Large message fragmentation
├── terminal_ux.py # Terminal interface and chat context
└── persistence.py # Settings and state storage
```
## Protocol Compatibility
The Python Terminal implementation is based on the original Bitchat projects:
- Original Rust version by [ShilohEye](https://github.com/ShilohEye/bitchat-terminal)
- iOS BitChat app by [Jack](https://github.com/permissionlesstech/bitchat)
- Android BitChat app [Jack](https://github.com/permissionlesstech/bitchat-android)
All use the same:
- Bluetooth LE service UUID: `F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C`
- Characteristic UUID: `A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5D`
- Binary protocol format
- Encryption algorithms
## Dependencies
### Core Dependencies
- `bleak` - Bluetooth LE library
- `cryptography` - Cryptographic operations
- `pynacl` - NaCl cryptography (Ed25519, X25519)
- `pybloom-live` - Bloom filter implementation
- `zstandard` - Fast compression
- `colorama` - Terminal colors
### Development Dependencies
- `pytest` - Testing framework
- `black` - Code formatter
- `flake8` - Linting
- `mypy` - Type checking
## Configuration
The application automatically saves settings at:
- **Windows**: `%APPDATA%\BitChat\state.json`
- **macOS/Linux**: `~/.config/bitchat/state.json`
### Saved Data
- Nickname
- Blocked users (by fingerprint)
- Channel creators and settings
- Password-protected channels (passwords encrypted)
- Identity key for encryption
## Security Features
### Encryption
- **X25519** for key exchange
- **Ed25519** for digital signatures
- **ChaCha20-Poly1305** for symmetric encryption
- **HKDF** for key derivation
### Privacy
- Message padding to hide message length
- Cover traffic for iOS compatibility
- Local storage with encrypted passwords
- No telemetry or analytics
### Network Security
- Peer authentication via public key cryptography
- Message replay protection with bloom filters
- TTL-based message propagation
- Forward secrecy for ephemeral keys
## Troubleshooting
### Bluetooth Issues
```bash
# Linux: Ensure user has bluetooth permissions
sudo usermod -a -G bluetooth $USER
# Check Bluetooth service
systemctl status bluetooth
```
### Permission Issues
- **Windows**: Run as Administrator if needed
- **macOS**: Allow app to access Bluetooth in System Preferences
- **Linux**: Ensure user is in `bluetooth` group
### Debug Mode
```bash
# Basic debug - shows connection info
python -m src.main -d
# Verbose debug - shows all packet info
python -m src.main -dd
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/bxdoan/py-bitchat
cd py-bitchat
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```
### Testing
```bash
pytest tests/
```
### Code Formatting
```bash
black src/
flake8 src/
mypy src/
```
## Roadmap
- [ ] GUI wrapper with tkinter/PyQt
- [ ] File transfer support
- [ ] Voice message support
- [ ] Group calls
- [ ] Mobile notifications
- [ ] Plugin system
## License
MIT License - see LICENSE file
## Contributing
All contributions are welcome! Please:
1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Create Pull Request