1 Introduction

Jabra SDK V2 is a shared object library (so), which provides interfaces to the following functionalities in Jabra devices:

  • Device settings: Allows the user to view and change the settings of the connected Jabra device.
  • Remote call control (RCC) : Allows the user to perform functionalities using the connected Jabra device such as:
    • Send and receive HID reports to and from the device.
    • Answer and end calls.
    • Mute and unmute calls.
    • Receive ringtone for incoming calls.
    • Hold and resume calls.
    • Manually control the audio.
  • Getting the serial number and battery status, if supported by the device.
  • Button configuration (button takeover and remote MMI).
  • Child device support with Jabra Link 360 and Jabra Link 370.
  • Busylight indication.
  • Concurrency support for multiple applications of SDK.

The SDK is built as a shared object library with C interfaces.

1.1 Abbreviations and acronyms

Acronym Description
API Application Programming Interface
HID Human Interface Device
SDK Software Development Kit
IDE Integrated Development Environment
USB Universal Serial Bus
RCC Remote Call Control
MMI Man Machine Interface

1.2 SDK installation

The Jabra Linux SDK release consists of a zip archive containing the following top level directories:

  • Demo – demo application and source code.
  • Doc – installation guide and release notes.
  • Library – shared object libraries and header files required for development.
  • Readme text file.

To unzip the zip archive execute:

unzip JabraLibLinux.zip

The directory contains the following assets:

Assets Description
readme.txt Provides information on Jabra SDK V2.
doc/Jabra_SDK_V2_User_Guide_Linux_1.0.pdf User Guide and API documentation.
doc/Jabra_SDK_V2_API_Doc.chm Doxygen generated API documentation, use kchmviewer to view.
doc/ReleaseNotes.txt Release information and list of supported devices.
library/[disto]/[arch]/libjabra.so.1.0.11.1 Jabra SDK shared library for [disto] and [arch].
library/headers/JabraNativeHid.h Header file defining the RCC APIs.
library/headers/JabraDeviceConfig.h Header file defining the dynamic setting APIs.
library/headers/Common.h Header file defining the common interfaces used across Jabra SDK V2.
demo/[disto]/JabraDemo Demo application.
demo/src/JabraDemoQt Demo application source code (Qt Creator project).

[disto] is Linux distribution e.g. Ubuntu

[arch] is processor architecture e.g. 32-bit

1.2.1 Supported Jabra devices

The following Jabra devices are supported by the SDK:

  • Jabra Pro 9470, Jabra Pro 9460, Jabra Pro 9450, Jabra Biz 2300, Jabra Motion Office, Jabra Evolve 65 USB, Jabra Biz 2400 II CC, Jabra Pro 930, Jabra Pro 935 (single and dual), Jabra Pro 925 (single and dual), Jabra Evolve 40/80, Jabra Link 265, Jabra Evolve 30 II, Jabra Evolve 20, Jabra Biz 1500, Jabra Biz 2400 II, Jabra Evolve 30, Jabra Link 260, Jabra Evolve 75.
  • Jabra Motion UC (over Bluetooth).
  • Jabra Link 360 and Jabra Link 370.
  • Jabra Speak 410, Jabra Speak 510, Jabra Speak 710, Jabra Speak 810.
  • Jabra Link 230, Jabra Link 850, Jabra Link 860 => only settings applicable.

Note: The headset may be wireless but the connection to the system must be via USB (e.g. using a Jabra Link 360 Bluetooth USB Adapter). In present scope, the library does not support Jabra Bluetooth headsets that are directly connected to the Linux system via Bluetooth.

1.2.2 Prerequisites

The prerequisites for the SDK are:

  • linux-gate.so.1
  • libasound.so.2
  • libudev.so.1
  • libssl.so.1.0.0
  • libcrypto.so.1.0.0
  • libz.so.1
  • libstdc++.so.6
  • libm.so.6
  • libgcc_s.so.1
  • libc.so.6
  • libdl.so.2
  • libpthread.so.0
  • librt.so.1
  • ld-linux.so.2 (32-bit), ld-linux-x86-64.so.2 (64-bit)
  • libresolv.so.2
  • libselinux.so.1
  • libcap.so.2
  • libpcre.so.1

