Răsfoiți Sursa

add mqtt doc
update signals doc. split into a dedicated doc per signal
revert brain

nico 7 ani în urmă
părinte
comite
3c4dc010a0

+ 12 - 163
Docs/signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-A signal is an input event triggered by a synapse. When a signal is caught, Kalliope runs attached neurons of the synapse. The signal can be of two types: order and event.
+A signal is an input event triggered by a synapse. When a signal is caught, Kalliope runs attached neurons of the synapse.
 
 The syntax is the following
 ```yml
@@ -8,173 +8,22 @@ signals:
     - signal_type: parameter
 ```
 
-## Order
-
-### Simple order
-An **order** signal is a word, or a sentence caught by the microphone and processed by the STT engine.
-
-Syntax:
-```yml
-signals:
-    - order: "<sentence>"
-```
-
-Example:
-```yml
-signals:
-    - order: "please do this action"
-```
-
-> **Important note:** SST engines can misunderstand what you say, or translate your sentence into text containing some spelling mistakes.
-For example, if you say "Kalliope please do this", the SST engine can return "caliope please do this". So, to be sure that your speaking order will be correctly caught and executed, we recommend you to test your STT engine by using the [Kalliope GUI](kalliope_cli.md) and check the returned text for the given order.
-
-> **Important note:** STT engines don't know the context. Sometime they will return an unexpected word.
-For example, "the operation to perform is 2 minus 2" can return "two", "too", "to" or "2" in english.
-
-> **Important note:** Kalliope will try to match the order in each synapse of its brain. So, if an order of one synapse is included in another order of another synapse, then both synapses tasks will be started by Kalliope.
-
-> For example, you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
-will be started by Kalliope. So keep in mind that the best practice is to use really different sentences with more than one word for your order.
-
-### Order with arguments
-You can add one or more arguments to an order by adding bracket to the sentence.
-
-Syntax:
-```yml
-signals:
-    - order: "<sentence> {{ arg_name }}"
-    - order: "<sentence> {{ arg_name }} <sentence>"
-    - order: "<sentence> {{ arg_name }} <sentence> {{ arg_name }}"
-```
-
-Example:
-```yml
-signals:
-    - order: "I want to listen {{ artist_name }}"
-    - order: "start the {{ episode_number }} episode"
-    - order: "give me the weather at {{ location }} for {{ date }}"
-```
-
-Here, an example order would be speaking out loud the order: "I want to listen Amy Winehouse"
-In this example, both word "Amy" and "Winehouse" will be passed as an unique argument called `artist_name` to the neuron.
-
-If you want to send more than one argument, you must split your argument with a word that Kalliope will use to recognise the start and the end of each arguments.
-For example:  "give me the weather at {{ location }} for {{ date }}"
-And the order would be: "give me the weather at Paris for tomorrow"
-And so, it will work too with: "give me the weather at St-Pierre de Chartreuse for tomorrow"
-
-See the **input values** section of the [neuron documentation](neurons) to know how to send arguments to a neuron.
-
->**Important note:** The following syntax cannot be used: "<sentence> {{ arg_name }} {{ arg_name2 }}" as Kalliope cannot know when a block starts and when it finishes.
-
-## Event
-
-An event is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.
-
-The event system is based on [APScheduler](http://apscheduler.readthedocs.io/en/latest/modules/triggers/cron.html) which it is itself based on [Linux crontab](https://en.wikipedia.org/wiki/Cron). 
-When you declare an event in the signal, Kalliope will schedule the launching of the target synapse.
-
-The syntax of an event declaration in a synapse is the following
+Or
 ```yml
 signals:
-  - event:
-      parameter1: "value1"
-      parameter2: "value2"
+    - signal_type: 
+        parameter_key1: parameter_value1
+        parameter_key2: parameter_value2
 ```
 
-For example, if we want Kalliope to run the synapse every day a 8:30, the event will be declared like this:
-```yml
-- event:
-    hour: "8"
-    minute: "30"
-```
-
-### Parameters
-Parameters are keyword you can use to build your event
-
-List of available parameter:
-
-| parameter   | required | default | choices                                                         | comment   |
-|-------------|----------|---------|-----------------------------------------------------------------|-----------|
-| year        | no       | *       | 4 digit                                                         | E.g: 2016 |
-| month       | no       | *       | month (1-12)                                                    |           |
-| day         | no       | *       | day of the (1-31)                                               |           |
-| week        | no       | *       | ISO week (1-53)                                                 |           |
-| day_of_week | no       | *       | number or name of weekday  (0-6 or mon,tue,wed,thu,fri,sat,sun) | 6=Sunday  |
-| hour        | no       | *       | hour (0-23)                                                     |           |
-| minute      | no       | *       | minute (0-59)                                                   |           |
-| second      | no       | *       | second (0-59)                                                   |           |
-
-> **Note:** You must set at least one parameter from the list of parameter
-
-### Expression 
-Expressions can be used in value of each parameter. Multiple expression can be given in a single field, separated by commas.
-
-| Expression | Field | Description                                                                             |
-|------------|-------|-----------------------------------------------------------------------------------------|
-| *          | any   | Fire on every value                                                                     |
-| */a        | any   | Fire every `a` values, starting from the minimum                                        |
-| a-b        | any   | Fire on any value within the `a-b` range (a must be smaller than b)                     |
-| a-b/c      | any   | Fire every c values within the `a-b` range                                              |
-| xrd y      | day   | Fire on the `x` -rd occurrence of weekday `y` within the month                          |
-| last x     | day   | Fire on the last occurrence of weekday `x` within the month                             |
-| last x     | day   | Fire on the last day within the month                                                   |
-| x,y,z      | day   | Fire on any matching expression; can combine any number of any of the above expressions |
 
 
-### Examples
+## Available signals
 
-#### Web clock radio
+Here is a list of core signal that are installed natively with Kalliope
 
-Let's make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7:30 AM and:
-- Wish us good morning
-- Give us the time
-- Play our favourite web radio
-
-The synapse in the brain would be
-```yml
-  - name: "wake-up"
-    signals:
-      - event:
-          hour: "7"
-          minute: "30"
-          day_of_week: "1,2,3,4,5"
-    neurons:
-      - say:
-          message:
-            - "Good morning"
-      - systemdate:
-          say_template:
-            - "It is {{ hours }} hours and {{ minutes }} minutes"
-      - shell: 
-          cmd: "mplayer http://192.99.17.12:6410/"
-          async: True
-```
-
-After setting up an event, you must restart Kalliope
-```bash
-python kalliope.py start
-```
-
-If the syntax is ok, Kalliope will show you each synapse that it has loaded in the crontab
-```
-Add synapse name "wake-up" to the scheduler: cron[day_of_week='1,2,3,4,5', hour='7', minute='30']
-Event loaded
-```
-
-That's it, the synapse is now scheduled and will be started automatically.
-
-
-####  Make Kalliope say something on the third Friday of June, July, August, November and December at 00:00, 01:00, 02:00 and 03:00
-```yml
-- name: "wake-up"
-  signals:
-    - event:
-        day: "3rd fri"        
-        month: "6-8,11-12"
-        hour: "0-3"        
-  neurons:
-    - say:
-        message:
-          - "This is a schedulled sentence"
-```
+| Name                                                   | Description                                                       |
+|--------------------------------------------------------|-------------------------------------------------------------------|
+| [event](../kalliope/signals/event)                     | Launch synapses periodically at fixed times, dates, or intervals. |
+| [mqtt_subscriber](../kalliope/signals/mqtt_subscriber) | Launch synapse from when receive a message from a MQTT broker     |
+| [order](../kalliope/signals/order)                     | Launch synapses from captured vocal order from the microphone     |

+ 0 - 39
kalliope/brain.yml

@@ -26,42 +26,3 @@
             - "Veuillez renouveller votre ordre"
             - "Veuillez reformuller s'il vous plait"
             - "Je n'ai pas saisi cet ordre"
-
-# https://pypi.python.org/pypi/paho-mqtt/1.3.0#constructor-reinitialise
-  - name: "test-mqtt-1"
-    signals:
-      - mqtt_subscriber:
-          broker_ip: "127.0.0.1"
-          broker_port: 8883
-          is_json: True
-          topic: "topic1"
-          username: "guest"
-          password: "guest"
-          ca_cert: "/home/nico/Desktop/PKI_rabbit/ca.cert"
-#          certfile: "/home/nico/Desktop/PKI_rabbit/client.crt"
-#          keyfile: "/home/nico/Desktop/PKI_rabbit/client.key"
-          tls_insecure: True
-    neurons:
-      - say:
-          message:
-            - "Bonjour monsieur {{ mqtt_subscriber_message['test'] }}"
-
-#  - name: "test-mqtt-2"
-#    signals:
-#      - mqtt_subscriber:
-#          broker_ip: "127.0.0.1"
-#          topic: "topic3"
-#    neurons:
-#      - say:
-#          message:
-#            - "Bonjour monsieur"
-#
-#  - name: "test-mqtt-3"
-#    signals:
-#      - mqtt_subscriber:
-#          broker_ip: "127.0.0.1"
-#          topic: "topic1"
-#    neurons:
-#      - say:
-#          message:
-#            - "Bonjour monsieur"

+ 114 - 0
kalliope/signals/event/README.md

@@ -0,0 +1,114 @@
+# Event
+
+## Synopsis
+
+An **event** is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.
+
+The event system is based on [APScheduler](http://apscheduler.readthedocs.io/en/latest/modules/triggers/cron.html) which it is itself based on [Linux crontab](https://en.wikipedia.org/wiki/Cron). 
+When you declare an event in the signal, Kalliope will schedule the launching of the target synapse.
+
+The syntax of an event declaration in a synapse is the following
+```yml
+signals:
+  - event:
+      parameter1: "value1"
+      parameter2: "value2"
+```
+
+For example, if we want Kalliope to run the synapse every day a 8:30, the event will be declared like this:
+```yml
+- event:
+    hour: "8"
+    minute: "30"
+```
+
+## Options
+
+Parameters are keyword you can use to build your event
+
+List of available parameter:
+
+| parameter   | required | default | choices                                                         | comment   |
+|-------------|----------|---------|-----------------------------------------------------------------|-----------|
+| year        | no       | *       | 4 digit                                                         | E.g: 2016 |
+| month       | no       | *       | month (1-12)                                                    |           |
+| day         | no       | *       | day of the (1-31)                                               |           |
+| week        | no       | *       | ISO week (1-53)                                                 |           |
+| day_of_week | no       | *       | number or name of weekday  (0-6 or mon,tue,wed,thu,fri,sat,sun) | 6=Sunday  |
+| hour        | no       | *       | hour (0-23)                                                     |           |
+| minute      | no       | *       | minute (0-59)                                                   |           |
+| second      | no       | *       | second (0-59)                                                   |           |
+
+> **Note:** You must set at least one parameter from the list of parameter
+
+Expressions can be used in value of each parameter. Multiple expression can be given in a single field, separated by commas.
+
+| Expression | Field | Description                                                                             |
+|------------|-------|-----------------------------------------------------------------------------------------|
+| *          | any   | Fire on every value                                                                     |
+| */a        | any   | Fire every `a` values, starting from the minimum                                        |
+| a-b        | any   | Fire on any value within the `a-b` range (a must be smaller than b)                     |
+| a-b/c      | any   | Fire every c values within the `a-b` range                                              |
+| xrd y      | day   | Fire on the `x` -rd occurrence of weekday `y` within the month                          |
+| last x     | day   | Fire on the last occurrence of weekday `x` within the month                             |
+| last x     | day   | Fire on the last day within the month                                                   |
+| x,y,z      | day   | Fire on any matching expression; can combine any number of any of the above expressions |
+
+
+## Synapses example
+
+### Web clock radio
+
+Let's make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7:30 AM and:
+- Wish us good morning
+- Give us the time
+- Play our favourite web radio
+
+The synapse in the brain would be
+```yml
+  - name: "wake-up"
+    signals:
+      - event:
+          hour: "7"
+          minute: "30"
+          day_of_week: "1,2,3,4,5"
+    neurons:
+      - say:
+          message:
+            - "Good morning"
+      - systemdate:
+          say_template:
+            - "It is {{ hours }} hours and {{ minutes }} minutes"
+      - shell: 
+          cmd: "mplayer http://192.99.17.12:6410/"
+          async: True
+```
+
+After setting up an event, you must restart Kalliope
+```bash
+python kalliope.py start
+```
+
+If the syntax is ok, Kalliope will show you each synapse that it has loaded in the crontab
+```
+Add synapse name "wake-up" to the scheduler: cron[day_of_week='1,2,3,4,5', hour='7', minute='30']
+Event loaded
+```
+
+That's it, the synapse is now scheduled and will be started automatically.
+
+
+###  Make Kalliope say something on the third Friday of June, July, August, November and December at 00:00, 01:00, 02:00 and 03:00
+
+```yml
+- name: "wake-up"
+  signals:
+    - event:
+        day: "3rd fri"        
+        month: "6-8,11-12"
+        hour: "0-3"        
+  neurons:
+    - say:
+        message:
+          - "This is a schedulled sentence"
+```

+ 3 - 1
kalliope/signals/mqtt_subscriber/MqttClient.py

@@ -100,7 +100,9 @@ class MqttClient(Thread):
         # convert payload to a dict if necessary
         if target_topic.is_json:
             message = json.loads(message)
-            logger.debug("[MqttClient] Payload converted to JSON dict: %s" % message)
+            logger.debug("[MqttClient] Payload message converted to JSON dict: %s" % message)
+        else:
+            logger.debug("[MqttClient] Payload message is plain text: %s" % message)
 
         # run each synapse
         for synapse in target_topic.synapses:

+ 171 - 7
kalliope/signals/mqtt_subscriber/README.md

@@ -1,8 +1,173 @@
 # MQTT Subscriber
 
+## Synopsis
+
+Launch synapses when receiving a message on a topic from a MQTT messaging broker server.
+
+>MQTT is a Client Server publish/subscribe messaging transport protocol. 
+It is mostly used in communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts.
+The main concept is that a client will publish a message attached to a "topic" to a server called a "broker", and other clients which are interested by the topic will subscribe to it. 
+The broker filters all incoming messages and distributes them accordingly.
+
+## Options
+
+| parameter    | required | default  | choices             | comment                                                                                                                                          |
+|--------------|----------|----------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| broker_ip    | YES      |          |                     | IP address of the MQTT broker server                                                                                                             |
+| topic        | YES      |          |                     | topic name to subscribe                                                                                                                          |
+| is_json      | NO       | FALSE    | True, False         | if true, all received message will be converted into a dict                                                                                      |
+| broker_port  | NO       | 1883     |                     | Port of the broker. By default 1883. 8883 when TLS is activated.                                                                                 |
+| client_id    | NO       | kalliope |                     | The client identifier is an identifier of each MQTT client and used by the broker server for identifying the client. Should be unique per broker |
+| keepalive    | NO       | 60       |                     | A time interval in seconds where the clients commits to by sending regular PING Request messages to the broker.                                  |
+| username     | NO       |          |                     | username for authenticating the client                                                                                                           |
+| password     | NO       |          |                     | password for authenticating the client                                                                                                           |
+| protocol     | NO       | MQTTv311 |   MQTTv31, MQTTv311 | Can be either MQTTv31 or MQTTv311                                                                                                                |
+| ca_cert      | NO       |          |                     | Path to the remote server CA certificate used for securing the transport                                                                         |
+| certfile     | NO       |          |                     | Path to the client certificate file used for authentication                                                                                      |
+| keyfile      | NO       |          |                     | Path to the client key file attached to the client certificate                                                                                   |
+| tls_insecure | NO       | FALSE    | True, False         | Set the verification of the server hostname in the server certificate                                                                            |
+
+
+## Values sent to the synapse
+
+| Name                    | Description                      | Type        | sample                                               |
+|-------------------------|----------------------------------|-------------|------------------------------------------------------|
+| mqtt_subscriber_message | message received from the broker | string/dict | "on", "off", {"temperature": "25", "humidity": "30"} |
+
+
+## Synapses example
+
+### Topic with plain text message
+
+The topic send the status of a light. The received message would be "on" or off"
+```yml
+- name: "test-mqtt-1"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        topic: "topic1"
+  neurons:
+    - say:
+        message:
+          - "The light is now {{ mqtt_subscriber_message }}"
+```
+
+Kalliope output example:
+```
+The light is now on
+```
+
+### Topic with json message
+
+In this example, the topic send a json payload that contain multiple information. E.g: `{"temperature": "25", "humidity": "30"}`
+```yml
+- name: "test-mqtt-2"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        topic: "topic2"
+        is_json: True
+  neurons:
+    - say:
+        message:
+          - "The temperature is now {{ mqtt_subscriber_message['temperature'] }}, humidity {{ mqtt_subscriber_message['humidity'] percents }}"
+```
+
+Kalliope output example:
+```
+The temperature is now 25 degrees, humidity 30%
+```
+
+### The broker require authentication
+
+Password authentication
+```yml
+- name: "test-mqtt-3"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        topic: "topic 3"
+        username: "guest"
+        password: "guest"
+  neurons:
+    - say:
+        message:
+          - "Message received on topic 3"
+```
+
+It's better to use TLS when using password authentication for securing the transport
+```yml
+- name: "test-mqtt-4"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        broker_port: 8883
+        topic: "topic 4"
+        username: "guest"
+        password: "guest"
+        ca_cert: "/path/to/ca.cert"
+        tls_insecure: True
+  neurons:
+    - say:
+        message:
+          - "Message received on topic 3"
+```
+
+Authentication based on client certificate
+```yml
+- name: "test-mqtt-5"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        broker_port: 8883
+        topic: "topic 5"
+        ca_cert: "/path/to/ca.cert"
+        tls_insecure: True
+        certfile: "/path/to/client.crt"
+        keyfile: "/path/to/client.key"
+  neurons:
+    - say:
+        message:
+          - "Message received on topic 5"
+```
+
+## Notes
+
+When you want to use the same broker within your multiple synapses in your brain, you must keep in mind that the configuration must be the same
+It means that you cannot declare a synapse that use a broker ip with TLS activated, and another synapse that use the same broker ip but without TLS activated.
+When you declare a "broker_ip", a unique object is created once, then topic are added following all synapses
+
+On the other hand, you can subscribe to multiple topic that use json or not within the same broker ip.
+```yml
+- name: "synapse-mqtt-1"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        topic: "topic1"
+        is_json: False
+  neurons:
+    - say:
+        message:
+          - "I'm started when message on topic 1"
+
+- name: "synapse-mqtt-2"
+  signals:
+    - mqtt_subscriber:
+        broker_ip: "127.0.0.1"
+        topic: "topic2"
+        is_json: True
+  neurons:
+    - say:
+        message:
+          - "I'm started when message on topic 2"
+``` 
+
+
 
 ## Test with rabbitmq-server broker
 
+This part can help you to configure your brain by sending message to a local broker
+
 ### Install rabbitmq
 
 ```
@@ -15,7 +180,7 @@ sudo rabbitmq-plugins enable rabbitmq_mqtt
 sudo systemctl restart rabbitmq-server
 ```
 
-Active web ui
+Active web ui (optional)
 ```bash
 sudo rabbitmq-plugins enable rabbitmq_management
 ```
@@ -27,20 +192,21 @@ sudo mv rabbitmqadmin /etc/rabbitmqadmin
 sudo chmod 755 /etc/rabbitmqadmin
 ```
 
-Create admin account
+Create admin account (when UI installed)
 ```bash
 sudo rabbitmqctl add_user admin p@ssw0rd
 sudo rabbitmqctl set_user_tags admin administrator
 sudo rabbitmqctl set_permissions -p / admin ".*" ".*" ".*"
 ```
 
-### Test publish
-Publish a message with amqp-tools in the default rabbitmq exchange with the topic key "test.light"
+### Publish message from CLI
+
+Publish a message with amqp-tools in the default rabbitmq exchange (amq.topic) with the topic key "test.light"
 ```
 amqp-publish -e "amq.topic" -r "test.light" -b "your message"
 ```
 
-Test publish json
+Test publish a json message
 ```
 amqp-publish -e "amq.topic" -r "test.light" -b '{"test" : "message"}'
 ```
@@ -115,5 +281,3 @@ Restart rabbitmq server to take care of changes
 ```bash
 sudo systemctl restart rabbitmq-server
 ```
-
-

+ 73 - 0
kalliope/signals/order/README.md

@@ -0,0 +1,73 @@
+# Order
+
+## Synopsis
+
+An **order** signal is a word, or a sentence caught by the microphone and processed by the STT engine.
+
+## Options
+
+| parameter | required | default | choices | comment                                             |
+|-----------|----------|---------|---------|-----------------------------------------------------|
+| order     | YES      |         |         | The order is passed directly without any parameters |
+
+## Values sent to the synapse
+
+None
+
+## Synapses example
+
+### Simple order
+
+Syntax:
+```yml
+signals:
+    - order: "<sentence>"
+```
+
+Example:
+```yml
+signals:
+    - order: "please do this action"
+```
+
+> **Important note:** SST engines can misunderstand what you say, or translate your sentence into text containing some spelling mistakes.
+For example, if you say "Kalliope please do this", the SST engine can return "caliope please do this". So, to be sure that your speaking order will be correctly caught and executed, we recommend you to test your STT engine by using the [Kalliope GUI](kalliope_cli.md) and check the returned text for the given order.
+
+> **Important note:** STT engines don't know the context. Sometime they will return an unexpected word.
+For example, "the operation to perform is 2 minus 2" can return "two", "too", "to" or "2" in english.
+
+> **Important note:** Kalliope will try to match the order in each synapse of its brain. So, if an order of one synapse is included in another order of another synapse, then both synapses tasks will be started by Kalliope.
+
+> For example, you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
+will be started by Kalliope. So keep in mind that the best practice is to use really different sentences with more than one word for your order.
+
+### Order with arguments
+You can add one or more arguments to an order by adding bracket to the sentence.
+
+Syntax:
+```yml
+signals:
+    - order: "<sentence> {{ arg_name }}"
+    - order: "<sentence> {{ arg_name }} <sentence>"
+    - order: "<sentence> {{ arg_name }} <sentence> {{ arg_name }}"
+```
+
+Example:
+```yml
+signals:
+    - order: "I want to listen {{ artist_name }}"
+    - order: "start the {{ episode_number }} episode"
+    - order: "give me the weather at {{ location }} for {{ date }}"
+```
+
+Here, an example order would be speaking out loud the order: "I want to listen Amy Winehouse"
+In this example, both word "Amy" and "Winehouse" will be passed as an unique argument called `artist_name` to the neuron.
+
+If you want to send more than one argument, you must split your argument with a word that Kalliope will use to recognise the start and the end of each arguments.
+For example:  "give me the weather at {{ location }} for {{ date }}"
+And the order would be: "give me the weather at Paris for tomorrow"
+And so, it will work too with: "give me the weather at St-Pierre de Chartreuse for tomorrow"
+
+See the **input values** section of the [neuron documentation](neurons) to know how to send arguments to a neuron.
+
+>**Important note:** The following syntax cannot be used: "<sentence> {{ arg_name }} {{ arg_name2 }}" as Kalliope cannot know when a block starts and when it finishes.