Programming with MicroPython

Chapter 1. What Is MicroPython?

MicroPython is a reimplementation of the Python programming language that targets microcontrollers and embedded systems.

Microcontrollers are computers shrunk onto a single, very small chip. Embedded systems are computers that function within a larger mechanical or electrical system. Embedded systems often use microcontrollers.

This book introduces, explores, and explains MicroPython through four typical yet different devices,¹ all of which have a microcontroller at their core.

Such devices are very different to other sorts of computer. Most computers contain lots of parts: memory, storage, and processing are physically separate components containing various specialist chips. They may also contain additional parts for sound, graphics, and networking capabilities. Such computers are significantly more powerful than the resource-constrained, microcontroller-based devices used in this book.

This raises two important questions:

• Why use such small, underpowered microcontroller-based devices?
• Why use Python?

Answering these questions illustrates why there is so much excitement surrounding MicroPython.

Why Micro?

Computers are amazing and seemingly magical things.

For example, it is commonplace to make video calls to the other side of the world. Yet, just 20 years ago, this was the realm of science fiction.

Any sufficiently advanced technology is indistinguishable from magic.

Arthur C. Clarke, Hazards of Prophecy: The Failure of Imagination

The quote from science-fiction author Arthur C. Clarke suggests advanced technology appears as awe-inspiring magic. He forgot to mention that any sufficiently advanced technology is boring if it’s everywhere. Familiarity and ubiquity banish any sense of wonder for all but the most inquisitive.

What do I mean?

I am just old enough to remember a world without computers everywhere. First encounters with computers felt like magic. For instance, when I was at university in the 1990s, I spent hours connected to multiuser, text-based virtual worlds² collaborating with people connected to the server from all over the globe. It felt amazing to work, in real-time, with such a diverse and far-flung group of friends. I was especially pleased to discover I could chat with my fellow users, albeit in a textual sense. Being British I always enquired about the weather and found it strangely satisfying to instantly know conditions in San Francisco, Tel Aviv, or Singapore (usually, better than the weather in London). Knowing this information and, more importantly, knowing how to get such information felt like magic.

Depending on your age, you probably experience one of two reactions to my example:

1. A tingle of nostalgia for those wonderful, exciting, and amazing early days of the internet.
2. Spare us reminiscences of the good old days; haven’t you heard of social media?

Today, my own children are unsurprised when they video-call their grandparents from mobile phones. There is no longer a sense of amazement or wonder at such feats of engineering. Rather, like generations of children before them, they’re more impressed, intrigued, and entertained by the magic found in stories, legends, and fairy tales.

Why?

It captures their imagination, whereas the use of everyday objects is humdrum and unremarkable.

Take the world of J.K. Rowling’s Harry Potter books—a world populated by enchanted objects, magical forces, and incantations that bestow upon the user the ability to transform the world around them. Readers are drawn into the world because they imagine, “Wouldn’t it be amazing if I owned an invisibility cloak, flying broom, or could cast a spell that allowed me to breathe under water?” There is a sense of wonder in the magic found in Rowling’s world. The same could be said of Tolkien’s Middle Earth, ancient Greek legends, any number of super heroes and Force-wielding Jedi in the Star Wars movies. It’s fun to be immersed in such magical realms—they entertain by encouraging a sense of wonder while giving imagination the freedom to wander. It’s an opportunity to ask yourself, “What would I do if I were the magic wielding hero?”

What has this to do with microcontrollers?

Such computing devices allow programmers to ask a similar question. Imaginations are set free to roam but, just as in literature and life, there is always a tension between right and wrong, good and evil, yes or no.

How?

Everyday objects containing small, embedded microcontrollers become programmable. If they are programmable, they have agency (the state of being in action) and autonomy (the capability of choosing how to act given certain situations). Rather than being static, dead objects, they become independent and demonstrate behaviours that bring them to life. Microcontroller-based devices are small enough to be stuck, sewn, soldered, and screwed in and on to other objects, turning everyday things into programmable “enchanted” objects.³ Most importantly, anyone with the right knowledge can “cast a spell” in code to modify the activities and behaviour of such objects.