1.2.3 Udev rules

To be able to communicate with Jabra devices with non-root privileges it is required to create a udev rule for Jabra devices. Place the udev rule in /etc/udev/rules.d, and follow naming guidelines for udev files. The contents of the file are:

ATTRS{idVendor}=="0b0e", MODE="0666", GROUP="users"

After creating the udev file (as root), reload the udev rules using:

sudo udevadm control --reload

1.3 Developing an application using Jabra SDK V2

1.3.1 System requirements

  • Linux distribution: Ubuntu 17.04 LTS (32-bit or 64-bit)
  • Qt Creator: Only required for demo code.
  • Network connection

1.3.2 Library interfaces

1.3.2.1 Common.h: Common interfaces for devices

API name Description
Jabra_GetVersion Gets the version of the SDK library.
Jabra_SetAppID Application should set the application name using this interface. The Client ID/App ID must be obtained by registering to Jabra portal by App developers. This is a mandatory step, which needs to be done before initialization. If not, callbacks will not be registered with SDK.
Jabra_Initialize Initializes the Jabra library. Argument details for the function are described here: Library Initialization.
Jabra_Uninitialize Performs cleanup of library memory.
Jabra_IsFirstScanForDevicesDone Checks if device is scanned during initialization. It is recommended to register for the corresponding callback during initialization.
Jabra_IsDeviceAttached Checks if a device is connected. It is recommended to register for the corresponding callback during initialization.
Jabra_GetAttachedJabraDevices Gets the list of connected Jabra devices.
Jabra_GetBatteryStatus Queries the current battery status for the charging state and indication of low battery. Only supported by devices with a battery.
Jabra_GetSerialNumber Returns the serial number of the specified Jabra device. The serial number is provided by an online Jabra service and therefore requires network access.
Jabra_GetFirmwareVersion Returns the firmware version of the specified Jabra device.
Jabra_GetDeviceImagePath Gets the image path of the connected device. The image is provided by Jabra Cloud service (and subsequently stored in the local directory of the device) and therefore requires network access for the first time.
Jabra_GetDeviceImageThumbnailPath Gets the thumbnail image of the device. The image is provided by Jabra cloud service (and subsequently stored in the local directory of the device) and therefore requires network access for the first time.
Jabra_FreeDeviceInfo Frees the information structure members of the device. This is called by the application right after handling the device attach event.
Jabra_IsLocked Checks whether the device is locked.
Jabra_GetLock Acquires lock for a particular device. It should be ensured that this API is called before performing any action on the device.
Jabra_ReleaseLock Releases the lock for a particular device.
Jabra_ConnectToJabraApplication Integrates softphone app to Jabra applications like Jabra Direct (JD).
Jabra_DisconnectFromJabraApplication Disconnects the Jabra SDK application from Jabra Direct.
Jabra_SetSoftphoneReady Sets the softphone to ready.
Jabra_IsSoftphoneInFocus Indicates whether the softphone is in focus.
Jabra_SetBTPairing Sets the Bluetooth device in pairing mode.
Jabra_SearchNewDevices Queries for available Bluetooth devices that are turned on, within range, and ready to connect.
Jabra_StopBTPairing Stops the search for available Bluetooth devices.
Jabra_SetAutoPairing Enables/disables auto pairing. When a Bluetooth adapter is plugged into the PC it will attempt to connect with the last connected Bluetooth device. If it cannot connect, it will automatically search for new Bluetooth devices to connect with if auto pairing is set.
Jabra_GetAutoPairing Queries whether auto pairing mode is enabled or disabled.
Jabra_ClearPairingList Clears the list of Bluetooth devices that are paired with the Bluetooth adapter.
Jabra_ConnectBTDevice Connects/Reconnects Bluetooth device with the Jabra Bluetooth adapter. Ensure the Bluetooth device is turned on and within range.
Jabra_ConnectNewDevice Connects with Bluetooth device and applies specified device details.
Jabra_DisconnectBTDevice Disconnects Bluetooth device from Bluetooth adapter.
Jabra_GetConnectedBTDeviceName Queries the name of Bluetooth device that is connected with Bluetooth adapter.
Jabra_GetErrorString Returns the error string from the error status.
Jabra_IsBusylightSupported Checks if busylight is supported by the device.
Jabra_GetBusylightStatus Checks the status of busylight.
Jabra_SetBusylightStatus Enables/Disables the busylight status.
Jabra_RegisterBusylightEvent Registers callback to receive busylight events.
Jabra_RegisterPairingListCallback Registers callback to receive list of devices paired with Bluetooth adapter.
Jabra_IsPairingListSupported Checks if pairing list is supported by the device.
Jabra_GetPairingList Gets the list of devices that have been paired with Bluetooth adapter.
Jabra_FreePairingList Frees the memory allocated for the list of paired devices.
Jabra_ConnectPairedDevice Connects a device that has already been paired.
Jabra_DisConnectPairedDevice Disconnects a paired device.
Jabra_ClearPairedDevice Clears the specified device from list of paired devices.
Jabra_IsRemoteMMISupported Checks if remote MMI feature is supported by the device.
Jabra_GetButtonFocus Configures the remote MMI events for a device.
Jabra_ReleaseButtonFocus Releases the remote MMI events configured in the device.
Jabra_GetSupportedButtonEvents Gets the supported remote MMI for a device.
Jabra_FreeButtonEvents Releases the memory allocated for the button events.
Jabra_RegisterForGNPButtonEvent Registers callback function to get notified on GNP button events.

