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 pyboardIn 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:
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.
MicroPython v1.8.2 on 2016-07-13; PYBv1.1 with STM32F405RG Type "help()" for more information. >>> >>>
REPLWhat 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 LEDAs 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>.
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)
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:
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.
>>> while True: ... pyb.LED(3).toggle() ... pyb.delay(250) ...
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 accelerometerHere is a quick experiment to see if the board’s accelerometer is working correctly.
The output should be a scolling endless list of the three values x, y and z:
>>> while True: ... print(pyb.Accel().x(),pyb.Accel().y(),pyb.Accel().z())
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.
-1 -2 21 -1 -2 20 -2 -1 20 …
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 programAfter 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) holeDon’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 yoursWhen 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.