Developer Blog

Connect IQ - BLE Direct Messaging Updates

02/09/17 @ 04:55 PM


The BLE Direct Messaging link feature of the Connect IQ SDK has received an overhaul with a focus on:

  • Reduced data transfer latency
  • Ability to remotely launch an application on the watch

All wearable devices (except for Epix) support these features as of the Connect IQ 2.2.3 SDK and Android / iOS Mobile 1.3 SDK releases.

Faster Data Transfer

A new lower latency API for direct messaging is now available for watch apps that communicate directly with a phone app via the Connect IQ Mobile SDK. These apps will receive a speed boost once they implement the new registerforPhoneAppMessages API, which is used to receive messages from a phone app. The behavior of this new API should be familiar with users of registerForOAuthMessages, since it shares the same base Message type. If messages are received when no callback is registered with this API, they are saved on the device until the storage limit for messages is reached. Any messages that are saved on the device will be sent to the specified callback after it is specified in registerforPhoneAppMessages. The transmit API is used to send messages directly to a phone app. A connection listener is registered with each transmit to receive the status of the attempted transmission:

//! Register a callback for receiving Phone App messages. The callback will be called
//! once for each message received. If there are messages waiting for the app when this
//! function is called, the callback will immediately be called once for each
//! waiting message.
//! @param method [Method] The callback with the signature callback(data). Data will be of
//!                        type PhoneAppMessage
//! @since 1.4.0
native function registerForPhoneAppMessages(method);
 
//! 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();
}

The existing mailbox API has been deprecated in ConnectIQ 2.2 and registerforPhoneAppMessages should be used instead for the aforementioned performance gains. An example of using both together in practice:

using Toybox.Communications;
    
class Example {
    function initialize() {
        var mailMethod = method(:onMail);
        var phoneMethod = method(:onPhone);
        if(Communications has :registerForPhoneAppMessages) {
            Communications.registerForPhoneAppMessages(phoneMethod);
        } else {
            Communications.setMailboxListener(mailMethod);
        }
    }
  
    ...
  
    // @param [MailboxIterator] mailIter
    function onMail(mailIter) {
        var mail = mailIter.next();
 
        while(mail != null) {
            // Do something with mail
            mail = mailIter.next();
        }
 
        Communications.emptyMailbox();
    }
 
    // @param [PhoneAppMessage] msg
    function onPhone(msg) {
        // Do something with msg.data
    }
}

The setMailboxListener and registerForPhoneAppMessages APIs are mutually exclusive and cannot be used at the same time in an app. If both listeners are registered, the deprecated mailbox listener will not receive any callbacks; messages will only be sent to the registerForPhoneAppMessages listener.

Opening an App on a Watch

The 1.3 updates for both the iOS and Android Mobile SDK’s allow you to prompt the user to open a Connect IQ application on their device. If the user chooses to open the app then it will be immediately opened. Only watch-apps may be launched remotely; launching widgets, data-fields and watch-faces is not supported.

Android

For Android you can use the openApplication API to request the remote launch. A response from the device will be returned to your IQOpenApplicationListener:

connectIQ.openApplication(device, app, new IQOpenApplicationListener() {
 
    @Override
    public void onOpenApplicationResponse(IQDevice device, IQApp app, IQOpenApplicationStatus status) {
        // Handle the response here
    }
 
});

See the Comm sample application included with the Android Mobile SDK for an example implementation.

iOS

For iOS you can use the the openAppRequest: method to request the remote launch:

[[ConnectIQ sharedInstance] openAppRequest:app
                                completion:^(IQSendMessageResult result) {
    switch(result) {
        case IQSendMessageResult_Success: NSLog(@”Popup was displayed”); break;
        case IQSendMessageResult_Failure_PromptNotDisplayed: NSLog(@”Popup was
                displayed”); break;
        case IQSendMessageResult_Failure_AppAlreadyRunning: NSLog(@”Popup was
                displayed”); break;
    }
}];

See the ExampleApp sample application included with the iOS Mobile SDK for an example implementation.

What’s Next?

Both of the samples included with the Android / iOS Mobile SDK’s have been updated to support remotely launching Comm sample from the Connect IQ SDK, which also now supports new registerForPhoneAppMessages API for faster communication. Get the SDK’s today to start playing with the new features!

Categories: Connect IQ SDK