ESL MQTT API Documentation Hub

System Overview

🌐

Network Architecture

Unified MQTT API supporting WiFi and BLE connections through mesh gateways

Learn More →

📱

ESL Management

2-bit color displays with proper error handling and versioning

Learn More →

⚡

Sleep/Wake Protocol

Efficient power management with scheduled wake-up cycles

Learn More →

🔧

API Examples

Real-world scenarios and implementation examples

Learn More →

Quick Start Guide

1

Setup Gateway

Configure your main gateway with Internet connectivity

2

Connect ESLs

Pair ESL devices via WiFi or BLE connections

3

Send Commands

Use MQTT topics to send render commands and updates

Key Features

🔄 Dual Connectivity

Support for both WiFi and BLE ESL devices

🎨 2-bit Color Display

White, Black, Red, and Yellow color support

📡 Mesh Network

Scalable mesh gateway architecture

⏰ Scheduled Updates

Automatic refresh at configured times

🔒 Security

Message validation and checksum verification

🔧 Firmware Updates

Over-the-air firmware update capability

🎨 Color Mapping & Display Specifications

Our ESL system uses an efficient 2-bit color encoding that provides optimal visual impact while maintaining excellent battery life and fast refresh rates.

2-bit Color Encoding

Binary	Hex	Color	Usage
`00`	`0`	White	Background, empty space
`01`	`1`	Black	Text, outlines, borders
`10`	`2`	Red	Sale prices, alerts, branding
`11`	`3`	Yellow	Highlights, special offers

Supported Display Sizes

2.13" ESL

Resolution: 250 × 122 pixels

Total Pixels: 30,500

Use Case: Small price tags, shelf strips

2.9" ESL

Resolution: 296 × 128 pixels

Total Pixels: 37,888

Use Case: Standard price tags (most common)

3.5" ESL

Resolution: 384 × 240 pixels

Total Pixels: 92,160

Use Case: Medium displays, detailed product info

3.7" ESL

Resolution: 480 × 280 pixels

Total Pixels: 134,400

Use Case: Enhanced product displays, promotions

4.2" ESL

Resolution: 400 × 300 pixels

Total Pixels: 120,000

Use Case: Large product displays, promotions

7.5" ESL

Resolution: 800 × 480 pixels

Total Pixels: 384,000

Use Case: Department signs, large promotions

Color System Benefits

🔋

Power Efficiency

75% less energy consumption compared to full-color displays, enabling 5+ year battery life

👀

High Contrast

Optimized color combinations ensure excellent readability from typical viewing distances

🏷️

Retail Optimized

Colors specifically chosen for retail environments - red for sales, yellow for promotions

⚡

Fast Refresh

2-bit encoding enables faster display updates (2-3 seconds vs 5-8 seconds for full color)

🏷️ Real-World Example: Premium Organic Coffee Sale

📦 Product: Starbucks Pike Place Roast Organic Ground Coffee

Regular Price: $12.99 → Sale Price: $9.99 (23% OFF)

Display Size: 2.9" ESL (296×128 pixels) | ESL ID: ESL_A3_047

Update Trigger: Flash Sale starts at 9:00 AM

🎨 Visual Layout Breakdown

RED Banner (Top 25 pixels)

Company Logo Area + "FLASH SALE" text

WHITE Background (Main area)

Product name, description, original price

BLACK Text

Product details, barcode, expiry info

YELLOW Price Banner (Bottom 30 pixels)

Sale price "$9.99" + savings "SAVE $3.00"

Exact Pixel Allocation (296×128):

Rows 1-25: RED Company branding + "FLASH SALE" banner

Rows 26-85: WHITE + BLACK Product name, description, original price strikethrough

Rows 86-115: BLACK Barcode, SKU: 012000161919, Exp: 12/2025

Rows 116-128: YELLOW Large "$9.99" + "SAVE $3.00" text

📡 Complete MQTT Message Payload

MQTT Topic: esl/render/ESL_A3_047

