Extend and expand your Circuit Playground projects with a bolt on TFT Gizmo that lets you add a lovely color display in a sturdy and reliable fashion. This PCB looks just like a round TFT breakout but has permanently affixed M3 standoffs that act as mechanical and electrical connections.

Once attached you'll get a 1.54" 240x240 IPS display with backlight control, two 3-pin STEMMA connectors for attaching NeoPixel strips or servos, and a Class D audio amplifier with a Molex PicoBlade connector that can plug one of our lil speakers.

This is a great companion for our Circuit Playground Express or Bluefruit boards thanks to their fast SPI hardware speeds, and works in Arduino and CircuitPython. You can use it with the Circuit Playground Classic but it won't be very fast, as you have to bitbang the SPI - and the display has a lot of pixels - so it's not recommended.

Comes with a PCB that has pre-soldered standoffs attached, and 12x M3 screws for attachment. Fits all Circuit Playgrounds but like we mentioned earlier, the Express and Bluefruit are recommended.

The TFT Gizmo uses SPI to receive image data. That means at least 5 pads are used - clock, data in, tft cs and d/c. An additional pin is used as a backlight control. These are already determined because of the bolt-on design. The TFT Gizmo also has a built-in audio amplifier and 2 JST connectors.

Power Pins

SPI Display Pins

Audio Pins

Extra Ports

Placing the Circuit Playground TFT Gizmo on the Circuit Playground Express or Circuit Playground Bluefruit is pretty straightforward. All you need is a #2 Phillips screwdriver.

Once you've assembled the TFT Gizmo onto your Circuit Playground you can test it by loading one of these pre-made UF2 onto your Circuit Playground with the TFT Gizmo attached - it will perform a graphics test so you know that the Gizmo's attached!

Circuit Playground Express

If you have a Circuit Playground Express, download this UF2 file by clicking below:

Circuit Playground Bluefruit

If you have a Circuit Playground Bluefruit, download this UF2 file by clicking below:

Running Text Example UF2

Once you've downloaded the appropriate UF2 file from above, plug in your Circuit Playground to your computer with a data/sync cable.

Double-click the reset button so that the boot drive folder shows up. This folder should be called CPLAYBOOT for the CP Express and CPLAYBTBOOT for the CP Bluefruit.

Drag-n-drop the downloaded UF2 onto CPLAYBOOT or CPLAYBTBOOT folder.

Press reset button to launch the code. If you don't get graphics on the TFT, check the assembly instructions on this page

This sketch is in Arduino, so after you've run this UF2, if you want to go back to CircuitPython, you'll need to re-install the CircuitPython UF2

Install Arduino Libraries

We have example code ready to go for use with these TFTs. It's written for Arduino, which should be portable to any microcontroller by adapting the C++ source.

Four libraries need to be installed using the Arduino Library Manager…this is the preferred and modern way. From the Arduino “Sketch” menu, select “Include Library” then “Manage Libraries…”

Type “gfx” in the search field to quickly find the first library — Adafruit_GFX:

Repeat the search and install steps, looking for the Adafruit BusIO, Adafruit Zero DMA, Adafruit ST7735 and ST7789, and Adafruit SPIFlash libraries.

After restarting the Arduino software, you should see a new example folder called Adafruit ST7735 and ST7789 Library, and inside, an example called graphicstest_tft_gizmo.

Now upload the sketch to your Circuit Playground board. You may need to press the Reset button to reset the Circuit Playground and TFT. You should see a collection of graphical tests draw out on the TFT.

Running in Software SPI mode

If you have a CircuitPlayground Classic or just want to run it as Software SPI for whatever reason, it's pretty easy to change. Due to the nature of the circular bolt-on style board that the gizmo is, physically changing pins isn't so easy, but we can change to software SPI, which is a bit slower. Find these lines:

// OPTION 1 (recommended) is to use the HARDWARE SPI pins, which are unique
// to each board and not reassignable.
Adafruit_ST7789 tft = Adafruit_ST7789(spi, TFT_CS, TFT_DC, TFT_RST);

// OPTION 2 lets you interface the display using ANY TWO or THREE PINS,
// tradeoff being that performance is not as fast as hardware SPI above.
//#define TFT_MOSI      PIN_WIRE_SDA  // Data out
//#define TFT_SCLK      PIN_WIRE_SCL  // Clock out
//Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_MOSI, TFT_SCLK, TFT_RST);

1
2
3
4
5
6
7
8
9

