Browse Source

Merge pull request #29 from kalliope-project/update_doc

Update doc
Monf 8 years ago
parent
commit
4a9e7cf43a
4 changed files with 192 additions and 6 deletions
  1. 1 1
      Docs/neuron_list.md
  2. 87 5
      Docs/neurons.md
  3. 75 0
      neurons/ansible_playbook/README.md
  4. 29 0
      neurons/gmail_checker/README.md

+ 1 - 1
Docs/neuron_list.md

@@ -11,7 +11,7 @@ A neuron is a module that will perform some actions attached to an order. You ca
 | [push_message](../neurons/push_message/)           | Send a push message to a remote device like Android/iOS/Windows Phone or Chrome browser | push_message      |
 | [say](../neurons/say/)                             | Make Kalliope talk by using TTS                                                         | say               |
 | [script](../neurons/script/)                       | Run an executable script                                                                | script            |
-| [shell](../neurons/command/)                       | Run a shell command                                                                     | shell             |
+| [shell](../neurons/shell/)                         | Run a shell command                                                                     | shell             |
 | [sleep](../neurons/sleep/)                         | Make Kalliope sleep for a while before continuing                                       | sleep             |
 | [systemdate](../neurons/systemdate/)               | Give the local system date and time                                                     | systemdate        |
 | [tasker_autoremote](../neurons/tasker_autoremote/) | Send a message to Android tasker app                                                    | tasker_autoremote |

+ 87 - 5
Docs/neurons.md

@@ -1,7 +1,7 @@
 # Neurons
 
-A neuron is a plugin that performs an action attached to some action. You can use it in 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 action is triggered.
+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.
 
 ## Usage
 Neurons are declared in the `neurons` section of a synapse in your brain file.
@@ -25,6 +25,89 @@ neurons:
 To know the list of required parameters, check of documentation of the neuron.
 Full list of [available neuron here](neuron_list.md)
 
