SoftBank Robotics documentation What's new in NAOqi 2.8?

ALDialog API

NAOqi Interaction engines - Overview | API | Tutorials

Namespace : AL

#include <alproxies/aldialogproxy.h>

Method list

As any module, this module inherits methods from ALModule API. It also has the following specific methods:

class ALDialogProxy

Deprecated Methods

Methods

void ALDialogProxy::setLanguage(const std::string& language)

Sets the language of the dialog engine for the current application.

Warning

Must not be called at the same time as any other ALSpeechRecognition or ALDialog method.

On a real robot, this method sets also ALSpeechRecognition and ALTextToSpeech languages. On a simulated robot, it sets only ALTextToSpeech language, as ALSpeechRecognition does not exist on virtual robots.

The settings will come back to the preferred language after the application’s exit. For further details, see: nao Setting NAO’s preferred language, pepp Setting Pepper’s preferred language.

Parameters:
std::string ALDialogProxy::getLanguage()

Gets the language of the dialog engine.

Returns:a language name.

Example: “English”.

For the complete list of supported languages, see: nao Dialog - List of supported Languages, pepp Dialog - List of supported Languages.
std::string ALDialogProxy::loadTopic(const std::string& topicPath)

Loads the topic, exports and compiles the corresponding context files so that they are ready to be used by the speech recognition engine (ASR). The name of the topic (defined in the first line of the specified file) is returned by the function, so that it can be used elsewhere in the code.

Note that loading a topic file can be both CPU and time consuming and should not be done while the dialog engine is running. Also, all ALDialogProxy::loadTopic should be done before any ALDialogProxy::activateTopic.

Parameters:
  • topicFilePath – full path to the .top file to load (on the robot). On a real robot, this path can be also relative to the applications folder: /home/nao/.local/share/PackageManager/apps/
Returns:

Name of the loaded topic. Any syntax errors in the topic file are thrown as exceptions.

Warning

Topics can be used only after having activated all of them and subscribed to the dialog engine (see: ALDialogProxy::activateTopic and ALDialogProxy::subscribe).
Using a non-activated (only loaded) topic may have unexpected results.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u: (Hello Nao how are you today) Hello human, I am fine thank you and you?

aldialog_loadTopic.py

ALDialog.setLanguage("English")
topicName = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
print topicName
print ALDialog.getLoadedTopics("English")
ALDialog.unloadTopic(topicName)
print ALDialog.getLoadedTopics("English")

Execution:

$ python aldialog_loadTopic.py --ip $YOUR_ROBOTS_IP_ADDRESS
> mytopic
> ['mytopic']
> []

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

See also the example in ALDialogProxy::getLoadedTopics.

std::string ALDialogProxy::loadTopicContent(const std::string& topicContent)

Works exactly like ALDialogProxy::loadTopic, but instead of a topic’s path, its qichat code can be passed directly to the method.

Parameters:
  • topicContent – qichat code to load to the dialog engine. The string has to be formatted correctly (with end-of-line markers, see example).
Returns:

Name of the loaded topic. Any syntax errors in the topic file are thrown as exceptions.

aldialog_loadTopicContent.py

ALDialog.setLanguage("English")
topicContent = ("topic: ~mytopic()\n"
                "language: enu\n"
                "proposal: hello\n"
                "u:(hi) nice to meet you\n")
topicName = ALDialog.loadTopicContent(topicContent)
print topicName
print ALDialog.getLoadedTopics("English")
ALDialog.unloadTopic(topicName)
print ALDialog.getLoadedTopics("English")

Execution:

$ python aldialog_loadTopicContent.py --ip $YOUR_ROBOTS_IP_ADDRESS
> mytopic
> ['mytopic']
> []
void ALDialogProxy::unloadTopic(const std::string& topicName)

Unloads the specified topic and frees the associated memory.

Parameters:

Warning

The topic’s name passed as parameter to ALDialogProxy::unloadTopic is the short name returned previously by ALDialogProxy::loadTopic, whereas ALDialogProxy::loadTopic takes as argument the topic’s path.

Warning

If a topic’s name passed to the method is wrong, a runtime error will be raised.

Warning

Topics loaded via an include instruction cannot be unloaded.

Example Python scripts can be found in ALDialogProxy::loadTopic and ALDialogProxy::getLoadedTopics.

void ALDialogProxy::getLoadedTopics(const std::string& language)

Returns a list of currently loaded topics for a given language.

Parameters:

Example Python script: loading, unloading and getting loaded topics in different languages

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u: (Hello Nao how are you today) Hello human, I am fine thank you and you?

aldialog_test_topic_file_2.top

topic: ~mytopic_2()
language: enu
proposal: human, how was your day?

aldialog_test_topic_file_frf.top

topic: ~mytopic()
language: frf
u: ({est-ce que} tu parles français) oui, bien sûr!

aldialog_getLoadedTopics.py

topic_name_eng_1 = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
print "\nLoaded an English topic:"
print "French loaded topics:", ALDialog.getLoadedTopics("French")
print "English loaded topics:", ALDialog.getLoadedTopics("English")
print "All loaded topics:", ALDialog.getAllLoadedTopics()

