Welcome to the MicroPython for micro:bit workshop! This workshop is aimed at makers who want to start programming with MicroPython, we will be using the micro:bit as it is very easy to use so we can cover the important concepts that will apply to the other MicroPython platforms like the Pycom and ESP32.
Before we get started, we are going to need a few items to get through this tutorial:
- Micro USB Cable
- 330Ω Resistor
- 10kΩ Potentiometer
- Alligator to Male Jumper
- Solderless Breadboard
If you run into any issues throughout the workshop, then please reach out on the forum. We are full-time makers and are here to help!
- Chapter 1 – Introduction to MicroPython
- What is MicroPython?
- What is the micro:bit?
- What can we do with MicroPython?
- Chapter 2 – Getting Ready
- Getting Ready
- Editing Code
- Real-time Coding
- Writing to the micro:bit
- Chapter 3 – Hello World!
- Importing Libraries
- Digital Read and Write
- Chapter 4 – Analogue outputs
- Analogue I/O
- Chapter 5 – Talking to other devices
- Using the radio.
- Introduce Lists
- Chapter 6 – Sensors
- Using the built-in sensors
Chapter 1 – Introduction to MicroPython
What is MicroPython?
MicroPython is a version of the Popular coding Language Python 3, That has been cut down and implemented on microcontrollers. If you have used Python and Arduino, you will know why this is something that would get us excited. The Arduino uses a version of the C programming language and although C is very powerful it is not the friendliest language to work with.
MicroPython. unlike C, is an interpreted language, so the code is not compiled beforehand it is executed at runtime. This can be good as it allows for fast easy coding but can also lead to problems as errors will not be caught until the code is run and introduces some overhead to computing your code.
If you want a more in-depth look at the pros and cons of MicroPython, Stephen has made an excellent MicroPython Primer that covers all the basics.
The micro:bit hardware
You may be wondering why we have chosen to do an introduction to MicroPython with a board like the micro:bit with its brightly coloured interface and focus on education and fun for children.
The reason is simply that all of those things hide that fact that the micro:bit is a fairly formidable microcontroller that will run circles around many more “serious” development kits like the Arduino Uno.
|Board||Arduino Uno||BBC Micro:Bit|
|Language||C (Ardunio)||MicroPython & C(Ardunio)|
|Word Size||8 bit||32 Bit|
|GPIO||20||17 (11 Digital, 6 Dual)|
The micro:bit also supports MakeCode a block-based code editor it is also compatible with other similar languages such as Scratch.
These things combined with the ease at which prototyping can be done with the tab connectors along the bottom make it easy to see why everyone seems to love this board.
What can we do with MicroPython?
This is a difficult question to answer, this platform is incredibly adaptable and very easy to code, you will find that your biggest limitation is your imagination (Yes this is a cliche, but accurate :) ).
We are going to be using the micro:bit which has a lot of extra features built in and is very popular and easily available board.
There is a massive range of MicroPython boards and some of them that will truly astound you with the number of features. A great example it the Pycom range that have a Dual Core CPU and variants are available for IoT, LoRa, GPS and many more.
I am sure that your mind is already buzzing with ideas from this brief introduction, by the end of this workshop you should have a good idea of how to start making them a reality.
Now with the why out of the way let's get to the how!
To start with we need to set up your micro:bit so that it can be programmed with MicroPython. Many of the MicroPython boards come with tools that are designed specifically for it, we are going to be using one our favourite tool for editing the code on the micro:bit, the editor called Mu (Mu is the Greek letter engineers use to represent micro).
The Firmware Update for the micro:bit could not be easier, all you need to do is download the micro:bit firmware then power up your micro:bit while holding down the button on the back of the board.
You can then copy firmware update into the drive called MAINTENANCE. The micro:bit drive will disappear and return as a drive called MICROBIT, ready for coding.
Plug it in!
This step is fairly easy all you need is to get your micro USB cable plug it into your micro:bit and in a microsecond, you will be ready to start coding in MicroPython. The only hard part is dealing with all the micros.
One of the great things about MicroPython is that you do not actually need a specific IDE to write python code for it. This means that you can write code for it in any editor you like, Including Notepad. All you need to do is save your code as main.py and copy it over to the MICROBIT drive that appears when you plug it into your computer.
As mentioned earlier we are going to be using the Mu editor, this editor gives us access to a lot of special tools for debugging and writing code that will make it a lot easier.
When you start-up Mu for the first time you will be presented with a choice to customise your experience based on the board you are using. If the board you are using is not in the list you can simply use the Python 3 mode.
You can write the following Code we will then save this as main.py
import machine # Generic library for MicroPython Hardware
print("Hello I am micro:bit\n") # print some Text.
print("I can do",machine.freq(),"things per second") # Get the Frequency of the CPU
Note: this snippet of code will run on almost any MicroPython board.
By hitting the Flash button we are able to “burn” the code to the chip, then opening the REPL (Read Evaluate Print Loop) option will let us see the output of the code.
Now if we click on the REPL button we will be able to see the output of the code we have just written.
You will now notice that with the REPL window open, the Flash and Files buttons will be greyed out, REPL will need to be disconnected by clicking the REPL button again before we can access these functions again.
You can connect to REPL on any MicroPython board by using a serial Client like PuTTY.
Now that we have had a look at the Mu editor, we are ready to start writing some MicroPython code. Finally!
Now that we have everything set up it’s time to have some fun! we are going to write some code that will let us interact with the micro:bit through buttons and an LED.
It is worth pointing out that though many of the details and concepts will translate to other MicroPython boards the specific libraries to interface with the hardware are unique to each board.
Wiring in an extra LED
We will wire an LED in series with a 330ohm Resistor to pin0, you can see the Fritzing diagram below.
Let's Write Some Code!
We are going to write a simple python script that will turn an LED off and on by pressing the A button. In computer science, this method of state dependant switch is called a latch, and though it may seem like an obvious piece of code it is very useful. Below we have the completed piece of code for this tutorial, you can either copy it over and read the explanations of the functions below or watch the video where we will go through writing the code line by line.
import microbit # import the micro:bit library
import time # import time library
myButton = microbit.button_a # define Variable to be our Button
outputPin = microbit.pin0 # define variable to be Output Pin
if myButton.is_pressed() == 1: # check if the button is pressed
if outputPin.read_digital() == 1: # read the Current state of the LED
outputPin.write_digital(0) # if LED is on Turn it off
outputPin.write_digital(1) # if LED is not on, turn it on
time.sleep(.5) # sleep using the python library time in seconds
This function is where Python (and by extension MicroPython) gets its power and versatility from if you want something in python chances are there is a library for it.
For this chapter, we are going to be using two libraries that will add some extra functionality that we need for this example.
This library gives you access to the MicroPython Hardware, without this we would have a very hard time knowing how to access all of the buttons, lights, and other features of the micro:bit.
This is a python library that gives us access to functions that have to do with time, without this python thinks about time in clock cycles and they happen so fast it is hard for humans to keep up.
Variables are kind of like little boxes that we can store values in, we can store lots of different things in these boxes, for example, we could store a number or a bunch of characters. In this case, we are going to use the variable to store the Pin and button we have chosen this will make it easy to change the output pin or button if we want to later. (Give it a try! change the pin number or button_a to button_b)
For now, we will not look too deeply into this, but this will basically loop through anything that is tabbed in from it.
This will run after the loop, so will never happen.
micro:bit Hardware functions
we are going to use a few functions from the micro:bit library, these will let us interface with the hardware. We will have a look at each one individually.
This is the built-in function for checking if button A is being pressed it will return a value of True or 1 if the button is pushed and will be 0 or False as all other times. Changing to button_b will swap the button you are working with.
This will cause the micro:bit to look at what the value on the pin is and if it detects a voltage it will return 1 and 0 if there is not one. This function with any pin from pin0 to pin20
This function will write input value to the digital pin, the value must be 1 or 0, when it is set to one there will be 3V active on that pin when set to 0 there will be no voltage.
If else and the not yet seen else if
The if statement is one of the most important control structures you will learn in coding as it allows us to make decisions. The if statement will evaluate the term you give it and if it is true it will run the block of code, If we would like to run a different block of code if the evaluation returns False we can use the else statement. We have several evaluations that are we can use with if statements (and anywhere else we want a True/False result)
6 > 2
2 > 6
3 < 9
9 < 3
3 == 3
3 == 9
3 != 9
3 != 3
Greater Than or Equal To
9 >= 3
9 >= 10
Less Than or Equal To
6 <= 6
6 <= 9
There is a third statement that relates to the if block and that is the else-if, which will perform another evaluation after the first. To make this clear I have written some pseudocode below.
Do this is if Eval1 is True.
elif Eval2 (Test if Eval1 is False)
Do this if Eval2 is true.
Do this if neither of the above are True.
It is worth making a note of the time.sleep and microbit.sleep functions. If you have come from Python you will be used to the sleep time being set in seconds the micro:bit library uses the more C like (read Arduino) way of using milliseconds and it may catch you out.
Now we have our first Complete MicroPython script with if statements and Digital I/O, Next we are going to go analogue!
Now that we have mastered the digital inputs we age going to have a look at the analogue functionality of the micro:bit. You may think that analogue is less advanced than the digital inputs this is not actually the case Digital Signals are ones that have only two states 0 and 1. Analogue signals are continuous meaning that they can have any value in some range (for example 0-1000). Let's have a look at how to use them.
The first thing we need to do is add an analogue input to read. To do this we will wire a potentiometer(pot) to pin1. To do this we will wire from the 3.3V pin to the left of the pot, pin1 to the middle pin and the right pin we will wire to another 330ohm resistor then to ground. (see Diagram below.)
Code an Adjustable Blinking light.
We are going to create another state-based program this one will use while loops one that will define an On function that will have a flashing light that’s period is controlled by the potentiometer. It will also have an off state when the light is off and nothing will happen. You can start with the completed code and then we will go through and explain all the functions we are using.
from microbit import * # another way to import so we don’t need microbit. analogueOut = pin0 # Store Pin0 as variable analogueIn = pin1 # Store Pin1 as variable Steps = 1000 # Number of steps and final brightness level state = "on" # Current State of the on off switch while True: # Loop forever while state == "on": # Loop while state is on cycleTime = analogueIn.read_analog() # Read Value from Potentiometer timeDelay = cycleTime/Steps # Calculate the time delay needed for i in range(0,Steps,1): # Loop while i is between 0 and Steps analogueOut.write_analog(i) # Set analogueOut to i sleep(timeDelay) # Wait for a moment if button_a.is_pressed() == 1: # Check button state = "off" # Set State to off break # End For loop for i in range(Steps,0,-1): # Loop while i is between 0 and Steps analogueOut.write_analog(i) # Set analogueOut to i sleep(timeDelay) # More waiting… if button_a.is_pressed() == 1: # again with the button check state = "off" # Can you guess? break # Does this mean it is broken? analogueOut.write_analog(0) # Set analogue out to off sleep(1000) # wait so we don’t turn back on while state == "off": # Loop while off if button_a.is_pressed() == 1: # even more button checking state = "on" # turn back on sleep(200) # time delay to save cycles.
This time we are going to use import a little differently, this time we will not need to use the microbit.function() syntax we used in the last chapter. This can be handy as it makes your code easier to type, though can get confusing if you have two libraries that have functions with the same name like time.sleep and micropython.sleep .
A string is a series of characters that are defined by surrounding the stored value in quotation marks (“). We can compare strings by using the equal-to comparator( ==). It is very important to note that if you compare the string “1” to the number 1 or “a” to “A” it will evaluate as false because to MicroPython they are different.
Last time we had a quick look at the while True loop, the while loop will evaluate a condition on every cycle so that if the condition evaluates to false the loop will stop running and continue with the script.
While Eval1 # This will re evaluate after every loop.
Do some things
Make sure you do something
that may change the outcome of Eval1
or you will be stuck forever
I will run once the Eval1 has evaluated as False
read_analogue() will return a value between 0 and 1024(largest number that can be represented in 10bits) that represents a voltage at the pin of between 0-3.3V
write_analogue() takes input in the range of 0-1024 and sets the pin to be a voltage between 0-3.3Volts using a PWM method. If you want to know more detail about the I/O on the micro:bit Read the docs(https://microbit-micropython.readthedocs.io/en/latest/pin.html) is a great place to find it.
A for loop is a structure that will run for a set number of iterations and uses an index variable for each step.
for ValueAtCurrentStep in AvailableValues
Do this to ValueAtCurrentStep
Also Do this to ValueAtCurrentStep
This will happed after the block has been done to every Item in AvailableValues
This function creates a range of values that will begin with the startPoint end on the step before the endPoint and will take a step of size stepSize. The step size is optional if you do not define it the function will just assume you meant 1. To make this obvious I have made a list below that shows some results.
The next thing we are going to look at is how to use the built-in Bluetooth radio, the micro bit uses a cut down version of the Bluetooth. The micro:bit radio broadcasts to out to anyone that is listening to that if you send a message all the micro:bits that are listening will also get the message. We are going to write some code that will send a message to any listening micro:bits and receive messages from any that are broadcasting.
import microbit import radio # Import Radio Functions radio.on() # Turn the Radio on alphabet = ["a","b","c"] # Store Our Alphabet, you can add more. alphIndex = 0 # Initialise the index variable. microbit.display.show(alphabet[alphIndex]) # Display Currently Indexed Character while True: # our old friend if microbit.button_a.is_pressed() == 1: # Check if button A is pressed alphIndex = alphIndex + 1 # If it is advance the Alphabet index if alphIndex > len(alphabet)-1: # Check if alphIndex is still in range alphIndex = 0; # Restet index to zero microbit.display.show(alphabet[alphIndex]) # Display Indexed Character microbit.sleep(125) # sleep for debouncing if microbit.button_b.is_pressed() == 1: # Check if button B is pressed radio.send(alphabet[alphIndex]) # Send current character microbit.sleep(125) # sleep for debouncing incoming = radio.receive() # grab incoming message if incoming: # if there is a message microbit.display.scroll(incoming) # Scroll the incoming character microbit.display.show(alphabet[alphIndex]) # Return to displaying what we will send microbit.sleep(125) # sleep to save cycles
Lists are incredibly useful memory structures that let us store a collection of values like our alphabet.
We can define a list by using square brackets ( [ and ] ) and the values can be any python datatype (including other lists!). We separate values with a comma (,).
myList = [0, 1, 2, 3, 4] #index locations of a list
We can get data from a list by using the list name and square brackets.
myList # returns the first element
myList[-1] # returns the last element
when given a list this function will return the number of items in the list. This is very useful in making as if you try to get a value from a location that is not in the list this will cause python to crash.
The radio functions let us send and receive messages from and to other micro:bits, we cannot choose who we are sending the message too so any message we send will go to every micro:bit within range (Though they will have to be listening.)
This function turns the radio on, by default, it is off in the micro:bit to save power. Once it is turned on we can use the other functions to send and receive messages.
Send will broadcast the input string to all micro:bits in the area. In our code, we are sending a single character but you can also send strings of multiple characters.
Getting messages is a little more complicated even though we only have the single command. The radio has a small amount of memory that is used to store messages until they are retrieved this is called the queue. The queue will hold onto all messages it gets until you use receive() which will return and remove the oldest value from the queue (by default there are 3 queue locations).
The micro:bit has some sensors built into it, not all MicroPython boards come with sensors built in but many do, and the way that we interface with them is in most cases the same. The first step is to import the required library then use that library to grab the data from the sensor.
We are also going to look at some more python constructs the list and the function. Lists store a collection of variables under the same name and can be indexed conveniently. A function is a block of code we can call at any time.
The great thing about working with built-in sensors and outputs is that we do not need to wire up any circuits to make this work.
Working with sensors.
Sensors are a way that we can let our projects detect the world around it, there are sensors available for almost anything you can imagine. There are a few things that need to be taken into account when working with all sensors though.
To take this into account when you are designing your code with sensors we always avoid using the equals comparator (==). If you want your code to get to a very precise level you will need to use the Logic and to make sure that a value is between some range. For example, if you are checking a water level and you wanted to be at 1 litre you could use the if statement. The distance between the values should be chosen based on how accurate your sensors are or how precise your level needs to be while aiming to have the largest gap between them as possible.
if (water > 0.999) & (water < 1.001): return True
Noise is anything that is picked up by the sensors that are not the signals you are trying to measure, for example, if you are trying to measure the force of acceleration as a bus accelerates then the vibration of the bus is noise, but if you are interested in the vibration the force of acceleration is the noise.
The Virtual Cup.
We are going to write some code that will allow us to use the micro:bit as a virtual cup. The code will use the accelerometer to detect the acceleration of gravity to determine if our cup is upright or tipped. We are going to make our virtual cup refill whenever it is upright.
import microbit # import the micro:bit library import microbit # import the micro:bit library import time # import time library level = 0 cupLevel=[ #Store the Images of out Cup Level microbit.Image("99999:" "99999:" "99999:" "99999:" "99999"), microbit.Image("00000:" "99999:" "99999:" "99999:" "99999"), microbit.Image("00000:" "00000:" "99999:" "99999:" "99999"), microbit.Image("00000:" "00000:" "00000:" "99999:" "99999"), microbit.Image("00000:" "00000:" "00000:" "00000:" "99999"), microbit.Image("00000:" "00000:" "00000:" "00000:" "00000") ] def cupTip(direction, level): # define the function cupTip with two inputs if (abs(direction) > 400 ) & (level > 0): # Check direction input and tank Level pourRate = level - round(abs(direction)/20) # Calulate how much level to remove return(pourRate) # Return the amout to remove elif level > 0: # If not tiped stay at the same level return level # return the level else: return 0 # Return zero is cupLevel goes negative while True: accelXYZ = microbit.accelerometer.get_values() # get list of accelerometer values. roll = accelXYZ # first item in list pitch = accelXYZ # second item in list yaw = accelXYZ # second item in list if (pitch > 1000) & (level < 1000): # detect the gravity vector on pitch and tank level level += 40 # is less than full level = cupTip(roll,level) # call function and use the returned value as the new level level = cupTip(yaw,level) # call function and use the returned value as the new level microbit.sleep(125) # wait for a moment # Assign image from list based on the current level if level < 10: microbit.display.show(cupLevel) elif level < 200: microbit.display.show(cupLevel) elif level < 400: microbit.display.show(cupLevel) elif level < 600: microbit.display.show(cupLevel) elif level < 800: microbit.display.show(cupLevel) else: microbit.display.show(cupLevel) print(level) # We will only see this in REPL
Functions are block of code that can be called from any point after they are defined to perform some action on some inputs.
Functions are defined with the def tag and can have as many inputs as you like. You can pass any kind of variable to a function in python this includes lists and any sensors like we have in the example.
def myFunction(input1, intput2, input3, …, inputN) #line one of function #line two of function #last line of function # This line is not in the function
The return statement will end the end the function and return the value you give it back to where the function was called. Like the inputs return can return any kind of variable including lists and objects.
output1 = input * 2 # run out code
return(output1) #Return Value and end.
input1 * 4 # This line will never run
# This line is not in the function
The microbit Image function will display an image on the front 5 by 5 led display, there are a bunch of predefined Images you can use or you can define your own as we have in the example. Each number in the strings represents an LED 0 indicates off and 9 is maximum brightness. The colon is the end of the line and is not needed on the last line. The following will display a scaled Pascal’s triangle.
myImage = microbit.Image("00000:" "00200:" "02420:" "24642:" "46864")
To display the image we need to use the microbit display function show.
Note: There is a way to hack a simple light sensor using the LED grid.
We are just going to have a look at how to access the raw data the micro:bit has some advanced features such as direction and gesture detection that you can also use.
The micro:bit temperature sensor is inside the CPU and is designed to monitor the chip though because the micro:bit runs very cool it is usually very close to the ambient temperature.
The compass is actually a magnetometer and can be used to detect any magnetic fields, not just the earths. (Actually if you have a large magnetic field nearby your compass will not work well). To call the raw values from the micro:bit we use compass.get_x(), it detects in 3 dimensions so we can use get_y() and get_z() as well.
microbit.compass.get_x() # Get magnetic field in X
microbit.compass.get_y() # Get magnetic field in Y
microbit.compass.get_z() # Get magnetic field in Z
The accelerometer is the sensor that we have used in our example and can be accessed in the same way the compass can with get_x, get_y, get_z. You can use get_values() to return all 3 dimensions mesured in milig(1 thousandths of earths gravity) over a range of -2 to 2 gravities in a single list.
microbit.accelerometer.get_x() # Get acceleration in X
microbit.accelerometer.get_y() # Get acceleration in Y
microbit.accelerometer.get_z() # Get acceleration in Z
microbit.accelerometer.get_values() # Return list of dimensions
This Workshop is still under construction, Please Check back soon for more Chapters.
You should now have a pretty good idea of how to program in MicroPython on the micro:bit. Thanks for following along I hope you have enjoyed this tutorial and it has helped you become more comfortable and ready to explore the possibilities of MicroPython.
If you are still hungry for more embedded Python you can check out other MicroPython Tutorials or our Circuit Python Tutorials which use Adafruit's own libraries to simplify MicroPython.
As always if you have any further question or comments you would like to add to this tutorial then join the discussion with our community of dedicated makers.