Introduction¶

The AIDL (Android Interface Definition Language) Interface allows Android applications to programmatically communicate with Six15’s service application. This interface offers the most flexibility and supports the most features on the ST1.

You can learn more about AIDL from Google’s AIDL documentation.

The only features not supported through the AIDL interface are the microphone (which is handled by the OS) and the camera when the “Expose Camera through SDK” is turned off. When this setting is turned off, the camera can be accessed directly as a USB Video Class (UVC) device.

The Android host device must have installed an app that provides the Six15 Service. The Six15 Service is implemented in the “Six15 ST1” application. Any of the “Six15 ST1” app variants expose exactly the same AIDL Interface.

AIDL is a very standard Android mechanism, but isn’t the easiest thing to use. Six15 also has an Intent Interface for sending simple text based content or static images to the HUD. The Intent Interface is simpler but less powerful than the AIDL Interface.

When Six15 makes changes in the future, the ALDI interface will be backwards compatible. Backward compatibility is standard for all AIDL interfaces by design.

Architecture¶

The “Six15 ST1” app includes an exported Android Service. Your application can talk to that Service by binding to it. Once bound, the client (your app) and server (our app) can communicate with each other. Your app will send commands like “display image”. Our app notifies you of events like “device connected” or “camera frame available”.

Additional details of the API are in API definition section.

The Six15 ST1 app connects to the ST1 over USB 2.0 or Bluetooth LE (Beta Testing). It interprets the commands from the AIDL interface and sends them to the ST1 where they can be executed. It also interprets messages from the ST1 and sends them back to the connected client apps.

Functionality¶

The AIDL Interface provides the following functions:

Get device status and state.

Write to display using images.

Write to display using screen mirroring or presentation mode.

Read from IMU (head tracker).

Read from Camera (ST1-C only).

Write/Read non-volatile user data.

Reducing Boilerplate Code¶

The following sections define Six15’s AIDL Interface in great detail. Deep understanding of AIDL will be needed if you were to implement a client application from scratch.

Six15 also has example code which can help to reduce boilerplate and get your app running much faster.

We highly recommend taking a look at the examples instead of writing your client’s AIDL from scratch. The example code was designed to be included in external client application as-is, but they also offer you the flexibility of customizing your integration when needed.

Including the AIDL Interface in your App¶

Six15 provides a set of AIDL interface files (most importantly IHudService.aidl and IHudServiceCallback.aidl) which define the communion between your app and the Six15 Service. Also included are Java classes which are used for preparing messages and parsing responses from the service. These files are released as part of the SDK. Particularly Six15Hud_Android_Service_AIDL_<version>.zip and hudservice-aidl.aar.

There are 3 main ways to include the AIDL interface definition files in your application. Listed in the order we recommend them:

Add AIDL from source.

Add AIDL from AAR.

Add AIDL files directly to your “app” module.

Add the AIDL from Source¶

Unzip Six15Hud_Android_Service_AIDL_<version>.zip, and rename “hudservice-aidl”. Place this “hudservice-aidl” module (folder) at the same level as your “app” module.

Add the module to your project by adding this line to your root level settings.gradle

include ':hudservice-aidl'

Add the module as a dependency to your “app” module by adding the following to your app/build.gradle

dependencies {
    ...
    implementation project(':hudservice-aidl')
}

This method is recommended since it gives you direct access to the files without the “black-box” of an AAR file in the way.

Add the AIDL from AAR¶

Create a new module (folder) in your Android Studio project named “hudservice-aidl”. This should be on the same level as your “app” module.

Place hudservice-aidl.aar from the SDK inside the hudservice-aidl folder.

Create a simple build.gradle inside the hudservice-aidl folder.

configurations.maybeCreate("default")
artifacts.add("default", file('hudservice-aidl.aar'))

Add this module to your project by adding this line to your root level settings.gradle

include ':hudservice-aidl'

Add the module as a dependency to your “app” module by adding the following to your app/build.gradle

dependencies {
    ...
    implementation project(':hudservice-aidl')
}

See our example GitHub Repository for a complete example. https://github.com/Six15-Technologies/ST1-Examples/tree/master/hudservice-aidl

Add the AIDL to your app module¶

Merge the “src” directory inside Six15Hud_Android_Service_AIDL_<version>.zip into your “app/src” directory. Make sure to use your AndroidManifest.xml file, not ours.

Merge files: build.gradle, proguard-rules.pro and consumer-rules.pro.

This method is not recommend because it makes applying SDK updates more difficult. It also make it unclear that the included files should not be modified.

Communicating with the AIDL Interface¶

The Six15 Service is an exported service inside the “Six15 ST1” application. It must be bound to by your application, be that an Activity, Fragment, Presentation, or Service. See Google’s documentation about Services for more information.

Service Binding Process¶

Six15 has example code to bind with our service. This documentation describes what our example code is doing.

Create a ServiceConnection

serviceConnection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName name, IBinder service) {
    // We will add more code later
    }

    @Override
    public void onServiceDisconnected(ComponentName name) {
    // TODO handle service disconnect
    }
};

Create an Intent to start the Six15 ST1 Service