{
  "message_id": "MSG_20241215_090001_047",
  "timestamp": "2024-12-15T09:00:01.345Z",
  "esl_id": "ESL_A3_047",
  "gateway_id": "GW_STORE_001_MAIN",
  "action": "render",
  "priority": "high",
  "data": {
    "product": {
      "name": "Starbucks Pike Place Roast Organic",
      "description": "Ground Coffee, Medium Roast, 12oz",
      "sku": "012000161919",
      "barcode": "012000161919",
      "category": "Coffee & Tea",
      "brand": "Starbucks",
      "size": "12 oz (340g)",
      "expiry_date": "2025-12-31"
    },
    "pricing": {
      "regular_price": 12.99,
      "sale_price": 9.99,
      "discount_percent": 23,
      "savings": 3.00,
      "currency": "USD",
      "promotion": "FLASH_SALE_ORGANIC",
      "valid_until": "2024-12-15T18:00:00Z"
    },
    "display": {
      "template": "sale_template_v2",
      "width": 296,
      "height": 128,
      "rotation": 0,
      "refresh_mode": "fast",
      "partial_update": false
    },
    "image_data": {
      "encoding": "base64_2bit",
      "compression": "none",
      "color_mapping": {
        "white": 0,
        "black": 1,
        "red": 2,
        "yellow": 3
      },
      "raw_size_bytes": 9472,
      "encoded_size_bytes": 12598,
      "data": "iVBORw0KGgoAAAANSUhEUgAAAEgAAAAgCAYAAACqW...
              [Base64 encoded 2-bit image data - 12,598 bytes]
              ...WJGmE2ZlNmdzZlY2Y0NmUjZlM2ZSNmUTZlA2YwN2X"
    },
    "metadata": {
      "update_reason": "price_change_promotion",
      "store_section": "Coffee & Beverages - Aisle 3",
      "shelf_position": "A3-047",
      "last_sync": "2024-12-15T08:59:45Z",
      "checksum": "sha256:a8f5f167f44f4964e6c998dee827110c",
      "version": "2.1.3"
    }
  },
  "settings": {
    "wake_time": "2024-12-15T09:00:00Z",
    "sleep_duration": 3600,
    "retry_attempts": 3,
    "timeout_seconds": 30,
    "ack_required": true
  }
}

📊 Storage & Performance Analysis

💾

Storage Impact

Raw 2-bit image: 9,472 bytes
Base64 encoded: 12,598 bytes
JSON metadata: 3,247 bytes
Total ESL payload: ~15.8 KB
Gateway storage: ~18 KB (with indexing)

📡

Transmission Details

MQTT payload size: 15,845 bytes
WiFi transmission: ~0.8 seconds
BLE transmission: ~12 seconds (chunks)
Display refresh: 2.1 seconds
Total update time: 3-15 seconds

⚡

Optimizations Applied

Template system: Reuse layout structure
Differential update: Only price area changes
Fast refresh mode: Skip full clear cycle
Compression: 40% size reduction possible
Caching: Store on gateway for retries

🔢 2-bit Encoding Process

1

Pixel Assignment

296×128 = 37,888 pixels total

White: 18,944 pixels (50%)

Black: 11,366 pixels (30%)

Red: 4,733 pixels (12.5%)

Yellow: 2,845 pixels (7.5%)

2

Binary Packing

4 pixels per byte:

White(00) Black(01) Red(10) Yellow(11) = 00011011 (0x1B)

Total bytes: 37,888 ÷ 4 = 9,472 bytes

3

Base64 Encoding

9,472 bytes × 1.33 = 12,598 characters

iVBORw0KGgoAAAANSUhEUgAAAEgAAAAgCAYAAACqW...

🛠️ Implementation Considerations

⏰ Timing Coordination

ESLs wake at scheduled times (9:00 AM) to receive flash sale updates. Gateway queues messages for optimal delivery timing.

🔄 Retry Logic

Failed transmissions retry up to 3 times with exponential backoff. Critical sale prices have higher retry priority.

✅ Validation

ESL confirms receipt with ACK containing checksum verification. Mismatched checksums trigger automatic retry.

