Browse Source

Doc enhancement (#437)

* add avaialble start options to the settings doc

* add a table of contents in front of each documentation + remove dangling spaces
Nicolas Marcq 6 years ago
parent
commit
dda2501277

+ 14 - 7
Docs/brain.md

@@ -1,5 +1,12 @@
 # Brain
 # Brain
 
 
+- [Brain](#brain)
+  - [Manage synapses](#manage-synapses)
+  - [Split the brain](#split-the-brain)
+  - [The default Synapse](#the-default-synapse)
+  - [Next: Start Kalliope](#next-start-kalliope)
+  - [Notes](#notes)
+
 The brain is a main component of Kalliope. It's a module that gives a configuration of your own personal assistant and, so, determines it's behavior and fonctionnalities.
 The brain is a main component of Kalliope. It's a module that gives a configuration of your own personal assistant and, so, determines it's behavior and fonctionnalities.
 
 
 Brain is composed by synapses: a synapse is the link between input and output actions.
 Brain is composed by synapses: a synapse is the link between input and output actions.
@@ -14,7 +21,7 @@ An input action, called a "[signal](signals.md)" can be:
 An output action is
 An output action is
 - **a list of neurons:** A [neuron](neurons.md) is a module or plugin that will perform some actions like simply talking, run a script, run a command or call a web service.
 - **a list of neurons:** A [neuron](neurons.md) is a module or plugin that will perform some actions like simply talking, run a script, run a command or call a web service.
 
 
-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, 
+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.
 but rather a model of a configuration or a process.
 Kalliope will look for the brain in the order bellow:
 Kalliope will look for the brain in the order bellow:
 - From you current folder, E.g `/home/pi/my_kalliope/brain.yml`
 - From you current folder, E.g `/home/pi/my_kalliope/brain.yml`
@@ -28,9 +35,9 @@ Let's take a look on a basic synapse in our brain:
   - name: "Say-hello"
   - name: "Say-hello"
     signals:
     signals:
       - order: "say hello"
       - order: "say hello"
-    neurons:      
+    neurons:
       - say:
       - say:
-          message: "Hello, sir"    
+          message: "Hello, sir"
 ```
 ```
 
 
 Let's break this down in sections so we can understand how the file is built and what each part means.
 Let's break this down in sections so we can understand how the file is built and what each part means.
@@ -52,7 +59,7 @@ signals:
   - order: "say-hello"
   - order: "say-hello"
 ```
 ```
 
 
-You can add as many orders as you want for the signals. Even if literally they do not mean the same thing (For example order "say hello" and order "adventure" or whatever) as long they are in the same synaps, they will trigger the same action defined in neurons. 
+You can add as many orders as you want for the signals. Even if literally they do not mean the same thing (For example order "say hello" and order "adventure" or whatever) as long they are in the same synaps, they will trigger the same action defined in neurons.
 
 
 Note that you are not limited by the exact sentence you put in your order. Kalliope uses the matching, it means that you can pronounce the sentence which contains your order (so, can be much longer) and it will lauch an attached task anyway. In this example, the task attached to order "say hello" will be launched even if you say
 Note that you are not limited by the exact sentence you put in your order. Kalliope uses the matching, it means that you can pronounce the sentence which contains your order (so, can be much longer) and it will lauch an attached task anyway. In this example, the task attached to order "say hello" will be launched even if you say
 - "say hello Kalliope"
 - "say hello Kalliope"
@@ -70,13 +77,13 @@ You must pay attention to define the orders as precise as possible. As Kalliope
   signals:
   signals:
     - order: "say hello"
     - order: "say hello"
 ```
 ```
-and 
+and
 ```yml
 ```yml
 - name: "Say-something"
 - name: "Say-something"
   signals:
   signals:
     - order: "say"
     - order: "say"
 ```
 ```
-When you will pronounce "say hello", it will trigger both synapses. 
+When you will pronounce "say hello", it will trigger both synapses.
 
 
 Then we have the neurons declaration. Neurons are modules that will be executed when the input action is triggered. You can define as many neurons as you want to the same input action (for example: say somethning, then do something etc...). This declaration contains a list (because it starts with a "-") of neurons
 Then we have the neurons declaration. Neurons are modules that will be executed when the input action is triggered. You can define as many neurons as you want to the same input action (for example: say somethning, then do something etc...). This declaration contains a list (because it starts with a "-") of neurons
 ```yml
 ```yml
@@ -123,7 +130,7 @@ E.g:
       - brains/find_my_phone.yml
       - brains/find_my_phone.yml
 ```
 ```
 
 
->**Note:** You can only use the `include` statement in the main brain file. 
+>**Note:** You can only use the `include` statement in the main brain file.
 
 
 >**Note:** the includes statement must start with a `-`
 >**Note:** the includes statement must start with a `-`
 
 

+ 10 - 3
Docs/contributing.md

@@ -1,5 +1,12 @@
 # Contributing
 # Contributing
 
 
+- [Contributing](#contributing)
+    - [Core](#core)
+    - [Community module (Neuron, STT, TTS)](#community-module-neuron-stt-tts)
+    - [Constraints](#constraints)
+    - [Limitations](#limitations)
+    - [Share it](#share-it)
+
 Kalliope needs the community to improve its Core features and to create new Neurons, STTs, TTSs. Let's join us !
 Kalliope needs the community to improve its Core features and to create new Neurons, STTs, TTSs. Let's join us !
 [Here is the Todo list](https://trello.com/b/H0TecLSi/kalliopecore) if you are looking for some ideas.
 [Here is the Todo list](https://trello.com/b/H0TecLSi/kalliopecore) if you are looking for some ideas.
 
 
@@ -37,14 +44,14 @@ See the dedicated documentation depending on the type of module you want to code
         :type my_parameter: str
         :type my_parameter: str
         """
         """
     ```
     ```
-    
+
 1. Respect [PEP 8](https://www.python.org/dev/peps/pep-0008/) -- Style Guide for Python Code
 1. Respect [PEP 8](https://www.python.org/dev/peps/pep-0008/) -- Style Guide for Python Code
 We recommend the usage of an IDE like [Pycharm](https://www.jetbrains.com/pycharm/)
 We recommend the usage of an IDE like [Pycharm](https://www.jetbrains.com/pycharm/)
 
 
-##### Limitations
+## Limitations
 
 
 1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__.
 1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__.
-    - Because of the differences between the STTs outputs: some are returning word some numbers (two != 2). 
+    - Because of the differences between the STTs outputs: some are returning word some numbers (two != 2).
     - Because of the i18n, we are not able to know if a variable should be  interpreted in english, french, spanish, etc ... ("two" != "deux" != "dos")
     - Because of the i18n, we are not able to know if a variable should be  interpreted in english, french, spanish, etc ... ("two" != "deux" != "dos")
 
 
 
 

+ 15 - 2
Docs/installation.md

@@ -1,5 +1,17 @@
 # Kalliope installation
 # Kalliope installation
 
 
+- [Kalliope installation](#kalliope-installation)
+    - [Prerequisites](#prerequisites)
+    - [Installation](#installation)
+        - [Method 1 - User install using the PIP package](#method-1---user-install-using-the-pip-package)
+        - [Method 2 - Manual setup using sources](#method-2---manual-setup-using-sources)
+        - [Method 3 - Developer install using Virtualenv](#method-3---developer-install-using-virtualenv)
+        - [Method 4 - Developer, dependencies install only](#method-4---developer-dependencies-install-only)
+    - [Test your env](#test-your-env)
+    - [Get a starter configuration](#get-a-starter-configuration)
+    - [Start Kalliope automatically after a reboot](#start-kalliope-automatically-after-a-reboot)
+    - [Next: settings](#next-settings)
+
 ## Prerequisites
 ## Prerequisites
 
 
 Please follow the right link bellow to install requirements depending on your target environment:
 Please follow the right link bellow to install requirements depending on your target environment:
@@ -88,7 +100,7 @@ mplayer test.wav
 Your installation is now complete, let's take a look now to the [quickstart documentation](installation/quickstart.md) to learn how to use Kalliope.
 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
 ## Get a starter configuration
-We create some starter configuration that only need to be downloaded and then started. 
+We create some starter configuration that only need to be downloaded and then started.
 Those repositories provide you a basic structure to start playing with kalliope. We recommend you to clone one of them and then go to the next section.
 Those repositories provide you a basic structure to start playing with kalliope. We recommend you to clone one of them and then go to the next section.
 
 
 - [French starter config](https://github.com/kalliope-project/kalliope_starter_fr)
 - [French starter config](https://github.com/kalliope-project/kalliope_starter_fr)
@@ -125,5 +137,6 @@ sudo systemctl start kalliope
 sudo systemctl enable kalliope
 sudo systemctl enable kalliope
 ```
 ```
 
 
-## Next: 
+## Next: settings
+
 If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md).
 If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md).

+ 6 - 9
Docs/installation/quickstart.md

@@ -1,17 +1,14 @@
 # Kalliope quick start
 # 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/). 
+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.
 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)
-- [German starter kit](https://github.com/kalliope-project/kalliope_starter_de)
+We made starter kits that only needs to be cloned, placed into the Rpi and launched. You'll find the whole list of available start kits on the [Kalliope's website](https://kalliope-project.github.io/starter_kit.html).
 
 
 Those repositories provide you a structure to start playing and learning basics of Kalliope.
 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. 
+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:
 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 your current folder, E.g `/home/pi/my_kalliope/settings.yml`
@@ -29,7 +26,7 @@ kalliope_config/
 └── settings.yml
 └── settings.yml
 ```
 ```
 
 
-Let's open the main brain file. You'll see there are some included sub brains file. 
+Let's open the main brain file. You'll see there are some included sub brains file.
 ```yml
 ```yml
 - includes:
 - includes:
     - brains/say.yml
     - brains/say.yml
@@ -54,7 +51,7 @@ 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).
 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. 
+If the trigger is successfully raised, you'll see "say something" into the console.
 ```bash
 ```bash
 2016-12-05 20:54:21,950 :: INFO :: Keyword 1 detected at time: 2016-12-05 20:54:21
 2016-12-05 20:54:21,950 :: INFO :: Keyword 1 detected at time: 2016-12-05 20:54:21
 Say something!
 Say something!

+ 10 - 2
Docs/installation/raspbian.md

@@ -1,5 +1,13 @@
 # Kalliope requirements for Raspbian
 # Kalliope requirements for Raspbian
 
 
+- [Kalliope requirements for Raspbian](#kalliope-requirements-for-raspbian)
+  - [Install via the pre-compiled disk image](#install-via-the-pre-compiled-disk-image)
+  - [Manual installation](#manual-installation)
+    - [Debian packages requirements](#debian-packages-requirements)
+  - [Raspberry Pi configuration](#raspberry-pi-configuration)
+    - [Microphone configuration](#microphone-configuration)
+    - [HDMI / Analog audio](#hdmi-analog-audio)
+
 ## Install via the pre-compiled disk image
 ## Install via the pre-compiled disk image
 
 
 Download the last image [from the release page](https://github.com/kalliope-project/kalliope/releases) of Kalliope and load it as usual onto an SD card.
 Download the last image [from the release page](https://github.com/kalliope-project/kalliope/releases) of Kalliope and load it as usual onto an SD card.
@@ -21,7 +29,7 @@ Supported Raspbian images:
 - [raspbian-2017-08-16](http://downloads.raspberrypi.org/raspbian/images/raspbian-2017-04-10/) (Strech based)
 - [raspbian-2017-08-16](http://downloads.raspberrypi.org/raspbian/images/raspbian-2017-04-10/) (Strech based)
 
 
 
 
-> **Note:** It is recommended to use a **lite** installation of Raspbian without any graphical interface for a better experience. 
+> **Note:** It is recommended to use a **lite** installation of Raspbian without any graphical interface for a better experience.
 
 
 > **Note:** The first Raspberry Pi is not officially supported. The installation will works but a single core with only 700Mhz may produce latency.
 > **Note:** The first Raspberry Pi is not officially supported. The installation will works but a single core with only 700Mhz may produce latency.
 
 
@@ -72,7 +80,7 @@ card 1: Headset [Logitech USB Headset], device 0: USB Audio [USB Audio]
   Subdevice #0: subdevice #0
   Subdevice #0: subdevice #0
 ```
 ```
 
 
-Here one shall see: 
+Here one shall see:
 - the analog audio (where the jack is connected) on card 0 and device 1
 - the analog audio (where the jack is connected) on card 0 and device 1
 - usb audio on card 1 and device 1
 - usb audio on card 1 and device 1
 
 

+ 17 - 2
Docs/kalliope_cli.md

@@ -1,5 +1,20 @@
 # Kalliope Command-line interface
 # Kalliope Command-line interface
 
 
+- [Kalliope Command-line interface](#kalliope-command-line-interface)
+    - [SYNOPSIS](#synopsis)
+    - [ARGUMENTS](#arguments)
+        - [start](#start)
+        - [gui](#gui)
+        - [install](#install)
+    - [OPTIONS](#options)
+        - [-v or --version](#v-or---version)
+        - [--run-synapse SYNAPSE_NAME](#run-synapse-synapsename)
+        - [--run-order "Your Order"](#run-order-your-order)
+        - [--brain-file BRAIN_FILE](#brain-file-brainfile)
+        - [--deaf](#deaf)
+        - [--debug](#debug)
+        - [--git-url](#git-url)
+
 ## SYNOPSIS
 ## SYNOPSIS
 This is the syntax used to run Kalliope from command line
 This is the syntax used to run Kalliope from command line
 ```bash
 ```bash
@@ -26,7 +41,7 @@ kalliope start
 To kill Kalliope, you can press "Ctrl-C" on your keyboard.
 To kill Kalliope, you can press "Ctrl-C" on your keyboard.
 
 
 ### gui
 ### gui
-Launch the Kalliope shell Graphical User Interface. 
+Launch the Kalliope shell Graphical User Interface.
 The GUI allows you to test your [STT](stt.md) and [TTS](tts.md) that you have configured in [settings.yml](default_settings.md) file of Kalliope.
 The GUI allows you to test your [STT](stt.md) and [TTS](tts.md) that you have configured in [settings.yml](default_settings.md) file of Kalliope.
 
 
 Example of use
 Example of use
@@ -84,7 +99,7 @@ kalliope start --run-order "hello"
 ### --brain-file BRAIN_FILE
 ### --brain-file BRAIN_FILE
 
 
 Replace the default brain file from the root of the project folder by a custom one.
 Replace the default brain file from the root of the project folder by a custom one.
-> **Important note:** The path must be absolute. The absolute path contains the root directory and all other subdirectories in which a file or folder is contained. 
+> **Important note:** The path must be absolute. The absolute path contains the root directory and all other subdirectories in which a file or folder is contained.
 
 
 Example of use
 Example of use
 ```bash
 ```bash

+ 12 - 1
Docs/neuron_list.md

@@ -1,4 +1,15 @@
 # Neuron installation
 # Neuron installation
+
+- [Neuron installation](#neuron-installation)
+    - [Neuron list](#neuron-list)
+    - [Installation](#installation)
+        - [Via the kalliope's CLI](#via-the-kalliopes-cli)
+        - [Manually](#manually)
+    - [Uninstall a resource](#uninstall-a-resource)
+        - [Via the kalliope's CLI](#via-the-kalliopes-cli)
+        - [Manually](#manually)
+    - [Update a resource](#update-a-resource)
+
 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.
 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.
 
 
 ## Neuron list
 ## Neuron list
@@ -26,7 +37,7 @@ You may be prompted to type your `sudo` password during the process.
 ### Manually
 ### Manually
 
 
 You can also install a neuron manually.
 You can also install a neuron manually.
-Fist, clone the repo in the right resource folder. 
+Fist, clone the repo in the right resource folder.
 ```bash
 ```bash
 cd /path/to/resource_folder
 cd /path/to/resource_folder
 git clone <plugin_url>
 git clone <plugin_url>

+ 33 - 22
Docs/neurons.md

@@ -1,5 +1,16 @@
 # Neurons
 # Neurons
 
 
+- [Neurons](#neurons)
+  - [Usage](#usage)
+  - [Input values](#input-values)
+  - [Output values](#output-values)
+  - [kalliope_memory](#kalliopememory)
+    - [Store parameters generated by a neuron](#store-parameters-generated-by-a-neuron)
+    - [Store parameters captured from orders](#store-parameters-captured-from-orders)
+    - [Get the last order generated TTS message](#get-the-last-order-generated-tts-message)
+  - [Overridable parameters](#overridable-parameters)
+    - [TTS](#tts)
+
 A neuron is a plugin that performs a specific action. You use it to create a synapse.
 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.
 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.
 If you want to install a community neuron, see the [neuron list documentation](neuron_list.md).
 If you want to install a community neuron, see the [neuron list documentation](neuron_list.md).
@@ -74,7 +85,7 @@ We recommend the reading of the [signals documentation](signals.md) for a comple
 
 
 Some neurons will return variables into a dictionary of value. Those values can be used to make your own Kalliope answer through a template.
 Some neurons will return variables into a dictionary of value. Those values can be used to make your own Kalliope answer through a template.
 The objective of using a template is to let the user choosing what he wants to make Kalliope saying in its own language.
 The objective of using a template is to let the user choosing what he wants to make Kalliope saying in its own language.
-A template is a text file that contains **variables**, which get replaced with values when the template is evaluated by 
+A template is a text file that contains **variables**, which get replaced with values when the template is evaluated by
 the [template engine](https://en.wikipedia.org/wiki/Jinja_(template_engine)), and **tags**, which control the logic of the template.
 the [template engine](https://en.wikipedia.org/wiki/Jinja_(template_engine)), and **tags**, which control the logic of the template.
 
 
 The template engine used in Kalliope is [Jinja2](http://jinja.pocoo.org/docs/dev/).
 The template engine used in Kalliope is [Jinja2](http://jinja.pocoo.org/docs/dev/).
@@ -97,7 +108,7 @@ Placed in a complete synapse, it looks like the following
             - "It is {{ hours }} hours and {{ minutes }} minutes"
             - "It is {{ hours }} hours and {{ minutes }} minutes"
 ```
 ```
 
 
-Here, we use [variables](http://jinja.pocoo.org/docs/dev/templates/#variables) from the neuron into our template file. Both variables will be interpreted by the template engine. 
+Here, we use [variables](http://jinja.pocoo.org/docs/dev/templates/#variables) from the neuron into our template file. Both variables will be interpreted by the template engine.
 So, what the user will hear is something like `It is 9 hours and 21 minutes`.
 So, what the user will hear is something like `It is 9 hours and 21 minutes`.
 
 
 We can add some logic to a template with tags. Here a simple example with [a test tag](http://jinja.pocoo.org/docs/dev/templates/#if), that will make Kalliope change the pronounced sentence depending on the current time.
 We can add some logic to a template with tags. Here a simple example with [a test tag](http://jinja.pocoo.org/docs/dev/templates/#if), that will make Kalliope change the pronounced sentence depending on the current time.
@@ -119,9 +130,9 @@ As this is multi-lines, we can put the content in a file and use a `file_templat
           file_template: /path/to/file/template.j2
           file_template: /path/to/file/template.j2
 ```
 ```
 
 
-## kalliope_memory: Store in memory a variable from an order or generated from a neuron
+## kalliope_memory
 
 
-Kalliope can store in a short term memory:
+Kalliope can store in a short term memory a variable from an order or generated from a neuron:
 - output parameters from a neuron
 - output parameters from a neuron
 - variable parameters captured from an order.
 - variable parameters captured from an order.
 
 
@@ -136,7 +147,7 @@ Syntax with output parameters from a neuron
   signals:
   signals:
     - order: "my order"
     - order: "my order"
   neurons:
   neurons:
-    - neuron_name:        
+    - neuron_name:
         kalliope_memory:
         kalliope_memory:
           key_name_in_memory: "{{ output_variable_from_neuron }}"
           key_name_in_memory: "{{ output_variable_from_neuron }}"
           other_key_name_in_memory: "{{ other_output_variable_from_neuron }}"
           other_key_name_in_memory: "{{ other_output_variable_from_neuron }}"
@@ -150,10 +161,10 @@ Syntax to reuse memorized parameters in another synapse
   neurons:
   neurons:
     - neuron_name:
     - neuron_name:
         parameter1: "{{ kalliope_memory['key_name_in_memory'] }}"
         parameter1: "{{ kalliope_memory['key_name_in_memory'] }}"
-        parameter2: "{{ kalliope_memory['other_key_name_in_memory'] }}"        
+        parameter2: "{{ kalliope_memory['other_key_name_in_memory'] }}"
 ```
 ```
 
 
->**Note:** The key name need to be placed into simple quotes 
+>**Note:** The key name need to be placed into simple quotes
 
 
 
 
 Example with a core neuron like `systemdate`
 Example with a core neuron like `systemdate`
@@ -164,7 +175,7 @@ Example with a core neuron like `systemdate`
   neurons:
   neurons:
     - systemdate:
     - systemdate:
         say_template:
         say_template:
-          - "It' {{ hours }} hours and {{ minutes }} minutes"         
+          - "It' {{ hours }} hours and {{ minutes }} minutes"
         kalliope_memory:
         kalliope_memory:
           hours_when_asked: "{{ hours }}"
           hours_when_asked: "{{ hours }}"
           minutes_when_asked: "{{ minutes }}"
           minutes_when_asked: "{{ minutes }}"
@@ -193,7 +204,7 @@ Multiple parameters can be used and concatenated in the same memorized key
 ```yml
 ```yml
 kalliope_memory:
 kalliope_memory:
   my_saved_key: "{{ neuron_parameter_name1 }} and {{ neuron_parameter_name2 }}"
   my_saved_key: "{{ neuron_parameter_name1 }} and {{ neuron_parameter_name2 }}"
-``` 
+```
 
 
 ### Store parameters captured from orders
 ### Store parameters captured from orders
 
 
@@ -203,9 +214,9 @@ Syntax
   signals:
   signals:
     - order: "my order with {{ variable }}"
     - order: "my order with {{ variable }}"
   neurons:
   neurons:
-    - neuron_name:        
+    - neuron_name:
         kalliope_memory:
         kalliope_memory:
-          key_name_in_memory: "{{ variable }}"         
+          key_name_in_memory: "{{ variable }}"
 ```
 ```
 
 
 The syntax to reuse memorized parameters in another synapse is the same as the one used with neuron parameters
 The syntax to reuse memorized parameters in another synapse is the same as the one used with neuron parameters
@@ -215,7 +226,7 @@ The syntax to reuse memorized parameters in another synapse is the same as the o
     - order: "an order"
     - order: "an order"
   neurons:
   neurons:
     - neuron_name:
     - neuron_name:
-        parameter1: {{ kalliope_memory['key_name_in_memory']}}               
+        parameter1: {{ kalliope_memory['key_name_in_memory']}}
 ```
 ```
 
 
 Example
 Example
@@ -240,7 +251,7 @@ The value can now be used in a next call like the following
   neurons:
   neurons:
     - say:
     - say:
         message:
         message:
-          - "It's {{ kalliope_memory['friend'] }} 
+          - "It's {{ kalliope_memory['friend'] }}
 ```
 ```
 
 
 Here is another example brain whit use the `neurotimer` neuron. In this scenario, you want to remember to do something
 Here is another example brain whit use the `neurotimer` neuron. In this scenario, you want to remember to do something
@@ -276,24 +287,24 @@ Here is another example brain whit use the `neurotimer` neuron. In this scenario
 ### Get the last order generated TTS message
 ### Get the last order generated TTS message
 
 
 Kalliope will save in memory automatically:
 Kalliope will save in memory automatically:
-- the last generated TTS message . 
+- the last generated TTS message .
 - the last caught order
 - the last caught order
 
 
 To get the last generated message, use the key `{{ kalliope_memory['kalliope_last_tts_message'] }}` in your synapse.
 To get the last generated message, use the key `{{ kalliope_memory['kalliope_last_tts_message'] }}` in your synapse.
 To get the last order, use the key `{{ kalliope_memory['kalliope_last_order'] }}` in your synapse.
 To get the last order, use the key `{{ kalliope_memory['kalliope_last_order'] }}` in your synapse.
 
 
-Keep in mind that the `kalliope_last_tts_message` variable is overridden every time Kalliope says something. 
+Keep in mind that the `kalliope_last_tts_message` variable is overridden every time Kalliope says something.
 So you need to catch messages you want to process in the right hook like `on_start_speaking` or `on_stop_speaking`.
 So you need to catch messages you want to process in the right hook like `on_start_speaking` or `on_stop_speaking`.
 
 
-An example of usage is to send each message to an API each time Kalliope start speaking. 
+An example of usage is to send each message to an API each time Kalliope start speaking.
 
 
 You need at first to create a hook in your `settings.yml` like the following
 You need at first to create a hook in your `settings.yml` like the following
 ```yml
 ```yml
-hooks:  
+hooks:
   on_start_speaking: "mm-say"
   on_start_speaking: "mm-say"
 ```
 ```
 
 
-Then create a synapse in your `brain` that is linked to the hook to send each message. 
+Then create a synapse in your `brain` that is linked to the hook to send each message.
 As a concrete example, here the [magic mirror neuron](https://github.com/kalliope-project/kalliope_neuron_magic_mirror) is used to send each spelt out loud message to the Magic Mirror API in order to show them on the screen.
 As a concrete example, here the [magic mirror neuron](https://github.com/kalliope-project/kalliope_neuron_magic_mirror) is used to send each spelt out loud message to the Magic Mirror API in order to show them on the screen.
 ```yml
 ```yml
   - name: "mm-say"
   - name: "mm-say"
@@ -307,8 +318,8 @@ As a concrete example, here the [magic mirror neuron](https://github.com/kalliop
 
 
 **Note**
 **Note**
 
 
-`kalliope_last_tts_message` is overridden each time Kalliope says something. 
-For example, a common practice is to have a synapse placed in the hook `on_triggered` in order to know when the hotword has been triggered. 
+`kalliope_last_tts_message` is overridden each time Kalliope says something.
+For example, a common practice is to have a synapse placed in the hook `on_triggered` in order to know when the hotword has been triggered.
 So, if this synapse is configured like the following
 So, if this synapse is configured like the following
 ```yml
 ```yml
 - name: "on-triggered-synapse"
 - name: "on-triggered-synapse"
@@ -356,7 +367,7 @@ text_to_speech:
       cache: True
       cache: True
 ```
 ```
 
 
-And this is how I override only the cache parameter. 
+And this is how I override only the cache parameter.
 ```yml
 ```yml
 - systemdate:
 - systemdate:
     say_template:
     say_template:
@@ -375,7 +386,7 @@ You can override all parameter for each neurons like in the example bellow
       - say:
       - say:
           message:
           message:
             - "Buenos dias"
             - "Buenos dias"
-          tts:             
+          tts:
             pico2wave:
             pico2wave:
               language: "es-ES"
               language: "es-ES"
               cache: False
               cache: False

+ 2 - 2
Docs/player.md

@@ -1,4 +1,4 @@
-# Players                                                                                                                                         # Players
+# Players
 
 
 The player is the library/software used to make Kalliope talk.
 The player is the library/software used to make Kalliope talk.
 With Kalliope project, you can set whatever sound player you want to use.
 With Kalliope project, you can set whatever sound player you want to use.
@@ -38,7 +38,7 @@ players:
      convert_to_wav: True
      convert_to_wav: True
 ```
 ```
 
 
->**Note:** Sometime, parameters will be necessary to use an engine. 
+>**Note:** Sometime, parameters will be necessary to use an engine.
 Click on a Player engine link in the `Current CORE Available Players` section to know which parameter are required.
 Click on a Player engine link in the `Current CORE Available Players` section to know which parameter are required.
 
 
 >**Note:** A player which does not ask for input parameters need to be declared as an empty dict. E.g: ```- player_name: {}```
 >**Note:** A player which does not ask for input parameters need to be declared as an empty dict. E.g: ```- player_name: {}```

+ 22 - 6
Docs/rest_api.md

@@ -2,6 +2,22 @@
 
 
 Kalliope provides the REST API to manage the synapses. For configuring the API refer to the [settings documentation](settings.md).
 Kalliope provides the REST API to manage the synapses. For configuring the API refer to the [settings documentation](settings.md).
 
 
+- [Rest API](#rest-api)
+  - [Synapse API](#synapse-api)
+  - [Curl examples](#curl-examples)
+    - [Get Kalliope's version](#get-kalliopes-version)
+    - [List synapses](#list-synapses)
+    - [Show synapse details](#show-synapse-details)
+    - [Run a synapse by its name](#run-a-synapse-by-its-name)
+    - [Run a synapse from an order](#run-a-synapse-from-an-order)
+    - [Run a synapse from an audio file](#run-a-synapse-from-an-audio-file)
+    - [The neurotransmitter case](#the-neurotransmitter-case)
+    - [Get deaf status](#get-deaf-status)
+    - [Switch deaf status](#switch-deaf-status)
+  - [Mute flag](#mute-flag)
+    - [Get mute status](#get-mute-status)
+    - [Set mute status](#set-mute-status)
+
 ## Synapse API
 ## Synapse API
 
 
 | Method | URL                               | Action                             |
 | Method | URL                               | Action                             |
@@ -90,7 +106,7 @@ Output example:
 }
 }
 ```
 ```
 
 
-### Show synapse details 
+### Show synapse details
 
 
 Normal response codes: 200
 Normal response codes: 200
 Error response codes: unauthorized(401), itemNotFound(404)
 Error response codes: unauthorized(401), itemNotFound(404)
@@ -158,7 +174,7 @@ curl -i -H "Content-Type: application/json" --user admin:secret -X POST \
 -d '{"mute":"true"}' http://127.0.0.1:5000/synapses/start/id/say-hello-fr
 -d '{"mute":"true"}' http://127.0.0.1:5000/synapses/start/id/say-hello-fr
 ```
 ```
 
 
-Some neuron inside a synapse will wait for parameters that comes from the order. 
+Some neuron inside a synapse will wait for parameters that comes from the order.
 You can provide those parameters by adding a `parameters` list of data.
 You can provide those parameters by adding a `parameters` list of data.
 Curl command:
 Curl command:
 ```bash
 ```bash
@@ -179,7 +195,7 @@ curl -i --user admin:secret -H "Content-Type: application/json" -X POST -d '{"or
 
 
 If the order contains accent or quotes, use a file for testing with curl
 If the order contains accent or quotes, use a file for testing with curl
 ```bash
 ```bash
-cat post.json 
+cat post.json
 {"order":"j'aime"}
 {"order":"j'aime"}
 ```
 ```
 Then
 Then
@@ -310,12 +326,12 @@ Curl command:
 curl -i --user admin:secret -X POST http://localhost:5000/synapses/start/audio -F "file=@path/to/file.wav" -F mute="true"
 curl -i --user admin:secret -X POST http://localhost:5000/synapses/start/audio -F "file=@path/to/file.wav" -F mute="true"
 ```
 ```
 
 
-#### The neurotransmitter case
+### The neurotransmitter case
 
 
-In case of leveraging the [neurotransmitter neuron](https://github.com/kalliope-project/kalliope/tree/master/kalliope/neurons/neurotransmitter), Kalliope expects back and forth answers.
+In case of leveraging the [neurotransmitter neuron](../kalliope/neurons/neurotransmitter), Kalliope expects back and forth answers.
 Fortunately, the API provides a way to continue interaction with Kalliope and still use neurotransmitter neurons while doing API calls.
 Fortunately, the API provides a way to continue interaction with Kalliope and still use neurotransmitter neurons while doing API calls.
 
 
-When you start a synapse via its name or an order (like shown above), the answer of the API call will tell you in the response that kalliope is waiting for a response via the "status" return. 
+When you start a synapse via its name or an order (like shown above), the answer of the API call will tell you in the response that kalliope is waiting for a response via the "status" return.
 
 
 Status can either by ```complete``` (nothing else to do) or ```waiting_for_answer```, in which case Kalliope is waiting for your response :).
 Status can either by ```complete``` (nothing else to do) or ```waiting_for_answer```, in which case Kalliope is waiting for your response :).
 
 

+ 55 - 17
Docs/settings.md

@@ -2,6 +2,35 @@
 
 
 This part of the documentation explains the main configuration of Kalliope placed in the `settings.md` file.
 This part of the documentation explains the main configuration of Kalliope placed in the `settings.md` file.
 
 
+- [Kalliope settings](#kalliope-settings)
+  - [Triggers configuration](#triggers-configuration)
+    - [default_trigger](#defaulttrigger)
+    - [triggers](#triggers)
+  - [Players configuration](#players-configuration)
+    - [default_player](#defaultplayer)
+    - [players](#players)
+  - [Speech to text configuration](#speech-to-text-configuration)
+    - [default_speech_to_text](#defaultspeechtotext)
+    - [speech_to_text](#speechtotext)
+    - [recognition_options](#recognitionoptions)
+      - [energy_threshold](#energythreshold)
+      - [adjust_for_ambient_noise_second](#adjustforambientnoisesecond)
+  - [Text to speech configuration](#text-to-speech-configuration)
+    - [default_text_to_speech](#defaulttexttospeech)
+    - [text_to_speech](#texttospeech)
+  - [Hooks](#hooks)
+  - [Rest API](#rest-api)
+    - [active](#active)
+    - [port](#port)
+    - [password_protected](#passwordprotected)
+      - [Login](#login)
+    - [Password](#password)
+    - [Cors request](#cors-request)
+  - [Resources directory](#resources-directory)
+  - [Global Variables](#global-variables)
+  - [Start options](#start-options)
+  - [Next: configure the brain of Kalliope](#next-configure-the-brain-of-kalliope)
+
 ## Triggers configuration
 ## Triggers configuration
 
 
 ### default_trigger
 ### default_trigger
@@ -54,7 +83,7 @@ default_player: "mplayer"
 ### players
 ### players
 The player is the engine in charge of running sounds in Kalliope.
 The player is the engine in charge of running sounds in Kalliope.
 
 
-Each Players has it own configuration. 
+Each Players has it own configuration.
 This configuration is passed as argument following the syntax bellow
 This configuration is passed as argument following the syntax bellow
 ```yml
 ```yml
 players:
 players:
@@ -84,7 +113,7 @@ players:
 ```
 ```
 
 
 Sometime, parameters will be necessary to use an engine. See the [complete list here](player_list.md) to know which parameter are required.
 Sometime, parameters will be necessary to use an engine. See the [complete list here](player_list.md) to know which parameter are required.
-Core players are already packaged with the installation of Kalliope an can be used out of the box. 
+Core players are already packaged with the installation of Kalliope an can be used out of the box.
 
 
 >**Note:** Most cloud based TTS generate a file in MP3 format. Some players are not able to read this format and then a conversion to wav is needed.
 >**Note:** Most cloud based TTS generate a file in MP3 format. Some players are not able to read this format and then a conversion to wav is needed.
 
 
@@ -147,13 +176,13 @@ Represents the energy level threshold for sounds. By default set to **4000**.
 Values below this threshold are considered silence, and values above this threshold are considered speech.
 Values below this threshold are considered silence, and values above this threshold are considered speech.
 This is adjusted automatically if dynamic thresholds are enabled with `adjust_for_ambient_noise_second` parameter.
 This is adjusted automatically if dynamic thresholds are enabled with `adjust_for_ambient_noise_second` parameter.
 
 
-This threshold is associated with the perceived loudness of the sound, but it is a nonlinear relationship. 
-The actual energy threshold you will need depends on your microphone sensitivity or audio data. 
-Typical values for a silent room are 0 to 100, and typical values for speaking are between 150 and 3500. 
+This threshold is associated with the perceived loudness of the sound, but it is a nonlinear relationship.
+The actual energy threshold you will need depends on your microphone sensitivity or audio data.
+Typical values for a silent room are 0 to 100, and typical values for speaking are between 150 and 3500.
 Ambient (non-speaking) noise has a significant impact on what values will work best.
 Ambient (non-speaking) noise has a significant impact on what values will work best.
 
 
-If you're having trouble with the recognizer trying to recognize words even when you're not speaking, try tweaking this to a higher value. 
-If you're having trouble with the recognizer not recognizing your words when you are speaking, try tweaking this to a lower value. 
+If you're having trouble with the recognizer trying to recognize words even when you're not speaking, try tweaking this to a higher value.
+If you're having trouble with the recognizer not recognizing your words when you are speaking, try tweaking this to a lower value.
 For example, a sensitive microphone or microphones in louder rooms might have a ambient energy level of up to 4000.
 For example, a sensitive microphone or microphones in louder rooms might have a ambient energy level of up to 4000.
 ```yml
 ```yml
 recognition_options:
 recognition_options:
@@ -214,7 +243,7 @@ Some arguments are required, some other optional, please refer to the [TTS docum
 
 
 ## Hooks
 ## Hooks
 
 
-Hooking allow to bind actions to events based on the lifecycle of Kalliope. 
+Hooking allow to bind actions to events based on the lifecycle of Kalliope.
 For example, it's useful to know when Kalliope has detected the hotword from the trigger engine and make her spell out loud that she's ready to listen your order.
 For example, it's useful to know when Kalliope has detected the hotword from the trigger engine and make her spell out loud that she's ready to listen your order.
 
 
 To use a hook, attach the name of the hook to a synapse (or list of synapse) which exists in your brain.
 To use a hook, attach the name of the hook to a synapse (or list of synapse) which exists in your brain.
@@ -313,19 +342,19 @@ hooks:
 **brain.yml**
 **brain.yml**
 ```yml
 ```yml
 - name: "turn-on-led"
 - name: "turn-on-led"
-  signals: []   
+  signals: []
   neurons:
   neurons:
     - script:
     - script:
-        path: "/path/to/script.sh on" 
-        
+        path: "/path/to/script.sh on"
+
 - name: "turn-off-led"
 - name: "turn-off-led"
-  signals: []   
+  signals: []
   neurons:
   neurons:
     - script:
     - script:
-        path: "/path/to/script.sh off"  
+        path: "/path/to/script.sh off"
 ```
 ```
 
 
->**Note:** You cannot use a neurotransmitter neuron inside a synapse called from a hook. 
+>**Note:** You cannot use a neurotransmitter neuron inside a synapse called from a hook.
 You cannot use the "say" neuron inside the "on_start_speaking" or "on_stop_speaking" or it will create an infinite loop
 You cannot use the "say" neuron inside the "on_start_speaking" or "on_stop_speaking" or it will create an infinite loop
 
 
 ## Rest API
 ## Rest API
@@ -411,7 +440,7 @@ resource_directory:
 The Global Variables paths list where to load the global variables.
 The Global Variables paths list where to load the global variables.
 Those variables can be reused in neuron parameters within double brackets.
 Those variables can be reused in neuron parameters within double brackets.
 
 
-E.g 
+E.g
 ```yml
 ```yml
 var_files:
 var_files:
   - variables.yml
   - variables.yml
@@ -433,12 +462,12 @@ And use variables in your neurons:
       - order: "Wait for me "
       - order: "Wait for me "
     neurons:
     neurons:
       - uri:
       - uri:
-          url: "{{baseURL}}get/1"        
+          url: "{{baseURL}}get/1"
           user: "admin"
           user: "admin"
           password: "{{password}}"
           password: "{{password}}"
 ```
 ```
 
 
-> **Note:** Because YAML format does no allow double braces not surrounded by quotes: you must use the variable between double quotes. 
+> **Note:** Because YAML format does no allow double braces not surrounded by quotes: you must use the variable between double quotes.
 
 
 A global variable can be a dictionary. Example:
 A global variable can be a dictionary. Example:
 ```yml
 ```yml
@@ -459,13 +488,22 @@ And a synapse that use this dict:
 ```
 ```
 
 
 ## Start options
 ## Start options
+
 Options that can be defined when kalliope starts.
 Options that can be defined when kalliope starts.
 
 
 Example config
 Example config
 ```yaml
 ```yaml
 options:
 options:
   muted: True
   muted: True
+  deaf: False
 ```
 ```
 
 
+Available options:
+
+| Option | Description                                                                                   |
+| ------ | --------------------------------------------------------------------------------------------- |
+| muted  | When muted, the STT engine will not be used to make Kalliope talking during neurons execution |
+| deaf   | When deaf, the trigger engine is not started. Kalliope will not listen for a wake up word     |
+
 ## Next: configure the brain of Kalliope
 ## Next: configure the brain of Kalliope
 Now your settings are ok, you can start creating the [brain](brain.md) of your assistant.
 Now your settings are ok, you can start creating the [brain](brain.md) of your assistant.

+ 1 - 3
Docs/signals.md

@@ -11,13 +11,11 @@ signals:
 Or
 Or
 ```yml
 ```yml
 signals:
 signals:
-    - signal_type: 
+    - signal_type:
         parameter_key1: parameter_value1
         parameter_key1: parameter_value1
         parameter_key2: parameter_value2
         parameter_key2: parameter_value2
 ```
 ```
 
 
-
-
 ## Available signals
 ## Available signals
 
 
 Here is a list of core signal that are installed natively with Kalliope
 Here is a list of core signal that are installed natively with Kalliope

+ 6 - 0
Docs/stt.md

@@ -1,5 +1,11 @@
 # Speech To Text (STT)
 # Speech To Text (STT)
 
 
+- [Speech To Text (STT)](#speech-to-text-stt)
+    - [Settings](#settings)
+    - [Current CORE Available STT](#current-core-available-stt)
+    - [STT Community Installation](#stt-community-installation)
+    - [Full Example](#full-example)
+
 This chapter describes how STT engine works.
 This chapter describes how STT engine works.
 
 
 The STT is a programs or API that converts the speech into text.
 The STT is a programs or API that converts the speech into text.

+ 11 - 2
Docs/tts.md

@@ -1,5 +1,14 @@
 # Text to speech (TTS)
 # Text to speech (TTS)
 
 
+- [Text to speech (TTS)](#text-to-speech-tts)
+    - [Settings](#settings)
+        - [default_text_to_speech](#defaulttexttospeech)
+        - [text_to_speech](#texttospeech)
+        - [cache_path](#cachepath)
+    - [Current Available TTS](#current-available-tts)
+    - [TTS Community Installation](#tts-community-installation)
+    - [Full Example](#full-example)
+
 This chapter describes how TTS engine works.
 This chapter describes how TTS engine works.
 
 
 The TTS is a programs or API that converts a text into a speech.
 The TTS is a programs or API that converts a text into a speech.
@@ -33,8 +42,8 @@ Click on a TTS engine link in the `Current Available TTS` section to know which
 
 
 ### cache_path
 ### cache_path
 
 
-TTS engines work all the same, we give them a text, they give back an audio file and we play the audio file. The generated audio file is placed in cache until it 
-is played by the audio player. Before generating a new audio file, Kalliope will take a look to the cache to load it directly without having to call the 
+TTS engines work all the same, we give them a text, they give back an audio file and we play the audio file. The generated audio file is placed in cache until it
+is played by the audio player. Before generating a new audio file, Kalliope will take a look to the cache to load it directly without having to call the
 TSS engine if the file has been generated before.
 TSS engine if the file has been generated before.
 
 
 You must set a path where the cache will be saved in the tag `cache_path`. This one is placed in /tmp by default.
 You must set a path where the cache will be saved in the tag `cache_path`. This one is placed in /tmp by default.