# Custom Fonts for CircuitPython Displays ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/071/369/medium800/circuitpython_hero-desk.jpg?1550448667) ## More Fonts Are you looking to display new fonts on your PyPortal? You can use just about any font on your computer or downloaded from the internet. This guide will walk you through generating bitmap fonts using the [FontForge open-source](https://fontforge.github.io) project. ## Why Bitmaps? PyPortal uses the [CircuitPython Bitmap Font Library](https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/) to render "live" text on the display. A bitmap font stores each character as an array of pixels. Bitmap fonts are simply groups of images. For each variant of the font, there is a complete set of images, with each set containing an image for each character. Computers, on the other hand, use variable size 'TrueType' or 'Postscript' fonts, where there's a mathematical algorithm that defines each character, so it can be drawn at _any_ size. ## Font Forging This is where FontForge comes into play. FontForge is an open-source font editor for Windows, Mac OS and GNU+Linux. It features tools for converting existing fonts into different font formats. ## Getting Started with FontForge Head on over to the [fontforge page](https://fontforge.github.io/en-US/) and download the app for your platform. You can choose to donate, subscribe via email or simply click the " **Subscribe/Confirm and Download**" button (no need to enter an email).  Follow along with the detailed installation guide to get setup with FontForge. ![circuitpython_hero-fontforge.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/359/medium640/circuitpython_hero-fontforge.jpg?1550439781) [Download FontForge](https://fontforge.github.io/en-US/downloads/) ## Where Do I Get Fonts? Here's a list of some neat places to obtain some fresh fonts. - [The Inter typeface family](https://rsms.me/inter/) - [Font Squirrel](https://www.fontsquirrel.com/) - [Google Fonts](https://fonts.google.com/) - [Adobe Fonts](https://fonts.adobe.com/) - [DaFont](https://www.dafont.com/) - [Font Library](https://fontlibrary.org/) # Custom Fonts for CircuitPython Displays ## Use FontForge ![](https://cdn-learn.adafruit.com/assets/assets/000/071/367/medium800/circuitpython_hero-fontforge.jpg?1550448607) ## Demo Walkthrough In this example, we're going to convert a **.TTF** (TrueType Format) into a **.BDF** (Bitmap Distribution Format). I'm using an open licensed font downloaded from Google Font, [Source Serif Pro](https://fonts.google.com/specimen/Source+Serif+Pro).  ## Open Font Use the **file** menu and choose **Open Font** from the list. Navigate to a directory where your desired font resides. Select the font and open it. ![circuitpython_open-font.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/361/medium640/circuitpython_open-font.jpg?1550446525) ## Set Font Size From the **element** menu, select **Bitmap Strikes Available**. In this dialog, you will need to specific how large you want your font to be. The font size is fixed with Bitmap fonts, so if you want to use different sizes, you'll need to make separate files. ![circuitpython_bitmap-strike-available.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/362/medium640/circuitpython_bitmap-strike-available.jpg?1550447371) ## Generate Bits From the **element** menu, select **Regenerate Bitmap Glyphs**. Similar to the previous dialog, enter the font size of your liking. You can make it smaller here. Be aware, values too small will not generate BDF's.  ![circuitpython_regenerate-bitmap.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/363/medium640/circuitpython_regenerate-bitmap.jpg?1550447555) ## Export Converted Font From the **file** menu, select **Generate Fonts**. In the dialog, select **No Outline Font** and **BDF** from the dropdown options. Use the navigation UI to save the file in your directory of choice. Click the **generate** button to save the file.  ![circuitpython_generate-font.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/364/medium640/circuitpython_generate-font.jpg?1550447833) ## BDF Resolution This dialog menu will pop up after clicking generate. You can choose one of the options from the list. If you'd like a different font size, you can enter that in the **Other** labeled input box. Click **OK** to save it! ![circuitpython_bdf-resolution.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/365/medium640/circuitpython_bdf-resolution.jpg?1550447953) ## Optimize File Size If you take a look at the file size of the .bdf, it's roughly around 900K – That can be a bit larger than needed, especially if you plan to store a lot of image and sound assets. In cases where you need to save on every byte, you can optimize the file size of your fonts by selecting only the characters you want to use. If you scroll through the full list of glyphs, you'll see there's extra special characters – A whole bunch of them! If you don't need them in your project, just select "space" (the glyph just before "!") plus the basic set of upper/lower and alphanumeric characters. You can click + hold and drag to make selections easier. With them selected, go through these steps: 1. Select the glyphs you want to keep 2. Use **Edit→Select→Invert Selection** to change the selection to the _unwanted_ glyphs. 3. Use **Encoding→Detach & Remove Glyphs...** to remove the unwanted glyphs. (You'll have to re-load your original font file to undo this step) 4. Use **Element→Regenerate Bitmap** to reprocess the glyphs. 5. Use **File→Generate Font** to save the reduced version of the file ![circuitpython_selected-glyphs.jpg](https://cdn-learn.adafruit.com/assets/assets/000/071/366/medium640/circuitpython_selected-glyphs.jpg?1550448080) Primary: Make sure your final font contains the letter capital **M** , which is used to estimate the height of letters in the font. Otherwise, the font will be incompatible with **adafruit\_display\_text** and give an error like `AttributeError: 'NoneType' object has no attribute 'height'` ## Optimize File Size (Manually) If you prefer, you can also use a text editor to remove glyphs from a **.bdf** file. BDF files are just text! Open a BDF file and search for “ **asciitilde** ” — this is usually the highest plain-ASCII-value glyph we want to preserve. A few lines down there will be an “ **ENDCHAR** ” line. Delete everything after the **ENDCHAR** line, then add a line containing  **ENDFONT**. That’s it! Save the file, which is usually just a small fraction of the original size. You won’t get any accented characters or special punctuation this way, so it’s not always the right thing for every situation. For the majority of plain-text programs though, this can really help stretch your CIRCUITPY drive space! ![circuitpython_fontforge-edit.png](https://cdn-learn.adafruit.com/assets/assets/000/097/160/medium640/circuitpython_fontforge-edit.png?1605820922) ## Font Colors The color of the fonts can be setup in your code. The CircuitPython library uses HEX color codes. This is similar to web color pickers but formatted slightly different. Most HEX color pickers use a hashtag in the front of the value, like, **#000000**. In CircuitPython, instead of a hashtag, **0x**  is used. Here's a few examples. - Black =  0x000000 - White = 0xFFFFFF - Purple = 0x8f42f4 # Custom Fonts for CircuitPython Displays ## Use otf2bdf For fast conversion, you can also use a command line tool called otf2bdf. The homepage is here: [http://sofia.nmsu.edu/~mleisher/Software/otf2bdf/](http://sofia.nmsu.edu/~mleisher/Software/otf2bdf/) Linux users can install it with something like **apt-get install otf2bdf**. Here is a pre-compiled version of **otf2bdf** but for Mac Users [mac_otf2bdf.zip](https://cdn-learn.adafruit.com/assets/assets/000/072/205/original/mac_otf2bdf.zip?1551657856) Use it in a terminal by calling it like: `otf2bdf FontFile.ttf -p pointsize -o FontFile.bdf` For example here is how to convert a font to a 12 point BDF file: `otf2bdf ChicagoFLF.ttf -p 12 -o Chicago-12.bdf` # Custom Fonts for CircuitPython Displays ## Convert to PCF CircuitPython supports two font formats: the textual **.bdf** format and the binary **.pcf** format. By taking the extra step of converting your font to **.pcf** you make fonts load faster and also typically save some storage space on the board **CIRCUITPY** flash drive. The converter software is hosted on github.io. Thanks to technology called [emscripten](https://emscripten.org/), it runs entirely in your web browser—the font file is not uploaded to a server, which also makes it really quick. web-bdftopcf is derived from the classic font converter of the same name, a program for Unix/Linux systems. If you're interested, you can [browse the C source on github](https://github.com/adafruit/web-bdftopcf). Head to [https://adafruit.github.io/web-bdftopcf/](https://adafruit.github.io/web-bdftopcf/) and click the "Browse" button. ![circuitpython_ksnip_20210105-081830.png](https://cdn-learn.adafruit.com/assets/assets/000/098/453/medium640/circuitpython_ksnip_20210105-081830.png?1609856326) Select a **.bdf** file from your computer and click Open. ![circuitpython_ksnip_20210105-084041.png](https://cdn-learn.adafruit.com/assets/assets/000/098/457/medium640/circuitpython_ksnip_20210105-084041.png?1609857680) After a moment, the font will be prepared in **.pcf** format and depending on your browser settings it may be automatically downloaded or you may have to confirm that you want to download the file. ![circuitpython_ksnip_20210105-084143.png](https://cdn-learn.adafruit.com/assets/assets/000/098/458/medium640/circuitpython_ksnip_20210105-084143.png?1609857718) In this particular case, the **.pcf** version of the font is only half the size of the **.bdf** font, which leaves more space on the **CIRCUITPY** drive for other assets like sound files and bitmaps. ![circuitpython_ksnip_20210105-083937.png](https://cdn-learn.adafruit.com/assets/assets/000/098/459/medium640/circuitpython_ksnip_20210105-083937.png?1609857736) # Custom Fonts for CircuitPython Displays ## Bitmap_Font Library This library is used for decoding `.pcf` or `.bdf` font files into Bitmap objects suitable for showing on a screen. ## Basic Usage If you just want to get your font loaded and shown on a standard display, you can do so using the [Adafruit\_CircuitPython\_Bitmap\_Font](https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font "Bitmap\_Font Library") library with the [Adafruit\_CircuitPython\_Display\_Text](https://github.com/adafruit/Adafruit_CircuitPython_Display_Text "Display\_Text Library") library. Paste a copy of your font **.pcf** or **.bdf** file on your **CIRCUITPY** drive. Inside of a directory named **fonts** is a good place to put it. But there is no strict requirement, the file can be anywhere on the drive. Then the font can be loaded like this:  `font = bitmap_font.load_font("fonts/my_font.bdf")` and then pass the font variable into the constructor for `BitmapLabel` or `Label`. `my_label = Label(font, text="Hello")` See the full example below: ![circuitpython_bitmap_font_example.png](https://cdn-learn.adafruit.com/assets/assets/000/101/191/medium640/circuitpython_bitmap_font_example.png?1617583922) https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/blob/main/examples/bitmap_font_label_simpletest.py # Custom Fonts for CircuitPython Displays ## Example Scripts ## ASCII Art in the Terminal One of the simpletest examples can be used to generate ASCII art output of the specified font file. https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/blob/main/examples/bitmap_font_simpletest.py To try it out on a PC or Raspberry Pi, run this command inside of the examples directory: `python bitmap_font_simpletest.py` To use it on a CircuitPython device save a copy of the script as `code.py` on your `CIRCUITPY` drive It will print out an ASCII art representation of the string in the variable named `message` your input word in the given font. You can open the script and modify the `message` or the font used if you like. ![](https://cdn-learn.adafruit.com/assets/assets/000/101/626/medium800/circuitpython_new_terminal_simpletest.png?1618831927) ## Awesome Icons The most typical way to use the library is for loading fonts to show letters, numbers, and other characters used to make words and strings. But font files can contain other types of glyphs as well.  The Fork Awesome project is an open source collection of icons normally used in web interfaces. [They've been converted](https://emergent.unpythonic.net/01606790241) to `.pcf` format for use with CircuitPython. The example script below is included in the Bitmap\_Font library examples directory. Explore the [forkawesome\_icons.py](https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/blob/main/examples/bitmap_font_forkawesome_icons.py) file to learn the names of the available icons. ![circuitpython_fork_awesome_icons.png](https://cdn-learn.adafruit.com/assets/assets/000/101/190/medium640/circuitpython_fork_awesome_icons.png?1617583594) https://github.com/adafruit/Adafruit_CircuitPython_Bitmap_Font/blob/main/examples/bitmap_font_label_forkawesome.py ## Featured Products ### Adafruit PyPortal - CircuitPython Powered Internet Display [Adafruit PyPortal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4116) **PyPortal** , our easy-to-use IoT device that allows you to create all the things for the “Internet of Things” in minutes. Make custom touch screen interface GUIs, all open-source, and Python-powered using tinyJSON / APIs to get news, stock, weather, cat photos,... Out of Stock [Buy Now](https://www.adafruit.com/product/4116) [Related Guides to the Product](https://learn.adafruit.com/products/4116/guides) ## Related Guides - [Adafruit PyPortal - IoT for CircuitPython](https://learn.adafruit.com/adafruit-pyportal.md) - [PyPortal Reddit Stats Trophy](https://learn.adafruit.com/pyportal-reddit-stats-trophy.md) - [Getting Started with Braille Output for CircuitPython REPL](https://learn.adafruit.com/getting-started-braille-output-circuitpython-repl.md) - [PyPortal Guitar Tuner](https://learn.adafruit.com/pyportal-guitar-tuner.md) - [CircuitPython Twitter Viewer Using the Twitter API](https://learn.adafruit.com/twitter-api-use.md) - [League of Legends Level Trophy for PyPortal](https://learn.adafruit.com/league-of-legends-level-trophy-for-pyportal.md) - [PyPortal MQTT Sensor Node/Control Pad for Home Assistant](https://learn.adafruit.com/pyportal-mqtt-sensor-node-control-pad-home-assistant.md) - [PyPortal Trivia Time with the Open Trivia Database](https://learn.adafruit.com/pyportal-trivia-time-open-trivia-database.md) - [PyPortal Event Count-Up Clock](https://learn.adafruit.com/pyportal-event-count-up-clock.md) - [Welcome to CircuitPython!](https://learn.adafruit.com/welcome-to-circuitpython.md) - [Portable PyPortal](https://learn.adafruit.com/portable-pyportal.md) - [PyPortal NASA Image of the Day Viewer](https://learn.adafruit.com/pyportal-nasa-image-of-the-day-viewer.md) - [PyPortal IoT Data Logger with Analog Devices ADT7410, Adafruit IO and CircuitPython](https://learn.adafruit.com/iot-pyportal-data-logger-adafruitio-circuitpython.md) - [Creating Slideshows in CircuitPython](https://learn.adafruit.com/creating-slideshows-in-circuitpython.md) - [Program CircuitPython USB Devices with iPhone & iPad](https://learn.adafruit.com/use-circuitpython-devices-with-iphone-ipad.md)