MicroPython for BBC micro:bit Technical Workshop

MicroPython for BBC micro:bit Technical Workshop

Agus Kurniawan

1st Edition, 2018

Copyright © 2018 Agus Kurniawan

 Table of Contents
MicroPython for BBC micro:bit Technical Workshop
Preface
1. Preparation
1.1 BBC micro:bit
1.2 Electronic Components
1.2.1 Arduino Starter Kit
1.2.2 Fritzing
1.2.3 Cooking-Hacks: Arduino Starter Kit
1.2.4 Arduino Sidekick Basic kit
1.3 Unboxing
1.4 Testing
2. Set up MicroPython on BBC micro:bit Board
2.1 Getting Started
2.2 Connect BBC micro:bit to Computer
2.3 Flashing MicroPython Firmware
2.3.1 Build and Flash from Source Code
2.3.2 Flash MicroPython using uFlash
2.4 My First MicroPython Program: Hello World!
2.5 Uploading Python file to BBC micro:bit
3. Display Programming
3.1 Getting Started
3.2 Displaying Characters
3.3 Displaying Images
4. BBC micro:bit GPIO
 4.1 Getting Started
4.2 Wiring
4.3 Demo 1: Blinking
4.4 Demo 2: Led-Button
5. Reading Analog Input and PWM
5.1 Getting Started
5.2 Reading Analog Input
5.2.1 Wiring
5.2.2 Writing Program
5.2.3 Testing
5.3 Working with PWM
5.3.1 Wiring
5.3.2 Writing Program
5.3.3 Testing
6. Working with SPI
6.1 Getting Started
6.2 Wiring
6.3 Writing a Program
6.4 Testing
7. Working with I2C
7.1 Getting Started
7.2 Wiring
7.3 Writing Program
7.4 Testing
8. Working with Accelerator and Compass Sensors
8.1 Getting Started
8.2 Working with Accelerator Sensor
 8.3 Working with Compass Sensor
Source Code
Contact
 Preface

This book was written to help anyone want to get started with BBC micro:bit
board using MicroPython. It describes the basic elements of the development of
BBC micro:bit board.

Agus Kurniawan

Depok, July 2018

1. Preparation
1.1 BBC micro:bit
BBC micro:bit is an open development board that allows you to run code on it
and have access to all of the hardware. This device has a lot of features, like 25
red LED lights that can flash messages. There are two programmable buttons
that can be used to control games or pause and skip songs on a playlist. You can
visit the official BBC micro:bit on http://microbit.org.
This book will focus on MicroPython development with BBC micro:bit board.
1.2 Electronic Components
We need electronic components to build our testing, for instance, Resistor, LED,
sensor devices and etc. I recommend you can buy electronic component kit.

1.2.1 Arduino Starter Kit

Store website: http://arduino.cc/en/Main/ArduinoStarterKit

1.2.2 Fritzing
Store website: http://shop.fritzing.org/ .

You can buy Fritzing Starter Kit with Arduino UNO or Fritzing Starter Kit with
Arduino Mega.

1.2.3 Cooking-Hacks: Arduino Starter Kit

Store website: http://www.cooking-hacks.com/index.php/shop/arduino/starter-
kits/arduino-starter-kit.html

1.2.4 Arduino Sidekick Basic kit

Store website: https://www.seeedstudio.com/Sidekick-Basic-Kit-for-Arduino-
V2-p-1858.html
1.3 Unboxing
I bought this board in Germany. The following is my development board.
1.4 Testing
For testing, I used BBC micro:bit on Windows, Mac and Ubuntu machines.

I also bought GPIO breakout for BBC micro:bit from

Pimoroni, https://shop.pimoroni.com/collections/micro-bit-uk/products/bread-
bit-breakout-board-for-micro-bit .

I also used Arduino Sidekick Basic kit for electronic components. I have some
another electronics kit included sensor and actuator.
 2. Set up MicroPython on BBC micro:bit Board

