DDE編輯器教程

Hello World 範例 with Java SDK for Zenbo Junior

0. Preface

華碩智慧機器人提供許多 Zenbo Junior 範例程式，供開發者夥伴更快熟悉 Zenbo Junior程式的開發方式。本文件將以 DDE 上 Hello World 語料為範例，說明如何在 Zenbo Junior 上搭配 Android SDK，產生一個支援對話的應用程式。

要執行 Hello World 範例程式，您的 Zenbo Junior 需要使用 v13.10.8.195 以上的版本，您可以在「設定」中的「關於平板電腦」中檢視「版本號碼」確認。而您的Zenbo Junior SDK需為 v2.1.18.2129 以上的版本。

本文內容將包含下述幾點，在您完成以下 2 個主要步驟後，即可在 Zenbo Junior 機台上體驗
Hello World 測試程式：

1. 在 DDE 網站上發佈語料並上傳到 Server。

[1] 在 DDE 匯入 Hello World 語料範例。

[2] DDE 的基礎語料設定。

[3] Hello World 的語料說明。

[4] 發佈自己的語料。

[5] 在 DDE 直接測試語料。

[6] 上傳語料至華碩開發者 Server。

2. 建置應用程式並安裝到 Zenbo Junior 機台。

[1] 在 Zenbo Junior 上執行 Android 範例程式。

希望在讀完本文後，能讓您快速上手第一個 Zenbo Junior 的對話應用開發，協助您來完成所期望的應用程式及語料。

1. 在 DDE 匯入 Hello World 語料範例

步驟 1：登入 DDE 網站

網址為 https://zenbo.asus.com/developer/tools/ds-editor.jsp。

進入網站後，請在 Project Center 點選 Import Template Project。

步驟 2：載入 Hello World 範例語料

選擇 Template Project : Hello World，點選 Add 鍵，即可成功匯入專案。

2. DDE 的基礎語料設定

為了後續能連結到您的 App，我們首先需要請您做些基本的設置，包含 Domain ID、Package Name 等相關的設置，未來您也可以透過直接修改這個 Template，來產生您所需要的語料。

首先，請先點選 Hello World 的 Project 下的 Edit 按鈕，開始編輯該專案。

由於每個語料皆需要對應的 Domain ID，因此需要先申請一個 Domain ID。申請 Domain ID 的步驟如下：

步驟 1：進入 Info 選單

點選 Menu 中 Info 按鈕。

步驟 2：註冊 Domain ID

點選 Project Info 中的 Register。

步驟 3：填入 Domain Name

在 Register a new Domain 的視窗中填入您的 Domain Name 和描述，並按下 Create。

步驟 4：儲存 Project Info

回到 Project Info 中，我們會看到在 DDE Domain ID 中，出現一組新的 Domain，其中包括一個系統配發的數字，而後面的括號裡則會有您剛剛所輸入的 Domain Name，請您選取這個 Domain，並點選 Save 以儲存 Project Info。

為方便後續章節的說明，在 Package Name、App Name 及 Launch Activity 的部分，請您先保留 Template 的預設值，因為相關設置都需要對應到您實作的 Android App。

Hello World 範例語料中上述欄位的預設值如下：

- Package Name：com.asus.zenbodialogsample
- App Name：Hello World
- Launch Activity：activity

您可以檢視當前的設定是否維持預設值，如您調整預設值，在後續章節中的對應值，或在未來如您實作自己的 Android App，也將會需要做相應調整。

完成上述四個步驟後，即完成 DDE 上的基本 Domain 設定。

3. Hello World 的語料說明

本章節中為您說明語料編輯方式。您若想先快速使用範例程式可以先略過本章節的說明，之後再回來繼續了解如何設計語句，完成您的應用程式。

一個基本的語料由 Plans、Intents 和 Concepts 組成，以下將簡要說明每一個部分，並將以 Hello Wold 為例說明。

3.1 Plans 說明

Plan 用來串接語句結果、參數及系統狀態，以下將會對其中幾項重要設置做說明：

