Taking Control of your Bluetooth Devices

From PyCon UK 2016

Bluetooth Low Energy (BTLE) is a part of the Bluetooth standard aimed at bringing wireless technology to low power devices, and it's getting into everything - lightbulbs, robots, personal health and fitness devices and plenty more. However, these devices don't always come with a nice developer friendly API - often all you get is a phone app.

We will investigate one of these devices and see how we can decipher some meaning from the conversations it has with its app. Armed with that information, we can go into Python and start writing code to control our device. Along the way we'll looking at the protocols and properties used in BTLE interactions and see how the same principles can be applied to a multitude of devices.

Video: https://www.youtube.com/watch?v=F39xhYWHDKA

Transcript

1. Helen Sherwood-Taylor PyCon UK September 2016 TAKING CONTROL OF YOUR BLUETOOTH DEVICES
2. BLUETOOTH LOW ENERGY BLE BTLE "Bluetooth Smart" aka: Part of Bluetooth 4.0
3. BLE FEATURES Simple protocols Low bandwidth Short range Low power Widely used
4. WHY? Fun Control Endless possibilities! But... where's my API?
5. ATT ATTRIBUTE PROTOCOL Handle (e.g. 0x12) UUID (e.g. f000ffad-0451-4000-b000-000000000000) Properties / Permissions (e.g. 0x02) Value Attributes
6. GATT GENERIC ATTRIBUTE PROFILE Builds on attributes Services / characteristics hierarchy All contribute to device profile
8. STANDARD UUIDS Defined by Bluetooth Special Interest Group (SIG) Based on Bluetooth Base UUID Refer to with first 32 bits Can be looked up in spec e.g. heart rate, wind speed, latitude xxxxxxxx-0000-1000-8000-00805F9B34FB
9. VENDOR UUIDS Refer to with full 128 bits Chosen by the vendor What do they mean?
10. INGREDIENTS HARDWARE Bluetooth lightbulb Controlling device (Android phone) ANALYSIS File transfer (adb?) Wireshark CONTROL Linux box BlueZ bluepy
11. THE APP
12. HCITOOL $ hcitool lescan LE Scan ... 88:C2:55:08:CB:77 (unknown) 88:C2:55:08:CB:77 icolorlive Advertising / scanning 48 bit address May require sudo
13. GATTTOOL [ ][88:C2:55:08:CB:77][LE]> connect [CON][88:C2:55:08:CB:77][LE]> characteristics [CON][88:C2:55:08:CB:77][LE]> handle: 0x0002, char properties: 0x02, char value handle: 0x0003, uuid: 00002a00-0000-1000-8000-00805f9b34fb handle: 0x0004, char properties: 0x02, char value handle: 0x0005, uuid: 00002a01-0000-1000-8000-00805f9b34fb handle: 0x0006, char properties: 0x0a, char value handle: 0x0007, uuid: 00002a02-0000-1000-8000-00805f9b34fb ... handle: 0x0024, char properties: 0x0a, char value handle: 0x0025, uuid: f000ffa3-0451-4000-b000-000000000000 handle: 0x0027, char properties: 0x0a, char value handle: 0x0028, uuid: f000ffa4-0451-4000-b000-000000000000 handle: 0x002a, char properties: 0x0a, char value handle: 0x002b, uuid: f000ffa6-0451-4000-b000-000000000000 ... That's 3 t's!
14. GATTTOOL [CON][88:C2:55:08:CB:77][LE]> char-read-hnd 0x3 [CON][88:C2:55:08:CB:77][LE]> Characteristic value/descriptor: 69 63 6f 6c 6f 72 6c 69 76 65 That's 3 t's! Read characteristic by UUID [CON][88:C2:55:08:CB:77][LE]> char-read-uuid 0x2a00 [CON][88:C2:55:08:CB:77][LE]> handle: 0x0003 value: 69 63 6f 6c 6f 72 6c 69 76 65 [CON][88:C2:55:08:CB:77][LE]> char-read-uuid f000ffa3-0451-4000-b000-000000000000 [CON][88:C2:55:08:CB:77][LE]> handle: 0x0025 value: 4f 43 Read characteristic by handle Read by vendor-defined UUID
15. LOG CAPTURE Android Developer Options Toggle Do stuff in app Download log Repeat
16. WIRESHARK Filter: btl2cap.cid == 0x0004
17. GATTTOOL [CON][88:C2:55:08:CB:77][LE]> char-write-cmd 0x28 ff0000 [CON][88:C2:55:08:CB:77][LE]> char-write-cmd 0x28 ffff00 [CON][88:C2:55:08:CB:77][LE]> char-write-cmd 0x28 ff00ff
18. PYTHON from time import sleep from bluepy.btle import Peripheral, ADDR_TYPE_PUBLIC GREEN = '006600' BLUE = '000066' PURPLE = '660066' addr = sys.argv[1] def disco(sequence): for code in sequence: conn.writeCharacteristic(0x28, bytearray.fromhex(code)) sleep(1.0) conn = Peripheral(addr, ADDR_TYPE_PUBLIC) disco((GREEN, BLUE, PURPLE) * 3) conn.disconnect()
19. FURTHER READING
20. RESOURCES icolorlive bulb (or search for bluetooth bulb) - Wireshark - pyshark (python lib for processing logs) - BlueZ - bluepy - https://www.amazon.co.uk/dp/B01FR6QNH0/ https://www.wireshark.org/ https://github.com/KimiNewt/pyshark http://www.bluez.org/ https://github.com/IanHarvey/bluepy
21. LINKS GATT specification: lists of UUIDs Adafruit tutorial on BLE sniffing Installing BlueZ on Raspberry Pi - https://www.bluetooth.com/specifications/gatt https://learn.adafruit.com/reverse-engineering- a-bluetooth-low-energy-light-bulb http://www.elinux.org/RPi_Bluetooth_LE
22. THANK YOU! twitter: @helenst github: @helenst http://helen.st/