MicroPython

Note this page describes how to use a MicroPython.org version of this library with MicroPython boards. Skip back to the previous page if you're using a CircuitPython board like the Feather M0 express!

In addition to CircuitPython there's an older MicroPython version of the TFT library that you can use with some MicroPython boards.  Before you get started it will help to be familiar with these guides for working with MicroPython:

See all the MicroPython guides in the learning system for more information.

MicroPython Module Install

To use the TFT display with your MicroPython board you'll need to install the micropython-adafruit-rgb-display MicroPython module on your board.  Remember this module is for MicroPython.org firmware and not Adafruit CircuitPython!

First make sure you are running the latest version of MicroPython for your board.  If you're using the ESP8266 MicroPython port you must be running version 1.8.5 or higher as earlier versions do not support using .mpy modules as shown in this guide.  

Next download the latest ili9341.mpy and rgb.mpy file from the releases page of the micropython-adafruit-rgb-display GitHub repository and use a tool like ampy to copy the files to the board.

Usage

The following section will show how to control the ILI9341 display from the board's Python prompt / REPL.   First connect to the board's serial REPL so you are at the MicroPython >>> prompt.

SPI Initialization

On MicroPython.org firmware which uses the machine API you can initialize SPI like the MicroPython SPI guide mentions.  For example on the ESP8266 with TFT FeatherWing you can run:

Download: file
import machine
spi = machine.SPI(1, baudrate=32000000)

Notice how the baudrate is specifying the SPI bus clock speed at 32mhz.  This means pixel data will be sent very quickly to the display--much quicker than a software SPI interface.  These displays can actually run up to about 64mhz but the ESP8266 SPI hardware can't support that fast of a speed!

Display Initialization

Next to import the display library and initialize it run the following code:

Download: file
import ili9341
display = ili9341.ILI9341(spi, cs=machine.Pin(0), dc=machine.Pin(15))

 When creating the display instance of the ILI9341 class you'll need to know which pins are connected to the display's CSDC, and optionally RST or reset line.  For the TFT FeatherWing see its guide for details on these pin connections.

The CS and DC parameters to the ILI9341 class initializer are required and should be a pin instance.  There are a few optional keyword arguments you can specify too:

  • rst - This is a GPIO pin connected to the RST or reset line on the display.  The default for this is to not be specified and reset is not used.
  • width - The width of the display in pixels, the default is 240.
  • height - The height of the display in pixels, the default is 320.

Drawing

After initializing SPI and the display you're ready to start drawing on it.  The usage of the drawing library is exactly the same as with CircuitPython so check out the CircuitPython drawing information--the same code will work on MicroPython too!

This guide was first published on Nov 16, 2016. It was last updated on Nov 16, 2016. This page (MicroPython) was last updated on Feb 23, 2020.