topic_name_eng_2 = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file_2.top")
print "\nLoaded another English topic:"
print "English loaded topics:", ALDialog.getLoadedTopics("English")
print "All loaded topics:", ALDialog.getAllLoadedTopics()

topic_name_frf_1= ALDialog.loadTopic("/home/nao/aldialog_test_topic_file_frf.top")
print "\nLoaded a French topic:"
print "French loaded topics:", ALDialog.getLoadedTopics("French")
print "All loaded topics:", ALDialog.getAllLoadedTopics()

ALDialog.unloadTopic("mytopic")  # notice that this call unloads both the French anf English "mytopic"
print "\nUnloaded 'mytopic':"
print "French loaded topics:", ALDialog.getLoadedTopics("French")
print "English loaded topics:", ALDialog.getLoadedTopics("English")
print "All loaded topics:", ALDialog.getAllLoadedTopics()

ALDialog.unloadTopic("mytopic_2")
print "\nUnloaded 'mytopic_2':"
print "All loaded topics:", ALDialog.getAllLoadedTopics()

Execution:

$ python aldialog_getLoadedTopics.py --ip $YOUR_ROBOTS_IP_ADDRESS
> Loaded an English topic:
> French loaded topics: []
> English loaded topics: ['mytopic']
> All loaded topics: ['mytopic']
>
> Loaded another English topic:
> English loaded topics: ['mytopic', 'mytopic_2']
> All loaded topics: ['mytopic', 'mytopic_2']
>
> Loaded a French topic:
> French loaded topics: ['mytopic']
> All loaded topics: ['mytopic', 'mytopic', 'mytopic_2']
>
> Unloaded 'mytopic':
> French loaded topics: []
> English loaded topics: ['mytopic_2']
> All loaded topics: ['mytopic_2']
>
> Unloaded 'mytopic_2':
> All loaded topics: []

Note

in the script, we assume that you put the .top files in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

std::vector<std::string> ALDialogProxy::getAllLoadedTopics()
Gets the list of all topics loaded to the dialog engine, regardless of their language.
An example Python script can be found in ALDialogProxy::getLoadedTopics.
void ALDialogProxy::activateTopic(const std::string& topicName)

Adds the specified topic to the list of the topics that are currently used by the dialog engine to parse the human’s inputs. Several topics can be active at the same time but only one will be used to generate proposals (this specific topic is said to have the focus).

Parameters:

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u: (Hello Nao how are you today) Hello human, I am fine thank you and you?

aldialog_activateTopic.py

ALDialog.setLanguage("English")
topicName = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
print topicName
ALDialog.activateTopic(topicName)
print ALDialog.getActivatedTopics()
ALDialog.deactivateTopic(topicName)
print ALDialog.getActivatedTopics()
ALDialog.unloadTopic(topicName)

Execution:

$ python aldialog_activateTopic.py --ip $YOUR_ROBOTS_IP_ADDRESS
> mytopic
> ['mytopic']
> []

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::deactivateTopic(const std::string& topicName)

Removes the specified topic from list of the topics that are currently used by the dialog engine to parse the human’s inputs. Several topics can be active at the same time but only one will be used to generate proposals (this specific topic is said to have the focus).

Parameters:

An example Python script can be found here ALDialogProxy::activateTopic.

std::vector<std::string> ALDialogProxy::getActivatedTopics()
Gets the list of activated topics in the current language.
An example Python script can be found here ALDialogProxy::activateTopic.
void ALDialogProxy::subscribe(const std::string& subscriberName)
Starts the dialog engine. Starts the speech recognition on robot.
Please note that it should be executed after all the ALDialogProxy::loadTopic and ALDialogProxy::activateTopic.
The dialog engine will stop when all subscribers will have unsubscribed.

Parameters:
  • subscriberName – a unique string to identify yourself.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u: (Hello Nao how are you today) Hello human, I am fine thank you and you?

aldialog_subscribe.py

ALDialog.setLanguage("English")
topicName = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topicName)
ALDialog.subscribe("my_subscribe_test")
try:
    raw_input("speak to the robot now, press Enter when finished")
finally:
    ALDialog.unsubscribe("my_subscribe_test")
    ALDialog.deactivateTopic(topicName)
    ALDialog.unloadTopic(topicName)'

Execution:

$ python aldialog_subscribe.py --ip $YOUR_ROBOTS_IP_ADDRESS
# say "Hello Nao how are you today" and check the robot's response

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::unsubscribe(const std::string& subscriberName)

Stops the dialog engine and the speech recognition on the robot if nobody else is subscribed to ALDialog.

Parameters:

An example Python script can be found here ALDialogProxy::subscribe.

std::vector<std::string> ALDialogProxy::runTopics(std::vector<std::string> topicsPathName)

Calls ALDialogProxy::loadTopic, ALDialogProxy::activateTopic and ALDialogProxy::subscribe for the topics given in parameter, then starts the speech recognition on the robot.

Caution: do not call ALDialogProxy::runTopics when:

Parameters:
  • topicsPathName – a list of full paths to the topics you want to run.
Returns:

a list of short names of the run topics.
void ALDialogProxy::stopTopics(std::vector<std::string> topicsName)

Deactivates and unloads topics previously run with ALDialogProxy::runTopics, then stops the speech recognition.

Parameters:
  • topicsName – a list with the names of topics to stop.
