@gnaudio/jabra-node-sdk
v3.6.2
Published
NodeJS SDK for Jabra Devices
Downloads
307
Readme
Jabra Node.js SDK
Table of Contents
- Table of Contents
Versions
Latest STABLE release is distributed on npmjs.com (see changelog for changes and notable defects).
Although this package also contains a library for Windows ARM64, this should be considered as Beta for the moment since it has not received full testing.
In addition, BETA versions may be available on npmjs with a version name ending with "-beta.X" specifier. For such BETA versions,the following applies:
> Disclaimer for Alpha and Beta Software Release
> Please note that this is a copyrighted Jabra Product ((c) 2022 GN Audio A/S) (the “Product”) which is still undergoing final testing before its official release. The Product and all content found on it are provided on an “as is” and “as available” basis. Jabra does not provide any warranties, neither express nor implied, as to the suitability or usability of the Product or any of its content.
> Jabra disclaims liability for any loss, whether direct, indirect, special or consequential, suffered by any person as a result of their use of the Product or the software embedded, and for any claim arising from any injury or damage, including but not limited to, any personal or bodily injury or tangible property damage, arising from or resulting in any way from any alleged defects in the material, workmanship, or performance of the Product, and Company shall indemnify Jabra in respect of any such claims. All usage of the Product is at users’ own risk and the user will be solely responsible for any resulting from such activities.
> Should you encounter any bugs, glitches, dangers, lack of functionality, lack of comfort or other problems with the Product, please let us know immediately so we can rectify these accordingly. Your help in this regard is greatly appreciated.
> The Product is released solely for test use in Company’s organization and must not under any circumstances be distributed to third parties without prior written acceptance from Jabra.
> By using the software, I accept and acknowledge the content herein.`
Pre-requisite
Node.js v10.x through v16.x. Currently, Node.js is not officially supported for Windows ARM64 so in order to use the native ARM64 library on this platform, Node.js should be installed from one of the unofficial builds, e.g. here.
On MacOS:
xcode
&python 3.7
. By default, Python is installed on macOS but make sure correct version(3.7+) is installed. Install Xcode from App store or download it from here.On Windows:
Visual C++ Build Tools
&Python 3.7
. You can install all of these by following any of the below mentioned steps.3.1. During Node.js installation By ticking the checkbox when prompted during Node.js installation for
Tools for Native modules
, this installs bothVisual C++ Build Tools
&Python 3.7
. Note This is prompted only for Windows platform. For other platforms like Linux or MAC, C++ compilation tools has to be installed separately as mentioned in other steps.3.2. Both
Visual C++ Build Tools
&Python 3.7
can also be installed using commandnpm install --global --production --add-python-to-path windows-build-tools
. To know more about this tool, see this link.. Note For executing this command throughWindows Command Prompt
orWindows PowerShell
, they should be ran in Administrator mode.On Linux:
build-essential
package for C++ compilation &Python 3.7
.4.1. 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.Example: The file name should be something like
80-jabra.rules
where the number before the dash indicates in what order the system reads the rules (e.g. if you had another rules file called70-someotherrule.rules
, it would read that one first), the word after the dash is just an identifier of sorts (it could be something other than jabra) and the extension must be.rules
.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
Reattach your Jabra device in order to get new permissions assigned.
All Platforms:
node-gyp
. You can install this using commandnpm install -g node-gyp
. To know more about this, see this linkFor Electron.JS: If you are using
asar
packaging then you may need tounpack
some of the resources used in this module. These resources are native library files i.elibjabra.dll
,libjabra.dylib
&libjabra.so
, which is stored in abuild\Release
folder. By default latest electron builder will automatically unpack, but if it does not work then you can provide below option to your build process. To know more, see this link
"build": {
"asarUnpack": ["node_modules/@gnaudio/jabra-node-sdk"]
}
Installation
This release is published to npm and can be installed via below command.
npm install --save @gnaudio/jabra-node-sdk
Debugging and Logging
Below environment variables are defined for logging and debugging purpose. User can change the values as per preference.
Environment Variable | Value | Description --- | --- | --- LIBJABRA_TRACE_LEVEL | fatal, error, warning(default), info, debug | Log levels LIBJABRA_RESOURCE_PATH | On Mac: ~/Library/Application Support/JabraSDK/ On Windows: %appdata%/Roaming/JabraSDK | This determine the system path where logs and device related files are written.
API Reference
API doc is in html format. See doc folder inside installed module node_modules\@gnaudio\jabra-node-sdk\dist\doc
and open index.html
.
Examples
For all examples, user should first register the app on Jabra developer site to get appID. User should pass this appID to createJabraApplication
in order to initialize the jabra module:
Simple button events example using javascript and plain promises
const j = require("@gnaudio/jabra-node-sdk");
j.createJabraApplication('123').then((jabra) => { // 123 is appID here
jabra.on('attach', (device) => {
console.log('Press any key on Jabra device ' + device.deviceName);
device.on('btnPress', (btnType, btnValue) => {
console.log('New input from device is received: ', j.enumDeviceBtnType[btnType], btnValue);
});
});
});
Simple button events example using typescript and plain promises
import { createJabraApplication, enumDeviceBtnType, enumHidState } from '@gnaudio/jabra-node-sdk';
createJabraApplication('123').then((jabra) => { // 123 is appID here
jabra.on('attach', (device) => {
console.log('Press any key on Jabra device ' + device.deviceName);
device.on('btnPress', (btnType, btnValue) => {
console.log('New input from device is received: ', enumDeviceBtnType[btnType], btnValue);
});
});
});
Ring example using typescript and plain promises
This example shows how to ring a Jabra device
import { createJabraApplication, JabraError } from '@gnaudio/jabra-node-sdk';
createJabraApplication('123').then((jabra) => { // 123 is appID here
jabra.on('attach', (device) => {
device.isRingerSupportedAsync().then( (supported) => {
if (supported) {
device.ringAsync().then ( () => {
console.log('ringing');
}).catch ((err: JabraError) => {
console.log('ring failed with error ' + err);
}); // ring the device
setTimeout(() => {
device.unringAsync().then(() => {
console.log('stopped ringing');
}).catch ((err: JabraError) => {
console.log('unring failed with error ' + err);
});
}, 5000); // stop ringing the device after 5 second
}
}).catch( (err: JabraError) => {
console.error('Jabra call failed with error ' + err)
});
});
jabra.on('detach', (device) => {
console.log('Device detached with deviceID:', device.deviceID);
// In this demo example, we will auto shutdown once all jabra devices are removed:
let remainingAttachedDevices = jabra.getAttachedDevices();
if (remainingAttachedDevices.length == 0) {
jabra.disposeAsync().then (() => {}); // Cleanup and allow node process to exit.
}
});
});
Multiple device management with typescript and async/await
import { createJabraApplication } from '@gnaudio/jabra-node-sdk';
(async () => {
let jabra = await createJabraApplication('123'); // 123 is appID here
await jabra.scanForDevicesDoneAsync(); // Wait for all pre-attached devices to be scanned.
const deviceInstanceList = jabra.getAttachedDevices();
if (deviceInstanceList.length<2) {
throw new Error('Please make sure 2 jabra devices are attached');
}
const firstDevice = deviceInstanceList[0];
await firstDevice.ringAsync();
const secondDevice = deviceInstanceList[1];
await secondDevice.ringAsync();
// Dispose jabra sdk to enable node process to shutdown.
await jabra.disposeAsync();
})();
Sequence diagrams
These sequence diagrams shows typical uses of the Node.js sdk:
Setup VSCode
The project includes config files for debugging typescript and C++ source files in Visual Studio Code via the C++ extension, for both Windows and Linux. The configuration files work without any modification, provided that you set up your environment first, by installing the necessary tools and defining some environment variable.
To debug a C++ file, open a typescript file referencing the C++ file and start the debugger (Running the debugger on C++ files directly won't work). Make sure the "Run"-dropdown at the top of the debugging-sidebar is set to "Current TS File - native code only (<your operating system>)"
Below, the setup steps for Windows and Linux.
Windows
You can more or less follow the instruction in the VSCode C++ extension guide. Then, you need to make sure all project pre-requisites are installed correctly, and finally set the following environment variables:
Environment Variable | Value | Description --- | --- | --- LIBJABRA_WIN_NODE_GYP_CACHE_PATH | eg. %appdata%\Local\node-gyp\Cache\12.16.3\include\node | Used by the C/C++ extension to resolve include paths LIBJABRA_WIN_CPP_COMPILER_PATH | eg. C:/Program Files (x86)/Microsoft Visual Studio/2019/Professional/VC/Tools/MSVC/14.25.28610/bin/Hostx64/x64/cl.exe | Used by the C/C++ extension to infer the path to the C++ standard library header files
Linux
You can read a more detailed guide on
the VSCode C++ extension page.
The important part is to install a C++ compiler and debugger. The easiest way
is to install build-essential
and gdb
, this way:
sudo apt-get install build-essential gdb
This maks your C++ compiler GCC, and you would likely use the g++
command to
compile.
Then, you need to install the project pre-requisites, and finally export the following environment variables:
Environment Variable | Likely value | Description
--- | --- | ---
JABRA_NODESDK_CPP_COMPILER_PATH | /usr/bin/g++ | Used by the C/C++ extension to infer the path to the C++ standard library header files
JABRA_NODESDK_NODE_GYP_CACHE_PATH | $HOME/.cache/node-gyp/14.4.0 | Used by the C/C++ extension to resolve include paths. NOTE: The final include/node
is added by the configuration and it's not necessary