Skip to content

Fonts~

Built-in~

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:

1
2
p4b1.text_font=24
p4b2.value_font=12

Developer Note

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) by customizing user_config_override.h.

Icons~

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.

Icon Code Name Icon Code Name
E045 arrow-down F2A3 battery-high
E6C0 arrow-down-box F2A1 battery-low
E04D arrow-left F2A2 battery-medium
E054 arrow-right E08E battery-outline
E05D arrow-up E5F1 ev-station
E6C3 arrow-up-box E32A leaf
E140 chevron-down F40B lightning-bolt
E141 chevron-left E425 power
E142 chevron-right E6A5 power-plug
E143 chevron-up E769 ceiling-light
E60C subdirectory-arrow-left F020 coach-lamp
E01B air-conditioner E95F desk-lamp
E957 cloud-search-outline E8DD floor-lamp
E238 fire E6B5 lamp
E438 radiator E335 lightbulb
EAD7 radiator-disabled E6E8 lightbulb-on
E717 snowflake F054 outdoor-lamp
E50F thermometer F2BA string-lights
E58C water F1E1 vanity-light
E58E water-percent E91C wall-sconce
E590 weather-cloudy E12C check
E591 weather-fog E156 close
E592 weather-hail E493 cog
E593 weather-lightning E1D9 dots-vertical
E67E weather-lightning-rainy E2DC home
E594 weather-night E6A1 home-outline
E595 weather-partly-cloudy E374 minus
E596 weather-pouring E415 plus
E597 weather-rainy E2E3 bed
E598 weather-snowy E10B car
E67F weather-snowy-rainy E176 coffee
E599 weather-sunny E606 pool
E59D weather-windy E9A0 shower
E59E weather-windy-variant EA70 silverware-fork-knife
E5A8 white-balance-sunny E4B9 sofa
E0ED calendar E9AB toilet
E150 clock-outline E004 account
E2DA history E64A human-greeting
E51B timer-outline E70E run
E0AF bluetooth E026 alert
E5A9 wifi E7AE cctv
E0AC blinds E81B door-closed
F011 blinds-open F0AF door-closed-lock
F2D4 garage-open-variant E81C door-open
F2D3 garage-variant E30B key-variant
F11C window-shutter E33E lock
F11D window-shutter-alert EFC6 lock-open-variant
F11E window-shutter-open E565 shield-check
E09A bell E68A shield-home
E11C cellphone E99D shield-lock
EAAC dishwasher F1DB window-closed-variant
E1FA engine EF5F monitor-speaker
E210 fan E75A music
E96B fountain E3E4 pause
E28F fridge-outline E40A play
E5FA kettle E456 repeat
E322 laptop E457 repeat-off
EC99 microwave E458 repeat-once
F39D recycle-variant E49D shuffle
F1F3 robot-mower-outline E49E shuffle-disabled
E70D robot-vacuum E4AD skip-next
E4DE stove E4AE skip-previous
E502 television E4C3 speaker
EA7A trash-can-outline E4DB stop
E917 tumble-dryer E57E volume-high
E72A washing-machine E580 volume-medium
E58F water-pump E75F volume-mute

Custom Fonts~

TrueType~

You can use any TrueType font containing characters or icons.

  1. 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.
  2. 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 "text_font":"arial20" or command p1b2.text_font=arial20.

Note

If you get an error when you upload the TTF file to the plate, make sure to use shorter filenames.

Tip

You can use different fonts for different properties of the same objects, like "text_font":"mdi32","value_font":"robotocondensed19". To use MDI icons, get the latest webfont build from their site. From the unzipped archive you need the .ttf

Warning

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.

Binary~

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?

  1. Give a name to the binary font. E.g. "arial_20"
  2. Specify the height in pixels
  3. Set the bpp (bits-per-pixel). Higher values result in a smoother (anti-aliased) font but will require more flash and memory.
  4. Choose a TTF, OTF or WOFF source font file
  5. Set a range of Unicode characters to include in your font or list the characters in the Symbols field
  6. 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.
  7. Click the Convert button to download the resulting .bin file.



You can use both "Ranges" and "Symbols" or only one of them

 

Usage~

  1. Upload the resulting binary font file to the flash partition of your plate.
  2. In the jsonl code use "text_font":"arial_20" without the extension or use command p1b2.text_font=arial_20

Warning

The entire binary font is cached into memory when it is first used. PSram is highly recommended to use binary fonts.

Encoding~

The encoding of the icons depends on how they are sent to the plate:

1. As JSON payload~