void ALDialogProxy::say(std::string topicPathAndName, std::string tagName)

Says a tagged sentence from a topic. Does not affect neither the currently activated topic(s) (even if it is the same topic) nor the speech recognition.

Parameters:
  • topicPathAndName – path to the topic, can be either absolute or relative to the application path (/home/nao/.local/share/PackageManager/apps/).
  • tagName – tag identifying the sentence.
void ALDialogProxy::setFocus(const std::string& topicName)

If multiple topics can be active at the same time, only one of them is used to generate proposals. This topic is said to have the focus. A call to this function forces the focus to the specified topic. After this call, proposals will be generated from this topic and human inputs will be first parsed through this topic. However, if a rule from a different active topic is matched, the focus will change automatically to that topic.

Parameters:
  • topicName – the topic’s name returned previously by ALDialogProxy::loadTopic (also included in the first line of the .top file).

Warning

Make sure you have activated the topic prior to calling ALDialogProxy::gotoTopic, ALDialogProxy::setFocus or any other method. Using a non-activated topic may have unexpected results.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
proposal: human, how are you ?
proposal: %dynamicTest What do you want to do ?

aldialog_test_topic_file_2.top

topic: ~mytopic_2()
language: enu
proposal: human, how was your day?
proposal: Do you like robots?

aldialog_setFocus.py

ALDialog.setLanguage("English")
topic_name = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
topic_name_2 = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file_2.top")
ALDialog.activateTopic(topic_name)
ALDialog.activateTopic(topic_name_2)
ALDialog.subscribe("my_setFocus_test")

ALDialog.setFocus("mytopic")
ALDialog.forceOutput()
ALDialog.forceOutput()
ALDialog.forceOutput()  # nothing more to say from "mytopic"
ALDialog.setFocus("mytopic_2")
ALDialog.forceOutput()
ALDialog.forceOutput()
ALDialog.forceOutput()  # nothing more to say from "mytopic_2"

ALDialog.unsubscribe("my_setFocus_test")
ALDialog.deactivateTopic(topic_name)
ALDialog.deactivateTopic(topic_name_2)
ALDialog.unloadTopic(topic_name)
ALDialog.unloadTopic(topic_name_2)

Execution – robot’s responses

$ python aldialog_setFocus.py --ip $YOUR_ROBOTS_IP_ADDRESS
# the robot will say:
# 1) "Human, how are you?"
# 2) "What do you want to do?"
# 3) [no more proposals will be found in the first topic]
# 4) "Human, how was your day?"
# 5) "Do you like robots?"
# 6) [no more proposals will be found in the second topic]

Note

in the script, we assume that you put both the .top files in the home folder on the robot (/home/nao). You can, of course, put them elsewhere and modify the script.

std::string ALDialogProxy::getFocus()

Returns the name of the currently focused topic. To focus a topic, you need to match a rule of that topic. You can also force the focus with ALDialogProxy::setFocus. The currently focused topic is also used to make proposals.

Returns:the currently focused topic’s name.
std::string ALDialogProxy::addFallback(const std::string& language, const std::string serviceName)

Defines a callback service to be called when the robot doesn’t understand.

The registered service must define a method string findOutput(string language, string input), where Language is the language input (Ex: “English”) and Input is the human sentence.

Sample: Open fallback.crg in Choregraphe and install it on the robot. As fallback of all dialogs, robot will repeat what human said. finOutput must return the robot answer or an empty string for no answer.
std::string ALDialogProxy::removeFallback(const std::string& language, const std::string serviceName)

Removes a fallback callback previously added with ALDialogProxy::addFallback.

void ALDialogProxy::activateTag(const std::string& tagName, const std::string& topicName)

Activates the given tag in the specified topic.

Parameters:
  • tagName – name of the tag to activate.
  • topicName – name of the topic that contains the tag.
Note:

if you load and activate your own topic, all tags inside it are active by default.

See also: ALDialogProxy::deactivateTag.

void ALDialogProxy::deactivateTag(const std::string& tagName, const std::string& topicName)
Deactivates a tag in the specified topic.
In qichat, tags can be used in inputs (human’s utterances) as well as in outputs (robot’s responses).
Any rule (the “u:” input) tagged with the deactivated tag will not be matched anymore (the qichat event Dialog/NotUnderstood() will be caught).
Any output tagged with the deactivated tag will not be said by the robot (but the rule will still match, so there will just be no answer; the qichat event Dialog/SpeakFailure() will be caught).
If a qichat input or output has more than one associated tag, all its tags have to be active for it to be active (it works as the logical AND).
Parameters:
  • tagName – name of the tag to deactivate.
  • topicName – name of the topic that contains the tag.
Note:

if you load and activate your own topic, all tags inside it are active by default.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u:(single-tagged rule %mytag_0) single-tagged rule test answer
u:(single-tagged output) %mytag_1 single-tagged output test answer
u:(double-tagged rule %mytag_2 %mytag_3) double-tagged rule test answer
u:(double-tagged output) %mytag_4 %mytag_5 double-tagged output test answer
u:(e:Dialog/SpeakFailure) I have matched a rule with an empty answer!
u:(e:Dialog/NotUnderstood) I haven't matched any rule!

aldialog_deactivateTag.py