Just as in literary worlds, embedded systems appear magical in ways that engage and inspire. Consequently, our world becomes programmable in a way that is similar to how make-believe spells control a fictional, magical world. Imagination and a sense of wonder for computing is, in a sense, restored. We regain the opportunity to ask ourselves, “What would I do if I could program these devices?” As Seymour Papert tells us, someone who learns to write code “both acquires a sense of mastery over a piece of the most modern and powerful technology and establishes an intense contact with some of the deepest ideas from science, from mathematics, and from the art of intellectual model building”. There are many examples of people inspired to build exciting hardware projects programmed with MicroPython. These encompass a diverse range of applications: robotics, sensing and reporting on the environment, satellite control, new musical instruments, art installations, counting South Atlantic krill, and quite a number of games, to name but a few.

Objects containing embedded and potentially networked microcontrollers are “enchanted” in the same way objects are in fictional, magical worlds—you simply give them instructions. Just like in magical stories, it is important to understand how such incantations in code make enchanted embedded objects work for you.

That’s where Python comes into the picture.

Why Python?

Python is an easy-to-learn, widely used, and expressive programming language (see Figure 1-1). It’s easy to write what you mean in Python with concise and simple code. Additionally, Python flourishes because it has a well-organised, proactive, diverse, and welcoming global community.

Figure 1-1. In 2016 Python was ranked the third most popular programming language in the world by the IEEE. Guido van Rossum (the inventor of Python) correctly points out the omission of the “Embedded” flag thanks to MicroPython.⁴

There are copious educational resources available for Python developers of all levels of experience. If you are unfamiliar with Python, you’ll find many free tutorials, courses, and meetups online; and, as you grow into Python, its excellent documentation and the technical support of its community will expand your horizons.

Note

This book will not include a Python tutorial.

There are a huge number of resources for both experienced programmers converting to Python and beginner programmers taking their first steps in code. Many of these resources are available online for free, and O’Reilly is rightly famous for the quality of its books and online video tutorials about Python. If you’re a complete beginner, I highly recommend Jake VanderPlas’s free A Whirlwind Tour of Python and Allen Downey’s Think Python.

A word of warning: learn Python 3 and avoid Python 2.

Python 2 is an earlier version of the language that’s still widely used for legacy reasons. It won’t be supported from 2020.

While Python 2 and Python 3 are very similar, and it’s even possible to write Python code that works on both versions, Python 3 is under active development, contains many improvements to Python 2, and includes useful new features that’ll never be available in Python 2.

MicroPython is a reimplementation of Python 3, and, for the rest of the book, it is assumed you have a basic level of understanding of Python 3, its syntax, and idioms.

MicroPython is a full reimplementation of Python 3. Apart from some differences described in the coming paragraphs, what you know about Python also applies to MicroPython. The most obvious difference between regular Python and Micro­Python is that MicroPython is designed to work under extraordinarily constrained conditions (such as just 16 kilobytes of RAM on the micro:bit).

MicroPython runs “bare-metal” directly on the hardware: there is no underlying operating system like Windows, macOS, or Linux. All the operations and services usually provided by an operating system are handled directly by MicroPython. MicroPython has complete and direct control of the hardware, so, in effect, Micro­Python is the operating system.

Apart from a few exceptions, all of the language features of Python are also in MicroPython. Due to the limited nature of the devices, MicroPython does not come with the full standard library by default. Rather, depending on the device, it will come with a subset of the standard library, often reimplemented in an efficient embedded-friendly manner.⁵ Usually, most of the features of a module will be available, but aspects that are considered edge-cases or redundant in an embedded context will not be implemented. All versions of MicroPython come with modules for interacting with the hardware, GPIO (general-purpose input/output) pins, peripherals, and components connected via such pins.

Since MicroPython is Python 3, you get:

