Bee Local

Open-source tools for the Bee Pioneer wearable AI device. Connect directly via BLE, capture audio, transcribe locally, and process with LLMs - no cloud required.

Why This Exists

The official Bee app was delisted from app stores. This project enables device owners to:

• Connect directly to their Bee Pioneer via Bluetooth
• Record and transcribe audio locally
• Process conversations with local LLMs
• Full control without vendor lock-in

Project Structure

bee_local/
├── ble-client/         # Python BLE client scripts
├── server/             # FastAPI service (full-featured)
├── docs/               # Protocol documentation
└── archive/            # Research artifacts (APK decompilation)

Quick Start

Option 1: BLE Client (Direct Connection)

Simple Python scripts for direct device control.

cd ble-client
python -m venv .venv && source .venv/bin/activate
pip install bleak

# Scan for device
python bee_scan.py

# Interactive CLI
python bee_cli.py --address C4:3E:05:F6:F8:91

# Record audio
python bee_audio.py --address C4:3E:05:F6:F8:91 --duration 30

Option 2: FastAPI Server (Full Features)

Complete service with REST API, WebSocket events, transcription, and LLM integration.

cd server
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Start server
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Access API docs
open http://localhost:8000/api/v1/docs

See server/README.md for full documentation.

Option 3: Run on Android (Full BLE Support)

For complete BLE functionality (notifications, battery status, audio streaming), run on Android via Termux.

# In Termux
pkg install python
pip install fastapi uvicorn bleak
python bee_server.py

See server/android/README.md for setup guide.

Platform Support

Feature	Linux	Android	macOS
Connect to Bee	Yes	Yes	Yes
Send commands	Yes	Yes	Yes
Receive notifications	Yes	Yes	No
Get battery/status	Yes	Yes	No
Audio streaming	Yes	Yes	No

macOS has BLE notification limitations. Commands work, but status/audio don't.

Device Information

Bee Pioneer Edition

• Connectivity: Bluetooth Low Energy (BLE)
• Audio Codec: OPUS (default) or AAC
• Charging: USB-C

Button Controls

Action	Method
Start/Stop capture	Single press
Voice assistant	Press and hold
Process conversation	Double press
Reset/Re-pair mode	Press 5x rapidly

LED Indicators

Pattern	Meaning
Blue-green flashing	Pairing mode
Blue flashing	Too far from phone
3x Red flash	Low battery
Solid while charging	Charging

BLE Protocol

Full protocol documentation: docs/BEE_PROTOCOL_SPEC.md

Key UUIDs

Component	UUID
Service	03D5D5C4-A86C-11EE-9D89-8F2089A49E7E
Control Characteristic	05E1F93C-D8D0-5ED8-DD88-379E4C1A3E3E
Audio Characteristic	B189A505-A86C-11EE-A5FB-8F2089A49E7E

Key Commands

Command	Code	Description
Get Device ID	0xC00E	8-byte hex identifier
Get Firmware	0xC005	Version (major.minor.patch)
Get Battery	0xC00F	Level (0-100) + charging state
Get State	0xC00A	Mute/Recording/Sleep
Set State	0xC006	Start/Stop recording
Power Off	0xC007	Shutdown device

Components

BLE Client (ble-client/)

Standalone Python scripts for direct BLE control.

Script	Purpose
bee_cli.py	Interactive command-line interface
bee_client.py	BLE client library
bee_audio.py	Audio capture to OGG Opus
bee_scan.py	Scan for Bee devices

FastAPI Server (server/)

Full-featured service with:

• REST API for device control
• WebSocket for real-time events
• Audio recording and storage
• Local transcription (Whisper)
• LLM integration (Ollama, OpenAI, Anthropic)
• Mobile client SDKs

Documentation (docs/)

File	Content
BEE_PROTOCOL_SPEC.md	Complete BLE protocol reference
fastAPI_bee_contract.md	API contract and platform notes

Troubleshooting

Device not found

1. Put Bee in pairing mode: Press button 5x (blue-green LED should flash)
2. Run scan within 60 seconds
3. Move device closer (RSSI should be > -70)

Connection fails on macOS

macOS BLE requires pairing for notifications. The service runs in write-only mode:

• Commands work (start/stop/poweroff)
• Status and audio don't work
• Use Linux or Android for full features

Audio not recording

1. Ensure device is in recording state (not muted)
2. Check notifications are enabled (not possible on macOS)
3. Verify audio characteristic subscription

Contributing

This is an open-source project for Bee Pioneer owners. Contributions welcome:

• Protocol improvements
• Platform support
• Bug fixes
• Documentation

License

MIT

Disclaimer

This project is for personal use by device owners. It is not affiliated with Bee.computer. Use responsibly.