1.3.2.2 JabraDeviceConfig.h: Interfaces for device settings

API name Description
Jabra_GetSettings Gets the settings for the connected Jabra device. Returns pointer to the device settings structure containing all settings for a particular device.
Jabra_FreeDeviceSettings When the device setting is requested by the application, memory needs to be freed by calling this API.
Jabra_SetSettings Updates/Sets the setting details of the connected Jabra device. Returns a return code to indicate whether settings were applied successfully.
Jabra_FreeString When the device image path is requested, application needs to release the memory by calling this API to prevent memory leak.
Jabra_GetFailedSettingNames Queries the list of failed setting names.
Jabra_FreeFailedSettings Prevents memory leak by releasing memory of failed setting names.
Jabra_IsFactoryResetSupported Returns whether the device supports factory reset.
Jabra_FactoryReset Restores the factory settings of the device.
Jabra_FreeDeviceSettings Prevents memory leak by releasing memory allocated to device settings.

1.3.2.3 JabraNativeHID.h: RCC interfaces

API name Description
Jabra_IsOffhookSupported Returns true if off hook is supported for a specific Jabra device.
Jabra_SetOffhook Sets the specified device off hook/on hook.
Jabra_IsRingerSupported Returns true if ringer is supported for a specific Jabra device.
Jabra_SetRinger Sets ringer on/off for the specified device.
Jabra_IsMuteSupported Returns true if ringer is supported for a specific Jabra device.
Jabra_SetMute Sets mute on/off for the specified device.
Jabra_IsHoldSupported Returns true if hold is supported for a specific Jabra device.
Jabra_SetHold Sets hold on/off for the specified device.
Jabra_IsOnlineSupported Returns true if online mode is supported for a specific Jabra device.
Jabra_SetOnline Turns online mode on/off for a wireless headset. Online mode opens an audio link (radio link) between a base/Bluetooth adapter and a headset.
Jabra_WriteHIDCommand Sends HID output reports with device ID, Usage Page, and Usage. This function is for advanced users. It is recommended to use the dedicated functions: Jabra_SetOffHook, Jabra_SetRinger, Jabra_SetMute, Jabra_SetHold, and Jabra_SetOnline

1.3.3 Steps to initialize the library

The following steps are mandatory for initializing the Jabra SDK:

  • A valid application ID key must be set to SDK using Jabra_SetAppID API prior to calling Jabra_Initialize. If the application ID key is not set, the SDK initialization will fail i.e. Jabra_Initialize will return false. Note, the application ID key must be obtained by the application developer by registering at the Jabra portal: https://developer.jabra.com and requesting an application ID key.
  • The library is initialized using the Jabra_Initialize API. The arguments consist of pointers to five callback functions and an instance number.