• Python’s style of object orientation (but without metaclasses)
• Data types (like unicode strings, integers, and floating-point numbers) and data structures (like lists, sets, and dictionaries)
• The highly dynamic nature of Python objects
• Functions as first-class objects
• Exception handling (try, except, finally, and the standard built-in exception classes)
• Fun features like generator functions (using the yield keyword), generator expressions, and list comprehensions
• The new async and await keywords in the very latest versions of MicroPython
• A comprehensive number of Python’s built-in functions

Because MicroPython runs on devices with different capabilities, the availability of features and modules will sometimes be different. Of course, devices with special capabilities, like WiFi, will include modules to support these features.

For example, the micro:bit comes with a cut-down version of the standard library’s random module, but the default build for the ESP8266 board has the ultra minimalist urandom module⁶ instead. Because of the onboard WiFi capability, the ESP8266 port comes with both the json and urequests modules, whereas the micro:bit port does not because the micro:bit has no WiFi. MicroPython on both boards comes with the universally useful math module.

MicroPython’s comprehensive and flexible re-implementation of Python 3 raises three interesting opportunities:

1. The wider Python community have the opportunity to try embedded development using their favourite language.
2. Embedded developers who use C and other traditional embedded languages have the opportunity to take advantage of Python’s ease of use and rich libraries.
3. Beginner programmers have the opportunity to start with more than just “Hello, World!” They’re empowered to create engaging first projects using light, sound, sensors, and networking.

Do you make Django websites, analyse data with SciPy, or present work with Jupyter notebooks? Thanks to MicroPython, your Python skills apply in the embedded world! It is very easy to buy an inexpensive microcontroller-based board, plug in peripherals such as sensors or motors, and build something fun and useful.

As a Python programmer with no embedded experience, my first steps with MicroPython were rewarding and fun. It’s remarkably satisfying to make an LED blink via MicroPython’s REPL;⁷ and, as this book demonstrates, it doesn’t take much more effort to learn enough to build and invent interesting embedded contraptions.

If you’re an experienced embedded developer, you may be asking, “What’s wrong with C?” Nothing, and I’m not in the business of provoking unhelpful language wars. There are times when C is absolutely the right language and developers must use the best tool for solving the problem at hand.

However, in many situations, MicroPython outperforms C. When prototyping, MicroPython gives you many useful features that avoid the need for tedious boilerplate code. One C programmer reported a working prototype in MicroPython in just an afternoon, when it would have previously taken a week in C. Sometimes a few simple lines of MicroPython are able to do what would require hundreds of lines of C, making such code easier to maintain.

MicroPython is often fast enough and manages the limited resources well enough that any speed or memory efficiencies gained by using C are dwarfed by Python’s ease of use and productivity.

In any case, where C is the right tool, it’s possible to write MicroPython modules in C and make use of them within your Python code. It’s even possible to write inline assembler as MicroPython functions.

For some beginner programmers, making a computer print “Hello, World!” on a screen is a revelation. Alas, to the vast majority of people, the end result is a “so what?”

Who can blame them?

Compared to the wonders of kitten photos, video conferencing, virtual reality, and beautifully rendered, multiplayer video games set in an almost infinite galaxy, “Hello, World!” is a bit of an anticlimax, especially if you’ve been led to believe this is your first step to becoming some sort of Hollywood style uber-hacker.

Playing with embedded devices or making objects that feel “enchanted” helps to overcome the disillusionment usually encountered with traditional beginner programming exercises. It’s more fun to program objects that emit rude sound effects on demand, animate a series of lights on a costume, send secret messages over a network, or become the heart of an autonomous robot vehicle than it is to underwhelm the world with a greeting.

Such opportunities allow Python programmers to join the embedded community, embedded developers to join the Python community, and beginner programmers to cut their teeth in the evolving embedded Python community gathering around MicroPython. Everyone is a winner.

Embedded programming is fun. Python programming is fun. But, put them together, and the fun factor is more than doubled!

Why is this important? Because community is Python’s secret weapon.

