From 02967a530c5c093533480b864d12d9e6cdc0f7c4 Mon Sep 17 00:00:00 2001 From: Dmitry Kovalev Date: Wed, 1 Aug 2018 12:01:56 -0700 Subject: [PATCH] Update documentation. Change-Id: I6115b9914e4e4110714f2cad3530dc94f87758ab --- CHANGES.md | 38 ++++++++++++ CONTRIBUTING.md | 34 ++++++++++ HACKING.md | 162 +++++++++++++++++++++++++++++++++++------------- README.md | 94 +++++++++++----------------- docs/vision.md | 33 ++++++++-- docs/voice.md | 19 +++--- 6 files changed, 265 insertions(+), 115 deletions(-) create mode 100644 CHANGES.md create mode 100644 CONTRIBUTING.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 00000000..8dc3b0b3 --- /dev/null +++ b/CHANGES.md @@ -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 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..addcd6c6 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 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/ diff --git a/HACKING.md b/HACKING.md index 4a73c3b8..e1b62419 100644 --- a/HACKING.md +++ b/HACKING.md @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index 5bf3a8a0..c90f745d 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,57 @@ # AIY Projects - +## 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] +* support-aiyprojects@google.com + +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 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 +[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 \ No newline at end of file diff --git a/docs/vision.md b/docs/vision.md index e1c10431..d70efbd4 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -3,11 +3,31 @@ ## Hardware * SOC: Myriad 2450 -* MCU: ATSAMD09D14 -* LED Driver: KTD2027A -* Crypto: ATECC608A (optional) +* MCU: ATSAMD09D14 [I2C address: 0x51] +* LED Driver: KTD2027A [I2C address: 0x30] +* Crypto (optional): ATECC608A [I2C address: 0x60] * IMU: BMI160 +## Drivers + +* MCU driver: `modinfo aiy-io-i2c` +* MCU PWM driver: `modinfo pwm-aiy-io` +* MCU GPIO driver: `modinfo gpio-aiy-io` +* MCU ADC driver: `modinfo aiy-adc` +* LED driver: `modinfo leds-ktd202x` +* Software PWM driver for buzzer: `modinfo pwm-soft` +* Myriad driver: `modinfo aiy-vision` + +To reset MCU: +``` +echo 1 | sudo tee /sys/bus/i2c/devices/1-0051/reset +``` + +To get MCU status message (including firmware version) and last error code: +``` +cat /sys/bus/i2c/devices/1-0051/{status_message,error_code} +``` + ## Pinout (40-pin header) ``` @@ -35,10 +55,11 @@ ## Troubleshooting -Sometimes Pi Zero doesn't work stable and fails with different kernel errors: -[Issue #346](https://github.com/google/aiyprojects-raspbian/issues/346). - +Sometimes Pi Zero doesn't work stable and fails with different kernel errors, +e.g. [Issue #346]. Run ``` echo "over_voltage=4" | sudo tee -a /boot/config.txt ``` and then reboot. + +[Issue #346]: https://github.com/google/aiyprojects-raspbian/issues/346 \ No newline at end of file diff --git a/docs/voice.md b/docs/voice.md index 5f2a2f7a..7f838025 100644 --- a/docs/voice.md +++ b/docs/voice.md @@ -9,10 +9,10 @@ **Voice Bonnet** -* Audio Codec: ALC5645 -* MCU: ATSAMD09D14 -* LED Driver: KTD2027B -* Crypto: ATECC608A (optional) +* Audio Codec: ALC5645 [I2C address: 0x1A] +* MCU: ATSAMD09D14 [I2C address: 0x52] +* LED Driver: KTD2027B [I2C address: 0x31] +* Crypto (optional): ATECC608A [I2C address: 0x62] * Microphone: SPH1642HT5H-1 x 2 ## Drivers @@ -35,10 +35,13 @@ echo "dtoverlay=googlevoicehat-soundcard" | sudo tee -a /boot/config.txt **Voice Bonnet** -Manual overlay load (EEPROM overlay must be disabled): -``` -sudo dtoverlay aiy-voicebonnet -``` +* MCU driver: `modinfo aiy-io-i2c` +* MCU PWM driver: `modinfo pwm-aiy-io` +* MCU GPIO driver: `modinfo gpio-aiy-io` +* MCU ADC driver: `modinfo aiy-adc` +* LED driver: `modinfo leds-ktd202x` +* Software PWM driver for buzzer: `modinfo pwm-soft` +* Sound drivers: `modinfo rl6231 rt5645 snd_aiy_voicebonnet` ## Pinout (40-pin header)