💾 Backup Storage

Gateway maintains 24-hour cache of all ESL states for rapid recovery and comparison during price audits.

📋 ESL Storage Requirements Summary

Quick Reference Guide: Essential storage calculations and memory requirements for ESL gateway planning and deployment.

📊 2-bit Image Sizes (per ESL)

Display Size	Resolution	Raw Image	With Metadata	Total per ESL
2.13"	250 × 122	7,625 bytes	+4.5 KB	~12 KB
2.9"	296 × 128	9,472 bytes	+5.5 KB	~15 KB
3.5"	384 × 240	23,040 bytes	+12 KB	~35 KB
3.7"	480 × 280	33,600 bytes	+16.5 KB	~50 KB
4.2"	400 × 300	30,000 bytes	+15 KB	~45 KB
7.5"	800 × 480	96,000 bytes	+44 KB	~140 KB

🏪 Gateway Flash Memory Requirements

Store Size	ESL Count	Storage Needed	Recommended Flash
Small Store	100 ESLs	2 MB	8 MB
Medium Store	500 ESLs	8.5 MB	32 MB
Large Store	2,000 ESLs	40 MB	128 MB
Enterprise	10,000+ ESLs	220 MB	512 MB - 1 GB

🔢 How 2-bit Calculation Works

📦

Pixel Packing

4 pixels = 1 byte (each pixel = 2 bits)

🔤

Encoding Overhead

Base64 encoding adds 33% overhead

📝

Metadata Size

JSON metadata adds ~3-5 KB per ESL

🛡️

Safety Buffer

3-4x actual needs recommended

🚀 Storage Optimizations

🗜️ GZIP Compression

60-80% size reduction

♻️ Differential Updates

90% savings for price changes

📦 Template System

50% reduction for similar products

🔄 LRU Caching

Faster access for frequent updates

📡 Gateway Memory Recommendations

🌐

Main Gateway

128 MB Flash + 32 MB RAM

Supports up to 5,000 ESLs

📡

Mesh Gateway

32 MB Flash + 8 MB RAM

Supports up to 200 ESLs

🎯

Key Takeaway

For a typical 2,000 ESL store, your main gateway needs approximately 40 MB of actual storage, so 128 MB Flash provides a comfortable 3x safety buffer for system operations, firmware updates, and future expansion!

System Overview

Network Architecture

ESL Management

Sleep/Wake Protocol

API Examples

Quick Start Guide

Setup Gateway

Connect ESLs

Send Commands

Key Features

🔄 Dual Connectivity

🎨 2-bit Color Display

📡 Mesh Network

⏰ Scheduled Updates

🔒 Security

🔧 Firmware Updates

🎨 Color Mapping & Display Specifications

2-bit Color Encoding

Supported Display Sizes

2.13" ESL

2.9" ESL

3.5" ESL

3.7" ESL

4.2" ESL

7.5" ESL

Color System Benefits

Power Efficiency

High Contrast

Retail Optimized

Fast Refresh

🏷️ Real-World Example: Premium Organic Coffee Sale

📦 Product: Starbucks Pike Place Roast Organic Ground Coffee

🎨 Visual Layout Breakdown

Exact Pixel Allocation (296×128):

📡 Complete MQTT Message Payload

📊 Storage & Performance Analysis

Storage Impact

Transmission Details

Optimizations Applied

🔢 2-bit Encoding Process

Pixel Assignment

Binary Packing

Base64 Encoding

🛠️ Implementation Considerations

⏰ Timing Coordination

🔄 Retry Logic

✅ Validation

💾 Backup Storage

📋 ESL Storage Requirements Summary

📊 2-bit Image Sizes (per ESL)

🏪 Gateway Flash Memory Requirements

🔢 How 2-bit Calculation Works

Pixel Packing

Encoding Overhead

Metadata Size

Safety Buffer

🚀 Storage Optimizations

📡 Gateway Memory Recommendations

Main Gateway

Mesh Gateway

Key Takeaway

Documentation

API Reference

System Architecture

Usage Examples

Sleep/Wake Protocol