# MicroPython Displays: Drawing Text

## Overview

Warning: 

https://www.youtube.com/watch?v=hyv8yxFeiiU

![](https://cdn-learn.adafruit.com/assets/assets/000/037/225/medium800/micropython_IMG_5599.jpg?1478897894)

So you have a nifty display like a bright Charlieplex LED or NeoPixel matrix powered by MicroPython, but what if you want to write text on it?  Most MicroPython display modules only give you basic pixel drawing commands so it's very cumbersome to draw text yourself pixel by pixel.  Luckily there's a handy new [MicroPython bitmap font module](https://github.com/adafruit/micropython-adafruit-bitmap-font) you can use to draw text on any pixel-based display!  This module shows some of the power of MicroPython--a single module can work with **any** pixel display because of MicroPython's dynamic language features.  In this guide you'll learn how to use a bitmap font rendering module with pixel-based displays like the [Charlieplex LED matrix](../../../../micropython-hardware-charlieplex-led-matrix) or [simple LED backpack matrix](../../../../micropython-hardware-led-backpacks-and-featherwings).

To follow this guide you'll want to be familiar with MicroPython by reading these guides:

- [MicroPython Basics: What is MicroPython?](../../../../micropython-basics-what-is-micropython)
- [MicroPython Basics: How to Load MicroPython on a Board](../../../../micropython-basics-how-to-load-micropython-on-a-board)
- [MicroPython Basics: Load Files & Run Code](../../../../micropython-basics-load-files-and-run-code)

See [all the MicroPython guides in the learning system](../../../../category/micropython) for more information.

In addition be sure to follow the guide for your pixel-based display first:

- [MicroPython Hardware: LED Backpacks & FeatherWings](../../../../micropython-hardware-led-backpacks-and-featherwings)
- [MicroPython Hardware: Charlieplex LED Matrix](../../../../micropython-hardware-charlieplex-led-matrix)
- [MicroPython Hardware: SSD1306 OLED Display](../../../../micropython-hardware-ssd1306-oled-display) (note the OLED display already has a font rendering function, but you can use this guide and its font rendering too!)
- [MicroPython Hardware: ILI9341 TFT & FeatherWing](../../../../micropython-hardware-ili9341-tft-and-featherwing)

# MicroPython Displays: Drawing Text

## Hardware

For this guide there's no special hardware you need to draw text on a display.  However you do need to have a pixel-based display of some sort (LED, TFT, NeoPixel--anything!) connected to your MicroPython board.  Check out the following guides for details on how to use a few pixel displays with MicroPython:

- [MicroPython Hardware: LED Backpacks & FeatherWings](../../../../micropython-hardware-led-backpacks-and-featherwings)
- [MicroPython Hardware: Charlieplex LED Matrix](../../../../micropython-hardware-charlieplex-led-matrix)
- [MicroPython Hardware: SSD1306 OLED Display](../../../../micropython-hardware-ssd1306-oled-display) (note the OLED display already has a font rendering function, but you can use this guide and its font rendering too!)
- [MicroPython Hardware: ILI9341 TFT & FeatherWing](../../../../micropython-hardware-ili9341-tft-and-featherwing)

Follow the appropriate guide to setup the hardware and make sure you can draw pixels on the display with MicroPython before continuing.

# MicroPython Displays: Drawing Text

## Software

# Install Module

To use the bitmap font module with your MicroPython board you'll need to install the [micropython-adafruit-bitmap-font MicroPython module](https://github.com/adafruit/micropython-adafruit-bitmap-font) on your board.

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](http://micropython.org/download#esp8266)** as earlier versions do not support using .mpy modules as shown in this guide.  

Download the latest **bitmapfont.mpy**  and **font5x8.bin** file from the [releases page](https://github.com/adafruit/micropython-adafruit-bitmap-font/releases) of the [micropython-adafruit-bitmap-font GitHub repository](https://github.com/adafruit/micropython-adafruit-bitmap-font/).

If your board supports USB mass storage, like the SAMD21 MicroPython port, then simply drag the .mpy and other files to the board's file system (eject the drive and reset the board to make sure it is picked up by MicroPython).

![](https://cdn-learn.adafruit.com/assets/assets/000/037/224/medium800/micropython_Screen_Shot_2016-11-10_at_11.26.36_PM.png?1478849229)

If your board doesn't support USB mass storage, like ESP8266 MicroPython boards, then [use a tool like ampy to copy the file to the board](../../../../micropython-basics-load-files-and-run-code/overview).

# Usage

The following section will show how to draw text on a matrix display like the Charlieplex FeatherWing/breakout or LED backpack.  

Note that currently the bitmap font rendering library only supports a simple **5 pixel wide by 8 pixel tall character** font.  This is great for large pixel displays like LED, NeoPixel, and Charlieplex matrices.

First [connect to the board's serial REPL](../../../../micropython-basics-how-to-load-micropython-on-a-board/serial-terminal)so you are at the MicroPython **\>\>\>** prompt.

# Display Initialization

Next you'll need to initialize your display so that you can draw pixels on it. [Consult the MicroPython display guides](../../../../micropython-displays-drawing-text/hardware) for details on initializing displays.  

For example the Charlieplex FeatherWing display initialization on ESP8266 MicroPython might look like:

```
import machine
import is31fl3731

i2c = machine.I2C(scl=machine.Pin(5), sda=machine.Pin(4))
matrix = is31fl3731.CharlieWing(i2c)
```

Once you have a matrix object which has a function to draw pixels you're ready to start drawing text.

# Bitmap Font Initialization

To use the bitmap font rendering module you'll need to import its module and create an instance of the **BitmapFont** class inside it.  For example to create a font renderer for the Charlieplex FeatherWing above you would run:

```
import bitmapfont
bf = bitmapfont.BitmapFont(15, 7, matrix.pixel)
bf.init()
```

The BitmapFont class initializer takes three parameters:

1. **The maximum width of the display in pixels** , in this case 15 for the Charlieplex FeatherWing.
2. **The maximum height of the display in pixels** , in this case 7 for the Charieplex FeatherWing.
3. **A pixel drawing function to call when the font class needs to write a pixel.**  For this example the Charlieplex matrix class **pixel** function is specified.  It's important to note that to use the bitmap font class you **must** have a function it can call to draw pixels!  This function can live anywhere, like as a global function or on a class instance.  The function needs to take at least a pixel x position and pixel y position parameter (in that order), and any number of other positional and keyword parameters after them (like color, intensity, etc.).

Next the **init()** function is called to setup the bitmap font drawing class.  Don't forget to call this function or else the font rendering won't work!  

Note too when you're finished using the bitmap font drawing class you shouild call the **deinit()** function to free the font resources it used.

As an alternative to calling **init** and **deinit** you can use the **BitmapFont** class as a [context manager](https://jeffknupp.com/blog/2016/03/07/python-with-context-managers/) that automatically initializes and deinitializes internal resources.  The syntax might look like:

```
with bitmapfont.BitmapFont(15, 7, matrix.pixel) as bf:
    # Bitmap font rendering code goes here!
    # No need to call init & deinit.
```

# Drawing Characters and Text

Once the bitmap font drawing class is initialized you're ready to write text to the display.  You can use the **text** function to draw a line of text anywhere on the display.  For the Charlieplex matrix you can call:

```
bf.text('Ada', 0, 0, 100)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/037/226/medium800/micropython_IMG_5591.jpg?1478898716)

The parameters to the text function are:

- **The string of text to display.**
- **The x position on the display to start drawing text.**
- **The y position on the display to start drawing text.**
- **All the remaining parameters (both positional and keyword) are passed through to the pixel drawing function.**  In this case the value 100 is passed to the Charlieplex matrix pixel function which will interpret it as the intensity of the LEDs.  For other displays you can pass in color or other data to use when printing the text.

If you need you can draw a single character with the **draw\_char** function, it's similar to text but only draws a single character.  For example with the Charlieplex matrix:

```
matrix.fill(0) # Clear the display
bf.draw_char('A', 0, 0, 100)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/037/227/medium800/micropython_IMG_5594.jpg?1478898735)

The parameters here are:

- **The character to print on the display.**
- **The x position on the display to start drawing the character.**
- **The y position on the display to start drawing the character.**
- **All the remaining parameters are passed through to the pixel drawing function** (see the text function description above).

Don't forget you can draw text in any color.  For example to draw dark text on a bright background you might try:

```
matrix.fill(100)
bf.text('Ada', 0, 0, 0)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/037/228/medium800/micropython_IMG_5595.jpg?1478898794)

Notice how the last parameter to the text function changed from a bright value like 100 to 0.  This means the display will turn off all the pixels where the text is drawn.

There's one more function on the bitmap font class that can be handy in some cases when animating or moving text, the **width** function to determine the pixel width of a string of text.  For example to find the number of pixels wide the string 'Hello' will occupy you can call:

```
width = bf.width('Hello')
print('Hello is {} pixels wide.'.format(width))
```

Just pass a string of text to **width** and it will return the number of pixels in the X dimension that the string will occupy on the display.

# Adapting To Other Displays

The power of the bitmap font class and MicroPython is that it's written in a way to work with any pixel-based display.  As long as you can call a pixel drawing function which takes at least a pixel X and Y position you can draw text on it with this module.  Just pass in the pixel drawing function to the **BitmapFont** class initializer as shown above.

For example to draw text on a 8x8 NeoPixel matrix you could first initialize the NeoPixels:

```
import neopixel
import machine
matrix = neopixel.NeoPixel(machine.Pin(6, machine.Pin.OUT), 64)
```

Then make a little pixel drawing helper function that takes an X, Y position and color as parameters and sets the appropriate pixel in the matrix:

```
def matrix_pixel(x, y, color):
    matrix[y*8 + x] = color
```

Notice how the pixel function has to convert a 2-dimensional X, Y location into a 1-dimensional location in the NeoPixel array.  It does this by multiplying the Y position, or the current row, by the stride, or pixel length of each row in the matrix, and adding the X position within that row.

Finally create the font class and pass it the pixel function created above:

```
import bitmapfont
bf = bitmapfont.BitmapFont(8, 8, matrix_pixel)
bf.init()
```

Then draw some text!  Remember the extra arguments to the text function will be passed along to the **matrix\_pixel** function so you can use it to set the text color.  To draw 'Ada' in pink you could run:

```
bf.text('Ada', 0, 0, (255, 0, 255))
```

That's all there is to using the bitmap font module to draw text on pixel displays!

Check out [the library examples](https://github.com/adafruit/micropython-adafruit-bitmap-font/blob/master/examples/) to see how to scroll a text message across the display.


## Featured Products

### Adafruit 15x7 CharliePlex LED Matrix Display FeatherWings

[Adafruit 15x7 CharliePlex LED Matrix Display FeatherWings](https://www.adafruit.com/product/2965)
You wont be able to look away from the mesmerizing patterns created by these  **Adafruit 15x7 CharliePlex LED Matrix Display FeatherWings**.  These 15x7 LED displays can be paired with with any of our [Feather...](https://www.adafruit.com/categories/830)

Out of Stock
[Buy Now](https://www.adafruit.com/product/2965)
[Related Guides to the Product](https://learn.adafruit.com/products/2965/guides)
### Adafruit 0.8" 8x16 Matrix FeatherWing Display Kit Various Colors

[Adafruit 0.8" 8x16 Matrix FeatherWing Display Kit Various Colors](https://www.adafruit.com/product/3155)
You will chirp with delight when you see how easy it is to make your very own 8x16 LED matrix display for any Feather. This kit combines two of our adorable miniature LED matrices with a FeatherWing driver board. At 0.8" square, these little 8x8 matrices have got everything a big LED...

Out of Stock
[Buy Now](https://www.adafruit.com/product/3155)
[Related Guides to the Product](https://learn.adafruit.com/products/3155/guides)
### Adafruit NeoPixel NeoMatrix 8x8 - 64 RGB LED Pixel Matrix

[Adafruit NeoPixel NeoMatrix 8x8 - 64 RGB LED Pixel Matrix](https://www.adafruit.com/product/1487)
Put on your sunglasses before wiring up this LED matrix - 64 eye-blistering RGB LEDs adorn the NeoMatrix for a blast of configurable color. Arranged in an 8x8 matrix, each pixel is individually addressable. Only one microcontroller pin is required to control all the LEDs, and you get 24 bit...

In Stock
[Buy Now](https://www.adafruit.com/product/1487)
[Related Guides to the Product](https://learn.adafruit.com/products/1487/guides)
### Flexible 8x8 NeoPixel RGB LED Matrix

[Flexible 8x8 NeoPixel RGB LED Matrix](https://www.adafruit.com/product/2612)
For advanced NeoPixel fans, we how have a bendable,  **Flexible 8x8 NeoPixel LED Matrix!** Control all 64 ultra-bright LEDs using a single microcontroller pin, set each LED as you wish to scroll messages or draw little images. This matrix has a thick flexible PCB backing that...

No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2612)
[Related Guides to the Product](https://learn.adafruit.com/products/2612/guides)
### Adafruit NeoPixel Shield for Arduino - 40 RGB LED Pixel Matrix

[Adafruit NeoPixel Shield for Arduino - 40 RGB LED Pixel Matrix](https://www.adafruit.com/product/1430)
Put on your sunglasses before putting this shield onto your 'duino - 40 eye-blistering RGB LEDs adorn the NeoPixel shield for a blast of configurable color. Arranged in a 5x8 matrix, each pixel is individually addressable. Only one pin (Digital #6) is required to control all the LEDs. You...

In Stock
[Buy Now](https://www.adafruit.com/product/1430)
[Related Guides to the Product](https://learn.adafruit.com/products/1430/guides)
### Adafruit Feather M0 Basic Proto - ATSAMD21 Cortex M0

[Adafruit Feather M0 Basic Proto - ATSAMD21 Cortex M0](https://www.adafruit.com/product/2772)
Feather is the new development board from Adafruit, and like its namesake it is thin, light, and lets you fly! We designed Feather to be a new standard for portable microcontroller cores.

This is the  **Feather M0 Basic Proto** , it has a bunch of prototyping space...

In Stock
[Buy Now](https://www.adafruit.com/product/2772)
[Related Guides to the Product](https://learn.adafruit.com/products/2772/guides)
### Adafruit Feather M0 Adalogger

[Adafruit Feather M0 Adalogger](https://www.adafruit.com/product/2796)
Feather is the new development board from Adafruit, and like its namesake it is thin, light, and lets you fly! We designed Feather to be a new standard for portable microcontroller cores.

This is the  **Adafruit Feather M0 Adalogger**  - our take on an...

In Stock
[Buy Now](https://www.adafruit.com/product/2796)
[Related Guides to the Product](https://learn.adafruit.com/products/2796/guides)
### Adafruit Feather M0 Bluefruit LE

[Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/product/2995)
Feather is the new development board from Adafruit, and like its namesake, it is thin, light, and lets you fly! We designed Feather to be a new standard for portable microcontroller cores.

This is the  **Adafruit Feather M0 Bluefruit LE**  - our take on an...

In Stock
[Buy Now](https://www.adafruit.com/product/2995)
[Related Guides to the Product](https://learn.adafruit.com/products/2995/guides)

## Related Guides

- [Adafruit Feather M0 Adalogger](https://learn.adafruit.com/adafruit-feather-m0-adalogger.md)
- [Adafruit Feather M0 Bluefruit LE](https://learn.adafruit.com/adafruit-feather-m0-bluefruit-le.md)
- [Adafruit NeoPXL8 FeatherWing and Library](https://learn.adafruit.com/adafruit-neopxl8-featherwing-and-library.md)
- [Dauntless Dotstar Gauntlets](https://learn.adafruit.com/dotstar-dauntless-gauntlets.md)
- [Using DS18B20 Temperature Sensor with CircuitPython](https://learn.adafruit.com/using-ds18b20-temperature-sensor-with-circuitpython.md)
- [CircuitPython Hardware: Charlieplex LED Matrix](https://learn.adafruit.com/micropython-hardware-charlieplex-led-matrix.md)
- [What is Web MIDI & BLE MIDI?](https://learn.adafruit.com/web-ble-midi.md)
- [Adafruit NeoPixel Überguide](https://learn.adafruit.com/adafruit-neopixel-uberguide.md)
- [Talking Musical NeoPixel Clock with Infrared, BLE and Touch Controls](https://learn.adafruit.com/talking-musical-neo-pixel-clock-with-infrared-ble-and-touch-controls.md)
- [CircuitPython Hardware: LED Backpacks & FeatherWings](https://learn.adafruit.com/micropython-hardware-led-backpacks-and-featherwings.md)
- [Feather + Raspberry Pi Weather Monitoring Network with LoRa or LoRaWAN](https://learn.adafruit.com/multi-device-lora-temperature-network.md)
- [Debugging the SAMD21 with GDB](https://learn.adafruit.com/debugging-the-samd21-with-gdb.md)
- [LED Acrylic Sign](https://learn.adafruit.com/led-acrylic-sign.md)
- [Robotic Xylophone with Adafruit Grand Central](https://learn.adafruit.com/robotic-xylophone-with-circuit-python.md)
- [Custom HID Devices in CircuitPython](https://learn.adafruit.com/custom-hid-devices-in-circuitpython.md)
- [Adafruit microSD Card BFF](https://learn.adafruit.com/adafruit-microsd-card-bff.md)
- [Quick-Start the Pico W WiFi with CircuitPython](https://learn.adafruit.com/pico-w-wifi-with-circuitpython.md)