MicroPython Documentation Release 1.9.4 Damien P. George, Paul Sokolovsky, and contributors Oct 01, 2018 CONTENTS 1 Quick reference for the ESP82661 1.1 Installing MicroPython..........................................1 1.2 General board control..........................................1 1.3 Networking................................................2 1.4 Delay and timing.............................................2 1.5 Timers..................................................3 1.6 Pins and GPIO..............................................3 1.7 PWM (pulse width modulation).....................................3 1.8 ADC (analog to digital conversion)...................................4 1.9 Software SPI bus.............................................4 1.10 Hardware SPI bus............................................4 1.11 I2C bus..................................................5 1.12 Real time clock (RTC)..........................................5 1.13 Deep-sleep mode.............................................5 1.14 OneWire driver..............................................6 1.15 NeoPixel driver..............................................6 1.16 APA102 driver..............................................6 1.17 DHT driver................................................7 1.18 WebREPL (web browser interactive prompt)..............................7 2 General information about the ESP8266 port9 2.1 Multitude of boards...........................................9 2.2 Technical specifications and SoC datasheets...............................9 2.3 Scarcity of runtime resources...................................... 10 2.4 Boot process............................................... 10 2.5 Known Issues............................................... 11 2.5.1 Real-time clock......................................... 11 2.5.2 Sockets and WiFi buffers overflow............................... 11 2.5.3 SSL/TLS limitations...................................... 11 3 MicroPython tutorial for ESP8266 13 3.1 Getting started with MicroPython on the ESP8266........................... 13 3.1.1 Requirements.......................................... 13 3.1.2 Powering the board....................................... 13 3.1.3 Getting the firmware...................................... 14 3.1.4 Deploying the firmware..................................... 14 3.1.5 Serial prompt.......................................... 15 3.1.6 WiFi............................................... 15 3.1.7 Troubleshooting installation problems............................. 15 3.2 Getting a MicroPython REPL prompt.................................. 16 i 3.2.1 REPL over the serial port.................................... 16 3.2.2 WebREPL - a prompt over WiFi................................ 16 3.2.3 Using the REPL......................................... 17 3.3 The internal filesystem.......................................... 19 3.3.1 Creating and reading files.................................... 19 3.3.2 Listing file and more...................................... 20 3.3.3 Start up scripts......................................... 20 3.3.4 Accessing the filesystem via WebREPL............................ 20 3.4 Network basics.............................................. 20 3.4.1 Configuration of the WiFi.................................... 21 3.4.2 Sockets............................................. 21 3.5 Network - TCP sockets.......................................... 21 3.5.1 Star Wars Asciimation..................................... 22 3.5.2 HTTP GET request....................................... 22 3.5.3 Simple HTTP server...................................... 23 3.6 GPIO Pins................................................ 23 3.6.1 External interrupts....................................... 24 3.7 Pulse Width Modulation......................................... 25 3.7.1 Fading an LED......................................... 25 3.7.2 Control a hobby servo...................................... 26 3.8 Analog to Digital Conversion...................................... 26 3.9 Power control............................................... 26 3.9.1 Changing the CPU frequency.................................. 26 3.9.2 Deep-sleep mode........................................ 27 3.10 Controlling 1-wire devices........................................ 27 3.11 Controlling NeoPixels.......................................... 28 3.12 Temperature and Humidity........................................ 29 3.13 Next steps................................................ 30 4 MicroPython libraries 31 4.1 Python standard libraries and micro-libraries.............................. 31 4.1.1 Builtin functions and exceptions................................ 32 4.1.2 array – arrays of numeric data................................ 35 4.1.3 gc – control the garbage collector............................... 35 4.1.4 math – mathematical functions................................ 36 4.1.5 sys – system specific functions................................ 38 4.1.6 ubinascii – binary/ASCII conversions........................... 40 4.1.7 ucollections – collection and container types...................... 40 4.1.8 uerrno – system error codes................................. 41 4.1.9 uhashlib – hashing algorithms............................... 42 4.1.10 uheapq – heap queue algorithm................................ 42 4.1.11 uio – input/output streams................................... 43 4.1.12 ujson – JSON encoding and decoding............................ 44 4.1.13 uos – basic “operating system” services............................ 45 4.1.14 ure – simple regular expressions............................... 48 4.1.15 uselect – wait for events on a set of streams........................ 50 4.1.16 usocket – socket module................................... 51 4.1.17 ussl – SSL/TLS module................................... 55 4.1.18 ustruct – pack and unpack primitive data types....................... 56 4.1.19 utime – time related functions................................ 57 4.1.20 uzlib – zlib decompression.................................. 60 4.2 MicroPython-specific libraries...................................... 60 4.2.1 btree – simple BTree database................................ 60 4.2.2 framebuf — Frame buffer manipulation........................... 63 ii 4.2.3 machine — functions related to the hardware........................ 65 4.2.4 micropython – access and control MicroPython internals................. 79 4.2.5 network — network configuration.............................. 81 4.2.6 uctypes – access binary data in a structured way...................... 85 4.3 Libraries specific to the ESP8266.................................... 88 4.3.1 esp — functions related to the ESP8266........................... 88 5 The MicroPython language 91 5.1 Glossary................................................. 91 5.2 The MicroPython Interactive Interpreter Mode (aka REPL)....................... 93 5.2.1 Auto-indent........................................... 93 5.2.2 Auto-completion........................................ 93 5.2.3 Interrupting a running program................................. 94 5.2.4 Paste Mode........................................... 94 5.2.5 Soft Reset............................................ 95 5.2.6 The special variable _ (underscore)............................... 96 5.2.7 Raw Mode........................................... 96 5.3 Writing interrupt handlers........................................ 96 5.3.1 Tips and recommended practices................................ 96 5.3.2 MicroPython Issues....................................... 97 5.3.3 Exceptions........................................... 99 5.3.4 General Issues.......................................... 100 5.4 Maximising MicroPython Speed..................................... 102 5.4.1 Designing for speed....................................... 103 5.4.2 Identifying the slowest section of code............................. 104 5.4.3 MicroPython code improvements................................ 105 5.4.4 The Native code emitter.................................... 105 5.4.5 The Viper code emitter..................................... 106 5.4.6 Accessing hardware directly.................................. 107 5.5 MicroPython on Microcontrollers.................................... 108 5.5.1 Flash Memory.......................................... 108 5.5.2 RAM.............................................. 108 5.5.3 The Heap............................................ 112 5.5.4 String Operations........................................ 113 5.5.5 Postscript............................................ 114 5.6 Distribution packages, package management, and deploying applications............... 114 5.6.1 Overview............................................ 114 5.6.2 Distribution packages...................................... 114 5.6.3 upip package manager..................................... 115 5.6.4 Cross-installing packages.................................... 116 5.6.5 Cross-installing packages with freezing............................ 116 5.6.6 Creating distribution packages................................. 117 5.6.7 Application resources...................................... 117 5.6.8 References........................................... 118 6 MicroPython differences from CPython 119 6.1 Syntax.................................................. 119 6.1.1 Spaces.............................................. 119 6.1.2 Unicode............................................