Skip to content

image

Matrix Fonts

This documentation is the same on the Github Repository, which may be easier to explore.

About These Fonts

These fonts are designed with LED Matrix Clocks in mind, especially a unit that uses EspHoMaTriXv2 or EspHome-Led-PixelClock. They are BDF and TTF Fonts, so they can be directly implemented with ESPHome (and perhaps Arduino).

Because these are bitmap fonts, the size of these fonts is pixel-fixed. They are not resizable. This is a good thing.

These TTF files are not usable by Windows, since they include only bitmaps.

Most characters will be 3 pixels wide, but certain characters like G and M and & are wider. Punctuation characters are generally 1 or 2 pixels wide. All characters have 1 empty column on the right side, except the space which is exactly 2 pixels, certain unicode hyphens, and perhaps some Ognok-accented Latin characters.

I will continue adding characters to fonts as I have time. If you wish your language to be represented or if you need some special characters added, open an issue and I'll see what I can do.

Previews

If you would like to see all available characters, take a look at my BDF Font Renderer.

This tool was used to generate the previews with:

ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz
!"#$%&'()*+,-./0123456789:;<=>?@[\]^_`{|}~
The quick brown fox jumps over the lazy dog.
Съешь ещё этих мягких французских булок, да выпей чаю.

There's a python version available too!

8-Series Fonts

Suitable when using the full height of an 8-row matrix

MatrixChunky8

Everything big and blocky - looks great as a time screen

image

[ BDF Download | TTF Download ]

MatrixChunky8X

Below the baseline is usually reserved for tails but with the 'X' fonts, there is no baseline - everything takes up the full 8 rows of pixels

image

[ BDF Download | TTF Download ]

MatrixLight8

Most characters have been lightened and stylized

image

[ BDF Download | TTF Download ]

MatrixLight8X

Lightened and stylized in 8 full rows - this one looks really good on info screens!

image

[ BDF Download | TTF Download ]

6-Series Fonts

Suitable when using a weekday band underneath the time on an 8-row matrix

Please note a lot of accented characters in the non-X fonts were pushed below the baseline to make them look slightly less terrible.

MatrixChunky6

Everything big and blocky

image

[ BDF Download | TTF Download ]

MatrixChunky6X

Big and blocky in 6 full rows

image

[ BDF Download | TTF Download ]

MatrixLight6

Lightened and stylized

image

[ BDF Download | TTF Download ]

MatrixLight6X

Lightened and stylized in 6 full rows

image

[ BDF Download | TTF Download ]

Characters Included

Latin-1

Basic Latin

! "#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~

Latin Extended-A

¡¢£¤¦§¨©ª«¬®¯°±²³´µ¶¥·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ

Unicode

Latin-1 Supplement

ĀāĂ㥹ĆćĈĉĊċČčĎďĐđĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪīĬĭĮįİıIJijĴĵĶķĸĹĺĻļĽľĿŀŁłŃńŅņŇňʼnŊŋŌōŎŏŐőŒœŔŕŖŗŘřŚśŜŝŞşŠšŢţŤťŦŧŨũŪūŬŭŮůŰűŲųŴŵŶŷŸŹźŻżŽžſ

Cyrillic

АаБбВвГ㥴ДдЕеЄєЖжЗзИиІіЇїЙйКкЛлМмНнОоПпРрСсТтУуФфХхЦцЧчШшЩщЬьЮюЯя

Greek * Only in 8-series Fonts

ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΤΥΦΧΨΩΆΈΉΊΌΎΏΪΫαβγδεζηθικλμνξοπρςστυφχψωάέήίϊϋόύώ

Note these have not been eye-tested by an actual Greek person. Please let me know if they're okay!

Vietnamese * Only in 8-series Fonts

Vietnamese uses these characters, already present in Basic Latin and Extended-A sets:

ABCDEGHIKLMNOPQRSTUVXYabcdeghiklmnopqrstuvxyÀÁÂÃÈÉÊÌÍÒÓÔÕÙÚÝàáâãèéêìíòóôõùúýĂăĐđĨĩŨũ

As well as these:

ƠơƯưẠạẢảẤấẦầẨẩẪẫẬậẮắẰằẲẳẴẵẶặẸẹẺẻẼẽẾếỀềỂểỄễỆệỈỉỊịỌọỎỏỐốỒồỔổỖỗỘộỚớỜờỞởỠỡỢợỤụỦủỨứỪừỬửỮữỰựỲỳỴỵỶỷỸỹ