ALDialog.setLanguage("English")
topic_name = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topic_name)
ALDialog.subscribe("my_deactivateTag_test")

tags = ["mytag_{}".format(i) for i in range (6)]  # mytag_0, mytag_1, (...), until mytag_5

# below, activating all tags in case of a previous deactivation, normally active by default
for tag in tags:
   ALDialog.activateTag(tag, "mytopic")  # you can use the "topic_name" variable here as well

# playing each case with activated and then deactivated tag
ALDialog.forceInput("single-tagged rule")  # standard response (mytag_0 active)
ALDialog.deactivateTag("mytag_0", "mytopic")
ALDialog.forceInput("single-tagged rule")  # "Dialog/NotUnderstood" is caught (mytag_0 blocked, rule not matched)

ALDialog.forceInput("single-tagged output")  # standard response (mytag_1 active)
ALDialog.deactivateTag("mytag_1", "mytopic")
ALDialog.forceInput("single-tagged output")  # no response to this (mytag_1 blocked)

ALDialog.forceInput("double-tagged rule")  # standard response (mytag_2 and mytag_3 active)
ALDialog.deactivateTag("mytag_3", "mytopic")
ALDialog.forceInput("double-tagged rule")  # "Dialog/NotUnderstood" is caught (mytag_2 active BUT mytag_3 blocked, rule not matched)

ALDialog.forceInput("double-tagged output")  # standard response (mytag_4 and mytag_5 active)
ALDialog.deactivateTag("mytag_5", "mytopic")
ALDialog.forceInput("double-tagged output")  # no response to this (mytag_4 active BUT mytag_5 blocked)

ALDialog.unsubscribe("my_deactivateTag_test")
ALDialog.deactivateTopic(topic_name)
ALDialog.unloadTopic(topic_name)

Execution - robot’s responses

$ python aldialog_deactivateTag.py --ip $YOUR_ROBOTS_IP_ADDRESS
# the robot will say:
# 1) single-tagged rule test answer
# 2) I haven't matched any rule!
# 3) single-tagged output test answer
# 4) I have matched a rule with an empty answer!
# 5) double-tagged rule test answer
# 6) I haven't matched any rule!
# 7) double-tagged output test answer
# 8) I have matched a rule with an empty answer!

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::gotoTag(const std::string tagName, const std::string& topicName)
Sets the focus to the given topic then says the sentence that contains tagName of the topic (if any).
Parameters:
  • tagName – Name of the tag in a sentence.
  • topicName – Name of the topic that will get the focus.

Warning

Make sure you have activated the topic prior to calling ALDialogProxy::gotoTopic, ALDialogProxy::setFocus or any other method. Using a non-activated topic may have unexpected results.

aldialog_gotoTag.py

ALDialog.setLanguage("English")
topicContent = ("topic: ~mytopic()\n"
                "language: enu\n"
                "proposal: %myTag hello\n")
topicName = ALDialog.loadTopicContent(topicContent)
ALDialog.activateTopic(topicName)
ALDialog.subscribe("my_gotoTopic_test")
ALDialog.gotoTag("myTag", "mytopic")  # "mytopic" is the value of topicName
ALDialog.unsubscribe("my_gotoTopic_test")
ALDialog.deactivateTopic(topicName)
ALDialog.unloadTopic(topicName)

Execution – robot’s responses

$ python aldialog_gotoTopic.py --ip $YOUR_ROBOTS_IP_ADDRESS
# the robot will say:
# "hello"
void ALDialogProxy::gotoTopic(const std::string& topicName)

Sets the focus to the given topic then says the first activated proposal of the topic (if any).

Parameters:
  • topicName – Name of the topic that will get the focus.

Warning

Make sure you have activated the topic prior to calling ALDialogProxy::gotoTopic, ALDialogProxy::setFocus or any other method. Using a non-activated topic may have unexpected results.

aldialog_gotoTopic.py

ALDialog.setLanguage("English")
topicContent = ("topic: ~mytopic()\n"
                "language: enu\n"
                "proposal: hello\n"
                "u1:(hi) nice to meet you\n")
topicName = ALDialog.loadTopicContent(topicContent)
ALDialog.activateTopic(topicName)
ALDialog.subscribe("my_gotoTopic_test")
ALDialog.gotoTopic("mytopic")  # "mytopic" is the value of topicName
ALDialog.forceInput("hi")
ALDialog.unsubscribe("my_gotoTopic_test")
ALDialog.deactivateTopic(topicName)
ALDialog.unloadTopic(topicName)

Execution – robot’s responses

$ python aldialog_gotoTopic.py --ip $YOUR_ROBOTS_IP_ADDRESS
# the robot will say:
# 1) "hello"
# 2) "nice to meet you"
void ALDialogProxy::setConcept(const std::string& conceptName, const std::string& language, const std::vector<std::string>& content)

Sets the specified dynamic concept of the specified language with the given word list.

Warning

The speech recognition must be already running (the robot must be listening). Otherwise the speech recognition will not be updated with the concept’s content.

So, make sure the Dialog engine is started by using the event Dialog/IsStarted().

Warning

ALDialogProxy::setConcept can be called only for a dynamic concept, declared in qichat with the keyword dynamic. Static concepts (declared in qichat with concept) are constant and cannot be modified with the ALDialog API.

