Google Glass Development Kit

Developer Zone

Glass Development Kit

The Glass Development Kit (GDK) is an add-on to the Android SDK that lets you build Glassware that runs directly on Glass.

Unlike the Mirror API, Glassware built with the GDK runs on Glass itself, allowing access to low-level hardware features.

For Android experts

If you're comfortable with Android, here's all you need to know:

Get the Android 4.0.3 (API 15) SDK and Glass Development Kit Sneak Peek add-on from the Android SDK Manager.

On Glass, turn on USB debugging (Settings > Device Info > Turn on debug).Import some GDK samples with the File > New Project > Android Sample Project menu.

When you're ready to create a project for your own Glassware, use these settings:Minimum and Target SDK Versions: 15 (There is only one Glass version, so minimum and target SDK are the same.)Compile with: Glass Development Kit Sneak PeekTheme: None (This allows the Glass theme to be applied.)

Head on over to the developer guides for more learning.

For Android beginnersWe recommend starting with the Building Your First App training class at the Android developers site and then building a few simple Android apps before building GDK Glassware.

Setting up the development environment

We recommend installing the ADT Bundle for easier development. The rest of these steps assume you have this installed.

Click Window > Android SDK Manager.

Install the SDK Platform and Google GDK Sneak Peek for Android 4.0.3 (API 15).

Everything else is optional.

On Glass, go to Settings > Device Info > Turn on debug to enable adb, which allows your development system to communicate with Glass.

Connect Glass to your development system and confirm that it's detected by clicking Window > Open Perspective > DDMS and verifying Glass appears in the Devices tab.

GDK Sneak Peek

User interfaceThe GDK offers different options to build the right UI for your Glassware. This section goes over what they are, when to use each, and how to build them.

Integrate rich content into the timelineLive cards display frequently updated information to the left of the Glass clock. Options range from simple text and images to full-blown 3D graphics.

Settings Present/Future Home Past

When to use live cards

When using live cards, the timeline still consumes some user input, so live cards don't support as many types of input features as an immersion. For example, swiping forward or backward on a live card navigates the timeline instead acting on the live card itself.

However, live cards have access to many of the same features an immersion does, such as sensor or GPS data. In general, use live cards when:

You want a limited window into an immersion. Live cards can display summary information and let users launch immersions if they want to do more.

You require a good amount of control over how to display information but don't require much input capabilities.Your information needs to be in the live section of the timeline.

When to use immersions

Glass displays immersions outside the context of the timeline, so they do not have the user input constraints that cards do. However, in most cases, live cards or static cards offer enough features and are easier to build. Only use immersions if you require extra control.

In general, use immersions when:

•You want to take precedence over the timeline and display a UI outside of its context.•You want to process all user input.•You require prolonged user attention, such as for a game.

Appears in the timeline Access to user input Control over user

interface Major uses

Static Cards Yes No No, must be in the form of a Card

Information display without user interaction

Live Cards Yes Yes, but timeline takes precedence Yes, no restrictions

Rich and live content with low user interaction

Immersions No Yes, no restrictions Yes, no restrictionsRich and live content with high user interaction

Choose an option

You can use one or all of the UI options in your Glassware. The following table lays out your options and the benefits of each.

Glass theme and UI widgets

The GDK provides a common theme and widgets to let you build UIs that look consistent with the rest of the Glass platform.

Applying the Glass themeGlass applies a standard theme to your Glassware, so it stays consistent with the rest of the user interface. The theme has the following characteristics:

•Uses Roboto typeface•Displays activities full-screen with no status bar or action bar•Applies solid, black background

To apply the Glass theme, don't declare a theme in your Android Manifest.

<resources>    <style name="CustomTheme" parent="@android:style/Theme.DeviceDefault">        <!-- Theme customization goes here. -->    </style></resources>

Creating Glass-styled cards

The Card class creates well-formed cards given a set of properties. You can use a card wherever you can a view.

A Card has the following properties:•Main body text•Left-aligned footer•Right-aligned footer for a timestamp•One image for the card's background or multiple images displayed on the left side of the card

To create and use a Card object:

1. Set properties of the card.2. Call Card.toView() to convert the card to an Android view.3. Use the view in your activities, layouts, or in a CardScrollView.

