NUWA Robot SDK Manual

ver 1.1.4

目次

NUWA Robot SDKとは？

NUWA Robot SDKは、NUWA Robotics 製のロボット（2019年11月現在、日本ではケビーのみ対応）用のアプリ開発キットです。Android Pをベースに動作しており、Android Studioを利用してアプリを作成することが可能です。

開発環境と関連資料

NUWA Robot SDKは、次の開発環境をサポートしています。

最新情報は、公式ホームページで公開しています。

NUWA Robot APIが含まれるAndroid Archive(aar)の他、サンプルコード、チュートリアルなどを提供しています。

NOTICE : Content Editor only for Business Partner, please contact nuwarobotics for more information.

※ 本ドキュメントは、NUWA Robot SDK Manualを日本語訳し、日本人向けにアレンジしたものです。最新のマニュアルについては、英語マニュアルを参照してください。また、初心者向けの日本語チュートリアルも合わせてご利用ください。

本ドキュメントの役割

本ドキュメントでは、NUWA Robot SDKの概要および、NUWA Robot APIの簡単な使い方を解説しています。APIの詳細につきましては、NUWA Robot SDK Javadoc を御覧ください。

APKのインストール

Androidの開発ツール（ADB）を利用して、アプリのapkをインストールすることが出来ます。ADBの接続にはパスワードが必要です。

APIの初期化と終了

アプリを作成するには、"NUWA Robot API"のインスタンスを作成する必要があります。

コールバックの登録

NUWA Robot APIのすべての機能は、Android インターフェース定義言語（AIDL）をベースに、非同期で動作します。ロボットからの通知を受け取るために、コールバックを登録する必要があります。

ロボットのイベントを受け取るための RobotEventListener と、音声認識のイベントを受け取るためのVoiceEventListener が用意されています。

ヘルパークラスを使用して、イベントの上書きも可能です。

APIの開始手順

NUWARobotAPI のインスタンス（mRobot）が作成されると、onWikiServiceStartのイベントが発生します。APIの呼び出しは、このイベントを受け取った後に行う必要があります。

モーションプレーヤー

ロボットを動作させるためのアクションを定義した「モーションファイル」を再生することが可能です。モーションファイルはタイムラインで制御されています。MP4による動画再生、モーター制御、LED制御などの要素で構成されており、APIを利用して再生することで、ケビーに一連のアクションを実行させることが出来ます。

※一部のモーションは、MP4による動画再生を含みません（モーター制御のみで構成されています）。

モーションファイルは、あらかじめNUWAが用意したファイルと、ユーザーが独自に作成したファイルの2種類が存在します。NUWAが用意したファイルの一覧については、以下のドキュメントを参照してください。

[Kebbi Motion list] NUWA MOTION

モーションファイルの作成には、NUWAが提供している「コンテンツエディター」を利用できます。Webベースのアプリケーションで、タイムラインを利用して簡単にモーションファイルを作成することが出来ます。

[Kebbi Content Editor] NUWA Content Editor

オーバーラップウィンドウコントロール

動画を含んだモーションファイルを再生する場合、標準の状態では、画面上部にオーバーラップウィンドウが表示されます。このウィンドウの表示をコントロールすることが可能です。

ウェイクワードによる呼びかけ

startWakeUp()を使用すると、ウェイクワード（「ハロー、ケビー」）による呼びかけを利用できます。アプリの実行中に、ユーザーから「ハロー、ケビー」と呼びかけられると、onWakeUpイベントが呼ばれます。

ローカル音声合成(TTS)

音声合成を利用して、ケビーに任意の文字列を発話させる事が可能です。

日本で発売しているケビーは、日本語と英語の２種類の音声合成が搭載されています。発話させる文章に日本語が含まれている場合は、文章全体を日本語の音声合成で発話します。

TTS Capability (Only support on Kebbi Air)

ローカル音声認識（ASR）

ASRエンジンの使用キーワードのリストを記述するSimpleGrammarDataは、アプリが最初にGrammarを作成する必要があります。 （命令リスト）

基本的な例

VoiceEventListener Callback

クラウド音声認識（ASR）とローカル音声認識（ASR）の混合

