Many graphics libraries (like this one) will provide functions for drawing various graphical primitives like lines, circles, squares, etc. But we will only need one very simple primitive for this project - the lowly pixel. There is a good discussion about the pixel and associate coordinate system in the GFX guide. The excellent figure below is borrowed from that guide. Think of this as looking at the front of your display.

The coordinate system starts in the upper left hand corner of the display. To specify a pixel location, you provide the x value and the y value in the form (x, y). This is another one of those computer things where counting starts at 0. Therefore, the very first pixel in the upper left hand corner is (0, 0). The x value is how far to the right, and the y value is how far down. In the figure above you can see two other pixels for x=6, y=13 => (6, 13) and for x=18, y=6 => (18, 6).

The other thing to note is that every display will have an associate width and height. This is basically the total number of pixels in each direction. For the example above, the width would be 24 and the height would be 16. Note that the last pixel coordinates are 23 in x and 15 in y. That's due to the counting from 0 thing again. So to draw the very last pixel - all the right, all the way down, the coordinates would be (width -1, height -1).

One Little Pixel

Let's wire up a display and play around with drawing pixels.

The diagram below shows how to wire up a 1.3" OLED to an ItsyBitsy M4 Express. The connection uses I2C, which is covered in the guide for the OLED, so be sure to read that first.

OK, here's the code. You can either save this as code.py to have it run automatically, or you can save it to another file name and run it manually.

# Import the needed libraries
import board
import busio
from digitalio import DigitalInOut
import adafruit_ssd1306

# Create the I2C bus
i2c = busio.I2C(board.SCL, board.SDA)

# Define display dimensions and I2C address
WIDTH = 128
HEIGHT = 64
ADDR = 0x3d

# Create the digital out used for display reset
rst = DigitalInOut(board.D7)

# Create the display
display = adafruit_ssd1306.SSD1306_I2C(WIDTH, HEIGHT, i2c, addr=ADDR, reset=rst)
display.fill(0)
display.show()

# Define pixel location
x = 42
y = 23
# Draw the pixel
display.pixel(x, y, 1)
display.show()

# Import the needed libraries
import board
import busio
from digitalio import DigitalInOut
import adafruit_ssd1306

# Create the I2C bus
i2c = busio.I2C(board.SCL, board.SDA)

# Define display dimensions and I2C address
WIDTH = 128
HEIGHT = 64
ADDR = 0x3d

# Create the digital out used for display reset
rst = DigitalInOut(board.D7)

# Create the display
display = adafruit_ssd1306.SSD1306_I2C(WIDTH, HEIGHT, i2c, addr=ADDR, reset=rst)
display.fill(0)
display.show()

# Define pixel location
x = 42
y = 23
# Draw the pixel
display.pixel(x, y, 1)
display.show()

Once you have that code loaded and it runs....voila! There's the pixel! Do you see it? It's super tiny on this little display, but there it is. It's so cute. I think I'll call it Dotty. Hi, Dotty!

And Dotty showed up right where we said to, 42 pixels to the right and 23 pixels down.

If you want to have Dotty show up in another location, edit these two lines of code:

x = 42
y = 23

x = 42
y = 23

and run the program again.

It's Full of Stars

Let's give Dotty the lowly pixels some friends. Lots of friends. To do that, we will draw more pixels. You can call the display.pixel() function as many times as you want to draw more than one pixel. Let's have some fun with that. Here's a program that draws 500 pixels in random locations. It does this over and over again, pausing for half a second each time.

# Import the needed libraries
import time
import random
import board
import busio
from digitalio import DigitalInOut
import adafruit_ssd1306

# Create the I2C bus
i2c = busio.I2C(board.SCL, board.SDA)

# Define display dimensions and I2C address
WIDTH = 128
HEIGHT = 64
ADDR = 0x3d

# Create the digital out used for display reset
rst = DigitalInOut(board.D7)

# Create the display
display = adafruit_ssd1306.SSD1306_I2C(WIDTH, HEIGHT, i2c, addr=ADDR, reset=rst)
display.fill(0)
display.show()

# Loop forever drawing random pixels
while True:
    for _ in range(500):
        x = random.randrange(WIDTH)
        y = random.randrange(HEIGHT)
        display.pixel(x, y, 1)
    display.show()
    time.sleep(0.5)
    display.fill(0)

# Import the needed libraries
import time
import random
import board
import busio
from digitalio import DigitalInOut
import adafruit_ssd1306

# Create the I2C bus
i2c = busio.I2C(board.SCL, board.SDA)

# Define display dimensions and I2C address
WIDTH = 128
HEIGHT = 64
ADDR = 0x3d

# Create the digital out used for display reset
rst = DigitalInOut(board.D7)

# Create the display
display = adafruit_ssd1306.SSD1306_I2C(WIDTH, HEIGHT, i2c, addr=ADDR, reset=rst)
display.fill(0)
display.show()

# Loop forever drawing random pixels
while True:
    for _ in range(500):
        x = random.randrange(WIDTH)
        y = random.randrange(HEIGHT)
        display.pixel(x, y, 1)
    display.show()
    time.sleep(0.5)
    display.fill(0)

Approximately twice a second the display will update with a random pattern of stars. Or is it snow? And where'd Dotty go? Lost in the snow storm I guess. Bye, Dotty!

And that's all there is to draw one or more pixels. Don't forget to call display.show() to actually see the results though.