Perhaps more than any other computing community, Python’s has a reputation for friendliness, openness, outreach, and the giving of time to community efforts.

Python programmers (sometimes called Pythonists, Pythonistas and/or Pythonauts) are well organised, having created the Python Software Foundation (PSF) as a rallying point for the community. The PSF was created to promote, protect, and advance the Python programming language (whose intellectual property belongs to the PSF) and to support and facilitate the growth of a diverse and international community of Python programmers. This is achieved by supporting the development of the Python programming language itself, providing technical infrastructure for the wider Python community, running and supporting a large number of international Python conferences (PyCons) around the world, and the giving of grants to individuals and organisations that promote the foundation’s aims.

Details about the Python language, the PSF, the grants programme, upcoming PyCons, and user groups around the world can be found at the Python language’s website. However, if you need information specific to Micro­Python, then visit the project’s own website.

Why does MicroPython have its own website rather than an area on the main website? It’s because of the remarkable history of the project.

It’s a great story and worthy of retelling here.

MicroPython Genesis

MicroPython is the creation of Damien George.

Damien is an Australian physicist who moved to the UK to work as a post-doctoral fellow at Cambridge University. His area of expertise is revealed on his home page on Cambridge University’s website:

My research interests centre around model building using extra dimensions, and the phenomenology of such models at the electroweak scale as is relevant for their testing at the Large Hadron Collider (LHC).

Damien also studied robotics as an undergraduate and was a competitor in the RoboCup, an international competition for teams who build robots that play football (soccer). He designed and wrote a scripting language from scratch for such robots. It was called Hush, and the language made it easy to change the robot’s artificial intelligence on the fly.

Obviously, Damien has an enquiring mind, a skill with hardware, and is extraordinarily talented. Back in 2013, he also had time on his hands.

He wondered if it would be possible to write a version of Python for microcontrollers. Given his experience with embedded systems found in robotics and an earlier project where he’d written his own embedded-C compiler from scratch, he was uniquely qualified and got to work. Some months later, he had created “for fun” a working proof of concept.

To gauge interest in and publicise his nascent project, Damien created a Kickstarter campaign. He promised that if he managed to raise £15,000, he would finish off his implementation of Python and provide those supporters who had paid £20 or more with a suitable microcontroller-based device called the PyBoard. He did this under the auspices of “George Robotics Limited”, the company he runs with his wife Viktoriya.⁸

When the campaign closed, it had raised almost £100,000.

The world wanted MicroPython!

Not only did Damien’s campaign exceed all expectations in terms of funding, but he delivered on his promise: the PyBoard was delivered to almost 2,000 supporters in 2014.

From that initial seed, MicroPython’s community has grown.

The code is released under an open source licence and hosted on GitHub, with people from all over the world contributing features, bug fixes, documentation, tools, and new ports of MicroPython to run on many different sorts of microcontroller.

But that’s not the end of the story.

In 2015, the European Space Agency (ESA) funded the development of MicroPython to determine the suitability of the language for space applications. In particular, the research focused on the dynamic configuration of payloads, such as satellites, via Python. Importantly, the valuable work Damien completed to make MicroPython more robust for critical embedded systems⁹ was folded back into the wider project.

It was a winning situation for everyone: MicroPython gained the potential to fly in space, and the community received improvements to the generic MicroPython implementation.

At around the same time, the British Broadcasting Corporation (BBC) announced its intention to release a small computing-in-education device to be delivered to every single 11-year-old in the United Kingdom (approximately 1 million devices). The PSF became a partner because the BBC wanted Python as one of the preferred languages for the device. Another (unnamed) partner was to create the micro:bit runtime for Python, but, in April of 2015, they pulled out.

Damien came to the rescue. Fortuitously, Damien’s next-door neighbour in Cambridge was the hardware engineer at ARM who designed the board for the micro:bit project. Damien’s neighbour provided him with a prototype board, and he started porting MicroPython to the device.

