diff --git a/docs/changes.md b/CHANGES.md similarity index 100% rename from docs/changes.md rename to CHANGES.md diff --git a/HACKING.md b/HACKING.md index 3fd9b07e..38e1dfff 100644 --- a/HACKING.md +++ b/HACKING.md @@ -1,189 +1,226 @@ -# System updates +# Install the AIY Projects software -We periodically update the SD card image that supports both the Vision Kit and -Voice Kit. Each release is based on [Raspbian][raspbian], with a few -customizations, and they are tested on various Raspberry Pi models. +This page describes how to install all software for an AIY Vision Bonnet or Voice Bonnet. -You can flash the latest system image for your kit as follows: +If you're updating an existing AIY kit or starting from scratch, we recommend you [install our +pre-built image](#install-our-pre-build-aiy-projects-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-aiy-software-on-an-existing-raspbian-system). -1. Download the latest `.img.xz` file from the [releases page on GitHub][github-releases]. (For release details, see the [Change log][changelog].) -1. Use an adapter to connect your MicroSD card to your computer. -1. Use a program such as [balenaEtcher](https://www.balena.io/etcher/) to flash the `.img.xy` file onto your MicroSD card. (balenaEtcher is free and works on Windows, Mac OS, and Linux.) +## 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][github-releases]. + (For release details, see the [Change log][changelog].) +1. Plug-in your MicroSD card to your computer with an adapter. +1. Use a program such as [balenaEtcher](https://www.balena.io/etcher/) 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! -If you prefer to update an existing Raspbian image yourself, follow the steps below. -## AIY Debian Package Repo +## 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][raspbian]. + +### 1. Add the AIY Debian packages repo Add AIY package repo: -``` + +```bash echo "deb https://packages.cloud.google.com/apt aiyprojects-stable main" | tee /etc/apt/sources.list.d/aiyprojects.list ``` -Add Google package keys from https://www.google.com/linuxrepositories/: -``` +Add Google package keys: + +```bash curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - ``` Update and install the latest system updates (including kernel): -``` + +```bash sudo apt-get update sudo apt-get upgrade ``` Reboot after update: -``` + +```bash sudo reboot ``` -## AIY Debian Packages - -### Vision and Voice Bonnets - -* `aiy-dkms` contains MCU drivers: - - * `aiy-io-i2c` — firmware update support - * `pwm-aiy-io` — [PWM][kernel-pwm] sysfs interface - * `gpio-aiy-io` — [GPIO][kernel-gpio] sysfs interface - * `aiy-adc` — [Industrial I/O][kernel-iio] 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][protobuf-issue] is fixed) along with [Google Assistant Library][assistant-library] for different Raspberry Pi boards. +### 2. Install optional packages -### Vision Bonnet +This package is needed only if you're using the light-up RGB button that's included with +the Vision/Voice Bonnet: -* `aiy-vision-dkms` contains `aiy-vision` Myriad driver -* `aiy-vision-firmware` contains Myriad firmware -* `aiy-models` contains [models][aiy-models] for on-device inference: +```bash +sudo apt-get install -y leds-ktd202x-dkms +``` - * Face Detection - * Object Detection - * Image Classification - * Dish Detection - * Dish Classification - * iNaturalist Classification (plants, insects, birds) +This package is needed only if you're using the piezo buzzer included with the Vision Bonnet: -### Voice Bonnet +```bash +sudo apt-get install -y pwm-soft-dkms +``` -* `aiy-voicebonnet-soundcard-dkms` contains sound drivers: +### 3. Install required packages - * `rl6231` - * `rt5645` - * `snd_aiy_voicebonnet` +Use the following commands to install packages for either the +[Vision Bonnet](#install-vision-bonnet-packages) or the +[Voice Bonnet/HAT](#install-voice-bonnethat-packages). -## AIY Setup +#### Install Vision Bonnet packages -### Vision Bonnet (minimal) +Install the bonnet drivers: -Install drivers: ```bash sudo apt-get install -y aiy-vision-dkms ``` -Install package with [models][aiy-models]: +Install the [example vision models][aiy-models]: + ```bash sudo apt-get install -y aiy-models ``` -Install optimized `protobuf` library for better performance: +Install the optimized `protobuf` library for better performance: + ```bash sudo apt-get install -y aiy-python-wheels ``` Reboot: + ```bash sudo reboot ``` -and verify that `dmesg` output contains `Myriad ready` message: + +Then verify that `dmesg` output contains `Myriad ready` message: + ```bash dmesg | grep -i "Myriad ready" ``` -### Voice Bonnet (minimal) +#### Install Voice Bonnet/HAT packages + +Install the bonnet/HAT drivers: -Install drivers: ```bash -sudo apt-get install -y aiy-voicebonnet-soundcard-dkms aiy-dkms +sudo apt-get install -y aiy-voicebonnet-soundcard-dkms ``` Install PulseAudio: + ```bash 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 ``` -Install optimized `protobuf` and `google-assistant-library`: +Install the Raspberry-Pi-compatible `google-assistant-library`: + ```bash sudo apt-get install -y aiy-python-wheels ``` Reboot: + ```bash sudo reboot ``` -and verify that you can record + +Then verify that you can record audio: + ```bash arecord -f cd test.wav ``` -and play a sound: -```bash -aplay test.wav -``` -### Vision and Voice Bonnet (additional) +...and play a sound: -Install LED driver to control button RGB LED: ```bash -sudo apt-get install -y leds-ktd202x-dkms +aplay test.wav ``` -Install software PWM driver to control buzzer: -```bash -sudo apt-get install -y pwm-soft-dkms -``` +Additionally, the Voice Bonnet/HAT requires access to Google Cloud APIs. +To complete this setup, follow the [Voice Kit setup instructions][aiy-voice-setup]. -Reboot: -```bash -sudo reboot -``` -## Python Library +### 4. Install the AIY Projects Python library -### Installation +Finally, you need to install the [AIY Projects Python library]( +https://aiyprojects.readthedocs.io/en/latest/index.html). -Make sure you already installed `aiy-python-wheels`: -```bash -sudo apt-get install -y aiy-python-wheels -``` +First make sure you have `git` installed: -Install `git` first: ```bash sudo apt-get install -y git ``` -Then clone `aiyprojects-raspbian` repo from GitHub: +Then clone this `aiyprojects-raspbian` repo from GitHub: + ```bash git clone https://github.com/google/aiyprojects-raspbian.git AIY-projects-python ``` -And install library in editable mode: +And now install the Python library in editable mode: + ```bash sudo pip3 install -e AIY-projects-python/src ``` -### Cloud access for Voice HAT or Voice Bonnet -To access the cloud services you need to register a project and generate -credentials for cloud APIs. This is documented in the -[setup instructions][aiy-voice-setup] on the webpage. +## 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-io` — [PWM][kernel-pwm] sysfs interface + * `gpio-aiy-io` — [GPIO][kernel-gpio] sysfs interface + * `aiy-adc` — [Industrial I/O][kernel-iio] 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][protobuf-issue] is fixed) along with [Google Assistant Library][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][aiy-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` + + + -[changelog]: CHANGES.html +[changelog]: CHANGES.md [raspbian]: https://www.raspberrypi.org/downloads/raspbian/ [image-flash]: https://www.raspberrypi.org/documentation/installation/installing-images/ [aiy-models]: https://aiyprojects.withgoogle.com/models/ diff --git a/README.md b/README.md index bdb2a7e0..8eb1c31a 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ assembly guide and other maker guides at [aiyprojects.withgoogle.com]. If you just need the Python API reference, see [aiyprojects.readthedocs.io]. Also have a look at the [example code][aiy-github-examples]. -If you need to update your kit's system image (whether you're using Google's provided image or -you're starting with Raspbian), read the [system updates guide][HACKING.md]. +If you want to flash the latest AIY system image or install AIY packages on an existing +Raspbian system, read the [system updates guide][HACKING.md]. ## Releases @@ -52,7 +52,7 @@ or provides incorrect responses), try the following: [HACKING.md]: HACKING.md [CONTRIBUTING.md]: CONTRIBUTING.md [downloads]: https://github.com/google/aiyprojects-raspbian/releases -[changelog]: https://aiyprojects.readthedocs.io/en/latest/changes.html +[changelog]: CHANGES.md [aiyprojects.withgoogle.com]: https://aiyprojects.withgoogle.com [aiyprojects.readthedocs.io]: https://aiyprojects.readthedocs.io diff --git a/docs/index.rst b/docs/index.rst index 45c65acf..c2de52a3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,9 +41,9 @@ assembly guides and makers guides, go to :caption: Other docs :maxdepth: 2 - Change log Source code (GitHub) - Raspbian setup (GitHub) + Change log (GitHub) + Software setup (GitHub) Contribution guide (GitHub) API indices