com.getpebble.android.kit

Class PebbleKit

java.lang.Object

com.getpebble.android.kit.PebbleKit

public final class PebbleKit
extends java.lang.Object

A helper class providing methods for interacting with third-party Pebble Smartwatch applications. Pebble-enabled Android applications may use this class to assist in sending/receiving data between the watch and the phone.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PebbleKit.FirmwareVersionInfo
static class	PebbleKit.PebbleAckReceiver A special-purpose BroadcastReceiver that makes it easy to handle 'RECEIVE_ACK' intents broadcast from pebble .apk.
static class	PebbleKit.PebbleDataLogReceiver A special-purpose BroadcastReceiver that makes it easy to handle 'DATA_AVAILABLE' data logging intents broadcast from pebble.apk.
static class	PebbleKit.PebbleDataReceiver A special-purpose BroadcastReceiver that makes it easy to handle 'RECEIVE' intents broadcast from pebble.apk.
static class	PebbleKit.PebbleNackReceiver A special-purpose BroadcastReceiver that makes it easy to handle 'RECEIVE_NACK' intents broadcast from pebble .apk.

Method Summary

Modifier and Type	Method and Description
static boolean	areAppMessagesSupported(android.content.Context context) Synchronously query the Pebble application to see if the connected watch is running a firmware version that supports PebbleKit messages.
static void	closeAppOnPebble(android.content.Context context, java.util.UUID watchappUuid) Send a message to the connected Pebble to close an application identified by a UUID.
static void	customizeWatchApp(android.content.Context context, Constants.PebbleAppType appType, java.lang.String name, android.graphics.Bitmap icon) Send a message to the connected Pebble to "customize" a built-in PebbleKit watch-app.
static PebbleKit.FirmwareVersionInfo	getWatchFWVersion(android.content.Context context) Get the version information of the firmware running on a connected watch.
static boolean	isDataLoggingSupported(android.content.Context context) Synchronously query the Pebble application to see if the connected watch is running a firmware version that supports PebbleKit data logging.
static boolean	isWatchConnected(android.content.Context context) Synchronously query the Pebble application to see if an active Bluetooth connection to a watch currently exists.
static android.content.BroadcastReceiver	registerDataLogReceiver(android.content.Context context, PebbleKit.PebbleDataLogReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'DATA_AVAILABLE' intent.
static android.content.BroadcastReceiver	registerPebbleConnectedReceiver(android.content.Context context, android.content.BroadcastReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'CONNECTED' intent.
static android.content.BroadcastReceiver	registerPebbleDisconnectedReceiver(android.content.Context context, android.content.BroadcastReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'DISCONNECTED' intent.
static android.content.BroadcastReceiver	registerReceivedAckHandler(android.content.Context context, PebbleKit.PebbleAckReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE_ACK' intent.
static android.content.BroadcastReceiver	registerReceivedDataHandler(android.content.Context context, PebbleKit.PebbleDataReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE' intent.
static android.content.BroadcastReceiver	registerReceivedNackHandler(android.content.Context context, PebbleKit.PebbleNackReceiver receiver) A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE_NACK' intent.
static void	requestDataLogsForApp(android.content.Context context, java.util.UUID appUuid) A convenience function to emit an intent to pebble.apk to request the data logs for a particular app.
static void	sendAckToPebble(android.content.Context context, int transactionId) Send a message to the connected watch acknowledging the receipt of a PebbleDictionary.
static void	sendDataToPebble(android.content.Context context, java.util.UUID watchappUuid, PebbleDictionary data) Send one-or-more key-value pairs to the watch-app identified by the provided UUID.
static void	sendDataToPebbleWithTransactionId(android.content.Context context, java.util.UUID watchappUuid, PebbleDictionary data, int transactionId) Send one-or-more key-value pairs to the watch-app identified by the provided UUID.
static void	sendNackToPebble(android.content.Context context, int transactionId) Send a message to the connected watch that the previously sent PebbleDictionary was not received successfully.
static void	startAppOnPebble(android.content.Context context, java.util.UUID watchappUuid) Send a message to the connected Pebble to launch an application identified by a UUID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

customizeWatchApp

public static void customizeWatchApp(android.content.Context context,
                                     Constants.PebbleAppType appType,
                                     java.lang.String name,
                                     android.graphics.Bitmap icon)
                              throws java.lang.IllegalArgumentException

Send a message to the connected Pebble to "customize" a built-in PebbleKit watch-app. This is intended to allow third-party Android applications to apply custom branding (both name and icon) on the watch without needing to distribute a complete watch-app.

Parameters:

context - The context used to send the broadcast. (Protip: pass in the ApplicationContext here.)

appType - The watch-app to be configured. Options are either

name - The custom name to be applied to the watch-app. Names must be less than 32 characters in length.

icon - The custom icon to be applied to the watch-app. Icons must be black-and-white bitmaps no larger than 32px in either dimension.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified name or icon are invalid. Constants.PebbleAppType.SPORTS or Constants.PebbleAppType.GOLF.

isWatchConnected

public static boolean isWatchConnected(android.content.Context context)

Synchronously query the Pebble application to see if an active Bluetooth connection to a watch currently exists.

Parameters:

context - The Android context used to perform the query. Protip: You probably want to use your ApplicationContext here.

Returns:

true if an active connection to the watch currently exists, otherwise false. This method will also return false if the Pebble application is not installed on the user's handset.

areAppMessagesSupported

public static boolean areAppMessagesSupported(android.content.Context context)

Synchronously query the Pebble application to see if the connected watch is running a firmware version that supports PebbleKit messages.

Parameters:

context - The Android context used to perform the query. Protip: You probably want to use your ApplicationContext here.

Returns:

true if the watch supports PebbleKit messages, otherwise false. This method will always return false if no Pebble is currently connected to the handset.

getWatchFWVersion

public static PebbleKit.FirmwareVersionInfo getWatchFWVersion(android.content.Context context)

Get the version information of the firmware running on a connected watch.

Parameters:

context - The Android context used to perform the query. Protip: You probably want to use your ApplicationContext here.

Returns:

null if the watch is disconnected or we can't get the version. Otherwise, a FirmwareVersionObject containing info on the watch FW version

isDataLoggingSupported

public static boolean isDataLoggingSupported(android.content.Context context)

Synchronously query the Pebble application to see if the connected watch is running a firmware version that supports PebbleKit data logging.

Parameters:

context - The Android context used to perform the query. Protip: You probably want to use your ApplicationContext here.

Returns:

true if the watch supports PebbleKit messages, otherwise false. This method will always return false if no Pebble is currently connected to the handset.

startAppOnPebble

public static void startAppOnPebble(android.content.Context context,
                                    java.util.UUID watchappUuid)
                             throws java.lang.IllegalArgumentException

Send a message to the connected Pebble to launch an application identified by a UUID. If another application is currently running it will be terminated and the new application will be brought to the foreground.

Parameters:

context - The context used to send the broadcast.

watchappUuid - A UUID uniquely identifying the target application. UUIDs for the stock PebbleKit applications are available in Constants.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified UUID is invalid.

closeAppOnPebble

public static void closeAppOnPebble(android.content.Context context,
                                    java.util.UUID watchappUuid)
                             throws java.lang.IllegalArgumentException

Send a message to the connected Pebble to close an application identified by a UUID. If this application is not currently running, the message is ignored.

Parameters:

context - The context used to send the broadcast.

watchappUuid - A UUID uniquely identifying the target application. UUIDs for the stock kit applications are available in Constants.

Throws:

java.lang.IllegalArgumentException - Thrown if the specified UUID is invalid.

sendDataToPebble

public static void sendDataToPebble(android.content.Context context,
                                    java.util.UUID watchappUuid,
                                    PebbleDictionary data)
                             throws java.lang.IllegalArgumentException

Send one-or-more key-value pairs to the watch-app identified by the provided UUID. This is the primary method for sending data from the phone to a connected Pebble. The watch-app and phone-app must agree of the set and type of key-value pairs being exchanged. Type mismatches or missing keys will cause errors on the receiver's end.

Parameters:

context - The context used to send the broadcast.

watchappUuid - A UUID uniquely identifying the target application. UUIDs for the stock kit applications are available in Constants.

data - A dictionary containing one-or-more key-value pairs. For more information about the types of data that can be stored, see PebbleDictionary.

Throws:

java.lang.IllegalArgumentException - Thrown in the specified PebbleDictionary or UUID is invalid.

sendDataToPebbleWithTransactionId

public static void sendDataToPebbleWithTransactionId(android.content.Context context,
                                                     java.util.UUID watchappUuid,
                                                     PebbleDictionary data,
                                                     int transactionId)
                                              throws java.lang.IllegalArgumentException

Send one-or-more key-value pairs to the watch-app identified by the provided UUID. The watch-app and phone-app must agree of the set and type of key-value pairs being exchanged. Type mismatches or missing keys will cause errors on the receiver's end.

Parameters:

context - The context used to send the broadcast.

watchappUuid - A UUID uniquely identifying the target application. UUIDs for the stock kit applications are available in Constants.

data - A dictionary containing one-or-more key-value pairs. For more information about the types of data that can be stored, see PebbleDictionary.

transactionId - An integer uniquely identifying the transaction. This can be used to correlate messages sent to the Pebble and ACK/NACKs received from the Pebble.

Throws:

java.lang.IllegalArgumentException - Thrown in the specified PebbleDictionary or UUID is invalid.

sendAckToPebble

public static void sendAckToPebble(android.content.Context context,
                                   int transactionId)
                            throws java.lang.IllegalArgumentException

Send a message to the connected watch acknowledging the receipt of a PebbleDictionary. To avoid protocol timeouts on the watch, applications must ACK or NACK all received messages.

Parameters:

context - The context used to send the broadcast.

transactionId - The transaction id of the message in which the data was received. Valid transaction IDs are between (0, 255).

Throws:

java.lang.IllegalArgumentException - Thrown if an invalid transaction id is specified.

sendNackToPebble

public static void sendNackToPebble(android.content.Context context,
                                    int transactionId)
                             throws java.lang.IllegalArgumentException

Send a message to the connected watch that the previously sent PebbleDictionary was not received successfully. To avoid protocol timeouts on the watch, applications must ACK or NACK all received messages.

Parameters:

context - The context used to send the broadcast.

transactionId - The transaction id of the message in which the data was received. Valid transaction IDs are between (0, 255).

Throws:

java.lang.IllegalArgumentException - Thrown if an invalid transaction id is specified.

registerPebbleConnectedReceiver

public static android.content.BroadcastReceiver registerPebbleConnectedReceiver(android.content.Context context,
                                                                                android.content.BroadcastReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'CONNECTED' intent. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_PEBBLE_CONNECTED

registerPebbleDisconnectedReceiver

public static android.content.BroadcastReceiver registerPebbleDisconnectedReceiver(android.content.Context context,
                                                                                   android.content.BroadcastReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'DISCONNECTED' intent. Go avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_PEBBLE_DISCONNECTED

registerReceivedDataHandler

public static android.content.BroadcastReceiver registerReceivedDataHandler(android.content.Context context,
                                                                            PebbleKit.PebbleDataReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE' intent. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_APP_RECEIVE

registerReceivedAckHandler

public static android.content.BroadcastReceiver registerReceivedAckHandler(android.content.Context context,
                                                                           PebbleKit.PebbleAckReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE_ACK' intent. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_APP_RECEIVE_ACK

registerReceivedNackHandler

public static android.content.BroadcastReceiver registerReceivedNackHandler(android.content.Context context,
                                                                            PebbleKit.PebbleNackReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'RECEIVE_NACK' intent. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_APP_RECEIVE_NACK

registerDataLogReceiver

public static android.content.BroadcastReceiver registerDataLogReceiver(android.content.Context context,
                                                                        PebbleKit.PebbleDataLogReceiver receiver)

A convenience function to assist in programatically registering a broadcast receiver for the 'DATA_AVAILABLE' intent. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

receiver - The receiver to be registered.

Returns:

The registered receiver.

See Also:

Constants.INTENT_DL_RECEIVE_DATA

requestDataLogsForApp

public static void requestDataLogsForApp(android.content.Context context,
                                         java.util.UUID appUuid)

A convenience function to emit an intent to pebble.apk to request the data logs for a particular app. If data is available, pebble.apk will advertise the data via 'INTENT_DL_RECEIVE_DATA' intents. To avoid leaking memory, activities registering BroadcastReceivers must unregister them in the Activity's Activity.onPause() method.

Parameters:

context - The context in which to register the BroadcastReceiver.

appUuid - The app for which to request data logs.

See Also:

Constants.INTENT_DL_RECEIVE_DATA, Constants.INTENT_DL_REQUEST_DATA