Plantronics Developer Connection - API

Radio Link Quality Data

jendeeda — Tue, 10 Apr 2018 17:26:50 +0000

Keywords:

API

One use case for Radio Link Quality APIs is how third-party call quality diagnostics tools can be enhanced by knowing what’s going on at the first three feet. Specifically, how can IT troubleshoot the Bluetooth link between headset and USB adapter?

The Radio Link Quality API provides key information that can be used to gain true insights into the Bluetooth radio link:

Quality impairment score (QIS) is a measure of the user’s average call quality based on the percentage of packet errors and related data. The higher the impairment score, the lower the quality of the user’s average call experience. For example, a QIS of 0 for a given user would indicate that all calls were free from any detectable errors, while a QIS of 100 for a user would indicate that all calls suffered a complete loss of call audio. QIS is reported once for every call.
Receive signal strength indication (RSSI) is a measure of the absolute strength of the Bluetooth signal at the headset. It measures the amount of power received at the headset antenna measured in dBm. dBm (sometimes dBmW or decibel-milliwatts) is an abbreviation for the power ratio in decibels (dB) of the measured power referenced to one milliwatt (mW). The RSSI is reported every four seconds during a call.
Link figure of metric (LFOM) is a calculated guess on what the user is hearing based on the radio link quality. For each packet of data across the link there is an indication of any corruption in the data. This information is used to calculate sample error rates, which are then further processed over a period of time, creating the LFOM metric. Zero means that there were no valid data across the link; five means there were no errors. The LFOM is reported every four seconds during a call.

With more people working remotely, in locations such as coffee shops and airport lounges, these three measurements now make it possible to quickly determine if the environment and its associated interference on the Bluetooth radio link is the root cause of the user’s audio issues.

HubRESTSample – a new C++ REST API Sample for PDC

lcollins — Tue, 06 Jun 2017 14:00:33 +0000

Keywords:

C++ REST API Hub Manager Pro

This new sample code illustrates seamless consumption of Plantronics out-of-proc REST API from C++ code!

Location of full sample code: https://github.com/pltdev/pdc/tree/master/C%2B%2B%20REST%20Sample

Key Benefits

Supports Plantronics Manager Pro configuration
- Works with Plantronics Hub via “out-of-proc” REST API
Supports multi-softphone & multi-device configurations
Same code for both Windows and Mac environments
Follows same model as the other PDC samples for C#, Java, JavaScript, etc
- Providing clear illustrations of basic call control
Illustrates support for resilience to Hub restarting and device changing

Design Overview

The design of the sample uses a threaded (active) object called HubRESTLib, that handles all the REST HTTP requests and resilience (reconnects). It allows Hub SDK commands to be issued and events from Hub SDK to be received via the callbacks of the IHubRestLib interface.

HubRESTSample 1.png

*POCO Libraries were used in this sample for HTTP requests and JSON parsing functionality, but any libraries could be used

The sample code in action…

Note: with this integration sample it is just 1 line of C++ code to connect to Plantronics REST API (instantiate HubSDKConnector object), and 1 line of code to cleanup (delete the object).

Once instantiated you are then able to submit API commands (e.g. IncomingCall, etc) to this object using a HubSDKAction object, as shown below. Some of the actions take parameters, e.g. callid, etc:

Note: you will need the full sample code to use this, obtain from here: https://github.com/pltdev/pdc/tree/master/C%2B%2B%20REST%20Sample

#include <iostream>
#include <string>
#include "HubSDKConnector.h"

using namespace std;

void ShowMenu()
{
	cout << endl;
	cout << "plt sample menu" << endl;
	cout << "--" << endl;
	cout << "1 - ring/incoming call" << endl;
	cout << "2 - outgoing call" << endl;
	cout << "3 - answer call" << endl;
	cout << "4 - hold call" << endl;
	cout << "5 - resume call" << endl;
	cout << "6 - mute call" << endl;
	cout << "7 - unmute call" << endl;
	cout << "8 - end call" << endl;
	cout << "0 - quit" << endl;
	cout << endl;
	cout << "> ";
}

int GetCommand()
{
	string cmdstr;
	int cmd;
	getline(std::cin, cmdstr);
	if (cmdstr.empty()) cmd = -1;
	else
	{
		try
		{
			cmd = atoi(cmdstr.c_str());
		}
		catch (exception const & e)
		{
			cout << "error : " << e.what() << endl;
			cmd = -1;
		}
	}
	return cmd;
}