This chapter explains how to prepare BBC micro:bit board development for
MicroPython.
2.1 Getting Started
MicroPython is a lean and efficient implementation of the Python 3
programming language that includes a small subset of the Python standard
library and is optimised to run on microcontrollers and in constrained
environments. There are various IoT boards with supported MicroPython.
Further information about MicroPython, you can visit official website
on https://micropython.org.
2.2 Connect BBC micro:bit to Computer
You need a micro USB cable to connect BBC micro:bit board to computer
through this cable. After connected, you should see this board run as external
flash dis. You can see it in Figure below.

You can verify your board using Terminal. In Mac, BBC micro:bit is detected as
/dev/cuXXX where XXX board serial number

$ ls /dev/cu*

In Linux, you can check it in /dev/tty*. For Windows users, you can verify it on
Device Manager which is recognized as COM
2.3 Flashing MicroPython Firmware
In this section, we learn how to flash MicroPython firmware into BBC micro:bit
board. I show you two methods to flash the firmware.

2.3.1 Build and Flash from Source Code

Technically, MicroPython source code for BBC micro:bit can be found
on https://github.com/bbcmicrobit/micropython. You can read and follow how to
build to flash MicroPython to BBC microb:it board.

If you have a computer with installed Ubuntu/Debian Linux, you can build
MicroPython firmware. You can type these commands to install required
libraries.

$ sudo add-apt-repository -y ppa:team-gcc-arm-embedded

$ sudo add-apt-repository -y ppa:pmiller-opensource/ppa
$ sudo apt-get update
$ sudo apt-get install cmake ninja-build gcc-arm-none-eabi
srecord libssl-dev

You also should install all required development libraries on Debian/Ubuntu by

typing this command.

$ sudo apt-get install python3-pip python-dev build-essential

Next, you should install yotta.

$ pip3 install yotta

Now you can build MicroPython for BBC micro:bit board.

$ git clone https://github.com/bbcmicrobit/micropython

$ cd micropython/
$ yt target bbc-microbit-classic-gcc-nosd
$ yt build

Now you can flash the firmware to the board.

2.3.2 Flash MicroPython using uFlash

The easier to flash MicroPython to BBC micro:bit board using uFlash. You read
the detail of uFlash project on this site, https://github.com/ntoll/uflash.

You can install uFlash using this command.

$ pip install uflash

You can upgrade uflash using this command.

$ pip install --no-cache --upgrade uflash

Now you can connect your BBC micro:bit board to computer. Then, type this
command to flash MicroPython firmware.

$ uflash

You board should be installed MicroPython firmware.

2.4 My First MicroPython Program: Hello World!
In this section, we will build a simple program, hello world. The program will
show a word "Hello, World!" in LED panel. You can use any serial application
such as CoolTerm or Putty in Windows. For demo, I use
CoolTerm, http://freeware.the-meiers.org.

Connect BBC micro:bit board and then set port of your board on CoolTerm with
baudrate 115200.
On Terminal option, you don't set anything.
Next, click Connect button. You should see ">>>". If not, press ENTER on
terminal of CoolTerm.
Now you can type these scripts on CoolTerm

from microbit import *

display.scroll("Hello, World!")
After done, you should see
2.5 Uploading Python file to BBC micro:bit
In this section, I show you how to upload our Python file to BBC micro:bit board
and then execute it. Firstly, we use the same scripts on previous section. Then,
we create a file, called hello.py, and write these scripts.

from microbit import *

def run():
display.scroll("Hello, World!")

To upload this file, we can use ampy from Adafruit. You can install it using pip.

$ pip install adafruit-ampy

If you are interested this tool, you can visit the official project
on https://github.com/adafruit/ampy. You can upload Python file using ampy.

For instance, your BBC micro:bit serial port is /dev/tty.usbmode,1422. Then, we

want to upload hello.py file using put command. You can type this command.

$ ampy --port /dev/tty.usbmodem1422 put hello.py