Is the plan able to launch the app：設值為 true 時，表示此 Plan 為 Cross Intent。亦即不需要前置的 Plan，只要當使用者說出對應語句，即會進入該 Plan。
Input Context：需要將前項 Is the plan able to launch the app 設值為 false 時才可填入，如果沒有填值，則效力將會等同於前項 Is the plan able to launch the app 設值為 true。 Input Context 表示只有在系統於此 Context 狀態下時，才會允許進入該 Plan。
Events：為 Plan 的觸發條件，需連結到所設計的對應 Intent。關於 Intent 的詳細說明將會在後續的 3.2 章節中為您介紹。
Actions：當觸發了此 Plan 之後，可設定系統要轉換到哪項 Output Contexts 的狀態，並可設定對應各別語系所要發出的 TTS 語句。
Beliefs：設置該 Plan 預期要抽取的參數，以及設計倘若缺少該參數時的回問方式，此處參數名稱需與在 Intent 中的設計一致。

以範例語料 Hello World 為例，語料中實作了兩個 Plan，分別為 lanuchHelloWolrd_Plan 及helloWorld，說明如下：

lanuchHelloWolrd_Plan
該 Plan 中，「Is the plan able to launch the app?」項目設值為 true，表示這個 Plan為 Cross Intent，也就是表示無需處在特定的上下文脈絡下就能被觸發。在 Events 中設置 utteranceToLanuchApp 為此 Plan 所連結的 Intent，而 Intent ID 後方括號中的內容則表示所選用 Intent 的支援語言，當值為 All 時表示將會支援所有的語系。
helloWorld
該 Plan 中，「Is the plan able to launch the app?」項目設值為 false，並且其中的「Input Context」的欄位為「helloWorld」，表示此為 Context 下的 Plan，需要進入到「helloWorld」這個上下文脈絡後，該 Plan 才有機會被觸發。也就是說，在 Events 中所設置連結的 userSayHello 這個 Intent，需要在滿足 Plan 本身的 Context 條件，以及 userSayHello 的意圖要求時，此 Plan 才會被觸發。

3.2 Intent 說明

Intents 我們稱之為「意圖」。在一個意圖內可以設計多個句型，而一個句型可由多個詞彙來組合。在 DDE 的介面顯示上，會再被細分為以藍色或橘色的方塊來呈現不同的用途。

藍色方塊為直述文字，本文之後將簡稱為藍字；橘色方塊則為引用的 Concept，本文之後簡稱為橘字；而淡橘色方塊也是橘字的一種，是表示該 Concept 可有可無，不是必需條件。

建立 Intent 輸入語句時，如果需要引用 Concept，可輸入@後挑選所需的 Concept，可選擇系統內建的預設 Concepts 或自訂的 Concepts。

您在設計 Intents 時，也能分別依照不同的語系來設計各別的意圖語句，目前提供的語系選項包括英文、繁體中文、簡體中文、廣東話、日本語，將會對應使用者Zenbo Junior 機台的語系設定，來提供不同語系的意圖支援。如果您設計意圖時，選擇All 則表示在機台語系設定切換至上述各語系時，系統都將支援此 Intent 的意圖語句。

以 Hello World 範例為例，該範例設計兩個意圖，分別為：

utteranceToLaunchApp
本意圖設計兩個句型，第一個句型由五個部分組成，一個藍字，一個橘字，以及三個淡橘色的橘字。而在<AppName>可以代入 Hello World，也就是說，當使用者講「我要用 Hello World」即會選中這一個意圖。

userSayHello
本意圖中設計了五個句型，其中第五個句型是由一個藍字，以及一個橘字組成。在 MyCity 這個 Concept 內有「白色城市」、「黑色城市」等詞彙，代表當使用者說出「哈囉白色城市」或「哈囉黑色城市」，皆會命中此意圖。

若在意圖中需要抽取參數，需要為其加入 Belief Name，設定方式是在要設定的橘字上，點擊滑鼠左鍵，並在 Set Belief Name 處設定參數名稱。

