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:

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.

Code	Name	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.

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 "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?

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 .bin file.

Name

Size

Bpp

Enable font compression (reduces size)

Source font

Ranges & Codepoints

Symbols & Characters

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

Usage~

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 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:

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

json example:

["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:

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

json example:

["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.

- 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