View source for CC2540

{{Project
   |Name=CC2540
   |Picture=cc2540_webee.png
   |Omschrijving=Making the CC2540 BLE dongle work
   |Status=In progress
   |Contact=bertrik
}}

== Introduction ==
This page is about the CC2540 bluetooth low-energy sniffer dongle and getting it to work with Linux.
A nice end result could be that it becomes possible to sniff directly in WireShark with this dongle.

I have such a "WeBee" dongle that can be found for about E15,- on websites like Aliexpress.

It's supposedly a CC2540 (or compatible) dongle, the USB id is 0451:16b3.

Interesting links:
* https://lacklustre.net/bluetooth/wireshark.html
* http://processors.wiki.ti.com/index.php/BLE_sniffer_guide
* https://github.com/andrewdodd/ccsniffpiper

== Analysis ==
=== USB descriptor ===
When plugging this stick into a Linux machine, you can see it uses only one bulk endpoint.

<pre>
Bus 001 Device 009: ID 0451:16b3 Texas Instruments, Inc. 
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0        32
  idVendor           0x0451 Texas Instruments, Inc.
  idProduct          0x16b3 
  bcdDevice           90.07
  iManufacturer           1 Texas Instruments
  iProduct                2 CC2540 USB Dongle
  iSerial                 0 
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength           25
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0x80
      (Bus Powered)
    MaxPower              100mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass       255 Vendor Specific Class
      bInterfaceSubClass    255 Vendor Specific Subclass
      bInterfaceProtocol    255 Vendor Specific Protocol
      iInterface              0 
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x83  EP 3 IN
        bmAttributes            2
          Transfer Type            Bulk
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval               5
Device Status:     0x0000
  (Bus Powered)
</pre>

=== USB logs from Windows ===
This USB device does actually work with Windows:
* [http://www.ti.com/tool/packet-sniffer SmartRF Protocol Packer Sniffer]

I've captured a log of the communication over USB while the BLE is capturing bluetooth traffic from some iBeacon, using [http://desowin.org/usbpcap/ USB pcap].

In the logs, I cannot see any firmware blobs being downloaded to the stick.
Probably the stick comes with a pre-loaded firmware of itself to do the BLE sniffing.

The USB control transfer request codes seem to match up with the code in https://github.com/christianpanton/ccsniffer/blob/master/ccsniffer.py
* 0xC0, GET_IDENT: returns some kind of identifier
* 0xC5, SET_POWER
* 0xC6, GET_POWER
* 0xC9, no idea, this appears in my USB logs but I can't find it in the python code
* 0xD0, START
* 0xD1, STOP
* 0xD2, SET CHAN  

== Protocol ==
[[File:cc2540_settings.png|right|thumb]]
[[File:cc2540_packet_details.png|thumb]]
[[File:cc2540_wireshark.png|thumb]]
In the windows sniffer software, it seems there are only two things communicated:
* towards the stick: which radio channel to sniff, and some other radio settings
* from the stick: raw sniffed BLE frames

=== Configuring the radio ===
This appears to be done using USB control transfers.

The following requests are sent:
{| class="wikitable"
! Request type
! Request
! Value
! Index
! Data
! Description
|-
| 0x40 || 0xC5 || 0 || 4 || - || Set power
|-
| 0xC0 || 0xC6 || 0 || 0 || 0x00 || Get power
|-
| 0xC0 || 0xC6 || 0 || 0 || 0x04 || Get power
|-
| 0x40 || 0xC9 || 0 || 0 || - || ???
|-
| 0x40 || 0xD2 || 0 || 0 || 0x27 || Set channel
|-
| 0x40 || 0xD2 || 0 || 1 || 0x00 || Set channel
|-
| 0x40 || 0xD0 || 0 || 0 || - || Start capture
|}

Request type 0x40 is a vendor-specific device request from host-to-device.
Request type 0xC0 is a vendor-specific device request from device-to-host.

=== Reading BLE frames ===
This appears to be done using USB bulk input transfers.

I can see a lot of similarities between the USB log and the BLE sniffer log.
The bulk USB data starts off with two bytes indicating the length of the rest of the data.

== Software ==
Preliminary code can be found at
https://github.com/bertrik/cc2540

It connects to the dongle and dumps raw USB packets to stdout.

This software requires libusb-1.0-dev