Whisplay AI Chatbot: a pocket sized voice assistant on a PiSugar Whisplay

A finished product, not a set of parts

The description is short and sets the scope: a pocket-sized AI chatbot device built using a Raspberry Pi Zero 2 W or Pi 5. The readme puts it more evocatively. Press the button, speak, and it talks back, like a futuristic walkie-talkie with a mind of its own.

What that means in practice is that the hardware list is short and fixed. A Raspberry Pi Zero 2 W, and the readme recommends a Pi 5 with 8GB of RAM for an offline build. A PiSugar Whisplay HAT, which includes the LCD screen, the on-board speaker and the microphone. And a PiSugar 3 1200mAh battery, with a 5000mAh version for the Pi 5.

The battery is the detail that makes this a pocket device rather than a desk project, and it is also why the readme has a separate page for battery level display instructions. There is a documented case for the device as well, with four printable enclosure designs: the Whisplay Chatbot Case for the Pi Zero 2, a fused filament model of the same, a Pi 5 version, and a Pi 5 version sized for the LLM8850 accelerator.

The project is published under GPL-3.0, the primary language is TypeScript, and the recent releases are v2.1.5 from 2026-10-20, v2.1.4 from 2026-10-19 and v2.1.3 from 2026-08-28. The last push was on 2026-10-20, so this is an actively worked product rather than an experiment that stopped.

There is also a Discord badge and a test video playlist linked from the readme, plus a tutorial video and three more tutorial links for the offline version build on the Pi 5. The presence of a case design, a battery and a screen means the result is something you hold, which is a different thing from a script you run on a desktop.

Installation is a sequence of shell scripts

The install path is a numbered list of steps, and it is short enough to follow end to end.

The first step is the clone.

   git clone https://github.com/PiSugar/whisplay-ai-chatbot.git
   cd whisplay-ai-chatbot

Then the dependencies, and the source of the shell profile matters.

   bash install_dependencies.sh
   source ~/.bashrc

The readme explains that running source ~/.bashrc is necessary to load the new environment variables, which means the dependency script writes to the profile rather than exporting into the current shell. That is a small thing that will confuse someone who skips it.

There is one option worth reading before you run anything. All scripts respect the NPM_REGISTRY environment variable, and if it is not set the official npm registry at https://registry.npmjs.org is used. To point at a mirror, in China for instance, you export it first.

   export NPM_REGISTRY="https://registry.npmmirror.com"
   bash install_dependencies.sh

The readme is explicit that this also applies to build.sh and to all the whisplay CLI commands, including plugin install, plugin update and update. That is a good design decision, because a mirror switch that only affected one script would produce a half-mirrored install that fails later in a confusing way.

After the dependencies comes the configuration, then the build, then the run.

   whisplay configure

That command opens an interactive config wizard, and if .env does not exist it is created automatically from .env.template. The manual alternative is to copy the template yourself, and the repository root holds .env.template.

   bash build.sh

   bash run_chatbot.sh

And there is an optional step for running the service at boot.

   bash startup.sh

The readme warns that this will disable the graphical interface and set the system to multi-user mode, which is suitable for headless operation. That is the correct trade for a device that is meant to be picked up and used, and the logs are written to chatbot.log, where tail -f chatbot.log shows them in real time.

The audio drivers come before all of this. The readme says you need to firstly install the audio drivers for the Whisplay HAT and to follow the instructions in the Whisplay HAT repository, and the fact that a separate repository exists for that is the clearest signal that the driver layer is the part you will spend the most time on.

A whisper CLI and a plugin system under the hood

The package manifest describes the runtime more clearly than the readme does, and there are two pieces of it worth pulling out.

The first is the CLI. The manifest registers a binary named whisplay pointing at ./bin/whisplay, and the readme mentions whisplay configure as the configuration entry point along with plugin install, plugin update and update. So the device is managed through a command line tool rather than a settings page on the LCD, which is the sensible choice for a device you configure over SSH once and then use by pressing a button.