Please make sure to disconnect all application that access the board serial port. If
not, you get problems while uploading Python file.

After that, open a serial app, CoolTerm. Connect to the board. You can verify
hello.py file already uploaded by typing these commands.

>>> import os
>>> os.listdir()
Now we can run our program by typing these commands.

>>> import hello

>>> hello.run()
To stop the program, you can press RESET button on the board.
To delete your Python file, you can use remove() function from os module.

>> import os
>> os.remove('hello.py')
 3. Display Programming

In this chapter I'm going to explain how to work with a display on BBC
micro:bit board.
3.1 Getting Started
BBC micro:bit has a display that consists of some 5 x 5 LEDs. We can create a
text or picture using this display.

Some MicroPython APIs related to display LEDs can be found on this

site, https://microbit-micropython.readthedocs.io/en/latest/display.html.
3.2 Displaying Characters
We can display a text using display.scroll() function. For instance, we display
"microbit!" word. You can type these scripts and save them into a file, called
displaytext.py.

from microbit import *

def run():
display.scroll('microbit!', wait=False, loop=True)

Upload this file and run it on a serial application.

>>> import displaytext

>>> displaytext.run()
Now you should see a text "microbit!" on the display from the board.
3.3 Displaying Images
We also put image on the display. MicroPython for BBC micro:bit has provided
Image object to show to the display. You can check it on this
document, https://microbit-
micropython.readthedocs.io/en/latest/tutorials/images.html.

For demo, we can write these scripts and save as displayimage.py file.

from microbit import *

def run():
display.show(Image.HEART)

Now you can upload this file and run it.

>>> import displayimage

>>> displayimage.run()
You can see the image on the display.
 4. BBC micro:bit GPIO

In this chapter we learn how to work with GPIO on BBC micro:bit board using
MicroPython.
4.1 Getting Started
General-purpose input/output (GPIO) is a generic pin on an integrated circuit
whose behavior, including whether it is an input or output pin, can be controlled
by the user at run time. GPIO pins have no special purpose defined, and go
unused by default.

To understand GPIO on BBC micro:bit board, you can see it in Figure below.

To work GPIO, I use bread:bit breakout board to attach our BBC micro:bit. You
can see it on https://shop.pimoroni.com/collections/micro-bit-uk/products/bread-
bit-breakout-board-for-micro-bit. The following is my wiring.
For demo, we build two programs: blinking and led-button
4.2 Wiring
In this section, we build a simple program to build blinking. We use two LEDs
which attach to GPIO pin P8 and pi P12. If you use GPIO breakout such as
bread:bit breakout board, you connect these LEDs in breadboard on GPIO P8
and P12 pins.

The following is my wiring

4.3 Demo 1: Blinking
In this demo, we perform blinking on two LEDs. We can use pin object. You can
read it on https://microbit-micropython.readthedocs.io/en/latest/pin.html.

Write this program.

from microbit import *

import time

def run():
print('blinking demo')
while 1:
pin8.write_digital(1)
pin12.write_digital(0)
time.sleep(2)

pin8.write_digital(0)
pin12.write_digital(1)
time.sleep(2)

Save this program as blinking.py.

Upload and run this program.

>>> import blinking

>>> blinking.run()
You should blinking LEDs on our wiring.
4.4 Demo 2: Led-Button
The second demo, we use built-in buttons with two LEDs. You can use button_a
and button_b to perform these built-in buttons. You can read its document on this
site, https://microbit-micropython.readthedocs.io/en/latest/button.html.

Our scenario is to turn on LED 1 if button A is pressed. If we press button B, we

turn on LED 2.

Now you can write this program.

from microbit import *

def run():
print('demo digital I/O')
while 1:
led1_state = button_a.is_pressed()
led2_state = button_b.is_pressed()

pin8.write_digital(led1_state)
pin12.write_digital(led2_state)

Save this program as gpiodemo.py.

