Pycopy Documentation Release 3.6.0

Damien P. George, Paul Sokolovsky, and contributors

Aug 31, 2021

Contents

1 License information 1

2 Pycopy language and implementation3 2.1 Glossary...... 3 2.2 Interactive Mode (aka REPL)...... 6 2.2.1 Auto-indent...... 6 2.2.2 Auto-completion...... 7 2.2.3 Interrupting a running program...... 7 2.2.4 Paste mode...... 8 2.2.5 Soft reset...... 8 2.2.6 The special variable _ (underscore)...... 9 2.2.7 Raw mode and raw-paste mode...... 9 2.3 MicroPython .mpy files...... 11 2.3.1 Versioning and compatibility of .mpy files...... 11 2.3.2 Binary encoding of .mpy files...... 12 2.4 Writing interrupt handlers...... 13 2.4.1 Tips and recommended practices...... 13 2.4.2 MicroPython issues...... 14 2.4.3 Exceptions...... 17 2.4.4 General issues...... 17 2.5 Maximising Speed...... 19 2.5.1 Designing for speed...... 20 2.5.2 Identifying the slowest section of code...... 22 2.5.3 MicroPython code improvements...... 22 2.5.4 The Native code emitter...... 23 2.5.5 The Viper code emitter...... 23 2.5.6 Accessing hardware directly...... 25 2.6 Usage on ...... 25 2.6.1 Flash memory...... 25 2.6.2 RAM...... 26 2.6.3 The heap...... 29 2.6.4 String operations...... 31 2.6.5 Postscript...... 31 2.7 Distribution packages, package management, and deploying applications...... 31 2.7.1 Overview...... 31 2.7.2 Distribution packages...... 32

i 2.7.3 upip package manager...... 32 2.7.4 Cross-installing packages...... 33 2.7.5 Cross-installing packages with freezing...... 33 2.7.6 Creating distribution packages...... 34 2.7.7 Application resources...... 34 2.7.8 References...... 35 2.8 Inline assembler for Thumb2 architectures...... 36 2.8.1 Document conventions...... 36 2.8.2 Instruction categories...... 36 2.8.3 Usage examples...... 45 2.8.4 References...... 49 2.9 Working with filesystems...... 49 2.9.1 VFS...... 50 2.9.2 Block devices...... 50 2.9.3 Filesystems...... 52 2.10 The pyboard.py tool...... 54 2.10.1 Running a command on the device...... 55 2.10.2 Running a script on the device...... 55 2.10.3 Filesystem access...... 55 2.10.4 Using the pyboard library...... 56

3 Pycopy libraries 57 3.1 Python standard libraries and micro-libraries...... 58 3.1.1 Builtin types, functions and exceptions (builtins)...... 58 3.1.2 cmath – mathematical functions for complex numbers...... 62 3.1.3 gc – control the garbage collector...... 63 3.1.4 math – mathematical functions...... 64 3.1.5 sys – system specific functions...... 66 3.1.6 uarray – arrays of numeric data...... 68 3.1.7 ubinascii – binary/ASCII conversions...... 68 3.1.8 ucollections – collection and container types...... 68 3.1.9 uerrno – system error codes...... 70 3.1.10 uhashlib – hashing algorithms...... 70 3.1.11 uheapq – heap queue algorithm...... 71 3.1.12 uio – input/output streams...... 71 3.1.13 ujson – JSON encoding and decoding...... 75 3.1.14 uos – basic “operating system” services...... 75 3.1.15 urandom – pseudo-random number generation...... 80 3.1.16 ure – simple regular expressions...... 80 3.1.17 uselect – wait for events on a set of streams...... 82 3.1.18 usocket – socket module...... 84 3.1.19 ussl – SSL/TLS module...... 89 3.1.20 ustruct – pack and unpack primitive data types...... 90 3.1.21 utime – time related functions...... 91 3.1.22 uzlib – zlib decompression...... 94 3.1.23 _thread – multithreading support...... 95 3.2 Pycopy-specific libraries...... 95 3.2.1 btree – simple BTree database...... 95 3.2.2 framebuf — frame buffer manipulation...... 97 3.2.3 machine — functions related to the hardware...... 100 3.2.4 pycopy – access and control Pycopy internals...... 121 3.2.5 network — network configuration...... 123 3.2.6 ubluetooth — low-level Bluetooth...... 132 3.2.7 ucryptolib – cryptographic ciphers...... 143 ii 3.2.8 uctypes – access binary data in a structured way...... 143 3.3 Port-specific libraries...... 149 3.4 Libraries specific to the Unix port...... 149 3.4.1 ffi – foreign function interface...... 149 3.5 Libraries specific to the pyboard...... 151 3.5.1 pyb — functions related to the board...... 151 3.5.2 lcd160cr — control of LCD160CR display...... 190 3.6 Libraries specific to the WiPy...... 196 3.6.1 wipy – WiPy specific features...... 197 3.6.2 class ADCWiPy – analog to digital conversion...... 197 3.6.3 class ADCChannel — read analog values from internal or external sources...... 198 3.6.4 class TimerWiPy – control hardware timers...... 198 3.6.5 class TimerChannel — setup a channel for a timer...... 199 3.7 Libraries specific to the ESP8266 and ESP32...... 200 3.7.1 esp — functions related to the ESP8266 and ESP32...... 200 3.7.2 — functionality specific to the ESP32...... 202 3.8 Libraries specific to the RP2040...... 206 3.8.1 rp2 — functionality specific to the RP2040...... 206