int main()
{
	cout << "C++ Plantronics Hub REST Sample" <<  endl;
	bool quit = false;
	int callid = 0; 

	HubSDKConnector * hubSDK = new HubSDKConnector(); // Connect to the Plantronics REST API

	while (!quit)
	{
		ShowMenu();
		int cmd = GetCommand();
		HubSDKAction action;
		switch (cmd)
		{
			case 1:
				callid++;
				// inform Plantronics my app has an incoming (ringing) call
				cout << "Performing incoming call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_IncomingCall;
				action.callid = callid; // numeric id to uniquely identify each call
				action.contactname = "Bob%20Smith"; // optional contact name for display devices, e.g. Calisto 240, note: needs url encoding e.g. spaces are %20, etc.
				hubSDK->DoHubSDKAction(action);
				break;
			case 2:
				callid++;
				// inform Plantronics my app has an outgoing call
				cout << "Performing outgoing call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_OutgoingCall;
				action.callid = callid;
				action.contactname = "Bob%20Smith";
				hubSDK->DoHubSDKAction(action);
				break;
			case 3:
				// inform Plantronics my app has now answered an incoming (ringing) call
				cout << "Answering call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_AnswerCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 4:
				// place call on hold
				cout << "Holding call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_HoldCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 5:
				// resume the call
				cout << "Resuming call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_ResumeCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 6:
				// mute the headset (note for wireless products, audio link must be active)
				cout << "Setting headset mute = true";
				action.ActionType = HubSDKActionType_SetMute;
				action.mutestate = true;
				hubSDK->DoHubSDKAction(action);
				break;
			case 7:
				// unmute the headset (note for wireless products, audio link must be active)
				cout << "Setting headset mute = false";
				action.ActionType = HubSDKActionType_SetMute;
				action.mutestate = false;
				hubSDK->DoHubSDKAction(action);
				break;
			case 8:
				// inform Plantronics my app has now terminated the call
				cout << "Terminating call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_TerminateCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 0:
				quit = true;
				break;
			default:
				cout << "Unrecognised menu choice." << endl;
				break;
		}
	}

	delete hubSDK; // Cleanup the Plantronics REST API

	return 0;
}

View of the application running:

It presents a menu allowing you to try out the basic call control commands, and see connection information and notifications from Plantronics Hub and the headset:

HubRESTSample 3.png

Advanced SDK Topic: Ensuring Resilience with Plantronics COM API

lcollins — Thu, 27 Apr 2017 10:02:55 +0000

Keywords:

resilience resilient COM API plantronics SDK

Author: Lewis Collins, Plantronics

When using the Plantronics COM API how do you ensure the connection to the Plantronics Hub software is working?

What if the user accidentally shuts down Plantronics Hub (or it crashes), or user upgrades it which would also result in it shutting down and starting again. Would your software re-connect to the COM API automatically?
What if Plantronics Hub is not installed, will your software still attempt to connect to it, resulting in long COM timeout? (Will this timeout impact your applications performance)?

On this page I present a solution to these problems that ensures resilience of connection to Plantronics COM API covering the scenarios mentioned above.

The approach is as follows:

Move all the code that connects / interacts with Plantronics COM API into a seperate class with its own thread. Now Plantronics COM API interaction is done on its own thread it will not impact your application's performance even if a COM timeout / exception occurs. This class is called HubSDKConnector.
In HubSDKConnector add a watchdog timer that polls (attempts to use) the COM API every 5 seconds. If the connection fails (exception occurs) it will attempt to re-establish connection. Note, this interval is slowed to 60 seconds if HubSDKConnector detects that a Plantronics Hub upgrade is in progress (Hub installer is running). This corner case allows user to upgrade Hub without your application attempting to request COM API again, which would respawn the Hub EXE before install operation completes, therefore requiring a reboot to complete install - this is not desirable

Code for this sample: click here>> (note: you must be registered and signed in to access this).

The code is functionally the same is as the basic C# sample (in Get Started, C# Tab), with the integration code moved into HubSDKConnector.cs. The code is in C#, but the same concept could be implemented in C++ with the Plantronics COM API.

Here is a screenshot of it running.

What do you think of this solution? Let me know your feedback or questions using the form at the bottom of the page. Have fun! :-)
Lewis.

ResilientPLTDemo.png

Implement Proximity Detection (Near/Far) with Voyager Focus UC/5200 UC and BT600 dongle