The timing of an email from early May 2015 confirms it took Damien only a week to get MicroPython into a usable state (used with permission):

I signed up to mbed, exported the blinky example for the mkit and got it compiling locally using a local toolchain. And then using this I managed to get MicroPython compiling and running on the mkit! There is a surprisingly large amount of room: I could enable floating point support, aribitrary precision integers, most of the Python features and a few builtin modules. The REPL works over the USB-UART with history and tab completion. It even has a working ctrl-C (meaning you can break out of an infinite loop). I implemented a basic “pyb” module with LED and Switch classes, and a delay function. So you can do something like:

led = pyb.LED(1)
while True:
    led.toggle()
    pyb.delay(100)

Thanks in part to Damien’s efforts, devices capable of running MicroPython are in the hands of a million children. Most importantly, the BBC’s micro:bit project has inspired others to recreate the project in their own locale [all the source code and hardware plans have been released under an open source license]. For example, developers in Germany are already in the advanced stages of releasing Calliope, based upon the micro:bit and also capable of running MicroPython.

Success breeds success, and MicroPython came to the attention of the wider world, including Adafruit Industries.

Adafruit, the brainchild of Limor “ladyada” Fried, is an open source hardware company with an international reputation for creating playful devices (such as its “Feather” line of boards), supplying components (from generic electrical parts to branded lines of components such as the popular and ubiquitous NeoPixels), and creating accessible educational resources available from its website and YouTube channel. Adafruit’s MicroPython learning resources are numerous, inspiring, and some of the best written and helpfully illustrated to be found anywhere. If you’re ever stuck for inspiration, check out these resources.

One such Adafruit device is the latest version of the Circuit Playground Express. It runs Adafruit’s customised version of MicroPython called CircuitPython and contains a remarkable number of onboard input and output peripherals such as a speaker, microphone, touch-sensitive pins, and multicolour NeoPixels, to name but a few.

Perhaps the only thing missing from this device is wireless networking for connecting to the internet. Given how the “Internet of Things” (IoT) is the buzzword du jour, one would be forgiven for thinking that MicroPython is missing out.¹⁰ It is not!

The Internet of Things is a network of everyday objects. Within these everyday objects are embedded sensors, software, and connectivity to enable data exchange. It means light bulbs, toasters, refrigerators, flower pots, watches, fans, planes, trains, automobiles, and even the kitchen sink could contain programmable, microcontroller-based devices. The vision of IoT is for computing devices to permeate everything around us and interconnect across the internet. Happily, there are a couple of cheap microcontrollers—the ESP8266 and ESP32—that are perfect for IoT projects. Guess what? They both run MicroPython!

This is both a grave and exciting prospect.

Grave, because of the potential for devices under the control of third parties to be monitoring and communicating about private spaces and personal aspects of our lives.

Exciting, because those of us who program can repurpose these devices or make our own embedded hardware under our own control to create interesting and useful projects.

MicroPython is at the heart of the exciting potential of networked microcontrollers because, as mentioned, it has been ported to two WiFi-capable microcontrollers, the popular ESP8266 and its replacement, the ESP32. The ESP8266 has built-in WiFi, and the ESP32 also adds additional support for Bluetooth.

Building on their success, Damien and Viktoriya ran a second Kickstarter campaign in 2016 with the modest aim of raising £6,000 to help support a port to the ESP8266. They were joined in this endeavour by Paul Sokolovsky, a collaborator and core MicroPython maintainer who had been making contributions to MicroPython from just after the first Kickstarter campaign. At almost £30,000 later, it was obvious Damien and Viktoriya had another success on their hands, and development got underway. Thanks to these efforts and the support of the Kickstarter backers, MicroPython runs well on the device. It is possible to write MicroPython code and build embedded projects that communicate over the internet with a board that costs less than $5. Such boards contain both the ESP8266 microcontroller and GPIO pins to which peripherals can be attached.

Development on the ESP32 port is in the advanced stages, and it is already quite usable (if you can get your hands on a board).

Dive In!