Now you can upload and run the program by typing this command.

>>> import gpiodemo

>>> gpiodemo.run()
Now you can upload this program into BBC micro:bit board. Then, try to press
button A and/or B. You should see the lighting LED.

The following is a sample of lighting LED while a button is pressed.

 5. Reading Analog Input and PWM

This chapter explains how to work with reading analog input and PWM on BBC
micro:bit.
5.1 Getting Started
We access serial port from micro USB on BBC micro:bit. In this chapter, we try
to communicate with BBC micro:bit board through analog and PWM pins.

You can see BBC micro:bit GPIO on this picture.

You can see ANALOG IN as analog input pin. For PWM pins, you can use any
digital pin.
https://microbit-micropython.readthedocs.io/en/latest/pin.html
5.2 Reading Analog Input
In this section, we learn how to read analog input from BBC micro:bit board. For
demo, I use SparkFun Electret Microphone Breakout from
SparkFun, https://www.sparkfun.com/products/12758.

5.2.1 Wiring
For demo, we perform the following wiring:

BBC micro:bit pin 1 is connected to AUD pin from SparkFun Electret

Microphone
BBC micro:bit GND is connected to GND pin from SparkFun Electret
Microphone
BBC micro:bit 3V 1 is connected to VCC from SparkFun Electret
Microphone

The following is my wiring.

5.2.2 Writing Program
We will read analog input from pin 1 on BBC micro:bit. Then, we print it on
Terminal.

The following is a complete program for our demo.

from microbit import *

import time

def run():
print('analog input demo')
while 1:
analog_in = pin1.read_analog()
print('AIN: ' + str(analog_in))
time.sleep(2)
Save this program as analogdemo.py.

5.2.3 Testing
Now you can upload the program into BBC micro:bit board. Then, run it. You
can type this command on your serial application.

>>> import analogdemo

>>> analogdemo.run()

Then, try to make noise on the sensor device so you get analog output on the
Terminal.

The following is the output of CoolTerm.

5.3 Working with PWM
The second demo is to work with PWM. We can use any digitan pin to be PWM
pin. For demo, we use RGB LED. It usually has 4 pins:

pin 1: red
pin 2: common pin. It could be connected to GND or VCC
pin 3: green
pin 4: blue

Let's start.

5.3.1 Wiring
For our testing, we configure the following PWM pins.

RGB LED pin 1 (red) is connected to BBC micro:bit pin 8

RGB LED pin 2 is connected to BBC micro:bit 3 V (VCC)
RGB LED pin 3 (green) is connected to BBC micro:bit pin 12
RGB LED pin 4 (blue) is connected to BBC micro:bit pin 16

The following is my wiring.

5.3.2 Writing Program
Now we create a program to generate some colors. You can write this program.

from microbit import *

import time

def set_rgb(red, green, blue):

# red
pin8.write_analog(red)
# green
pin12.write_analog(green)
# blue
pin16.write_analog(blue)

time.sleep(2)

def run():
print('print PWM with RGB led')
 while 1:
print('red')
set_rgb(1023, 0, 0)
print('green')
set_rgb(0, 1023, 0)
print('blue')
set_rgb(0, 0, 1023)
print('yellow')
set_rgb(1023, 1023, 0)
print('purple')
set_rgb(323, 0, 323)
print('aqua')
set_rgb(0, 1023, 1023)

Save this program as pwmdemo.py .

5.3.3 Testing
Now you can upload the program file and then run it. Type these commands on
serial app Terminal.

>>> import pwmdemo

>>> pwmdemo.run()

The program output:

You should see various colors on RGB LED.
 6. Working with SPI

In this chapter I'm going to explain how to work with SPI on BBC micro:bit
board.
6.1 Getting Started
The Serial Peripheral Interface (SPI) is a communication bus that is used to
interface one or more slave peripheral integrated circuits (ICs) to a single master
SPI device; usually a microcontroller or microprocessor of some sort.