Warning

Calling ALDialogProxy::setConcept on an existing and non-empty concept overwrites its content.

Parameters:
  • conceptName – Name of the concept to set.
  • language – language of the concept or its qichat code. Examples: “jpj”, “enu”, “English”, “Japanese”. For the complete list of supported languages, see: nao Dialog - List of supported Languages or pepp Dialog - List of supported Languages.
  • content – a list of words or expressions to be included in the concept.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
dynamic: things_you_can_ride
u:(I want to ride a _~things_you_can_ride) Of course you can ride a $1 ! I'm going with you !

aldialog_setConcept.py

ALDialog.setLanguage("English")
topicName = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topicName)
ALDialog.subscribe("my_setConcept_test")
ALDialog.setConcept("things_you_can_ride", "English", ["bike", "dragon", "unicorn", "double-decker bus"])
try:
    ALDialog.forceInput("I want to ride a double-decker bus")
    ALDialog.forceInput("I want to ride a dragon")
finally:
    ALDialog.unsubscribe("my_setConcept_test")
    ALDialog.clearConcepts()
    ALDialog.deactivateTopic(topicName)
    ALDialog.unloadTopic(topicName)

Execution – robot’s responses

$ python aldialog_setConcept.py --ip $YOUR_ROBOTS_IP_ADDRESS
# the robot will say:
# 1) "Of course you can ride a double-decker bus ! I'm going with you !"
# 2) "Of course you can ride a dragon ! I'm going with you !"

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::addToConcept(const std::string& conceptName, const std::string& language, const std::vector<std::string>& content)

Allows to add more words / sentences to an existing, non-empty dynamic concept, without overwriting it.

Warning

ALDialogProxy::addToConcept can be called only for a dynamic concept, declared in qichat with the keyword dynamic. Static concepts (declared in qichat with concept) are constant and cannot be modified with the ALDialog API.

Parameters:
  • conceptName – name of the concept to modify.
  • language – language of the concept or its qichat code. Examples: “jpj”, “enu”, “English”, “Japanese”. For the complete list of supported languages, see: nao Dialog - List of supported Languages or pepp Dialog - List of supported Languages.
  • content – a list of words / expressions to be added to the concept.
Note:

calling ALDialogProxy::addToConcept on an empty dynamic concept has exactly the same effect as ALDialogProxy::setConcept.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
dynamic: things_you_can_ride
u:(I want to ride a _~things_you_can_ride) Of course you can ride a $1 ! I'm going with you !

aldialog_addToConcept.py

ALDialog.setLanguage("English")
topicName = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topicName)
ALDialog.subscribe("my_addToConcept_test")
ALDialog.clearConcepts()

ALDialog.setConcept("things_you_can_ride", "English", ["bike", "dragon", "unicorn", "double-decker bus"])
print ALDialog.getConcept("things_you_can_ride", "English")
ALDialog.addToConcept("things_you_can_ride", "English", ["horse", "motorcycle", "just anything"])
print ALDialog.getConcept("things_you_can_ride", "English")

ALDialog.unsubscribe("my_addToConcept_test")
ALDialog.clearConcepts()
ALDialog.deactivateTopic(topicName)
ALDialog.unloadTopic(topicName)

Execution:

$ python aldialog_addToConcept.py --ip $YOUR_ROBOTS_IP_ADDRESS
> ['bike', 'dragon', 'unicorn', 'double-decker bus']
> ['horse', 'motorcycle', 'just anything', 'bike', 'dragon', 'unicorn', 'double-decker bus']

See also the example in ALDialogProxy::setConcept.

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

std::vector<std::string> ALDialogProxy::getConcept(const std::string& conceptName, const std::string& language)

Retrieves the content of an existing dynamic concept, set previously with ALDialogProxy::setConcept or ALDialogProxy::addToConcept.

Parameters:

Warning

ALDialogProxy::getConcept works only for a dynamic concepts, declared in qichat with the keyword dynamic. Static concepts (declared in qichat with concept) cannot be read with the ALDialog API.

An example Python script can be found here ALDialogProxy::addToConcept.

void ALDialogProxy::clearConcepts()

Clears the contents of all existing dynamic concepts. Does not modify static concepts.

An example Python script can be found here ALDialogProxy::addToConcept.

void ALDialogProxy::setConfidenceThreshold(const std::string& grammar, const float& threshold)

For the given grammar, sets the minimum confidence level of a speech recognition result. Below this threshold value, the dialog engine ignores results returned by the ASR (as if the robot did not hear anything).

Parameters:
  • grammar – name of the grammar for which we set the threshold: BNF, SLM or REMOTE.
  • threshold – desired threshold value: [0, 1] (be default around 0.5).
void ALDialogProxy::setConfidenceThreshold(const std::string& grammar, const float& threshold, const std::string& language)

For the given grammar and language, sets the minimum confidence level of a speech recognition result. Below this threshold value, the dialog engine ignores the result (as if the robot did not hear anything).

Parameters:
float ALDialogProxy::getConfidenceThreshold(const std::string& grammar, const std::string& language)

For the given grammar and language, gets the minimum confidence level of a speech recognition result. Below this threshold value, the dialog engine ignores the result (as if the robot did not hear anything).

Parameters:
Returns:

