Arduino library · Displays

Adafruit GC9A01A: the 1.28 inch round TFT on Arduino

Yes. You can use the Adafruit GC9A01A library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Round display, GC9A01). The example below, "Round watch face", runs on the Arduino Uno R3.

Built in on Mokxi: #include <Adafruit_GC9A01A.h> and it builds, with nothing to install. Free, and no account needed.

What Adafruit GC9A01A does

The GC9A01 is the controller behind the round 1.28 inch 240x240 screens used in DIY smartwatches, gauges and robot eyes. Adafruit_GC9A01A drives it over SPI and hands the drawing to Adafruit_GFX, so circles, lines, text and bitmaps use the same calls as on any Adafruit screen.

The thing to keep in mind is that the memory is square and the glass is not. Pixels drawn into the four corners are stored and never seen, so lay out a design around the center at (120, 120) with a radius of 120. Rotation needs no offsets on this chip, which makes setRotation() simple compared with the ST7789.

begin() sends the long vendor start-up sequence these panels need, including the inversion command for the IPS glass. The runnable example is a watch face on an Uno with a DS3231 clock: it erases each hand by drawing it again in black and draws the new one, because repainting 240x240 pixels every second is too slow over an Uno’s SPI.

Library Manager nameAdafruit GC9A01A
AuthorAdafruit
Include#include <Adafruit_GC9A01A.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesRound display, GC9A01

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <Adafruit_GC9A01A.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Adafruit GC9A01A" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit GC9A01A to lib_deps in PlatformIO. Mokxi follows the calls of release 1.2.0, so a sketch written here builds there too.

The calls you will use

In the order a sketch meets them.

Adafruit_GC9A01A tft(10, 9)

Makes the display on the hardware SPI pins with CS on 10 and DC on 9. A third argument names the reset pin; leave it out when RES is not wired.

tft.begin()

Resets the panel if a reset pin was given and sends the start-up sequence. An optional argument sets the SPI speed.

tft.fillScreen(GC9A01A_BLACK)

Paints every pixel, the visible circle and the hidden corners. Do it once in setup(), not on every frame.

tft.drawLine(120, 120, x, y, GC9A01A_WHITE)

A line from the center outward, which is all a clock hand is. Work the end point out from the angle with a sine table or sin() and cos().

tft.fillCircle(120, 120, 60, GC9A01A_RED)

A filled disc around the center. Concentric circles make a quick gauge face or an eye.

tft.setRotation(1)

Turns the drawing by quarter turns. On round glass it mostly matters for where text and the 12 o’clock mark end up.

Example: Round watch face

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
// Round watch face: an analog clock on a 1.28 inch GC9A01 round display,
// with the time from a DS3231, the way a desk watch or a smartwatch face is
// built.
//
//   GC9A01   SCL -> 13   SDA -> 11   CS -> 10   DC -> 9   VCC -> 5 V   GND -> GND   (RES left free)
//   DS3231   SDA -> A4   SCL -> A5   VCC -> 5 V   GND -> GND
//
// The display is a 240x240 square of memory with round glass on it, so the
// face is centered at (120, 120) with a radius of 120. Each second the sketch
// rubs out the hands where they were, by drawing them again in black, and
// draws them where they are now: redrawing the whole face would take this
// board a long time over its SPI bus.
//
// The hands are straight lines from the center, and their ends come from a
// table of sines in steps of 6 degrees (one minute of the dial), because this
// board has no floating point. The time is the DS3231's own registers, read
// over Wire: three bytes of BCD from register 0.

#include <SPI.h>
#include <Wire.h>
#include "Adafruit_GFX.h"
#include "Adafruit_GC9A01A.h"

Adafruit_GC9A01A tft(10, 9);  // CS, DC; no reset pin
const uint8_t DS3231 = 0x68;

uint8_t fromBcd(uint8_t b) { return (b >> 4) * 10 + (b & 0x0f); }

// Seconds, minutes and hours: the DS3231's first three registers, in BCD.
// False when the clock does not answer.
uint8_t now[3];
bool readClock() {
  Wire.beginTransmission(DS3231);
  Wire.write(0x00);
  Wire.endTransmission();
  if (Wire.requestFrom(DS3231, 3) != 3) return false;
  for (uint8_t i = 0; i < 3; i++) now[i] = fromBcd(Wire.read() & 0x7f);
  return true;
}

const int16_t CX = 120;
const int16_t CY = 120;
const uint16_t FACE = GC9A01A_BLACK;

// sin(6 degrees x i) x 127 for i = 0 to 15, a quarter of the dial.
const int8_t SINE[16] = {0, 13, 26, 39, 52, 64, 75, 85, 94, 103, 110, 116, 121, 124, 126, 127};

int16_t sine60(uint8_t i) {
  i %= 60;
  if (i <= 15) return SINE[i];
  if (i <= 30) return SINE[30 - i];
  if (i <= 45) return -SINE[i - 30];
  return -SINE[60 - i];
}

// The point `radius` pixels from the center at dial position `i` (0 is 12 o'clock).
int16_t dialX(uint8_t i, int16_t radius) { return CX + radius * sine60(i) / 127; }
int16_t dialY(uint8_t i, int16_t radius) { return CY - radius * sine60(i + 15) / 127; }

void hand(uint8_t i, int16_t radius, uint16_t color) {
  tft.drawLine(CX, CY, dialX(i, radius), dialY(i, radius), color);
}

void drawFace() {
  tft.fillScreen(FACE);
  // A tick a minute, longer every five.
  for (uint8_t i = 0; i < 60; i++) {
    int16_t inner = (i % 5 == 0) ? 100 : 108;
    tft.drawLine(dialX(i, inner), dialY(i, inner), dialX(i, 112), dialY(i, 112), GC9A01A_WHITE);
  }
}

uint8_t lastSecond = 255;
uint8_t hourPos, minutePos, secondPos;

void setup() {
  tft.begin();
  drawFace();
  Wire.begin();
}

void loop() {
  if (!readClock() || now[0] == lastSecond) {
    delay(20);
    return;
  }
  bool first = lastSecond == 255;
  lastSecond = now[0];

  // Rub out the old hands, then draw the new ones, longest last.
  if (!first) {
    hand(secondPos, 95, FACE);
    hand(minutePos, 85, FACE);
    hand(hourPos, 55, FACE);
  }
  hourPos = (now[2] % 12) * 5 + now[1] / 12;
  minutePos = now[1];
  secondPos = now[0];

  hand(hourPos, 55, GC9A01A_WHITE);
  hand(minutePos, 85, GC9A01A_WHITE);
  hand(secondPos, 95, GC9A01A_RED);
}

Open it in the editor, wired and ready to run · Round watch face: the project page

Common errors and how to fix them

The screen stays black, or shows only a flash of noise

Check that DC and CS match the constructor and that the module’s SDA and SCL go to MOSI and SCK (11 and 13 on an Uno). Despite the labels these pins are SPI, not I2C.

Text near the edge is cut off

The corners of the 240x240 memory are outside the round glass. Keep anything you need to read inside a circle of radius about 110 from (120, 120).

The display flickers badly when the clock updates

The sketch clears the whole screen every second. Erase only what moved, by drawing the old hand or digits in the background color, then draw the new ones.

Questions and answers

Is the GC9A01 an I2C display?

No. The pins are often labeled SDA and SCL, but they carry SPI data and clock, and the module also needs DC and CS.

Try Adafruit GC9A01A without installing anything

Open the example, change the sketch, and keep your version in a free account.