Pycopy Documentation Release 3.6.0
Total Page:16
File Type:pdf, Size:1020Kb
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 Interpreter 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 Microcontrollers........................................ 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 esp32 — 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..........................................