ローカルの音声認識（ASR）で認識結果が取得できなかった場合に、より認識精度の高い、クラウドの音声認識（ASR）を利用して音声認識の結果を取得することが出来ます。

  1. ローカル音声認識に成功した場合は、その結果を返却します（クラウド音声認識は実行しない）
  2. 失敗した場合は、クラウド音声認識を行い結果を返却します（インターネットが利用可能な場合のみ）

音声認識の結果は、json 形式の文字列として返却されます。

VoiceEventListener Callback

センサーイベント

ケビーには、タッチセンサー、人感センサー（PIR）、落下防止センサーが搭載されています。これらのセンサーイベントは、リクエストにより有効になります。

LED制御

ケビーには、4つのLED（頭、胸、右手、左手）が搭載されています。ケビーが生きているように振る舞う「ブレスモード」と、プログラムからLEDを自由に制御するための「ライトオンモード」が用意されています。

デフォルトではシステムがLEDを制御しています。これを停止してアプリから制御するには、disableSystemLED を呼び出す必要があります。アプリが終了する前（アプリが onPause 状態になった時）に、enableSystemLED を呼び出すのを忘れないでください。

NOTICE : Kebbi-air not support FACE and Chest LED Breath mode.

サーボモーター制御

ケビーには、10個のサーボモーターが搭載されています。APIを使用して、それぞれを制御することが可能です。

モーターには、それぞれIDが付与されています。これとは別に、移動用のホイールが床面に存在します。

[モーターの位置とID]

motor_id

モーターの角度範囲

各モーターに設定可能な角度の範囲は以下のとおりです。

ID12345678910
Max204057010005701000
Min-20-40-85-200-3-80-85-200-3-80

移動制御

ホイールを動作させて、ケビーを移動させることが可能です。前進、後退、旋回、停止の動作を行うことが出来ます。

ロックホイールモード

充電ケーブルを接続している場合、「ロックホイールモード」が自動的に有効になります。アプリ内で unlockWhee を呼び出すことで、ロックホイールモードを無効にすることができます。

※充電ケーブルの破損には十分注意してください。

落下イベント

ケビーが机の上などから落下した場合、イベントが発生します。RobotEventListenerのコールバックを利用して、このイベントを受け取ることが可能です。

Face control

Example

Custom Behavior

class BaseBehaviorService

Developer should implement a class to determine how to react when receiving a customized NLP response from NUWA Trainingkit.

class ISystemBehaviorManager

This class has been encapsulated in BaseBehavior. Developer can get this instance which is created by BaseBehavior.

class CustomBehavior

The Object which let developer define how to to deal with customized NLP response.

Sample code

Robot Service Recoveryのハンドリング

Robotサービス（Robot SDK）が予期しない例外を発生すると、ケビーは自動的に再起動します。アプリはRobotEventListenerのコールバックを利用することで、シナリオの終了処理などを適切に行うことが出来ます。

ロボットメニューに、アイコンを追加する方法

マニフェストファイルに記載することで、ケビーのロボットメニューにアプリのアイコンを追加することが出来ます。

音声コマンドでの呼び出し

マニュフェストファイルを設定することで、ケビーの音声コマンドから、アプリを呼び出す事ができるようになります。アクティビティを起動したり、インテントをブロードキャストしたりすることが可能です。

音声コマンドは、文字列の内容が100%マッチする必要があります。カンマ区切りで複数のコマンドを登録することができ、日本語の指定も可能です。

Disable Support Always Wakeup

Kebbi-air support "Always wakeup" anywhere. (Kebbi and Danny only support wakeup on Face) We allow App declare on Application or Activity scope.

Application Scope Example

Activity Scope Example

How to call nuwa ui to add face recognition

App could call nuwa Face Recognition APP to add a face to system. Developer could lunch App by Intent and receive face-id and name from onActivityResult.

    private final int ACTIVITY_FACE_RECOGNITION = 1;

    private void lunchFaceRecogActivity() {
        Intent intent = new Intent("com.nuwarobotics.action.FACE_REC");
        intent.setPackage("com.nuwarobotics.app.facerecognition2");
        intent.putExtra("EXTRA_3RD_REC_ONCE", true);
        startActivityForResult(intent, ACTIVITY_FACE_RECOGNITION);
    }
    
    
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        Log.d(TAG, "onActivityResult, requestCode=" + requestCode + ", resultCode=" + resultCode);
        if (resultCode > 0) {
            switch (requestCode) {
                case ACTIVITY_FACE_RECOGNITION:
                    mFaceID = data.getLongExtra("EXTRA_RESULT_FACEID", 0);
                    mName = data.getStringExtra("EXTRA_RESULT_NAME");
                    Log.d(TAG, "onActivityResult, faceid=" + mFaceID + ", nickname=" + mName);
                    lunchRoomListActivity(mName);
                    break;
            }
        } else {
            Log.d(TAG, "unexception exit");
        }
    }

