Our devices, when talking to a computer, use the USB connection (even the wireless devices have a dongle or base that connects via USB).

 

There are a lot to be learned or to know about how USB works for the info to follow to make some sense. If you're brave enough and are playing on a platform that we don't offer an SDK today, the knowledge here will assist you to enjoy developing for our headsets on other platforms and pretty much any language that you may fancy.

 

If you are developing hardware (raspberry pi, arduino,etc), or software on a platform other than the ones currently supported, such as Linux or Mac for example, or on an embedded Android or Linux system, the information below will help you get off the ground and as usual, if you need any assistance, feel free to reach out we are always interested in hearing what you're building.

 

USB basics

 

Take a look at http://usb.org or something like USB in a NutShell - Chapter 1 - Introduction for some info to how USB is structured and how the data is exchanged. Explaing USB here is beyond the scope and I wouldn't accomplish it in 1 blog post.

 

For our purpose here, you'll need to know about Pages, Usages and Reports. Remember these terms, we'll come back to them

 

Plantronics HID

 

At Plantronics, we've defined how our devices communicate to the host device via our own HID specification. All that it means is how we have our data flowing in our own vendor specific page.

 

For our existing devices, use refer to the Plantronics HID 1.0. The Plantronics HID 2.0 specification is being worked on and a draft can be available on requests to vendors desiring to integrate with our future/upcoming devices that will conform to it. The full Plantronics HID 1.0 specification can also be available in full to vendors interested in it. For more details, please contact me directly or thru the comments in this blog.

 

Plantronics HID 1.0

 

Plantronics Vendor Page (0xFFA0)

 

Plantronics HID 1.0 spec, defines 0xFFA0 as the vendor page used. Devices shall conform to the general USB recommendations for USAGE PAGES and USAGE IDs. In particular, the IDs for high level collections shall be restricted to 1-0x1F

 

FEATURE Usages

 

Usage

Bits

Usage Description

Description

0xB5 1 Microphone Mute Get/SET the HS Mute State – True if HS is muted, False otherwise
0xA1 1 Host requested radio link Radio link requested by host independent of local buttons.

0 – RF Link Disable

1 – RF Link Enable

note: External software conditions (softphones, for example) can change the mute any time without an INPUT mute key press indication, therefore it is important to reread the mute usage before acting on its state.

 

INPUT Usages

 

Usage Bits Usage Description Description
0xA1 1 RF link state

1 = RF link established,

0 = RF link released

0xB7 1 Headset talk button Answer/make call
0xB5 1 Headset mute button Mute headset microphone
0xB3 1 Headset flash Soft phone Flash function
0xB1 1 Headset volume up Volume up button
0xB2 1 Headset volume down Volume down button

 

OUTPUT Usages

 

Usage Bits Usage Description Comments
0xA1 1 Host requested radio link Radio link requested by host independent of local buttons.

0 – RF Link Disable

1 – RF Link Enable

0x9E 1 VOIP ring Incoming soft phone call
0x8D 1 Host Present bit Set by Host application when running
0x8F 1 Exclusive bit Set by the Host application to ensure host control of hardware commands.
0xDC 1 Active SoftphoneCall Set by the Host application to denote the  Softphone Call Status:

0 = SP call Inactive

1 = SP call Active(Incoming Call, Outgoing Call, or Active Call)

 

Plantronics HID 2.0

 

Plantronics Vendor Page (0xFFA2)

 

To allow for some improvements while keeping backwards compatibility, Plantronics HID 2.0 has definide the Vendor Page to be 0xFFA2.

 

Future Plantronics devices complying to the Plantronics HID 2.0 specification will also have the HID 1.0 page available for hosts that have not yet integrated the new specification to its hosts devices.


Although there are no devices implementing the Plantronics HID 2.0 yet, here's how their implementation will differ, so you'll be ready to plug them in to your solution as soon as they are available.

 

Plantronics HID 1.0 to Plantronics HID 2.0 migration

 

Hid 1.0 Usage Input/ Output/ Feature Description Hid 2.0  Equivalent Input/ Output/ Feature Comments
0xA1 Output Host requested radio link 0x50 / 0x52 / 0x54 Output For HID 2.0, Radio Link is enabled as part of the Bluetooth, PSTN, or USB audio routing request
0x9E Output VOIP ring 0x9E   Unchanged
0x8D Output Host Present bit 0x8F Output For HID 2.0, Host Present has been deprecated
0x8F Output Exclusive bit 0x8F Output For HID 2.0,   Exclusive bit is now implemented as an up/down counter
0xDC Output Active Softphone Call 0xDC Output Unchanged
0xA1 Input RF link state 0xA0 Input For Hid 2.0, implementation is a wrap to indicate that the Feature value has changed. Host Software must examine the OTA Audio link feature (usage 0xA5)
0xB7 Input Headset talk button 0xB7 Input Unchanged  
0xB5 Input Headset mute button 0x9C / 0xB5 Input For Hid 2.0, the Headset Mute button indicates the button press. It provides no indication of the Mute State. Usage 0x9C denotes that the Mute State has changed.
0xB3 Input Headset flash 0xB3 Input Unchanged
0xB1 Input Headset volume up 0xB1 Input Unchanged
0xB2 Input Headset volume down 0xB2 Input Unchanged
0xB5 Feature Microphone Mute 0xB5 Feature/ Output For Hid 2.0, Mute implementation is now enabled either by a Set Feature request, or using the Output usage. This is dependent on the device implementation.
0xA1 Feature Host requested radio link 0xA5 Feature For Hid 2.0, the feature is used to provide an indication of the radio link. In order to update the radio link, the Host software must use usages 0x50 /0x52 / 0x54

 

