THETAプラグイン開発（theta-plugin-sdkについて）

githubで公開されている、THETAプラグイン開発用SDK(theta-plugin-sdk)の内容を確認する。

2020年1月24日更新：最近のSDKに合わせて更新 (SDK ver.1.0.2->ver.2.1.0)。リンク切れを修正。

1. はじめに

　RICOH THETA VはAndroid OSでできており、当初プラグインには対応していなかったが、６月末のRICOH THETAプラグインパートナープログラム開始によって、独自のAndroidアプリ（＝プラグイン）をインストールできるようになった。ここではSDKとドキュメントを確認する。

• SDK : https://github.com/ricohapi/theta-plugin-sdk
• ドキュメント：https://api.ricoh/docs/theta-plugin/how-to-develop/

開発したプラグインをadbコマンド経由でTHETA本体にインストールするにはTHETA Pluginの開発者登録する必要がある（THETA V or Z1実機の写真が必要）。サイトはRICOH Developer Connection上にあるが、プラグイン開発者登録は"RICOH Account"とは無関係なので、RICOH Accountを作る必要はない。

• プラグイン開発者登録: RICOH THETA Plug-in Partner Program
• 登録アカウントの管理: RICOH THETA Plug-in Partner Program (Profile)
• 開発したプラグイン登録:RICOH THETA Plug-in Partner Program (Partner Menu)

2. theta-plugin-sdkの中身

　githubからcloneしたtheta-plugin-sdk(ver.2.1.0)をAndroid Studioで開いてみる。

　ソースコードを見ると、appとpluginlibraryの２つに分かれている。appではnetworkなどのクラス群が実装されている。SDKのver.1.xまでは直接ソースコードとしてpluginlibraryが含まれていたが、ver.2.xからは app/build.gradleでimplementation 'com.theta360:pluginlibrary:2.1.0'のような形でセットアップされ、MainActivity.javaのなどのコード上で import com.theta360.pluginlibrary.activity.PluginActivity; のような形でimportするようになっている。

(↓ ver.1.0.2の場合はtheta-plugin-libraryがコード(pluginlibrary)として含まれていた。)

theta-plugin-libraryではプラグイン固有の仕様に対応した実装がされている。独自のプラグインを作る場合は主にapp部分を開発し、もしも必要があればtheta-plugin-library部分を修正できる。
　また、theta-plugin-sdkはTHETA Vのシャッターボタンを押して、静止画が撮影できるようになっている。

• app

  • MainActivity.java（上の画面キャプチャ部分）
    • PluginActivityを継承したMainActivityになっており、onCreate(), onResume(), onPause()のみ実装されている。PluginActivityはpluginlibraryで定義されている。
    • onCreate()内の実装
      • setKeyCallbackが呼ばれ、KeyCallback interfaceの実装が行われている。
      • onKeyDown()
        • シャッターボタン(KEYCODE_CAMERA)だった時はAsyncTaskを継承したTakePictureTaskが呼ばれる。
          TakePictureTaskのdoInBackground()内ではlocalhost("127.0.0.1:8080")宛にcamera.takePictureのWebAPIが呼び出されている。
        • WebAPIとはTHETA向けのWebAPIであり、GoogleのOpen Spherical Camera APIを拡張したものとなっている。
        • WebAPIの呼び出しには同じくapp内に実装されているHttpConnectorクラスが使われている。このクラスはtakePicture以外のコマンドも実装されており、WebAPIの呼び出しが必要となった時に利用できるだろう。
      • onKeyUp()
        • どこかのボタンを押し上げる（戻す）とnotificationLedBlinkが呼ばれる。
        • notificationLedBlinkを用いて、LED3 (Wireless Light)を青色で点滅させる実装がされている。
      • onKeyLongPress()
        • 特に実装されていない。pluginlibraryでモードボタンの長押しに対応するコードが実装されている。

• theta-plugin-library (pluginlibrary)

  • pluginlibraryにはドキュメントに記載されているTHETA独自のブロードキャストなどが定義されている。
  • PluginActivityはAppCompatActivityを継承しており、AndroidアプリのActivity Lifecycle部分(onCreate, onResume, onPause)が実装されている。 以下の図はdeveloper.android.comより引用
    • onCreate()
      • AndroidのUncaughtExceptionHandlerを継承した、UncaughtExceptionクラスが登録されており、何か例外が発生すると、エラーとなってプラグインが終了するようになっている。
    • onResume()
      • キーイベントの登録がされている。pluginlibraryに実装されたKeyReceiverクラスが利用されており、このクラスにReceiving Button Eventsに記載があるようなブロードキャストインテントを取得する部分が実装されている。onKeyReceiverがPluginActivityクラス内に定義されており、appのMainActivityで利用していたonKeyLongPressなどのコールバックはonKeyReceiver経由で行われる。
    • onPause()
      • isClosedの設定によっては、終了処理が呼び出される。
      • KeyReceiverクラスの登録を解除する。onPause以降はキーイベント（コールバック）が来なくなる。
  • その他、PluginActivityクラスには以下のようなメソッドが定義されている。Broadcast Intentに記載されている多くの制御をメソッドの呼び出しで利用できる。
    • notificationWlanOffなどWLANを制御するメソッド
    • notificationLedShowなどのLEDを制御するメソッド
    • notificationAudioShutterなどの音を制御するメソッド
    • notificationCameraOpenなど、Camera APIを使うときに必要なメソッド

　既存のAndroidアプリのプロジェクトをプラグインにする時は、theta-plugin-sdkからpluginlibraryなど必要な部分をプロジェクトへインポートorコピーして使えば良い。

3. スマホ or THETA Vで動かして見る

　AndroidスマホもしくはTHETA Vで動かして見る。手元のスマホはAndroid 7.0なので、minSdkVersionとtargetSdkVersionをAPI24に変更する必要があった。
　AndroidスマホでPluginSDKアプリを動かして見た。(Thetaには画面がないはずだが)Hello Worldが表示されている。同じようにAndroidアプリをTHETA上で動作させることもできる。THETAの画面表示にはVysorを使うことができる。

4. まとめ

　プラグイン開発は通常のAndroidアプリの開発と同様にAndroid Studioを用いて行うことができる。THETA Vのプラグインに固有の機能を実装したクラス群がtheta-plugin-sdkの中で定義されている。PluginActivityクラスを利用することでTHETAを制御でき、HttpConnectorクラスでWebAPIで定義された機能を利用することができる。

参考

• RICOH THETA プラグイン開発　ワークショップ　＃１ 資料