MicroPython Documentation Release 0.0.0 Damien P. George and contributors Aug 08, 2017 Contents 1 Core Modules 3 1.1 Support Matrix..............................................3 1.2 Modules.................................................3 1.2.1 analogio — Analog hardware support...........................3 1.2.2 audioio — Support for audio input and output.......................5 1.2.3 bitbangio — Digital protocols implemented by the CPU.................7 1.2.4 board — Board specific pin names.............................. 10 1.2.5 busio — Hardware accelerated behavior........................... 10 1.2.6 digitalio — Basic digital pin support........................... 15 1.2.7 microcontroller — Pin references and core functionality................ 17 1.2.8 neopixel_write — Low-level neopixel implementation................. 18 1.2.9 pulseio — Support for pulse based protocols........................ 18 1.2.10 time — time and timing related functions.......................... 22 1.2.11 touchio — Touch related IO................................. 23 1.2.12 uheap — Heap size analysis.................................. 23 1.2.13 usb_hid — USB Human Interface Device.......................... 24 1.2.14 help() - Built-in method to provide helpful information.................. 24 2 Additional Libraries on GitHub 25 2.1 Bundle.................................................. 25 2.2 Foundational Libraries.......................................... 25 2.3 Helper Libraries............................................. 25 2.4 Drivers.................................................. 26 3 Adding *io support to other ports 27 3.1 File layout................................................ 27 3.2 Adding support.............................................. 27 3.2.1 Modifying the build....................................... 27 3.2.2 Hooking the modules in..................................... 28 3.2.3 Implementing the Common HAL................................ 29 3.2.4 Testing............................................. 29 4 Design Guide 31 4.1 Start libraries with the cookiecutter................................... 31 4.2 Module Naming............................................. 31 4.3 Lifetime and ContextManagers..................................... 31 4.4 Verify your device............................................ 32 i 4.5 Getters/Setters.............................................. 32 4.6 Design for compatibility with CPython................................. 33 4.6.1 Example............................................. 33 4.7 Document inline............................................. 33 4.7.1 Module description....................................... 33 4.7.2 Class description........................................ 33 4.7.3 Data descriptor description................................... 34 4.7.4 Method description....................................... 34 4.7.5 Property description....................................... 34 4.8 Use BusDevice.............................................. 34 4.8.1 I2C Example.......................................... 35 4.8.2 SPI Example.......................................... 35 4.9 Use composition............................................. 35 4.10 Lots of small modules.......................................... 36 4.11 Speed second............................................... 36 4.12 Avoid allocations in drivers....................................... 36 4.12.1 Examples............................................ 36 4.13 Sensor properties and units........................................ 36 4.14 Common APIs.............................................. 37 4.15 Adding native modules.......................................... 37 4.16 MicroPython compatibility........................................ 37 5 Supported Ports 39 5.1 SAMD21x18............................................... 39 5.1.1 Pinout.............................................. 39 5.1.2 Building............................................. 41 5.1.3 Deploying............................................ 41 5.1.4 Connecting........................................... 42 5.1.5 Port Specific modules...................................... 42 5.2 ESP8266................................................. 43 5.2.1 Quick reference for the ESP8266................................ 43 5.2.2 General information about the ESP8266 port......................... 49 5.2.3 MicroPython tutorial for ESP8266............................... 51 6 MicroPython libraries 69 6.1 Python standard libraries and micro-libraries.............................. 69 6.2 MicroPython-specific libraries...................................... 70 6.2.1 machine — functions related to the board.......................... 70 6.2.2 micropython – access and control MicroPython internals................. 84 6.2.3 network — network configuration.............................. 85 6.2.4 uctypes – access binary data in a structured way...................... 85 7 Adafruit CircuitPython 89 7.1 Project Status............................................... 89 7.1.1 Supported boards........................................ 89 7.2 Download................................................. 90 7.3 Documentation.............................................. 90 7.4 Contributing............................................... 90 7.5 Differences from MicroPython...................................... 90 7.6 Project Structure............................................. 91 7.6.1 Core............................................... 91 7.6.2 Ports............................................... 91 8 Contributing 93 8.1 Developer contact............................................ 93 ii 8.2 Licensing................................................. 93 8.3 Code guidelines............................................. 93 9 Contributor Covenant Code of Conduct 95 9.1 Our Pledge................................................ 95 9.2 Our Standards.............................................. 95 9.3 Our Responsibilities........................................... 96 9.4 Scope................................................... 96 9.5 Enforcement............................................... 96 9.6 Attribution................................................ 96 10 MicroPython & CircuitPython license information 97 11 Indices and tables 99 Python Module Index 101 iii iv MicroPython Documentation, Release 0.0.0 Welcome! This is the documentation for Adafruit CircuitPython. It is an open source derivative of MicroPython for use on educational development boards designed and sold by Adafruit. Adafruit CircuitPython features unified Python core APIs and a growing list of drivers that work with it. The Adafruit Express line of boards are specifically designed for use with CircuitPython. They are the CircuitPlay- ground Express, Feather M0 Express, and Metro M0 Express. Other supported boards include the Arduino Zero, Adafruit Feather M0 Basic, Adafruit Feather HUZZAH and Adafruit Feather M0 Bluefruit LE. Adafruit has many excellent tutorials available through the Adafruit Learning System. These docs are low-level API docs and may link out to separate getting started guides. Contents 1 MicroPython Documentation, Release 0.0.0 2 Contents CHAPTER 1 Core Modules These core modules are intended on being consistent across ports. Currently they are only implemented in the SAMD21 and ESP8266 ports. A module may not exist in a port if no underlying hardware support is present or if flash space is limited. For example, a microcontroller without analog features will not have analogio. Support Matrix Port analogioaudioiobitbangioboardbusiodigitaliomicrocontrollerneopixel_writepulseiotimetouchiouheapusb_hid SAMD21 Yes No No Yes Yes Yes Yes Yes No Yes Yes De- Yes bug SAMD21 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes De- Yes Ex- bug press ESP8266 Yes No Yes Yes Yes Yes Yes Yes No Yes No De- No bug Modules analogio — Analog hardware support The analogio module contains classes to provide access to analog IO typically implemented with digital-to-analog (DAC) and analog-to-digital (ADC) converters. Libraries AnalogIn – read analog voltage Usage: 3 MicroPython Documentation, Release 0.0.0 import analogio from board import * adc= analogio.AnalogIn(A1) val= adc.value class analogio.AnalogIn(pin) Use the AnalogIn on the given pin. The reference voltage varies by platform so use reference_voltage to read the configured setting. Parameters pin (Pin) – the pin to read from deinit() Turn off the AnalogIn and release the pin for other use. __enter__() No-op used by Context Managers. __exit__() Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info. value Read the value on the analog pin and return it. The returned value will be between 0 and 65535 inclusive (16-bit). Even if the underlying analog to digital converter (ADC) is lower resolution, the result will be scaled to be 16-bit. Returns the data read Return type int reference_voltage The maximum voltage measurable. Also known as the reference voltage. Returns the reference voltage Return type float AnalogOut – output analog voltage The AnalogOut is used to output analog values (a specific voltage). Example usage: import analogio from microcontroller import pin dac= analogio.AnalogOut(pin.PA02) # output on pin PA02 dac.value= 32768 # makes PA02 1.65V class analogio.AnalogOut(pin) Use the AnalogOut on the given pin. Parameters pin (Pin) – the pin to output to deinit() Turn off the AnalogOut and release the pin for other use. __enter__() No-op used by Context