Browse Source

Doc review + cleanup

add masnifest to include the readme

update python lib

doc factorization

review doc

update doc

update doc

update doc

update doc

update doc
nico 8 years ago
parent
commit
99899a7c83

+ 9 - 8
Docs/brain.md

@@ -13,6 +13,10 @@ An output action is
 
 Brain is expressed in YAML format (see YAML Syntax) and has a minimum of syntax, which intentionally tries to not be a programming language or script, 
 but rather a model of a configuration or a process.
+Kalliope will search her brain in the order bellow:
+- From you current folder, E.g `/home/pi/my_kalliope/brain.yml`
+- From `/etc/kalliope/brain.yml`
+- From the default `brain.yml`. You can take a look into the default [`brain.yml`](../kalliope/brain.yml) file which is located in the root of the project tree.
 
 Let's take a look on a basic synapse in our brain:
 
@@ -28,11 +32,7 @@ Let's take a look on a basic synapse in our brain:
 
 Let's break this down in sections so we can understand how the file is built and what each part means.
 
-The file starts with:
-```
----
-```
-This is a requirement for YAML to interpret the file as a proper document.
+The file starts with: `---`. This is a requirement for YAML to interpret the file as a proper document.
 
 Items that begin with a ```-``` are considered as list items. Items have the format of ```key: value``` where value can be a simple string or a sequence of other items.
 
@@ -95,7 +95,7 @@ neurons:
 Note here that parameters are indented with one tabulation bellow the neuron's name (YAML syntax requirement).
 
 In this example, the neuron called "say" will make Kalliope speak out loud the sentence in parameter **message**.
-See the complete list of [available neurons](neurons.md) here.
+See the complete list of [available neurons](neuron_list.md) here.
 
 ## Manage synapses
 
@@ -108,7 +108,6 @@ If you want a better visibly, or simply sort your actions in different files, yo
 
 To do that, use the import statement in the entry brain.yml file with the following syntax:
 ```
----
   - includes:
       - path/to/sub_brain.yml
       - path/to/another_sub_brain.yml
@@ -116,7 +115,6 @@ To do that, use the import statement in the entry brain.yml file with the follow
 
 E.g:
 ```
----
   - includes:
       - brains/rolling_shutter_commands.yml
       - brains/find_my_phone.yml
@@ -133,4 +131,7 @@ You can provide a default synapse in case none of them are matching when an orde
 >**Note:** This default synapse is optional.
 >**Note:** You need to define it in the settings.yml cf :[Setting](settings.md).
 
+## Next: Start Kalliope
+Now you take a look into the [CLI documentation](kalliope_cli.md) to learn how to start kalliope
+
 

+ 112 - 0
Docs/installation.md

@@ -0,0 +1,112 @@
+# Kalliope installation
+
+## Prerequisites
+
+Please follow link bellow to install requirements depending on your target environment:
+- [Raspbian (Raspberry Pi 2 & 3)](installation/raspbian_jessie.md)
+- [Ubuntu 14.04/16.04](installation/ubuntu_16.04.md)
+- [Debian Jessie](installation/debian_jessie.md)
+
+## Installation
+
+### Method 1 - User install using the PIP package
+
+You can install kalliope on your system by using Pypi:
+```
+sudo pip install kalliope
+```
+
+### Method 2 - Manual setup using sources
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+```
+
+Install the project:
+```
+sudo python setup.py install
+```
+
+### Method 3 - Developer install using Virtualenv
+
+Install the `python-virtualenv` package:
+```
+sudo apt-get install python-virtualenv
+```
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+cd kalliope
+```
+
+Generate a local python environment:
+```
+virtualenv venv
+```
+
+Install the project using the local environment:
+```
+venv/bin/pip install --editable .
+```
+
+### Method 4 - Developer, dependencies install only
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+cd kalliope
+```
+
+Install the python dependencies directly:
+```
+sudo pip install -r install/python_requirements.txt
+```
+
+## Test your env
+
+To ensure that you can record your voice, run the following command to capture audio input from your microphone:
+```
+rec test.wav
+```
+
+Press CTRL-C after capturing a sample of your voice.
+
+Then play the recorded audio file
+```
+mplayer test.wav
+```
+
+You can then test your Kalliope is working by using the "bonjour" order integrated in the [default brain](../kalliope/brain.yml).
+Start kalliope:
+```
+kalliope start
+```
+
+Kalliope will load default settings and brain, the output should looks the following
+```
+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. 
+```
+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.
+```
+Say something!
+Google Speech Recognition thinks you said Bonjour
+Order matched in the brain. Running synapse "say-hello-fr"
+Waiting for trigger detection
+```
+
+## Next: Create you own bot
+If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md).

+ 2 - 102
Docs/installation/debian_jessie.md

@@ -1,8 +1,6 @@
-# Kalliope installation on Debian Jessie
+# Kalliope requirements for Debian Jessie
 
-## Requirements
-
-### Debian packages requirements
+## Debian packages requirements
 
 Edit `/etc/apt/sources.list` and check that you have `contrib` and `non-free` and backports archives enabled:
 ```
