Package com.vuzix.ultralite

Interface UltraliteSDK

public interface UltraliteSDK
Main entry point for interacting with Ultralite glasses. Use UltraliteSDK.get(Context) to obtain an instance.

The SDK may not be available for immediate use. It's also possible the SDK will become unavailable at some point in the future. Use isAvailable() or getAvailable() to monitor the state of the SDK. SDK methods will have no effect if called when the SDK is unavailable.

An app that wishes to control the glasses must use requestControl(). If there are glasses connected, this request should normally be granted. You should also monitor the control status with either isControlledByMe() or getControlledByMe(). When another app requests control, your app will be notified that control has been lost. You can also lose control if the connection is broken or if the glasses are unlinked. When control is lost, assume all of your configuration such as layout and canvas state is gone. The next time you gain control, you will have to setup this configuration again.

Once control has been successfully requested, you can use methods such as setLayout(), sendText() or any of the Canvas methods. Other methods can be called without having control.
Since:
1.0.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    UltraliteSDK.AcknowledgedCallback
    Gets notified when requestAcknowledgement has been processed.
    static interface 
    UltraliteSDK.Canvas
    Canvas is used to perform direct drawing operations to the Ultralite display.
    static interface 
    UltraliteSDK.ScrollingTextView
    ScrollingTextView is used to perform optimized text drawing to the Ultralite display.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addEventListener(EventListener listener)
    Adds an event listener to be notified of interactions with the glasses.
    void
    clearFont()
    Switch back to the default built-in font.
    void
    clearNotification(String key)
    Clears a previously sent notification.
    static UltraliteSDK
    get(android.content.Context context)
    Obtains an instance of the UltraliteSDK.
    androidx.lifecycle.LiveData<Boolean>
    getAvailable()
    Returns the SDK availability as a LiveData that can be observed.
    int
    getBatteryLevel()
    Returns the current battery level of the glasses or zero if not connected.
    androidx.lifecycle.LiveData<BatteryStatus>
    getBatteryStatus()
    Returns the battery status as a LiveData that can be observed.
    UltraliteSDK.Canvas
    getCanvas()
    Returns a Canvas object that can be used to draw directly to the Ultralite screen.
    androidx.lifecycle.LiveData<Boolean>
    getConnected()
    Returns the connection status as a LiveData that can be observed.
    androidx.lifecycle.LiveData<Boolean>
    getControlled()
    Returns glasses control status as a LiveData that can be observed.
    androidx.lifecycle.LiveData<Boolean>
    getControlledByMe()
    Returns this app's control status as a LiveData that can be observed.
    Layout
    getLayout()
    Get the current layout.
    androidx.lifecycle.LiveData<Boolean>
    getLinked()
    Returns the link status as a LiveData that can be observed.
    String
    getName()
    Returns the name of the linked pair of glasses.
    UltraliteSDK.ScrollingTextView
    getScrollingTextView()
    Returns a ScrollingTextView object that can be used to draw optimized text to the Ultralite screen.
    boolean
    isAvailable()
    Determines if the SDK is currently available for use.
    boolean
    isCharging()
    Returns true if the glasses are currently charging.
    boolean
    isConnected()
    Determines if glasses are currently connected.
    boolean
    isControlled()
    Determines if the glasses are being controlled by any app, including this one.
    boolean
    isControlledByMe()
    Determines if the glasses are being controlled by this app.
    boolean
    isLinked()
    Determines if this device is currently linked to a pair of glasses.
    void
    releaseControl()
    Releases control of the glasses.
    void
    removeEventListener(EventListener listener)
    Removes a previously added event listener.
    void
    requestAcknowledgement(UltraliteSDK.AcknowledgedCallback callback)
    Request to be notified when this message is received by the glasses.
    boolean
    requestControl()
    Requests control of the glasses.
    void
    screenOff()
    Explicitly turn the screen off.
    void
    screenOn()
    Explicitly turn the screen on.
    void
    sendIcon(LVGLImage icon)
    Sends an icon to the glasses.
    void
    sendNotification(String title, String message)
    Sends a notification to the glasses for display with a default notification icon.
    void
    sendNotification(String title, String message, LVGLImage icon)
    Sends a notification to the glasses for display with an optional icon.
    void
    sendNotification(String key, String title, String message, LVGLImage icon)
    Sends a notification to the glasses for display with an optional icon.
    void
    sendNotification(String key, String title, String message, String peekText, LVGLImage icon)
    Sends a notification to the glasses for display with an optional icon.
    void
    sendText(String text)
    Sends the specified text to the glasses for display.
    void
    sendText(String text, Icon icon)
    Sends the specified text and icon to the glasses for display.
    void
    setFont(String fontFamily, int style, int textSize)
    Sets the font used on the glasses.
    void
    setLayout(Layout layout, int timeout)
    Requests the specified layout and display timeout with a status bar displayed.
    void
    setLayout(Layout layout, int timeout, boolean hideStatusBar)
    Requests the specified layout, display timeout and hidden status bar if desired.
    void
    setLayout(Layout layout, int timeout, boolean hideStatusBar, boolean showTapAnimation, int maxNumTaps)
    Requests the specified layout, timeout and hidden status bar if desired.

  • Method Details

    • get

      static UltraliteSDK get(android.content.Context context)
      Obtains an instance of the UltraliteSDK.
      Parameters:
      context - a context
      Returns:
      an UltraliteSDK
      Throws:
      NullPointerException - if context is null
      Since:
      1.0.0

    • isAvailable

      boolean isAvailable()
      Determines if the SDK is currently available for use.
      Returns:
      true if the SDK is available, false otherwise.
      Since:
      1.0.0

    • getAvailable

      androidx.lifecycle.LiveData<Boolean> getAvailable()
      Returns the SDK availability as a LiveData that can be observed.
      Returns:
      a LiveData Boolean
      Since:
      1.0.0

    • isLinked

      boolean isLinked()
      Determines if this device is currently linked to a pair of glasses.
      Returns:
      true if linked, false otherwise
      Since:
      1.0.0

    • getLinked

      androidx.lifecycle.LiveData<Boolean> getLinked()
      Returns the link status as a LiveData that can be observed.
      Returns:
      a LiveData Boolean
      Since:
      1.0.0

    • getName

      String getName()
      Returns the name of the linked pair of glasses.
      Returns:
      the name of the glasses or null if this device is not linked to anything
      Since:
      1.0.0

    • isConnected

      boolean isConnected()
      Determines if glasses are currently connected.
      Returns:
      true if connected, false otherwise
      Since:
      1.0.0

    • getConnected

      androidx.lifecycle.LiveData<Boolean> getConnected()
      Returns the connection status as a LiveData that can be observed.
      Returns:
      a LiveData Boolean
      Since:
      1.0.0

    • getBatteryStatus

      androidx.lifecycle.LiveData<BatteryStatus> getBatteryStatus()
      Returns the battery status as a LiveData that can be observed. When not connected, the LiveData will contain null.
      Returns:
      a LiveData containing BatteryStatus
      Since:
      1.0.0

    • getBatteryLevel

      int getBatteryLevel()
      Returns the current battery level of the glasses or zero if not connected.
      Returns:
      the current battery level
      Since:
      1.0.0

    • isCharging

      boolean isCharging()
      Returns true if the glasses are currently charging. If not connected, false will be returned.
      Returns:
      true if the glasses are charging, false otherwise
      Since:
      1.0.0

    • isControlled

      boolean isControlled()
      Determines if the glasses are being controlled by any app, including this one.
      Returns:
      true if the glasses are currently being controlled, false otherwise
      Since:
      1.0.0

    • getControlled

      androidx.lifecycle.LiveData<Boolean> getControlled()
      Returns glasses control status as a LiveData that can be observed.
      Returns:
      a LiveData Boolean
      Since:
      1.0.0

    • isControlledByMe

      boolean isControlledByMe()
      Determines if the glasses are being controlled by this app.
      Returns:
      true if the glasses are currently being controlled, false otherwise
      Since:
      1.0.0

    • getControlledByMe

      androidx.lifecycle.LiveData<Boolean> getControlledByMe()
      Returns this app's control status as a LiveData that can be observed.
      Returns:
      a LiveData Boolean
      Since:
      1.0.0

    • requestControl

      boolean requestControl()
      Requests control of the glasses. This request will only be granted if the SDK is available, a pair of glasses are linked and they are currently connected. You should only request control of the glasses if you have a user-driven experience you need to display. For more passive user data, consider using notifications instead.
      Returns:
      true if control is gained, false otherwise
      Since:
      1.0.0

    • releaseControl

      void releaseControl()
      Releases control of the glasses. It's good practice to do this as soon as you are done with your user-driven experience. Some apps may wait to take control until they've seen another app has released control.
      Since:
      1.0.0

    • setLayout

      void setLayout(@NonNull Layout layout, int timeout)
      Requests the specified layout and display timeout with a status bar displayed. If control has not been requested successfully, this method call does nothing.

      You can request the display stay on forever by passing in zero for the timeout. This should only be done in very specific use cases as the display will use more power. Keep in mind, the user can always turn off the display with the power button.
      Parameters:
      layout - a Layout
      timeout - a display timeout value in seconds, use zero to keep the display on (must be greater than or equal to zero)
      Since:
      1.0.0

    • setLayout

      void setLayout(@NonNull Layout layout, int timeout, boolean hideStatusBar)
      Requests the specified layout, display timeout and hidden status bar if desired. If control has not been requested successfully, this method call does nothing.

      You can request the display stay on forever by passing in zero for the timeout. This should only be done in very specific use cases as the display will use more power. Keep in mind, the user can always turn off the display with the power button.
      Parameters:
      layout - a Layout
      timeout - a display timeout value in seconds, use zero to keep the display on (must be greater than or equal to zero)
      hideStatusBar - true to hide the status bar, false to show it (true only applies to CANVAS layout)
      Since:
      1.0.0

    • setLayout

      void setLayout(@NonNull Layout layout, int timeout, boolean hideStatusBar, boolean showTapAnimation, int maxNumTaps)
      Requests the specified layout, timeout and hidden status bar if desired. You can also customize the tap behavior. A max number of taps between 0-3 can be specified. Any other value will be treated like zero. Based on this value, the following behavior will be present:
      • 0 - No taps are reported. (default)
      • 1 - Only single taps are reported. This has the shortest delay from when the user taps until processing.
      • 2 - Single and double taps are reported. This has a medium delay from when the user taps until processing.
      • 3 - Single, double, and triple taps are reported. This has the longest delay from when the user taps until processing.
      If control has not been requested successfully, this method call does nothing.

      You can request the display stay on forever by passing in zero for the timeout. This should only be done in very specific use cases as the display will use more power. Keep in mind, the user can always turn off the display with the power button.
      Parameters:
      layout - a Layout
      timeout - a display timeout value in seconds, use zero to keep the display on (must be greater than or equal to zero)
      hideStatusBar - true to hide the status bar, false to show it (true only applies to CANVAS layout)
      showTapAnimation - whether the tap animation is shown on the glasses.
      maxNumTaps - the max number of taps as described above
      Since:
      1.1.0

    • getLayout

      @Nullable Layout getLayout()
      Get the current layout.
      Returns:
      Currently active Layout
      Since:
      1.4.0

    • setFont

      void setFont(String fontFamily, int style, int textSize)
      Sets the font used on the glasses. Font will remain in effect until control is released. If control has not been requested successfully, this method call does nothing.
      Parameters:
      fontFamily - the desired font family of a built-in system font as defined by Typeface.create. If null the default font will be used.
      style - the desired style as defined by Typeface.create
      textSize - the desired text size (in pixel units, greater than zero)
      Since:
      1.1.0
      See Also:

    • clearFont

      void clearFont()
      Switch back to the default built-in font. If control has not been requested successfully, this method call does nothing.
      Since:
      1.1.0

    • sendText

      void sendText(@NonNull String text)
      Sends the specified text to the glasses for display. Make sure you call setLayout() first and do not choose DEFAULT or CANVAS. If control has not been requested successfully, this method call does nothing.
      Parameters:
      text - the text to display
      Since:
      1.0.0

    • sendText

      void sendText(@NonNull String text, @NonNull Icon icon)
      Sends the specified text and icon to the glasses for display. Make sure you call setLayout() first and do not choose DEFAULT or CANVAS. If control has not been requested successfully, this method call does nothing.
      Parameters:
      text - the text to display
      icon - the icon to display, only used for navigation layouts, ignored otherwise
      Since:
      1.0.0

    • sendIcon

      void sendIcon(@NonNull LVGLImage icon)
      Sends an icon to the glasses. Once sent, the icon can be used by specifying Icon.CUSTOM in sendText(). If control has not been requested successfully, this method call does nothing.
      Parameters:
      icon - the icon as in LVGLImage format
      Since:
      1.0.0

    • sendNotification

      void sendNotification(@NonNull String title, @NonNull String message)
      Sends a notification to the glasses for display with a default notification icon. This method does not require glasses control. If not connected, this method call does nothing.
      Parameters:
      title - the title of the notification
      message - the message contents of the notification
      Since:
      1.0.0

    • sendNotification

      void sendNotification(@NonNull String title, @NonNull String message, @Nullable LVGLImage icon)
      Sends a notification to the glasses for display with an optional icon. If icon is null, a default icon will be displayed. This method does not require glasses control. If not connected, this method call does nothing.

      Note: the notification icon may be ignored if the title and message have too many non-standard characters for which a custom font needs to be compiled.
      Parameters:
      title - the title of the notification
      message - the message contents of the notification
      icon - the notification icon to display as an LVGLImage, can be null
      Since:
      1.0.0

    • sendNotification

      void sendNotification(@Nullable String key, @NonNull String title, @NonNull String message, @Nullable LVGLImage icon)
      Sends a notification to the glasses for display with an optional icon. If icon is null, a default icon will be displayed. If a non-null key is provided, the notification can be updated or cleared later on. If you don't care about updating or clearing later on, pass in null for the key. If not connected, this method call does nothing.

      Note: the notification icon may be ignored if the title and message have too many non-standard characters for which a custom font needs to be compiled.
      Parameters:
      key - a unique key that can be used to update or clear the notification
      title - the title of the notification
      message - the message contents of the notification
      icon - the notification icon to display as an LVGLImage, can be null
      Since:
      1.2.0

    • sendNotification

      void sendNotification(@Nullable String key, @NonNull String title, @NonNull String message, @Nullable String peekText, @Nullable LVGLImage icon)
      Sends a notification to the glasses for display with an optional icon. If icon is null, a default icon will be displayed. If a non-null key is provided, the notification can be updated or cleared later on. If you don't care about updating or clearing later on, pass in null for the key. If not connected, this method call does nothing.

      Note: the notification icon may be ignored if the title and message have too many non-standard characters for which a custom font needs to be compiled.
      Parameters:
      key - (optional) unique key that can be used to update or clear the notification
      title - the title of the notification
      message - the message contents of the notification
      peekText - (optional) Single-line title/body displayed when the message peeks instead of showing full-screen. If omitted, the title will be displayed.
      icon - the notification icon to display as an LVGLImage, can be null
      Since:
      1.5.0

    • clearNotification

      void clearNotification(@NonNull String key)
      Clears a previously sent notification. It's possible the notification is no longer displaying, in which case this method does nothing. If not connected, this method call does nothing.
      Parameters:
      key - the unique key for a previously sent notification
      Since:
      1.2.0

    • screenOn

      void screenOn()
      Explicitly turn the screen on. If control has not been requested successfully, this method call does nothing.
      Since:
      1.2.0

    • screenOff

      void screenOff()
      Explicitly turn the screen off. If control has not been requested successfully, this method call does nothing.
      Since:
      1.2.0

    • addEventListener

      void addEventListener(EventListener listener)
      Adds an event listener to be notified of interactions with the glasses.
      Parameters:
      listener - an EventListener
      Since:
      1.0.0

    • removeEventListener

      void removeEventListener(EventListener listener)
      Removes a previously added event listener.
      Parameters:
      listener - an EventListener
      Since:
      1.0.0

    • requestAcknowledgement

      void requestAcknowledgement(UltraliteSDK.AcknowledgedCallback callback)
      Request to be notified when this message is received by the glasses. This allows synchronizing the phone logic with the glasses processing.
      Parameters:
      callback - callback to be notified when the commit is complete
      Since:
      1.3.0

    • getCanvas

      UltraliteSDK.Canvas getCanvas()
      Returns a Canvas object that can be used to draw directly to the Ultralite screen. To use a Canvas, you must set the layout to CANVAS. This method does not require glasses control, but the methods on Canvas do.
      Returns:
      a Canvas object
      Since:
      1.0.0

    • getScrollingTextView

      UltraliteSDK.ScrollingTextView getScrollingTextView()
      Returns a ScrollingTextView object that can be used to draw optimized text to the Ultralite screen. To use a ScrollingTextView, you must set the layout to SCROLL. This method does not require glasses control, but the methods on ScrollingTextView do.
      Returns:
      a ScrollingTextView object
      Since:
      1.4.0