Turn a Raspberry Pi Zero 2 W + PiSugar Whisplay HAT into a pocketable AI buddy.
Hold the button, speak your mind, and the bot answers back with a playful persona, animated LEDs, scrolling text, and synthesized voice powered by OpenAI GPT-5-mini.
⚠️ Fun project only. This is not a safety-critical device or a financial oracle.
- Raspberry Pi Zero 2 W (Raspbian/Raspberry Pi OS Bookworm recommended)
- PiSugar Whisplay HAT (LCD, mic, speaker, RGB LED, button)
- Optional: PiSugar battery pack (not required for development/simulation)
- MicroSD card (16 GB+) and reliable 5 V power source
- Single-language stack – Pure Python (
asyncioeverywhere) with uv/pyproject.toml. - Personality engine – Three built-in personas (Arcade Ally, Cosmic Companion, Byte-Sized Bard) with LED colour themes and playful prompts.
- Fun idle loop – Periodic hints and tips when the device is waiting for your next question.
- Speech pipeline – SoX for capture, OpenAI GPT-5-mini for STT/LLM/TTS, mpg123 for playback.
- Simulation mode – Run the full flow on macOS/Linux dev machines (keyboard triggers replace the Whisplay button).
- History & continuity – Recent conversations stored under
data/history.jsonto give replies some memory.
uv sync --all-extras
cp .env.example .env
echo "OPENAI_API_KEY=sk-your-key" >> .env
uv run -- python -m whisplay_chatbot simulatePress Enter once to simulate a button press, then again to release. Logs are written to data/logs/whisplay.log; follow them with tail -f data/logs/whisplay.log. Simulation audio dumps land in data/.
-
Prepare the Pi
sudo apt update sudo apt install -y python3.11-full python3-pip sox mpg123 git
-
Clone & install
git clone https://github.com/URL42/whisplay_chatbot.git cd whisplay_chatbot uv sync --group pi --all-extras -
Environment
cp .env.example .env nano .env # add OpenAI key and any overrides -
Run
uv run -- python -m whisplay_chatbot run
Hold the Whisplay button, speak, release, and enjoy! Add --simulate to the command if you need to force keyboard mode.
Tip: Logs are stored in
data/logs/whisplay.log. Stream them withtail -f data/logs/whisplay.log.
Create /etc/systemd/system/whisplay-chatbot.service:
[Unit]
Description=Whisplay AI Chatbot
After=network-online.target sound.target
Wants=network-online.target
[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/whisplay_chatbot
EnvironmentFile=/home/pi/whisplay_chatbot/.env
ExecStart=/home/pi/.local/bin/uv run -- python -m whisplay_chatbot run
Restart=on-failure
[Install]
WantedBy=multi-user.targetEnable it:
sudo systemctl daemon-reload
sudo systemctl enable --now whisplay-chatbotLogs stream under journalctl -u whisplay-chatbot -f.
| Variable | Description | Default |
|---|---|---|
OPENAI_API_KEY |
GPT-5-mini API key | required |
OPENAI_BASE_URL |
Override API endpoint (optional) | |
WHISPLAY_ENABLE_SIMULATION |
1 to run without Pi hardware |
0 |
WHISPLAY_PERSONA_MODE |
random, rotate, or fixed |
random |
WHISPLAY_PERSONA_NAME |
Persona name if fixed |
|
WHISPLAY_IDLE_TIMEOUT_SECONDS |
Hint cadence while idle | 180 |
WHISPLAY_MAX_RECORD_SECONDS |
Recording cap | 12 |
WHISPLAY_TTS_VOICE |
Preferred OpenAI voice for playback | alloy |
WHISPLAY_LOG_LEVEL |
Logging verbosity | INFO |
WHISPLAY_LOG_DIR |
Directory for log files | data/logs |
Place any custom persona definitions in a JSON file and point WHISPLAY_PERSONAS_PATH to it.
uv run pytest
uv run ruff check .
uv run ruff format --check .To run the chatbot with live hardware from your dev machine, set WHISPLAY_ENABLE_SIMULATION=0 and ensure you have the Whisplay HAT drivers (RPi.GPIO, spidev) available.
- Ask “Tell me a retro joke” to trigger Arcade Ally puns.
- Try “Narrate a space bedtime story” for stargazing lore.
- Request haiku or limericks to hear the Byte-Sized Bard rhyme.
- Leave the bot idle to get playful tips on what to ask next.
GPL-3.0-or-later — see LICENSE. Contributions welcome! Open a PR with your persona ideas, idle animations, or new hardware tricks.