Note these have not been eye-tested by an actual Vietnamese person. Please let me know if they're okay! A lot of characters in Chunky8 (and some in Light8) had to be pushed below the baseline to make the accent possible. The 8X fonts are probably okay. I do wonder if the vowels with horns or dots are actually legible (particulary the O's in positions 7896 to 7907).

International Phonetic Alphabet * Only in 8-series Fonts

Please note that these characters are much wider than the standard characters because tails, staffs, and curves are quite important to the IPA. They are mostly based on the Light8 style and are identical in all 8-series fonts.

The IPA mostly uses these characters:

ɐɑɒɓɔɕɖɗɘəɚɛɜɝɞɟɠɡɢɣɤɥɦɧɨɪɫɬɭɮɯɰɱɲɳɴɵɶɸɹɺɻɼɽɾɿʀʁʂʃʄʅʈʉʊʋʌʍʎʏʐʑʒʔʕʘʙʚʛʜʝʟʡʢ

If you're unable to display all characters, depending on your needs, you can try adding the Obsolete / Disordered Speech / Sinology characters:

ɩɷʆʇʓʖʗʞʠʣʤʥʦʧʨ
ʩʪʫʬʭ
ʮʯ

Korean * Only in 8-series Fonts (only useful for time and date display)

오후전일월화수목금토요년

Chinese * Only in 8-series Fonts (only useful for time and date display)

一二三四五六天七八九十星期月上下午年日零〇

Note that 上下午 are squished a bit to allow display of 上午 & 下午 more easily. Also, 零 probably looks terrible.

General Punctuation

Spaces

The regular space (as available on most keyboards) is 2 pixels wide. Here are some other available spaces.

   
Space Name Unicode Width
Thin Space U+2009 1 pixel
En Space U+2002 3 pixels
Em Space U+2003 4 pixels
Pixel Spaces (that can be used as characters)

