# Kasper's micro:bit
So you finished [Python for kids](https://nostarch.com/pythonforkids)? Wouldn't it be awesome to use your
[BBC micro:bit](https://microbit.org/) as a **wireless game controller** for your own DIY games? You can do it with
this python package! Pair your [micro:bit](https://microbit.org/) to your computer with bluetooth and **use buttons A
and B or the accelerometer to control your game**. Like it? Give us a :star: on github!
[](https://github.com/janickr/kaspersmicrobit/actions/workflows/lint_and_test.yml)
[](https://kaspersmicrobit.readthedocs.io/en/stable/?badge=stable)
[](https://pypi.org/project/kaspersmicrobit/)
[](https://github.com/janickr/kaspersmicrobit/blob/main/README-nl.md)
Kasper's microbit is a python package to make a connection to a BBC micro:bit by means of the Bluetooth LE GATT services
exposed by the micro:bit.
[](https://www.youtube.com/watch?v=t3JARVPQE9Q)
Watch the full video [on youtube](https://www.youtube.com/watch?v=t3JARVPQE9Q)
## Getting started
Install kaspersmicrobit:
```bash
$ pip install kaspersmicrobit
```
Copy [this hex file](https://kaspersmicrobit.readthedocs.io/en/latest/assets/hex/microbit-bluetooth-accel-buttons-led-temp-no-pairing.hex)
to the micro:bit and run your first program:
```python
import time
from kaspersmicrobit import KaspersMicrobit
def pressed(button):
print(f"button {button} pressed")
with KaspersMicrobit.find_one_microbit() as microbit:
microbit.buttons.on_button_a(press=pressed)
time.sleep(10)
```
## Learn more
Visit https://kaspersmicrobit.readthedocs.io:
- Try the [accelerometer](https://kaspersmicrobit.readthedocs.io/en/stable/accelerometer/), or the [led display](https://kaspersmicrobit.readthedocs.io/en/stable/led/)
- [Learn](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/) to make your own .hex files
- [Simple examples](https://kaspersmicrobit.readthedocs.io/en/stable/buttons/), learn how to use each service offered by the micro:bit
- [Full Api documentation](https://kaspersmicrobit.readthedocs.io/en/stable/reference/kaspersmicrobit/)
- Combining KaspersMicrobit [with tkinter](https://kaspersmicrobit.readthedocs.io/en/stable/tkinter/use_buttons_to_move_rectangle/)
or [with pygame](https://kaspersmicrobit.readthedocs.io/en/stable/pygame/use_buttons_to_move_rectangle/)
Or take a look at the [examples](https://github.com/janickr/kaspersmicrobit/tree/main/examples) directory.
## Micro:bit versions, operating systems, Bluetooth pairing
Below you can find which combinations of operating systems and microbit versions have been known to work.
| micro:bit v2.x | No pairing required | Just works pairing |
|----------------|---------------------|--------------------|
| Windows | :heavy_check_mark: | :heavy_check_mark: |
| Linux | :heavy_check_mark: | :heavy_check_mark: |
| MacOS | :heavy_check_mark: | :grey_question: |
I don't have a mac to test kaspersmicrobit on. Let me know [here (#5)](https://github.com/janickr/kaspersmicrobit/issues/5)
if it works or not!
Thanks [@RyanNorge](https://github.com/RyanNorge) for testing a micro:bit v2.x on MacOS in "No pairing required" mode
| micro:bit v1.x | No pairing required | Just works pairing |
|----------------|---------------------|--------------------|
| Windows | :heavy_check_mark: | :x: |
| Linux | :heavy_check_mark: | :heavy_check_mark: |
| MacOS | :grey_question: | :grey_question: |
## Troubleshooting
### Upgrade to the latest version
```bash
$ pip install --upgrade kaspersmicrobit
```
### Bluetooth connection
First try turning the micro:bit off and on again.
If you are not using the "with"-block, but calling .connect() yourself, always make sure that in any case you
call .disconnect() when you don't need the connection anymore (for instance when you exit your application)
#### No pairing required
If the hex file was created with the setting ["No pairing required"](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/#disable-pairing)
then the micro:bit should not be paired with the operating system
#### Just works pairing
Don't use pairing with a micro:bit v1 on windows, use ["No pairing required"](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/#disable-pairing)
instead.
For other versions: try to remove the micro:bit from the paired Bluetooth devices and pairing it your computer again.
See also: https://support.microbit.org/helpdesk/attachments/19075694226
### The micro:bit shows a sad face and error 020
This means the micro:bit is out of memory. You probably have enabled too many Bluetooth services in MakeCode. Or maybe
your MakeCode program is too large. Because the micro:bit v1 has less memory than the v2, this has a higher chance to
occur on v1 micro:bits.
See also: [the micro:bit error codes](https://makecode.microbit.org/device/error-codes)
### tkinter "main thread is not in main loop"
When combining kaspersmicrobit with tkinter (the window library used in [Python for kids](https://nostarch.com/pythonforkids))
you could bump into the TK error "main thread is not in main loop". This is probably because you call TK code from
within a callback function that you registered to be called when a button press occurs or new accelerometer data is
present (or some other notification). The callback is executed on a different thread and tkinter does not like this.
There are at least 2 solutions for this:
- don't call tkinter code in a callback
- wrap the callback with `kaspersmicrobit.tkinter.do_in_tkinter(tk, your_callback)` this makes sure that your callback
will be executed on the tk thread, avoiding the error
Raw data
{
"_id": null,
"home_page": "https://github.com/janickr/kaspersmicrobit",
"name": "kaspersmicrobit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "microbit,bluetooth,ble,python-for-kids,gatt",
"author": "Janick Reynders",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f8/7c/58606fbc1bb48700c2e2f0ae0564f82b007056e0ac4c085087809c99b120/kaspersmicrobit-0.5.0.tar.gz",
"platform": null,
"description": "# Kasper's micro:bit\nSo you finished [Python for kids](https://nostarch.com/pythonforkids)? Wouldn't it be awesome to use your\n[BBC micro:bit](https://microbit.org/) as a **wireless game controller** for your own DIY games? You can do it with \nthis python package! Pair your [micro:bit](https://microbit.org/) to your computer with bluetooth and **use buttons A \nand B or the accelerometer to control your game**. Like it? Give us a :star: on github!\n\n[](https://github.com/janickr/kaspersmicrobit/actions/workflows/lint_and_test.yml)\n[](https://kaspersmicrobit.readthedocs.io/en/stable/?badge=stable) \n[](https://pypi.org/project/kaspersmicrobit/)\n[](https://github.com/janickr/kaspersmicrobit/blob/main/README-nl.md)\n\nKasper's microbit is a python package to make a connection to a BBC micro:bit by means of the Bluetooth LE GATT services\nexposed by the micro:bit.\n\n[](https://www.youtube.com/watch?v=t3JARVPQE9Q)\n\nWatch the full video [on youtube](https://www.youtube.com/watch?v=t3JARVPQE9Q)\n\n## Getting started\nInstall kaspersmicrobit:\n```bash\n$ pip install kaspersmicrobit\n```\nCopy [this hex file](https://kaspersmicrobit.readthedocs.io/en/latest/assets/hex/microbit-bluetooth-accel-buttons-led-temp-no-pairing.hex) \nto the micro:bit and run your first program:\n```python\nimport time\n\nfrom kaspersmicrobit import KaspersMicrobit\n\n\ndef pressed(button):\n print(f\"button {button} pressed\")\n\nwith KaspersMicrobit.find_one_microbit() as microbit:\n microbit.buttons.on_button_a(press=pressed)\n time.sleep(10)\n```\n\n## Learn more\nVisit https://kaspersmicrobit.readthedocs.io:\n\n - Try the [accelerometer](https://kaspersmicrobit.readthedocs.io/en/stable/accelerometer/), or the [led display](https://kaspersmicrobit.readthedocs.io/en/stable/led/)\n - [Learn](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/) to make your own .hex files\n - [Simple examples](https://kaspersmicrobit.readthedocs.io/en/stable/buttons/), learn how to use each service offered by the micro:bit \n - [Full Api documentation](https://kaspersmicrobit.readthedocs.io/en/stable/reference/kaspersmicrobit/)\n - Combining KaspersMicrobit [with tkinter](https://kaspersmicrobit.readthedocs.io/en/stable/tkinter/use_buttons_to_move_rectangle/) \n or [with pygame](https://kaspersmicrobit.readthedocs.io/en/stable/pygame/use_buttons_to_move_rectangle/)\n\nOr take a look at the [examples](https://github.com/janickr/kaspersmicrobit/tree/main/examples) directory.\n\n## Micro:bit versions, operating systems, Bluetooth pairing\n\nBelow you can find which combinations of operating systems and microbit versions have been known to work.\n\n\n| micro:bit v2.x | No pairing required | Just works pairing |\n|----------------|---------------------|--------------------|\n| Windows | :heavy_check_mark: | :heavy_check_mark: |\n| Linux | :heavy_check_mark: | :heavy_check_mark: |\n| MacOS | :heavy_check_mark: | :grey_question: |\n\nI don't have a mac to test kaspersmicrobit on. Let me know [here (#5)](https://github.com/janickr/kaspersmicrobit/issues/5)\nif it works or not! \nThanks [@RyanNorge](https://github.com/RyanNorge) for testing a micro:bit v2.x on MacOS in \"No pairing required\" mode\n\n\n| micro:bit v1.x | No pairing required | Just works pairing |\n|----------------|---------------------|--------------------|\n| Windows | :heavy_check_mark: | :x: |\n| Linux | :heavy_check_mark: | :heavy_check_mark: |\n| MacOS | :grey_question: | :grey_question: |\n\n\n## Troubleshooting\n### Upgrade to the latest version\n```bash\n$ pip install --upgrade kaspersmicrobit \n```\n### Bluetooth connection\nFirst try turning the micro:bit off and on again.\n\nIf you are not using the \"with\"-block, but calling .connect() yourself, always make sure that in any case you \ncall .disconnect() when you don't need the connection anymore (for instance when you exit your application)\n\n#### No pairing required\nIf the hex file was created with the setting [\"No pairing required\"](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/#disable-pairing)\nthen the micro:bit should not be paired with the operating system\n\n#### Just works pairing \nDon't use pairing with a micro:bit v1 on windows, use [\"No pairing required\"](https://kaspersmicrobit.readthedocs.io/en/stable/makecode-bluetooth/create-a-makecode-project-without-pairing/#disable-pairing)\n instead. \n\nFor other versions: try to remove the micro:bit from the paired Bluetooth devices and pairing it your computer again.\n\nSee also: https://support.microbit.org/helpdesk/attachments/19075694226\n\n### The micro:bit shows a sad face and error 020\nThis means the micro:bit is out of memory. You probably have enabled too many Bluetooth services in MakeCode. Or maybe\nyour MakeCode program is too large. Because the micro:bit v1 has less memory than the v2, this has a higher chance to\noccur on v1 micro:bits.\nSee also: [the micro:bit error codes](https://makecode.microbit.org/device/error-codes)\n\n### tkinter \"main thread is not in main loop\"\nWhen combining kaspersmicrobit with tkinter (the window library used in [Python for kids](https://nostarch.com/pythonforkids))\nyou could bump into the TK error \"main thread is not in main loop\". This is probably because you call TK code from \nwithin a callback function that you registered to be called when a button press occurs or new accelerometer data is \npresent (or some other notification). The callback is executed on a different thread and tkinter does not like this. \nThere are at least 2 solutions for this:\n\n - don't call tkinter code in a callback\n - wrap the callback with `kaspersmicrobit.tkinter.do_in_tkinter(tk, your_callback)` this makes sure that your callback \n will be executed on the tk thread, avoiding the error\n",
"bugtrack_url": null,
"license": "Mozilla Public License 2.0 (MPL 2.0)",
"summary": "A python package to connect to the Bluetooth LE GATT services of BBC micro:bit devices. Use your micro:bit as a wireless game controller!",
"version": "0.5.0",
"project_urls": {
"Documentation (en)": "https://kaspersmicrobit.readthedocs.io/en/stable",
"Documentation (nl)": "https://kaspersmicrobit.readthedocs.io/nl/stable",
"Homepage": "https://github.com/janickr/kaspersmicrobit"
},
"split_keywords": [
"microbit",
"bluetooth",
"ble",
"python-for-kids",
"gatt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cce37d7bc4891089ef40c3aa4c7988bd4d99b3aa1be7c7c2cbd0df99e88e47e1",
"md5": "86e14e935b116b032402bc4095f45a4a",
"sha256": "036ae0dc60fdf77903a2959022a048bcc19e1df9941ffc96322d2fac91fcbb3b"
},
"downloads": -1,
"filename": "kaspersmicrobit-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86e14e935b116b032402bc4095f45a4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 49702,
"upload_time": "2024-02-25T21:29:36",
"upload_time_iso_8601": "2024-02-25T21:29:36.862993Z",
"url": "https://files.pythonhosted.org/packages/cc/e3/7d7bc4891089ef40c3aa4c7988bd4d99b3aa1be7c7c2cbd0df99e88e47e1/kaspersmicrobit-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f87c58606fbc1bb48700c2e2f0ae0564f82b007056e0ac4c085087809c99b120",
"md5": "d560f9b9fa203a52aa2314a50739722d",
"sha256": "789745a8988d1ab7f63cd5b6c42108b04a17edf73dd2ff7fd4e3323fb6a467d7"
},
"downloads": -1,
"filename": "kaspersmicrobit-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "d560f9b9fa203a52aa2314a50739722d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 40612,
"upload_time": "2024-02-25T21:29:38",
"upload_time_iso_8601": "2024-02-25T21:29:38.488856Z",
"url": "https://files.pythonhosted.org/packages/f8/7c/58606fbc1bb48700c2e2f0ae0564f82b007056e0ac4c085087809c99b120/kaspersmicrobit-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-25 21:29:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "janickr",
"github_project": "kaspersmicrobit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kaspersmicrobit"
}
JSON