threshold value for the given grammar and language; the default value depends on the robot’s configuration, in most cases it’s around 0.5.
Note:

To set all the thresholds to default, call ALDialogProxy::removeAllLanguageThresholds
std::map<std::string, std::map<std::string, float>> ALDialogProxy::getAllConfidenceThresholds()

For all the 3 grammars (BNF, SLM, REMOTE) returns the ASR threshold’s value for each language. Speech recognition results whose confidence is below this threshold are ignored by the dialog engine.

Note

The default thresholds can be different on your robot. They may depend on your robot’s version.

void ALDialogProxy::removeAllLanguageThresholds()

Resets all speech recognition confidence thresholds to default.

void ALDialogProxy::setAnimatedSpeechConfiguration(const AL::ALValue& animatedSpeechConfiguration)

Sets the animated speech (speaking movement) configuration used by the dialog. It can be different from the general one, defined with the ALSpeakingMovement API.

Parameters:
  • animatedSpeechConfiguration – the animated speech configuration to be used by the dialog. It follows the same format than the one used by ALAnimatedSpeechProxy::say with local configuration. Currently the only valid parameter is bodyLanguageMode.

Note

In order to reset the configuration to default (so that the dialog uses the general ALSpeakingMovement configuration), pass an empty vector (list in Python) to the method.

AL::ALValue ALDialogProxy::getAnimatedSpeechConfiguration()

Gets the current animated speech (speaking movement) configuration used by the dialog.

Returns:an AL::ALValue (in C++) / a list of two-element lists (in Python) with the current values of animated speech parameters.

Warning

If the returned value does not follow the format specified in ALAnimatedSpeechProxy::say, it is not taken into account by the dialog – the robot will continue using the default speaking movement configuration. In order to check the default speaking movement configuration, call ALSpeakingMovementProxy::getMode and ALSpeakingMovementProxy::isEnabled.

void ALDialogProxy::forceOutput()

Forces the robot to say a proposal, if any is available. A proposal will be said either from the currently focused topic or last focused topic (in case if no topics are focused).

void ALDialogProxy::forceInput(const std::string& input)

Stimulates the dialog engine with the given input as if this input had been given by the speech recognition engine.

Warning

The Dialog Engine responds to a forceInput even in the absence of a ALDialogProxy::subscribe or a ALDialogProxy::runDialog.

Parameters:
  • input – human input to match
std::vector<std::string> ALDialogProxy::getUserList()

Gets the list of user IDs if you have added at least one data for this user with $user/variable=value. User ID are given by ALDialogProxy::openSession called by ALAutonomousLife.

Returns:List of user IDs (int).
void ALDialogProxy::openSession(int id)

Opens a new dialog session. A call to this function restores the dialog user variables to ALMemory from the dialog database.

Parameters:
  • id – ID of the user.
void ALDialogProxy::closeSession()

Closes the current dialog session and stores all the related ALMemory variables in the database dedicated to ALDialog.

void ALDialogProxy::runDialog()

Retrieves all topics marked as collaborative dialog in application manifest. Loads, compiles and activates these topics. Application triggers are automatically added in speech recognition if application dialog_applauncher is installed on robot. dialog_applauncher is a basic channel application.

void ALDialogProxy::stopDialog()

If runDialog was started, stops all topics marked as collaborative dialog in application manifest.

void ALDialogProxy::insertUserData(const std::string& variableName, const std::string& variableValue, const int& userID)

Inserts directly a variable in user dialog database.

Parameters:
  • variableName – Variable name.
  • variableValue – Variable value.
  • userID – User ID.
void ALDialogProxy::getUserData(const std::string& variableName, const int& userID)

Gets a variable value from user dialog database.

Parameters:
  • variableName – Variable name.
  • userID – User ID.
Returns:

Variable value (string).
void ALDialogProxy::getUserDataList(const int& userID)

Gets all variable list of a user.

Parameters:
  • userID – User ID.
Returns:

Variable name list.
void ALDialogProxy::compileAll()

Can be optionally called after a series of loadTopic in order to build dialog model and speech recognition model. If not called the compilation occurs once at runtime.

void ALDialogProxy::setDelay(const std::string& eventName, int validity)

This method is related to the qichat event detection feature (see also other related methods: ALDialogProxy::addBlockingEvent and ALDialogProxy::removeBlockingEvent). If an event is not blocking (that is, does not interrupt the robot’s speach immediately), it has a limited validity, by default: 2 seconds. If the robot is currently saying a very long sentence, the event (ex. touching the robot’s head) will time out, the robot will not react.

Parameters:
  • eventName – name of the event whose validity you want to change.
  • validity – validity (time out) in milliseconds (5000 = 5 seconds). Set to -1 for infinite validity.
Note:

after a naoqi restart, the default value will be restored (2000 = 2 seconds).

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u:([e:FrontTactilTouched e:MiddleTactilTouched e:RearTactilTouched]) You touched my head!
u:(start counting) 0, 1, 2, 3, 4, 5.

aldialog_setDelay.py

ALDialog.setLanguage("English")
topic_name = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topic_name)
ALDialog.subscribe("my_setDelay_test")

raw_input("\nThe robot is going to start counting from 0 to 5. "
          "Try touching its head's tactile sensors while it's speaking. "
          "The timeout is set to default (2 seconds). Press Enter to start:")
