So what is Spokes anyway?

Overview

Spokes is a runtime engine and software stack to facilitate interaction with and management of Plantronics devices including headsets, handsets and speakerphones.

3^rd party applications can interact with Plantronics devices using Spokes via the 3 different APIs: COM Service, REST Service and iPlugin SDK.

These 3 API options are shown in the below diagram:

What are the key features of the Plantronics device platform that applications can leverage using Spokes?

• Wearing Sensor

  • Get initial wearing state, receive events when it changes

• Proximity

  • Register for proximity, receive updates of user’s range to PC

• Headset docked state

  • Notified when device is docked/undocked

• Mobile caller id / call management

  • Caller id of incoming / outgoing mobile calls
  • Dial / answer / reject / end mobile calls via Spokes API

• Serial number

  • Programmable unique id per device
  • Uses for asset tracking or application user personalisation

• Data Logging

  • Log information about device usage as well as any information important to your application from other services, cloud applications etc.

• Call control

  • Softphones can notify Spokes of inbound/outbound calls via high-level API
  • No need to perform low-level device control
  • Note: also be informed of on-going call progress in other softphone apps supported by Plantronics (see list below) – multi softphone support

• Multi-line support

  • Receive events to notify the calling status / held status of the 3 lines (PC, mobile and desk phone)

Note: the set of above features available will vary depending on the Plantronics device in use.

What plugins come with Spokes?

Softphones

• Avaya IP Softphone V6.0 SP9 and V5.2 SP5
• Avaya IP Agent V7.0 SP8 and V6.0 SP18
• Avaya one-X Communicator V6.1 SP3 and V5.2 SP5
• Avaya one-X Agent V2.5 SP2
• Cisco IP Communicator V8.6(1) and V7.0.6.0, 7.0.5.0
• Cisco UC Integration for Microsoft Office Communicator (CUCIMOC) V8.0 (3)
• Cisco UC Integration for Microsoft Lync (CUCILync) V8.5(5)
• Cisco Unified Personal Communicator (CUPC) V8.5(5) and V8.0(3)
• Cisco WebEx Connect V7.2.1
• Microsoft Office Communicator R2 3.5
• Microsoft Lync 4.0
• NEC Univerge SP350 V4.1 and V5.1
• Shoretel Call Manager V10.2
• Shoretel Communicator V12.2
• Skype V5.8 and V4.2 – Skype Plugin Sample Code available!!!

Media Players

• Windows Media Player
• Winamp
• iTunes

Other

• Logging Plugin – useful for debugging your applications, see section 6 of reference manual.

What Management Tools come with Spokes?

• The Plantronics Control Panel (for easy configuration of device settings)
• The Plantronics Battery Status Monitor (shows wireless headset battery status on the system tray area)
• The Plantronics Update Manager (for easy update of Spokes software and device firmware)

There are 3 APIs - which one do I use with my application?

Languages supported today with current Spokes SDK:

*Note: The C# support for COM Service requires integrations to target .NET Framework 4.0 or higher only.

COM Service API with C#: How do I get started?

The COM Service allows your application to remain nicely decoupled from the Plantronics Spokes runtime. Integrating to C# is facilitated through adding an interop assembly to your project.

• This is described in a quick start tutorial for Blackwire 700 device (will also work with other devices): click here.
• There is a more comprehensive command-line demo (screenshot below) showing more API features: click here.
• For more samples check out the DevZone

COM Service for C++: How do I get started?

• There is a comprehensive command-line demo similar to above that shows the API features: click here.
• For more samples check out the DevZone

REST Service API with JavaScript: How do I get started?

• There is a hello world tutorial: click here.
• There is a more comprehensive sample showing more of the API: click here
• There are also some great blog posts around the JavaScript features.
• For more samples check out the DevZone

iPlugin API for C#: I’ve written my own plugin, how do I load it into Spokes?

• You copy your plugin DLL to the folder of “PlantronicURE.exe” (the Plantronics runtime)
• Then you add an entry to the PURE.xml file to tell it to load your plugin
• Then arrange for PlantronicsURE.exe to restart.
• For some sample code of iPlugins for Spokes, refer to the C# section of DevZone.

Where is the PURE.xml file?

It can be in 2 places:

• C:\ProgramData\Plantronics\PlantronicsURE\PURE.xml
• %localappdata%\VirtualStore\PURE.xml (Sometimes Spokes is using a "virtual" copy of the file in here)

Example entry for PURE.xml

<Plugin Name="MyPlugin" ProcessName="" Enabled="true" Active="false">
  <Assembly>MyPlugin.dll</Assembly>
  <ClassType />
  <Type>SoftPhone</Type>
  <FeatureType>1</FeatureType>
  <CustomProperty Key="MyProperty" Value="MyValue" />
</Plugin>

What do those tags mean?

• <Plugin> - defines the name of the Plugin, and also the Enabled and Active flags which get updates in realtime as the plugin initializes (refer to the samples).
• <Assembly> - defines the DLL name of the Plugin
• <ClassType> - can optionally define the type name of the iPlugin-derived class within the Plugin DLL that the runtime should instantiate
• <Type> - defines the type of plugin this is from this list:

public enum PluginType
{
     Unknown = 0,
     SoftPhone= 1,
     MediaPlayer = 2,
     Application = 3,
     Service =4
}

• <FeatureType> - defines additional features the softphone may have from:

public enum PluginFeatureType
{
     None = 0x0,
     MakeCall = 0x1, --> is able to handle MakeCall (dialling) event from device
     EscalateIMToVoice = 0x2 --> not used
}

• <CustomProperty> - defines a custom property value for use in your plugin. You can obtain the value of this property in your plugin code using the following code:
  C#

  String m_myProperty = m_sessionMgr.GetCustomProperty("MyPlugin", "MyProperty");

  Where MyPlugin is the Plugin name give in the Plugin tag above, and MyProperty is the key of the CustomProperty. Note: can also set the value with SetCustomProperty method, so the property in PURE.xml can be used as small persistant store, e.g. for screen coordinates, file names, etc.

More Information

To learn more about developing with Spokes SDK and Plantronics Devices, click here.

This article was contributed by Lewis Collins. He became a member of the Plantronics Engineering team in August 2011. In this role he provides software consulting and expertise internally across teams and to external development partners who want to integrate with the Plantronics SDK kits and headset products. Previously Lewis gained experience in a wide range of software engineering activities and technologies, working in the telecommunications and public safety sectors as a software engineer at Integraph, a consultant for Altran Technologies UK and as a software engineer for Teleca Ltd.