Skip to content

Commit

Permalink
Merge pull request #401 from kalliope-project/dev
Browse files Browse the repository at this point in the history 
Release 0.5
  • Loading branch information
@Sispheor
Sispheor committed Jan 13, 2018
2 parents c882c9d + bc01067 commit b3f21be
Show file tree
Hide file tree
Showing 79 changed files with 2,325 additions and 1,406 deletions.
14 changes: 14 additions & 0 deletions CHANGELOG.md
View file
@@ -1,3 +1,17 @@
v0.5.0 / 2018-01-13
===================
- Fix: recognition option in settings
- Fix: no_voice flag in neurotransmitter neuron no longer lost
- Fix: retrieve parameters when user order contains non matching words
- Fix: Update Voicerss TTS
- Fix: Usage of double brackets with json sentence
- Fix: Remove acapela TTS
- Feature: Kalliope can be started muted
- Feature: add geolocation signals
- Feature: add Watson TTS
- Feature: Hook. WARNING: This is a breaking change. Settings must be updated
- Feature: add normal, strict and ordered-strict order

v0.4.6 / 2017-10-03
===================
- add core neuron: neurotimer
Expand Down
14 changes: 14 additions & 0 deletions Docs/kalliope_cli.md
View file
Expand Up @@ -96,6 +96,20 @@ You can combine the options together like, for example:
kalliope start --run-synapse "say-hello" --brain-file /home/me/my_other_brain.yml
```

### --muted

Starts Kalliope in a muted state.

Example of use
```bash
kalliope start --muted
```

You can combine the options together like, for example:
```bash
kalliope start --muted --brain-file /home/me/my_other_brain.yml
```

### --debug

Show debug output in the console
Expand Down
82 changes: 82 additions & 0 deletions Docs/rest_api.md
View file
Expand Up @@ -308,6 +308,88 @@ Curl command:
curl -i --user admin:secret -X POST http://localhost:5000/synapses/start/audio -F "file=@path/to/file.wav" -F no_voice="true"
```

#### 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.
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.

Status can either by ```complete``` (nothing else to do) or ```waiting_for_answer```, in which case Kalliope is waiting for your response :).

In this case, you can launch another order containing your response.

Let's take as an example the simple [neurotransmitter brain of the EN starter kit](https://github.com/kalliope-project/kalliope_starter_en/blob/master/brains/neurotransmitter.yml):

First step is to fire the "ask me a question order":

```bash
curl -i --user admin:secret -H "Content-Type: application/json" -X POST -d '{"order":"ask me a question"}' http://localhost:5000/synapses/start/order
```

The response should be as follow:

```JSON
{
"matched_synapses": [
{
"matched_order": "ask me a question",
"neuron_module_list": [
{
"generated_message": "do you like french fries?",
"neuron_name": "Say"
}
],
"synapse_name": "synapse1"
}
],
"status": "waiting_for_answer",
"user_order": "ask me a question"
}
```

The ```"status": "waiting_for_answer"``` indicates that it waits for a response, so let's send it:

```bash
--user admin:secret -H "Content-Type: application/json" -X POST -d '{"order":"not at all"}' http://localhost:5000/synapses/start/order
```

```JSON
{
"matched_synapses": [
{
"matched_order": "ask me a question",
"neuron_module_list": [
{
"generated_message": "do you like french fries?",
"neuron_name": "Say"
},
{
"generated_message": null,
"neuron_name": "Neurotransmitter"
}
],
"synapse_name": "synapse1"
},
{
"matched_order": "not at all",
"neuron_module_list": [
{
"generated_message": "You don't like french fries.",
"neuron_name": "Say"
}
],
"synapse_name": "synapse3"
}
],
"status": "complete",
"user_order": null
}

```

And now the status is complete. This works also when you have nested neurotransmitter neurons, you just need to keep monitoring the status from the API answer.

### Get mute status

Normal response codes: 200
Expand Down
212 changes: 91 additions & 121 deletions Docs/settings.md
View file
Expand Up @@ -212,94 +212,118 @@ text_to_speech:

Some arguments are required, some other optional, please refer to the [TTS documentation](tts.md) to know available parameters for each supported TTS.

