TRMNL Image Generator

Generate images compatible with TRMNL e-ink displays.

Quick Start

Generate an HTML template, screenshot it, convert to 1-bit, upload:

# 1. Screenshot HTML at 800x480
playwright screenshot template.html raw.png --viewport-size=800,480

# 2. Convert to 1-bit monochrome
magick raw.png -monochrome -colors 2 -depth 1 -strip png:output.png

# 3. Upload to TRMNL
curl -X POST --data-binary @output.png \
  -H 'Content-Type: image/png' \
  'https://usetrmnl.com/api/plugin_settings/{PLUGIN_UUID}/image'

Image Requirements

TRMNL devices require specific image formatting:

ImageMagick Conversions

Standard 1-bit PNG

magick input.png -monochrome -colors 2 -depth 1 -strip png:output.png

With Floyd-Steinberg dithering (better gradients)

magick input.png -dither FloydSteinberg -remap pattern:gray50 -depth 1 -strip png:output.png

BMP3 format (alternative)

magick input.png -monochrome -colors 2 -depth 1 -strip bmp3:output.bmp

2-bit grayscale (FW 1.6.0+ only)

# Create colormap first
magick -size 4x1 xc:#000000 xc:#555555 xc:#aaaaaa xc:#ffffff +append -type Palette colormap-2bit.png

# Convert with colormap
magick input.png -resize 800x480\! -dither FloydSteinberg -remap colormap-2bit.png \
  -define png:bit-depth=2 -define png:color-type=0 output.png

HTML Template Design

For best e-ink results:

• Use high-contrast black/white design
• Avoid gradients and anti-aliasing
• Use bold, sans-serif fonts (min 14px)
• Keep layouts simple with clear hierarchy
• Test with actual device (screens vary)

Example Template Structure

<!DOCTYPE html>
<html>
<head>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      width: 800px;
      height: 480px;
      font-family: system-ui, sans-serif;
      background: white;
      color: black;
      padding: 24px;
    }
    h1 { font-size: 48px; font-weight: 900; }
    .content { font-size: 18px; }
  </style>
</head>
<body>
  <h1>TITLE</h1>
  <div class="content">Content here</div>
</body>
</html>

Upload API

Plugin Image Endpoint

curl -X POST --data-binary @image.png \
  -H 'Content-Type: image/png' \
  'https://usetrmnl.com/api/plugin_settings/{PLUGIN_UUID}/image'

Response on success:

{"data":{"message":"Image uploaded successfully"}}

Finding Plugin UUID

1. Go to TRMNL dashboard
2. Navigate to your plugin settings
3. UUID is in the URL: /plugin_settings/{UUID}

Verification

Check image properties with ImageMagick:

magick identify -verbose output.png | grep -E "(Geometry|Depth|Colors|Type)"

Expected output:

Geometry: 800x480+0+0
Type: Bilevel
Depth: 1-bit
Colors: 2

Common Issues