Htek UCV series phones - Android SDK Guide

1 Change History
2 1. Introduction
3 2. Application Building
4 3 Component Introduction
5 4. Scene System
6 5. Key Events
7 6. LED
8 7. Audio Channel
9 8. USB headset
10 9. Default Dial App
11 10. Autostart
12 Htek SDK Demo & Library Download

Change History

May 15, 2024

Update application building steps.

Update component introduction.

Add demo and library download link.

Oct 30, 2023

Update the Key Events chapter

1. Introduction

Htek UCV series phone is developed on the platform. This guide introduce the Htek's Android SDK to help the developers use the APIs.

1.1 Supported Models

Model	Firmware
UCV10 series	5.42.1.7.1.32 or higher
UCV20 series	5.42.1.7.1.32 or higher
UCV50 series	5.42.1.7.1.32 or higher
UCV52 series	5.42.1.7.1.32 or higher
UCV53 series	5.42.1.7.1.32 or higher

2. Application Building

Here is the necessary steps to build the application with Htek Android SDK.

2.1 Put libraries under directory app/libs

2.2 Add dependence in build.gradle

dependencies {
    ......
    implementation(files("libs/hlvoipCfg-release.aar"))
    implementation(files("libs/hlvoipCall-release.aar"))
    implementation(files("libs/hlBth.jar"))

    compileOnly(files('libs/hlsys.jar'))
    ......
}

2.3 Add API key in AndroidManifest.xml

To get an API key, please follow Request an API Key

<manifest xxxx>
    <application
        ...
        <meta-data
            android:name="api_key" android:value="/{api_key}" />
    </application>
 
</manifest xxxx>/>

3 Component Introduction

The VoIP API refers to a set of interfaces for developing applications based on Htek Android phones.

3.1 hlsys.jar

Provide support for Scene system, audio control, key event, LED control and USB headset control.

Refer to:

Scene System
Key Event
LED
Audio Channel
USB Headset

3.2 hlBth.jar

Provide support for Htek BT handset.

3.3 hlVoipCfg

Used to get and set the configurations of Htek VoIP

import com.htek.cfg.utils.CfgUtils; 

//Get and set configurations
//[xxxx] is of Int, String, Float, Double
CfgUtils.getCfg[xxxx]Value()
CfgUtils.setCfg[xxxx]Value()

//Get and set account info：
List<VoipAccount> CfgUtils.loadAccounts()
VoipAccount getAccount()
updateAccount()
VoipAccount getDefaultAccount()
setDefaultAccount()

//Get and set account configurations；
List<VoipProfile> CfgUtils.loadProfiles()
VoipProfile CfgUtils.getProfile()
updateProfile()

Refer to: Htek SDK Demo

3.4 hlVoipCall

Used to makes call and answers call through Htek VoIP.

Htek VoIP is the built-in call component on the phone, if your APP has its own call function, you don’t need use this component.

Refer to: Htek SDK Demo

4. Scene System

4.1 Introduction of Scene System

When using an Htek Android phone, there are many states, which the phone may be in one of them when you operate the phone.
Depending on the state, the phone responses differently to the same command/action.

For example, when you using the dialpad, and at the same time, you pickup the handset, the phone will call the number if you have already input some numbers, or it will switch to handset mode if you haven't input anything.

We call the current state of the phone a scene, and we use Scene System to manage the scene switching.

Below table lists some scenes as an example:

Action → Current Scene ↓	Pickup handset	Press handsfree button	Press headset button

Action → Current Scene ↓	Pickup handset	Press handsfree button	Press headset button
Idle	Enter dialpad	Enter dialpad	Switch headset priority mode
Using an app (not in talking)	Enter dialpad	Enter dialpad	Switch headset priority mode
Play Music	Using handset play	Using handsfree play	Using headset play
Using 3rd-party app talking	Switch to handset mode	Switch to handsfree mode	Switch to headset mode
Using dialpad	If already dial nubmers, call out using handset; else, switch to handset mode	If already dial nubmers, call out using handsfree; else, switch to handsfree mode	If already dial nubmers, call out using headset; else, switch to headset mode
Using built-in VOIP app talking	Switch to handset mode	If already in handsfree mode, end up the call; else, switch to handsfree mode	If already in headset mode, end up the call; else, switch to headset mode

4.2 Scene Client and Scene Manager

The scene system consists of scene client and scene manager.

4.2.1 Scene Manager

The SceneManager is a system service, and you can get an instance through this way:

Here is a list of all interfaces supported by the Scene Manager.

Expand the below block.

4.2.2 Scene Client

Implement a Scene Client and register it to Scene Manager so you can use it to handle events. You may have multi Scene Clients, but only the one which has the highest priority will be active to work. (refer to Scene Priority)

The interface of Scene Client is as below:

