bitchat-py (Lightweight Bitchat Client)

A minimal, single-file Python 3 client for the Bitchat decentralized BLE mesh protocol.

Designed to be lightweight and "hackable," this script is ideal for testing and automation. It allows you to broadcast and receive public messages without a heavy UI or complex installation.

Quick Start

1. Setup Virtual Environment

It is recommended to run this in a dedicated virtual environment to keep dependencies clean.

# Create the virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install bleak pynacl lz4

2. Run the Client

You can run the client directly using the venv python executable, or after activating the environment.

# Syntax: ./venv/bin/python3 bitchat-client.py <YourNickname>
./venv/bin/python3 bitchat-client.py Alice

Troubleshooting

Since this script interacts directly with low-level Bluetooth adapters, the hardware can sometimes get stuck. Use these commands to reset the state.

If you see connection errors or scanning hangs:

Kill "zombie" processes: If the script didn't exit cleanly, background processes might be holding the adapter.

pkill -f "python.*bitchat-client"

Hard Reset Bluetooth: If the adapter is completely unresponsive, restart the system service (requires sudo).

sudo systemctl restart bluetooth

Alternatives

• This Project (bitchat-py): Best for scripting, minimal resources, and creating bots/relays.
• bitchat-python: A fully-featured terminal application with a rich UI and more complex architecture.

Note

This is a reference implementation. Capabilities are limited to public chat.