Skip to content
Template-oriented driver for e-paper displays
Branch: master
Clone or download
Latest commit 174c024 Sep 10, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
examples/weather_dashboard
lib
src mdns Apr 14, 2018
web
.build_web.py
.get_version.py
.gitignore
.prepare_release
.travis.yml
README.md
platformio.ini

README.md

e-Paper Templates Build Status release License

Template-oriented driver for e-paper displays using Arduino. Define a layout with a JSON template, and update the display by changing variables via a REST API or MQTT.

Demo

Requirements

  1. ESP8266/ESP32. The entire display frame is buffered in memory, so ESP32 may be a more suitable for large displays.
  2. A WaveShare e-Paper module. Currently only the 4.2" black/white display is supported.

Setup

  1. Flash your MCU.
    1. With PlatformIO: for example pio run -e esp32 -t upload.
    2. Use a pre-compiled binary from the releases page.
  2. Setup WiFi. A setup AP will appear named epaper_XXXXXX. The default password is waveshare.

Variables

Displays are made dynamic by binding variables to certain regions. When variables are updated, the corresponding regions are updated. There are two ways to update variables:

REST API

$ curl -v -X PUT -H'Content-Type: application/json' -d '{"variable_name":"variable_value"}' http://epaper-display/variables

MQTT

Configure MQTT using the /settings endpoint:

$ curl -v -X PUT -H'Content-Type: application/json' -d '{
  "mqtt_server": "deepthought.sidoh.org",
  "mqtt_username": "sidoh",
  "mqtt_password": "hunter2",
  "mqtt_variables_topic_pattern": "template-displays/display1/:variable_name"
}' http://epaper-display/settings

You can then publish messages to, for example template-displays/display1/variable_name to update the value of the variable variable_name.

mosquitto_pub -h my-mqtt-broker.com -u username -P hunter2 -t 'template-displays/display1/variable_name' -m "variable_value"

Formatters

Variables can optionally be passed through a formatting function before being rendered. The supported formatters are:

time

Format a UNIX epoch timestamp using standard strftime flags.

{
  "text": [
    {
      "x": 100,
      "y": 100,
      "font": "FreeSansBold9pt7b",
      "color": "black",
      "variable": "my_variable",
      "formatter": "time",
      "args": {
        "timezone": "PT",
        "format": "%l:%M %p"
      }
    }
  ]
}

The timestamp will be converted to the provided timezone if one is specified.

cases

Simple map from key to value. Particularly useful for variable bitmaps:

{
  "bitmaps": [
    {
      "x": 100,
      "y": 100,
      "w": 64,
      "h": 64,
      "variable": "my_variable",
      "formatter": "cases",
      "args": {
        "prefix": "/b/",
        "default": "unknown.bin",
        "cases": {
          "sunny": "sunny.bin",
          "cloudy": "cloudy.bin"
        }
      }
    }
  ]
}

Templates

Templates are composed of the following types of components:

  1. Lines
  2. Text
  3. Bitmaps

Lines

Lines simply have start and end coordinates. You can optionally specify a color. Example:

{
  "lines": [
    {"x1": 0, "x2": 100, "y1": 0, "y2": 100, "color": "black"}
  ]
}

Text

Text can be defined statically, or using a variable. Examples of each:

{
  "text": [
      {
      "x": 10,
      "y": 220,
      "font": "FreeSansBold9pt7b",
      "static": "Outside"
    },
    {
      "x": 120,
      "y": 220,
      "font": "FreeSans9pt7b",
      "variable": "outside_temp_updated_at",
      "formatter": "Time",
      "args": {
        "timezone": "PT",
        "format": "%l:%M %p"
      }
    },
    {
      "x": 10,
      "y": 275,
      "font": "FreeMonoBold24pt7b",
      "variable": "outside_temp"
    }
  ]
}

Bitmaps

Bitmaps are in a special compacted format. Here is a ruby script that converts a PNG to the bitfield format.

They are referenced via filenames, and can be managed through the REST API:

$ curl -X POST -F 'my-bitmap.bin=@path/to/bitmap.bin' http://epaper-display/bitmaps
$ curl -v http://epaper-display/bitmaps
[{"name":"/b/bitmap.bin","size":512}]
$ curl -X DELETE http://epaper-display/bitmaps/bitmap.bin

Example:

{
  "bitmaps": [
    {
      "x": 0,
      "y": 0,
      "w": 64,
      "h": 64,
      "color": "black",
      "static": "/b/bitmap.bin"
    },
    {
      "x": 100,
      "y": 100,
      "w": 64,
      "h": 64,
      "variable": "my_variable",
      "formatter": "cases",
      "args": {
        "prefix": "/b/",
        "default": "unknown.bin",
        "cases": {
          "sunny": "sunny.bin",
          "cloudy": "cloudy.bin"
        }
      }
    }
  ]
}

Examples

The examples directory has a few sample templates.

Managing templates

Templates can be managed via the REST API:

$ curl -X POST -F 'image=@data/path/to/template.json' http://epaper-display/templates
$ curl http://epaper-display/templates
[{"name":"/t/template.json","size":3527}]
$ curl -X DELETE http://epaper-display/templates/template.json

Selecting a template

$ curl -X PUT -H'Content-Type:application/json' \
  -d '{"template_path":"/templates/template.json"}' \
  http://epaper-display/settings

REST API

The following RESTful routes are available:

  1. /variables - GET, PUT.
  2. /templates - GET, POST.
  3. /templates/:template_name - GET, DELETE, PUT
  4. /bitmaps - GET, POST.
  5. /bitmaps/:bitmap_name - GET, DELETE.
  6. /settings - GET, PUT.
  7. /about - GET.
  8. / - GET.
You can’t perform that action at this time.