MicroPython Documentation
                                             Release 1.18
           DamienP.George,PaulSokolovsky,andcontributors
                                                 Jan16,2022
                                                                                                                             CONTENTS
                    1   MicroPythonlibraries                                                                                                     1
                        1.1    Python standard libraries and micro-libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .         1
                               1.1.1    array–arraysofnumericdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .              2
                               1.1.2    binascii–binary/ASCIIconversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .               2
                               1.1.3    builtins–builtin functions and exceptions          . . . . . . . . . . . . . . . . . . . . . . . . .     3
                               1.1.4    cmath–mathematicalfunctions for complex numbers              . . . . . . . . . . . . . . . . . . . .     5
                               1.1.5    collections–collection and container types           . . . . . . . . . . . . . . . . . . . . . . . .     6
                               1.1.6    errno–systemerrorcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .             7
                               1.1.7    gc–control the garbage collector       . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .     8
                               1.1.8    hashlib–hashingalgorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .              9
                               1.1.9    heapq–heapqueuealgorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .             10
                               1.1.10   io–input/output streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .        10
                               1.1.11   json–JSONencodinganddecoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                 12
                               1.1.12   math–mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .          12
                               1.1.13   os–basicoperating system services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .          15
                               1.1.14   random–generaterandomnumbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .               19
                               1.1.15   re–simpleregular expressions         . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
                               1.1.16   select–waitforeventsonasetofstreams . . . . . . . . . . . . . . . . . . . . . . . . . .                23
                               1.1.17   socket–socketmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .            24
                               1.1.18   ssl–SSL/TLSmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .            29
                               1.1.19   struct–packandunpackprimitivedatatypes . . . . . . . . . . . . . . . . . . . . . . . .                 30
                               1.1.20   sys–systemspecificfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           31
                               1.1.21   time–timerelated functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .         33
                               1.1.22   uasyncio asynchronous I/O scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . .            36
                               1.1.23   zlib–zlibdecompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           41
                               1.1.24   _thread–multithreading support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           41
                        1.2    MicroPython-specific libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .       42
                               1.2.1    bluetooth low-level Bluetooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .          42
                               1.2.2    btree–simpleBTreedatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .              53
                               1.2.3    cryptolib–cryptographic ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .            56
                               1.2.4    framebuf framebuffermanipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .              56
                               1.2.5    machine functions related to the hardware . . . . . . . . . . . . . . . . . . . . . . . . . .          59
                               1.2.6    micropython–accessandcontrolMicroPythoninternals . . . . . . . . . . . . . . . . . .                   86
                               1.2.7    neopixel control of WS2812 / NeoPixel LEDs . . . . . . . . . . . . . . . . . . . . . . . .             88
                               1.2.8    network network configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .           89
                               1.2.9    uctypes–accessbinarydata in a structured way . . . . . . . . . . . . . . . . . . . . . . .             99
                        1.3    Port-specific libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
                               1.3.1    Libraries specific to the pyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
                               1.3.2    Libraries specific to the WiPy      . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
                               1.3.3    Libraries specific to the ESP8266 and ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . 156
                                                                                                                                                 i
                                              1.3.4         Libraries specific to the RP2040 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
                                              1.3.5         Libraries specific to Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
                                   1.4        Extending built-in libraries from Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
                             2     MicroPythonlanguageandimplementation                                                                                                                                             173
                                   2.1        Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
                                   2.2        TheMicroPythonInteractive Interpreter Mode (aka REPL)                                              .  . . . . . . . . . . . . . . . . . . . . . 175
                                              2.2.1         Auto-indent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
                                              2.2.2         Auto-completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
                                              2.2.3         Interrupting a running program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
                                              2.2.4         Paste mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
                                              2.2.5         Soft reset        .  .   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
                                              2.2.6         Thespecial variable _ (underscore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
                                              2.2.7         Rawmodeandraw-pastemode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
                                   2.3        MicroPython remote control: mpremote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
                                              2.3.1         Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
                                              2.3.2         Shortcuts         .  .   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
                                              2.3.3         Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
                                   2.4        MicroPython .mpy files                     . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
                                              2.4.1         Versioning and compatibility of .mpy files . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
                                              2.4.2         Binary encoding of .mpy files                        . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
                                   2.5        Writing interrupt handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
                                              2.5.1         Tips and recommended practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
                                              2.5.2         MicroPython issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
                                              2.5.3         Exceptions           .   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
                                              2.5.4         General issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
                                   2.6        Maximising MicroPython speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
                                              2.6.1         Designing for speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
                                              2.6.2         Identifying the slowest section of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
                                              2.6.3         MicroPython code improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
                                              2.6.4         TheNative code emitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
                                              2.6.5         TheVipercodeemitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
                                              2.6.6         Accessing hardware directly                      . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
                                   2.7        MicroPython on microcontrollers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
                                              2.7.1         Flash memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
                                              2.7.2         RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
                                              2.7.3         Theheap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
                                              2.7.4         String operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
                                              2.7.5         Postscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
                                   2.8        MicroPython manifest files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
                                              2.8.1         Freezing source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
                                              2.8.2         Including other manifest files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
                                              2.8.3         Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
                                   2.9        Distribution packages, package management, and deploying applications                                                   .  . . . . . . . . . . . . . . 207
                                              2.9.1         Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
                                              2.9.2         Distribution packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
                                              2.9.3         upippackagemanager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
                                              2.9.4         Cross-installing packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
                                              2.9.5         Cross-installing packages with freezing                            . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
                                              2.9.6         Creating distribution packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
                                              2.9.7         Application resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
                                              2.9.8         References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
                                   2.10 Inline assembler for Thumb2 architectures                                     .  .  .  .  . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
                                              2.10.1        Documentconventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
                             ii