橘字還可以設定使用的方式，例如是否要依順序(Order)使用、是否為可選(Optional)項目、完全命中(PerfectMatch)，都將會影響到語句是否可擊中所設計的意圖。詳細的操作方式，可以參考 DDE 的使用教學文件。

3.3 Concept 說明

Concept 為詞彙的集合，您可以把同類型詞彙都定義在同一個 Concept 內，以方便管理。

以本範例而言，MyCity 有 2 組 Instance 分別為 city001、city002。在每個 ID 後方欄位裡，可以填入一組同義詞。以 city001 為例，即表示「Black City」和「黑色城市」這兩個詞彙，在本應用中就代表著相同的意義。

另外，請留意 Concept 需要依據語系來設計的，如希望該詞彙在所有語系皆可支援，則可選擇 all，否則請加入在指定語言的列表中。您可點選 + different lang 處新增所要支援的語系詞彙，目前提供英文、繁體中文、簡體中文、廣東話、日本語的語系選項。

3.4 注意事項

當 Zenbo Junior 設定中文語系下，語音辨識引擎主要以中文為主，僅能辨識少量的英文。因此未來開發者在設計語句時，請盡量避免在 DDE 中設計中英文混雜的語句，因為這類型的語句語音辨識度不佳，會進一步影響到語意意圖的理解。

4. 發佈自己的語料

語料編輯完後，需要完成發佈的動作之後，才可以在 DDE 介面上做測試，而發佈語料的步驟如下：

步驟 1：發佈語料

點選螢幕右方的 Publish 按鈕，之後會跳出 Data Validation 的畫面。

步驟 2：資料驗證

請點選 Continue To Publish，畫面會跳出 Validation 的結果。若顯示「Success!!」表示資料驗證無誤。

步驟 3：完成語料發佈

請點選 Continue To Publish。

執行完畢後，上方會跳出 Success 資訊，表示此時已發佈成功。

5. 在 DDE 直接測試語料

在 DDE 頁面的右端，有提供一個語料測試的工具介面，您可以透過文字方式，在此模擬語句與對話意圖間的關係，確認是否能讓目標語句擊中您所預期的意圖，及能否取得您所需要的參數值。

下圖為輸入「我要用 hello world」後的回傳結果。

6. 上傳語料至華碩開發者 Server

在DDE 上實際對建置的語料測試完畢後，您此時可以將語料上傳到華碩開發者Server 上，之後您便可在 Zenbo Junior 上將語料下載到機台中使用。

步驟 1：上傳語料

在 Dev 頁籤下點擊「Deploy To Download Server」，將語料上傳 Server。

步驟 2：取得 Metadata（重要步驟）

點擊跳出的完成畫面右下方的「Copy the meta-data to Clipboard」按鈕，複製 Manifest 文字訊息。在開發 Android App 時，會需要將 Manifest 文字訊息貼上到 Android Manifest 中，操作步驟我們將在後續的 7.1.3 章節中為您詳細說明。

7. 在 Zenbo Junior 上執行範例程式

在本章節中，將向您說明如何在 Zenbo Junior 機台上執行您開發的應用程式，以下段落將為您詳細說明Android SDK 執行範例程式的方式，並為您說明範例程式所使用到的 SDK 功能。

7.1 以 Android SDK 方式執行範例程式

7.1.1 範例程式下載位置

前往華碩開發者平台，網址為 https://zenbo.asus.com/developer/tools/zenbo_junior_i

點選頁面中間 Zenbo Junior SDK 區塊的 Download 按鍵下載 SDK 及範例程式。

7.1.2 設定 Android 開發環境

開啟 Android Studio，確認您已經下載了 Android 6.0 的 SDK。如尚未下載，請點選 File 下的 Settings。

在 Android SDK 勾選 Android 6.0，並點選 OK 鍵，即完成 Android SDK 6.0 的安裝。

開啟 ZenboJuniorSDK_and_SampleCode 專案資料夾，其中 ZenboDialogSample 即為 HelloWorld 的範例程式。我們接下來將會在這支範例程式上，與您一起完成您的第一支 Zenbo Junior 應用程式。