Setup 3rd App as Launcher app to replace Nuwa Face Activity

Nuwa Face Activity is a Unity Activity to present kebbi face. We setup it as default HOME APP to make sure HOME Key can back to Nuwa Face Activity.

We allow Developer totally replace kebbi face by following implementation.

Step1 : declare 3rd App as a HOME APP.

  <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.HOME" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>

Step 2 : Setup 3rd App as default HOME App. 

1. Open Setting
2. click "About Kebbi" 10 times to enable developer menu
3. click "Home Setting"(啟動器設定)

setting

4. "Home app" (ホームアプリ) -> setup to your app

setting_default_app setting_default_launcher

NOTICE : This setting will cause "Nuwa Face Activity" not always shown after HOME KEY pressed. You have to call Face Control API to trigger shown.

Prevent HOME KEY to suspend device

Some business environment request not allow user suspend device by press HOME KEY.

1. Open Setting
2. click "About Kebbi" 10 times to enable developer menu	1. 
3. "Home screen key for locking screen" (ホーム画面のキーロック画面)
4. disable it to prevent goToSleep when press HOME Key on Nuwa Face Activity.

How to Auto Launch 3rd Activity when bootup

3rd App can declare following intent on Androidmanifest.xml.

Full Example：

<activity android:name=".CustomerAutoStartActivity">
    <intent-filter>
       <action android:name="com.nuwarobotics.feature.autolaunch" />
       <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

 

Q＆A

質問：

mRobot.motionPlayで指定したモーションが実行できません

回答：

  1. onErrorOfMotionPlay のコールバックをチェックして、エラー情報を確認してください
  2. モーション名が有効であることを確認してください
  3. モーションリストを確認し、正しいモーション名を指定してください

[Kebbi Motion list] https://dss.nuwarobotics.com/documents/listMotionFile

質問：

アプリからLEDを制御できません

回答：

  1. LEDを制御する前に、disableSystemLED を呼び出してください。例：onCreate 内に記述。
  2. アプリが終了する前に、enableSystemLED を呼び出す必要があります。例：onPause 内に記述。

質問：

ボタンなどを表示しても、タッチイベントを受け取れない場合があります。

回答：

オーバーラップウィンドウがすでに表示されている可能性が高いです。hideWindow(false)を呼び出して、オーバーラップウィンドウを非表示にしてください。オーバーラップウィンドウは、起動時には非表示になっていますが、モーションファイルの再生を行うと表示状態になります。 モーションの再生が終わると、onCompleteOfMotionPlay が呼び出されるので、この中でhideWindow(false)を呼び出してください。

質問：

音声認識（ASR）は、どの言語をサポートしていますか？

回答：

日本語と英語をサポートしています。

質問：

音声合成（TTS）は、どの言語をサポートしていますか？

回答：

日本語と英語をサポートしています。日本で発売しているケビーは、日本語と英語の２種類の音声合成が搭載されています。発話させる文章に日本語が含まれている場合は、文章全体を日本語の音声合成で発話します。

質問：

ロボットのタッチイベントが利用できません

回答：

  1. タッチイベントを利用する前に、mRobot.requestSensor(SENSOR_TOUCH)を呼び出してください。
  2. 次の例のように、コールバックでタッチ処理を行います
    mRobot.registerRobotEventListener(new RobotEventListener() {
        @Override
        public void onTouchEvent(int type, int touch) {
            // type: head: 1, chest: 2, right hand: 3, left hand: 4
            // touch: touched: 1, untouched: 0
        }
    });

※タッチイベントを終了する場合は、mRobot.stopSensor(NUWARobotAPI.SENSOR_NONE)を呼び出す必要があります。