開發者
ok
選擇您的語系
English繁體中文
Zenbo SDK - 入門
Zenbo SDK - 入門
v1.0.1
v1.0.1
Document

Zenbo SDK - 入門

系統要求

Zenbo 的作業系統版本是 Android M。你可以使用 Android Studio 或其他 IDE 進行 android 開發。有關更多訊息，請參閱 Android Studio。

SDK包

  1. Java Jar 文件 (ZenboSDK.jar)
  2. 擴展 Android Activity 函式庫
  3. RobotDevExample 原始碼
  4. ZenboSDK 的 Javedoc

SDK設備

  1. Android M，API level 23
  2. Dependency Google GSON library

關於 Zenbo SDK

DS：對話系統

CSR：連續語音識別

SLU：口語語言理解

App產出

開發者準備：

  1. 開發者在 DS 編輯器中加入交叉意圖，例如“拍照”，接著編輯package名稱並啟動活動名稱。
  2. 使用 DS 編輯器來定義應用程式操作，以便你可以使用語音命令控制應用程式。
  3. 使用 Zenbo SDK 開發你的應用程式，並包含運動、視覺、機器人和實用程式(utility)。

 

由使用者執行：

  1. 使用語音命令“Hey Zenbo”來啟動CSR，接著說出交叉意圖（例如拍照）。
  2. DS系統向雲端發送語音指令，回傳SLU結果。
  3. 機器人框架通過解析 SLU 結果打開應用程式。
  4. 應用通過 Zenbo SDK 接收 DS 編輯器中該APP定義的 SLU 結果並執行相應的操作。
  5. App 可以利用 Zenbo SDK 執行機器人的功能。

Zenbo SDK 架構

子類(Subclass)

Zenbo SDK 包括以下子類：

  1. 機器人：對話系統，表情。
  2. 視覺：臉部偵測、身體追蹤、手勢偵測、測量高度。
  3. 運動：移動身體/頭部，遠端遙控。
  4. 實用程式(utility)：跟隨使用者，通過手勢去某個地點，播放情感動作。
  5. WheelLights：閃爍、呼吸、充電、跑馬燈。
  6. 聯絡人：使用者資料、房間資訊。
  7. SLAM：獲得位置資訊。

Callback

每個函數回傳一個命令序號。開發者可以使用序號來驗證結果。

  • 一般callback
    • onStateChange：回傳命令狀態，包括ACTIVE、PENDING、SUCCESS、FAIL。如果回調回傳“FAIL”，則該參數包含錯誤代碼
    • onResult：命令處理時的回傳參數
  • DS callback: Listen class
    • onResult：SLU 結果
    • onRetry：當 DS 無法識別結果時自動再次詢問
    • onVoiceDetect：檢測語音事件，例如檢測 HeyZenbo，啟動/停止 CSR
  • 視覺callback
    • onDetectFaceResult：回傳人偵測測結果，包括人臉位置、人臉框位置等
    • onDetectPersonResult：回傳人員位置
    • onGesturePoint：回傳手臂手勢點位置

SLU範例

{
    "system_info": {
        "version_info": "ver1.0"
    },
    "event_slu_query": {
        "user_utterance": [
            {
                "CsrType": "Google",
                "result": [
                    "show me a",
                    "show me a call",
                    "show me",
                    "show me all",
                    "show me a song"
                ]
            },
            {
                "CsrType": "vocon",
                "result": "show me the photo"
            }
        ],
        "correctedSentence": "show me the photo",
        "error_code": "success",
        "app_semantic": {
            "IntentionId": "gallery.photo.request",
            "Domain": "49",
            "domain": "com.asus.robotgallery",
            "CrossIntent": true,
            "output_context": [
                "gallery_device_previous_state",
                "gallery_device_choose",
                "gallery_device_choose_number",
                "gallery_cancel",
                "gallery_quit",
                "gallery_show_tutorial",
                "gallery_repeat_tts"
            ],
            "Phrase": []
        },
        "speaker_id": "",
        "doa": 0
    }
}

請參閱 DS 文件以了解更多資訊。

Zenbo App開發注意事項

清單文件(Manifest file)

Zenbo SDK 需要以下標籤：

