{"id":25604533,"url":"https://github.com/alcir/microbit-ble","last_synced_at":"2025-06-17T19:36:55.926Z","repository":{"id":56286200,"uuid":"110753203","full_name":"alcir/microbit-ble","owner":"alcir","description":"Read data from micro:bit using Bluetooth from Linux","archived":false,"fork":false,"pushed_at":"2020-11-16T19:54:23.000Z","size":1172,"stargazers_count":49,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T09:49:44.106Z","etag":null,"topics":["bluepy","bluetooth","linux","microbit","microbit-ble","python","uart"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alcir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-14T22:39:36.000Z","updated_at":"2024-12-03T15:02:30.000Z","dependencies_parsed_at":"2022-08-15T16:00:52.331Z","dependency_job_id":null,"html_url":"https://github.com/alcir/microbit-ble","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alcir/microbit-ble","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcir%2Fmicrobit-ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcir%2Fmicrobit-ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcir%2Fmicrobit-ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcir%2Fmicrobit-ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alcir","download_url":"https://codeload.github.com/alcir/microbit-ble/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alcir%2Fmicrobit-ble/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260427399,"owners_count":23007502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluepy","bluetooth","linux","microbit","microbit-ble","python","uart"],"created_at":"2025-02-21T17:39:32.700Z","updated_at":"2025-06-17T19:36:50.910Z","avatar_url":"https://github.com/alcir.png","language":"Python","readme":"# Read micro:bit data from Linux via Bluetooth (BLE)\n\nHow to read data from micro:bit via Bluetooth on Linux.\n\n## No /dev/ttySOMETHING for UART\n\nMaybe due to the Bluetooth Low Energy protocol or implementation, I have not found the possibility to create a serial device in Linux. So the simplest way to read data from the micro:bit is Python. In this case I use **bluepy** https://github.com/IanHarvey/bluepy\n\n## Testing Bluetooth services from the shell\n\nFor testing purposes, you can use the `bluetoothctl`, `hcidump` (to sniff the bluetooth communication) and `gatttool` commands from **bluez** package.\n\n## micro:bit UART\n\nIn the micro:bit device, using MakeCode, it is possible to enable UART in order to send and receive arbitrary data to and from the connected device.\nIn order to get data from UART, you have to enable notification, writing \"0200\" on the Client Characteristic Configuration Descriptor (CCCD) of the UART Service Characteristic. The CCCD is 2902.\n\n### UART known issue: need to reset\n\nUsing UART there is a known issue: https://lancaster-university.github.io/microbit-docs/ble/uart-service/#example-microbit-application-animal-vegetable-mineral-game *[...] This prevents the event handler from exiting. Under normal circumstances this is fine. If however the connected application loses its connection and then reconnects, the onConnected method will not execute and therefore the 'connected' variable which tracks the Bluetooth connection state will not update. The micro:bit application will now behave as though it is not in a connection and therefore functions such as sending text by pressing a button will not work. In this situation the user should simply reset their micro:bit and reconnect their smartphone application. An API which allows serial reads to unblock or perhaps threads to be terminated is under consideration for a future release of the micro:bit runtime.*\"\n\nIn short: if the connection is interrupted, or the Phyton program exits without sending the disconnection message, the \"forever block\" containing the \"Bluetooth UART write\" block seems to get stuck. Even after reconnection (or rather starting the Python program again), there is no way to read any data. This lead to the need to reset the micro:bit.\n\n## MakeCode projects\n\nPlease remember that, every time you upload new code to the micro:bit, you have to pair again the device.\n\n### MakeCode blocks for UART\n\n![makecodeuart1](img/makeblockuart4.svg)\n\nLink to the MakeCode project: [https://makecode.microbit.org/_XXD3iuF36HCF](https://makecode.microbit.org/_XXD3iuF36HCF).\n\nPlease note the reset block.\nIn the Python program, if we will not receive any notification (aka data from UART) for a while, we will reset the device, then try to reconnect: this is a kind of workaround for the known issue described before. \n\n### MakeCode blocks for Temperature sensor\n\n![makecodetemp1](img/makeblocktemp1.svg)\n\nLink to the MakeCode project: [https://makecode.microbit.org/_6fT9haLmrFkC](https://makecode.microbit.org/_6fT9haLmrFkC).\n\n## Pairing from Linux with bluetoothctl\n\nSee MakeCode Bluetooth Pairing for instructions on how to put the micro:bit pairing mode (A+B, + reset, release reset, release A+B).\n\n\u003cpre\u003e\n$ bluetoothctl\n[NEW] Controller YY:YY:YY:YY:YY:YY pc [default]\nAgent registered\n[bluetooth]# scan on\nDiscovery started\n[CHG] Controller YY:YY:YY:YY:YY:YY Discovering: yes\n[NEW] Device XX:XX:XX:XX:XX:XX BBC micro:bit [pogeg]\n[bluetooth]# pair XX:XX:XX:XX:XX:XX\nAttempting to pair with XX:XX:XX:XX:XX:XX\n...\n[bluetooth]# scan off\n\n\u003c/pre\u003e\n\nUsage examples\n\n\u003cpre\u003e\n[bluetooth]# connect XX:XX:XX:XX:XX:XX\n\nAttempting to connect to XX:XX:XX:XX:XX:XX\n[CHG] Device XX:XX:XX:XX:XX:XX Connected: yes\n[CHG] Device XX:XX:XX:XX:XX:XX Name: BBC micro:bit\n[CHG] Device XX:XX:XX:XX:XX:XX Alias: BBC micro:bit\nConnection successful\n...\n[BBC micro:bit]# list-attributes \n...\n[BBC micro:bit]# select-attribute 00002a26-0000-1000-8000-00805f9b34fb\n[BBC micro:bit:/service000f/char0014]# read\nAttempting to read /org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX/service000f/char0014\n[CHG] Attribute /org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX/service000f/char0014 Value:\n  32 2e 30 2e 30 2d 72 63 39 2d 2d 67              2.0.0-rc9--g    \n  32 2e 30 2e 30 2d 72 63 39 2d 2d 67              2.0.0-rc9--g \n[BBC micro:bit:/service000f/char0014]# disconnect \nAttempting to disconnect from XX:XX:XX:XX:XX:XX\n[CHG] Device XX:XX:XX:XX:XX:XX ServicesResolved: no\nSuccessful disconnected\n[CHG] Device XX:XX:XX:XX:XX:XX Connected: no\n[CHG] Device YY:YY:YY:YY:YY:YY RSSI: -71\n\u003c/pre\u003e\n\nTest UART data (we have to select TX characteristic). Note that read method is pointless, we have to use notification in order to get useful data. Conversely, in order to get temperature data, we can use read or notification. This is valid also for the Python programs.\n\n\u003cpre\u003e\n[BBC micro:bit]# select-attribute 6e400002-b5a3-f393-e0a9-e50e24dcca9e\n[BBC micro:bit:/service0021/char0022]# attribute-info \nCharacteristic - Nordic UART TX\n\tUUID: 6e400002-b5a3-f393-e0a9-e50e24dcca9e\n\tService: /org/bluez/hci0/dev_E4_6D_B6_FC_83_A8/service0021\n\tValue:\n  00                                               .               \n\tNotifying: no\n\tFlags: indicate\n[BBC micro:bit:/service0021/char0022]# notify on \n...\n[CHG] Attribute /org/bluez/hci0/dev_E4_6D_B6_FC_83_A8/service0021/char0022 Value:\n  34 30 33 39                                      4039            \n[CHG] Attribute /org/bluez/hci0/dev_E4_6D_B6_FC_83_A8/service0021/char0022 Value:\n  34 30 34 32                                      4042            \n[BBC micro:bit:/service0021/char0022]# notify off\n[CHG] Attribute /org/bluez/hci0/dev_E4_6D_B6_FC_83_A8/service0021/char0022 Notifying: no\nNotify stopped\n\u003c/pre\u003e\n\n### Using gatttool command\n\nTo read the temperature value.\n\n\u003cpre\u003e\n$ sudo gatttool -b E4:6D:B6:FC:83:A8  -I -t random\n[XX:XX:XX:XX:XX:XX][LE]\u003e connect \nAttempting to connect to XX:XX:XX:XX:XX:XX\nConnection successful\n[XX:XX:XX:XX:XX:XX][LE]\u003e primary \nattr handle: 0x0001, end grp handle: 0x0007 uuid: 00001800-0000-1000-8000-00805f9b34fb\nattr handle: 0x0008, end grp handle: 0x000b uuid: 00001801-0000-1000-8000-00805f9b34fb\nattr handle: 0x000c, end grp handle: 0x000e uuid: e95d93b0-251d-470a-a062-fa1922dfa9a8\nattr handle: 0x000f, end grp handle: 0x0015 uuid: 0000180a-0000-1000-8000-00805f9b34fb\nattr handle: 0x0016, end grp handle: 0x0020 uuid: e95d93af-251d-470a-a062-fa1922dfa9a8\nattr handle: 0x0021, end grp handle: 0xffff uuid: e95d6100-251d-470a-a062-fa1922dfa9a8\n[XX:XX:XX:XX:XX:XX][LE]\u003e char-desc 0x0021 0xffff\nhandle: 0x0021, uuid: 00002800-0000-1000-8000-00805f9b34fb\nhandle: 0x0022, uuid: 00002803-0000-1000-8000-00805f9b34fb\nhandle: 0x0023, uuid: e95d9250-251d-470a-a062-fa1922dfa9a8\nhandle: 0x0024, uuid: 00002902-0000-1000-8000-00805f9b34fb\nhandle: 0x0025, uuid: 00002803-0000-1000-8000-00805f9b34fb\nhandle: 0x0026, uuid: e95d1b25-251d-470a-a062-fa1922dfa9a8\n[XX:XX:XX:XX:XX:XX][LE]\u003e char-read-hnd 0x0023\nIndication   handle = 0x000a value: 0c 00 ff ff \nCharacteristic value/descriptor: 19 \n\u003c/pre\u003e\n\n*19* is in sint8, that is 25 in decimal.\n\nTo read the notification interval (Temperature Interval) of the temperature (when enabled, see below).\n\n\u003cpre\u003e\n[E4:6D:B6:FC:83:A8][LE]\u003e char-read-hnd 0x0026\nCharacteristic value/descriptor: e8 03\n\u003c/pre\u003e\n\n`e8 08` that is 59395 milliseconds (UINT16 - Big Endian (AB))\n\nSo to receive temperature updates (as seen before, every 1 second circa) we have to write `0100` to the Client Characteristic Configuration Descriptor (CCCD), and `0000` in order to stop notifications.\n\n\u003cpre\u003e\n[XX:XX:XX:XX:XX:XX][LE]\u003e char-write-req 0x0024 0100\nCharacteristic value was written successfully\nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \nNotification handle = 0x0023 value: 19 \n[XX:XX:XX:XX:XX:XX][LE]\u003e char-write-req 0x0024 0000\nCharacteristic value was written successfully\n\u003c/pre\u003e\n\nPlease note: the value to write to the UART CCCD in order to enable notifications is `0200` and not `0100`\n\n## Bluetooth services and characteristics\n\nThese are the services that we will use in the Python program.\n\nFor UART\n\n| Type | UUID | Description |\n| ---- | ---- | ----------- |\n| Primary Service | 6e400001-b5a3-f393-e0a9-e50e24dcca9e | Nordic UART Service |\n| Descriptor      | 00002902-0000-1000-8000-00805f9b34fb | Client Characteristic Configuration |\n| Characteristic  | 6e400002-b5a3-f393-e0a9-e50e24dcca9e | Nordic UART TX |\n| Characteristic  | 6e400003-b5a3-f393-e0a9-e50e24dcca9e | Nordic UART RX |\n\nFor temperature sensor\n\n| Type | UUID | Description |\n| ---- | ---- | ----------- |\n| Primary Service | e95d6100-251d-470a-a062-fa1922dfa9a8 | MicroBit Temperature Service |\n| Descriptor      | 00002902-0000-1000-8000-00805f9b34fb | Client Characteristic Configuration |\n| Characteristic  | e95d9250-251d-470a-a062-fa1922dfa9a8 | Vendor specific (the temperature value) |\n| Characteristic  | e95d1b25-251d-470a-a062-fa1922dfa9a8 | MicroBit Temperature Period |\n\nFor the accelerometer\n\n| Type | UUID | Description |\n| ---- | ---- | ----------- |\n| Primary Service | e95d0753-251d-470a-a062-fa1922dfa9a8 | MicroBit Accelerometer Service |\n| Descriptor | 00002902-0000-1000-8000-00805f9b34fb | Client Characteristic Configuration |\n| Characteristic | e95dca4b-251d-470a-a062-fa1922dfa9a8 | MicroBit Accelerometer Data |\n| Characteristic | e95dfb24-251d-470a-a062-fa1922dfa9a8 | MicroBit Accelerometer Period |\n\nAccelerometer Data _contains accelerometer measurements for X, Y and Z axes as 3 signed 16 bit values in that order and in little endian format_.\u003cbr/\u003e\nMicroBit Accelerometer Period _determines the frequency with which accelerometer data is reported in milliseconds; valid values are 1, 2, 5, 10, 20, 80, 160 and 640_. So \"8002\" is 640, \"A000\" is 160, \"1400\" is 20, \"0200\" is 2 and so on. Note: 1 millisecond (that is \"0100\") seems to be invalid.\n\n## Useful links\n\n- micro:bit Bluetooth profile specification: https://lancaster-university.github.io/microbit-docs/resources/bluetooth/bluetooth_profile.html\n- micro:bit Bluetooth UART Service: https://lancaster-university.github.io/microbit-docs/ble/uart-service/#bluetooth-uart-service\n- MakeCode Bluetooth Pairing: https://makecode.microbit.org/reference/bluetooth/bluetooth-pairing\n- bluepy, a Bluetooth LE interface for Python documentation: http://ianharvey.github.io/bluepy-doc/\n\n## Disclaimer\n\nI'm not a Python developer and my knowledge of Bluetooth protocol is close to zero. So sorry for the imperfections.\n","funding_links":[],"categories":["🗞️ Articles"],"sub_categories":["🏗️ Project Collections"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcir%2Fmicrobit-ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falcir%2Fmicrobit-ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falcir%2Fmicrobit-ble/lists"}