Parameter Description
FirstScanForDeviceDoneFunc Callback function that is called when the library has finished the initial scanning for Jabra devices.
DeviceAttachedFunc Callback function that is called when a new Jabra device is connected or the library has been initialized and found a Jabra device.
DeviceRemovedFunc Callback function that is called when a Jabra device is removed.
ButtonInDataRawHidFunc Callback function that is called when new input data has been received. Data is raw HID data.
ButtonInDataTranslatedFunc Callback function that is called when new input data has been received. Data is represented at a higher level of abstraction than the raw HID data.
Instance Optional instance number. Can be 0 if not used.

Important: As callbacks are executed in SDK context, the application must perform only small/lightweight activity. For bulky functionality, it should continue using the application thread.

Library initialization must be done only once. Before process shutdown, Jabra_Uninitialize() must be called in order to perform memory cleanup.

Note: For RCC to be reflected in a Jabra device, HID button inputs from the device to the PC must be acknowledged by the application. Otherwise the next button input transition will not be detected by the system. A button input is acknowledged by setting the corresponding button output to the same value as the input value.

For example, when you receive an OffHook = true, you must call Jabra_SetOffHook (deviceId, true). After acknowledging the input you can set the new desired state.

For example, to reject the off-hook request you could call Jabra_SetOffHook (deviceId, false).

1.3.4 32-bit and 64-bit support

The library is delivered in a 32-bit version and in a 64-bit version. Application developers must make sure that linking is done to the version corresponding to the application.

1.3.5 Network connection

For most of the SDK functionality a network connection is required. During device discovery, information about the device is retrieved from Jabra server and stored locally. Default storage location is /tmp/Resources which can be changed by setting the LIBJABRA\_RESOURCE\_PATH environment variable.

1.3.6 Logging

The SDK provides logging to troubleshoot issues. By default, the log level is set to warning. You can alter logs by setting the environment variable LIBJABRA\_TRACE\_LEVEL from the command prompt. Other supported log levels are invalid, fatal, and error. The logs are sent to stdout.

1.3.7 Points to remember

  • As multiple applications can access the same device at the same time, the device must be locked by the application before performing operations such as call control, view settings, apply settings. An RCC or setting operation will not be able to perform unless the device is locked. The application must unlock the device after usage, so that other applications can access the device.
  • Concurrency is maintained between all the applications that use the Jabra SDK library and Jabra Direct.
  • Dependent settings are special settings that are dependent on other settings. For example, based on the value of one setting, other setting(s) may become enabled or disabled.
    • The application needs to handle dependency settings, based on the flag isDepedentsetting in the exposed settingInfo structure.
    • ListKeyValue (structure) in each setting (mainly for drop down control settings) will contain a list of possible values. In addition, ListKeyValue will also have details of dependent settings.
    • For each value in the ListKeyValue structure,
      • dependentcount will have the information for how many settings are dependent on this value. It will be zero, if no settings are dependent.
      • If dependentcount is not zero, then DependencySetting (structure) will have the details of the settings that are dependent.
      • DependencySetting will have setting GUID and a flag to indicate whether to enable or disable it.
      • For some settings that are disabled because of dependency, the value needs to be changed to the default value. dependentDefaultValue in settingInfo structure will have the default value.
  • PC settings are settings that the application needs to handle because they are not device settings. And the exposed settingInfo structure has the flag, isPCsetting, to identify whether it is a PC setting.
  • Any given string input should be terminated with a null character.
  • Validations such as regular expression, minimum length, or maximum length for string input, need to be handled by the application.
  • The button configurations done for remote MMI would be cleared/reset when unplugging the device or exiting the application. The application should perform the button configuration again the next time it starts up.

1.3.8 Bluetooth adapter devices

  • The call control is not supported for USB Bluetooth adapters (such as Jabra Link 360) unless they are paired with a Bluetooth headset.
  • Settings of Bluetooth headsets can be accessed through the USB adapter when paired.
  • Only USB devices can be reset to default factory settings.

