From 7fd41986dd8fb8fc7ea38321ea7bdb05b18ee216 Mon Sep 17 00:00:00 2001 From: nico Date: Sat, 21 Jan 2017 18:35:14 +0100 Subject: [PATCH] update doc, add quickstart and pre compiled raspbian image --- Docs/installation.md | 34 +------------ Docs/installation/quickstart.md | 76 ++++++++++++++++++++++++++++ Docs/installation/raspbian_jessie.md | 25 ++++++--- Docs/settings.md | 20 +------- README.md | 7 ++- 5 files changed, 99 insertions(+), 63 deletions(-) create mode 100644 Docs/installation/quickstart.md diff --git a/Docs/installation.md b/Docs/installation.md index 45cebc01..6b9864b3 100644 --- a/Docs/installation.md +++ b/Docs/installation.md @@ -80,37 +80,7 @@ Then play the recorded audio file mplayer test.wav ``` -You can then test that your Kalliope is working by using the "bonjour" order integrated in the [default brain](../kalliope/brain.yml). -Start kalliope: -```bash -kalliope start -``` - -> **Note:** Do not start Kalliope as root user or with sudo - -Kalliope will load default settings and brain, the output should looks the following -```bash -Starting event manager -Events loaded -Starting Kalliope -Press Ctrl+C for stopping -Starting REST API Listening port: 5000 -``` - -Then speak the hotwork out loud to wake up Kalliope. By default, the hotwork is "Kalliopé" with the french pronunciation. -If the trigger is successfully raised, you'll see "say something" into the console. -```bash -2016-12-05 20:54:21,950 :: INFO :: Keyword 1 detected at time: 2016-12-05 20:54:21 -Say something! -``` - -Then you can say "bonjour" and listen the Kalliope response. -```bash -Say something! -Google Speech Recognition thinks you said Bonjour -Order matched in the brain. Running synapse "say-hello-fr" -Waiting for trigger detection -``` +Your installation is now complete, let's take a look now to the [quickstart documentation](installation/quickstart.md) to learn how to use Kalliope. ## Get a starter configuration We create some starter configuration that only need to be downloaded and then started. @@ -120,5 +90,5 @@ Those repositories provide you a basic structure to start playing with kalliope. - [English starter config](https://github.com/kalliope-project/kalliope_starter_en) -## Next: Create you own bot +## Next: If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md). diff --git a/Docs/installation/quickstart.md b/Docs/installation/quickstart.md new file mode 100644 index 00000000..109ae87d --- /dev/null +++ b/Docs/installation/quickstart.md @@ -0,0 +1,76 @@ +# Kalliope quick start + +Kalliope needs two files to works, a `settings.yml` and a `brain.yml`. +As files are written on YAML syntax, we strongly recommend you to use an editor(IDE) like [VS Code](https://code.visualstudio.com/) or [Atom](https://atom.io/). + +If you are using kalliope from a Rpi, the idea would be to configure your assistant from your main computer with an IDE and then push your config folder into your Rpi. + +We made starter kits that only needs to be cloned, placed into the Rpi and launched. +- [French starter kit](https://github.com/kalliope-project/kalliope_starter_fr) +- [English starter kit](https://github.com/kalliope-project/kalliope_starter_en) + +Those repositories provide you a structure to start playing and learning basics of Kalliope. +Download the starter kit of your choice and open the folder with your IDE. + +When you start kalliope using the CLI (`kalliope start`), the program will try to load your `settings.yml` and `brain.yml` in the following order: +- From your current folder, E.g `/home/pi/my_kalliope/settings.yml` +- From `/etc/kalliope/settings.yml` +- From the default `settings.yml`. You can take a look into the default [`settings.yml`](../kalliope/settings.yml) file which is located in the root of the project tree. + +This a common tree of a Kalliope configuration folder: +``` +kalliope_config/ +├── brains +│   └── included_brain.yml +├── brain.yml +├── files +│   └── kalliope-EN-13samples.pmdl +└── settings.yml +``` + +Let's open the main brain file. You'll see there are some included sub brains file. +```yml +- includes: + - brains/say.yml +``` + +If you open the `say.yml` file from the brains folder, you'll see a basic synapse that uses the [neuron](../neurons.md) "[Say](../../kalliope/neurons/say)" and make Kalliope speaks out loud "Hello sir" when you say "hello". +Move into the folder and then start Kalliope: +```bash +cd /path/to/the/starter_kit +kalliope start +``` +> **Note:** Do not start Kalliope as root user or with sudo + +Kalliope will load settings and brain, the output should looks the following +```bash +Starting event manager +Events loaded +Starting Kalliope +Press Ctrl+C for stopping +Starting REST API Listening port: 5000 +Waiting for trigger detection +``` + +Then speak the hotwork out loud to wake up Kalliope (with the right pronunciation depending on your starter kit. "Kalliopé" in french, "Kalliopee" in English). +If the trigger is successfully raised, you'll see "say something" into the console. +```bash +2016-12-05 20:54:21,950 :: INFO :: Keyword 1 detected at time: 2016-12-05 20:54:21 +Say something! +``` + +Then you can say "hello" and listen the Kalliope response. +```bash +Say something! +Google Speech Recognition thinks you said hello +Order matched in the brain. Running synapse "say-hello" +Waiting for trigger detection +``` + +That's it! You are ready to customize your assistant! + +## What next? + +- See what you can customize in your [settings](../settings.md) like changing the hotword, the STT or TTS engine. +- Create your [brain](../brain.md) +- See the list of [available neurons](../neuron_list.md) diff --git a/Docs/installation/raspbian_jessie.md b/Docs/installation/raspbian_jessie.md index 542fd9b6..774f9eab 100644 --- a/Docs/installation/raspbian_jessie.md +++ b/Docs/installation/raspbian_jessie.md @@ -1,8 +1,19 @@ # Kalliope requirements for Raspbian +## Install the pre-compiled disk image -## Supported Version +Download the last image [from the release page](https://github.com/kalliope-project/kalliope/releases) of Kalliope and load it as usual into your SD card. +**Login:** pi +**Password:** raspberry + +Once installed, use the `raspi-config` command to expend the file system and fill the whole available space on your SD card. +The SSH server is already active. You only need to get the ip of your Rpi via the command `ip a` and then connect via your favourite SSH client. +We placed in `/home/pi` the two starter config we made for [French](https://github.com/kalliope-project/kalliope_starter_fr) and [English](https://github.com/kalliope-project/kalliope_starter_en). + +## Manual installation + +Supported Raspbian images: [raspbian-2016-09-28](http://downloads.raspberrypi.org/raspbian/images/raspbian-2016-09-28/) [raspbian-2016-11-29](http://downloads.raspberrypi.org/raspbian/images/raspbian-2016-11-29/) [raspbian-2017-01-10](http://downloads.raspberrypi.org/raspbian/images/raspbian-2017-01-10/) @@ -11,7 +22,7 @@ > **Note:** The first Raspberry Pi is not officially supported. The installation will works but a single core with only 700Mhz may produce a some latencies. -## Debian packages requirements +### Debian packages requirements Install some required system libraries and software: @@ -26,12 +37,6 @@ wget https://bootstrap.pypa.io/get-pip.py sudo python get-pip.py ``` -## Raspberry Pi configuration - -This part deals with the special configuration needed to get kalliope working on a RPi. - -### Packages - On a Raspberry Pi, pulseaudio is not installed by default ```bash sudo apt-get install pulseaudio pulseaudio-utils @@ -42,6 +47,10 @@ Start the pulseaudio server pulseaudio -D ``` +## Raspberry Pi configuration + +This part deals with the special configuration needed to get kalliope working on a RPi. + ### Microphone configuration Get your output card diff --git a/Docs/settings.md b/Docs/settings.md index ba7a4d6a..9e09edf6 100644 --- a/Docs/settings.md +++ b/Docs/settings.md @@ -1,24 +1,6 @@ # Kalliope settings -This part of the documentation explains the main configuration of Kalliope. - -Kalliope needs two files to works, a `settings.yml` and a `brain.yml`. Files are written on YAML syntax. - -When you start kalliope using the CLI, the program will try to load your settings.yml and brain.yml in the following order: -- From you current folder, E.g `/home/pi/my_kalliope/settings.yml` -- From `/etc/kalliope/settings.yml` -- From the default `settings.yml`. You can take a look into the default [`settings.yml`](../kalliope/settings.yml) file which is located in the root of the project tree. - -This a common tree of a Kalliope configuration folder: -``` -kalliope_config/ -├── brains -│   └── included_brain.yml -├── brain.yml -├── files -│   └── kalliope-FR-13samples.pmdl -└── settings.yml -``` +This part of the documentation explains the main configuration of Kalliope placed in the `settings.md` file. ## Triggers configuration diff --git a/README.md b/README.md index 3ac41c79..bde7c220 100644 --- a/README.md +++ b/README.md @@ -26,13 +26,12 @@ Kalliope is easy-peasy to use, see the hello world ## Installation -- [Kalliope installation documentation](Docs/installation.md) +- [Kalliope installation documentation](Docs/installation.md) (Ubuntu/Debian/Raspbian) +- [Pre-compiled disk image for Raspberry](Docs/installation/raspbian_jessie.md) ## Quick start -We made starter kits that only needs to be cloned and launched. Starter kits can help you to learn basics of Kalliope -- [French starter kit](https://github.com/kalliope-project/kalliope_starter_fr) -- [English starter kit](https://github.com/kalliope-project/kalliope_starter_en) +Once installed, you can start learning basics of Kalliope from a [quick start configuration](Docs/installation/quickstart.md) ## Usage