|
@@ -0,0 +1,105 @@
|
|
|
+# shell
|
|
|
+
|
|
|
+## Synopsis
|
|
|
+
|
|
|
+Run a shell command on the local system where Kalliope is installed.
|
|
|
+
|
|
|
+
|
|
|
+## Options
|
|
|
+
|
|
|
+| parameter | required | default | choices | comment |
|
|
|
+|-----------|----------|---------|----------|-----------------------------------------------------------------------------|
|
|
|
+| cmd | yes | | | The shell command to run |
|
|
|
+| async | no | False | | If True, Kalliope will not wait for the end of the execution of the command |
|
|
|
+
|
|
|
+
|
|
|
+## Return Values
|
|
|
+
|
|
|
+Values are only returned by the neuron if the async mode is set to `False`.
|
|
|
+
|
|
|
+| Name | Description | Type | sample |
|
|
|
+|------------|-------------------------------------------------------------------------------------------------------|--------|-------------------------------|
|
|
|
+| output | The shell output of the command if any. The command "date" will retun "Sun Oct 16 15:50:45 CEST 2016" | string | Sun Oct 16 15:50:45 CEST 2016 |
|
|
|
+| returncode | The returned code of the command. Return 0 if the command was succesfuly exectued, else 1 | int | 0 |
|
|
|
+
|
|
|
+
|
|
|
+## Synapses example
|
|
|
+
|
|
|
+Simple that will create a file locally
|
|
|
+```
|
|
|
+ - name: "create a local file"
|
|
|
+ neurons:
|
|
|
+ - shell:
|
|
|
+ cmd: "touch ~/test.txt"
|
|
|
+ signals:
|
|
|
+ - order: "touch"
|
|
|
+```
|
|
|
+
|
|
|
+We want to launch our favorite web radio. This command, which it call mplayer, will block the entire Kalliope process if we
|
|
|
+wait for the result unless the mplayer process is killed. So we add async parameter.
|
|
|
+```
|
|
|
+ - name: "run web radio"
|
|
|
+ neurons:
|
|
|
+ - shell:
|
|
|
+ cmd: "mplayer http://192.99.17.12:6410/"
|
|
|
+ async: True
|
|
|
+ - say:
|
|
|
+ message: "web radio lanched"
|
|
|
+ signals:
|
|
|
+ - order: "run web radio"
|
|
|
+```
|
|
|
+If the parameter `async` is set to True, the neuron will not return any values.
|
|
|
+
|
|
|
+
|
|
|
+Then, we can kill the player process with another synapse
|
|
|
+```
|
|
|
+ - name: "stop web radio"
|
|
|
+ neurons:
|
|
|
+ - shell:
|
|
|
+ cmd: "pkill mplayer"
|
|
|
+ - say:
|
|
|
+ message: "web radio stopped"
|
|
|
+ signals:
|
|
|
+ - order: "stop web radio"
|
|
|
+```
|
|
|
+
|
|
|
+Make Kalliope add two number and speak out loud the result. Here you should hear "4".
|
|
|
+```
|
|
|
+ - name: "get the result of the addition: 1 + 3"
|
|
|
+ neurons:
|
|
|
+ - shell:
|
|
|
+ cmd: "echo $(expr \"1\" + \"3\")"
|
|
|
+ say_template: "{{ output }}"
|
|
|
+ signals:
|
|
|
+ - order: "addition"
|
|
|
+```
|
|
|
+
|
|
|
+Let's use a file template. We try to remove the file `~/test.txt` and make Kalliope gice us the result depending of the
|
|
|
+returned error code.
|
|
|
+If the file is present on the system, you will hear "The command has succeeded" and so the file has been deleted.
|
|
|
+If you run it a second time, the command will fail as the file is not anymore present and so you should hear
|
|
|
+"The command has failed". See the template example bellow.
|
|
|
+```
|
|
|
+ - name: "remove a file"
|
|
|
+ neurons:
|
|
|
+ - shell:
|
|
|
+ cmd: "rm ~/test.txt"
|
|
|
+ file_template: remove_file.j2
|
|
|
+ signals:
|
|
|
+ - order: "rm file"
|
|
|
+```
|
|
|
+
|
|
|
+## Templates example
|
|
|
+
|
|
|
+Template `remove_file.j2` used in the remove file example remove_file.j2
|
|
|
+```
|
|
|
+{% if returncode == 0 %}
|
|
|
+ The command succeeded
|
|
|
+{% else %}
|
|
|
+ The command failled
|
|
|
+{% endif %}
|
|
|
+```
|
|
|
+
|
|
|
+## Notes
|
|
|
+
|
|
|
+> **Note:** If the parameter `async` is set to True, the neuron will not return any values.
|