1.4 Sample application code

Both source code and binary files for the demo application are packed along with this SDK. The demo application is a Qt application built using Qt Creator. The test program demonstrates library initialization, usage of remote call controls, and device setting features using Jabra SDK V2.

Figure 2(a): Device Information View

Figure 2(a): Device Information View

Figure 2(b): Device information View after locking the device

Figure 2(b): Device information View after locking the device

Figure 2(c): Device Settings View

Figure 2(c): Device Settings View

Figure 2(d): Call Control View

Figure 2(d): Call Control View

Figure 2(e): Device information when Bluetooth adapter is connected

Figure 2(e): Device information when Bluetooth adapter is connected

Figure 2(f): Device connected to PC using Bluetooth adapter

Figure 2(f): Device connected to PC using Bluetooth adapter

Figure 2(g): Bluetooth pairing when headset is connected to PC using Bluetooth adapter

Figure 2(g): Bluetooth pairing when headset is connected to PC using Bluetooth adapter

Figure 2(h): Mapping of button events with user actions

Figure 2(h): Mapping of button events with user actions

1.5 Development setup

1. Install Qt Creator (IDE):

sudo apt-get install qtcreator (Ubuntu)

sudo apt-get install libqt5-creator (openSUSE)

2. Create links to the SDK interface and shared object (here Ubuntu, 64-bit):

cd JabraLibLinux/demo/JabraDemoQt ln -s ../../library/headers/*.h . ln -s ../../library/ubuntu/64-bit/libjabra.so.1.0.11.1 . ln -s libjabra.so.1.0.11.0 libjabra.so

3. Open the demo project file:

qtcreator JabraLibLinux/demo/JabraDemoQt/JabraDemo.pro

4. Configure project:

Press the Configure Project button.

Press the Configure Project button.

5. Rebuild project:

Select Build, Rebuild All.

Figure 3: Qt Creator – view of project compilation

Figure 3: Qt Creator – view of project compilation

The demo is now executable.

1.6 Sequence diagrams

This section contains sequence diagrams for the most common use cases. Using the same patterns such as the one described here, enables more advanced use cases.

1.6.1 Get device settings

The following diagram illustrates how to get settings from the device using this library.

Figure 5: Get device settings

Figure 5: Get device settings

1.6.2 Set device settings

The following diagram illustrates how to set settings from the application to the device, using this library.

Figure 6: Set device settings

Figure 6: Set device settings

1.6.3 Off-Hook

The following diagrams illustrate how to implement off-hook/on-hook scenarios in your softphone using this library.

1.6.3.1 Softphone initiated

Figure 7: Softphone OffHook initiation

Figure 7: Softphone OffHook initiation

1.6.3.2 User initiated

Figure 8: User OffHook initiation

Figure 8: User OffHook initiation

1.6.4 Mute

The following diagrams illustrate how to implement mute/unmute scenarios in your softphone using this library.

1.6.4.1 Softphone initiated

Figure 9: Softphone mute toggle

Figure 9: Softphone mute toggle

1.6.4.2 User initiated

Figure 10: User mute toggle

Figure 10: User mute toggle

1.6.5 Hold

The following diagrams illustrate how to implement hold/resume call scenarios in your softphone using this library.

1.6.5.1 Softphone initiated

Figure 11: Softphone hold/resume

Figure 11: Softphone hold/resume

1.6.5.2 User initiated

Figure 12: User hold/resume

Figure 12: User hold/resume

1.6.6 Remote MMI – button takeover

Figure 13: Button takeover

Figure 13: Button takeover

1.6.7 Child device support

Figure 12: Child device handling

Figure 12: Child device handling

2 Third party license notice

2.1 License notice for libjsoncpp

Copyright (c) 2007-2010 Baptiste Lepilleur

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Updated license information can be found here.

2.2 License notice for pugixml

This library is distributed under the MIT License:

Copyright (c) 2006-2015 Arseny Kapoulkine

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Updated license information can be found here.

2.3 License notice for libcurl

The MIT License (MIT)

Copyright (c) 2015 Andreas Rumpf

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Updated license information can be found here.