Json template - OpenEPaperLink/OpenEPaperLink GitHub Wiki

Images can be generated by the esp32 by pushing or pulling a json template. In the template, you can draw whatever you like.

  • Pull: set the URL using the json template content card.
  • Push: do a http POST to /jsonupload, with parameters mac and json. A demo/test-form is placed on /jsontemplate-demo.html

Example json file:

[
    {"text": [5,5,"Bahnschrift 20","fonts/bahnschrift20",1]},
    {"box": [10,30,20,20,1]},
    {"box": [35,30,20,20,2]},
    {"triangle": [60,30,60,50,80,40,1]},
    {"text": [5,80,"Plain text glasstown_nbp_tf","glasstown_nbp_tf",1]},
    {"text": [5,95,"Plain text 7x14_tf","7x14_tf",2]},
    {"text": [5,110,"Plain text t0_14b_tf","t0_14b_tf",1]},
    {"text": [135,5,"30","fonts/bahnschrift30",2]},
    {"text": [215,5,"70","fonts/bahnschrift70",1]},
    {"text": [150,80,"50","fonts/calibrib50",2,0]},
    {"text": [205,60,"80","fonts/calibrib80",2]},
    {"text": [90,35,"calibrib30","fonts/calibrib30",1]},
    {"line": [10,120,290,120,1]},
    {"line": [10,115,290,115,2]}
]

Result:

Json template

Text

  • { "text": [x, y, "text", "fontname", color] }
  • { "text": [x, y, "text", "fontname", color, alignment] }
  • { "text": [x, y, "text", "fontname", color, alignment, size] }
  • { "text": [x, y, "text", "fontname", color, alignment, size, background_color] }

Templates

When displaying text on a tag there is an option to insert template variables into the text. These will get replaced by the AP. There are two kinds of template variables: system variables ({ap_ip}) and JSON variables ({.a.b.1.c}). Notice how both template variables are encapsulated in curly braces { and }, but JSON variables start with a dot . and are separated by dots.

System variables

System variables are generated by the AP itself as well as its connected tags. They can also be set using the POST endpoints/set_var and /set_vars. There is also an option to set system variables with custom tag data (documentation will follow soon).

Here is a list of possible system variables:

Name Description Example
ap_ip Access Point ip address 192.168.1.5
ap_ch Access Point channel 11
ap_tagcount Access Point tag count 42
ap_date Current date 20-05-2023
ap_time Current time 06:27:54

JSON variables

JSON variables are somewhat special meaning that they can only be used when both a JSON template Filename as well as a URL are specified. The AP will then fetch the URL and parse it as JSON. Next the JSON template file is parsed and both system and JSON variables are replaced.

Take this example:

The endpoint http://192.168.5.6/rest/state returns a JSON:

{
    "a": {
        "b:"[
            "c": "value",
            "d": 4
        ]
    }
}

Then the values of c and d can be used inside the JSON template file as {.a.b.0.c} and {.a.b.1.d} respectively.

There is also support for single math operations (+, -, * and /). You can only ever combine two variables: {.a}*{.b}. Something like {.a}*{.b}/{.c} will NOT work!

Note that the returned JSON of the endpoint should be as small as possible due to the constrained resources on the AP. Currently the JSON is limited to 1000 bytes in size. One possibility to optimize the code would be to create a filter from the given JSON template variables, but then the JSON template file would need to be parsed twice, once for filter creation and once more for variable replacement.

Paragraph Text

A text, bounded by a box. The text flows to the next lines (breaking on spaces, hyphen and CR). Only works for .vlw bitmap fonts. Available from release 2.06

  • { "textbox": [x, y, w, h, "text", "fontname" }
  • { "textbox": [x, y, w, h, "text", "fontname", color ] }
  • { "textbox": [x, y, w, h, "text", "fontname", color, line height] }

Default line height = 1. Try values like 1.25 for a slightly bigger line spacing.

Graphics

  • { "box": [x, y, width, height, color] }
  • { "rbox": [x, y, width, height, corner-radius, color] }
  • { "line": [x1, y1, x2, y2, color] }
  • { "triangle": [x1, y1, x2, y2, x3, y3, color] }
  • { "circle": [x, y, radius, color] }

Parameters

  • x: X pixel coordinate (x1, x2 and x3 being multiple positions)
  • y: Y pixel coordinate (y1, y2 and y3 being multiple positions)
  • width: Width in pixels
  • height: Height in pixels
  • "text": Text to display
  • "fontname": Name of font -> see Fonts section further down
  • size: Font size
  • color: see below
  • alignment: One of 0 (left), 1 (center) and 2 (right)

When entering coordinates, take note of the following: The small bitmap fonts have their origin at the left bottom corner. The vlw bitmap fonts have their origin at the top left. And the origin of the truetype fonts is as much as possible at the baseline, but that can differ depending on the font. So, it's a bit trial and error.

Color parameter

  • 0 or "white": white
  • 1 or "black": black
  • 2 or "red": red
  • 3 or "yellow": yellow (if the tag supports it)
  • 4 or "lightgray" (uses pattern dither, not suitable for small fonts)
  • 5 or "darkgray" (uses pattern dither, not suitable for small fonts)
  • 6 or "pink" (uses pattern dither, not suitable for small fonts)

Fonts

Bitmap fonts:

any fonts in the /fonts folder:

  • bahnschrift20.vlw upper case, lower case, numbers, and äöüßÄÖÜåÅ!\"#$%&'()*+,-./:;<=>?@[\\]^_{|}~°
  • bahnschrift30.vlw upper case, lower case, numbers, and äöüßÄÖÜåÅ!\"#$%&'()*+,-./:;<=>?@[\\]^_{|}~°
  • bahnschrift70.vlw only 0123456789.
  • calibrib30.vlw upper case, lower case, numbers, and äöüßÄÖÜåÅ!\"#$%&'()*+,-./:;<=>?@[\\]^_{|}~°
  • twcondensed20.vlw Only SUMOTWEHFRAZDIV0123456789. Use for weekday names and numbers.

If you want to add extra fonts to this list, you can convert them from Truetype by using Processing (https://processing.org/) and this script https://github.com/Bodmer/TFT_eSPI/tree/master/Tools/Create_Smooth_Font/Create_font . Make sure you set smooth = false in the script, to prevent antialissing. Place the .vlw font file in the /fonts folder. No need to update/rebuild the firmware.

Truetype fonts:

{ "text": [x, y, "text", "fontname", color, alignment, size] }

Put the truetype font in the /fonts folder. Make sure you select your truetype font file carefully: some are very big, and that will not fit in the file system.

example: { "text": [0, 10, "Use any font in any size!", "Inkfree.ttf", 1, 0, 40] }

Tip: if you want icons and symbols, the Font Awesome font works quite well.

Rotate Screen

It is possible to rotate the complete display:

{ "rotate": 0 }

The possible Values are 0 for default orintation, 1 for 90° , 2 for 180° and 3 for 270°

⚠️ **GitHub.com Fallback** ⚠️