Comments


Hello, We're developing a Linux module for the Calisto P240. Could you send me the HID 1.0/2.0 specifications for this device??

Best regards,

Sergio.

--

Sergio Domínguez García

F1-connecting S.L.

Móvil: +34 690 060 871

E-mail: sergio.dominguez@f1-connecting.com


Hi Sergio,

Sorry for the delay in replying to your request.

Please be assured that we are looking into this and will respond soon.

Best Regards,

Lewis.


Hello Lewis, this issue is very urgent for us. We are developing a prototype for a project with this device and the customer is very interested in this project.

Best Regards,

Sergio.


Hi Sergio,

I have sent you and email, please take a look and get back to me.

Thanks,

Lewis.


Hello!

We want to make a linux driver for model calisto P240 and we will need his HID 1.0/2.0 specifications.

Could you send me by email (daniel.alves@quobis.es)?

Thanks so much.


Hi Daniel,

I will look into this for you and get back to you soon.

Thanks,

Lewis.


Hi again,

We are still looking into this and whether we need an NDA to release this information.

Thanks for your patience.

Lewis.


Hi Lewis,

Thanks for all.

The problem is:

We want to capture the key events but we don't receive anything from the telephone.

The device is recognized by linux and the Descriptor is correct:

(terminal output):

Bus 002 Device 006: ID 047f:ae11 Plantronics, In

Interface Descriptor:

      bLength                 9

      bDescriptorType         4

      bInterfaceNumber        3

      bAlternateSetting       0

      bNumEndpoints           1

      bInterfaceClass         3 Human Interface Device

      bInterfaceSubClass      0 No Subclass

      bInterfaceProtocol      0 None

      iInterface              0

        HID Device Descriptor:

          bLength                 9

          bDescriptorType        33

          bcdHID               1.00

          bCountryCode            0 Not supported

          bNumDescriptors         1

          bDescriptorType        34 Report

          wDescriptorLength     730

         Report Descriptors:

           ** UNAVAILABLE **

      Endpoint Descriptor:

        bLength                 7

        bDescriptorType         5

        bEndpointAddress     0x83  EP 3 IN

        bmAttributes            3

          Transfer Type            Interrupt

          Synch Type               None

          Usage Type               Data

        wMaxPacketSize     0x0040  1x 64 bytes

        bInterval               4

We tried this:

http://developer.plantronics.comarticle/accessing-usb-devices-hid

But we don't receive any data. Does Calisto p240 use a specific protocol for establish connection and send the events?

If you need an NDA, there is not problem.

Thanks so much!


Hi Daniel,

The P240 uses a custom protocol for some of the features including dialing and caller id display.

We can release these details with suitable NDA in place.

I will email you to continue this process.

Thanks,

Lewis.


Hello,  I'm using C315 USB heaset. I'm curious about C315 follow which stand. HID Spec or Vendor Spec ? Could you let me know C315 comply which Spec? And if you have HID control linux sample driver for Plantroics HID devices, could your update in here?  Thanks a lot.

Hi,
The Blackwire headsets follow both the Microsoft Telephony HID spec and also a Plantronics Vendor Spec.
We have some sample code in python that you could use on Linux in this blog post:
http://developer.plantronics.com/article/accessing-usb-devices-hid
Thanks,
Lewis.
 

