MicroPython Documentation Release 1.9.2 Damien P. George, Paul Sokolovsky, and contributors August 23, 2017 CONTENTS 1 Quick reference for the pyboard1 1.1 General board control..........................................1 1.2 Delay and timing.............................................1 1.3 LEDs...................................................1 1.4 Pins and GPIO..............................................2 1.5 Servo control...............................................2 1.6 External interrupts............................................2 1.7 Timers..................................................2 1.8 PWM (pulse width modulation).....................................2 1.9 ADC (analog to digital conversion)...................................3 1.10 DAC (digital to analog conversion)...................................3 1.11 UART (serial bus)............................................3 1.12 SPI bus..................................................3 1.13 I2C bus..................................................4 2 General information about the pyboard5 2.1 Local filesystem and SD card......................................5 2.2 Boot modes................................................5 2.3 Errors: flashing LEDs..........................................6 2.4 Guide for using the pyboard with Windows...............................6 2.5 The pyboard hardware..........................................6 2.6 Datasheets for the components on the pyboard.............................6 2.7 Datasheets for other components.....................................7 3 MicroPython tutorial for the pyboard9 3.1 Introduction to the pyboard.......................................9 3.1.1 Caring for your pyboard....................................9 3.1.2 Layout of the pyboard.....................................9 3.1.3 Plugging in and powering on..................................9 3.1.4 Powering by an external power source............................. 10 3.2 Running your first script......................................... 10 3.2.1 Connecting your pyboard.................................... 10 3.2.2 Opening the pyboard USB drive................................ 11 3.2.3 Editing main.py ........................................ 12 3.2.4 Resetting the pyboard...................................... 12 3.3 Getting a MicroPython REPL prompt.................................. 13 3.3.1 Windows............................................ 13 3.3.2 Mac OS X............................................ 13 3.3.3 Linux.............................................. 13 3.3.4 Using the REPL prompt.................................... 14 3.3.5 Resetting the board....................................... 14 i 3.4 Turning on LEDs and basic Python concepts.............................. 14 3.4.1 A Disco on your pyboard.................................... 15 3.4.2 The Fourth Special LED.................................... 16 3.5 The Switch, callbacks and interrupts................................... 16 3.5.1 Switch callbacks........................................ 17 3.5.2 Technical details of interrupts................................. 17 3.5.3 Further reading......................................... 18 3.6 The accelerometer............................................ 18 3.6.1 Using the accelerometer.................................... 18 3.6.2 Making a spirit level...................................... 19 3.7 Safe mode and factory reset....................................... 19 3.7.1 Safe mode............................................ 19 3.7.2 Factory reset the filesystem................................... 20 3.8 Making the pyboard act as a USB mouse................................ 20 3.8.1 Sending mouse events by hand................................. 21 3.8.2 Making a mouse with the accelerometer............................ 21 3.8.3 Restoring your pyboard to normal............................... 22 3.9 The Timers................................................ 22 3.9.1 Timer counter.......................................... 23 3.9.2 Timer callbacks......................................... 23 3.9.3 Making a microsecond counter................................. 24 3.10 Inline assembler............................................. 24 3.10.1 Returning a value........................................ 24 3.10.2 Accessing peripherals...................................... 24 3.10.3 Accepting arguments...................................... 25 3.10.4 Loops.............................................. 25 3.10.5 Further reading......................................... 26 3.11 Power control............................................... 26 3.12 Tutorials requiring extra components.................................. 26 3.12.1 Controlling hobby servo motors................................ 26 3.12.2 Fading LEDs.......................................... 29 3.12.3 The LCD and touch-sensor skin................................ 32 3.12.4 The AMP audio skin...................................... 34 3.12.5 The LCD160CR skin...................................... 37 3.13 Tips, tricks and useful things to know.................................. 39 3.13.1 Debouncing a pin input..................................... 39 3.13.2 Making a UART - USB pass through.............................. 39 4 MicroPython libraries 41 4.1 Python standard libraries and micro-libraries.............................. 41 4.1.1 Builtin functions and exceptions................................ 42 4.1.2 array – arrays of numeric data................................ 44 4.1.3 cmath – mathematical functions for complex numbers.................... 45 4.1.4 gc – control the garbage collector............................... 46 4.1.5 math – mathematical functions................................ 46 4.1.6 sys – system specific functions................................ 49 4.1.7 ubinascii – binary/ASCII conversions........................... 50 4.1.8 ucollections – collection and container types...................... 51 4.1.9 uerrno – system error codes................................. 52 4.1.10 uhashlib – hashing algorithms............................... 52 4.1.11 uheapq – heap queue algorithm................................ 53 4.1.12 uio – input/output streams................................... 53 4.1.13 ujson – JSON encoding and decoding............................ 55 4.1.14 uos – basic “operating system” services............................ 55 ii 4.1.15 ure – simple regular expressions............................... 57 4.1.16 uselect – wait for events on a set of streams........................ 58 4.1.17 usocket – socket module................................... 59 4.1.18 ustruct – pack and unpack primitive data types....................... 63 4.1.19 utime – time related functions................................ 63 4.1.20 uzlib – zlib decompression.................................. 67 4.2 MicroPython-specific libraries...................................... 67 4.2.1 btree – simple BTree database................................ 67 4.2.2 framebuf — Frame buffer manipulation........................... 69 4.2.3 machine — functions related to the hardware........................ 71 4.2.4 micropython – access and control MicroPython internals................. 84 4.2.5 network — network configuration.............................. 86 4.2.6 uctypes – access binary data in a structured way...................... 90 4.3 Libraries specific to the pyboard..................................... 93 4.3.1 pyb — functions related to the board............................. 93 4.3.2 lcd160cr — control of LCD160CR display......................... 126 5 The MicroPython language 133 5.1 Glossary................................................. 133 5.2 The MicroPython Interactive Interpreter Mode (aka REPL)....................... 134 5.2.1 Auto-indent........................................... 134 5.2.2 Auto-completion........................................ 135 5.2.3 Interrupting a running program................................. 135 5.2.4 Paste Mode........................................... 136 5.2.5 Soft Reset............................................ 136 5.2.6 The special variable _ (underscore)............................... 137 5.2.7 Raw Mode........................................... 137 5.3 Writing interrupt handlers........................................ 137 5.3.1 Tips and recommended practices................................ 138 5.3.2 MicroPython Issues....................................... 138 5.3.3 Exceptions........................................... 140 5.3.4 General Issues.......................................... 140 5.4 Maximising MicroPython Speed..................................... 143 5.4.1 Designing for speed....................................... 143 5.4.2 Identifying the slowest section of code............................. 145 5.4.3 MicroPython code improvements................................ 145 5.4.4 The Native code emitter.................................... 146 5.4.5 The Viper code emitter..................................... 146 5.4.6 Accessing hardware directly.................................. 148 5.5 MicroPython on Microcontrollers.................................... 148 5.5.1 Flash Memory.......................................... 148 5.5.2 RAM.............................................. 149 5.5.3 The Heap............................................ 152 5.5.4 String Operations........................................ 154 5.5.5 Postscript............................................ 154 5.6 Inline Assembler for Thumb2 architectures..............................