<application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
    <meta-data android:name="zenbo_ds_domainuuid" android:value="82F199B9E7774C688114A72457E3C223"/>
    <meta-data android:name="zenbo_ds_version_82F199B9E7774C688114A72457E3C223" android:value="0.0.1" />
    <activity
                android:name=".MainActivity"
                ...
            
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
            <category android:name="com.asus.intent.category.ZENBO" />
            <category android:name="com.asus.intent.category.ZENBO_LAUNCHER" />
            <data android:name="com.asus.intent.data.MIN_ROBOT_API_LEVEL.1" />
        </intent-filter>
    </activity>
</application>

Note:

<meta-data android:name="zenbo_ds_domainuuid" android:value="82F199B9E7774C688114A72457E3C223"/> and
<meta-data android:name="zenbo_ds_version_82F199B9E7774C688114A72457E3C223" android:value="0.0.1" />:
這是 DDE 所定義的，你必須在Manifest 中寫入這些資訊，否則語音命令將無法打開應用程式。 “2F199B9E7774C688114A72457E3C223”是domain UUID。 ”0.0.1”是 DDE版本。細節請參考 DDE 文件。

<category android:name="android.intent.category.LAUNCHER" />:
建議刪除此行。刪除此行後，使用者將無法通過觸控打開應用程式，只能使用語音命令打開應用程式。

<category android:name="com.asus.intent.category.ZENBO" />:
此行聲明此活動與 Zenbo SDK 相容。 Zenbo 應用程式使用此類別來列出機器人上已經安裝相容應用程式。

<category android:name="com.asus.intent.category.ZENBO_LAUNCHER" />:
此行允許你的應用程式顯示在 Zenbo Launcher 中。

<data android:name="com.asus.intent.data.MIN_ROBOT_API_LEVEL.1" />:
此數字指的是應用程式運行時所需要的最低機器人 API level。如果機器人 API level低於此屬性中指定的值，Zenbo 商店將阻止使用者安裝應用程式。此狀況類似於 Android API level。

當App啟動時獲取 cross-intent SLU

Intent intent = getIntent();
JSONObject slu_json;
try {
    slu_json = new JSONObject(intent.getStringExtra("json"));
} catch (NullPointerException | JSONException ex) {
    ex.printStackTrace();
}

OnCreate - declare RobotAPI

RobotAPI mRobotAPI;

@Override
protected void ononCreate (Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    mRobotAPI  = new RobotAPI(thisContext, callbackHandle);
}

onPause/onResume:

@Override
protected void onResume() {
    super.onResume();
    mRobotAPI.robot.registerListenCallback(dsCallback);
}
@Override
protected void onPause() {
    super.onPause();
    mRobotAPI.robot.unregisterListenCallback();
}

註記：

當應用程式處於“onPause”狀態時，callback仍然有效。應用程式需要調用 unregisterListenCallback 來中斷連接。如果應用程式之前中斷了連接並且狀態變回“onResume”時，則應用程式需要利用

導覽和狀態欄

建議隱藏 UI 的導覽和狀態欄。

擴展機器人活動

RobotActivity 是利用Zenbo SDK 編寫應用程式的起點。 RobotActivity 是基本的activity，可以輕鬆的與 Zenbo 進行整合，通常在為 Zenbo 建立activity時會需要。請參閱範例程式程式。

 

Access機器人傳感器

介紹

機器人傳感器的存取已經整合到android SensorManager 中。
只需使用 android SensorManager 就可以取得傳感器數值。

傳感器類型

電容式觸摸傳感器(Capacity touch sensor)：

Zenbo 的頭上有一個觸摸傳感器。該傳感器可以進行感應觸摸並可以將觸摸時間識別為“短觸摸”或“長觸摸”。

跌落傳感器(Drop laser sensor)：

Zenbo 底部有五個跌落傳感器。這些傳感器可以幫助感應 Zenbo 周圍地面的距離。

聲納(Sonar)：

Zenbo 使用聲納來測量周圍環境的距離。每個輪子都有一個聲納傳感器。 Zenbo 的機身前方還有三個傳感器，後方也有一個。

里程計(Odometry)：

