MicroPython Documentation
                                              Release 1.10
           DamienP.George,PaulSokolovsky,andcontributors
                                                  Jan25,2019
                                                                                                                                                                                                     CONTENTS
                             1     MicroPythonlibraries                                                                                                                                                                 1
                                   1.1        Python standard libraries and micro-libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                 2
                                              1.1.1         Builtin functions and exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                            2
                                              1.1.2         array–arraysofnumericdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                   5
                                              1.1.3         cmath–mathematicalfunctions for complex numbers . . . . . . . . . . . . . . . . . . . .                                                                     5
                                              1.1.4         gc–controlthegarbage collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                6
                                              1.1.5         math–mathematicalfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                  7
                                              1.1.6         sys–systemspecificfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                  9
                                              1.1.7         ubinascii–binary/ASCIIconversions . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                   11
                                              1.1.8         ucollections–collectionandcontainertypes . . . . . . . . . . . . . . . . . . . . . .                                                                      11
                                              1.1.9         uerrno–systemerrorcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                 12
                                              1.1.10        uhashlib–hashingalgorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                  13
                                              1.1.11        uheapq–heapqueuealgorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                 14
                                              1.1.12        uio–input/output streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                            14
                                              1.1.13        ujson–JSONencodinganddecoding . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                     16
                                              1.1.14        uos–basic“operating system” services . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                              16
                                              1.1.15        ure–simpleregularexpressions                              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . .              20
                                              1.1.16        uselect–waitforeventsonasetofstreams . . . . . . . . . . . . . . . . . . . . . . . .                                                                      22
                                              1.1.17        usocket–socketmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                23
                                              1.1.18        ussl–SSL/TLSmodule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                  28
                                              1.1.19        ustruct–packandunpackprimitivedatatypes . . . . . . . . . . . . . . . . . . . . . . .                                                                     29
                                              1.1.20        utime–timerelatedfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                30
                                              1.1.21        uzlib–zlibdecompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                               33
                                              1.1.22        _thread–multithreadingsupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                 33
                                   1.2        MicroPython-specific libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                               33
                                              1.2.1         btree–simpleBTreedatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                 33
                                              1.2.2         framebuf—Framebuffermanipulation . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                    36
                                              1.2.3         machine—functionsrelatedtothehardware . . . . . . . . . . . . . . . . . . . . . . . .                                                                     38
                                              1.2.4         micropython–accessandcontrolMicroPythoninternals . . . . . . . . . . . . . . . . .                                                                        55
                                              1.2.5         network—networkconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                   57
                                              1.2.6         ucryptolib–cryptographicciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                   66
                                              1.2.7         uctypes–accessbinarydatainastructured way . . . . . . . . . . . . . . . . . . . . . .                                                                     67
                                   1.3        Libraries specific to the pyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                              71
                                              1.3.1         pyb—functionsrelated to the board . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                               71
                                              1.3.2         lcd160cr—controlofLCD160CRdisplay . . . . . . . . . . . . . . . . . . . . . . . . . 109
                                   1.4        Libraries specific to the WiPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
                                              1.4.1         wipy–WiPyspecificfeatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
                                              1.4.2         class TimerWiPy – control hardware timers . . . . . . . . . . . . . . . . . . . . . . . . . . 114
                                              1.4.3         class TimerChannel — setup a channel for a timer . . . . . . . . . . . . . . . . . . . . . . . 116
                                   1.5        Libraries specific to the ESP8266 and ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
                                                                                                                                                                                                                        i
                                              1.5.1         esp—functionsrelated to the ESP8266 and ESP32 . . . . . . . . . . . . . . . . . . . . . 117
                                              1.5.2         esp32—functionalityspecific to the ESP32 . . . . . . . . . . . . . . . . . . . . . . . . . 118
                             2     TheMicroPythonlanguage                                                                                                                                                           121
                                   2.1        Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
                                   2.2        TheMicroPythonInteractive Interpreter Mode (aka REPL) . . . . . . . . . . . . . . . . . . . . . . . 123
                                              2.2.1         Auto-indent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
                                              2.2.2         Auto-completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
                                              2.2.3         Interrupting a running program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
                                              2.2.4         Paste Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
                                              2.2.5         Soft Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
                                              2.2.6         Thespecial variable _ (underscore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
                                              2.2.7         RawMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
                                   2.3        Writing interrupt handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
                                              2.3.1         Tips and recommended practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
                                              2.3.2         MicroPython Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
                                              2.3.3         Exceptions           .   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . . . . 129
                                              2.3.4         General Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
                                   2.4        Maximising MicroPython Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
                                              2.4.1         Designing for speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
                                              2.4.2         Identifying the slowest section of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
                                              2.4.3         MicroPython code improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
                                              2.4.4         TheNative code emitter                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . . 135
                                              2.4.5         TheVipercodeemitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
                                              2.4.6         Accessing hardware directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
                                   2.5        MicroPython on Microcontrollers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
                                              2.5.1         Flash Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
                                              2.5.2         RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
                                              2.5.3         TheHeap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
                                              2.5.4         String Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
                                              2.5.5         Postscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
                                   2.6        Distribution packages, package management, and deploying applications . . . . . . . . . . . . . . . 144
                                              2.6.1         Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
                                              2.6.2         Distribution packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
                                              2.6.3         upippackagemanager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
                                              2.6.4         Cross-installing packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
                                              2.6.5         Cross-installing packages with freezing                            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . 146
                                              2.6.6         Creating distribution packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
                                              2.6.7         Application resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
                                              2.6.8         References           .   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . . . . 148
                                   2.7        Inline Assembler for Thumb2 architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
                                              2.7.1         Documentconventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
                                              2.7.2         Instruction Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
                                              2.7.3         Usage examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
                                              2.7.4         References           .   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . . . 161
                             3     MicroPythondifferences from CPython                                                                                                                                              163
                                   3.1        Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
                                              3.1.1         Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
                                              3.1.2         Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
                                   3.2        Core Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
                                              3.2.1         Classes        .  .   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . . . . . . . . . . . . . . . 164
                                              3.2.2         Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
                                              3.2.3         Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
                             ii