The Badge comes with a preinstalled Micropython interpreter. Python should be the easiest way to control the device and write apps for The Badge, especially if you are a beginner or don’t want to spend a lot of time downloading tools and debugging drivers.
First, make sure Python is installed and you didn’t accidentally
delete it. Check in the
apps menu. If it’s not there: install the
Python app from the Hatchery by going to
Hatchery -> ESP32 native binaries -> Utility -> Python and install it either onto the flash or
onto an SD card.
If you have it already installed, make sure to check that you have the latest
There are several ways to run badgepython and develop badgepython applications. None of them are particularly well documented, so it’s up to you to explore what you can do and how to do it in a smart way.
In case you are interested in improving the documentation, we would be very happy to receive pull requests.
Here are a few starting points:
Run Python interactively
Start Python on your badge (
Python). There should be a message on
screen that an interactive Python console is availble on your USB serial
connection. Baud rate is 115200. Connect to it using a serial terminal of your
screen /dev/tty<your_serial> 115200. On MacOS,
.usbmodem101; on Linux probably
ACM0. You may also use other
terminal emulators such as
picocom based on your OS and/or
preference). The badge typically exposes two serial ports, simply try - one
should give you access to a terminal. If terminal gives a totally black screen, press enter to see the prompt appear.
You can now run python interactively. For example, run
print("That was easy!"). Amazing!
$ picocom /dev/ttyACM0 -b 115200 >>> print("That was easy") That was easy
If you are having problems connecting to the serial console, please check here !
Not only is the terminal a great way to try stuff out, it also allows easy
access to The Badge’s file system. Type
import os, then
see the root filesystem. A FAT partition is mounted on the badge’s internal
/. If you inserted a MicroSD card,
its contents will be mounted at
/sd. You can traverse the directories with
os.listdir() (and you will see that Python apps live at
/apps/python/<appname>/). You can create and remove directories with
os.rmdir and delete files
os.remove. Don’t screw up your
filesystem too badly. More documentation on basic micropython’s OS
library is available in the MicroPython
Try using the screen:
>>> import display >>> display.drawFill(0xFF0000) >>> display.flush()
display is a badge-specific module. There are several Badge-specific modules.
You can find documentation on them
(they might not be all fully up-to-date, but good enough for a start). In
addition there is also a
mch22 module that offers a few badge-specific APIs.
Finding out about it’s features is left as an exercise to the reader (hint:
Try some of the other APIs
Check in the API Reference for a list of APIs that work on the MCH2022 Badge, Try some of these APIs out in the emulator. Please be aware that you can’t expect APIs to work just because they have a green checkmark. It’s only a suggestion!
Develop microPython apps in the emulator
Uri Shaked a.k.a Wokwi built an awesome emulation of the badge that runs in your browser. This is an amazing way to quickly get started with app development. It’s not as fast as your badge, but it implements a surprising amount of the peripherals. Just try it.
Run an app on the Badge itself
Have a look at your Badge’s filesystem and the example apps in the
Hatchery (btw: browsing the hatchery is a great
resource for examples). You will see that each app resides in its own directory
/apps/python/<appname>. The main entry point is the
inside that directory. The directory may contain other python sources and
resource files. Apps stored in the internal flash reside in
apps on the (optional) SD card reside in
Create an app folder on your Badge’s filesystem (let’s call it
/apps/python/myapp in this example). There are two ways to create a
new app folder for your app: either connect to the BadgePython interactive
screen, PuTTY, …), and create the directory with the
>>> import os >>> os.listdir("/apps/python") ['citycontrol', 'someapp'] >>> os.mkdir("/apps/python/myapp") >>> os.listdir("/apps/python") ['citycontrol', 'someapp', 'myapp']
or use the mch2022 tools to create a new folder from your laptop:
$ python webusb_fat_ls.py /flash/apps/python Booting into WebUSB, please wait ... transfer speed: 2.32 kb/s Directory listing for "/flash/apps/python"... Directory "citycontrol" Directory "someapp" $ python webusb_fat_mkdir.py /flash/apps/python/myapp Starting... /internal/apps/python/ Succesfully created directory $ python webusb_fat_ls.py /flash/apps/python Booting into WebUSB, please wait ... transfer speed: 20.32 kb/s Directory listing for "/flash/apps/python"... Directory "citycontrol" Directory "someapp" Directory "myapp"
Now it’s time to write some code on your laptop using a text editor of your choice. If you’re not sure what and how to program, you can use the following example:
import display import random def drawRandomLine(): x1 = random.randint(0,320) x2 = random.randint(0,320) y1 = random.randint(0,240) y2 = random.randint(0,240) color = random.randint(0,0xFFFFFF) display.drawLine(x1,y1,x2,y2,color) display.flush() display.drawFill(0xFFFFFF) while True: drawRandomLine()
This program will clear the screen and then draw random lines infinitely.
Save that file as, say,
To upload the file to the Badge, you can clone the mch2022 tools. This repository contains scripts to upload files to the badge via WebUSB.
Python apps reside in the FatFS partitions inside the badge’s internal
flash and/or the optional SD card, so you should use the
webusb_fat_*** scripts from the tools
python3 tools/webusb_fat_ls.py /. You will see that the root directory listing
contains two entries:
sdcard (the mount points for the
internal and external partitions).
$ python3 webusb_fat_ls.py / transfer speed: 1045.4196368656173 Directory listing for "/"... Directory "flash" Directory "sdcard"
Warning: Confusion. Pandemonium. Chaos!
The paths in the filesystems are different depending on whether you
access them internally via the
os MicroPython API or whether you adress
them externally via the
Internally, i.e. from MicroPython (or native apps) are prefixed with
sd if they are located on the optional SD-Card.
Externally, i.e. from the
webusb_fat...py scripts, paths pointing to
internal files are prefixed with
flash and paths pointing to the SD
Card are prefixed with
Copy the __init.py__ file.
python3 tools/webusb_fat_push.py <file on your laptop> <file on The Badge> to upload your file to the Badge (don’t
forget to adjust the path for your laptop). You should see a
progress message and a success message on the terminal and your badge screen.
If you get a Unicode error, you can probably fix it by changing the
character in the
webusb.py script (two occurrences).
$ python webusb_fat_push.py __init__.py /flash/apps/python/myapp/__init__.py transfer speed: 28560.15516885618 File uploaded
After uploading, you should be ready to launch your app on the Badge (
myapp) and see colourful lines on the screen. If your script contains errors,
you will typically see a crash message on screen. To see error messages,
connect your serial terminal (see above) to the badge before starting your app.
Be kind, rewind
Unfortunately, there’s no way to end the app yet, so you have to restart your
badge by power cycling it (or using the
webusb_reset.py script in the
folder or uploading another file). Let’s add that by editing your
import display import random import buttons import mch22 def reboot(pressed): if pressed: mch22.exit_python() buttons.attach(buttons.BTN_A,reboot) def drawRandomLine(): x1 = random.randint(0,320) x2 = random.randint(0,320) y1 = random.randint(0,240) y2 = random.randint(0,240) color = random.randint(0,0xFFFFFF) display.drawLine(x1,y1,x2,y2,color) display.flush() display.drawFill(0xFFFFFF) while True: drawRandomLine()
The additional lines will add a key listener that will trigger a reset when the
A key is pressed.
Repeat the upload using the
webusb_fat_push.py script. Restart your app. Done!
Publish your work!
After you’re done writing an amazing app (and writing an amazing
with it), share it with others! The Hatchery is the
Badge’s “App store”. You can read about publishing eggs in the hatchery