+## Input values
+
+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 the captured order
+
+From the neuron declaration:
+```
+neurons:
+    - neuron_name:
+        parameter1: "value1"
+        parameter2: "value2"
+```
+
+From the captured order:
+```
+  - name: "run-neuron-with-parameter-in-order"
+    neurons:
+      - neuron_name:
+          parameter1: "value1"
+          parameter2: "value2"
+          args:
+          - parameter3
+    signals:
+      - order: "this is an order with the parameter {{ parameter3 }}"
+```
+
+Here, the spoken value captured by the TTS engine will be passed as an argument to the neuron in the variable named `parameter3`.
+
+Example, with the synapse declaration above, if you say "this is an order with the parameter Amy Winehouse". The neuron will receive a parameter named `parameter3` with "Amy Winehouse" as a value of this parameter.
+
+
+## Output values
+
+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.
+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 used in Kalliope is [Jinja2](http://jinja.pocoo.org/docs/dev/).
+
+For example, if we look at the [documentation of the neuron systemedate](../neurons/systemdate), we can see that the neuron will return a dictionary of value like `minute`, `hours` and all other values about the current time on the system where Kalliope is installed.
+
+A simple, that only use **variables**, template would be
+```
+It is {{ hours }} and {{ minutes }} minutes.
+```
+
+Placed in a complete synapse, it looks like the following
+```
+- name: "time"
+    neurons:
+      - systemdate:
+          say_template:
+            - "It is {{ hours }} hours and {{ minutes }} minutes"
+    signals:
+      - order: "what time is it"
+```
+
+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`.
+
+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.
+```
+{% if hours > 8 %}
+    It is late, isn't it?
+{% else %}
+    We still have time
+{% endif %}
+```
+
+As this is multi-lines, we can put the content in a file and use a `file_template` instead of a `say_template` for more clarity.
+```
+- name: "time"
+    neurons:
+      - systemdate:
+          file_template: /path/to/file/template.j2
+    signals:
+      - order: "what time is it"
+```
+
+
+
 ## Overridable parameters
 
 For each neuron, you can override some parameters to use a specific configuration of TTS instead of the default one 
@@ -33,15 +116,14 @@ set in [settings.yml](settings.yml) file.
 ### Cache
 
 You can override the default cache configuration. By default Kalliope uses a cache to save a generated audio from a TTS engine.
-This cache is usefull to not to regenerate often used sentences that are not suppose to be changed very often. For exemple, the following sentence will not change in time, so it's more optimized to generate it once and to keep it in cash:
+This cache is usefull to manage sentences that are not suppose to be changed very often. For exemple, the following sentence will not change in time, so it's more optimized to generate it once and to keep it in cash:
 ```
 - say:
     message:
       - "Hello, sir"
 ```
 
-In some cases, especially when the neuron is based on a template, the generated audio will change at each new call of the neuron and so the usage 
-of a cache is not necessary. The best example of the case like this is the `systemdate` neuron. As the time changes every minute, the generated audio will change too and so, saving the generated audio in the cache is useless. In this case, you can override the cache usage for this neuron:
+In some cases, especially when the neuron is based on a template, the generated audio will change on each new call of the neuron and so the usage of a cache is not necessary. The best example of the case like this is the `systemdate` neuron. As the time changes every minute, the generated audio will change too and so, saving the generated audio in the cache is useless. In this case, you can override the cache usage for this neuron:
 ```
 - systemdate:
     say_template:

+ 75 - 0
neurons/ansible_playbook/README.md

@@ -0,0 +1,75 @@
+# ansible_playbook
+
+## Synopsis
+
+Run an Ansible playbook. Ansible is a free-software platform for configuring and managing computers which combines multi-node software deployment, ad hoc task execution, and configuration management.
+
+Playbooks are Ansible’s configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
+
+This neuron can be used to perform complex operation with all [modules available from Ansible](http://docs.ansible.com/ansible/modules.html).
+
+
+## Options
+
+| parameter | required | default | choices | comment                                      |
+|-----------|----------|---------|---------|----------------------------------------------|
+| task_file | YES      |         |         | path to the Playbook file that contain tasks |
+
+
+
+## Synapses example
+
+Call the playbook named playbook.yml
+```
+   - name: "Ansible-test"
+    neurons:
+      - ansible_playbook: "playbook.yml"
+      - say:
+          message: "Tache terminée"
+    signals:
+      - order: "playbook"
+```
+
+Content of the playbook. This playbook will use the [URI module](http://docs.ansible.com/ansible/uri_module.html) to interact with a webservice on a remote server.
+```
+---
+- name: Playbook
+  hosts: localhost
+  gather_facts: no
+  connection: local
+
+  tasks:   
+    - 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": "start"}
+```
+
+
+## Note
+
+Ansible contain a lot of modules that can be useful for Kalliope
+
+- [Notification](http://docs.ansible.com/ansible/list_of_notification_modules.html): can be used to send a message to Pushbullet, IRC channel, Rocket Chat and a lot of other notification services
+- [Files](http://docs.ansible.com/ansible/list_of_files_modules.html): can be used to perform a backup or synchronize two file path
+- [Windows](http://docs.ansible.com/ansible/list_of_windows_modules.html): Can be used to control a Windows Desktop
+
+Shell neuron or script neuron can perform same actions. Ansible is just a way to simplify some execution or enjoy some [already made plugin](http://docs.ansible.com/ansible/modules_by_category.html). 
+
+Here is the example of synapse you would use to perform a call to a web service without Ansible:
+```
+- name: "start-music"
+    neurons:
+      - shell:
+          cmd: "curl -i --user admin:secret -H \"Content-Type: application/json\" -X POST -d '{\"app_name\":\"music\",\"state\":\"start\"}' http://192.168.0.17:8000/app"      
+    signals:
+      - order: "start music rock"
+```

+ 29 - 0
neurons/gmail_checker/README.md

@@ -34,6 +34,35 @@ Simple example :
       - order: "Do I have emails"
 ```
 
+A complex example that read subject emails. This is based on a file_template
+```
+  - name: "check-email"
+    neurons:
+      - gmail_checker:
+          username: "me@gmail.com"
+          password: "my_password"
+          file_template: /templates/my_email_template.j2            
+    signals:
+      - order: "Do I have emails"
+```
+
+Here the content of the `my_email_template.j2`
+```
+You have {{ unread }} email
 
+{% set count = 1 %}
+{% if unread > 0 %}
+    {% for subject in subjects %}
+     email number {{ count }}. {{ subject }}
+     {% set count = count + 1 %}
+    {% endfor %}
+{% endif %}
+```
 ## Notes
 
+Gmail now prevent some mailbox to be accessed from tier application. If you receive a mail like the following:
+```
+Sign-in attempt prevented ... Someone just tried to sign in to your Google Account mail@gmail.com from an app that doesn't meet modern security standards.
+```
+
+You can allow this neuron to get un access to your email in your [Gmail account settings](https://www.google.com/settings/security/lesssecureapps).