The ESP32 firmware includes these built-in fonts:
- Unscii with font size 8pt
- Roboto Condensed in four font sizes depending on the display resolution:
- 320x240: 12, 16, 24 and 32pt
- 480x320: 16, 24, 32 and 48pt
Each font contains selected glyphs of the Latin-1 character set and MaterialDesign icons below.
The built-in fonts can be set by using the pointsize as parameter. For example:
It is possible to create custom builds with built-in fonts of other sizes (choose any four of 12, 14, 16, 20, 22, 24, 26, 28, 32, 36, 38, 40, 44, 48) and
supporting Latin-2, Cyrillic, Greek or Vietnamese character sets (even combined)
The icons in the list below are included with the built-in font sizes. Included are a range of arrows, navigation, climate, controls, devices, energy, lights, places, presence, security, sound, time and wireless icons.
You can use any TrueType font containing characters or icons.
- Upload any TTF (TrueType) font file to the flash partition of your plate. If you want to use other styles than Regular like Italic or Bold, make sure you use a font which provides separate, optimized versions for these. You can upload and use multiple font files, but within a property you can only select one font.
- In the jsonl code use the filename of the font without the extension and the desired font size added to it. So for example to have a text rendered in Arial 20px, you upload arial.ttf to the plate and use
If you get an error when you upload the TTF file to the plate, make sure to use shorter filenames.
You can use different fonts for different properties of the same objects, like
To use MDI icons, get the latest webfont build from their site. From the unzipped archive you need the
Use as few as possible separate TTF fonts in parrallel, because each of them is loaded in memory, which will exhaust faster. With the open source FontForge tool you can combine glyphs and icons from different fonts into one single TTF file and create your custom collection based on your needs.
With the online Font Converter tool you can create binary font files from any TTF, OTF or WOFF font. You can select custom ranges of Unicode characters and specify the bpp (bits-per-pixel).
The font converter is designed to be compatible with LVGL. An offline version of the converter is also available here.
Online Font Converter~
How to use the font converter?
- Give a name to the binary font. E.g. "arial_20"
- Specify the height in pixels
- Set the bpp (bits-per-pixel). Higher values result in a smoother (anti-aliased) font but will require more flash and memory.
- Choose a TTF, OTF or WOFF source font file
- Set a range of Unicode characters to include in your font or list the characters in the Symbols field
- Optionally choose another font too and specify the ranges and/or symbols for it as well. The characters will be merged into the final binary font.
- Click the Convert button to download the resulting
- Upload the resulting binary font file to the flash partition of your plate.
- In the jsonl code use
"text_font":"arial_20"without the extension or use command
The entire binary font is cached into memory when it is first used. PSram is highly recommended to use binary fonts.
The encoding of the icons depends on how they are sent to the plate:
1. As JSON payload~
To use an icon in a
jsonl payload you need to prefix the UTF-8 character code with
ArduinoJSON will correctly decode the text into it's UTF-8 representation while parsing the JSON object:
If the icon codepoint is larger than
0xFFFF you need to convert the codepoint to its surrogate pair first!
Then include both UTF-16 surrogate characters in the payload like this:
2. As raw payload~
Raw payloads are directly passed to the LVGL text rendering engine without any conversion on the MCU. You need to make sure the string is properly encoded into UTF-8 by the application sending the payload! How this is accomplished depends on the Home Automation tool:
Code points up to
0xFFFFshould be encoded as
"\uE6E8"in the template. Note: Use lowercase
\uand exactly 4 hexadecimal digits.
Code points above
0xFFFFmust be encoded as
"\U0001F5E9"in the template. Note: Use capital
\Uand exactly 8 hexadecimal digits.
At the end of the template you must indicate that Home Assistant needs encoded the string before sending it by appending
|e(pipe symbol +
e) at the end.
1 2 3
For MDI icons, use this modified cheatsheet to get the raw and the surrogate paired codepoints ready to use. Note that the cheatsheet may not contain the very latest icons.
The characters are encoded in UTF-8. All character sets include the Ascii
0x20-0x7E characters, the non-braking-space (NBSP) and 10 universal symbols.
Each set contains roughly the same extended characters from its equivalent iso-8859 standard.
All character sets also contain about 130 standard Material Design Icons for home automation use.
The default font in pre-compiled binaries is Roboto-Condensed-Regular with the Latin 1 character set. There is no support for right-to-left scripts.
For example: To display the ÷ character on the plate you need to use
\u00F7 in json or jsonl commands, or send the encoded UTF-8 bytes
0xB7 in other commands.
Includes all ASCII 0x20-0x7E characters extended with a non-breaking space and 10 universal symbols:
This is the default character set of the pre-compiled firmware binary files.
Includes all characters and symbols from the Ascii range above.
Covers Northern, Western and Southern European languages: English (en), French (fr), Spanish (es), Portuguese (pt), Italian (it), Dutch (nl), German (de), Danish (da), Swedish (sv), Norwegian (no), Finnish (fi), Albanian (sq), Turkish (tr)
¡ ¿ À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ Ğ ğ İ ı Œ œ Ş ş Š š Ž ž ẞ
Covers Central and Eastern European languages: Czech (cs), Hungarian (hu), Polish (pl), Romanian (ro), Croatian (hr), Slovak (sk), Slovenian (sl), Sorbian (sb)
Á Â Ä É Í Î Ó Ô Ö Ú Ü Ý á â ä é í î ó ô ö ú ü ý Ă ă Ą ą Ć ć Č č Ď ď Đ đ Ĕ ĕ Ę ę Ě ě Ĺ ĺ Ľ ľ Ł ł Ń ń Ň ň Ő ő Ŕ ŕ Ř ř Ś ś Ş ş Š š Ţ ţ Ť ť Ů ů Ű ű Ź ź Ż ż Ž ž Ǎ ǎ Ȁ ȁ Ȃ ȃ Ȅ ȅ Ȇ ȇ Ȉ ȉ Ȋ ȋ Ȍ ȍ Ȏ ȏ Ȑ ȑ Ȓ ȓ Ȕ ȕ Ȗ ȗ Ș ș Ț ț
Covers the Slavic languages that use a Cyrillic alphabet, including Belarusian, Bulgarian, Macedonian, Russian, Serbian, and Ukrainian
Ѐ Ё Ђ Ѓ Є Ѕ І Ї Ј Љ Њ Ћ Ќ Ѝ Ў Џ А Б В Г Д Е Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ъ Ы Ь Э Ю Я а б в г д е ж з и й к л м н о п р с т у ф х ц ч ш щ ъ ы ь э ю я ѐ ё ђ ѓ є ѕ і ї ј љ њ ћ ќ ѝ ў џ
Covers the Greek (el) language:
Ά Έ Ή Ί Ό Ύ Ώ ΐ Α Β Γ Δ Ε Ζ Η Θ Ι Κ Λ Μ Ν Ξ Ο Π Ρ Σ Τ Υ Φ Χ Ψ Ω ά έ ή ί ΰ α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ ς σ τ υ φ χ ψ ω ϊ ϋ ό ύ ώ
Covers the Vietnamese (vi) language:
Á À Â Ă Ã Ấ Ầ Ắ Ằ Ẫ Ẵ Ả Ẩ Ẳ Ạ Ậ Ặ Đ É È Ê Ẽ Ế Ề Ễ Ẻ Ể Ẹ Ệ Í Ì Ĩ Ỉ Ị Ó Ò Ô Õ Ố Ồ Ỗ Ỏ Ơ Ổ Ọ Ớ Ờ Ỡ Ộ Ở Ợ Ú Ù Ũ Ủ Ư Ụ Ứ Ừ Ữ Ử Ự Ý Ỳ Ỹ Ỷ Ỵ á à â ă ã ấ ầ ắ ằ ẫ ẵ ả ẩ ẳ ạ ậ ặ đ é è ê ẽ ế ề ễ ẻ ể ẹ ệ í ì ĩ ỉ ị ó ò ô õ ố ồ ỗ ỏ ơ ổ ọ ớ ờ ỡ ộ ở ợ ú ù ũ ủ ư ụ ứ ừ ữ ử ự ý ỳ ỹ ỷ ỵ ₫