@@ -25,101 +23,3 @@ You also need some packages from the backports:
 sudo apt-get install -t jessie-backports python-setuptools
 sudo apt-get install -t jessie-backports python-pyasn1
 ```
-
-## Installation
-
-### Method 1 - User install using the PIP package
-
-You can install kalliope on your system:
-```
-sudo pip install kalliope
-```
-
-Or just in your user home:
-```
-pip install --user kalliope
-```
-
-Run Kalliope from a shell:
-```
-kalliope start
-```
-
-### Method 2 - Manual user install using the git repository
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-```
-
-Install the project:
-```
-sudo python setup.py install
-```
-
-Run Kalliope from a shell:
-```
-kalliope start
-```
-
-### Method 3 - Developer install using Virtualenv
-
-Install the `python-virtualenv` package:
-```
-sudo apt-get install python-virtualenv
-```
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-cd kalliope
-```
-
-Generate a local python environment:
-```
-virtualenv venv
-```
-
-Install the project using the local environment:
-```
-venv/bin/pip install --editable .
-```
-
-Run Kalliope from a shell:
-```
-venv/bin/kalliope start
-```
-
-### Method 4 - Developer, dependencies install only
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-cd kalliope
-```
-
-Install the python dependencies directly:
-```
-sudo pip install -r install/python_requirements.txt
-```
-
-Run Kalliope from a shell directly:
-```
-python kalliope.py start
-```
-
-## Test your env
-
-To ensure that you can record your voice, run the following command to capture audio input from your microphone:
-```
-rec test.wav
-```
-
-Press CTRL-C after capturing a sample of your voice.
-
-Then play the recorded audio file
-```
-mplayer test.wav
-```
-
-If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](../settings.md).

+ 8 - 46
Docs/installation/raspbian_jessie.md

@@ -1,57 +1,19 @@
-# Kalliope installation on Raspbian
+# Kalliope requirements for Raspbian
 
-## Requirements
+## Debian packages requirements
 
-### Debian packages requirements
-
-Install some required system libraries and softwares:
+Install some required system libraries and software:
 
 ```
 sudo apt-get update
 sudo apt-get install git python-pip python-dev libsmpeg0 libttspico-utils libsmpeg0 flac dialog libffi-dev libffi-dev libssl-dev portaudio19-dev build-essential libssl-dev libffi-dev sox libatlas3-base mplayer
 ```
 
-## Installation
-
-### Method 1 - User install using the PIP package
-
-You can install kalliope on your system:
-```
-sudo pip install kalliope
-```
-
-Or just in your user home:
-```
-pip install --user kalliope
-```
-
-Run Kalliope:
-```
-kalliope start
-```
-
-### Method 2 - Manual user install using the git repository
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-```
-
-Install the project:
-```
-sudo python setup.py install
-```
-
-Run Kalliope from a shell:
-```
-kalliope start
-```
-
-# Raspberry Pi configuration
+## Raspberry Pi configuration
 
-This documentation deals with the special configuration needed for get kalliope working on a RPi.
+This part deals with the special configuration needed for get kalliope working on a RPi.
 
-## Packages
+### Packages
 
 On a Raspberry Pi, pulseaudio is not installed by default
 ```