SPI in micro:bit board can be defined on the following pins:

MOSI on DOUT pin P15

MISO on DIN pin P14
SCLK on SCK P13
We can only use one SPI on micro:bit board with SPI master mode. We develop
program based SPI using SPI read and write blocks on Pins block category.

In this chapter, we build a SPI Loopback app. Let's start!.

6.2 Wiring
To develop SPI loopback, we can connect MOSI pin to MISO pin. This means
you connect pin P14 to pin P15 using cable or jumper.
The following is a sample of wiring.
6.3 Writing a Program
To send and receive data over SPI, we can use write_readinto() function from spi
object. You can read this object on this site, https://microbit-
micropython.readthedocs.io/en/latest/spi.html.

For testing, you can write this program to send and receive data over SPI.

from microbit import *

import random
import time

def run():
print('demo spi')
spi.init(2)
while 1:
tx = ''.join(chr(random.randint(50,85)) for _ in
range(4))
rx = bytearray(4)

spi.write_readinto(tx,rx)

print('tx: ' + str(tx))

print('rx: ' + str(rx))

time.sleep(2)

Save this code as spidemo.py.

6.4 Testing
Now you can upload program to BBC micro:bit board. If done, open your Serial
Monitor tool. You can the program by typing these commands.

>>> import spidemo

>>> spidemo.run()

You should see received data from SPI as shown in Figure below.
 7. Working with I2C

In this chapter we learn how to work with I2C on BBC micro:bit board using
MicroPython.
7.1 Getting Started
The I2C (Inter-Integrated Circuit) bus was designed by Philips in the early '80s
to allow easy communication between components which reside on the same
circuit board. TWI stands for Two Wire Interface and for most marts this bus is
identical to I²C. The name TWI was introduced by Atmel and other companies to
avoid conflicts with trademark issues related to I²C.

I2C bus consists of two wires, SDA (Serial Data Line) and SCL (Serial Clock
Line). BBC micro:bit has I2C pins on P19 (SCL) and P20 (SDA).

For testing, I used PCF8591 AD/DA Converter module with sensor and actuator
devices. You can find it on the following online store:

Amazon, http://www.amazon.com/PCF8591-Converter-Module-Digital-
Conversion/dp/B00BXX4UWC/
eBay, http://www.ebay.com
Dealextreme, http://www.dx.com/p/pcf8591-ad-da-analog-to-digital-digital-
to-analog-converter-module-w-dupont-cable-deep-blue-336384
Aliexpress, http://www.aliexpress.com/

In addition, you can find this device on your local electronics store/online store.

This module has mini form model too, for instance, you can find it on Amazon,
http://www.amazon.com/WaveShare-PCF8591T-Converter-Evaluation-
Development/dp/B00KM6X2OI/ .
This module use PCF8591 IC and you can read the datasheet on the following
URLs.

http://www.electrodragon.com/w/images/e/ed/PCF8591.pdf
http://www.nxp.com/documents/data_sheet/PCF8591.pdf

In this chapter, we build a program to access sensor via I2C using MicroPython
on BBC micro:bit board.
7.2 Wiring
We use PCF8591 AD/DA Converter as I2C source. You can connect PCF8591
AD/DA Converter to JBBC micro:bit board board directly.

The following is our wiring lab:

PCF8591 AD/DA Converter SDA --> BBC micro:bit board SDA (pin P20)
PCF8591 AD/DA Converter SCL --> BBC micro:bit board CLK0 (pin
P19)
PCF8591 AD/DA Converter VCC --> BBC micro:bit board VCC 3.3V
(+3.3V)
PCF8591 AD/DA Converter GND --> BBC micro:bit board GND

Hardware implementation can be shown in Figure below.

7.3 Writing Program
We use I2C on BBC micro:bit board using MicroPython. We can use i2c object.
Furthermore about i2c object, please read it on https://microbit-
micropython.readthedocs.io/en/latest/i2c.html . PCF8591 AD/DA Converter
module has three sensor devices: Thermistor, Photo-voltaic cell and
Potentiometer. This module runs on I2C bus with address 0x48 (72). In this case,
we read all sensor data.

