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

Commit

Permalink
Update documentation.
Browse files Browse the repository at this point in the history 
Change-Id: I6115b9914e4e4110714f2cad3530dc94f87758ab
  • Loading branch information
@dmitriykovalev
dmitriykovalev committed Aug 1, 2018
1 parent 7183f09 commit 02967a5
Show file tree
Hide file tree
Showing 6 changed files with 265 additions and 115 deletions.
38 changes: 38 additions & 0 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Changelog

All SD card images can be found at [releases][github-releases] page.

## AIY Kits Release 2018-08-XX

**Bug Fixes**

* Fix PulseAudio infinite loop with Voice Bonnet
* Fix PulseAudio volume control
* Fix gpiozero LED on/off bug
* Fix local USB networking on macOS
* Fix HACKING.md
* Fix check_audio.py

**Improvements**

* Add Makefile for common shortcuts
* Add vision unit tests for all models and examples
* Add video streaming support (experimental)
* Add Cloud IOT support (experimental)
* Add more documentation (pinouts, drivers, trobuleshooting, etc.)
* Add new examples and update existing ones
* Add CHANGES.md to track release changes
* Add more vision examples
* Remove unnecessary files (e.g. ALSA configs)
* Update vision driver to support mmap syscall
* Update sound driver to support latest Raspbian image

## AIY Kits Release 2018-04-13

## AIY Kits Release 2018-02-21

## AIY Kits Release 2017-12-18

## VoiceKit Classic Image 2017-09-11

[github-releases]: https://github.com/google/aiyprojects-raspbian/releases
34 changes: 34 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Contributions

We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.

## Scope of Contributions

This project consists of the support libraries (audio, gRPC, etc) required for
AIY Projects, as well as simple examples to experiment with and build upon.

Please limit pull requests to bug fixes or improvements to code or documentation
clarity. If you've added new examples and you'd like to publish your fork for
others to use, you can post on [hackster.io] or other channels.

## Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution,
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.

## Code reviews

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult [GitHub Help] for more
information on using pull requests.

[hackster.io]: https://www.hackster.io/
[GitHub Help]: https://help.github.com/articles/about-pull-requests/
162 changes: 118 additions & 44 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,145 @@
# Setting up the image