Newer versions of Android require an explicit intent when binding to a service. Since the Six15 Service could be hosted by different applications, you should query which application is hosting the intent instead of hard coding a package name and class name.

public static Intent createExplicitSix15ServiceIntent(Context context) {
    Intent intent = new Intent("com.six15.hudservice.SERVICE");
    List<ResolveInfo> resolveInfo = context.getPackageManager().queryIntentServices(intent, 0);
    if (resolveInfo == null || resolveInfo.size() == 0) {
        return null;
    }
    ResolveInfo serviceInfo = resolveInfo.get(0);
    ComponentName component = new ComponentName(serviceInfo.serviceInfo.packageName, serviceInfo.serviceInfo.name);

    // Set the component to be explicit
    intent.setComponent(component);
    return intent;
}

Running queryIntentServices() requires the following in your AndroidManifest.xml

<queries>
   <intent>
      <action android:name="com.six15.hudservice.SERVICE" />
   </intent>
</queries>

Bind to the Service using your ServiceConnection and Intent.

For an Activity this is normally done in onStart() and context is “this”.

Intent intent = createExplicitSix15ServiceIntent(context);
if (intent != null){
    context.bindService(intent, serviceConnection, Context.BIND_AUTO_CREATE);
}

Handle onServiceConnected to acquire IHudService.

Create a member variable for hudService first.

private IHudService hudService;

IHudService is used to send commands to the Six15 Service. This method was already defined above in step 1.

public void onServiceConnected(ComponentName name, IBinder service) {
    hudService = IHudService.Stub.asInterface(service);
}

Create an IHudServiceCallback

This will receive responses from the “Six15 ST1” app.

IHudServiceCallback callbacks = new IHudServiceCallback.Stub() {
    //TODO Override methods. Android Studio can do this automatically with Alt-Enter

};

Check for init, and then register callback

Inside onServiceConnected(), use IHudService to check for init, and then register your IHudServiceCallback.

try {
    if (hudService.isInited()) {
        hudService.registerCallback(callbacks);
        return;
    }
} catch (RemoteException e) {
    e.printStackTrace();
}

Now your app is bound to the Six15 Service. You can use any of the functions defined in IHudService.aidl to talk to the service. Once a device connects, you can send data to the ST1 as well.

Make a service call

A simple example of using the service calls is to set the display to a single color. This can be done by adding a call to onConnected callback:

public void onConnected(boolean connected) throws RemoteException {
    Bitmap screen = Bitmap.createBitmap(Constants.ST1_HUD_WIDTH, Constants.ST1_HUD_HEIGHT, Bitmap.Config.ARGB_8888 );
    screen.eraseColor(Color.GREEN);
    ImageFrame toHud = new ImageFrame(screen);
    try {
        hudService.sendImageToHud(toHud);
    } catch (RemoteException e) {
        e.printStackTrace();
    }
}

Clean-up

When you’re done with the service, unregister your callbacks and unbind from the service. This is likely done in onStop() for an Activity.

if (hudService != null) {
    try {
        hudService.unregisterCallback(callbacks);
    } catch (RemoteException e) {
        e.printStackTrace();
    }
}
context.unbindService(serviceConnection);

Important AIDL Interfaces¶

Some of the important AIDL and Java classes included in the hudservice-aid module are listed below.

Name	Description
IHudService.aidl	This is the main AIDL interface which your application uses to talk to the Six15 Service.
IHudServiceCallback.aidl	This is the AIDL interface which defines how the Six15 Service talks to your application.
ByteFrame.aidl	The HUD Byte Frame interface is a marshalling wrapper for sending a raw byte array of image data to the HUD for display. This is the type that must be used to send JPEG images to the HUD.
ImageFrame.aidl	The ImageFrame interface is the marshalling wrapper for sending Android Bitmap objects to the HUD. This is the type that must be used to send Bitmap images to the HUD.

Handling Callbacks¶

The IHudServiceCallback Interface provides a way to handle incoming data from the Six15 Service, and through extension, from the ST1. These callbacks are not called on your applications main thread. Therefore it is often necessary to pass these commands to your Activity’s main thread. One way to do this is with a Handler.

Below is a partial implementation of IHudServiceCallback Interface. Many of the callback functions receive a command byte (see HUD_CommandBYTE) and a response in the form of JSON. Our example code’s HudServiceConnection class shows how to parse this JSON into the associated objects. The example code also make it easy to forward every callback onto a specific handler.

Handler handler = new Handler(Looper.getMainLooper());

