Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bithuman.ai/llms.txt

Use this file to discover all available pages before exploring further.

Raspberry Pi Device

​
Quick Start

1

Hardware needed

  • Raspberry Pi 4B (8GB RAM recommended)
  • microSD card (32GB+, Class 10)
  • USB microphone
  • Stable internet connection
  • Separate computer for web interface (recommended)
2

Install OS

Use Raspberry Pi OS (64-bit) with Raspberry Pi Imager.
3

Setup Pi

sudo apt update && sudo apt upgrade -y
sudo apt install python3.11 python3.11-venv -y
python3.11 -m venv bithuman-env
source bithuman-env/bin/activate
4

Install dependencies

pip install bithuman --upgrade livekit-agents openai
sudo apt install portaudio19-dev -y
5

Set environment

export BITHUMAN_API_SECRET="your_secret"
export BITHUMAN_MODEL_PATH="/home/pi/model.imx"
export LIVEKIT_API_KEY="your_livekit_key"
export LIVEKIT_API_SECRET="your_livekit_secret"
export LIVEKIT_URL="wss://your-project.livekit.cloud"
export OPENAI_API_KEY="your_openai_key"
export LOADING_MODE="SYNC"  # Important for Pi performance
6

Run agent

git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/essence-selfhosted
View source code on GitHub
cp .env.example .env
# Edit .env with your credentials
docker compose up
For best results, run the web interface on a separate computer. Running both agent and web UI on the same Pi causes significant slowdown.

​
What It Does

  1. Runs avatar agent optimized for Raspberry Pi
  2. Uses SYNC loading mode for memory efficiency
  3. Connects to web browsers via LiveKit
  4. Suited for always-on edge applications
Raspberry Pi UI Pi-specific optimizations:
  • Synchronous model loading (LOADING_MODE="SYNC")
  • Lower memory limits (1500MB warning threshold)
  • Single process mode for stability
  • Extended initialization timeout (120s)

​
Auto-start Service

Make it run automatically on boot:
/etc/systemd/system/bithuman-agent.service
[Unit]
Description=bitHuman Avatar Agent
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi
Environment=LOADING_MODE=SYNC
Environment=BITHUMAN_API_SECRET=your_secret
Environment=BITHUMAN_MODEL_PATH=/home/pi/model.imx
ExecStart=/home/pi/bithuman-env/bin/python examples/essence-selfhosted/agent.py start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable bithuman-agent
sudo systemctl start bithuman-agent
sudo systemctl status bithuman-agent

​
Performance Tips

# Enable performance governor
echo 'performance' | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# Disable unnecessary services
sudo systemctl disable bluetooth
sudo systemctl disable wifi  # if using ethernet
  • Use swap file for extra memory
  • Store models on USB SSD if possible
  • Monitor with htop or free -h

​
Common Issues

ProblemSolution
Out of memoryUse Pi 4B 8GB, enable swap: sudo dphys-swapfile swapon
Slow performanceUse ethernet, check CPU temp: vcgencmd measure_temp
Audio problemsCheck USB mic: arecord -l, test: arecord -d 5 test.wav
Model loading timeoutEnsure LOADING_MODE="SYNC", use faster storage

​
Hardware Add-ons

import board
import adafruit_dht

# Add environmental awareness
dht = adafruit_dht.DHT22(board.D4)
temperature = dht.temperature
humidity = dht.humidity

​
Next Steps

  • Add sensors — Integrate environmental awareness
  • Add camera — Use Pi camera for visual context
  • Scale up — Deploy multiple Pi devices
  • Go local — Replace OpenAI with local LLM