Connect IQ/Programmer's Guide/Communication - api_programming @ ウィキ

http://developer.garmin.com/connect-iq/programmers-guide/communication/

Widget と Apps は Bluetooth Low Energy (BLE) を用いてスマホ（携帯電話）と通信可能。
スマホはデバイスとデータを共有したり、他のアプリケーションやネットとの橋渡しとして振る舞う。
これにより、スマホがウェアラブルウェブの一部となる。

デバイスとスマホの通信には、やや複雑なところがある。
例えば、時間に関する通信が行われている間に時計のアプリは落ちてしまったり、時計側のアプリがアクティブでない時に携帯のアプリが情報を送信しようしとしたり、といった場合だ。
開発者がこういった問題を簡単に理解できるようにするため、Monkey C は low-level インターフェースを公開せず、代わりに high-levelアプローチ（ソケットメタファではなくメールボックスメタファを）採用している。
メッセージは、情報の小包としてとして作成され、デバイス間を行き来する。
各アプリは受け取るメールボックスを持っていて、新しいメッセージが到着するとイベントを開始する。

JSONや画像のリクエストをつくる high-levelインターフェースもある。
これにより、開発者が独自のスマホアプリを書くことなく、ウェアラブルアプリを開発するオブションを提供している。

Approaches

Monkey C はスマホ（携帯電話）との通信手段を２つ準備している。

• Germin Connect Mobile
• Direct Messaging

Garmin Connect Mobile

Monkey C は Germin Connect Mobile を通じて基本的なウェブサービスを呼び出すことができる。

module Communications
{
   // ウェブのプロクシとして Garmin Connect Mobile を使う方法には makeJsonRequest() を使う
   // リクエストは非同期で行われる。リクエストが帰ってきたときにレスポンスコールバックが呼ばれる
   //    @param [String] url : リクエストURL
   //    @param [Dictionary] parameters : GETリクエストやPOSTリクエストでセットされる、キーと値。null も可。
   //    @param [Dictionary] options : オプション。null も可。
   //    @option options [Number] : The HTTP メソッドmethod of the request. HTTP_REQUEST_METHOD_XXX value.
   // @option options [Dictionary] :headers A Dictionary of HTTP headers to include in the request.
   // @option :headers [Number] "Content-Type" In the dictionary of HTTP headers, content
   //       type can be specified using a REQUEST_CONTENT_TYPE_XXX value. If the content type
   //       is not specified, it will default to "appllication/json" for GET and DELETE requests,
   //       and will default to "application/x-www-form-urlencoded" for POST and PUT requests.
   //       This option is only needed for overriding these defaults.
   // @param [Method] responseCallback : This is a callback in the format function
   //       responseCallback(responseCode, data); responseCode has the server response code, and
   //       data contains a Dictionary of content if the request was successful.
   function makeJsonRequest( url, parameters, options, responseCallback );

   // These are the supported HTTP methods
   enum {
       HTTP_REQUEST_METHOD_GET = 1,
       HTTP_REQUEST_METHOD_PUT = 2,
       HTTP_REQUEST_METHOD_POST = 3,
       HTTP_REQUEST_METHOD_DELETE = 4
   }
}

These APIs expose JSON requests and image requests as very straightforward APIs for making REST API calls. The JSON calls are converted to serialized Monkey C data and sent across the BLE pipe.

Direct Messaging

WatchApp の中には、 Garmin Connect Mobile を通す代わりに直接スマホアプリと直接通信したいものもある。
このような場合に、Monkey C は「メールボックス」の概念を提供する。
各Appはメッセージを受け取る独自のメールボックスを持っており、メッセージを受け取った際にはイベントを発生させる。

//! メールボックスからメッセージを読み出すためには MailboxIterator を用いる
class MailboxIterator
{
   //! next() : メールボックスから次のメッセージを取得する
   //!    @return Message content （メッセージがなければNull）
   function next();
}

//! getMailbox() : アプリのメールボックスの MailboxIterator を取得する
//!    @return [MailboxIterator] メールボックスの MailboxIterator
function getMailbox();

//! SetMailboxLister( listener) : メールボックスのイベント用のリスナーを追加する。
//!    リスナーメソッド は、新しいメッセージを受け取るたびに呼び出される
//! @param [Method] listener Callback in the format function listener(iterator).
//!       iterator is the mailbox iterator for the app.
function setMailboxListener( listener );

// emptyMailbox() : メールボックスを空にする
function emptyMailbox();

//! BLEリンクを通じて、データを送る
//! @param [Object] 送られるオブジェクト
//! @param [Dictionary] options Additional transmit options (TBD)
//! @param [ConnectionListener] listener ConnectionListener classの拡張
function transmit( content, options, listener );

//! Listener class for transmit
class ConnectionListener
{
   //! onError() : 通信操作がエラーとなった場合に呼び出されるコールバック
   function onError();

   //! onError() : 通信操作が完了した場合に呼び出されるコールバック
   function onComplete();
}

Mobile SDK Downloads

ConnectIQ Mobile SDK は ConnectIQ Developer SDK とは別にリリースされており、iOS と Android で利用できる。
Mobile SDK には幾つかの種類がある。

• Android BLE
• iOS BLE
• Android ADB

BLE は Android, iOS を用いたデバイスで通信できるアプリの開発をサポートする。
ADB は ConnectIQ シミュレータでのテストで用いられる。

スマホのプラットフォームにあったバージョンをダウンロードするための情報は、Garmin Developer サイトで見つかられるかも。

BLE Simulation Over Android Debug Bridge

ConnectIQ シミュレータを用いるときには、ADBを用いている Android デバイスで動いているアプリと通信することができる。
これにより、実際の BLE スピードに近いパフォーマンスでシミュレートすることができる。

The ADB edition of the Android Mobile SDK and companion app is required to use ADB for testing. Here’s how to enable the companion to communicate over ADB:

   Connect the phone to the PC running the simulator via USB
   Have USB debugging enabled on the Android handset
   Obtain an instance of ConnectIQ using getInstance( IQCommProtocol.ADB_SIMULATOR )
   Optionally call setAdbPort( int port ) to set a specific port to use for communication (the default port is 7381)
   Call initialize()

To allow the simulator to communicate over ADB, forward the TCP port to the Android device in a terminal or console:

adb forward tcp:7381 tcp:7381

Note that this command will need to be reissued for each connected Android device, or if a device is disconnected and re-connected.

Once your app is started on the phone, connect it to the simulator by clicking the Connection menu and selecting Start (CTRL-F1). The Connect IQ apps in the simulator will now be able to communicate with your device via the Communications APIs over ADB.