IHudServiceCallback callback = new IHudServiceCallback.Stub() {
    @Override
    public void onInfo(byte cmd, String jsonText) throws RemoteException {
        handler.post(() -> {
            Log.d(TAG, "onInfo() data sent to main thread with: cmd = [" + cmd + "], jsonText = [" + jsonText + "]");
        }
    }
}

HUD_CommandBYTE Definition¶

The HUD command bytes are the command responses that will be returned for a specific call by the HUD Service (like onInfo()). Use the command byte to determine the response type for your response handler.

Note

This may not be the full list of commands if new features are added. If this happens, HUD_CommandBYTE.forValue(int cmd) may return null. Be sure to check the return value for null or perform your comparison using the byte value instead of comparing enums directly. Putting a null enum in a switch statement will cause a crash.

HC_STATUS  ((byte)0x00),
HC_VERSIONS ((byte)0x01),
HC_DEV_INFO ((byte)0x02),
HC_DEV_SETTINGS ((byte)0x03),
HC_VERSIONS_EXTRA ((byte)0x04),
HC_MODE_UPD ((byte)0x05),
HC_MODE_QUERY ((byte)0x0A),
HC_MODE_SRST ((byte)0x0F),
HC_DISP_SIZE ((byte)0x20),
HC_DISP_CLEAR ((byte)0x21),
HC_DISP_BRT ((byte)0x22),
HC_DISP_ON ((byte)0x23),
HC_DISP_AGGRESSIVE_SLEEP ((byte)0x24),
HC_DISP_DITHER ((byte)0x25),
HC_DISP_INFO ((byte)0x2F),
HC_CAM_START ((byte)0x30),
HC_CAM_SNAP ((byte)0x35),
HC_CAM_STOP ((byte)0x3A),
HC_CAM_INFO ((byte)0x3F),
HC_CFG_SPEN ((byte)0x40),
HC_CFG_SPDEL ((byte)0x41),
HC_CFG_SPIMAGE ((byte)0x42),
HC_CFG_AUTRESIZE ((byte)0x43),
HC_CFG_BL ((byte)0x44),
HC_CFG_APP ((byte)0x45),
HC_CFG_OEM ((byte)0x46),
HC_CFG_SETTINGS ((byte)0x47),
HC_CFG_CUSTOM ((byte)0x49),
HC_CFG_RESET ((byte)0x4F),
HC_IMU_DATA ((byte)0x50),
HC_IMU_STATUS ((byte)0x51),
HC_IMU_START ((byte)0x52),
HC_IMU_START_CAL ((byte)0x53),
HC_IMU_GET_CAL ((byte)0x54),
HC_IMU_SET_FILTER_TUNE ((byte)0x55),
HC_IMU_STOP ((byte)0x5F),
HC_AUD_INFO ((byte)0x6F),
HC_DRAW ((byte)0x70),
HC_DEV_METRICS ((byte)0x80),
HC_DEV_DEBUG_TERMINAL ((byte)0x81),
HC_DEV_720_FPS ((byte)0x82),
HC_DEV_TEXT_SEND((byte)0x83),
HC_DEV_TEXT_CLEAR((byte)0x84),
HC_IMAGE ((byte)0xD0),
HC_JPEG((byte)0xDE),
HC_RAW ((byte)0xDD),
HC_ERROR ((byte)0xEE),
HC_HEART_BEAT ((byte)0xFF);

API Definitions¶

This section lists the possible AIDL function calls your application can make. These functions instruct the Six15 service to take some action, or preform some task.

These AIDL functions are defined in IHudService.aidl.

Information and Hardware Functions¶

Many functions return status integers, and will respond asynchronously to the application with a callback. The response integers are:

Return Values¶
Value	Description
>= 0	Success
-1	Sending the command to the HUD failed
-2	Function is not supported or disabled in the service

When calling integer return type functions in the API, there can be additional data received in the form of a JSON string asynchronously. The developer should implement the Callback interface and check for data sent by the Service.

Service Initialized¶

Function Prototype:

boolean isInited()

Parameters:

None

Return:

Boolean

Description:

Retrieve if the HUD service has been initialized.

True indicates that is initialized.

False has indicated that it is not initialized.

Async JSON Data:

None

Register Service callback¶

Function Prototype:

void registerCallback(IHudServiceCallback cb)

Parameters:

IHudServiceCallback

Return:

void

Description:

Used to register your interface implementation as the callback to be called by the HUD service.

Async JSON Data:

None

Unregister Service Callback¶

Function Prototype:

void unregisterCallback(IHudServiceCallback cb)

Parameters:

IHudServiceCallback

Return:

void

Description:

Used to unregister your interface implementation as the callback to be called by the HUD service.

Async JSON Data:

None

Check Service Callback¶

Function Prototype:

boolean checkCallback(IHudServiceCallback cb)

Parameters:

IHudServiceCallback

Return:

Boolean

Description:

Used to check if your interface implementation has been registered as a callback with the HUD service.

True indicates that it is already registered

False indicates that it is not registered

Async JSON Data:

None

Get HUD Connected¶

Function Prototype:

boolean getHudConnected()

Parameters:

None

Return:

Boolean

Description:

Used to check if a HUD is connected to the Android device. Returns true when a HUD is connected to the Android’s USB port.

Async JSON Data:

None

Get SDK Version¶

Function Prototype:

String getSDKVersion()

Parameters:

None

Return:

String

Description:

Retrieve the SDK version information in the form of “x.xx.xx”

Note

This function did not always return the correct value in SDK versions between 2.0 and 2.5.0.

Async JSON Data:: None

Get HUD Information¶

Function Prototype:

int getHudInfo()

Parameters:

None

Return:

Integer

Description:

Retrieves all HUD information.

Command BYTE:

HC_DEV_INFO

ASYNC JSON Data:

DeviceInfo.java

{
    "man_id":"SIX15",
    "prod_id":"1234",
    "prod_name":"ST1",
    "device_id":"SD1234",
    "serial_num":"1212121",
    "hw_ver":"x.xx.xx",
    "bl_ver":"x.xx.xx",
    "fw_ver":"x.xx.xx"
}

Get HUD Information Fast¶

Function Prototype:

String getHudInfromation()

Note

“Information” in this function call is spelled incorrectly. It is left in API for legacy compatibility.

Parameters:: None
Return:: String
Description:: If available, returns cached hud_info command, otherwise returns null.

{
    "man_id":"SIX15",
    "prod_id":"1234",
    "prod_name":"ST1",
    "device_id":"SD1234",
    "serial_num":"1212121",
    "hw_ver":"x.xx.xx",
    "bl_ver":"x.xx.xx",
    "fw_ver":"x.xx.xx"
}

Command BYTE:: HC_DEV_INFO
Async JSON Data:: None

Get HUD Version Information¶

Function Prototype:

int getHudVersions()

Parameters:

None

Return:

Integer

Description:

Retrieves HUD versioning information for hardware, bootloader, and firmware

Command BYTE:

HC_VERSIONS

ASYNC JSON Data:

DeviceInfo.java

{
    "hw_ver":"x.xx.xx",
    "bl_ver":"x.xx.xx",
    "fw_ver":"x.xx.xx"
}

Get HUD Settings¶

Function Prototype:

int getHudSettings()

Parameters:

None

Return:

Integer

Description:

Retrieves HUD settings information.

Command BYTE:

HC_DEV_SETTINGS

ASYNC JSON Data:

DeviceSettings.java

{
    "width":640,
    "height":400,
    "resize_on":"false",
    "splash_en":"true",
    "mic_en":"true",
    "bright_def":2
}

Set HUD Settings Defaults¶

Function Prototype:

int setHudDefaultSettings()

Parameters:

None

Return:

Integer

Description:

Resets all settings to default values.

Command BYTE:

HC_DEV_SETTINGS

ASYNC JSON Data:

DeviceSettings.java

{
    "width":640,
    "height":400,
    "resize_on":"false",
    "splash_en":"true",
    "mic_en":"true",
    "bright_def":2
}

Set HUD Settings¶

Function Prototype:

int setHudSettings(boolean autoResize, boolean splashEnable, byte defBrightness)

Parameters:

autoResize, splashEnable, defBrightness

Return:

Integer

Description:

Allows application to save settings to the HUD device that will persist across power cycles.

Command BYTE:

HC_DEV_SETTINGS

ASYNC JSON Data:

DeviceSettings.java

{
    "width":640,
    "height":400,
    "resize_on":"false",
    "splash_en":"true",
    "mic_en":"true",
    "bright_def":2
}

Get HUD Operation Mode¶

Function Prototype:

int getHudOperationMode()

Parameters:

None

Return:

Integer

Description:

Retrieves the current operation mode of the device.

Returns:

0 - Normal Mode

1 - Mirror and Presentation mode.

2 - Presentation Mode

3 - (reserved)

4 - Mirror Mode

5 - Mirror with crop mode (accessed using Six15 ST1 app)

Command BYTE:

None

ASYNC JSON Data:

None

Set HUD Operation Mode¶

Function Prototype:

boolean setHudOperationMode(int mode, boolean bStopOnly)

Parameters:

mode
bStop Only

Return:

Boolean

Description:

Sets the current operation mode of the device. Returns true when the call succeeds. Modes available are:

0 - Normal Mode

1 - Mirror and Presentation mode.

2 - Presentation Mode

3 - (reserved)

4 - Mirror Mode

5 - Mirror with crop mode (accessed using Six15 ST1 app)

The boolean bStopOnly is used to tell the function not to stop the running mode and not set the HUD to a different mode. bStopOnly will almost all the time be false, unless there was a situation where you wanted to stop something like screen mirroring without changing the stated and not effect the HUD service of screen mirroring being changed in the preferences.

Command BYTE:

None

ASYNC JSON Data:

None

Ping Command¶

Function Prototype:

int sendPing()

Parameters:

None

Return:

Integer

Description:

Simple command response that performs a heartbeat style test.

Command BYTE:

None

Async JSON Data:

onPing() callback.

Query Device Mode¶

Function Prototype:

int doQueryHudMode()

Parameters:

None

Return:

Integer

Description:

Query device mode application or bootloader. Returns negative value on failure to send command. When command is sent successfully a response from the HUD will send json data back. Mode value is “bl” or “app”.

Command BYTE:

None

ASYNC JSON Data:

{
    "mode":"bl"
}

Soft Reset¶

Function Prototype:

int doHudSoftReset()

Parameters:

None

Return:

Integer

Description:

Soft reset of HUD hardware.

Command BYTE:

None

Async JSON Data:

None

Get Hud Debug Terminal¶

Function Prototype:

int getHudDebugTerminal()

Parameters:

None

Return:

Integer

Description:

Receives a message from the devices internal debug terminal. This function is intended for internal use.

Command BYTE:

HC_DEV_DEBUG_TERMINAL

Async JSON Data:

{
    "term":"xxxxx"
}

Is Connected Over Low Bandwidth Link¶

Function Prototype:

boolean isConnectedOverLowBandwidthLink()

Parameters:

None

Return:

Boolean

Description:

Returns true if the connected device is connected over a low bandwidth link. False otherwise. When true applications may want to avoid sending high quality JPEGs and/or high FPS screen updates.

Command BYTE:

None

Async JSON Data:

None

Get Aggressive Display Power Saving Enabled¶

Function Prototype:

int getAggressiveDisplayPowerSavingEnabled()

Parameters:

None

Return:

Integer

Description:

Gets the current aggressive power saving state. This state can default to different values based on the revision of HUD and/or FPGAs.

Command BYTE:

HC_DISP_AGGRESSIVE_SLEEP

Async JSON Data:

{
    "disp_aggressive_sleep":true/false,
    "hw_enabled":true/false
}

Set Aggressive Display Power Saving Enabled¶

Function Prototype:

int setAggressiveDisplayPowerSavingEnabled(boolean enabled);

Parameters:

enabled

Return:

Integer

Description:

Overrides the default aggressive power saving state. This function is intended for internal use.

Command BYTE:

None

Async JSON Data:

None

Get Hud Battery Level¶

Function Prototype:

int getHudBatteryLevel();

Parameters:

None

Return:

Integer

Description:

Queries the connected device asking for it’s battery level, is applicable. If the device has a battery and responds with its battery level, callback void onBattery(int battery_percent) will be called with the current battery level between 0 and 100.

Display Functions¶

Get HUD Display Size¶

Function Prototype:

int getHudDisplaySize()

Parameters:

None

Return:

Integer

Description:

Retrieve HUD display width and height in pixels.

Command BYTE:

HC_DISP_SIZE

ASYNC JSON Data:

{
    "width":640,
    "height":400
}

Get Auto Resize of Image¶

Function Prototype:

boolean getAutoResizeEnabled()

Parameters:

None

Return:

Boolean

Description:

Returns true if images will be resized to fit the display automatically. Resizing only occurs when images are larger than the display width and/or height.

Command BYTE:

None

Async JSON Data:

None

Set Auto Resize of Image Data¶

Function Prototype:

boolean setAutoResizeImage(boolean enable)

Parameters:

enable

Return:

Boolean

Description:

Set auto resize of images for current session, not persisting.

Command BYTE:

None

Async JSON Data:

None

Get Last Frame Send Time¶

Function Prototype:

float getLastFrameBufferTime()

Parameters:

None

Return:

float

Description:

Retrieves the elapsed time for transcoding and sending the image to the HUD.

Command BYTE:

None

Async JSON Data:

None

Get Display Information¶

Function Prototype:

int getDisplayInfo()

Parameters:

None

Return:

Integer

Description:

Retrieves the full display information.

Command BYTE:

HC_DEV_INFO

ASYNC JSON Data:

No Class Defined

{
    "width":640,
    "height":400,
    "display_on":"true",
    "bright_lvl":3
}

Get Display Status On/Off¶

Function Prototype:

int getDisplayOn()

Parameters:

None

Return:

Integer

Description:

Returns true if the HUD display is on.

Command BYTE:

HC_DISP_ON

ASYNC JSON Data:

No Class Defined

{
    "disp_on":"true"
}

Set Display Status On/Off¶

Function Prototype:

int setDisplayOn(boolean onOff)

Parameters:

onOff

Return:

Integer

Description:

Set HUD display on or off, display status will be sent back from the HUD. True will turn display on and false will turn the display off.

Command BYTE:

HC_DISP_ON

ASYNC JSON Data:

No Class Defined

{
    "disp_on":"true"
}

Get Display Brightness Level¶

Function Prototype:

int getBrightnessLevel()

Parameters:

None

Return:

Integer

Description:

Returns current brightness level of the HUD display. Values are integers from zero (0) to three (3), with three (3) being the highest.

Command BYTE:

HC_DISP_BRT

ASYNC JSON Data:

No Class Defined

{
    "bright_lvl":3
}

Set Display Brightness Level¶

Function Prototype:

int setBrightnessLevel(byte level)

Parameters:

None

Return:

Integer

Description:

Sets brightness level of the HUD display for current session. Returns current brightness level of the HUD display. Values are integers from zero (0) to three (3), with three (3) being the highest.

Command BYTE:

HC_DISP_BRT

Async JSON Data:

No Class Defined

{
    "bright_lvl":3
}

Clear HUD Display¶

Function Prototype:

boolean clearHudDisplay()

Parameters:

None

Return:

Boolean

Description:

Clears HUD display.

Returns true when the clear command was sent successfully and false when there is an error.

Command BYTE:

HC_DISP_CLEAR

Async JSON Data:

{
    "disp_on":"false"
}

Send JPEG file to HUD¶

Function Prototype:

boolean sendJpegToHud(String filePath)

Parameters:

filePath

Return:

Boolean

Description:

Note

This interface does not work on recent versions of Android because the service likely does not have correct permissions to access the file at the path specified.

This function is NOT recommended.

Send a JPEG file to the HUD directly. Developer must provide a string path to the JPEG file to send. Developer must also ensure that permissions where implicitly granted by the user for accessing storage on Android version 6.0 and later. Returns true when the JPEG formatted image data was sent successfully and false when there is an error. Data will be checked and verified.

Command BYTE:

None

Async JSON Data:

None

Send Android Bitmap to HUD¶

Function Prototype:

boolean sendImageToHud(in ImageFrame imageFrame)

Parameters:

ImageFrame

Return:

Boolean

Description:

Send a bitmap to the HUD. Returns true when the bitmap data was sent successfully and false when there is an error.

Developer must provide an ImageFrame wrapped bitmap object to this function to martial the data to the remote service. Data will be checked and verified.

Command BYTE:

None

Async JSON Data:

None

Send Buffer to HUD¶

Function Prototype:

boolean sendBufferToHud(in ByteFrame byteFrame)

Parameters:

ImageFrame

Return:

Boolean

Description:

Send a raw JPEG buffer to the HUD.

Returns true when the buffer data was sent successfully and false when there is an error. Developer must provide a ByteFrame wrapped byte array to this function to martial the data to the remote service.

This is provided as a performance enhancement and data is not checked or verified. This command requires that the developer ensure that the JPEG data is properly formatted for the HUD.

Command BYTE:

None

Async JSON Data:

None

Set Dither Enabled¶

Function Prototype:

int setDitherEnabled(boolean enabled);

Parameters:

Boolean

Return:

Integer

Description:

Enable or disable display dithering.

Dithering slightly adjusts the position of the image on the HUD over time. This can help reduce display burn-in when the same image is shown over long periods of time.

This setting must be set every time a device connects and is not persistent.

Command BYTE:

None

Async JSON Data:

None

Send Display Text¶

Function Prototype:

int sendDisplayText(String text);

Parameters:

String

Return:

Integer

Description:

Adds a small text overlay to the HUD display which looks similar to a subtitle or an Android “Toast” message. These messages can be useful for errors or other unexpected actions which can’t be shown with a full image, and can’t be shown on the host devices’s UI. These message eventually time out after a few seconds. Avoid using these for normal operation.

Command BYTE:

None

Async JSON Data:

None

Clear Display Text¶

Function Prototype:

int clearDisplayText();

Parameters:

None

Return:

Integer

Description:

Immediately clear any text messages sent with sendDisplayText(text)

Command BYTE:

None

Async JSON Data:

None

IMU Functions¶

IMU functions are located on the HUD can asynchronously stream factory calibrated sensor data to the connected device in the form of JSON data. The sensor returns accelerometer, gyroscope, magnetometer, quaternion, and temperature data.

IMU Data¶

Function Prototype:

None

Parameters:

None

Return:

None

Description:

The IMU sensor data is sent to the HUD every 16ms (60Hz).

This data is sent via the HUD Service callback onImuData function. Data is in JSON format defined below. All floats are carried out to a maximum of three decimal places except for temperature which is two decimal places.

Accelerometer data is in the form of a float vector consisting of X, Y, Z values signified by the A element.

Gyroscope data is in the form of an array of floats X, Y, Z values signified by the G element.

Magnetometer data is in the form of a float vector X, Y, Z values signified by the M element.

A Quaternion is provided signified by the Q element and consists of W, X, Y, Z values.

Temperature is in the format of degrees Celsius and is signified by the T element in the data structure and consists of a single float value.

ASYNC JSON Data:

ImuData.java

{
    "A":[0.000,0.000,0.000],
    "G":[0.000,0.000,0.000],
    "M":[0.000,0.000,0.000],
    "Q":[0.000,0.000,0.000,0.000],
    "T":0.00
}

IMU Status¶

Function Prototype:

int getImuStatus()

Parameters:

None

Return:

Integer

Description:

Asynchronously returns a JSON message indicating the state of the IMU data stream.

Command BYTE:

None

Async JSON Data:

{
    "imu_on":"true"
}

Start IMU¶

Function Prototype:

int startImu()

Parameters:

None

Return:

Integer

Description:

Starts the IMU data stream and asynchronously returns a JSON message indicating the state of the IMU data stream.

Command BYTE:

None

Async JSON Data:

{
    "imu_on":"true"
}

Stop IMU¶

Function Prototype:

int stopImu()

Parameters:

None

Return:

Integer

Description:

Stop the IMU data Stream, and asynchronously returns JSON message indicating the state of the IMU data stream.

Command BYTE:

None

ASYNC JSON Data:

{
    "imu_on":"false"
}

Start User IMU Cal¶

Function Prototype:

bool startUserImuCal(int imuSensor);

Parameters:

int imuSensor

Return:

bool

Description:

Calibrate the IMU using the Six15 ST1 App

Before using this method, make sure the IMU data Stream has been started using startImu(), otherwise the calibration will not be able to complete. This starts the process of calibrating the gyroscope and MAG BIAS in the HUD.

Only way to get status is by calling get status function. During the calibration process, make sure the HUD is stationary while the gyroscope is being calibrated and moving while MAG BIAS. It is important that the MAG BIAS rotates slowly in three different directions: forward over itself, pivoting around itself, and rotating end over end.

Get User IMU Cal¶

Function Prototype:

bool getUserImuCal(int imuSensor)

Parameters:

int imuSensor

Return:

bool

Description:

Calibrate the IMU using the Six15 ST1 App

Get the status of the IMU’s calibration of the system corresponding to the given byte value. In the asynchronous JSON that is returned there are three indexes: imu_en, cal_status, and cal_error. Imu_en is the current status of the imu. If the imu is connected and enabled this should have a value of one. Otherwise, this will have a value of zero.

Cal_status is what the system is currently looking at. While calibrating the gyroscope it will have a value of two and for MAG BIAS it will have a value of three. Once the calibration is complete this value will become zero.

Cal_error will read zero if there are no errors.

ASYNC JSON Data:

ImuStatus.java

{
    "imu_en":1,
    "cal_status":3,
    "cal_error":0
}

Set IMU Filter Tune¶

Function Prototype:

int setImuFilterTune(float gain, float zeta)

Parameters:

gain, zeta

Return:

Integer

Description:

Adjusts the responsiveness and drift behavior of the IMU sensor fusion. This function is intended for internal use.

Command BYTE:

None

ASYNC JSON Data:

None

HUD Camera Functions¶

All camera functions require the CAMERA permissions

<uses-permission android:name="android.permission.CAMERA" />

Camera Field of View Measurements¶

The camera field of view is given in the table below.

Resolutions¶
Aspect Ratio	Supported Resolutions	Field of View	Tolerance
4:3	640x480 2592x1944 (5MP)	65.9°	±1°
16:9	1280x720 (720p) 1920x1080 (1080p) 2560x1440 (QHD)	61.6°	±1°

Has Camera¶

Function Prototype:

boolean hasCamera()

Parameters:

None

Return:

Boolean

Description:

Returns true if the connected device has a camera. False otherwise.

Command BYTE:

None

Async JSON Data:

None

Set HUD Camera Enabled¶

Function Prototype:

void setCameraEnabled(boolean cameraEnable)

Parameters:

cameraEnable

Return:

void

Description:

This function call is deprecated, calling it does nothing.

Command BYTE:

None

Async JSON Data:

None

Get HUD Camera Enabled¶

Function Prototype:

boolean getCameraEnabled()

Parameters:

void

Return:

Boolean

Description:

If communicating with ST1C (with camera), returns True

If communicating with ST1 (no camera), returns False

Command BYTE:

None

Async JSON Data:

None

Set Camera Autofocus Mode¶

Function Prototype:

void setCameraAutofocusMode(boolean bAutofocusOn)

Parameters:

bAutofocusOn

Return:

void

Description:

Enable or disable camera autofocus. Setting bAutofocusOn to true turns autofocus on and false turns autofocus off.

Command BYTE:

None

Async JSON Data:

None

Get Camera Autofocus Mode¶

Function Prototype:

boolean getCameraAutofocusMode()

Parameters:

None

Return:

Boolean

Description:

Returns whether or not the HUD camera has autofocus enabled(true) or disabled(false).

Command BYTE:

None

Async JSON Data:

None

Start Camera¶

Function Prototype:

Boolean startCameraCapture()

Parameters:

None

Return:

Boolean

Description:

Start camera streaming. Function will decode the JPEG data to an Android image and send each frame as an image to the application.

This will trigger the callback onImage() and will return a bitmap.

This call should be considered only for low-performance applications. Depending on the host hardware and selected resolution, maximum framerate may not be available.

Consider using startRawCameraCapture()

Command BYTE:

None

Async JSON Data:

None

Start Camera (Raw JPEG Mode)¶

Function Prototype:

Boolean startRawCameraCapture()

Parameters:

None

Return:

Boolean

Description:

Start camera streaming. Raw JPEG frames will be sent to the application from HUD service via onJpeg.

The data sent is taken from the motion-JPEG stream on the UVC camera.

This can provide a higher-framerate interface to the camera due to the lower data transfer over the ADIL interface.

Command BYTE:

None

Async JSON Data:

None

Stop Camera¶

Function Prototype:

Boolean stopCamera()

Parameters:

None

Return:

Boolean

Description:

Stop camera streaming.

Command BYTE:

None

Async JSON Data:

None

Get Supported Resolutions¶

Function Prototype:

List<CameraResolution> getSupportedCameraResolutions()

Parameters:

None

Return:

List<CameraResolution>

Description:

Only supported on SDK 2.0 and above (5.xx firmware). Returns a list of supported camera resolutions.

Command BYTE:

None

Async JSON Data:

None

Get Current Camera Resolution¶

Function Prototype:

CameraResolution getCurrentCameraResolution()

Parameters:

None

Return:

CameraResolution

Description:

Only supported on SDK 2.0 and above (5.xx firmware). Returns the current camera resolution.

Command BYTE:

None

Async JSON Data:

None

Set Current Camera Resolution¶

Function Prototype:

boolean setCurrentCameraResolution(CameraResolution cam_res)

Parameters:

CameraResolution

Return:

Boolean

Description:

Only supported on SDK 2.0 and above (5.xx firmware). Changes the current camera resolution, returns true on success and false on failure.

Command BYTE:

None

Async JSON Data:

None

Get Camera Zoom¶

Function Prototype:

int getCameraZoom()

Parameters:

None

Return:

Integer

Description:

Only supported on SDK 2.0 and above (5.xx firmware). Returns the current camera zoom setting with zero (0) being no zoom and any positive integer being the level of zoom. Supported zoom levels can be found in the CameraResolution object.

Command BYTE:

None

Async JSON Data:

None

Set Camera Zoom¶

Function Prototype:

boolean setCameraZoom(int zoom)

Parameters:

int

Return:

Boolean

Description:

Only supported on SDK 2.0 and above (5.xx firmware). Sets the camera zoom setting to the desired zoom level. Returns true on success and false on failure. Supported zoom levels can be found in the CameraResolution object.

Command BYTE:

None

Async JSON Data:

None

Set 720 Framerate¶

Function Prototype:

int set720Framerate(byte value);

Parameters:

byte

Return:

Boolean

Description:

Sets the camera’s video frame-rate when running at 720p. It is not recommend to adjust this value. Some legacy Android devices lack the CPU power to stream 720 video and used this setting to slow the camera down. All modern devices should use the maximum value of 24.

Command BYTE:

None

Async JSON Data:

None

Get 720 Framerate¶

Function Prototype:

int get720Framerate();

Parameters:

byte

Return:

Boolean

Description:

Gets the camera’s video frame-rate when running at 720p. Some legacy Android devices lack the CPU power to stream 720 video and used this setting to slow the camera down. All modern devices should use the maximum value of 24.

Command BYTE:

HC_DEV_720_FPS

Async JSON Data:

{
    "cam_720fps":xx
}

HUD Microphone Functions¶

Get HUD Microphone Enabled¶

Function Prototype:

boolean getMicrophoneEnabled()

Parameters:

None

Return:

Boolean

Description:

Get whether or not the HUD Microphone is enabled or disabled.

Command BYTE:

None

Async JSON Data:

None

Set HUD Microphone Enabled¶

Function Prototype:

void setMicrophoneEnabled(boolean microphoneEnable)

Parameters:

microphoneEnable

Return:

void

Description:

Enable or disable the microphone feature.

This is used if Android system uses the HUD microphone as the default microphone. When disabled, the Android system will use the normal default microphone.

If the microphone state is changed in the ST1, the ST1 will restart so the new USB descriptors will be sent.

The set of microphone enable is stored in non-volatile memory in the ST1, it does not need to be called every time an app is started.

Note

Calling this function will cause the ST1 to reboot.

Command BYTE:

None

Async JSON Data:

None

HUD User Data Functions¶

The HUD allows the application to store data in the HUD devices non-volatile memory. There is 256K bytes available for the developer. The only requirement is that the data must be stored in a string.

Get User Data¶

Function Prototype:

String getUserData()

Parameters:

None

Return:

String

Description:

Gets user data string. Typically developers will use a JSON string.

This is an asynchronous call, the data stored in the HUD will be sent from the HUD to the application.

Command BYTE:

None

Async JSON Data:

Returns string of user data stored on HUD device.

Set User Data¶

Function Prototype:

boolean setUserData(String data)

Parameters:

data

Return:

Boolean

Description:

Sets user data string. Typically developers will use a JSON string.

Command BYTE:

None

Async JSON Data:

Returns a JSON string indicating success or failure of saving user data.

Firmware Version Functions¶

Get Current Firmware Version¶

Function Prototype:

String getFirmwareVersion()

Parameters:

None

Return:

String

Description:

Retrieves version of firmware currently running in HUD. In the format “x.xx”.

Command BYTE:

None

Async JSON Data:

None

Get Extra Version¶

Function Prototype:

String getExtraVersions()

Parameters:

None

Return:

String

Description:

Retrieve extra version information.

Async JSON Data:

DeviceExtraInfo.java

{
    "fw_git_ver":"vx_xx-x-gxxxxxxx",
    "disp_fpga_ver":"xxxxxxxx-xx",
    "camera_fpga_ver":"xxxxxxxx-xx"
}

Deprecated Functions¶

Get Splash Screen Enabled¶

Function Prototype:

boolean getSplashScreenEnabled()

Parameters:

None

Return:

Boolean

Description:

Intended to reply with the enabled state of the splash screen. Hardware does not reply to this message. The splash screen is always enabled.

Command BYTE:

HC_CFG_SPEN

Async JSON Data:

None

Get Camera Snapshot¶

Function Prototype:

int getCameraSnapshot()

Parameters:

None

Return:

Integer

Description:

Intended to capture a single image without starting video. This functionally does not work, and therefore function does nothing.

Command BYTE:

None

Async JSON Data:

None

Get Camera Snapshot¶

Function Prototype:

void startScreenCaptureCommand(int resultCode, in Intent data, int mode)

Parameters:

None

Return:

void

Description:

Deprecated function to start screen mirroring. This function does nothing. Use setHudOperationMode() instead.

Command BYTE:

None

Async JSON Data:

None

Get Screen Capture Enabled¶

Function Prototype:

boolean getScreenCaptureEnabled()

Parameters:

None

Return:

Boolean

Description:

Deprecated function to check if screen mirroring is enabled. Use getHudOperationMode() instead.

Command BYTE:

None

Async JSON Data:

None