DDE Tutorial

Template: Hello World

After you read the explanation for this DDE sample project Hello World, you will know:

What is a cross intent
How to trigger your app
What is an app specific concept
What is a system concept
How to reference a concept of an intent
What are the three conditions to control a triggered plan
What is the required belief
What is input context
How to test a project on DDE

Part 1: Import Sample Project : Hello World

In the DDE editor, you can easily import the Hello World Sample Project by clicking project -> project center ->“Import Template Project: Hello World”

Fig. 1. This figure shows the button to import the sample project.

Fig. 2. The figure shows the result after importing the sample project.

Part 2: Fill your app’s package name, activity name, and get your app key ID in the Console of the Developer Site.

Before you start using the DDE Editor, you should register the info of your app (such as 1. Package Name 2. App Name 3. Activity Name, etc.,) in the App Key Management page by clicking Console in the upper right corner(see figure 3), and after completing some more operations illustrated below, you will be assigned an app key ID for this app (with the corresponding package name, activity name, app name, etc.).

Fig. 3. The figure shows where the Console button is.

After getting in the console page (if you have not logged-in, the website will ask you to log in), you will see the App Key Management page as figure 4 below:

Fig. 4. The figure shows the App Key Management Page.

You can click “Add” to register a new app. Now you should predefine some static info here and maybe follow the default grey-out text in some fields.

Fig. 5. The figure shows you an example of how to fill the app related info to get an app key ID.

After pressing SUBMIT, you will get an app key like below:

Fig. 6. The figure shows you the results if submitted successfully.

Now go back to the DDE Editor.

By clicking Project -> Info, you can choose an app ID as the figure below:

Fig. 7. The figure shows you how to go to the place to enter the app-specific info.

Case 1. For developers to deploy

Having successfully registered the app, you will get an ID generated from the App Key Management. Now from the App ID field, you can choose the ID you just got. Note that you can use the same ID for other projects as well.

For case 1, all you need to fill in by yourself are the Domain Name and App ID, and then the other fields will be filled automatically after you have chosen an app ID.

Fig. 8. Project Info -> register a domain ID.

Fig. 9. Register a new Domain Name.

Fig. 10. Click All to access the list describing all the domains.

Case 2. For developers who intend to test the app

Case 2 is for users who only intend to use the DDE editor to test an app flow but don’t want it to be deployed at all. In contrast to Case 1, you can leave the app ID field blank by not selecting any. However, you have to to fill in “DDE Domain ID”, “Package Name”, “Launch Activity” and “App Names” by yourself. The system will not do it for you. (see Fig. 9.)

For example,

“Package Name”: "com.asus.webTest"

“Launch Activity”: "test.webTestActivity"

“App Names”: "webTest"

Fig. 11. Fill Domain Name, Package Name, Launch Activity and App Name

If the App Key ID is correct, the related info blanks will be filled automatically. Be sure to make your Package Name and Activity Name be the same as your own apps’ (here it means the package name and activity name in the code you will install on Zenbo), because that is how Zenbo SDK will get the corrected path to launch your app.

Part 3: An Overview of the Hello World project

In the Concepts Tab Page

In our Hello World app, there are three concepts, one of which is called MyCity. Click it, and you will see two instances: city001(Black City) and city002(White City).

Fig. 12. An overview of Concepts.

Fig. 13. Detailed info of the class MyCity.

In the Intents Tab Page

There are two intents :

Fig. 14. The overview of intents.

Let's take a look at utteranceToLanuchApp first.

Fig. 15. Detailed info of the intent utteranceToLaunchApp.

This intent is a cross intent, meaning saying one of these sentences to Zenbo will launch the Hello World app. Please pay particular attention to the patterns of these sentences. Follow these patterns when creating cross intents. If your app contains a cross intent sentence whose pattern is different from the above ones, your app will be rejected when you try to publish it.

An app can have more than one cross intent, but every cross intent must have the above six sentences, and every sentence has its unique pattern to follow.

