Since its first release in 1991, the Python programming language has been widely adopted, and today it has become the preferred language of many programmers. Although intended for PC applications, a few years ago Python was ported to embedded systems too. MicroPython (uPy), as it was called, is a subset of Python that runs on platforms like the BBC micro:bit and the ESP8266. It also runs on the pyboard, the official uPy demonstrator board.
 
The Micro Python project (written with two words at this time), including the pyboard, was on Kickstarter by the end of 2013 where it scooped up more than six times the initial funding goal of £15,000. This success implied that the team had to throw in support for the CC3000 Wi-Fi module, the WIZ820io Ethernet module, and the NRF24L01+ low-power wireless module. Now, almost four years later, let’s see what has come of it all. Let's have a play with the pyboard and uPy.

Getting started with the pyboard

In front of you you should have a pyboard v1.1 (PYBv1.1, nicely packaged!), a micro USB cable and a computer (I used a Windows 10 laptop). Connecting the board to the computer immediately brings up a window showing the contents of drive E, labeled PYBFLASH. The operating system should also find a serial port. After opening a serial port terminal program (Tera Term), connecting it to the pyboard's port and pressing a key, you should see the Python prompt:  
MicroPython v1.8.2 on 2016-07-13; PYBv1.1 with STM32F405RG
Type "help()" for more information.
>>> 
>>> 
Wow, that was fast! Less than a minute after plugging in the board — a minute mostly spent on moving the mouse around to open and navigate through the operating system's menus — you are in business. 

REPL

What you are now looking at is a simple, interactive programming environment that takes single expressions, evaluates them, and returns the result. Such an environment is known as a Read–Evaluate–Print loop or REPL. It is important to know this acronym, because, when doing Python, you will encounter it a lot. 

Next step: blink an LED

As the prompt suggests, type ‘help()’ and press the enter key. This brings up a list of possible commands to get you started. Having a close look at this list is interesting as it reveals what is possible with the board. Built around an STM32F405RG ARM Cortex-M4F microcontroller, the board apparently has a real-time clock (RTC), an analog-to-digital converter (ADC), a digital-to-analog converter (DAC), four LEDs, switches, an accelerometer, a random number generator (RNG), I²C, SPI, UART, I/O pins and it supports servos. Some functions that control these peripherals are listed too, making for a pretty comprehensive help indeed. Simply looking at the board reveals also an SD card connector.

At the prompt, type the command below and press <Enter>. 
>>> pyb.LED(1).on()
Notice how a red LED, next to the USR pushbutton, lights up. Repeating the command but with the ‘1’ replaced by a ‘2’ (use the arrow keys to go back to the previous command and edit it) lights up a green LED next to the red one. LED number three is yellow, number four is blue. Except for the yellow one, the LEDs are incredibly bright and you better not look right into them. Let’s continue therefore with LED(3), leaving you with the exercise to switch off the other three LEDs.

To blink an LED forever a loop is needed, for instance the 'while' loop. To make it loop forever use a condition that will always be true, like the Boolean constant True. Enter the command (don't forget the colon ':' at the end) 
>>> while True:
Next, enter a toggle LED command. The terminal will start indenting the code as is compulsory in Python, shown by three dots. Enter a delay command to set the blink rate, 250 ms for instance. You should now have something like this: 
>>> while True:
...     pyb.LED(3).toggle()
...     pyb.delay(250)
...
To get this loop going you have to leave indentation mode first by pressing the backspace key, then press enter. LED3 should now blink at the rate you entered.

As you may have noticed, the terminal does not accept commands while the loop runs. To break out of the loop and return to the command prompt, press Ctrl-C ('interrupt a running program'). Now all the commands that were entered while the loop was running will be executed, so better be careful what you do during program execution!

pyboard accelerometer

Here is a quick experiment to see if the board’s accelerometer is working correctly.  
>>> while True:
...     print(pyb.Accel().x(),pyb.Accel().y(),pyb.Accel().z())
The output should be a scolling endless list of the three values x, y and z: 
-1 -2 21
-1 -2 20
-2 -1 20
…
As before, press Ctrl-C to return to the prompt. This is a revealing test as it shows the speed of execution of an apparently simple loop. All it does is read a sensor and print three integer values. I measured about three lines per second, which is not very fast.

The reason for this slowness is that the program is interpreted on-the-fly instead of being transformed (compiled) into machine instructions first, and even though there is only one line of code (ignoring the while statement), this is in reality a quite complex instruction. It is possible to speed things up by creating so-called frozen modules, but doing this implies recompiling the complete firmware for the pyboard, which is outside the scope of this article.

My first program

After playing a while in the REPL you may be wondering how to transform your volatile experiments into something more, let’s say, persistent. This is easy enough; all you need is a good text editor.



The pyboard is accessible as a flash drive and when you open it in a file viewer, you will see the file main.py. This is the Python file that is executed after a pyboard reset (hard with the RST pushbutton, or soft with the Ctrl-D command). Open this file in the text editor and add your commands to it. When done, save the file and reset the board to launch your program.

Getting out of a (deep) hole

Don’t be afraid to get creative, trial and error is the way to go. If you manage to mess things up in such a way that nothing seems to be working anymore, know that there are two rescue protocols that may help you out: safe mode and factory reset. In safe mode the files boot.py and main.py are not executed, giving you access to the file system (the USB drive should appear). Now you can edit boot.py and main.py to fix any problems.

Factory reset goes a step further than safe mode. It deletes all the files on the internal pyboard storage (not the SD card), and restores the files boot.py, main.py, README.txt and pybcdc.inf back to their original state. Pressing RST once more gets you back to where you started: the beginning of this article.

I want more!

The MicroPython website has nice tutorials that show how to use the pyboard’s peripherals. Reading them is highly recommended and will save you a lot of time. They also present some advanced techniques like combining assembler with uPy. Keep in mind that these tutorials concern the pyboard and presented techniques may not work (in the same way) on another board.

Not all mistakes are yours

When you start to learn writing uPy programs you will, of course, encounter your share of errors and mistakes. One of the most common — and frustrating — errors is forgetting to use the tab key. Or thinking that you were using tabs, when in reality you were not. Remember that Python requires indentation and for this it only accepts tab characters. Therefore, make sure that your text editor preserves tabs as there are many that silently replace them by spaces. The freeware editor Notepad++ is a good editor that does Python syntax highlighting and preserves tabs.

Besides indentation problems you may also run into Python compatibility issues. MicroPython is a port of Python, but it is not a perfect port. On the uPy website you can find a list of differences between CPython (the Python reference implementation) and uPy. So, if one day you run into a strange error where code that is supposed to work, doesn’t, maybe you should check this list.

Conclusion

MicroPython and the pyboard present a fun and low-cost way of getting into embedded programming and learning Python along the way. All of the goods promised during the Kickstarter campaign have been delivered, even the stretch goals. The uPy website with its nice tutorials may not always be up to date, so, when in doubt, consult the project pages at GitHub.