ALDialog.forceInput("start counting")

raw_input("\nThe robot is going to start counting from 0 to 5. "
          "Try touching its head's tactile sensors while it's speaking. "
          "The timeout is set to infinite now. Even if you touch the head when the "
          "robot only starts counting, it will still react after having stopped speaking. Press Enter to start:")
ALDialog.setDelay("MiddleTactilTouched", -1)
ALDialog.setDelay("FrontTactilTouched", -1)
ALDialog.setDelay("RearTactilTouched", -1)
ALDialog.forceInput("start counting")

raw_input("\nThe robot is going to start counting from 0 to 5. "
          "Try touching its head's tactile sensors while it's speaking. "
          "The timeout is set back to default (2 seconds). Press Enter to start:")
ALDialog.setDelay("MiddleTactilTouched", 2000)
ALDialog.setDelay("FrontTactilTouched", 2000)
ALDialog.setDelay("RearTactilTouched", 2000)
ALDialog.forceInput("start counting")

ALDialog.unsubscribe("my_setDelay_test")
ALDialog.deactivateTopic(topic_name)
ALDialog.unloadTopic(topic_name)

Execution:

$ python aldialog_setDelay.py --ip $YOUR_ROBOTS_IP_ADDRESS
# follow the instructions displayed on the screen

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::addBlockingEvent(const std::string& eventName)

Qichat has an event detection feature – for example touching the robot’s head can provoke a verbal reaction. With this method you can declare an event as blocking, so that it will interrupt the robot’s speech and the robot will react immediately. By default, the dialog engine waits until the speech is finished and then makes the robot react to the event. In order to restore the default behavior, use the ALDialogProxy::removeBlockingEvent method (or restart naoqi).

Parameters:
  • eventName – name of the event that you want to make blocking.

Example Python script & dialog topic:

aldialog_test_topic_file.top

topic: ~mytopic()
language: enu
u:([e:FrontTactilTouched e:MiddleTactilTouched e:RearTactilTouched]) You touched my head!
u:(start counting) 0, 1, 2, 3, 4, 5.

aldialog_addBlockingEvent.py

ALDialog.setLanguage("English")
topic_name = ALDialog.loadTopic("/home/nao/aldialog_test_topic_file.top")
ALDialog.activateTopic(topic_name)
ALDialog.subscribe("my_deactivateTag_test")

raw_input("\nThe robot is going to start counting from 0 to 5 now. "
          "Try touching its head's tactile sensors while it's speaking. "
          "It will not interrupt its speech. Press Enter to start:")
ALDialog.forceInput("start counting")

raw_input("\nThe robot is going to start counting from 0 to 5 now. "
          "Try touching its head's tactile sensors while it's speaking. "
          "Touching the head is now declared as a blocking event, the "
          "robot will react to your touch immediately. Press Enter to start:")
ALDialog.addBlockingEvent("MiddleTactilTouched")
ALDialog.addBlockingEvent("FrontTactilTouched")
ALDialog.addBlockingEvent("RearTactilTouched")
ALDialog.forceInput("start counting")

raw_input("\nThe robot is going to start counting from 0 to 5 now. "
          "Try touching its head's tactile sensors while it's speaking. "
          "The default behavior is restored now, the robot won't interrupt its speech.")
ALDialog.removeBlockingEvent("MiddleTactilTouched")
ALDialog.removeBlockingEvent("FrontTactilTouched")
ALDialog.removeBlockingEvent("RearTactilTouched")
ALDialog.forceInput("start counting")

ALDialog.unsubscribe("my_deactivateTag_test")
ALDialog.deactivateTopic(topic_name)
ALDialog.unloadTopic(topic_name)

Execution:

$ python aldialog_addBlockingEvent.py --ip $YOUR_ROBOTS_IP_ADDRESS
# follow the instructions displayed on the screen

Note

in the script, we assume that you put the aldialog_test_topic_file.top file in the home folder on the robot (/home/nao). You can, of course, put it elsewhere and modify the script.

void ALDialogProxy::removeBlockingEvent(const std::string& eventName)

This method reverts the functionality previously enabled with ALDialogProxy::addBlockingEvent. The given event will no longer immediately interrupt the robot’s speech.

Parameters:
  • eventName – name of the event that you want not to be blocking anymore.

An example Python script can be found in ALDialogProxy::addBlockingEvent.

void ALDialogProxy::startPush()

Makes the dialog engine start making proposals automatically. After an answer, the dialog engine will automatically say a proposal from the available topics (the proposal will be included in the answer). Dialog engine will first try to say a proposal from the topic having the focus (see: ALDialogProxy::setFocus), then from other topics.

void ALDialogProxy::stopPush()

Makes the dialog engine stop making proposals automatically.

void ALDialogProxy::resetAll()

Resets the status of all topics: all proposals can be used again. Scopes (u1 rules) are closed.

void ALDialogProxy::resetLanguage()

Sets the language of the dialog engine to the preferred language of the robot.

For further details, see:

nao Setting NAO’s preferred language pepp Setting Pepper’s preferred language.

void ALDialogProxy::generateSentences(const std::string& destination, const std::string& topic, const std::string& language)

