Skip to content
This repository has been archived by the owner on Feb 9, 2023. It is now read-only.

Commit

Permalink
reorganize and clarify instructions for AIY system updates;
Browse files Browse the repository at this point in the history 
move changelog back to CHANGES.md at root

Change-Id: I1109d0bbdefd3449334bb1b0765df3a4a7bf6ad2
  • Loading branch information
@scottamain
scottamain committed Nov 7, 2019
1 parent 94fa0d3 commit b7ec451
Show file tree
Hide file tree
Showing 4 changed files with 129 additions and 92 deletions.
0 docs/changes.md → CHANGES.md
View file
File renamed without changes.
211 changes: 124 additions & 87 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
@@ -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/
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ assembly guides and makers guides, go to
:caption: Other docs
:maxdepth: 2

Change log <changes>
Source code (GitHub) <https://github.com/google/aiyprojects-raspbian>
Raspbian setup (GitHub) <https://github.com/google/aiyprojects-raspbian/blob/aiyprojects/HACKING.md>
Change log (GitHub) <https://github.com/google/aiyprojects-raspbian/blob/aiyprojects/CHANGES.md>
Software setup (GitHub) <https://github.com/google/aiyprojects-raspbian/blob/aiyprojects/HACKING.md>
Contribution guide (GitHub) <https://github.com/google/aiyprojects-raspbian/blob/aiyprojects/CONTRIBUTING.md>

API indices
Expand Down

0 comments on commit b7ec451

Please sign in to comment.