This book explores MicroPython with the aforementioned devices. They’re typical of the different sorts of devices MicroPython supports, so skill and knowledge transfer to the many other supported devices should be easy.

All of them are relatively affordable, and each is different enough from the others to demonstrate that not only is MicroPython an extraordinarily flexible platform, but also that there’s an interesting diversity in capability, intention, and potential use cases in the MicroPython device ecosystem. Since new ports of MicroPython and new devices are released regularly, there is a good chance the device you may be using doesn’t even exist at the time of writing. Nevertheless, the principles, techniques, and knowledge found in this book are easy to adapt to new ports and devices.

The remainder of this book is organised into the following sections:

• Introductory chapters that describe the four boards: the original PyBoard, the micro:bit, Adafruit’s Circuit Playground Express, and the ESP8266/ESP32 family of boards. Each chapter describes the boards, their capabilities, how to flash MicroPython onto the devices,¹¹ put your code on the device, connect to the Python REPL, and make an LED blink. If you can make an LED blink, all the essentials are in place.
• A chapter on thinking about embedded development: its scope, potential, opportunities, and potential pitfalls. This will primarily use David Rose’s lists of attributes (mentioned in an earlier footnote) to provide a framework.
• A series of chapters relating to various aspects and capabilities of MicroPython, introduced and explained by practical examples in code that target the four devices: visual feedback, input and sensing, GPIO, networking, sound and music, and robotics. The examples are written to be extended and to act as launchpads for your own fun projects.
• A chapter on idiomatic MicroPython. Writing code in such constrained circumstances can pose unique challenges that don’t usually impact regular Python development. For example, we will cover what to do when you inevitably encounter memory-related errors. We will also consider what options you have for improving the performance of MicroPython by squeezing as much performance as possible from the microcontroller.
• A conclusion containing pointers for your next steps.

This book provides you with all the knowledge you’ll need to roll up your sleeves, get stuck in, and create something wonderful with MicroPython.

Most importantly, using MicroPython will be fun. Let’s get started.

¹ MicroPython works on many different devices. The four used in this book were chosen because they represent the diversity of choice while being exemplars of the different sorts of device that are available. If you have a different sort of embedded device running MicroPython, the general principles outlined in this book remain the same, and it should be relatively simple to adapt the code examples.

² Such text-based worlds are called MOOs (multiuser object orientation), and many are still available online. See https://en.wikipedia.org/wiki/MOO.

³ We’ll look at what it means for an object to be “enchanted” in greater detail later in the book, especially with reference to a framework of ideas suggested by Professor David Rose of the Massachusetts Institute of Technology (MIT).

⁴ IEEE Spectrum, “The 2016 Top Programming Languages”, posted 26 Jul 2016.

⁵ The available modules, including some not in the standard library (such as urequests), can be found at https://github.com/micropython/micropython-lib.

⁶ Use of “u” is shorthand for the Greek letter µ (pronounced “mu”), which stands for “micro” (small) in the metric measurement system.

⁷ REPL stands for “read, evaluate, print, loop”. It’s what you get when you type python from the command line and see three chevrons (>>>) prompting you do some interactive Python programming.

⁸ Viktoriya’s contributions to the MicroPython project have been and continue to be fundamental to its success and growth. The sacrifices, support, and efforts of non-technical partners of free software developers are often overlooked. In this case, the MicroPython Kickstarter was very much a Damien and Viktoriya team effort, with each complementing the other’s skills and expertise.

⁹ With an emphasis on determinism of the virtual machine and memory management.

¹⁰ Actually, the micro:bit has a beautifully simple radio that makes it perfect for IoT projects, and the Circuit Playground Express can send and receive messages via infrared light. We’ll explore such capabilities further in Chapter 10.

¹¹ The term flash means to erase and re-write memory. When you flash MicroPython onto a device, you’re loading it into the device’s memory. The term flash originates from the practice of flashing ultraviolet light onto an EPROM memory chip in order to erase it before being reprogrammed. These days we flash via USB.