Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Install the AIY Projects software

This page describes how to install all software for an AIY Vision Bonnet or Voice Bonnet.

If you're updating an existing AIY kit or starting from scratch, we recommend you install our pre-built image. But if you have your own Raspbian system that you'd like to use with an AIY kit, then you can install our software on your existing Raspbian system.

Install our pre-build AIY Projects image

To flash our latest pre-built system image onto an SD card, follow these steps:

  1. Download the latest .img.xz file from our releases page on GitHub. (For release details, see the Change log.)
  2. Plug-in your MicroSD card to your computer with an adapter.
  3. Use a program such as balenaEtcher to flash the .img.xy file onto your MicroSD card. (balenaEtcher is free and works on Windows, Mac, and Linux.)

When flashing is done, put the MicroSD card back in your kit and you're good to go!

Install AIY software on an existing Raspbian system

Follow these steps to install the AIY drivers and software onto an existing Raspbian system.

Note: This process is compatible with Raspbian Buster (2019-06-20) or later only. Before you start, be sure you have the latest version of Raspbian.

1. Add the AIY Debian packages repo

Add AIY package repo:

echo "deb aiyprojects-stable main" | sudo tee /etc/apt/sources.list.d/aiyprojects.list

Add Google package keys:

curl | sudo apt-key add -

Update and install the latest system updates (including kernel):

sudo apt-get update
sudo apt-get upgrade

Reboot after update:

sudo reboot

2. Install optional packages

RGB Button Driver

This package is needed only if you're using the light-up RGB button that's included with the Vision/Voice Bonnet:

sudo apt-get install -y leds-ktd202x-dkms

Run sudo modprobe leds_ktd202x to load the driver and sudo modprobe -r leds_ktd202x to unload it. Vision/Voice Bonnet does this automatically via built-in device tree overlay saved in the board's EEPROM.

Piezo Buzzer Driver

This package is needed only if you're using the piezo buzzer included with the Vision Bonnet:

sudo apt-get install -y pwm-soft-dkms

Pi Zero Ethernet-over-USB

This package is needed only if you're using Ethernet-over-USB on Pi Zero:

sudo apt-get install -y aiy-usb-gadget

Default Pi IP address is, host IP address will be assigned automatically.

Support for AIY Projects app

In order to make the Pi work with the AIY Projects app:

sudo apt-get install -y aiy-bt-prov-server

3. Install required packages

Use the following commands to install packages for either the Vision Bonnet or the Voice Bonnet/HAT.

Install Vision Bonnet packages

Install the bonnet drivers:

sudo apt-get install -y aiy-vision-dkms

Install the example vision models:

sudo apt-get install -y aiy-models

Install the optimized protobuf library for better performance:

sudo apt-get install -y aiy-python-wheels

Enable camera module:

echo "start_x=1" | sudo tee -a /boot/config.txt

Set GPU memory to 128MB:

echo "gpu_mem=128" | sudo tee -a /boot/config.txt

Make sure to not use GPIO6 for SPI0 (required since 5.4 kernel):

echo "dtoverlay=spi0-1cs,cs0_pin=7" | sudo tee -a /boot/config.txt


sudo reboot

Then verify that dmesg output contains Myriad ready message:

dmesg | grep -i "Myriad ready"

You can also verify that camera is working fine by watching video on the connected monitor:

raspivid -t 0

Or use ffplay to get video output on the host machine:

ssh pi@raspberrypi.local "raspivid --nopreview --timeout 0 -o -" | ffplay -loglevel panic -

Install Voice Bonnet/HAT packages

Voice HAT does not require any driver installation. You only need to load device tree overlay on boot:

echo "dtoverlay=googlevoicehat-soundcard" | sudo tee -a /boot/config.txt

Voice Bonnet requires driver installation:

sudo apt-get install -y aiy-voicebonnet-soundcard-dkms

Disable built-in audio:

sudo sed -i -e "s/^dtparam=audio=on/#\0/" /boot/config.txt

Install PulseAudio:

sudo apt-get install -y pulseaudio
sudo mkdir -p /etc/pulse/daemon.conf.d/
echo "default-sample-rate = 48000" | sudo tee /etc/pulse/daemon.conf.d/aiy.conf

You may also need to disable module-suspend-on-idle PulseAudio module for the Voice HAT:

sudo sed -i -e "s/^load-module module-suspend-on-idle/#load-module module-suspend-on-idle/" /etc/pulse/

If you want to use Google Assistant, install the Raspberry-Pi-compatible google-assistant-library python library from aiy-python-wheels package:

sudo apt-get install -y aiy-python-wheels


sudo reboot

Then verify that you can record audio:

arecord -f cd test.wav

...and play a sound:

aplay test.wav

Additionally, the Voice Bonnet/HAT requires access to Google Cloud APIs. To complete this setup, follow the Voice Kit setup instructions.

4. Install the AIY Projects Python library

Finally, you need to install the AIY Projects Python library.

First make sure you have git installed:

sudo apt-get install -y git

Then clone this aiyprojects-raspbian repo from GitHub:

git clone AIY-projects-python

And now install the Python library in editable mode:

sudo pip3 install -e AIY-projects-python

Appendix: List of all AIY Debian packages

The following is just a reference of all packages that are installed when you follow the above steps.

Vision and Voice Bonnets

  • aiy-dkms contains MCU drivers:

    • aiy-io-i2c — firmware update support
    • pwm-aiy-ioPWM sysfs interface
    • gpio-aiy-ioGPIO sysfs interface
    • aiy-adcIndustrial I/O ADC interface
  • aiy-io-mcu-firmware contains MCU firmware update service

  • leds-ktd202x-dkms contains leds-ktd202x LED driver

  • pwm-soft-dkms contains pwm-soft software PWM driver

  • aiy-python-wheels contains optimized protobuf python wheel (until this issue is fixed) along with Google Assistant Library for different Raspberry Pi boards.

Vision Bonnet

  • aiy-vision-dkms contains aiy-vision Myriad driver

  • aiy-vision-firmware contains Myriad firmware

  • aiy-models contains models for on-device inference:

    • Face Detection
    • Object Detection
    • Image Classification
    • Dish Detection
    • Dish Classification
    • iNaturalist Classification (plants, insects, birds)

Voice Bonnet

  • aiy-voicebonnet-soundcard-dkms contains sound drivers:

    • rl6231
    • rt5645
    • snd_aiy_voicebonnet