// OPTION 1 (recommended) is to use the HARDWARE SPI pins, which are unique
// to each board and not reassignable.
Adafruit_ST7789 tft = Adafruit_ST7789(spi, TFT_CS, TFT_DC, TFT_RST);

// OPTION 2 lets you interface the display using ANY TWO or THREE PINS,
// tradeoff being that performance is not as fast as hardware SPI above.
//#define TFT_MOSI      PIN_WIRE_SDA  // Data out
//#define TFT_SCLK      PIN_WIRE_SCL  // Clock out
//Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_MOSI, TFT_SCLK, TFT_RST);

Comment out option 1, and uncomment option 2 Then you can change the TFT_ pins to whatever pins you'd like!

Although there isn't a built in microSD card slot, we can still use the SPI flash to store and load bitmap images! It's really easy with Adafruit Arcada because it can make the SPI flash show up as a drive on your computer that you can easily copy files over to.

Let's start by downloading this image of Adabot and Blinka.

Required Libraries for Bitmaps

To draw Bitmaps, we'll be using the Arcada library, but there are a few other required libraries as well. If you haven't already, go ahead and take a look at the Arcada Libraries page to get all set up.

TinyUSB

Arcada Library

Start by opening the File→examples→Adafruit Arcada Library→imageloader_tft_gizmo example:

Uploading the Images

Now upload the example sketch to the Circuit Playground.

Now go ahead and copy adabot.bmp and blinka.bmp onto the root of the CIRCUITPY drive.

Press the buttons on the back of your Circuit Playground board. Pressing one should make ADABOT appear! Pressing the other will make BLINKA appear. If you have any problems, check the serial console for any messages such as not being able to initialize the flash or not finding the image.

Full ImageLoader Example

#include "Adafruit_Arcada.h"
Adafruit_Arcada arcada;

#define IMAGE_A "adabot.bmp"
#define IMAGE_B "blinka.bmp"

void setup(void) {
  if (!arcada.arcadaBegin()) {
    while (1);
  }
  // If we are using TinyUSB we will have the filesystem show up!
  arcada.filesysBeginMSD();

  Serial.begin(115200);
  //while(!Serial) delay(10);       // Wait for Serial Monitor before continuing

  arcada.enableSpeaker(false);

  // Start TFT and fill blue
  arcada.displayBegin();
  arcada.display->fillScreen(ARCADA_BLUE);
  arcada.setBacklight(255);

  if (arcada.filesysBegin()) {
    Serial.println("Found filesystem!");
  } else {
    arcada.haltBox("No filesystem found! For QSPI flash, load CircuitPython. For SD cards, format with FAT");
  }

  // Turn on backlight
  arcada.setBacklight(255);
}