The build itself is a TypeScript compile with one extra step.

  "main": "index.js",
  "bin": {
    "whisplay": "./bin/whisplay"
  },
  "scripts": {
    "dev": "yarn build && yarn start",
    "build": "rm -rf dist && tsc && node scripts/register-whisplay-daemon-app.js",
    "start": "node dist/index.js",

The build script removes the dist directory, runs tsc, and then registers the daemon application through a script in scripts/. The yarn.lock at the root and the dev script using yarn build and yarn start tell you the intended package manager, and the postinstall hook runs patch-package, with a patches/ directory in the repository, so the project patches its own dependencies at install time.

The second piece is the plugin system, and the repository layout shows how much of the project is a framework rather than a single application. There is a skills/ directory, a cli/ directory, a src/ directory, a web/ directory, a python/ directory, a bin/ directory, a docker/ directory, a packaging/ directory and a wiki directory that is committed to the repository. There is also a README-llm8850.md at the root and an index_knowledge.sh script, plus an openclaw/ directory.

The two language split is visible in the dependency list. onnxruntime-node is there, along with @picovoice/leopard-node and @picovoice/orca-node for wake word and voice activity detection, and the python/ directory with its own requirements file is where the speech side lives, since the readme mentions the python code having its own dependencies and Whisper being used on the LLM8850. The Goals section in the readme spells out the support matrix, with LLM8850 Whisper, melottsTTS, the Qwen3 language model API, the Qwen3-VL multimodal API and image generation all marked as supported, plus the Raspberry Pi AI HAT+ 2 with Hailo-10H, and speaker recognition still to come.

The cloud model support is broad. The dependency list includes the Anthropic SDK, the OpenAI SDK, the AWS Bedrock runtime client with Polly for text to speech and Transcribe streaming for speech recognition and S3 Vectors, the Google GenAI client and the Google Cloud text to speech package, a Qdrant JavaScript client for vector search, and Koa with a router and a websocket library for the local server.

Rebuilding, upgrading the env file and restarting the service

Three maintenance procedures are documented, and they are the ones you will actually use after the first install.

The first is the rebuild. If you make changes to the node code, or simply pull new code from the repository, you need to rebuild the project, and the command is the same build script you used to install.

   bash build.sh

The second case is a Python dependency problem. If you hit a ModuleNotFoundError, or there are new third party libraries in the python code, the readme tells you to update the Python dependencies with pip and a specific flag.

cd python
pip install -r requirements.txt --break-system-packages

The --break-system-packages flag is there because the PiSugar system images install into the system Python rather than a virtual environment, and modern pip refuses to do that by default. It is a deliberate override rather than an accident, and it is worth understanding that the Python side of this project installs into the system interpreter.

The third is the environment file, which is described as being updated from time to time. If you want to upgrade your existing .env based on the latest .env.template, the readme gives a script.

bash upgrade-env.sh

The recommended way to update environment variables is otherwise the configure command, and the reason given is that it lets you manage .env by category and creates the file automatically if it is missing. You can also edit .env directly, and after making changes the service has to be restarted.

sudo systemctl restart chatbot.service

The service name tells you the packaging: the chatbot runs as a systemd unit called chatbot.service, which is what startup.sh sets up when it switches the system to multi-user mode.

Two more features are documented in the readme with their own wiki pages: a wake word for hands-free interaction, and image generation from text prompts. There is also a page on the data folder describing the sub-folder layout and the cleanup options, which is the kind of detail that appears when a project has been running on real hardware for a while and has filled up an SD card.

Where the Whisplay AI Chatbot is the wrong tool

There are four cases where this is the wrong choice, and in three of them the reason is the same: the project is a product for one piece of hardware.

The first is anything that is not a PiSugar Whisplay. The manifest shows a service built around a Koa web server, websocket support, an LCD interface and on-device wake word and voice activity detection through the Picovoice packages. The screen, the button, the microphone and the speaker are not accessories to the software, they are the input and output model of the application. Porting it to a different display or a different microphone is not a configuration change.

The second is a developer who wants a chatbot framework. The openclaw/ directory, the skills/ directory, the plugin system and the CLI suggest an extensible structure, and that is the most interesting part of the project, but it is an application with a plugin mechanism rather than a library you build on. If you want to build a voice assistant product, you would either use this whole device or none of it.

The third is a battery powered deployment that has to last. The hardware list specifies a 1200mAh battery, 5000mAh for the Pi 5, and the readme also links a battery level display page, which suggests the battery is the binding constraint. A Pi 5 running a speech recognition model and a language model is a lot to ask of a small battery, and the readme's own guidance, a Pi 5 with 8GB of RAM for offline builds, points at the more capable board.

The fourth is a privacy sensitive deployment that cannot use the network. The offline build is documented, and the LLM8850 accelerator is supported for local Whisper, TTS and language models, but the dependency list also includes a full set of cloud SDKs, and the goals list includes the Qwen3 and Qwen3-VL APIs which are network calls. A local only build is possible, but it is a configuration choice, and the readme does not describe how to strip the cloud paths out.

On the alternative, the difference in approach against building the same thing yourself is the integration work. Doing this from scratch means writing the audio capture path, the wake word detection, the speech to text step, the model call, the text to speech step and the display update, and then dealing with the latency of each. This project has all of that already integrated, with the driver layer, the case design and the battery display as parts the vendor provides, which is why it exists as a product rather than a tutorial.

The second comparison is a dedicated voice assistant product, which gets you a working device without a soldering iron, at the cost of the hardware being closed and the software being something you did not write. The trade here is between a device you can modify, since the source is published and the CLI and plugin system are open, and one you cannot.

The GPL-3.0 licence matters for the first option. If you want to ship a commercial product based on this software, the copyleft terms apply to the parts you distribute, and the readme does not discuss that, so read the LICENSE file and take advice before you build on it commercially.

Editorial conclusion

Whisplay AI Chatbot suits a maker who wants a finished voice assistant product rather than a set of components, since the HAT, the case designs, the drivers and the service all come from the same vendor, and it does not suit a developer who wants a chatbot framework to build on, since the runtime is tied to that hardware. Before you start, install the audio drivers from the Whisplay HAT repository and read the offline build tutorial for the Pi 5, because the readme recommends the Pi 5 with 8GB of RAM for offline builds and the two boards have different practical limits.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. PiSugar/whisplay-ai-chatbot on GitHub
4. README
5. Releases