在您初次開啟範例程式專案時，如出現錯誤訊息「ERROR: SDK location not found. Define a location by setting the ANDROID_SDK_ROOT environment variable or by setting the sdk.dir path in your project's local.properties file.」，則您可以點擊在錯誤訊息中的藍色文字「Set sdk.dir in local.properties and sync project」來排除 SDK 路徑問題，完成後 Build 訊息欄位將顯示如「CONFIGURE SUCCESSFUL in 1s」的執行成功訊息，之後當您再次使用範例程式專案時，就不會再遇到此問題。

7.1.3 Android 範例程式設定

步驟 1：修改 Manifest

開啟ZenboDialogSample\src\main 路徑下ZenboDialogSample 中的AndroidManifest.xml檔案，以「Deploy to Download Server」時所複製到剪貼簿中的字串，覆蓋掉下圖反白處的字串。如您未保留 Deploy 階段時的字串內容，請您參考第 6 章操作方式再次 Deploy 語料之後，複製所需的 Manifest 文字訊息。

您所複製的 Manifest 字串內，包含 Domain 語料的 UUID、語料版本、Package Name，應該會是呈現如下的結構：

步驟 2：設定安裝時自動更新語料

在AndroidManifest 檔案中，加入下述內容，讓語料在安裝 APK 過程中可以自動進行更新。

步驟 3：更新範例程式中的 UUID

修改專案中的 ZenboDialogSample.java，將 Android Manifest 中的 UUID，複製到程式中的 DOMAIN 參數值，檔案路徑為 ZenboDialogSample\src\main\java\com\asus\zenbodialogsample。

7.1.4 Android 範例程式說明

我們定義了幾項建議開發者設置的全域變數，可以方便您後續操作 SDK 行為，以下參數分別對應到 Log Tag、Domain UUID、Domain ID、Package Name，範例中將使用到 TAG 以及 DOMAIN，而您可視需求決定是否建立 DOMAIN_ID、PKG_NAME 等參數

public final static String TAG = "ZenboDialogSample";
public final static String DOMAIN = "1B4C7D6DF6034B389316818208D1BFF7";
public final static String DOMAIN_ID = "16546";
public final static String PKG_NAME = "com.asus.zenbodialogsample";

protected void onResume

調用 Zenbo Junior 的 SDK，包括 setExpression、jumpToPlan、speakAndListen、speak，在接下來我們將逐一做介紹。

protected void onResume()
{ super.onResume();
// close faical
robotAPI.robot.setExpression(RobotFace.HIDEFACE);
// jump dialog domain
robotAPI.robot.jumpToPlan(DOMAIN, "lanuchHelloWolrd_Plan");
// listen user utterance
robotAPI.robot.speakAndListen("Which city do you like?", new SpeakConfig().timeout(20));
// robotAPI.robot.speak("Which city do you like?", new SpeakConfig().timeout(20));
// show hint
mTextView.setText(getResources().getString(R.string.dialog_example));
}

setExpression

用於為 Zenbo Junior 設置各式表情，我們共提供 27 種表情，您可以在需要時為 Zenbo Junior 指定符合語境或行為的表情反應，包括 ACTIVE、AWARE_LEFT、 AWARE_RIGHT 、 CONFIDENT 、 DEFAULT 、 DEFAULT_STILL 、 DOUBTING 、 EXPECTING 、HAPPY 、HELPLESS 、HIDEFACE 、IMPATIENT 、INNOCENT 、 INTERESTED、LAZY、OTHER_USE、PLEASED、PRETENDING、PREVIOUS、PROUD、 QUESTIONING、SERIOUS、SHOCKED、SHY、SINGING、TIRED、WORRIED。

jumpToPlan

用於指定觸發的 Plan，當您需要跳轉到指定的 Plan 時就可以使用，需要提供您要跳轉的 Domain UUID 及 Plan Name。因為我們在程式的開頭處已經設置相關全域變數了，所以請直接填 DOMAIN 即可，而 Play_Basic 則改成您想要跳轉觸發的 Plan。

speakAndListen

