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

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 プラグイン開発　ワークショップ　＃１資料