// Create a card with some simple text and a footer.Card card1 = new Card(context);card1.setText("This card has a footer.");card1.setInfo("I'm the footer!");View card1View = card1.toView();

// Create a card with a full-screen background image.Card card2 = new Card(context);card2.setText("This card has a puppy background image.");card2.setInfo("How can you resist?");card2.setFullScreenImages(true);card2.addImage(R.drawable.puppy_bg);View card2View = card2.toView();

// Create a card with multiple images displayed as a mosaic.Card card3 = new Card(context);card3.setText("This card has a mosaic of puppies.");card3.setInfo("Aren't they precious?");card3.addImage(R.drawable.puppy_small_1);card3.addImage(R.drawable.puppy_small_2);card3.addImage(R.drawable.puppy_small_3);View card3View = card3.toView();

Creating scrolling cards in activities

The Glass display and touchpad are great for displaying swipable cards, like in the Glass timeline. If you're building an activity, you can create the same type of effect with the CardScrollView widget.

Implement a CardScrollAdapter to supply cards to the CardScrollView. You can build a standard view hierarchy yourself or use the Card class.

Create a CardScrollView that uses the CardScrollAdapter as a supply for cards.Set your activity's content view to be the CardScrollView or display the CardScrollView in a layout.

public class CardScrollActivity extends Activity {

    private List<Card> mCards;    private CardScrollView mCardScrollView;