lcollins — Fri, 02 Sep 2016 13:32:28 +0000

Keywords:

proximity near far SDK API integration 5200 uc focus voyager bt600

Greetings!

The Plantronics SDK feature for receiving proximity events when headset is Near or Far from PC can still be used with the new line of products based on BT600 dongle (Voyager Focus UC, Voyager 5200 UC).

**Full sample code for this article located here**: /system/files/FocusProximityExample.zip
(You must be logged in to download the file).

You can register for Proximity with these devices using the latest SDK version 3.8.51454.38364, located here: http://developer.plantronics.com/windows

You need to register for DeviceListener HeadsetStateChanged events, like this:

m_deviceListenerEvents.onHeadsetStateChanged += m_deviceListenerEvents_onHeadsetStateChanged;

Then you register to receive proximity:

m_hostCommandExt.EnableProximity(true); // enable proximity reporting for device
m_hostCommandExt.RequestProximity();    // request to receive asyncrounous near/far proximity event to HeadsetStateChanged event handler.

When you handle the HeadsetStateChanged events you can see if you are near or far:
(Note, there are a couple of edge cases for the older legacy wireless products where you need to re-register for proximity on InRange and ProximityDisabled, these do not apply to BT600).

        private static void m_deviceListenerEvents_onHeadsetStateChanged(COMDeviceListenerEventArgs args)
        {
            switch (args.HeadsetStateChange)
            {
                case DeviceHeadsetStateChange.HeadsetStateChange_Near:
                    Console.WriteLine(">>Headset NEAR (via deviceListener event)");
                    break;
                case DeviceHeadsetStateChange.HeadsetStateChange_Far:
                    Console.WriteLine(">>Headset FAR (via deviceListener event)");
                    // this is NOT working. for now use workaround in m_deviceComEvents_onDataReceived below.
                    break;
                case DeviceHeadsetStateChange.HeadsetStateChange_ProximityDisabled:
                    // Immediately re-enable proximity
                    RegisterForProximity(true);
                    break;
                case DeviceHeadsetStateChange.HeadsetStateChange_InRange:
                    // Immediately re-enable proximity
                    RegisterForProximity(true);
                    break;
            }
        }

Finally, there is a known issue with the current SDK version that we need to workaround to get the "Far" event. (the "Far" event is not currently reported via DeviceListener, expected to be implemented in later SDK release 3.9).

For the workaround register to receive "raw" headset data events:

            m_deviceComEvents = m_activeDevice as ICOMDeviceEvents_Event;
            m_deviceComEvents.onDataReceived += m_deviceComEvents_onDataReceived;

Then when you receive raw data event, use the code below to work out when the device is "Far":

        private static string byteArrayToString(byte[] p)
        {
            StringBuilder b = new StringBuilder();
            foreach (byte x in p)
                b.Append(x.ToString("X2"));
            return b.ToString();
        }

        private static void m_deviceComEvents_onDataReceived(ref object report)
        {
            byte[] reportbuf = (byte[])report;
            string datareporthex = byteArrayToString(reportbuf);

            // use raw device data to implement proximity Far event
            string command = datareporthex.Substring(18, 4);
            switch (command)
            {
                case "0806":
                    string nearfar = datareporthex.Substring(26, 2);
                    if (nearfar == "00")    // this workaround is required with 3.8 for now as Far is not done in Spokes SDK (will be in 3.9)
                    {
                        Console.WriteLine(">>Headset FAR (via raw device data event)");
                    }
                    break;
            }
        }

Here is a picture of the code in action:

focus proximity example.png

That's it! Have fun with proximity
Lewis.

**Full sample code for this article located here**: /system/files/FocusProximityExample.zip

Integrate Plantronics REST API from Go

lcollins — Thu, 01 Sep 2016 12:06:32 +0000

Keywords:

go SDK API REST plantronics

Greetings!

I have recently created an example integrate from the Go language to the Plantronics REST API.

It is still a work in progress but it is functional for receiving device, session and session manager events. (For further guidance on the REST Service API URLs you can use, check out the Java and JavaScript integration samples elsewhere on this site).

Obtain Go language (golang) from here: https://golang.org/

Obtain the sample code from here: http://developer.plantronics.com/system/files/plt%20go%20sample.zip
Note: you must login to this site to download that file.

Here is how you connect to Plantronics from Go (code snippet):

