Overview

• General Considerations
• Font Setup
• Font Conversion

---

General Considerations

The library does not come with a built-in font to keep the code size small. Currently, the library only supports the Adafruit-GFX-Library font format. Their repository provides a handful of pre-made fonts as well as tools to create custom ones.

If you only want to display a word or two, instead of defining an entire font, it might be a better idea to display them as images or as custom characters to save space.

The library also provides the ability to magnify fonts, enabling the use of a single font at different scales without the need to include multiple versions of it. The magnification value can be set with the ssd1306_set_font_scale() function:

/* Magnify the font by 2 (default is 1) */
ssd1306_set_font_scale(&display, 2);

Some library functions require a font to be defined; if used without a font, the characters will be drawn as empty rectangles. These functions are:

• ssd1306_draw_char()
• ssd1306_draw_str()
• ssd1306_draw_int32()
• ssd1306_draw_float()
• ssd1306_draw_printf()

These functions print at the current cursor location. The cursor typically represents the bottom-left corner of the next character to be drawn. Note that this isn't exact, as the characters can define offsets in any direction. The cursor can be set with the ssd1306_set_cursor() function:

/* Set the cursor to (0, 15) */
ssd1306_set_cursor(&display, 0, 15);

Characters that aren't supported by the font will also drawn as empty rectangles.

The only supported non-printable characters are \r and \n.

---

Font Setup

• Navigate to the Fonts directory within the Adafruit-GFX-Library repository.
• Copy the font of your choosing into your project (FreeMonoBold9pt7b.h for example).
• Convert the font by following the conversion steps below.
• Include the font header in your source file:

#include "FreeMonoBold9pt7b.h"

• Call the ssd1306_set_font() function with the address of the ssd1306_font struct:

ssd1306_set_font(&display, &FreeMonoBold9pt7b);

---

Font Conversion

• Consider FreeMonoBold9pt7b.h as an example. If you collapse the definitions, the file looks like:

#pragma once
#include <Adafruit_GFX.h>

const uint8_t FreeMonoBold9pt7bBitmaps[] PROGMEM = {...
const GFXglyph FreeMonoBold9pt7bGlyphs[] PROGMEM = {...
const GFXfont FreeMonoBold9pt7b PROGMEM = {...

• If your compiler doesn't support #pragma once, replace it with a header guard:

#ifndef FREEMONOBOLD9PT7B_H
#define FREEMONOBOLD9PT7B_H

#include <Adafruit_GFX.h>

const uint8_t FreeMonoBold9pt7bBitmaps[] PROGMEM = {...
const GFXglyph FreeMonoBold9pt7bGlyphs[] PROGMEM = {...
const GFXfont FreeMonoBold9pt7b PROGMEM = {...

#endif

• Replace the <Adafruit_GFX.h> with the library header file path:

#ifndef FREEMONOBOLD9PT7B_H
#define FREEMONOBOLD9PT7B_H

#include "ssd1306.h"

const uint8_t FreeMonoBold9pt7bBitmaps[] PROGMEM = {...
const GFXglyph FreeMonoBold9pt7bGlyphs[] PROGMEM = {...
const GFXfont FreeMonoBold9pt7b PROGMEM = {...

#endif

• Replace the structure names with the library structures and remove the PROGMEM macro. In the end, the file should look like:

• ssd1306_glyph struct for the glyph array.
• ssd1306_font struct for the font.

#ifndef FREEMONOBOLD9PT7B_H
#define FREEMONOBOLD9PT7B_H

#include "ssd1306.h"

const uint8_t FreeMonoBold9pt7bBitmaps[] = {...
const struct ssd1306_glyph FreeMonoBold9pt7bGlyphs[] = {...
const struct ssd1306_font FreeMonoBold9pt7b = {...

#endif