表示在 Zenbo Junior 發完 TTS 語音後，將會自動收音來取得使用者的回應語句。您可以調整 SpeakConfig 以操作 TTS 的行為，如語速、音調、收音時間等。

speak

表示 Zenbo Junior 在發完 TTS 語音後，即完成行為。您同樣可以調整 SpeakConfig來操作 TTS 的行為。

protected void onPause

在 onPause 階段，以 stopSpeakAndListen 強制中斷尚未完成的發話及收音行為。

protected void onPause()
{ super.onPause();
//stop listen user utterance
robotAPI.robot.stopSpeakAndListen();
}

public static RobotCallback.Listen robotListenCallback

這支程式主要架構在 RobotCallback.Listen，也就是 CSR 收音內容送到 Server 端處理完畢後，回到 Local 端的 Callback 中，在 RobotCallback.Listen 的 onResult 中，會收到 Server 回傳的 JSON 物件，其中就是語意理解完成後得到的資訊，接下來將為您逐一做介紹。

public static RobotCallback.Listen robotListenCallback = new RobotCallback.Listen()
{ @Override
public void onResult(JSONObject jsonObject)
{ String text;
text = "onResult: " + jsonObject.toString();
Log.d(TAG, text);
String sIntentionID = RobotUtil.queryListenResultJson(jsonObject, "IntentionId");
Log.d(TAG, "Intention Id = " + sIntentionID);
String domain = RobotUtil.queryListenResultJson(jsonObject, "domain");
String utterance = RobotUtil.queryListenResultJson(jsonObject,"correctedSentence");
String response = RobotUtil.queryListenResultJson(jsonObject, "output_text");
String beliefs = RobotUtil.queryListenResultJson(jsonObject, "beliefs");
if (sIntentionID.equals("helloWorld")) {
String sSluResultCity = RobotUtil.queryListenResultJson(jsonObject,"myCity1",null);
Log.d(TAG, "Result City = " + sSluResultCity);
if (sSluResultCity != null) {
mTextView.setText("You are now at " + sSluResultCity);
}
}
}
}

首先，以 queryListenResultJson 解析收到的JSONObject，此處為您介紹五個常用參數的用途，除了範例程式中有使用到的 IntentionId 外，還包括 domain、correctedSentence、 output_text、beliefs 等。這五項資訊的涵義如下：

1. domain: Package Name；

2. IntentionId: 語句的意圖，可以對應 DDE Domain Project 上的 Plan ID；

3. correctedSentence: 是經過校正後的 CSR 內容，若您需要的是原始的 CSR 內容，則請您取用 originalSentence；

4. output_text: 依據您定義的 Intent，此時要發出的 TTS 內容；

5. Beliefs: 為您所有抽取到的參數內容。在後方 PARAM 相關段落中，則為您示範如何以遍歷的方式取得 beliefs 參數的內容，詳情您可以參考 getBeliefArray、getBeliefValue 中的操作方式。

如果您在測試過程中，Log 中所印出的 Intention 值為空字串，可能是表示您未能成功擊中該意圖，這時就需要您檢視意圖設計語句內容，以確認您設計的語句是否能涵蓋實際辨識出的文字內容。

若您對於完整的 Zenbo Junior SDK 功能感到興趣，可以前往華碩 Zenbo Junior 開發者網站參考 Zenbo Junior SDK 的 API 文件，其中將為您介紹更多 Zenbo Junior SDK API 項目，網址為 https://zenbo.asus.com/developer/documents/zenbo_junior/Zenbo-Junior-SDK/DialogSystem

7.1.5 在 Zenbo Junior 上安裝並執行範例程式

在本章節中，將與您一起把範例程式安裝到 Zenbo Junior 機台中實際執行，首先我們需要將您的專案輸出為可以安裝的 APK 檔案。

步驟 1：建置專案

依序點擊 Build 頁籤的 Clean Project、Rebuild Project，無需等待 Clean Project 完成，即可點擊 Rebuild Project，Android Studio 將會為您安排依序執行。

步驟 2：建置 APK

在 Android Studio 提示流程完成後，請到 Build 頁籤的 Build Bundle(s) / APK(s)選項，點擊您所需的輸出格式，若要輸出 APK 格式則請點擊 Build APK(s)，開始輸出 APK 檔案。

