Merge pull request #230 from kalliope-project/dev

Version 4.3
kalliope-project · Mar 11, 2017 · 4c6586b · 4c6586b
2 parents 307c65c + 29e3c68
commit 4c6586b
Show file tree

Hide file tree

Showing 72 changed files with 1,479 additions and 673 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,18 @@
+v0.4.3 / 2017-03-11
+===================
+- Update Documentation
+- Improve API + manage incoming audio
+- Fix bug maximum recursion
+- Disable REST API by default 
+- Add command line run-order to start a synapse
+- Run default synapse if STT engine do not return an order
+- Manage global variables
+- Remove password from log
+- cli command to delete a neuron
+- Fix neurotransmitter
+- Fix Acapela TTS
+- Remove Voxygen TTS (not working anymore)
+
 v0.4.2 / 2017-01-18
 ===================
 - fix community neuron installation

diff --git a/Docs/contributing/contribute_stt.md b/Docs/contributing/contribute_stt.md
@@ -37,23 +37,24 @@ The constructor has a __**kwargs argument__ which is corresponding to the Dict o
 1. Attach the incoming callback to the self.main_controller_callback attribute. This callback come from the main controller and will receive the text at the end of the process
 1. Obtain audio from the microphone in the constructor. (Note : we mostly use the [speech_recognition library](https://pypi.python.org/pypi/SpeechRecognition/))
 1. Set your callback method into the mother class with `self.set_callback(self.google_callback)`. This callback is the one which will process the audio into a text.
-1. Use self.start_listening() from the mother class to get an audio. Once caught, the mother class will give the audio stream to the callback you've set before.
-1. The callback method must implement two arguments: recognizer and audio. The audio argument contains the stream caught by the microphone
+1. Use self.start_processing() from the mother class to get an audio from the microphone or read the audio file path if provided. The mother class will give the audio stream to the callback you've set before.
+1. The callback method must implement two arguments: recognizer and audio. The audio argument contains the stream caught by the microphone or read from an audio file path
 1. Do magic stuff with the audio in order to get a string that contains the translated text
 1. Once you get the text, let give it to the main_controller_callback method received in the constructor by calling it with the text string as argument `self.main_controller_callback(audio_to_text)`
 
     ```python
     def __init__(self, callback=None, **kwargs):
-        OrderListener.__init__(self)
+        # give the audio file path to process directly to the mother class if exist
+        SpeechRecognition.__init__(self, kwargs.get('audio_file_path', None))
         # here is the main controller callback. We will return the text at the end of the process
         self.main_controller_callback = callback
 
         self.argument_from_settings = kwargs.get('argument_from_settings', None)
 
         #  give our callback   
         self.set_callback(self.my_callback)
-        # start the microphone to capture an audio
-        self.start_listening()
+        # start processing, record a sample from the microphone if no audio file path provided, else read the file
+        self.start_processing()
 
         def my_callback((self, recognizer, audio):
             # ---------------------------------------------

diff --git a/Docs/installation.md b/Docs/installation.md
@@ -53,6 +53,11 @@ Install the project using the local environment:
 venv/bin/pip install --editable .
 ```
 
+Activate the local environment:
+```bash
+source venv/bin/activate
+```
+
 ### Method 4 - Developer, dependencies install only
 
 Clone the project:
@@ -63,7 +68,7 @@ cd kalliope
 
 Install the python dependencies directly:
 ```bash
-sudo pip install -r install/python_requirements.txt
+sudo pip install -r install/files/python_requirements.txt
 ```
 
 ## Test your env
@@ -88,7 +93,7 @@ Those repositories provide you a basic structure to start playing with kalliope.
 
 - [French starter config](https://github.com/kalliope-project/kalliope_starter_fr)
 - [English starter config](https://github.com/kalliope-project/kalliope_starter_en)
-
+- [German starter config](https://github.com/kalliope-project/kalliope_starter_de)
 
 ## 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/debian_jessie.md b/Docs/installation/debian_jessie.md
@@ -26,3 +26,5 @@ Then, with pip, the last release of setuptools
 sudo pip install -U setuptools
 ```
 
+Then, follow the [main installation documentation](../installation.md).
+
diff --git a/Docs/installation/quickstart.md b/Docs/installation/quickstart.md
@@ -8,6 +8,7 @@ If you are using kalliope from a Rpi, the idea would be to configure your assist
 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)
+- [German starter kit](https://github.com/kalliope-project/kalliope_starter_de)
 
 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. 
@@ -17,7 +18,7 @@ When you start kalliope using the CLI (`kalliope start`), the program will try t
 - 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:
+This is a common tree of a Kalliope configuration folder:
 ```
 kalliope_config/
 ├── brains

diff --git a/Docs/installation/raspbian_jessie.md b/Docs/installation/raspbian_jessie.md
@@ -28,7 +28,7 @@ Install some required system libraries and software:
 
 ```bash
 sudo apt-get update
-sudo apt-get install git 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
+sudo apt-get install git 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 libyaml-dev libpython2.7-dev
 ```
 
 Let's install the last release of python-pip
@@ -153,3 +153,5 @@ Check the [official documentation](https://www.raspberrypi.org/documentation/con
 ```bash
 sudo raspi-config
 ```
+
+Then, follow the [main installation documentation](../installation.md).
diff --git a/Docs/installation/ubuntu_14.04.md b/Docs/installation/ubuntu_14.04.md
@@ -14,3 +14,5 @@ Let's install the last release of python-pip
 wget https://bootstrap.pypa.io/get-pip.py
 sudo python get-pip.py
 ```
+
+Then, follow the [main installation documentation](../installation.md).
diff --git a/Docs/installation/ubuntu_16.04.md b/Docs/installation/ubuntu_16.04.md
@@ -13,3 +13,5 @@ Let's install the last release of python-pip
 wget https://bootstrap.pypa.io/get-pip.py
 sudo python get-pip.py
 ```
+
+Then, follow the [main installation documentation](../installation.md).
diff --git a/Docs/kalliope_cli.md b/Docs/kalliope_cli.md
@@ -72,6 +72,15 @@ Example of use
 kalliope start --run-synapse "say-hello"
 ```
 
+### --run-order "Your Order"
+
+Run a specific order from command line.
+
+Example of use
+```bash
+kalliope start --run-order "hello"
+```
+
 ### --brain-file BRAIN_FILE
 
 Replace the default brain file from the root of the project folder by a custom one.

diff --git a/Docs/neuron_list.md b/Docs/neuron_list.md
@@ -1,38 +1,88 @@
-# List of available neuron
-
+# Neuron installation
 A neuron is a module that will perform some actions attached to an order. You can use it in your synapses. See the [complete neuron documentation](neurons.md) for more information.
 
-## Core neuron
-
-| Name                                                      | Description                                       |
-|-----------------------------------------------------------|---------------------------------------------------|
-| [ansible_playbook](../kalliope/neurons/ansible_playbook/) | Run an ansible playbook                           |
-| [kill_switch](../kalliope/neurons/kill_switch/)           | Stop Kalliope process                             |
-| [neurotransmitter](../kalliope/neurons/neurotransmitter/) | Link synapse together                             |
-| [say](../kalliope/neurons/say/)                           | Make Kalliope talk by using TTS                   |
-| [script](../kalliope/neurons/script/)                     | Run an executable script                          |
-| [shell](../kalliope/neurons/shell/)                       | Run a shell command                               |
-| [sleep](../kalliope/neurons/sleep/)                       | Make Kalliope sleep for a while before continuing |
-| [systemdate](../kalliope/neurons/systemdate/)             | Give the local system date and time               |
-| [uri](../kalliope/neurons/uri/)                           | Interacts with HTTP and HTTPS web services.       |
-
-## Community neuron
-
-| Name                                                                                 | Description                                                                             |
-|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
-| [gmail_checker](https://github.com/kalliope-project/kalliope_neuron_gmail)           | Get the number of unread email and their subjects from a gmail account                     |
-| [google agenda](https://github.com/bacardi55/kalliope-google-calendar)               | Get your next meetings on google calendar                                                |
-| [list available orders](https://github.com/bacardi55/kalliope-list-available-orders) | Let kalliope tell you what she how she can help                                            |
-| [openweathermap](https://github.com/kalliope-project/kalliope_neuron_openweathermap) | Get the weather of a location                                                               |
-| [pi camera](https://github.com/bacardi55/kalliope-picamera)                          | Take picture with your picamera                                                             |
-| [pushetta](https://github.com/kalliope-project/kalliope_neuron_pushetta)             | Send a push message to a remote device like Android/iOS/Windows Phone or Chrome browser |
-| [rss_reader](https://github.com/kalliope-project/kalliope_neuron_rss_reader)         | get rss feed from website                                                                   |
-| [tasker](https://github.com/kalliope-project/kalliope_neuron_tasker)                 | Send a message to Android tasker app                                                         |
-| [twitter](https://github.com/kalliope-project/kalliope_neuron_twitter)               | Send a Twit from kalliope                                                                   |
-| [wake_on_lan](https://github.com/kalliope-project/kalliope_neuron_wake_on_lan)       | Wake on lan a computer                                                                       |
-| [web scraper](https://github.com/bacardi55/kalliope-web-scraper)                     | Read web pages that don't provide RSS feed or APIs (by scraping html)                                                    |
-| [wikipedia](https://github.com/kalliope-project/kalliope_neuron_wikipedia)           | Search for a page on Wikipedia                                                               |
-
-Wanna add your neuron in the list? Open [an issue](../../issues) with the link of your neuron or send a pull request to update the list directly.
-
-To know how to install a community neuron, read the "Installation" section of the [neuron documentation](neurons.md).
+## Neuron list
+
+Get the full neuron list available on [the project web site](https://kalliope-project.github.io/).
+
+## Installation
+
+Core neurons are already packaged with the installation of kalliope an can be used out of the box. Community neuron need to be installed manually.
+>**Note:** To install a neuron, you must declare your `resource_directory` in your [settings](settings.md).
+
+### Via the kalliope's CLI
+
+CLI syntax
+```bash
+kalliope install --git-url <git_url>
+```
+
+E.g:
+```bash
+kalliope install --git-url https://github.com/kalliope-project/kalliope_neuron_wikipedia.git
+```
+You may be prompted to type your `sudo` password during the process.
+
+### Manually
+
+You can also install a neuron manually.
+Fist, clone the repo in the right resource folder. 
+```bash
+cd /path/to/resource_folder
+git clone <plugin_url>
+```
+
+Then install it manually via Ansible (Ansible has been installed with kalliope)
+```bash
+cd <cloned_repo>
+ansible-playbook install.yml -K
+```
+
+Full example
+```bash
+cd /home/me/my_kalliope_config/resources/neurons
+git clone https://github.com/kalliope-project/kalliope_neuron_hue.git
+cd hue
+ansible-playbook install.yml -K
+```
+
+## Uninstall a resource
+### Via the kalliope's CLI
+>**Note:** To uninstall a resource, you must declare the `resource_directory` in your [settings](settings.md).
+
+CLI syntax
+```bash
+kalliope uninstall --neuron-name <neuron_name>
+kalliope uninstall --stt-name <stt_name>
+kalliope uninstall --tts-name <tts_name>
+kalliope uninstall --trigger-name <trigger_name>
+```
+
+E.g:
+```bash
+kalliope uninstall --neuron-name hue
+```
+
+### Manually
+
+To remove a resource, you only need to delete the folder from the corresponding `resource_directory`.
+```bash
+cd /path/to/resource_folder
+rm -rf <resource_name>
+```
+
+E.g
+```bash
+cd /home/me/my_kalliope_config/resources/neurons
+rm -rf hue
+```
+
+>**Note:** When deleting a resource folder, libraries that have been installed by the resource are not removed from the system. If you want a complete cleanup, you'll have to open the install.yml file of the resource to see what have been installed and rollback manually each task.
+For example, when installing the neuron hue, the python lib called phue has been installed. To perform a complete cleanup, you need then to run "sudo pip uninstall phue".
+
+
+## Update a resource
+
+To update a resource, you can either:
+- uninstall the resource and then reinstall it back
+- go into the resource directory and run a `git pull`
diff --git a/Docs/neurons.md b/Docs/neurons.md
@@ -2,22 +2,7 @@
 
 A neuron is a plugin that performs a specific action. You use it to create a synapse.
 You can add as many neurons as you want to a synapse. The neurons are executed one by one when the input order is triggered.
-
-## Installation
-
-Core neurons are already packaged with the installation of kalliope an can be used out of the box. Community neuron need to be installed manually.
-
-Use the CLI
-```bash
-kalliope install --git-url <git_url>
-```
-
-E.g:
-```bash
-kalliope install --git-url https://github.com/kalliope-project/kalliope_neuron_wikipedia.git
-```
-
-You may be prompted to type your `sudo` password during the process. You can see the list of [available neuron here](neuron_list.md)
+If you want to install a community neuron, see the [neuron list documentation](neuron_list.md).
 
 ## Usage
 Neurons are declared in the `neurons` section of a synapse in your brain file.
@@ -47,6 +32,7 @@ Full list of [available neuron here](neuron_list.md)
 
 Neurons require some **parameters** from the synapse declaration to work. Those parameters, also called arguments, can be passed to the neuron in two way:
 - from the neuron declaration
+- from global variables
 - from the captured order
 
 From the neuron declaration:
@@ -57,6 +43,16 @@ neurons:
         parameter2: "value2"
 ```
 
+From global variables: (cf: [settings.md](settings.md))
+```yml
+  - name: "run-simple-sleep"
+    signals:
+      - order: "Wait for me "
+    neurons:
+      - sleep:
+          seconds: {{variable}}
+```
+
 From the captured order:
 ```yml
   - name: "run-neuron-with-parameter-in-order"
@@ -160,10 +156,10 @@ neurons:
   - say:
     message:
       - "My name is Kalliope"
-    tts: "voxygen"
+    tts: "acapela"
 ```
 
-Here, the first neuron will use the default tts as set in the settings.yml file. The second neuron will use the tts "voxygen".
+Here, the first neuron will use the default tts as set in the settings.yml file. The second neuron will use the tts "acapela".
 
 >**Note:** The TTS must has been configured with its required parameters in the settings.yml file. See [TTS documentation](tts.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -26,3 +26,5 @@ Then, with pip, the last release of setuptools
		sudo pip install -U setuptools
		```

		Then, follow the [main installation documentation](../installation.md).