Interacting with Jabra devices

The API interaction between the application and the Jabra device is generally based on the following:

  • A request/acknowledge pattern for major functions (i.e., offhook/onhook, mute, etc)
  • Synchronous functions for minor operations
  • Informational signals from the device

The library encapsulates all the bit-field manipulation and timing management of the USB HID protocol and provides API functions at different abstraction levels.

Understanding event signals

To make a correct integration of the call control API, you must understand the following concept regarding events:

Events sent from the device to the application are not simple keypresses. There is no one-to-one relation between pressing a button on the Jabra device and the application receiving an event.

Instead, events sent from the device can be triggered in different circumstances and are signals notifying the application that something has happened.

One circumstance can be that the user expresses an intent to do something by interacting with the Jabra device, for example pressing a physical button.

Another trigger can be an acknowledgment to a request from the application or an error condition, such as the headset being out of range from the base station.

Therefore, you cannot interpret events as only button presses.

Request/acknowledge interactions

When integrating, you must pay special attention to the request/acknowledge interactions. Firstly, signals are sent between the application and device, and these interactions require a specific response in return to be completed successfully.

Sending an off-hook request requires a similar acknowledgment in return, otherwise, the off-hook command is ignored. For example:

  1. An off-hook signal sent from the headset requires an acknowledgement from the application in return
  2. An off-hook command sent from the application causes an acknowledgement from the headset in return

Both the signal and the acknowledgement are the same; this is especially important for the off-hook function. If the application is written with a generic keypress handler, then ending a call from the application by sending an on-hook command to the device results in a 'ghost keypress' arriving from the device up to two seconds later.

This, however, is not a keypress/button press, but rather the acknowledgment from the device to the off-hook command from the application.

Reacting to device signals

Jabra devices send signals notifying you when something happens in the Jabra device. For example:

  • The user expresses an intent to do something by interacting with the Jabra device. For example, pressing a button or lifting the boom arm
  • An acknowledgment to a request (e.g., a HOOK_SWITCH signal after your application successfully starts a call)
  • An error condition (e.g., headset out of range from the base station)

Controlling the device state

The call control mechanism of Jabra devices is a state machine. For the most part, the application is in full control of the state of the headset.

Changing states, for example on-hook to off-hook or not-ringing to ringing, is generally controlled by the application, not the Jabra device.

In other words: the application is the leader; the Jabra device is the follower.

The following is a simplified example using off-hook and on-hook state:

  • Your application gets an incoming call and sends a ring signal to the headset. The user then presses the answer call button on the headset to take the call. Following a conversation, the user ends the call by pressing the end call button on the headset again.

    This is illustrated in the following diagram: 
sequenceDiagram
    participant User as User
    participant App as Application
    participant Device as Headset

    App -) Device: Ringer = 1
    Note over Device: Headset is ringing
    User -->> Device: Accepts call by pressing the 'answer' button
    Note over Device: Headset sends a signal
    Device ->> App: Hook Switch = 1
    Note over App: App must acknowledge<br>this signal.
    App -) Device: Hook Switch = 1
    App -) Device: Ringer = 0

    Note over User,Device: Call in progress...

    User -->> Device: Ends call by pressing the 'end' button
    Note over Device: Headset sends a signal
    Device -) App: Hook Switch = 0
    Note over App: App must acknowledge<br>this signal.
    App -) Device: Hook Switch = 0

From a device integration point of view, the following sequence occurs after the application sends a ring signal to the headset and the user presses the answer button:

  1. The headset sends an off-hook signal (HOOK_SWITCH = 1) to the application and waits for the application to respond with instructions
  2. The application then sends an off-hook acknowledgment (HOOK_SWITCH = 1) to the headset to acknowledge the signal
  3. The call is active - The user has a conversation
    This is the result of the acknowledgment
  4. The headset sends an on-hook signal (HOOKSWITCH = 0) to the application and waits for the acknowledgment
  5. The application then sends an on-hook acknowledgment (HOOKSWITCH = 0) to the headset to acknowledge the signal
    The call state is inactive - The call is terminated

Moreover, if the sequence occurs the other way round, i.e., the user answers the call by pressing a virtual button on the application User Interface (UI), the application sends an off-hook signal to the headset, and the headset then returns an acknowledgment.

Setting the ringer ON/OFF

Notifies that there is an incoming call. This is an important signal as it is used to notify of an incoming call and can have different effects in different scenarios.

For example, a device might respond with a flashing green LED whilst your application might play its own ringtone.

Signals and the current operational state

Your application does not have to react to all signals received from the device and must ignore interactions that are out of context from the situation at hand.

For example:

In the case that your application receives an incoming call and sends a ring signal to a headset, then the expected message from the headset is an acceptance or a rejection.

In this scenario, either of the two is an expected return message, however, if your application does not have an incoming call, nor has it sent a ring signal to the headset, then it should not react to any off-hook signals from the headset.

Situations with out-of-context messages can happen for various reasons such as interference from other applications.

It is strongly recommended that your application does not react to unexpected off-hook events, despite this being allowed, it is likely to cause interference with other applications or Unified Communication (UC) clients on the client's computer.

For example, an application can react to an unexpected off-hook signal from a device; interpreting the off-hook signal as a desire by the user to make an outgoing call, the application then shows a dial-pad on the screen and activates a dial-tone in the headset.

However, the signal was sent as an acknowledgment from the device to a different application and your application should not react to it.