4 Differences from CPython 211 4.1 Syntax...... 211 4.1.1 Operators...... 211 4.1.2 Spaces...... 211 4.1.3 Unicode...... 212 4.2 Core language...... 212 4.2.1 Classes...... 212 4.2.2 Functions...... 215 4.2.3 Generator...... 216 4.2.4 Runtime...... 216 4.2.5 import...... 217 4.3 Builtin types...... 219 4.3.1 Exception...... 219 4.3.2 bytearray...... 220 4.3.3 bytes...... 221 4.3.4 dict...... 222 4.3.5 float...... 222 4.3.6 int...... 222 4.3.7 list...... 223 4.3.8 str...... 224 4.3.9 tuple...... 226 4.4 Modules...... 227 4.4.1 array...... 227 4.4.2 builtins...... 228 4.4.3 collections...... 229 4.4.4 json...... 229 4.4.5 struct...... 230 4.4.6 sys...... 230

5 Developing and building 233 5.1 Getting Started...... 233 5.1.1 Source control with git...... 233 5.1.2 Get the code...... 234 5.1.3 Compile and build the code...... 234 5.1.4 Building the documentation...... 236

iii 5.1.5 Running the tests...... 237 5.1.6 Folder structure...... 237 5.2 Writing tests...... 238 5.3 The ...... 239 5.3.1 Adding a grammar rule...... 239 5.3.2 Adding a lexical token...... 240 5.3.3 Parsing...... 241 5.3.4 Compiler passes...... 241 5.3.5 Emitting ...... 243 5.3.6 Emitting native code...... 243 5.4 Memory Management...... 244 5.4.1 The object model...... 244 5.4.2 Allocation of objects...... 245 5.5 Implementing a Module...... 246 5.5.1 Implementing a core module...... 247 5.6 Optimizations...... 248 5.6.1 Frozen bytecode...... 248 5.6.2 Variables...... 248 5.6.3 Allocation of memory...... 249 5.7 MicroPython string interning...... 249 5.7.1 Compile-time QSTR generation...... 249 5.7.2 Run-time QSTR generation...... 250 5.8 Maps and Dictionaries...... 250 5.8.1 Open addressing...... 251 5.8.2 Linear probing...... 251 5.9 The public API...... 252 5.10 Extending MicroPython in C...... 252 5.10.1 MicroPython external C modules...... 252 5.10.2 Native machine code in .mpy files...... 256 5.11 Porting MicroPython...... 260 5.11.1 Minimal MicroPython firmware...... 260 5.11.2 MicroPython Configurations...... 262 5.11.3 Support for standard input/output...... 263 5.11.4 Building and running...... 263 5.11.5 Adding a module to the port...... 264

6 Quick reference for the pyboard 265 6.1 General information about the pyboard...... 266 6.1.1 Local filesystem and SD card...... 266 6.1.2 Boot modes...... 266 6.1.3 Errors: flashing LEDs...... 267 6.1.4 Guide for using the pyboard with Windows...... 267 6.1.5 The pyboard hardware...... 267 6.1.6 Datasheets for the components on the pyboard...... 267 6.1.7 Datasheets for other components...... 268 6.2 MicroPython tutorial for the pyboard...... 268 6.2.1 Introduction to the pyboard...... 268 6.2.2 Running your first script...... 269 6.2.3 Getting a MicroPython REPL prompt...... 272 6.2.4 Turning on LEDs and basic Python concepts...... 273 6.2.5 Switches, callbacks and interrupts...... 275 6.2.6 The accelerometer...... 277 6.2.7 Safe mode