Metadata-Version: 2.1
Name: kaspersmicrobit
Version: 0.4.1
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!
Home-page: https://github.com/janickr/kaspersmicrobit
Author: Janick Reynders
License: Mozilla Public License 2.0 (MPL 2.0)
Project-URL: Documentation, https://kaspersmicrobit.readthedocs.io/en/stable
Keywords: microbit,bluetooth,ble,python-for-kids,gatt
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md

# 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!

[![Lint and Test](https://github.com/janickr/kaspersmicrobit/actions/workflows/lint_and_test.yml/badge.svg)](https://github.com/janickr/kaspersmicrobit/actions/workflows/lint_and_test.yml)
[![Documentation Status](https://readthedocs.org/projects/kaspersmicrobit/badge/?version=stable)](https://kaspersmicrobit.readthedocs.io/en/stable/?badge=stable) 
[![PyPi](https://img.shields.io/pypi/v/kaspersmicrobit)](https://pypi.org/project/kaspersmicrobit/)
[![Nederlands](https://img.shields.io/badge/vertaling-Nederlands-blue)](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.

[![Video of games created with kaspersmicrobit](https://kaspersmicrobit.readthedocs.io/en/latest/kaspersmicrobit-youtube.gif)](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/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          | :grey_question:     | :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!


| 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