Hi Lewis, I'm not familar with python and link(http://developer.plantronics.com/servlet/JiveServlet/download/1162-4545/...) is not avaliable any more. Instead, i tried with lsusb utility. And also, i tried with Liux driver code. But i couldn't control C315 headset LED of mute and call buttons. I always met "broken pipe(32)" error when i sent USB control message. First of all, i checked Report descrioptor of HID classes with lsusb utility. Item(Global): Usage Page, data= [ 0x08 ] 8 LEDs Item(Global): Report ID, data= [ 0x09 ] 9 Item(Local ): Usage, data= [ 0x09 ] 9 Mute Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report ID, data= [ 0x17 ] 23 Item(Local ): Usage, data= [ 0x17 ] 23 Off-Hook Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report ID, data= [ 0x18 ] 24 Item(Local ): Usage, data= [ 0x18 ] 24 Ring Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report ID, data= [ 0x1e ] 30 Item(Local ): Usage, data= [ 0x1e ] 30 Speaker Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report ID, data= [ 0x20 ] 32 Item(Local ): Usage, data= [ 0x20 ] 32 Hold Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report ID, data= [ 0x2a ] 42 Item(Local ): Usage, data= [ 0x2a ] 42 On-Line Item(Global): Report Count, data= [ 0x01 ] 1 Item(Main ): Output, data= [ 0x22 ] 34 Data Variable Absolute No_Wrap Linear No_Preferred_State No_Null_Position Non_Volatile Bitfield Item(Global): Report Count, data= [ 0x07 ] 7 Item(Main ): Output, data= [ 0x01 ] 1 Constant Array Absolute No_Wrap Linear Preferred_State No_Null_Position Non_Volatile Bitfield Item(Main ): End Collection, data=none As the report, report ID of "Mute" led is 0x9. I set "struct usb_ctrlrequest" as 7.2.2 Set_Report Request of the HID Spec 1.11, bmRequestType : 0x21 bRequest : SET_REPORT (0x9) wValue : Report Type and Report ID - 0x209 ( Report Type << 8 | Report ID ) Report Type - 0x2 (Output) Report ID - 0x9 (Mute led) wIndex : Interface ( In my case, interface number is 3. I also tried with 0) wLength : 0 Data : Null I tested with variable values for bmRequestType, bRequest, wValue, wIndex, and wLength. But, "broken pipe" error is alwasy happened. I used below code in lsusb utility to control C315 Headset LED. retval = usb_get_driver_np(udev, hid_intf_num, dname, 31); if (!retval) { printf("%s : detach kernel driver %s\n", __func__, dname); usb_detach_kernel_driver_np(udev, hid_intf_num); } if (usb_claim_interface(udev, hid_intf_num) == 0) { ret = usb_control_msg(udev, USB_TYPE_CLASS|USB_RECIP_INTERFACE, 0x9, 0x209, 0, status, 1, CTRL_TIMEOUT); } In Linux kernel driver, retval = usb_control_msg(udev, usb_sndctrlpipe(udev, 0), 0x09/*0x09 : Request*/, 0x21 /*0x21 : request type*/, 0x209/*configuration value*/, 0/*index*/, enable/*data*/, 1/*data size*/, 2000); I couldn't resovle "Broken Pipe" erorr with any values. So, i wonder did i use correct values to control C315 headset? I spent several days to clear this issue. But, i couldn't until now. Could you help me? Thanks, Shin.

Hi Lewis, As the endpoint descriptor of C315, Its transfer type is Interrupt and bEndpointAddress is only INPUT. Endpoint Descriptor: bLength 7 bDescriptorType 5 bEndpointAddress 0x84 EP 4 IN bmAttributes 3 Transfer Type Interrupt Synch Type None Usage Type Data wMaxPacketSize 0x0025 1x 37 bytes bInterval 1 You can find explain about bEndpointAddress in below link. http://libusb.org/static/api-1.0/structlibusb__endpoint__descriptor.html http://libusb.org/static/api-1.0/group__desc.html#ga86c880af878493aa8f80... As their explain, C315 supports only INPUT for HID endpoint direction. Can i control LEDs of C315 with HID control command? Thanks, Shin.

Hi Shin,

Thanks for your questions.

I have added a couple of the missing files from that article here, including the Python code:
http://developer.plantronics.com/sites/default/files/missilelauncher.py_.zip
http://developer.plantronics.com/sites/default/files/missile_launcher_raspberrypi_0.png

The Plantronics Blackwire C315 will implement both some standard Microsoft USB HID usage pages (e.g. Telephony) and also a Plantronics vendor page 047f.
Various interactions with the device are possible across both usage pages.

We have 2 articles that reveal some information about the USB HID implementation, as follows:
http://developer.plantronics.com/article/interacting-plantronics-devices-without-sdk
and:
http://developer.plantronics.com/article/accessing-usb-devices-hid

This site is intended to support developers and partners who are using the Plantronics SDK which is currently available for Windows and Mac OS X.

Thanks,
Lewis.






 

Dear Lewis, we want to develop an application for the P240 as well. The platform will be Rasbian, therefore I am looking to receive the documentation that is available under NDA. I tried to contact the developer support via the form, but I did not receive any reply yet. Can you please supply me the neccessary data, my e-mail-address is available in my details. Best regards, Tobias

are these till working??had some problems..contacts an programming essay writer and he told me these are outdated but didn't provided my with any advice..anyways..are they outdated??

We've both multiple W445 and they are useless without your support as the SKD are only for Windows&Mac. We are waiting over a year for NDA regarding HID specification for supporting them as if it was some top secret matter. Other vendors like Jabra share all the informations, and even have Android&Linux SDK. You really can't help us in any way? The previous examples with simple HIDs are outdated and we can't control basic features (like power management)

Hi,
Thanks for your post, I am going to look into this for you and get back to you shortly.
Lewis.

Hi again,
Apologies again for not responding for so long.
I have just spoken about this to our regional manager for Poland and our local contact will reach out to you shortly to discuss.
Thanks,
Lewis.

Hello! I am evaluating the .Audio 478 for use with a soft phone. I would like to read the state of the device (mute and volume.) I can listen for the buttons being pressed via IOKit on the Mac via the IOHIDLib component. However, reading all the other values results in zero. Can one read the current volume and mute status? They are indpendent from the OS volume and mute levels.