Moving on, let's look at the other intent userSayHello.

Fig. 16. Detailed info of the intent userSayHello.

In the Plan Tab Page

There are two Plans:

Fig. 17. An overview of Plans.

Plan lanuchHelloWolrd_Plan.

Fig. 18. Part 1 of detailed info of lanuchHelloWolrd_Plan.

Fig. 19. Part 2 of detailed info of lanuchHelloWolrd_Plan.

The settings of “will this plan launch your app” in lanuchHelloWolrd_Plan is true so that this is an entry Plan for this app. When an user utterance hits the intent “utteranceToLanuchApp”(a csr event), and since there is no required belief needed to be collected, the Plan is triggered. Once this Plan is triggered, the Action is to choose a matched condition (In this case, it is the “always” condition that is matched.) and then set the next context to “helloWorld” to be listened by the DS.

Plan helloWorld_Plan.

Fig. 20. Part 1 of detailed info of helloWorld_Plan.

Fig. 21. Part 2 of detailed info of helloWorld_Plan.

The setting of “will this plan launch your app” in helloWolrd_Plan is false, so there must define an input context inside (In this case, it is defined as “helloWorld”, which is a trigger condition of this plan.).

Once the context stack "helloWorld" comes, and the user utterance hits the intent “userSayHello”, since there is a required Belief “myCity1”in this Plan, this Plan will start to check if the value of the required belief (myCity1) is already acquired from an user utterance; if not, the DS will seek clarification “can you tell me what city you are from?”, which is defined in the prompts of myCity1. If all the beliefs set to "required" are acquired, this Plan is triggered. However, the system will give up this plan after attempting clarification four times.

Once this Plan is triggered, the Action is to choose a matched condition (In this case, it is the “always” condition), and then set an empty output context to be listened by the DS. Then the System will display the response “welcome to my city”. You can usually easily control when to respond by getting the string and call the TTS API in the Zenbo SDK).

Part 4: Publish your Hello World project

Now that you have linked your own specific app key ID and the sample project together, you can now publish your project.

Fig. 22. The figure shows the button to Publish the project.

Part 5: Test on DDE

After publishing your app, before you test it on real devices, you can do a quick and simple test on the DDE editor.

Please input “start the hello world sample” or "開啟第一個測試" and press enter.

Fig. 23. Simple test of the hello world project.

Now you will see the response as below:

Fig. 24. Simple test result of hello world project.

Fig. 25. Simple test json result of hello world project.

Note: “start the hello world sample” or "開啟第一個測試" is defined in the utteranceToLaunchApp intent, and lanuchHelloWolrd_Plan has defined utteranceToLaunchApp as its CSR event. That is, once the CSR event “utteranceToLaunchApp” happens, the Plan is triggered.

You can then input “hello black city” and press Enter.

Fig. 26. Simple test of hello world project.

You will then get:

Fig. 27. Simple test result of hello world project.

Fig. 28. Simple test result of hello world project.

Note 1 : In the CSR case, the letters are always in lower case.

Note 2: How does this work? Remember the first Plan “lanuchHelloWolrd_Plan”. when the Plan is triggered, it has defined some tasks to do. One of the tasks is to set context status to “helloWorld”, which is actually one of the trigger conditions of the second plan “helloWorld_Plan” (The Input context is helloWorld), and “hello Black City” is defined in the userSayHello intent, which is also a CSR event in helloWorld_Plan; that is, once the CSR event “sayHelloWorld” intent happens, and the system also gets the required Belief info from the user utterance, the Plan is triggered.

Part 6: Test Belief Setting

Now, let’s try again quickly by the following steps:

Reset context
Input “start the hello world sample” or "開啟第一個測試" and press enter
Input “hello taipei” or "哈囉黑色城市"

Now , you will see a system clarification like below:

Fig. 29. Example of the system trying to do clarification to get the required Belief.

Why it happened?

Notice that under the belief setting in plan “helloWorld_Plan”, you will find that there are two beliefs.