@@ -63,7 +25,7 @@ Start the pulseaudio server
 pulseaudio -D
 ```
 
-## Microphone configuration
+### Microphone configuration
 
 Get your output card
 ```
@@ -157,7 +119,7 @@ mplayer test.wav
 ```
 
 
-## HDMI / Analog audio
+### HDMI / Analog audio
 
 By default the audio stream will get out by HDMI if something is plugged to this port.
 Check the [official documentation](https://www.raspberrypi.org/documentation/configuration/audio-config.md) to switch from HDMI to analog.

+ 2 - 102
Docs/installation/ubuntu_16.04.md

@@ -1,8 +1,6 @@
-# Kalliope installation on Ubuntu 16.04
+# Kalliope requirements for Ubuntu 14.04/16.04
 
-## Requirements
-
-### Debian packages requirements
+## Debian packages requirements
 
 Install some required system libraries and softwares:
 
@@ -10,101 +8,3 @@ Install some required system libraries and softwares:
 sudo apt-get update
 sudo apt-get install git python-pip python-dev libsmpeg0 libttspico-utils libsmpeg0 flac dialog libffi-dev libffi-dev libssl-dev portaudio19-dev build-essential libssl-dev libffi-dev sox libatlas3-base mplayer
 ```
-
-## Installation
-
-### Method 1 - User install using the PIP package
-
-You can install kalliope on your system:
-```
-sudo pip install kalliope
-```
-
-Or just in your user home:
-```
-pip install --user kalliope
-```
-
-Run Kalliope:
-```
-kalliope start
-```
-
-### Method 2 - Manual user install using the git repository
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-```
-
-Install the project:
-```
-sudo python setup.py install
-```
-
-Run Kalliope from a shell:
-```
-kalliope start
-```
-
-### Method 3 - Developer install using Virtualenv
-
-Install the `python-virtualenv` package:
-```
-sudo apt-get install python-virtualenv
-```
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-cd kalliope
-```
-
-Generate a local python environment:
-```
-virtualenv venv
-```
-
-Install the project using the local environment:
-```
-venv/bin/pip install --editable .
-```
-
-Run Kalliope from a shell:
-```
-venv/bin/kalliope start
-```
-
-### Method 4 - Developer, dependencies install only
-
-Clone the project:
-```
-git clone https://github.com/kalliope-project/kalliope.git
-cd kalliope
-```
-
-Install the python dependencies directly:
-```
-sudo pip install -r install/python_requirements.txt
-```
-
-Run Kalliope from a shell directly:
-```
-python kalliope.py start
-```
-
-## Test your env
-
-To ensure that you can record your voice, run the following command to capture audio input from your microphone:
-```
-rec test.wav
-```
-
-Press CTRL-C after capturing a sample of your voice.
-
-Then play the recorded audio file
-```
-mplayer test.wav
-```
-
-If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](../settings.md).

+ 19 - 5
Docs/settings.md

@@ -1,13 +1,24 @@
 # Kalliope settings
 
 This part of the documentation explains the main configuration of Kalliope.
-You will have to modify the configuration file called `settings.yml` which is located in the root of the project tree.
 
-The file is written on YAML syntax.
+Kalliope need two file to works, a `settings.yml` and a `brain.yml`. Files are written on YAML syntax.
 
-## Tunable settings
+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.
 
-The following settings can be modified:
+This a common tree of a Kalliope configuration folder:
+```
+kalliope_config/
+├── brains
+│   └── included_brain.yml
+├── brain.yml
+├── files
+│   └── kalliope-FR-13samples.pmdl
+└── settings.yml
+```
 
 ## Triggers configuration
 
