Tutorial: Uploading & Using Custom Fonts, with examples
Purpose
This tutorial provides instructions and examples on how to use custom fonts when designating "Json template" as the content source for OpenEPaperLink (OEPL) tags. This tutorial may be a bit verbose for those inexperienced (noobs) to web development.
Instructions
-
Find your font. See Open Source Fonts section for a very limited list of open-source fonts.
-
Download the font to your computer. For example: download Font Awesome v6.5.2 and then extract the font file
webfonts/fa-regular-400.ttf📘 Info
If download is in a compressed (ZIP, GZip, etc) package, then extract the font file(s).
-
On web browser, go to the admin page of your access point (AP), eg,
http://{ap_ip_address}/. Double-click on file explorer link (folder icon on page's menu bar, to the far right).Or just go directly to url:
http://{ap_ip_address}/edit. You may rename your font file before upload to the AP, but please note the following current filename limitations:- Can be alpha-numeric
- Can have caps
- Can have spaces
- limited to 32 characters, including the dot & extension. For example,
ABCDEFGHijklmnopqrstuvwxyz 1.ttf
-
Upload your font file to the
/fontsdirectory. -
On AP admin page, configure tag to:
- Content: Json template
- source: URL -or- Filename
If source is "URL", it should produce a valid JSON.
If source is "Filename", then you must first upload a valid JSON file to the root directory (
/). See step #3 for how to upload a file. The file should have an extension of '.json'. Once the file has been uploaded, then you can come back to this screen to select the desired file.
Examples
Using the included "weathericons.ttf" font
-
JSON:
[ { "text": [0, 0, "bahnschrift30.vlw...", "calibrib16.vlw", "red", 0, 16] }, { "text": [0, 16, "The quick brown fox jumps over the lazy dog", "bahnschrift30.vlw", "black", 0, 30] }, { "text": [0, 50, "weathericons.ttf...", "calibrib16.vlw", "red", 0, 16] }, { "text": [1, 66, "\uF000 \uF016 \uf045 \uf0E8 \uF071 \uF07A \uF0C4 \uF0EA", "weathericons.ttf", "black", 3, 30] } ] -
Output:
Using Font Awesome "fa-regular-400.ttf"
-
JSON:
[ { "text": [0, 0, "bahnschrift30.vlw...", "calibrib16.vlw", "red", 0, 16] }, { "text": [0, 16, "The quick brown fox jumps over the lazy dog", "bahnschrift30.vlw", "black", 0, 30] }, { "text": [0, 50, "fa-regular-400.ttf...", "calibrib16.vlw", "red", 0, 16] }, { "text": [1, 66, "\u2665 \uF087 \uF118 \u1F923 \u1F4B3", "fa-regular-400.ttf", "black", 3, 30] } ] -
Output:
Caveats
Supported Fonts
- As of AP version 2.60b, only the following font types are supported:
- Processing fonts (
.vlw): This tutorial does not include instructions for how to createVLWfont. For that information, please refer to the Processing app below. - TrueType (
.ttf)
- Processing fonts (
Referencing specific character
In most cases with icon or symbol fonts (like Font Awesome and Weather Icons) or if you need to use a character that is not accessible via keyboard, you can open that font file using the Linux app font-manager (https://github.com/FontManager/font-manager). I don't know the specific apps for MacOS or Windows, sorry.
Using a font viever app like font-manager, find the character and get its Unicode number. For example, in the included Weather Icons font, the icon for hail, or is it meteor?, ( ) is Unicode F071.
In the JSON template, enter this character as \uXXXX. For example, \uF071. The "\u" must be lowercase "u" but the Unicode hex number (F071) is case insensitive.
Font Spacing
Some symbol or icon font characters are extra wide and need spacing before and after the character. Make sure you test and review your output.
Display Error
It looks like Unicode U+010000 to U+10FFFF cannot be display correctly (see https://en.wikipedia.org/wiki/UTF-16#U+0000_to_U+D7FF_and_U+E000_to_U+FFFF). If that is the case, you'll see the character instead. Font Awesome has a few characters in this situation.
Access Point
Mind not to upload too many custom font files or files too large as some APs have a small amount of memory. See https://github.com/OpenEPaperLink/OpenEPaperLink/wiki/Building-an-Access-Point.