Plantronics Spokes SDK Overview

Introduction 

The Plantronics Unified Runtime Engine (Spokes) SDK exposes a set of interfaces for application developers to interact with Plantronics current and future devices. The Spokes SDK provides an abstraction for many application needs, including soft phone and media player integration. The SDK exposes events for device button presses and device state changes, and also a set of commands that the host can send to the device.

With the SDK, Spokes supported Plantronics devices provide many features to endusers such as:

• Call control  support ( eg. Remote ring detection,hook switch control and dialpad)
• Media player control ( eg. Pause, Stop media player while on a call )
• Device configuration support ( eg. Audio bandwith settings)
• Device state change notification support ( eg. Docked/Undocked, Don/Doff, multiline call mangement etc.)
• Device Firmware upgrade support (DFU)

Spokes supported devices (corded or cordless) fall into the following categories:

• Single interface device ( VOIP Only ): Single interface devices connect to the host via USB and provide only VOIP call control with all supported soft phones in Spokes.
• Multiple interface device (VOIP, PSTN, Mobile): Multiple interface devices connect to the host via USB and also have connectivity with another interface e.g.  PSTN connection via a hard-phone and also may act as a BT endpoint for mobile phone to pair with.
• Display device : Display devices can be single or multiple interface devices and have a display and key pad on the device. In addition to the features supported by non display devices, display devices support caller ID for incoming and outgoing calls, ability to make call and send DTMF digits while on a call.

Plantronics Spokes SDK

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

Languages supported today with Spokes SDK:

Notes:

*The .NET support for COM Service is via an Interop Assembly called "Interop.Plantronics.dll". This requires apps to target .NET Framework 4.0 or higher.

The "iPlugin API" is considered deprecated and is being removed at next major Spokes release and should no longer be used.

Ready to integrate your app into Spokes? Try these resources:

• So what is Spokes anyway?
• Spokes SDK 5-Minute Quick-start blog!
• DevZone

Spokes Architecture

Spokes Plug-in Architecture

The Spokes SW stack is depicted above and has several functional modules such as Device Manager, Device Listener, Call manager, Session Manager etc. The function of each module is described in following sections. The Spokes Plug-in is the single entry point for all external application interactions. Soft phone and media player components are required to implement a common interface IPlugin and, based on the Spokes configuration XML (PURE.XML), Spokes will dynamically load these modules as part of the process start up. Once successfully loaded, soft phone and media player modules will register with Spokes and use the Spokes ICallCommand, ICallEvents and ISessionManagerEvents interfaces to send commands and to receive events from Spokes. From the Spokes SDK application developers also have access to the current connected device IDevice and can register for all the events exposed in the device manager SDK.

Spokes Session Manager

The Spokes Session Manager will be responsible for handling all incoming client sessions. The client applications can range from Soft phone (SP) and Media Player (MP) modules to other third party applications that want to interface with devices directly. The Session Manager will expose interfaces for call handling, device state and events, sending alters, and media player control.

The Session Manager provides the following functionality:

• Handles all incoming Spokes client requests
• Maintains a list of client sessions
• Interfaces with the Spokes Call Manager and the Device Listener and propagates events and commands from and to the Spokes clients

Spokes Call Manager

The Spokes Call Manager interfaces with the Device Listener and the Session Manager and provides call control functionality. The Call Manager will support devices with single (VoIP only) and multiple channels (VoIP, PSTN, Mobile).  The Call Manager will also manage instances of active and held calls. There will be only one active call that can go through transitions based on the user action on the device or on the soft phone. The Call Manager will be able to support multiple calls from the same soft phone or from different soft phones. A well defined behavior for talk and flash button presses and to round robin between multiple calls across soft phones is implemented in the Call Manager.

The Call Manager also handles outgoing calls initiated from a device. Display devices with keypad, contact list or call log can make call requests to the Device Manager. The Device Listener will get the call request and propagate it to the Call Manager. The Call Manager creates an outgoing call instance and manages it based on user action.

Spokes Device Listener

Plantronics devices may provide more functionality (such as support for multiple communication endpoints (VoIP, PSTN and Mobile) and these devices may expose device specific commands and events. The Device Manager will expose all the device specific events and commands supported by these devices. The Device Listener provides a consistent interface across all devices so that applications need not handle device specific events and commands.

The Device Listener will provide the following functionality:

• Interfaces with the Device Manager and registers for all device specific events
• Exposes a common interface for call control commands and call control events to the Call Manager
• Handles device specific details for sending custom data, display, alert etc.
• Exposes a common interface for device state, commands and events to the Session Manager

Spokes Device Manager

The Device Manager will provide to the host the device interface layer for all Plantronics devices. The device manager provides the following functionality:

• A set of generic interfaces for USB device communication
• Supports USB device enumeration and filtering devices based on product ID
• Exposes USB device HID capabilities
• Provides USB device arrival and removal notification
• Supports device specific features by exposing additional device specific interfaces
• Supports configuration for USB devices
• Supports Device Firmware Upgrade (DFU)
• On supported devices, provides a mechanism for sending custom data (through a HID pipe) – custom data might include calendar alerts, IM messages, contact list, call log, etc.

The Device Manager interfaces with a HID abstraction layer to communicate with USB devices. The HID layer provides all the necessary USB device communication and device management by using Win32 APIs via Pinvoke (Platform Invoke services) and will be exposed only to the Device Manager.

The Device Manager also exposes few interfaces such as IDeviceManager for finding a specific device and device enumeration, IDevice for exposing a USB device and its common and device specific behaviors, IHostCommand and IDeviceEvents for handling device specific behavior. IHostCommand abstracts all the commands a host can send to a device and IDeviceEvents abstracts all the events that a device can send to the host. As part of the device enumeration, the Device Manager will initialize the common device behavior and also the device specific behavior based on the device it enumerates.

Next Steps

Please refer to the Spokes API specification for all the details on the interfaces and sample code for writing a plug-in for call control or for directly interfacing with the device. The current version of Spokes is build on Microsoft .NET 3.5 SP1 runtime.

The latest information will be made on the Plantronics Developer Connection web site and so please access this site to discover the latest information and engage with your fellow developers.

This article was contributed by Ramesh Theivendran. Ramesh has been a member of the Corporate Software development team at Plantronics since October 2007. Currently, he server as the software architect for Plantronics Spokes. Prior to joining Plantronics, Ramesh served as a Principal Architect at Borland International and as a Programmer at the Indian Institute of Technology, Bombay (IITB), INDIA. He has over 20 years of experience in building software tools & SDK for wide variety of distributed applications. Ramesh lives in Scotts Valley, California with his wife, Aruna, and their two daughters, Vineha and Vinusha.