Connect IQ SDK

Communication

Widgets and apps can communicate with a mobile phone via Bluetooth Low Energy (BLE). The mobile phone may be sharing data with the device, or it may act as a bridge between the app and the Internet. This allows the mobile phone to become part of the wearable web.

There are a few complications with device to phone communication. For example, the watch app may be killed during the time communication happens, or a phone app may try to send information while the app is not active. To simplify these cases for you, Monkey C does not expose a low-level interface, but instead exposes a very high-level approach. Instead of using a socket metaphor, the API exposes a mailbox metaphor. Messages are constructed as a parcel of information and sent back and forth. Each app will have a mailbox where messages are received, and an event that fires when new messages arrive.

There will also be a high level interface for making JSON and image requests. This will allow you the option of developing a wearable web app without having to write your own companion phone app.

Monkey C exposes two approaches for communicating with the mobile phone: through Garmin Connect™ Mobile and direct messaging.

Garmin Connect Mobile

Monkey C exposes some high level APIs to allow calls to basic web services.

module Communications
{
  //! To use Garmin Connect Mobile as a proxy to the web, use makeJsonRequest().
  //! The request is asynchronous; the responseCallback will be called
  //! when the request returns.
  //! @param [String] url The URL being requested
  //! @param [Dictionary] request Dictionary of keys and values, appended
  //! to the URL as a GET request
  //! @param [Dictionary] options Dictionary of options
  //! @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, request, options, responseCallback);

  //! To request an image through Garmin Connect Mobile, call makeImageRequest(). GCM
  //! will scale and dither the image based on the capabilities of the device, but
  //! the user will be able to pass additional options (like dithering it down to a
  //! one color image)
  //! @param [String] url URL of image to request
  //! @param [Dictionary] options Additional image options (TBD)
  //! @param [Method] responseCallback This is a callback in the format
  //! function responseCallback(responseCode, data);
  //! responseCode has the server response code, and data contains
  //! a WatchUi.Bitmap if it was successful.
  function makeImageRequest(url, options, responseCallback);
}

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

Some watch apps will want to communicate directly with a phone app. For these cases Monkey C exposes a concept of a mailbox. Each app will have its own mailbox that it can retrieve messages from and it can subscribe to an event that fires when a new message comes in.

//! The MailboxIterator is used to get the messages out of the Mailbox.
class MailboxIterator
{

  //! Call next() to get the next message from the mailbox.
  //! @return Message content, or null if no messages
  function next();
}
//! Call getMailbox() to get the MailboxIterator for this App's mailbox.
//! @return [MailboxIterator] Iterator for the mailbox
function getMailbox();

//! Add a listener for mailbox events. The listener method is called whenever a
//! new message is received
//! @param [Method] listener Callback in the format function listener(iterator).
//! iterator is the mailbox iterator for the app.
function setMailboxListener(listener);

//! To clear the contents of the mailbox, call emptyMailbox().
function emptyMailbox();

//! Send data across the the BLE link.
//! @param [Object] The object to be sent
//! @param [Dictionary] options Additional transmit options (TBD)
//! @param [ConnectionListener] listener An extension of the
//! ConnectionListener class.
function transmit(content, options, listener);

//! Listener class for transmit
class ConnectionListener
{
  //! Callback when a communications operation error occurs.
  function onError();

  //! Callback when a communications operation completes.
  function onComplete();
}

BLE Simulation Over Android Debug Bridge

When using the Connect IQ Simulator, you can communicate with a companion app running on an Android device using the Android Debug Bridge (ADB). This will simulate actual BLE speeds so you can get a feel for the performance of your application.

To enable the companion to communicate over ADB you must:

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

To allow the simulator to communicate over ADB, in a terminal or console forward the tcp port you are using to the Android device.

adb forward tcp:7381 tcp:7381

Note that this command will need to be reissued for each Android device you connect, or if you disconnect and re-connect a device.

Once your app is started on the phone, you can connect it to the simulator using the Connection | Start (CTRL-F1) menu item. The Connect IQ apps in the simulator will now be able to communicate with your device via the Communications APIs.

Getting the Mobile SDKs

The three Connect IQ Mobile SDKs are available separately from the Connect IQ SDK.

Get the Mobile SDKs