In case those spaces are no use to you (they're invisible and ESPHome will likely treat them as spaces), here are some other available spaces using the Unicode encircled number set.

⓪①②③④⑤⑥⑦⑧⑨⑩
Space Name Unicode Space Width
⓪ Circled 0 U+24EA 0 pixels
① Circled 1 U+2460 1 pixel
② Circled 2 U+2461 2 pixels
③ Circled 3 U+2462 3 pixels
④ Circled 4 U+2463 4 pixels
⑤ Circled 5 U+2464 5 pixels
⑥ Circled 6 U+2465 6 pixels
⑦ Circled 7 U+2466 7 pixels
⑧ Circled 8 U+2467 8 pixels
⑨ Circled 9 U+2468 9 pixels
⑩ Circled 10 U+2469 10 pixels
Other Punctuation Marks

The regular hypen-minus (as available on most keyboards) is 3 pixels wide plus a space. Here are some other available punctuations.

‐–—―•
Mark Name Unicode Width
‐ Hypen U+2010 1 pixel wide, no space
– En Hypen U+2013 2 pixels wide + space
— Em Hyphen U+2014 4 pixels wide + space
― Horizontal Bar U+2015 4 pixels wide, no space
• Bullet U+2022 1 pixel wide + space

Currency Symbols

₡₢₦₩₪₫€₭₮₱₲₴₵₸₹₺₼₽₾₿

Letterlike Symbols

℃℉

Unknown Character Symbols

One of these characters may appear if the character you call for is unavailable.

Appearance Name Unicode
image Null U+0000
image White Box U+25A1
image Unknown Character U+FFFD

Note that adding them to the glyphs list in an ESPHome does not seem to help when trying to display an actually unknown character (my clock just paints a wide block) but here are the latter two anyways (null isn't usable this way):

□�

Using These Fonts In ESPHome

To reduce the space that the font takes up during the compile please use code as such (specify which glyphs to include):

font: 
  - file: fonts/MatrixLight6.bdf
    id: special_font
    glyphs:  |-
      ! "#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz°

If using a TTF file, you MUST specify the font size:

font: 
  - file: fonts/MatrixLight8.ttf
    id: default_font
    glyphs:  |-
      ! "#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz°
    size: 8

According to the guide in the ESPHome docs, this is the way to include special characters:

    glyphs: [
      "%0123456789 EHLPClock.DatenfWiONI:SpTAr",
      "\u0000", # null
      "\u25A1", # white box
      "\uFFFD", # unknown character
      ]

Note this doesn't actually seem to work for getting ESPHome to show the box or unknown character when trying to display an un-included glyph... adding null and white box (together) change something about how it is handled - a box is shown but it isn't the one in the font (and adding unknown character has no effect).

BDF or TTF?

Sometime in 2025, ESPHome switched to Freetype for font encoding (instead of Pillow).

BDF files with Unicode appear to be encoded correctly... but if you get any errors, try the TTF font. There is no size difference in the compiled .bin file so don't worry if one is more or less space-efficient than the other.

Pillow Problems with BDF

As of 2024, ESPHome was using Pillow to encode fonts and it would not encode Unicode BDF files correctly. Anything beyond the normal ASCII range would cause errors like:

UnicodeEncodeError: 'latin-1' codec can't encode character '\u0416' in position 0: ordinal not in range(256)

This error has to do with the way that Pillow interprets a BDF font file as being in the Latin-1 codepage if the character list doesn't match what it expects. Since that part of Pillow is quite old, there seems to be no interest in fixing it to match UTF standards. So, if you're stuck with Pillow and wish to use Unicode characters (anything outside of Latin Basic and Extended-A), you must use a TTF file instead.

Sidenote that Pillow also has a glyph limit with BDF fonts of 256. Freetype has no such limit (I think).

Compiling Errors

Any characters included in the glyphs list that are not actually in the font will cause ESPHome to error when compiling. Any character requested not included in the glyphs list should result in an error and/or a block or blank being displayed by your clock.

Also note that there is a limit of 256 characters that can be used. This is a hard limit set by Pillow. If your glyphs list is longer, any characters beyond that limit will simply not be displayed.

EspHoMaTriXv2

When using EspHoMaTriX, check that this is in your yaml (edit as needed) (this note may be outdated):

ehmtxv2:
  default_font_id: default_font
  default_font_yoffset: 6
  special_font_id: special_font
  special_font_yoffset: 8

Please note that yoffset can be tricky. You should use a number that corresponds with the baseline of the font. For these fonts, there is actually nothing below the font baseline; I've designed the fonts so the non-X fonts are actually raised 1 pixel above the baseline so the tails appear correctly.

Update History

Date Release Notes
2026.03.08 Light8X: Minor fix to p and q, web renderer tweaked again
2026.03.01 Python tool added, tweaks to both renderers
2026.02.27 Web renderer added, more minor fixes to many glyphs
2026.02.20 Unknown characters added to Light fonts, "Character substiutions" removed from all, minor fixes to many glyphs
2025.05.25 Minor fixes to Korean, Chinese, ESPHome now works with BDF
2024.10.09 Vietnamese and IPA added to 8-series
2024.01.09 Greek and Chinese added to 8-series
2023.10.15 Cyrillic added to 6-series
2023.10.13 Korean added to 8-series
2023.10.05 Readme improved, hyphens and spaces added
2023.09.23 Cyrillic added to 8-series
2023.09.22 More Unicode characters added, renamed from MatrixClock fonts to Matrix fonts
2023.09.18 Added Latin-1 Supplement to 6-series
2023.07.23 X-series fonts added (TTF & BDF fonts): Added Latin-1 Supplement to 8-series
2023.04.06 6-series & 8-series fonts based on Tom Thumb: ASCII character set (TTF & BSD fonts)

Editing or Contributing

If you wish a character set to be added, open an issue, make a request! Please keep your communication lines open because I'm not likely familiar with your language and I'll have questions!

Check out FontForge: https://fontforge.org/en-US/

Thanks to...

My wife for huge help with Korean and Chinese characters.

Andrew J.Swan for huge help with Cyrillic characters.

Inspiration

Originally, I used Tom Thumb as a base. There may be still be some resemblance but that's just because there's only so much you can do with such limited pixels. Nevertheless, if you're interested in a 4x6 (3x5 useable) monospaced font you can click here.

Also, some inspiration for the Korean characters was borrowed from Dalmoori Font, a very nice Hangul pixel font.

The Chinese characters are almost 100% copied from Boutique Bitmap 7x7 Font, a Chinese pixel font and stretched a bit in the X-series.