Write the following compete program for our demo.

from microbit import *

import time

def run():
print('read sensor from i2c protocol')
PCF8591 = 0x48 # I2C bus address
PCF8591_ADC_CH0 = '\x00' # thermistor
PCF8591_ADC_CH1 = '\x01' # photo-voltaic cell
PCF8591_ADC_CH3 = '\x03' # potentiometer

# construct an I2C bus

i2c.init()

while 1:
# read thermistor
i2c.write(PCF8591, PCF8591_ADC_CH0)
time.sleep(1)
i2c.read(PCF8591, 1)
data = i2c.read(PCF8591, 1)
print('Thermistor: ' + str(ord(chr(data[0]))))

# photo-voltaic cell
i2c.write(PCF8591, PCF8591_ADC_CH1)
time.sleep(1)
i2c.read(PCF8591, 1)
data = i2c.read(PCF8591, 1)
print('photo-voltaic: ' + str(ord(chr(data[0]))))

# potentiometer
 i2c.write(PCF8591, PCF8591_ADC_CH3)
time.sleep(1)
i2c.read(PCF8591, 1)
data = i2c.read(PCF8591, 1)
print('potentiometer: ' + str(ord(chr(data[0]))))

time.sleep(2)

Save this program as i2csensor.py.

7.4 Testing
Now you can upload and run the program to BBC micro:bit board board.

If done, open Serial monitor tool and connect to BBC micro:bit. Then, type these
commands.

>>> import i2csensor

>>> i2csensor.run()

You should see sensor data from I2C. The following is a sample output.
 8. Working with Accelerator and Compass Sensors

This chapter explains how to develop BBC micro:bit with utilizing built-in
sensors, accelerator and compass sensors.
8.1 Getting Started
In this chapter, we explore how to work with built-in sensors, accelerator and
compass.

Let's explore.
8.2 Working with Accelerator Sensor
First demo, we build a program to access accelerator sensor. We can use
accelerator object. You can read the API in this site, https://microbit-
micropython.readthedocs.io/en/latest/accelerometer.html.

For demo, we get sensor data: x, y and z values from the sensor. You can write
this program.

from microbit import *

def run():
print('accelerometer demo')

while True:
x = accelerometer.get_x()
y = accelerometer.get_y()
z = accelerometer.get_z()
gesture = accelerometer.current_gesture()

print('x= ' + str(x) + ' ;y= ' + str(y) + ' ;z= ' +
str(z))
print('gesture: ' + gesture)
sleep(500)

Save this program as accdemo.py.

Now you can upload it into the board. You can run this program from
MicroPython terminal by typing these commands.

>>> import accdemo

>>> accdemo.run()

Try to shake your board to see sensor data on the Terminal.

A sample of program output can be seen in Figure below.
8.3 Working with Compass Sensor
The second demo is to build a program to access compass sensor. We can use
compas object, https://microbit-
micropython.readthedocs.io/en/latest/compass.html.

For demo, you can write this complete program.

from microbit import *

def run():
print('calibrate')
compass.calibrate()

while True:
x = compass.get_x()
y = compass.get_y()
z = compass.get_z()

print('x: ' + str(x))

print('y: ' + str(y))
print('z: ' + str(z))
sleep(500)

Save this program as comdemo.py.

Upload the program and run it.

>>> import comdemo

>>> comdemo.run()

Firstly, the program performs calibration. You can should move the board until
all LEDs are lighting. After that, you should see sensor data on Terminal.

A program output can be seen in Figure below.

 Source Code

You can download source code on http://www.makers.id/ak/bbcpy.zip .

 Contact

If you have question related to this book, please contact me at

aguskur@hotmail.com . My blog: http://blog.aguskurniawan.net