## Wake up answers configuration
## Hooks

### random_wake_up_answers
When Kalliope detects your trigger/hotword/magic word, it lets you know that it's operational and now waiting for order. It's done by answering randomly
one of the sentences provided in the variable random_wake_up_answers.
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.

This variable must contain a list of strings as shown bellow
To use a hook, attach the name of the hook to a synapse (or list of synapse) which exists in your brain.

Syntax:
```yml
random_wake_up_answers:
- "You sentence"
- "Another sentence"
hooks:
hook_name1: synapse_name
hook_name2:
- synapse_name_1
- synapse_name_2
```

E.g
E.g.
```yml
random_wake_up_answers:
- "Yes sir?"
- "I'm listening"
- "Sir?"
- "What can I do for you?"
- "Listening"
- "Yes?"
hooks:
on_start: "on-start-synapse"
```

### random_wake_up_sounds
You can play a sound when Kalliope detects the hotword/trigger instead of saying something from
the `random_wake_up_answers`.
Place here a list of full paths of the sound files you want to use. Otherwise, you can use some default sounds provided by Kalliope which you can find in `/usr/lib/kalliope/sounds`.
By default two file are provided: ding.wav and dong.wav. In all cases, the file must be in `.wav` or `.mp3` format. If more than on file is present in the list,
Kalliope will select one randomly at each wake up.
List of available hook

| Hook name | Description |
|------------------------|-----------------------------------------------------------------|
| on_start | When kalliope is started. This hook will only be triggered once |
| on_waiting_for_trigger | When Kalliope waits for the hotword detection |
| on_triggered | When the hotword has been detected |
| on_start_listening | When the Speech to Text engine is listening for an order |
| on_stop_listening | When the Speech to Text engine stop listening for an order |
| on_order_found | When the pronounced order has been found in the brain |
| on_order_not_found | When the pronounced order has not been found in the brain |
| on_mute | When Kalliope switches from non muted to muted |
| on_unmute | When Kalliope switches from muted to non muted |
| on_start_speaking | When Kalliope starts speaking via the text to speech engine |
| on_stop_speaking | When Kalliope stops speaking |

Example: You want to hear a random answer when the hotword has been triggered

**settings.yml**
```yml
random_wake_up_sounds:
- "local_file_in_sounds_folder.wav"
- "/my/personal/full/path/my_file.mp3"
hooks:
on_triggered: "on-triggered-synapse"
```

E.g
**brain.yml**
```yml
random_wake_up_sounds:
- "ding.wav"
- "dong.wav"
- "/my/personal/full/path/my_file.mp3"
- name: "on-triggered-synapse"
signals: []
neurons:
- say:
message:
- "yes sir?"
- "I'm listening"
- "I'm listening to you"
- "sir?"
- "what can i do for you?"
- "Speaking"
- "how can i help you?"
```

>**Note: ** If you want to use a wake up sound instead of a wake up answer you must comment out the `random_wake_up_answers` section.
E.g: `# random_wake_up_answers:`


## On ready notification
This section is used to notify the user when Kalliope is waiting for a trigger detection by playing a sound or speak a sentence out loud
Example: You want to know that your order has not been found

### play_on_ready_notification
This parameter define if you play the on ready notification:
- `always`: every time Kalliope is ready to be awaken
- `never`: never play a sound or sentences when kalliope is ready
- `once`: at the first start of Kalliope

E.g:
**settings.yml**
```yml
play_on_ready_notification: always
hooks:
on_order_not_found: "order-not-found-synapse"
```
### on_ready_answers
The on ready notification can be a sentence. Place here a sentence or a list of sentence. If you set a list, one sentence will be picked up randomly

E.g:
**brain.yml**
```yml
on_ready_answers:
- "I'm ready"
- "Waiting for order"
- name: "order-not-found-synapse"
signals: []
neurons:
- say:
message:
- "I haven't understood"
- "I don't know this order"
- "Please renew your order"
- "Would you please reword your order"
- "Can ou please reformulate your order"
- "I don't recognize that order"
```