Generates all possible input sentences to a text file.

Parameters:
std::vector<std::string> ALDialogProxy::setVariablePath(const std::string& topicName, const std::string& eventName, const std::string& path)

Changes event name at runtime.

Parameters:
  • topicName – Topic that contains the event.
  • eventName – Original event name.
  • path – New event name.

Deprecated methods

void ALDialogProxy::setASRConfidenceThreshold(const float& threshold)

Deprecated since version 2.4: use ALDialogProxy::setConfidenceThreshold instead.

float ALDialogProxy::getASRConfidenceThreshold()

Deprecated since version 2.4: use ALDialogProxy::getConfidenceThreshold and ALDialogProxy::getAllConfidenceThresholds instead.

Events

Event: "Dialog/Answered"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised each time the robot answers. Contains the last answer. Subscribing to this event starts ALDialog.

Example

u:(what did you say before) I said $Dialog/Answered
Event: "Dialog/LastInput"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised each time the robot catches a human input. Contains the last human input.

Example

u:(hello) $Dialog/LastInput
Event: "Dialog/LastAnswer"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Contains the last robot’s answer that is not coming from a rule u:(e:NotUnderstood)

Event: "Dialog/SaidMisunderstood"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the robot didn’t understand. Equivalent to Dialog/NotUnderstood().

Event: "Dialog/NotUnderstoodEvent"
callback(std::string eventName, std::string subscriberIdentifier)

Raised when the robot didn’t understand and there is a e:Dialog/NotUnderstood matched in the topic.

Event: "Dialog/Tag"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the robot says a sentence with a tag inside. The event’s value is the tag’s name.

Event: "Dialog/Focus"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the dialog engine changes the currently focused topic. The new focused topic’s name is in the event’s value.

Event: "Dialog/FocusDescription"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the dialog engine changes the currently focused topic. The event’s value is the topic’s description. The value is empty if the topic does not have any description.

Event: "Dialog/ActivateTopic"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the dialog engine activates a topic. The topic’s name is the event’s value.

Event: "Dialog/DeactivateTopic"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the dialog engine deactivates a topic. The topic’s name is the event’s value.

Event: "Dialog/OpenSession"
callback(std::string eventName, int id, std::string subscriberIdentifier)

Raised when the dialog engine has finished opening a session. Value is the session ID.

Event: "Dialog/IsStarted"
callback(std::string eventName, int state, std::string subscriberIdentifier)

Raised when the dialog engine starts or stops. The value is “1” for start, “0” for stop.

Event: "Dialog/MainDialogStarted"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Raised when the collaborative dialog starts or stops.

  • The value is 1 when the collaborative dialog is started.
  • The value is 0 when the collaborative dialog is stopped or dialog reflex is stopped.
Event: "Dialog/NothingToSay"
callback(std::string eventName, std::string subscriberIdentifier)

Raised when ^gotoRandom didn’t find any proposal to say.

Event: "Dialog/CannotMakeIt"
callback(std::string eventName, std::string behaviorName, std::string subscriberIdentifier)

Internal event. Do not use.

Event: "Dialog/Language/English"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Value = 1 if the given language (here it’s English) is installed. The variable is not created if the language is not installed.

Event: "Dialog/Language/French"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Value = 1 if the given language (here it’s French) is installed. The variable is not created if the language is not installed.

Event: "Dialog/Scope"
callback(std::string eventName, int state, std::string subscriberIdentifier)
  • Raised with value 1 when a u1, u2, u3... scope are opened.
  • Raised with value 0 when a u1, u2, u3... scope are closed.

Data

Event: "Dialog/MatchedApp"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

When Dialog/LastAnswer is raised, Dialog/MatchedApp contains the application that matched.

Event: "Dialog/MatchedInput"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

When Dialog/LastAnswer is raised, Dialog/MatchedInput contains the current human input in the rule that matched.

Event: "Dialog/MatchedTopic"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

When Dialog/LastAnswer is raised, Dialog/MatchedTopic contains the topic that matched.

Event: "Dialog/RobotModel"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Data that contains “juliette” on Pepper robot and “nao” on nao robot.

Event: "Dialog/RobotName"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Data that contains “pepper” or “nao” depending robot model.

Event: "Dialog/MatchedLine"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

When Dialog/LastAnswer is raised, Dialog/MatchedLine contains the line in the topic that matched.

Event: "Dialog/TalkTime"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Current talk time in seconds since last ALDialog::openSession and last human sentence. Dialog/TalkTime is not updated on forceInput API call.

Event: "Dialog/DateCode"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Concatenation: month number + day number. Ex: 1225 for Christmas.

Event: "Dialog/Default"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Value = 1 if the current time is between 11 AM and 7 PM.

Event: "Dialog/Morning"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Value = 1 if the current time is between 5 AM and 11 AM.

Event: "Dialog/Night"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Value = 1 if current time is between 7 PM and 5 AM.

Event: "Dialog/Year"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Current year (format: YYYY).

Event: "Dialog/Hour"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Current hour (in 24-hour format).

Event: "Dialog/Minute"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Current minute.

Event: "Dialog/Second"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Current second.

Event: "Dialog/CurrentString"
callback(std::string eventName, std::string value, std::string subscriberIdentifier)

Currently processed human input.