里程計根據車輪計數提供當前位置和方向。當 Zenbo 啟動里程計時，會將位置重置為 (0, 0) 並將其方向重置為 0 rad。
這可以用來計算不同時間點之間的相對位置。

頸部編碼器(Neck encoder)：

此編碼器用於監測 Zenbo 的頸部角度。

車輪編碼器(Wheel encoder)：

該編碼器用於監測車輪速度。

本體加速度計原始數據(Body accelerometer raw data)：

該傳感器記錄本體中的加速度計數據。

本體陀螺儀原始數據(Body gyroscope raw data)：

該傳感器紀錄本體中的陀螺儀數據。

馬達(Motor)：

該傳感器紀錄馬達的數據。

Dock IR：

記錄本體背面的紅外線傳感器的數據。

頸部軌跡(Neck trajectory)：

記錄當前軌跡。

車輪軌跡(Wheel trajectory)：

記錄當前車輪軌跡。

傳感器列表：

Sensor

SensorEvent Data

Description

Units

TYPE_DROP_LASER

SensorEvent.values[0]

Drop laser info #5

meters

SensorEvent.values[1]

Drop laser info #4

meters

SensorEvent.values[2]

Drop laser info #3

meters

SensorEvent.values[3]

Drop laser info #2

meters

SensorEvent.values[4]

Drop laser info #1

meters

SensorEvent.values[5]

Drop laser info #5

mcps

SensorEvent.values[6]

Drop laser info #4

mcps

SensorEvent.values[7]

Drop laser info #3

mcps

SensorEvent.values[8]

Drop laser info #2

mcps

SensorEvent.values[9]

Drop laser info #1

mcps

TYPE_CAPACITY_TOUCH

SensorEvent.values[0]

1: 0.35s > T >= 0.005s
2: 1s > T >= 0.35s
3: 3s > T >= 1s
4: T > 3s

 

TYPE_SONAR

SensorEvent.values[0]

Right sonar

 

SensorEvent.values[1]

Left sonar

 

SensorEvent.values[2]

Back sonar

 

SensorEvent.values[3]

Right sonar on the front side

 

SensorEvent.values[4]

Left sonar on the front side

 

SensorEvent.values[5]

Central sonar on the front side

 

TYPE_ODOMETRY

SensorEvent.values[0]

The current position of the base in x axis

meters

SensorEvent.values[1]

The current position of the base in y axis

meters

SensorEvent.values[2]

The heading direction of the base

radian

TYPE_NECK_ENCODER

SensorEvent.values[0]

Robot neck yaw

radian

SensorEvent.values[1]

Robot neck pitch

radian

SensorEvent.values[2]

Bit 0 : Busy Yaw
Bit 1 : Busy Pitch
Bit 2 : Error Yaw (over stop position)
Bit 3 : Error Pitch (over stop position)
Bit 4 : Break Yaw
Bit 5 : Break Pitch
Bit 6 : Driver Yaw
Bit 7 : DriverPitch

 

TYPE_WHEEL_ENCODER

SensorEvent.values[0]

Left wheel

m/s

SensorEvent.values[1]

Right wheel

m/s

TYPE_ROBOT_BODY_ACCELEROMETER_RAW

SensorEvent.values[0]

Robot body acceleration force along the x axis(including gravity)

m/s2

SensorEvent.values[1]

Robot body acceleration force along the y axis(including gravity)

m/s2

SensorEvent.values[2]

Robot body acceleration force along the z axis(including gravity)

m/s2

TYPE_ROBOT_BODY_GYROSCOPE_RAW

SensorEvent.values[0]

Robot body rate of rotation around the x axis

rad/s

SensorEvent.values[1]

Robot body rate of rotation around the y axis

rad/s

SensorEvent.values[2]

Robot body rate of rotation around the z axis

rad/s

TYPE_ROBOT_MOTOR

SensorEvent.values[0]

Neck yaw current

A

SensorEvent.values[1]

Neck pitch current

A

SensorEvent.values[2]

Left wheel current

A

SensorEvent.values[3]

Right wheel current

A

SensorEvent.values[4]

Neck yaw PWM

counts

SensorEvent.values[5]

Neck pitch PWM

counts