Interface	Parameters	Return Value	Comments

Interface	Parameters	Return Value	Comments
enter		void
exit		void	If there is another Scene Client has higher priority exists, or unregister this Scene Client, exit() will be called.
getName		String	Need to implement to return the name of Scene Client.
onAudioDeviceChanged		true: if it is no need to use system default audio device switching mechanism; false: if need.	Generally, return false is recommended. Tips: the system default audio device switching mechanism will update the corresponding LED, Status Bar and so on when the audio device has been changed.
onDialpadPress	c: the currently input character (0~9, *, #). replace: replace the previous input character or not	true: Dialpad press event will not be deliver to the currently active app false: Dialpad press event will be deliver to the currently active app	This callback doesn't run in UI threading, please avoid executing blocking tasks here.
onEhsEvent	ehsEvent: EHS Event	true: if the EHS event is handled false: if the EHS event has not been handled	If you don't need EHS, you don't need to implement it, and you can just return false.
onUnhandleKeyEvent	event： unhandled key event	true: if the key event is handled false: if the key event has not been handled

4.3 Key Event Dispatch with Scene System

The key event dispatch of Htek Android SDK is different with the Android standard

4.4 Scene Priority

The valid value of scene priority is between 0 to 100.

Here is a list of the built-in settings.

Priority	Value
SceneManager.SENCE_PRIORITY_MIN	0
SceneManager.SENCE_PRIORITY_LOW	20
SceneManager.SENCE_PRIORITY_MID	40
SceneManager.SENCE_PRIORITY_HIGH	60
SceneManager.SENCE_PRIORITY_EXTRA_HIGH	80
SceneManager.SENCE_PRIORITY_MAX	100

4.5 Built-in Scene

Scene	Priority	Purpose	Lifecycle
Idle	0	Provide a default handle if there is no other scene	Always
Launcher	1	The scene of the launcher app, which is used to handle dialing in the launcher.	From the launcher is displayed until the launcher is overwritten by another apps
Media	20	The scene of playing media.	From the beginning of media paly until the media was ended or was interrupted by another scene.
Commucation	40	The scene of making a conversation on a third-party app.	From the beginning of the conversation until it was ended or was interrupted by another scene.
Voip Call	80	The scene of handling system VoIP call.	From the first VoIP call started until all calls stopped.
Dialpad	100	The scene of handling dialpad event.	From the dialpad displayed until the exited the dialpad or was interrupted by another scene.

5. Key Events

5.1 When app is running in foreground

When the app is running in foreground, the key events dispatching is the same as Android standard.

5.2 When app is running in background

When the app is running in background, the app should has its own SceneClinet with a high priority.

The key events will be sent to the Scene Client firstly, and then be send to the onUnhandleKeyEvent of the Scene Client.

5.3 Key Events list

6. LED

There are two types of LED on Htek Android phone.

Power LED, normally on the top of the phone.
Function key LED contains the Speaker, Headset, Voice Mail, Mute and so on.

6.1 Power LED Manager

The Power LED is aimed at showing the status of the phone. There are four different status now:

Ringing Status
Miss Call Status
Voice Message Status
Active Call Status

The PowerLEDManager is a system service, you can get the instance through this way:

And here are the interfaces of the PowerLEDManager.

6.2 Function Key LED Manager

Function key contains the Speaker, Headset, Voice Mail, Mute and so on.

Different phone models may have different function keys. If you need the LED of a specific function key, please read the model datasheet, or consult Htek.

The manager of Function Key LED is LEDManager. It is also a system service and you can get the instance by the similar way:

The interfaces of LEDManager lists as below:

7. Audio Channel

The interfaces of controlling audio channel are contained in SceneManager. To get the instance of the SceneManger, you can do this:

The below content lists the interfaces related to audio channel controlling.

Note that even without registering your own SceneClient, you can still call the interfaces above. But if you want to get better embedded in the Htek Android phone and provide a better user experience, it is recommended to implement your own.

8. USB headset

The USBHeadsetManager is also a system service, you can get the instance through this way:

Then, you can control the USB headset by the below interfaces:

9. Default Dial App

In AndroidManifest.xml of the app, receive android.intent.action.DIAL and set the priority higher than 0, you can let the app become the default dial app.

Here is an example:

10. Autostart

In AndroidManifest.xml of the app, receive android.intent.action.BOOT_COMPLETED.

Here is an example:

Htek SDK Demo & Library Download

Date	Demo	Library	Revision

Date	Demo	Library	Revision
May 15, 2024	http://fm.htek.com/rs/sdk/demo/MyDialer_20240515.zip	http://fm.htek.com/rs/sdk/package/hlsdk-5.42.1.7.1.32B5.zip	bc1277b5dd6b044f6bef82f03c1fcfec15f624bc