### on_ready_sounds
You can play a sound instead of a sentence.
Remove the `on_ready_answers` parameters by commenting it out and use this one instead.
Place here the path of the sound file. Files must be .wav or .mp3 format.
Example: You are running Kalliope on a Rpi. You've made a script that turn on or off a led.
You can call this script every time kalliope start or stop speaking

E.g:
**settings.yml**
```yml
on_ready_sounds:
- "ding.wav"
- "dong.wav"
- "/my/personal/full/path/my_file.mp3"
hooks:
on_start_speaking: "turn-on-led"
on_stop_speaking: "turn-off-led"
```

>**Note: ** If you want to use a on ready sound instead of a on ready you must comment out the `random_on_ready_answers` section.
E.g: `# random_on_ready_answers:`
**brain.yml**
```yml
- name: "turn-on-led"
signals: []
neurons:
- script:
path: "/path/to/script.sh on"

- name: "turn-off-led"
signals: []
neurons:
- script:
path: "/path/to/script.sh off"
```

>**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

## Rest API

Expand Down Expand Up @@ -359,19 +383,6 @@ allowed_cors_origin:

Remember that an origin is composed of the scheme (http(s)), the port (eg: 80, 4200,…) and the domain (mydomain.com, localhost).

## Default synapse

Run a default [synapse](brain.md) when Kalliope can't find the order in any synapse or if the SST engine haven't understood the order.

```yml
default_synapse: "synapse-name"
```

E.g
```yml
default_synapse: "Default-response"
```

## Resources directory

The resources directory is the path where Kalliope will try to load community modules like Neurons, STTs or TTSs.
Expand Down Expand Up @@ -444,55 +455,14 @@ And a synapse that use this dict:
- "the number is {{ contacts[contact_to_search] }}"
```

## Raspberry LED and mute button
LEDs connected to GPIO port of your Raspberry can be used to know current status of Kalliope.
A button can also be added in order to pause the trigger process. Kalliope does not listen for the hotword anymore when pressed.

A Dictionary called `rpi` can be declared which contains pin number to use following the mapping bellow

| Value name | Description |
|-------------------|------------------------------------------------------------------------------------------------------------|
| pin_mute_button | Pin connected to a mute button. When pressed the trigger process of kalliope is paused |
| pin_led_started | Pin switched to "on" when Kalliope is running |
| pin_led_muted | Pin switched to "on" when the mute button is pressed |
| pin_led_talking | Pin switched to "on" when Kalliope is talking |
| pin_led_listening | Pin switched to "on" when Kalliope is readu to listen an order after a trigger detection ("Say something") |
## Start options
Options that can be defined when kalliope starts.

**Example config**
```yml
rpi:
pin_mute_button: 6
pin_led_started: 5
pin_led_muted: 17
pin_led_talking: 27
pin_led_listening: 22
Example config
```yaml
start_options:
muted: True
```

You can also define a couple led instead of all if you don't use them
```yml
rpi:
pin_mute_button: 6
pin_led_started: 5
# pin_led_muted: 17
# pin_led_talking: 27
# pin_led_listening: 22
```

**Example circuit**

You will be using one of the ‘ground’ (GND) pins to act like the ‘negative’ or 0 volt ends of a battery.
The ‘positive’ end of the battery will be provided by a GPIO pin.

<p align="center">
<img style="width: 200px;" src="../images/led_kalliope_circuit.png">
</p>


>**Note:** You must ALWAYS use resistors to connect LEDs up to the GPIO pins of the Raspberry Pi.
The Raspberry Pi can only supply a small current (about 60mA). T
he LEDs will want to draw more, and if allowed to they will burn out the Raspberry Pi.
Therefore putting the resistors in the circuit will ensure that only this small current will flow and the Pi will not be damaged.


## Next: configure the brain of Kalliope
Now your settings are ok, you can start creating the [brain](brain.md) of your assistant.
1 change: 1 addition & 0 deletions Docs/signals.md
View file
Expand Up @@ -27,3 +27,4 @@ Here is a list of core signal that are installed natively with Kalliope
| [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 |
| [geolocation](../kalliope/signals/geolocation) | Define synapses to be triggered by clients handling geolocation |

0 comments on commit b3f21be

Please sign in to comment.