Fig. 30. Review belief setting in helloWorld_Plan.

Regarding the first row, myCity1 is set to “required”, which means before you execute your task defined in this plan, you must get the value from the user, or the system will ask for clarification based on the prompt of this belief.

And how to interact with the system? Try inputting “white city”.

Fig. 31. Example answer of the clarification.

Fig. 32. Example of the result after the user answered the clarification,

notice that there are two beliefs extracted from the user utterance here.

Part 7: Test on Zenbo

Now, you must be wondering on how to test it on Zenbo.

First, you must install your own app with your registered packageName and Activity Name on the Dev Site.

After Installing, you can say “hey zenbo” and wait for the sign to speak “start the hello world sample” or "開啟第一個測試", now you will see Zenbo launch your app.

For more infomation on the right way to test on Zenbo, please refer to the developer website for other formal documents.

Your andorid code apk need add "82F199B9E7774C688114A72457E3C229 = domin uuid" and "0.0.1" is the version you can found before you go to edit a project on project center in "Manifest.xml".

Manifest.xml's content

</application>

Notice, the meta-data need to put between <application> and </application>

Part 8: Use DS API for the template project

Here are some sample codes for the DS API in the Zenbo SDK

Notice that

82F199B9E7774C688114A72457E3C229 is the DDE Domain UUID.
The behavior of setting context is one-shot. You may need to set the context in the next session if you want to use the context again.

Sample Code1:

sample code 1-1

//Normal case for start DS to listen user utterance

mRobotAPI.robot.speakAndListen("", 10);  // time out : 10 second

sample code 1-2

//Start TTS first then Listen user utterance  

mRobotAPI.robot.speakAndListen("Which city do you like?", 10);

Sample Code2:

/*

Set two contexts (helloWorld, helloWorld2) to be listened by DS and then start to listen user utterance.

suppose helloWorld and helloWorld2 are the input context of the plan for the status that i want to make the intent of the plan to be considered by DS.

*/



mRobotAPI.robot.setListenContext(“82F199B9E7774C688114A72457E3C229”, “helloWorld, helloWorld2”);

mRobotAPI.robot.speakAndListen("", 10);

Sample Code3

/*

 jump to the plan (lanuchHelloWolrd_Plan) and do the actions (set context status), and then start to listen user utterance.

*/

mRobotAPI.robot.jumpToPlan("82F199B9E7774C688114A72457E3C229",” lanuchHelloWolrd_Plan”);

mRobotAPI.robot.speakAndListen("", 10);

Sample Code4:

//clear current app context and then start to listen user utterance

mRobotAPI.robot.clearAppContext("82F199B9E7774C688114A72457E3C229");

mRobotAPI.robot.speakAndListen("", 10);

Part 9: Customize your DDE hello world Project

Now you can try modifying the “MyCIty” Concept as well as the sayHello intent, and make more specific plans on DDE.

Fig. 33. An example of a customized Concept.

Fig. 34. An example of a customized intent.

Fig. 35. An example of a customized intent.

Note that you can reference a concept using an "@", and then press "Enter" to get the orange UI as below :

Fig. 36. An example of referencing a concept as slot in a sentence.

Fig. 37. An example of referencing an app-specific concept as slot in sentence.

In Fig. 37, the expression means that the user utterance “hi black city” and “hi white city” will both hit the intent.

Fig. 38. An example of a customized plan.

Fig. 38 shows how to set the output context of the plan, you can define a whole new plan which has “nextContextAfterHelloWorld” as its input context.

Review

Now you should have known how to:

make a plan to trigger your app,
create your App specific Concept, and
reference an system concept in your intent sentences.

(If you are interested in the system concept, please see the system concept doc.)

Understand that a plan is triggered once:
- The CSR intent defined in the plan is hit
- The context status is the same as the input context in the plan
Understand that a plan will give up the action (even when the event is matched) once:
- The condition is not satisfied
- The value of the required Belief is missing and cannot be obtained from the user