SensorEvent.values[6]

Left wheel PWM

counts

SensorEvent.values[7]

Right wheel PWM

counts

TYPE_ROBOT_DOCK_IR

SensorEvent.values[0]

Right dock IR

 

SensorEvent.values[1]

Center dock IR

 

SensorEvent.values[2]

Left dock IR

 

TYPE_ROBOT_NECK_TRAJECTORY

SensorEvent.values[0]

Robot neck yaw

radian

SensorEvent.values[1]

Robot neck

radian

TYPE_ROBOT_WHEEL_TRAJECTORY

SensorEvent.values[0]

Left wheel

m/s

SensorEvent.values[1]

Right wheel

m/s

如何使用傳感器

傳感器類型參數已經於 RobotAPI.Utility.SensorType 中聲明。

細節請參考“了解RobotSensorSample APP”章節和“RobotSensorSample”程式碼。

 

了解 RobotDevExample App

每個應用程式包括 3 個模組：

  1. ZenboSDK：Zenbo SDK 模組。
  2. RobotActivityLibrary：具有擴展活動和導入 Zenbo SDK 的 AAR 模組。
  3. RobotDevSample-RobotDevSample：Zenbo SDK 的原始碼。

運動範例：MotionMoveBodyHead.java

這是一個如何使用 Zenbo SDK 的範例。檢查選項motion->moveBody & moveHead。

你可以輸入 x、y 和 theta 值，讓 Zenbo 移動它的身體。

mBtn_MoveBody.setOnClickListener(new Button.OnClickListener() {
    @Override
    public void onClick(View v) {
        float x = Float.valueOf(mEditTextMoveBodyX.getText().toString());
        float y = Float.valueOf(mEditTextMoveBodyY.getText().toString());
        float theta = Float.valueOf(mEditTextMoveBodyTheta.getText().toString());
        robotAPI.motion.moveBody(x, y, theta);
    }
});

 

 

Q&A

  1. 為什麼我的App會自動關閉並回到Zenbo的臉上？

Zenbo 有兩種模式：Android 模式和 Zenbo 模式。

  1. Android 模式：當 Zenbo 的臉出現時按下主頁按鈕。
  2. Zenbo模式：Zenbo的臉出現在螢幕上。可以使用語音命令或 Zenbo 應用程式打開應用程式。

你必須在 Zenbo 模式下打開 Zenbo 應用程式；否則1分鐘後又會回到Zenbo的臉上。加入FLAG_KEEP_SCREEN_ON 可以跳過 Zenbo 模式timeout，但是當收到“嘿 Zenbo”時它仍然會回到 Zenbo 的臉。
 

  1. 為什麼我在 Zenbo 商店找不到我的最新應用程式？

請檢查 MIN_ROBOT_API_LEVEL。 Zenbo 商店將顯示比系統更高 ROBOT_API_LEVEL 的應用程式。如果你不使用較新的 API，則可以在清單中分配較低的 MIN_ROBOT_API_LEVEL。大多數 API 是向後兼容的。
 

  1. 我可以使用壓頭功能嗎？

是的，這可以分兩步完成。

  1. 使用 RobotAPI.robot.setPressOnHeadAction 關閉系統行為。
  2. 使用 Utility.SensorType.CAPACITY_TOUCH 類型引用 AndroidSensorManager 以監聽“按下頭部”事件callback。

 

  1. 我可以獲得 3D 相機或深度視圖原始數據嗎？

不行，目前不提供開發者使用 3D 相機。
 

  1. VisionConfig 是什麼意思？

我們為每個參數添加了說明。更多資訊請參考最新的 ZenboSDK 文檔。

 

  1. “Hey Zenbo”和看著使用者在嘈雜的環境中不起作用。我能做什麼？

你可以改用藍牙麥克風。但是，Zenbo 無法從藍牙麥克風獲取聲音方向。
 

  1. 為什麼我在使用 API 時會收到 SERVICE_FAIL？

請在 onCreate 中使用新的 ZenboSDK instance，並在收到 onResume 或 RobotCallback.initComplete() 後使用 API。請勿在建立 ZenboSDK instance時使用任何 API。

 

 

 


 

Go To Top