func httpGetJSON(url string) (map[string]interface{}) {
    var dat map[string]interface{}
    resp, err := http.Get(url)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    if b, err2 := ioutil.ReadAll(resp.Body); err2 == nil {
        if err := json.Unmarshal(b, &dat); err != nil {
            log.Fatal(err)
        }
    }
    return dat
}

func connectToPlantronics() {
    fmt.Print("Connecting to Plantronics...\r\n")
    var jsondata map[string]interface{} = httpGetJSON("http://127.0.0.1:32017/Spokes/DeviceServices/Attach?uid=0123456789")
    fmt.Print("\r\nSession ID:\r\n\r\n"+jsondata["Result"].(string)+"\r\n\r\n")
    sessionId = jsondata["Result"].(string)
    
    var result string = httpGet("http://127.0.0.1:32017/Spokes/SessionManager/Register?name="+pluginName)
    fmt.Print("\r\nResult:\r\n\r\n"+result+"\r\n\r\n")
    pluginRegistered = true
    
    go eventsListenerThread(sessionId,pluginName)  // start monitoring events after connect to api
}

Below is a picture of the code in action, having received a "Don" event (when I put on the Plantronics headset)...
Have fun!
Lewis.

go sample.png

Using Plantronics SDK from Java

lcollins — Thu, 05 Nov 2015 12:40:30 +0000

Keywords:

Java plantronics SDK integration REST Service API

*Update 22nd Jan 2016*: Since the SDK version 3.7.x, you can now optionally use https:// port 32018 in addition to http:// on port 32017! (however for https you may need to manually deploy the self-signed certificate if using Firefox or Java).

Sample code:
Download this sample code as a ZIP

String tmpResult =
    RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/DeviceServices/Attach?uid=0123456789"
);

This code requires the convenience function SendRESTCommand (available in the sample code ZIP).

0123456789 is a magic uid which tells the REST Service API to attach to the "primary" Plantronics device (primary device is settable via the Plantronics Hub user interface, in the case you have more than one Plantroncis device attached to your PC).

Now we can examine the tmpResult variable to see if the attach was a success.

int pos = tmpResult.indexOf("\"Result\":\"");
if (pos>-1)
{
    tmpResult = tmpResult.substring(pos+10);
    pos = tmpResult.indexOf("\"");
    if (pos>-1)
    {
        tmpResult = tmpResult.substring(0, pos);
        System.out.println("Session id is: " + tmpResult);
        sessionid = tmpResult;
    }
}

This code is extracting the sessionid from the HTTP response. We need that later for some of the other REST Service API commands. Note, the HTTP response is in fact JSON, so it would be better to parse with a JSON parser, but I haven't adopted a suitable JSON parser yet...

After a short delay we can go ahead an register a REST Service API plugin. The plugin is needed for some of the call control commands.

try
{
    Thread.sleep(250);
}
catch (InterruptedException ex)
{
    Logger.getLogger(PlantronicsRESTDemo.class.getName()).log(Level.SEVERE, null, ex);
}                                  
if (sessionid.length()>0)
{
    RESTConvenienceClass.SendRESTCommand(
        "http://127.0.0.1:32017/Spokes/SessionManager/Register?name=My%20Java%20Plugin"
    );               
    pluginRegistered = true;
}

Now we are able to poll for device events using further REST Service API commands, like this:
(Note: the sessid and plugin_name need to match what we registered earlier).
The contents of the responses we get back tell us lots of information, such as when user has answered a call with headset, mutes a call, takes headset off, etc.

RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/DeviceServices/Events?sess="
        + sessid
        + "&queue=0"
)
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/Events"
);
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/SessionManagerCallEvents?name="
        + plugin_name
);

Finally we can control the headset by telling it when we are going on a call, for example:
An incoming call (pass an integer callid, used to refer to this call during its lifecycle, and pass an optional caller name for Plantronics' display device products):

callid = callid + 1;
caller_name = "Bob%20Smith";
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/IncomingCall?name=My%20Java%20Plugin&callID=%7B%22Id%22%3A%22"
        + callid
        + "%22%7D&contact=%7B%22Name%22%3A%22"
        + caller_name
        + "%22%7D&tones=Unknown&route=ToHeadset"
);

End the call:

RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/TerminateCall?name=My%20Java%20Plugin&callID=%7B%22Id%22%3A%22"
        + callid
        + "%22%7D"
);

For more examples and to see a complete Java implementation, download the sample code ZIP.

Here is a screeshot of the sample code in action running under NetBeans IDE:

false

Have fun!