We recommend using [the latest image](https://dl.google.com/dl/aiyprojects/aiyprojects-latest.img.xz) we
provide. Those images are based on [Raspbian](https://www.raspberrypi.org/downloads/raspbian/),
with a few customizations and are tested on the Raspberry Pi 3, 3B+ and Zero. If you prefer
to setup Raspbian yourself, there are some manual steps you need to take.
## Overview

## Installing the dependencies
We recommend using [the latest image][github-releases] we provide. Those images
are based on [Raspbian][raspbian], with a few customizations and are tested on
the different Raspberry Pi models. If you prefer to setup Raspbian yourself,
there are some manual steps you need to take.

First, make sure you have `git` installed and clone this repository in
`~/AIY-projects-python`:
## AIY Package Repo

```shell
sudo apt-get install git
cd
git clone https://github.com/google/aiyprojects-raspbian.git AIY-projects-python
Add AIY package repo:
```
echo "deb https://dl.google.com/aiyprojects/deb stable main" | sudo tee -a /etc/apt/sources.list.d/aiyprojects.list
```

Add Google package keys from https://www.google.com/linuxrepositories/:
```
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
```

Then, install the project dependencies and setup the services:
Update and install the latest system updates (including kernel):
```
sudo apt-get update
sudo apt-get upgrade
```

``` shell
cd ~/AIY-projects-python/src
sudo pip3 install .
Reboot after update:
```
sudo reboot
```

## AIY Packages

Package `aiy-dkms` contains MCU and Myriad drivers:

* `aiy-io-i2c`
* `pwm-aiy-io`
* `gpio-aiy-io`
* `aiy-adc`
* `aiy-vision`

Package `aiy-vision-firmware` contains Myriad firmware for Vision Bonnet.

Package `aiy-io-mcu-firmware` contains MCU firmware update service.

## Configuring the Voice HAT driver
Package `leds-ktd202x-dkms` contains LED driver:

To use the Voice HAT, your kernel needs to be 4.9 or later. This is available
on Raspbian 2017-07-05 and later. Voice HAT driver is automatically configured
by aiy_voice_classic service.
* `leds-ktd202x`

After your Pi has rebooted with the driver enabled, run:
Package `pwm-soft-dkms` contains Software PWM driver:

* `pwm-soft`

Package `aiy-voicebonnet-soundcard-dkms` contains sound drivers:

* `rl6231`
* `rt5645`
* `snd_aiy_voicebonnet`

Package `aiy-voicebonnet-routes` contains ALSA UCM files for Voice Bonnet.

Package `aiy-models` contains [models][aiy-models] for Vision Bonnet.

### Vision Bonnet Minimal Setup

```
cd ~/AIY-projects-python
sudo scripts/install-alsa-config.sh
env/bin/python checkpoints/check_audio.py
sudo apt-get install aiy-dkms
sudo reboot
```

Don't skip running `check_audio.py` before rebooting, as it has an important
effect on the state of ALSA, the sound architecture.
Run `dmesg` and check it contains `Myriad ready` message.

## Get cloud credentials
In additional you can install package with [models][aiy-models]:

To access the cloud services you need to register a project and generate
credentials for cloud APIs. This is documented in the
[setup instructions](https://aiyprojects.withgoogle.com/voice#google-assistant--get-credentials) on the
webpage.
```
sudo apt-get install aiy-models
```

## Running automatically
### Voice Bonnet Minimal Setup

You can find sample scripts in the `src` directory showing how to use the
Assistant SDK.
```
sudo apt-get install pulseaudio
mkdir -p ~/.config/pulse/
echo "default-sample-rate = 48000" > ~/.config/pulse/daemon.conf
```

To execute any of these scripts on the Raspberry Pi, login to it and run
(replacing the filename with the script you want to run):
```
sudo apt-get install aiy-dkms aiy-voicebonnet-soundcard-dkms aiy-voicebonnet-routes
sudo reboot
```

``` shell
cd ~/AIY-projects-python
python3 src/examples/voice/assistant_library_demo.py
You should be able to record
```
arecord -f cd test.wav
```
and play
```
aplay test.wav
```
sound right now.

### Vision/Voice Bonnet Additional Setup

If you want the voice recognizer service to run automatically when the Pi
boots, you need to have a file in the `src` directory named `main.py`. You can
make a copy of one of the example scripts and rename it. Then run this command:
Install LED driver to control button RGB LED:
```
sudo apt-get install leds-ktd202x-dkms
```

``` shell
sudo cp ~/AIY-projects-python/systemd/voice-recognizer.service /lib/systemd/system
sudo systemctl enable voice-recognizer.service
Install Software PWM driver to control buzzer:
```
sudo apt-get install pwm-soft-dkms
echo "pwm-soft" | sudo tee -a /etc/modules
sudo modprobe pwm-soft
```

## Python Library

### Installation

Install `git` first:
```
sudo apt-get install git
```

Then clone `aiyprojects-raspbian` repo from GitHub:
```
git clone https://github.com/google/aiyprojects-raspbian.git AIY-projects-python
```

And install library in editable mode:
```
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](https://aiyprojects.withgoogle.com/voice#google-assistant--get-credentials) on the
webpage.

[raspbian]: https://www.raspberrypi.org/downloads/raspbian/
[aiy-models]: https://aiyprojects.withgoogle.com/models/
[github-releases]: https://github.com/google/aiyprojects-raspbian/releases
94 changes: 37 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,77 +1,57 @@
# AIY Projects

<img src="https://aiyprojects.withgoogle.com/static/images/icons/aiy-circular-logo.svg" width="40%">
## Overview

This repository contains an easy-to-use API for the AIY Vision Kit and
AIY Voice Kit.
You can use it for face detection and object recognition, or use it to create
voice commands with simple while loops - have a look at the
[demos](https://github.com/google/aiyprojects-raspbian/tree/aiyprojects/src/examples).
Documentation is at the [AIY Projects site](https://aiyprojects.withgoogle.com).
This repository contains an easy-to-use API for the [AIY Vision Kit][aiy-vision]
and [AIY Voice Kit][aiy-voice]. Have a look at [example code][aiy-github-examples]
to see how both kits can be used. Comprehensive documentation is at the
[AIY Projects Site][aiy-site].

If you're using Raspbian instead of Google's provided image, read
[HACKING.md](HACKING.md) for information on getting started.
[HACKING.md] for information on getting started.

For returning users:
The code for all AIY kits is in the `aiyprojects` branch, and is included in
images starting with aiyprojects-2017-12-18.img. The previous `voicekit` branch
contains code just for the Voice Kit, and the `master` branch contains the
original, deprecated Voice Recognizer demo.
For returning users. The code for all AIY kits is in the `aiyprojects` branch,
and is included in images starting with `aiyprojects-2017-12-18.img`.
The previous `voicekit` branch contains code just for the Voice Kit, and the
`master` branch contains the original deprecated `Voice Recognizer` demo.

## Support

If you're having trouble assembling your kit or running the demos,
try the [AIY Forums](https://www.raspberrypi.org/forums/viewforum.php?f=114).
If you're having trouble assembling your kit or running the demos, you can try

If you've found a bug in the AIY API or demos, you can look at the
[known issues](https://github.com/google/aiyprojects-raspbian/issues) or create
a new one, or even fix it yourself and send us a pull request.
* [AIY Forums][aiy-forums]
* [AIY Stack Overflow][aiy-stack-overflow]
* [AIY GitHub Issues][aiy-github-issues]
* [email protected]

If you've found a bug and fixed it yourself, please send us a pull request!
Check [CONTRIBUTING.md] for details.

If you've found a problem with the Assistant (for example, crashes in the
library or incorrect responses), you can try
[the G+ community](https://plus.google.com/communities/117537996116836200696),
[Stack Overflow](https://stackoverflow.com/questions/tagged/google-assistant-sdk),
or [the assistant-sdk-python repo](https://github.com/googlesamples/assistant-sdk-python/).

If you've had a problem after updating the source code, try downloading the
latest AIY image from the website, or alternatively run the following commands
in the dev terminal:

```
rm -r env
./scripts/install-deps.sh
```

## Contributions

We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.

### Scope of contributions

This project consists of the support libraries (audio, gRPC, etc) required for AIY Projects, as well as simple examples to experiment with and build upon.

Please limit pull requests to bug fixes or improvements to code or documentation clarity.
We're not accepting pull requests that add new commands to keep this project as simple as possible.
If you've added new commands and you'd like to publish your fork for others to use, you can post on [hackster.io](https://www.hackster.io/) or other channels.

### Contributor License Agreement
* [Assistant G+ community][assistant-google-plus]
* [Assistant Stack Overflow][assistant-stack-overflow]
* [Assistant GitHub Issues][assistant-github-issues]

Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution,
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.
##

You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.
<p align="center">
<img width="15%" src="https://aiyprojects.withgoogle.com/static/images/icons/aiy-circular-logo.svg">
</p>

### Code reviews
[HACKING.md]: HACKING.md
[CONTRIBUTING.md]: CONTRIBUTING.md

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult [GitHub Help] for more
information on using pull requests.
[aiy-site]: https://aiyprojects.withgoogle.com/
[aiy-vision]: https://aiyprojects.withgoogle.com/vision/
[aiy-voice]: https://aiyprojects.withgoogle.com/voice/

[aiy-forums]: https://www.raspberrypi.org/forums/viewforum.php?f=114
[aiy-stack-overflow]: https://stackoverflow.com/questions/tagged/google-aiy
[aiy-github-issues]: https://github.com/google/aiyprojects-raspbian/issues
[aiy-github-examples]: https://github.com/google/aiyprojects-raspbian/tree/aiyprojects/src/examples

[GitHub Help]: https://help.github.com/articles/about-pull-requests/
[assistant-google-plus]: https://plus.google.com/communities/117537996116836200696
[assistant-stack-overflow]: https://stackoverflow.com/questions/tagged/google-assistant-sdk
[assistant-github-issues]: https://github.com/googlesamples/assistant-sdk-python/issues
Loading

0 comments on commit 02967a5

Please sign in to comment.