Tutorial on Deploying Xiaozhi Chatbot with Raspberry Pi

July 16, 2025 By Adeept

I. Preparation Requirements:

A Raspberry Pi (4B or higher)
A 32GB memory card
A microphone
A speaker
A camera

II. Burning the Raspberry Pi System Image:

Download the image burning tool: https://www.raspberrypi.com/software/
Download the system image(Raspberry Pi OS (64-bit)): https://www.raspberrypi.com/software/operating-systems/
Burn the system image to the Raspberry Pi.
Insert the microSD card with the burned Raspberry Pi system into the Raspberry Pi and start the system.

III. Deploy the Xiaozhi Chatbot:

Execute the following command to download the Xiaozhi Robot code (do not use sudo; use the default “pi” user):
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
Install system dependencies:

sudo apt-get update

# Essential installations

sudo apt-get install python3-pyaudio portaudio19-dev ffmpeg libopus0 libopus-dev build-essential python3-venv

# Install volume control dependencies and PulseAudio utilities

sudo apt-get install pulseaudio-utils

Python Dependency Installation: Use Miniconda (recommended) because some packages cannot be downloaded directly from the Raspberry Pi system’s repositories, which may lead to installation failures.

Download the Miniconda installation package:

wget -O Miniconda3-latest-Linux-aarch64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh

Add execution permissions to the installation script:

chmod +x Miniconda3-latest-*.sh

Run the installation script:

./Miniconda3-latest-*.sh

During the installation process:

When the license agreement appears → Press the Enter key to scroll through slowly, or press q to skip directly.

Type yes to accept the agreement. Select the installation path (the default is $HOME/miniconda3) → Press Enter directly to confirm.

Whether to initialize Miniconda → Type yes (recommended).

Configure environment variables:

nano ~/.bashrc
Add at the end of the file:
export PATH="$HOME/miniconda3/bin:$PATH"
Save and exit:
Press Ctrl + X, press Y, press Enter
Make the configuration take effect immediately:

source ~/.bashrc

Check if conda is installed successfully. If successful, the version number will be output (e.g., conda 24.1.2):
conda --version
(Recommended) Disable automatic activation of the base environment on startup:
conda config --set auto_activate_base false
Install project dependencies:

1. Create a py-xiaozhi virtual environment (Python version restriction: It is recommended to use Python 3.9.13+ version, with a maximum recommended version of 3.12)
conda create -n py-xiaozhi python=3.10 -y
2. Activate the environment
conda activate py-xiaozhi
3. Install Python dependencies
cd py-xiaozhi/
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
Install other dependencies (because installing these two with pip may cause issues with startup. They need to be installed separately in conda)
# Still in the px-xiaozhi virtual environment being created
# PyQt5
conda install pyqt=5.15.10 -y
# OpenCV
conda install opencv=4.10.0 -y

Start Xiaozhi Robot (remember to connect peripherals such as camera, microphone, and speaker):
python main.py
Upon first launch, the verification code xxxxxx will be printed in the log
Log in to the Xiaozhi Console: https://xiaozhi.me/console
Register and create an agent, click “Add Device“, and enter the verification code:

Restart the Xiaozhi robot:
python main.py
Configuration information has been generated under this project:

config/config.json

{

“SYSTEM_OPTIONS”: {

“CLIENT_ID”: “a254fb22-f54f-48ca-8e32-29557542cfcf1”,

“DEVICE_ID”: “dc:a6:32:7f:db:91”,

“NETWORK”: {

“OTA_VERSION_URL”: “https://api.tenclass.net/xiaozhi/ota/”,

“WEBSOCKET_URL”: “wss://api.tenclass.net/xiaozhi/v1/”,

“WEBSOCKET_ACCESS_TOKEN”: “test-token”,

“MQTT_INFO”: {

“endpoint”: “mqtt.xiaozhi.me”,

“client_id”: “GID_test@@@dc_a6_32_7f_db_91@@@a254fb22-f54f-48ca-8e32-29557542cfcf”,

“username”: “eyJpcCI6IjExNi4zMS4yNTUuMTIifQ==”,

“password”: “ODxGAmYTSPuc5ajG0YpiT+cK5DQATnUCpUeoLY+K4Z8=”,

“publish_topic”: “device-server”,

“subscribe_topic”: “null”

“ACTIVATION_VERSION”: “v2”,

“AUTHORIZATION_URL”: “https://xiaozhi.me/”

}

“WAKE_WORD_OPTIONS”: {

“USE_WAKE_WORD”: true,

“MODEL_PATH”: “models/vosk-model-small-cn-0.22”,

“WAKE_WORDS”: [

“小智”,

“小美”,

]

“TEMPERATURE_SENSOR_MQTT_INFO”: {

“endpoint”: “你的Mqtt连接地址”,

“port”: 1883,

“username”: “admin”,

“password”: “123456”,

“publish_topic”: “sensors/temperature/command”,

“subscribe_topic”: “sensors/temperature/device_001/state”

“HOME_ASSISTANT”: {

“URL”: “http://localhost:8123”,

“TOKEN”: “”,

“DEVICES”: []

“CAMERA”: {

“camera_index”: 1,

“frame_width”: 640,

“frame_height”: 480,

“fps”: 30,

“Loacl_VL_url”: “https://open.bigmodel.cn/api/paas/v4/”,

“VLapi_key”: “90edcea408a4442295cb5cd2ab1752914.iQLrZg76zUpOJgBJ”,

“models”: “glm-4v-flash”

}

config/efuse.json

{

“serial_number”: “SN-0EA6D7B6-dca6327fdb91”,

“hmac_key”: “22143413742b6dc80173abf5ff1d97a488b9cee225092bce94eb56456fcf140d”,

“activation_status”: true

}

When the activation_status changes to true, it indicates that it has been activated.
Successfully started:

At this point, the Xiaozhi robot has been successfully activated, and you can now have a normal conversation with Xiaozhi.

IV.Configure the Voice Wake-up Function for Xiaozhi Chatbot

Open Vosk model address: https://alphacephei.com/vosk/models

Choose the speech recognition model you need to download (taking vosk-model-small-cn-0.22 as an example):

wget -O vosk-model-small-cn-0.22.zip https://alphacephei.com/vosk/models/vosk-model-small-cn-0.22.zip

Place the downloaded speech model in the specified “models” directory:

cd py-xiaozhi/

mkdir models

cd models

mv ~/vosk-model-small-cn-0.22.zip ./

Modify configuration:
cd ../config/
nano config.json
Set up the voice wake-up model and turn on the switch for using the wake-up word:

Press Ctrl+X,Y to save

Start the Xiaozhi robot, and you can wake it up by voice

V.Configure Visual Recognition Function for Xiaozhi Chatbot

Open the Zhipu AI console: https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys

Create API keys:

Modify the configuration file config/config.json,copy the created API keys, replace the value of VLapi_key, and select glm-4v-flash for the models model. This visual model is free and can be adjusted for other models as needed.

nano ./config/config.json