To use an icon in a json or jsonl payload you need to prefix the UTF-8 character code with \u. ArduinoJSON will correctly decode the text into it's UTF-8 representation while parsing the JSON object:

jsonl example:

1
{"page":2,"id":1,"obj":"label","w":150,"h":50,"text":"\uE64A Hello world!"}

json example:

1
["p2b1.text=\uE64A Hello world!"]

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:

jsonl example:

1
{"page":2,"id":1,"obj":"label","w":150,"h":50,"text": "\uDB81\uDC25 Hello world!"}

json example:

1
["p2b1.text=\uDB81\uDC25 Hello world!"]

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:

Home Assistant~

  • Code points up to 0xFFFF should be encoded as "\uE6E8" in the template.
    Note: Use lowercase \u and exactly 4 hexadecimal digits.

  • Code points above 0xFFFF must be encoded as "\U0001F5E9" in the template.
    Note: Use capital \U and 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
- obj: "p1b2"  # light-switch toggle button
  properties:
    "text": '{{ "\uE6E8" if is_state("light.x","on") else "\U0001F5E9" |e }}'

Tip

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.

Character Sets~

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 0xC3 0xB7 in other commands.

Ascii~

Includes all ASCII 0x20-0x7E characters extended with a non-breaking space and 10 universal symbols:

NBSP £ ° ± ² ³ µ × ÷ € •

Latin 1~

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)

¡ ¿ À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ Ğ ğ İ ı Œ œ Ş ş Š š Ž ž ẞ

Latin 2~

Needs compiling with customization. Includes all characters and symbols from the Ascii range above.

Covers Central and Eastern European languages: Czech (cs), Hungarian (hu), Polish (pl), Romanian (ro), Croatian (hr), Slovak (sk), Slovenian (sl), Sorbian (sb)

Á Â Ä É Í Î Ó Ô Ö Ú Ü Ý á â ä é í î ó ô ö ú ü ý Ă ă Ą ą Ć ć Č č Ď ď Đ đ Ĕ ĕ Ę ę Ě ě Ĺ ĺ Ľ ľ Ł ł Ń ń Ň ň Ő ő Ŕ ŕ Ř ř Ś ś Ş ş Š š Ţ ţ Ť ť Ů ů Ű ű Ź ź Ż ż Ž ž Ǎ ǎ Ȁ ȁ Ȃ ȃ Ȅ ȅ Ȇ ȇ Ȉ ȉ Ȋ ȋ Ȍ ȍ Ȏ ȏ Ȑ ȑ Ȓ ȓ Ȕ ȕ Ȗ ȗ Ș ș Ț ț

Cyrillic~

Needs compiling with customization. Includes all characters and symbols from the Ascii range above.

Covers the Slavic languages that use a Cyrillic alphabet, including Belarusian, Bulgarian, Macedonian, Russian, Serbian, and Ukrainian

Ѐ Ё Ђ Ѓ Є Ѕ І Ї Ј Љ Њ Ћ Ќ Ѝ Ў Џ А Б В Г Д Е Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ъ Ы Ь Э Ю Я а б в г д е ж з и й к л м н о п р с т у ф х ц ч ш щ ъ ы ь э ю я ѐ ё ђ ѓ є ѕ і ї ј љ њ ћ ќ ѝ ў џ

Greek~

Needs compiling with customization. Includes all characters and symbols from the Ascii range above.

Covers the Greek (el) language:

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

Vietnamese~

Needs compiling with customization. Includes all characters and symbols from the Ascii range above.

Covers the Vietnamese (vi) language:

Á À Â Ă Ã Ấ Ầ Ắ Ằ Ẫ Ẵ Ả Ẩ Ẳ Ạ Ậ Ặ Đ É È Ê Ẽ Ế Ề Ễ Ẻ Ể Ẹ Ệ Í Ì Ĩ Ỉ Ị Ó Ò Ô Õ Ố Ồ Ỗ Ỏ Ơ Ổ Ọ Ớ Ờ Ỡ Ộ Ở Ợ Ú Ù Ũ Ủ Ư Ụ Ứ Ừ Ữ Ử Ự Ý Ỳ Ỹ Ỷ Ỵ á à â ă ã ấ ầ ắ ằ ẫ ẵ ả ẩ ẳ ạ ậ ặ đ é è ê ẽ ế ề ễ ẻ ể ẹ ệ í ì ĩ ỉ ị ó ò ô õ ố ồ ỗ ỏ ơ ổ ọ ớ ờ ỡ ộ ở ợ ú ù ũ ủ ư ụ ứ ừ ữ ử ự ý ỳ ỹ ỷ ỵ ₫


Last update: 2023-12-09