    @Override    protected void onCreate(Bundle savedInstanceState) {      super.onCreate(savedInstanceState);

      createCards();

      mCardScrollView = new CardScrollView(this);      ExampleCardScrollAdapter adapter = new ExampleCardScrollAdapter();      mCardScrollView.setAdapter(adapter);      mCardScrollView.activate();      setContentView(mCardScrollView);    }

private void createCards() { mCards = new ArrayList<Card>();

Card card;

card = new Card(this); card.setText("This card has a footer."); card.setInfo("I'm the footer!"); mCards.add(card);

card = new Card(this); card.setText("This card has a puppy background image."); card.setInfo("How can you resist?"); card.setFullScreenImages(true); card.addImage(R.drawable.puppy_bg); mCards.add(card);

card = new Card(this); card.setText("This card has a mosaic of puppies."); card.setInfo("Aren't they precious?"); card.addImage(R.drawable.puppy_small_1); card.addImage(R.drawable.puppy_small_2); card.addImage(R.drawable.puppy_small_3); mCards.add(card); }

private class ExampleCardScrollAdapter extends CardScrollAdapter { @Override public int findIdPosition(Object id) { return -1; }

@Override public int findItemPosition(Object item) { return mCards.indexOf(item); }

@Override public int getCount() { return mCards.size(); }

@Override public Object getItem(int position) { return mCards.get(position); }

@Override public View getView(int position, View convertView, ViewGroup parent) { return mCards.get(position).toView(); }}

Live Cards

Live cards appear in the present and future section of the timeline and display information that is relevant at the current time.

You can render live cards with low frequency, which updates the card once every few seconds, or with high frequency, which updates the card many times a second.

Live card architectureLive cards require a long running context to own them for the entire time that they are visible, so manage them in a background service.

You can then publish a live card as soon as the service starts or in response to other events that the service monitors.

When the live card is no longer relevant, destroy the service to stop rendering.

Low-Frequency Rendering

Low-frequency rendering is limited to a small set of Android views and can only update the display once every few seconds.

It's a simple way to create live cards with simple content that doesn't require constant rendering.

High Frequency Rendering

High frequency rendering gives you access to most of the Android rendering options.It's more involved than low-frequency rendering, but gives you more features.

Creating low-frequency live cards

Low frequency rendering requires a UI supplied by a RemoteView. that supports the following subset of Android layouts and views:

FrameLayoutLinearLayoutRelativeLayoutGridLayoutAdapterViewFlipperAnalogClockButtonChronometerGridViewImageButtonImageViewListViewProgressBarStackViewTextViewViewFlipper

Use low frequency rendering when:

You only require the standard Android view APIs and not more advanced rendering.You only require relatively infrequent updates (a few seconds between refreshes).

Keep in mind:

Live cards must always have a PendingIntent declared with setAction() for the timeline to publish the card.

To make changes to a card after publishing, call setViews() on the card with the updated layout before publishing again.

// Cached instance of the LiveCard created by the publishCard() method.private LiveCard mLiveCard;

private void publishCard(Context context) { if (mLiveCard == null) { String cardId = "my_card"; TimelineManager tm = TimelineManager.from(context); mLiveCard = tm.getLiveCard(cardId);

mLiveCard.setViews(new RemoteViews(context.getPackageName(), R.layout.card_text)); Intent intent = new Intent(context, EntryActivity.class); mLiveCard.setAction(PendingIntent.getActivity(context, 0, intent, 0)); mLiveCard.publish(); } else { // Card is already published. return; }}

private void unpublishCard(Context context) { if (mLiveCard != null) { mLiveCard.unpublish(); mLiveCard = null; }}

Creating high-frequency live cards

High frequency rendering lets you draw directly on the backing Surface of the live card.

This rendering is more flexible and lets you use all of Android's graphics options.

Use high frequency rendering when:

You need to update the live card frequently (many times a second).You need flexibility in what you can render. RemoteView only supports rendering a layout, but direct rendering let you use any graphics option in the Android framework.

Keep in mind:

You should create a background service to render on the live card's surface.Use the surfaceCreated() and surfaceDestroyed() methods to start and stop your rendering logic when the card is displayed or hidden.The surface holder's callback methods are not invoked on the main UI thread.Live cards must always have a PendingIntent declared with setAction()

Displaying live cards immediately

By default, Glass publishes live cards to the timeline silently. Users have to navigate to the active section of the timeline to see it.

If you want Glass to automatically jump to the live card after publishing:

Call LiveCard.setNonSilent(true).Call LiveCard.publish().

LiveCard liveCard;// ...liveCard.setNonSilent(true);liveCard.publish();

This is often useful when the main user interface is a live card and not an activity.

Creating and displaying a menu

To display a menu for a live card, you create an activity to display the menu for the card and to handle user selection events.

The activity can then do things such as stop the rendering of the live card or start other activities or services to do other tasks.

Creating menu resources

Creating menu resources is the same as on the Android platform, but follow these guidelines for Glass:

For each menu item, provide a 50 × 50 pixel menu item icon. The menu icon must be white in color on a transparent background. See the Glass menu item icons for an example or to download them for your own use.

Use a short name that describes the action and is in title case. An imperative verb works well (for example, Share or Reply all).

Glass does not display live cards without a menu item. At the very least, provide a Stop menu item, so users can remove the live card from the timeline.

<menu xmlns:android="http://schemas.android.com/apk/res/android">    <item   android:id="@+id/menu_item_1"   android:title="@string/Menu_Item_1"       <!-- must have "Stop" menu item -->   android:icon="@drawable/menu_item_1_icon" />   <!-- white on transparent icon --></menu>

Creating an activity to handle menu callbacks

You must define a menu activity that your live card invokes when users tap on it.

Override the following Activity callback methods to properly create, show, and dismiss menus in your menu activity:

1. onCreateOptionsMenu() inflates the XML menu resource.2. onResume() shows the menu when the activity is in focus.3. onPrepareOptionsMenu() shows or hides menu items if required. For example, you

can show different menu items based on what users are doing. For example, you can show different menu items based on some contextual data.

4. onOptionsItemSelected() handles user selection.5. onOptionsMenuClosed() to finish the activity, so that it no longer appears over the live

card. You must finish the activity here so it is properly finished when the menu is closed by a selection or by a swipe down.

Making the menu activity transparentTo have the menu activity overlay over the live card:Create a res/values/styles.xml file and declare a style that makes the activity's background transparent:

<resources>    <style name="MenuTheme" parent="@android:style/Theme.DeviceDefault">        <item name="android:windowBackground">@android:color/transparent</item>        <item name="android:colorBackgroundCacheHint">@null</item>        <item name="android:windowIsTranslucent">true</item>        <item name="android:windowAnimationStyle">@null</item>    </style></resources>

In your AndroidManifest.xml file, assign the theme to the menu activity:

<?xml version="1.0" encoding="utf-8"?>    <manifest ... >      ...        <application ... >            ...            <activity                android:name=".MenuActivity"                android:theme="@style/MenuTheme"                ...>            </activity>        </application>

    </manifest>

Displaying the menu

Provide a PendingIntent for the card's action using setAction(). The pending intent starts the menu activity when users tap on the card: Intent menuIntent = new Intent(this, MenuActivity.class); mLiveCard.setAction(PendingIntent.getActivity(this, 0, menuIntent, 0)); mLiveCard.publish();

Menu utilities

A few helper methods are available to modify the look and behavior of menus. See MenuUtils for more information.

Immersions

Immersions give you more ways to consume user input and create user interfaces. This allows you to create the most custom experience, but involves the most work.

Creating immersions

•You create immersions using standard Android activities, but keep the following in mind when writing activities for Glass:•Design your UIs for a 640 × 360 pixel screen.•Design interactions that make sense on Glass instead of porting over activities from other Android devices.•Don't rely on complex touch gestures or UI patterns.•Swiping down always goes back in the activity stack until users reach the timeline. It should function much like the Android back button on smartphones and tablets.•Create a 50 × 50 pixel icon and specify it for the android:icon attribute of the <activity> element in your Android manifest. Also specify text for android:label. This allows a voice or touch menu item that is associated with multiple Glassware to show your Glassware's name and icon as an option.

Touch Gestures

Accessing raw data from the Glass touchpad is possible with the Android SDK. However, the GDK provides a gesture detector designed for the Glass touchpad that automatically detects common gestures on Glass, including tapping, swiping, and scrolling.

Detecting activity-level gestures

Detecting gestures at the activity level is appropriate when you don't care what part of your UI has focus. For instance, if you want to bring up a menu whenever a user taps the touchpad.

The following example:Creates a GestureDetector that implements listeners to process recognized gestures.Overrides the activity's onGenericMotionEvent() method to pass the motion events to the gesture detector's onMotionEvent() method.

When a motion event occurs, the system passes it to the gesture detector. If recognized, the gesture detector notifies the appropriate listener to process the event.

Detecting view-level gestures

Detecting gestures at the view level is appropriate when you want to do different things depending on what view has focus.

The following example:Creates a custom view that overrides the dispatchGenericFocusedEvent() method. When a motion event occurs, this method passes the motion event to the gesture detector.Declares the view to be focusable so that it detects events when it has focus.

Creates a GestureDetector that implements listeners to process recognized gestures.When the gesture detector recognizes a motion while the view is in focus, the gesture detector calls the appropriate listener.

Voice InputVoice is an integral part in a hands-free experience for users. Glass lets you declare voice triggers to launch your Glassware from the ok glass voice menu.

Launching GlasswareTo add a trigger to the ok glass voice main menu:

Declare a string value in res/values/strings.xml that defines the name of your voice trigger. Optionally declare a voice prompt to display the speech recognition activity before launching your Glassware.

<?xml version="1.0" encoding="utf-8"?><resources>    <string name="glass_voice_trigger">take note</string>    <string name="glass_voice_prompt">tell me what's on your mind</string></resources>

Create an XML resource for the voice trigger in res/xml/<my_voice_trigger>.xml that uses the string value as the keyword.

<?xml version="1.0" encoding="utf-8"?><trigger keyword="@string/glass_voice_trigger">    <input prompt="@string/glass_voice_prompt" /></trigger>

Register an intent filter using the com.google.android.glass.action.VOICE_TRIGGER action in your Android manifest. The intent filter starts your activity if it detects users speaking your voice trigger.

<?xml version="1.0" encoding="utf-8"?><application ...>    <activity ...>        <intent-filter>            <action                android:name="com.google.android.glass.action.VOICE_TRIGGER" />        </intent-filter>        <meta-data android:name="com.google.android.glass.VoiceTrigger"            android:resource="@xml/my_voice_trigger" />    </activity>    // ...</application>

If your voice trigger used a voice prompt and starts an activity, obtain any transcribed text with the following code (such as in onResume()):

ArrayList<String> voiceResults = getIntent().getExtras()        .getStringArrayList(RecognizerIntent.EXTRA_RESULTS);

If the voice trigger starts a service, the intent extra is available in the onStartCommand() callback:

@Overridepublic int onStartCommand(Intent intent, int flags, int startId) {    ArrayList<String> voiceResults = intent.getExtras()            .getStringArrayList(RecognizerIntent.EXTRA_RESULTS);    // ...}

Setting constraints

If you need one or all of the following features to launch your Glassware, specify them in the res/xml/<my_voice_trigger>.xml resource. If the features are not available, Glass disables the voice trigger:

cameranetworkmicrophone

<trigger keyword="@string/glass_voice_trigger">    <constraints        camera="true"        network="true" /></trigger>

Starting the speech recognition activity

The speech recognition activity waits for users to speak and returns the trascribed text after they are done. To start the activity:

Call startActivityForResult() with the ACTION_RECOGNIZE_SPEECH intent. The following intent extras are supported when starting the activity:

EXTRA_PROMPTEXTRA_RESULTS_PENDINGINTENTEXTRA_RESULTS_PENDINGINTENT_BUNDLE

Override the onActivityResult() callback to receive the transcribed text from the EXTRA_RESULTS intent extra. This callback is called when users finish speaking.private static final int SPEECH_REQUEST = 0;

private void displaySpeechRecognizer() {    Intent intent = new Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH);    startActivityForResult(intent, SPEECH_REQUEST);}

@Overrideprotected void onActivityResult(int requestCode, int resultCode,        Intent data) {    if (requestCode == SPEECH_REQUEST && resultCode == RESULT_OK) {        List<String> results = data.getStringArrayListExtra(                RecognizerIntent.EXTRA_RESULTS);        String spokenText = results.get(0);        // Do something with spokenText.    }    super.onActivityResult(requestCode, resultCode, data);}

Sensors

The following sensors are supported on Glass:

TYPE_ACCELEROMETERTYPE_GRAVITYTYPE_GYROSCOPETYPE_LIGHTTYPE_LINEAR_ACCELERATIONTYPE_MAGNETIC_FIELDTYPE_ORIENTATION (deprecated)TYPE_ROTATION_VECTOR

The following sensors are not supported:

TYPE_AMBIENT_TEMPERATURETYPE_PRESSURETYPE_PROXIMITYTYPE_RELATIVE_HUMIDITYTYPE_TEMPERATURE

Here's some tips when using sensors on Glass:

The Glass sensor coordinate system is shown below relative to the Glass display. For more information, see sensor coordinate system.

The accelerometer, gyroscope, and magnetometer are located on the optics pod of the Glass device, which users rotate to align the device with their sight. You cannot measure the angle of the optics pod directly, so be aware of this when using angles from these sensors for applications such as compass heading.

To preserve battery life, only listen to sensors when you need them. For example, if your Glassware uses a Service to render a LiveCard and you only need the sensors when the live card is visible, use the LiveCard surface callback methods to start and stop listening to the sensors.

Sensor event callbacks run on the UI thread, so process events and return as quickly as possible. Consider pushing sensor events into a queue and using a background thread to handle them if your processing takes too long.50 Hz is often a sufficient sampling rate for tracking head motion.

CameraYou can use the Glass camera to capture images and video and to also display the camera's preview stream for a variety of different use cases.

Overview

You have two options for capturing images or video:

Calling the built-in camera activity with startActivityForResult(). Use this option when possible.

Building your own logic with the Android Camera API. Follow these guidelines if you are using this method:

Take a picture on a camera button click and a video on a long click, just like Glass does.Indicate to the user whether a picture was taken or a video was recorded.Keep the screen on during capture.

Sharing the camera with the Glass system

If your Glassware uses the Android APIs to access the camera, temporarily release the camera when possible if users press the hardware camera button.

Override the onKeyDown() method in your activity and intercept KEYCODE_CAMERA to handle camera button presses.

Release the camera and return false to indicate that you did not consume the event so that the built-in Glass camera starts.

Note: If you return true from onKeyDown(), your activity consumes the event and the Glass camera doesn't start. Do this only if there is no way to interrupt your activity's use of the camera (for example, if you are capturing continuous video).

After the image or video capture takes place, Glass returns to your activity, where you can reclaim the camera in onResume().

@Overridepublic boolean onKeyDown(int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_CAMERA) { // Stop the preview and release the camera. // Execute your logic as quickly as possible // so the capture happens quickly. return false; } else { return super.onKeyDown(keyCode, event); }}

@Overrideprotected void onResume() { super.onResume(); // Re-acquire the camera and start the preview.}

Thanks