@@ -203,7 +214,7 @@ Password used by the basic HTTP authentication. Must be provided if `password_pr
 
 ## Default synapse
 
-Run a default synapse when Kalliope can't find the order in any synapse.
+Run a default [synapse](brain.md) when Kalliope can't find the order in any synapse. 
 
 ```
 default_synapse: "synapse-name"
@@ -213,3 +224,6 @@ E.g
 ```
 default_synapse: "Default-response"
 ```
+
+## Next: configure the brain of Kalliope
+Now your settings are ok, you can start creating the [brain](brain.md) of your assistant.

+ 1 - 0
MANIFEST.in

@@ -0,0 +1 @@
+include *.md

+ 3 - 4
README.md

@@ -1,6 +1,6 @@
 # Kalliope
 
-[![Build Status](https://travis-ci.org/kalliope-project/kalliope.svg?branch=tests_monf)](https://travis-ci.org/kalliope-project/kalliope)
+[![Build Status](https://travis-ci.org/kalliope-project/kalliope.svg)](https://travis-ci.org/kalliope-project/kalliope)
 
 ![logo](images/Kalliope_logo_large.png)
 
@@ -24,9 +24,8 @@ Kalliope is easy-peasy to use, see the hello world
 
 ## Installation
 
-- [Raspbian Jessie(Raspberry pi)](Docs/installation/raspbian_jessie.md)
-- [Ubuntu 16.04](Docs/installation/ubuntu_16.04.md)
-- [Debian Jessie](Docs/installation/debian_jessie.md)
+- [Kalliope installation documentation](Docs/installation.md)
+
 
 ## Usage
 

+ 1 - 2
install/files/python_requirements.txt

@@ -1,10 +1,9 @@
-SpeechRecognition==3.4.6
+SpeechRecognition>=3.5.0
 markupsafe==0.23
 pyaudio==0.2.9
 ansible==2.2.0.0
 python2-pythondialog==3.4.0
 jinja==1.2
-python-crontab==2.1.1
 cffi==1.9.1
 pygmail==0.0.5.4
 pushetta==1.0.15

+ 1 - 1
kalliope/_version.py

@@ -1,2 +1,2 @@
 # https://www.python.org/dev/peps/pep-0440/
-version_str = "0.3.0"
+version_str = "0.3.0c"

+ 0 - 25
kalliope/tasks.yml

@@ -1,25 +0,0 @@
----
-- name: Playbook
-  hosts: localhost
-  gather_facts: no
-  connection: local
-
-  tasks:
-    - shell: /usr/bin/uptime
-      register: shell_out
-
-    - debug: msg="{{ shell_out.stdout }}"
-
-
-    - name: "Call api"
-      uri:
-          url: "http://192.168.0.17:8000/app"
-          HEADER_Content-Type: "application/json"
-          method: POST
-          user: admin
-          password: secret
-          force_basic_auth: yes
-          status_code: 201
-          body_format: json
-          body: >
-            {"app_name": "music", "state": "stop"}

+ 1 - 4
setup.py

@@ -57,13 +57,12 @@ setup(
 
     # required libs
     install_requires=[
-        'SpeechRecognition==3.4.6',
+        'SpeechRecognition>=3.5.0',
         'markupsafe==0.23',
         'pyaudio==0.2.9',
         'ansible==2.2.0.0',
         'python2-pythondialog==3.4.0',
         'jinja==1.2',
-        'python-crontab==2.1.1',
         'cffi==1.9.1',
         'pygmail==0.0.5.4',
         'pushetta==1.0.15',
@@ -86,10 +85,8 @@ setup(
     # additional files
     package_data={
         'kalliope': [
-            'brains/*.yml',
             'brain.yml',
             'settings.yml',
-            'tasks.yml',
             'trigger/snowboy/armv7l/_snowboydetect.so',
             'trigger/snowboy/x86_64/_snowboydetect.so',
             'trigger/snowboy/resources/*',