步驟 3：取得 APK 檔案

當 Android Studio 提示已完成 APK 檔案輸出後，請前往專案路徑下取得 APK 檔案，例如 ZenboDialogSample\build\outputs\apk\debug\ZenboDialogSample-debug.apk，或您可以直接點選提示訊息中的藍色 locate 文字，開啟 APK 檔案所在位置。

步驟 4：安裝 APK 到 Zenbo Junior 機台

在 APK 所在的檔案路徑下，開啟命令提示字元 CMD 後輸入指令進行安裝，若是曾經有安裝過同樣的 APK 到該 Zenbo Junior 的機台過，則需要加上-r 參數，例如以下指令：

如果此時出現 Success 字樣表示安裝成功。若您於 AndroidManifest.xml 的 zenbo_ds_auto_update 值是設為 true，此時會依照您填寫的語料版本，自 Server 端去下載對應的語料到 Zenbo Junior 機台中，在完成語料更新之後，您就可以開始使用您的程式了。

錯誤排除：

如果出現 error: no devices/emulators found、adb: error: failed to get feature set: no devices/emulators found、- waiting for device -的錯誤訊息，則您需要確認 Zenbo Junior 機台是否已與該電腦以 Micro USB 線連接。

若已連接傳輸線，則需要確認是否已開啟 USB 偵錯。若您尚未開啟 USB 偵錯及取得開發者權限，請您先在設定的關於平板電腦中，連續點擊版本號碼取得開發者權限，然後在系統點擊進階，而後點擊開發人員選項，並確認 USB 偵錯為開啟狀態後，請點選確定以開啟 USB 偵錯。

此時會跳出「允許 USB 偵錯嗎？」視窗，您可以勾選「一律允許透過這台電腦進行」並點擊確定，後續以傳輸線連接同一台電腦時，就不需要再進行確認了。

觸控螢幕並下拉畫面，在選單點擊「已開啟 USB 檔案轉移模式」，點選檔案轉移選項。

重新執行指令，待畫面出現 Success 訊息，即代表程式已完成安裝。

7.1.6 Test Android Sample application on Zenbo Junior

步驟 1：開啟範例程式

您已經完成範例程式的安裝步驟，有兩種方式啟動 Hello World 範例程式：

在 Zenbo Junior 的 App 列表內，點擊 ZenboDialogSample 圖示使用範例程式。
喚醒 Zenbo Junior 後，以「我要用 Hello World」語句進入範例程式。

步驟 2：於程式中做語句測試

進入 Hello World 範例程式後，Zenbo Junior 會詢問 Which City Do You Like，您可以回答「哈囉黑色城市」或「哈囉白色城市」語句來做測試，並觀察意圖和取得參數的結果，是否與您所設計的語句意圖相符。

附錄：Hello World 測試語句參考表

Intent	Sentence
utteranceToLanuchApp	我要用 Hello World
userSayHello	哈囉黑色城市
userSayHello	哈囉白色城市
userSayHello	哈囉臺北市
userSayHello	哈囉高雄
userSayHello	嗨紐約

8. 結語

本文以 DDE 上 Hello World 範例語料為例，說明如何在 Zenbo Junior 上通過搭配 Android SDK，產生一個支援對話的應用程式。希望您在閱讀本文之後，能上手開發出您的第一個 Zenbo Junior 對話應用，來完成您所期望的應用程式功能。

倘若您對於完整的 Zenbo Junior SDK 功能感到興趣，也可以前往華碩 Zenbo Junior 開發者網站參考 Zenbo Junior SDK 的 API 文件，其中將會為您介紹更多 Zenbo Junior SDK API 項目，網址為https://zenbo.asus.com/developer/documents/zenbo_junior/Zenbo-Junior- SDK/DialogSystem

如果本文有任何未盡之處，或您想與我們取得聯繫，也歡迎您隨時通過以下的聯繫方式來聯絡我們，將竭誠為您服務： https://zenbo.asus.com/contact.