void loop() {
  const char *imagefile = 0;
  arcada.readButtons();
  uint8_t buttons = arcada.justPressedButtons();
  Serial.print("Pressed: ");
  if (buttons & ARCADA_BUTTONMASK_LEFT) {
    imagefile = IMAGE_A;
    Serial.print("< ");
  }
  if (buttons & ARCADA_BUTTONMASK_RIGHT) {
    imagefile = IMAGE_B;
    Serial.print("> ");
  }
  Serial.println();

  delay(25);
  if (! imagefile) return;
 
  for (int i=255; i>=0; i--) {
    arcada.setBacklight(i);
    delay(1);
  }
  
  // Load full-screen BMP file at position (0,0) (top left).
  Serial.printf("Loading %s to screen...", imagefile);
  ImageReturnCode stat = arcada.drawBMP((char*) imagefile, 0, 0);
  if(stat == IMAGE_ERR_FILE_NOT_FOUND) {
    arcada.haltBox("File not found");
  } else if(stat == IMAGE_ERR_FORMAT) {
    arcada.haltBox("Not a supported BMP variant.");
  } else if(stat == IMAGE_ERR_MALLOC) {
    arcada.haltBox("Malloc failed (insufficient RAM).");  
  }
  for (int i=0; i<=255; i++) {
    arcada.setBacklight(i);
    delay(1);
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

#include "Adafruit_Arcada.h"
Adafruit_Arcada arcada;

#define IMAGE_A "adabot.bmp"
#define IMAGE_B "blinka.bmp"

void setup(void) {
  if (!arcada.arcadaBegin()) {
    while (1);
  }
  // If we are using TinyUSB we will have the filesystem show up!
  arcada.filesysBeginMSD();

  Serial.begin(115200);
  //while(!Serial) delay(10);       // Wait for Serial Monitor before continuing

  arcada.enableSpeaker(false);

  // Start TFT and fill blue
  arcada.displayBegin();
  arcada.display->fillScreen(ARCADA_BLUE);
  arcada.setBacklight(255);

  if (arcada.filesysBegin()) {
    Serial.println("Found filesystem!");
  } else {
    arcada.haltBox("No filesystem found! For QSPI flash, load CircuitPython. For SD cards, format with FAT");
  }

  // Turn on backlight
  arcada.setBacklight(255);
}


void loop() {
  const char *imagefile = 0;
  arcada.readButtons();
  uint8_t buttons = arcada.justPressedButtons();
  Serial.print("Pressed: ");
  if (buttons & ARCADA_BUTTONMASK_LEFT) {
    imagefile = IMAGE_A;
    Serial.print("< ");
  }
  if (buttons & ARCADA_BUTTONMASK_RIGHT) {
    imagefile = IMAGE_B;
    Serial.print("> ");
  }
  Serial.println();

  delay(25);
  if (! imagefile) return;
 
  for (int i=255; i>=0; i--) {
    arcada.setBacklight(i);
    delay(1);
  }
  
  // Load full-screen BMP file at position (0,0) (top left).
  Serial.printf("Loading %s to screen...", imagefile);
  ImageReturnCode stat = arcada.drawBMP((char*) imagefile, 0, 0);
  if(stat == IMAGE_ERR_FILE_NOT_FOUND) {
    arcada.haltBox("File not found");
  } else if(stat == IMAGE_ERR_FORMAT) {
    arcada.haltBox("Not a supported BMP variant.");
  } else if(stat == IMAGE_ERR_MALLOC) {
    arcada.haltBox("Malloc failed (insufficient RAM).");  
  }
  for (int i=0; i<=255; i++) {
    arcada.setBacklight(i);
    delay(1);
  }
}

You will need a board capable of running CircuitPython such as the Circuit Playground Express or Circuit Playground Bluefruit. The Circuit Playground Classic will only run Arduino sketches.

Circuit Playground Express with Displayio

If you have a Circuit Playground Express board, you will need a special build that includes displayio to use the TFT Gizmo. Be sure to download the latest one. You can find it here:

Required CircuitPython Libraries

To use this display with displayio, there are only two required libraries.

First, make sure you are running the latest version of Adafruit CircuitPython for your board.

Next, you'll need to install the necessary libraries to use the hardware Carefully follow the steps to find and install the library from Adafruit's CircuitPython library bundle.  Our introduction guide has a great page on how to install the library bundle for both Express and non-Express boards.

Due to the number of libraries in the bundle, it is recommended that you manually install the necessary library from the bundle:

• adafruit_st7789
• adafruit_gizmo

Before continuing make sure your board's lib folder has the adafruit_st7789.mpy and adafruit_gizmo file and folder copied over.

Code Example Additional Libraries

For the Code Example, you will need an additional library. We decided to make use of a library so the code didn't get overly complicated. You'll also need to copy over the following library from the bundle:

• adafruit_display_text

Go ahead and install this in the same manner as the driver library by copying the adafruit_display_text folder over to the lib folder on your CircuitPython device.

CircuitPython Code Example

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""
This test will initialize the display using displayio and draw a solid green
background, a smaller purple rectangle, and some yellow text.
"""

import displayio
import terminalio
from adafruit_display_text import label

from adafruit_gizmo import tft_gizmo

# Create the TFT Gizmo display
display = tft_gizmo.TFT_Gizmo()

# Make the display context
splash = displayio.Group()
display.root_group = splash

color_bitmap = displayio.Bitmap(240, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00  # Bright Green

bg_sprite = displayio.TileGrid(color_bitmap, pixel_shader=color_palette, x=0, y=0)
splash.append(bg_sprite)

# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088  # Purple
inner_sprite = displayio.TileGrid(inner_bitmap, pixel_shader=inner_palette, x=20, y=20)
splash.append(inner_sprite)

# Draw a label
text_group = displayio.Group(scale=2, x=50, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area)  # Subgroup for text scaling
splash.append(text_group)

while True:
    pass

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""
This test will initialize the display using displayio and draw a solid green
background, a smaller purple rectangle, and some yellow text.
"""

import displayio
import terminalio
from adafruit_display_text import label

from adafruit_gizmo import tft_gizmo

# Create the TFT Gizmo display
display = tft_gizmo.TFT_Gizmo()

# Make the display context
splash = displayio.Group()
display.root_group = splash

color_bitmap = displayio.Bitmap(240, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00  # Bright Green

bg_sprite = displayio.TileGrid(color_bitmap, pixel_shader=color_palette, x=0, y=0)
splash.append(bg_sprite)

# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088  # Purple
inner_sprite = displayio.TileGrid(inner_bitmap, pixel_shader=inner_palette, x=20, y=20)
splash.append(inner_sprite)

# Draw a label
text_group = displayio.Group(scale=2, x=50, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area)  # Subgroup for text scaling
splash.append(text_group)

while True:
    pass

Let's take a look at the sections of code one by one. We start by importing displayio,terminalio for the font, a label, and the tft_gizmo helper.

import displayio
import terminalio
from adafruit_display_text import label
from adafruit_gizmo import tft_gizmo

1
2
3
4

import displayio
import terminalio
from adafruit_display_text import label
from adafruit_gizmo import tft_gizmo

Next, we initialize the helper, which takes care of all the TFT Gizmo ST7789 Driver initialization for us. If we stopped at this point and ran the code, we would have a terminal that we could type at and have the screen update.

display = tft_gizmo.TFT_Gizmo()

1

display = tft_gizmo.TFT_Gizmo()

Next we create a background splash image. We do this by creating a group that we can add elements to and adding that group to the display. In this example, we are limiting the maximum number of elements to 10, but this can be increased if you would like. The display will automatically handle updating the group.

splash = displayio.Group(max_size=10)
display.root_group = splash

1
2

splash = displayio.Group(max_size=10)
display.root_group = splash

Next we create a Bitmap which is like a canvas that we can draw on. In this case we are creating the Bitmap to be the same size as the screen, but only have one color. The Bitmaps can currently handle up to 256 different colors. We create a Palette with one color and set that color to 0x00FF00 which happens to be green. Colors are Hexadecimal values in the format of RRGGBB. Even though the Bitmaps can only handle 256 colors at a time, you get to define what those 256 different colors are.

color_bitmap = displayio.Bitmap(240, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00 # Bright Green

1
2
3

color_bitmap = displayio.Bitmap(240, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00 # Bright Green

With all those pieces in place, we create a TileGrid by passing the bitmap and palette and draw it at (0, 0) which represents the display's upper left.

bg_sprite = displayio.TileGrid(color_bitmap,
                               pixel_shader=color_palette,
                               x=0, y=0)
splash.append(bg_sprite)

1
2
3
4

bg_sprite = displayio.TileGrid(color_bitmap,
                               pixel_shader=color_palette,
                               x=0, y=0)
splash.append(bg_sprite)

Next we will create a smaller purple square. The easiest way to do this is the create a new bitmap that is a little smaller than the full screen with a single color and place it in a specific location. In this case, we will create a bitmap that is 20 pixels smaller on each side. The screen is 240x240, so we'll want to subtract 40 from each of those numbers.

We'll also want to place it at the position (20, 20) so that it ends up centered.

inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088 # Purple
inner_sprite = displayio.TileGrid(inner_bitmap,
                                  pixel_shader=inner_palette,
                                  x=20, y=20)
splash.append(inner_sprite)

1
2
3
4
5
6
7

inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088 # Purple
inner_sprite = displayio.TileGrid(inner_bitmap,
                                  pixel_shader=inner_palette,
                                  x=20, y=20)
splash.append(inner_sprite)

Since we are adding this after the first square, it's automatically drawn on top. Here's what it looks like now.

Next let's add a label that says "Hello World!" on top of that. We're going to use the built-in Terminal Font and scale it up by a factor of two. To scale the label only, we will make use of a subgroup, which we will then add to the main group.

Labels are centered vertically, so we'll place it at 120 for the Y coordinate, and around 50 pixels make it appear to be centered horizontally, but if you want to change the text, change this to whatever looks good to you. Let's go with some yellow text, so we'll pass it a value of 0xFFFF00.

text_group = displayio.Group(max_size=10, scale=2, x=50, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area) # Subgroup for text scaling
splash.append(text_group)

1
2
3
4
5

text_group = displayio.Group(max_size=10, scale=2, x=50, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area) # Subgroup for text scaling
splash.append(text_group)

Finally, we place an infinite loop at the end so that the graphics screen remains in place and isn't replaced by a terminal.

while True:
    pass

1
2

while True:
    pass

Where to go from here

Be sure to check out this excellent guide to CircuitPython Display Support Using displayio

Files

• EagleCAD files for Circuit Playground TFT Gizmo on GitHub
• Fritzing object in the Adafruit Fritzing Library
• 3D Model on Github

Schematic for Circuit Playground TFT Gizmo

Fab Print