API Documentation Overview

The ESL system APIs are organized into three main categories based on communication patterns. Choose the appropriate section based on your integration needs.

📚 Documentation Structure:
The APIs have been split into focused sections for easier navigation and implementation. Each section contains complete message specifications, examples, and implementation details.

🔗 Hardware-to-Hardware API

Device & Gateway Communications

  • 🌐 Gateway-to-Device messaging
  • 📡 Device-to-Device coordination
  • 🕸️ Inter-Gateway mesh networking
  • ⚡ Power-optimized operations
  • 🚨 Emergency & recovery protocols
View Hardware API →

Use Cases: ESL device firmware development, gateway software, mesh network implementation

Protocol: MQTT over BLE mesh, direct WiFi

🖥️ Server-to-Hardware API

Server Commands & Device Responses

  • 📤 Display render commands
  • 📊 Device status & health reports
  • 📋 Bulk operations coordination
  • ⚙️ Configuration management
  • ⚠️ Error handling & recovery
View Server-Hardware API →

Use Cases: Content management systems, display controllers, device monitoring

Protocol: MQTT over WiFi/Internet, secure TLS

🏢 Server-Only API

Management & Business Operations

  • 🔐 Authentication & permissions
  • 🏪 Store & product management
  • 📊 Analytics & reporting
  • 👤 User account management
  • ⚙️ System administration
View Server API →

Use Cases: Web dashboards, mobile apps, third-party integrations

Protocol: HTTP/HTTPS REST, WebSocket

Quick Reference Guide

📨 All MQTT Message Types

Hardware-to-Hardware Messages

Message Type Direction QoS Purpose
local_render_command Gateway → ESL 1 Local cached content rendering
wake_schedule_command Gateway → ESL 1 Power-optimized wake coordination
mesh_config_update Gateway → ESL 2 Local mesh network configuration
peer_sync ESL ↔ ESL 1 Direct content synchronization
peer_status_broadcast ESL → Peers 0 Mesh health monitoring
collective_update ESL → Group 1 Coordinated group operations
mesh_coordination Gateway ↔ Gateway 2 Load balancing and handover
mesh_discovery Gateway → Mesh 1 Network topology discovery
power_coordination Gateway → Mesh 1 Power-aware operation planning
mesh_emergency_broadcast Gateway → All 2 Emergency coordination

Server-to-Hardware Messages

Message Type Direction Connection Type QoS Purpose
render_command Server → WiFi ESL Direct (ESP32-S3) 1 Display content updates
ble_render_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Display content updates via gateway
partial_render_command Server → WiFi ESL Direct (ESP32-S3) 1 Fast partial updates
ble_partial_render_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Fast partial updates via gateway
clear_display_command Server → WiFi ESL Direct (ESP32-S3) 1 Clear display content
ble_clear_display_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Clear display content via gateway
config_update Server → ESL (device-specific routing) Direct or Gateway-routed 2 Device configuration changes
firmware_update Server → ESL (device-specific routing) Direct or Gateway-routed 2 Firmware distribution
bulk_render Server → Gateway Gateway coordination 2 Multi-device coordination
wifi_status_update WiFi ESL → Server Direct (ESP32-S3) 0 Device health reporting
ble_status_update BLE ESL → Gateway → Server Gateway-routed (nRF52832) 0 Device health reporting via gateway
heartbeat WiFi ESL → Server Direct (ESP32-S3) 0 Connectivity confirmation
ble_heartbeat BLE ESL → Gateway → Server Gateway-routed (nRF52832) 0 Connectivity confirmation via gateway
render_complete WiFi ESL → Server Direct (ESP32-S3) 1 Update completion confirmation
ble_render_complete BLE ESL → Gateway → Server Gateway-routed (nRF52832) 1 Update completion confirmation via gateway
device_error ESL → Server (device-specific routing) Direct or Gateway-routed 1 Error reporting

📍 MQTT Topic Structure

Topic Naming Convention:
esl/v{version}/{connection_type}/{routing}/{device_id}/{message_type}/{sub_type?}

Primary Topic Patterns

Communication Type Topic Pattern Example
Server → WiFi ESL (ESP32-S3) esl/v1/wifi/direct/{device_id}/{message_type} esl/v1/wifi/direct/ESL_WIFI_001/render_command
WiFi ESL (ESP32-S3) → Server esl/v1/wifi/direct/{device_id}/response/{message_type} esl/v1/wifi/direct/ESL_WIFI_001/response/status_update
Server → Main Gateway (ESP32-S3) esl/v1/gateway/main/{gateway_id}/{message_type} esl/v1/gateway/main/GW-MAIN-001/bulk_render
Main Gateway (ESP32-S3) → Server esl/v1/gateway/main/{gateway_id}/response/{message_type} esl/v1/gateway/main/GW-MAIN-001/response/bulk_status
Gateway → BLE ESL (nRF52832) esl/v1/mesh/{gateway_id}/local/{device_id}/{message_type} esl/v1/mesh/GW-MESH-001/local/ESL_BLE_005/render
BLE ESL (nRF52832) → Gateway esl/v1/mesh/{gateway_id}/local/{device_id}/response/{message_type} esl/v1/mesh/GW-MESH-001/local/ESL_BLE_005/response/status
BLE ESL ↔ BLE ESL (Peer-to-Peer) esl/v1/peer/{source_device_id}/sync/{target_device_id} esl/v1/peer/ESL_BLE_001/sync/ESL_BLE_002
Gateway ↔ Gateway (Mesh Coordination) esl/v1/gateway/mesh/{source_gateway}/coord/{target_gateway} esl/v1/gateway/mesh/GW-MESH-001/coord/GW-MESH-002
⚠️ Important Communication Rules:
  • WiFi ESL devices (ESP32-S3): Can connect directly to server via Internet
  • BLE ESL devices (nRF52832): MUST communicate through gateways - no direct server connection
  • Main Gateways (ESP32-S3): Bridge between server and BLE mesh network
  • Mesh Gateways (ESP32-C3): Extend BLE coverage, route through main gateway

Broadcast Topics

Broadcast Type Topic Pattern Description
All WiFi ESL devices esl/v1/broadcast/wifi/all/{message_type} Direct broadcast to all WiFi ESL devices
All BLE ESL devices esl/v1/broadcast/ble/all/{message_type} Broadcast through all gateways to BLE devices
All gateways esl/v1/broadcast/gateway/all/{message_type} Broadcast to all main and mesh gateways
Store group (WiFi) esl/v1/group/store/{store_id}/wifi/{message_type} Broadcast to WiFi ESLs in specific store
Store group (BLE via Gateway) esl/v1/group/store/{store_id}/ble/{message_type} Broadcast to BLE ESLs via store gateways
Department group (WiFi) esl/v1/group/department/{dept_id}/wifi/{message_type} Broadcast to WiFi ESLs in specific department
Department group (BLE via Gateway) esl/v1/group/department/{dept_id}/ble/{message_type} Broadcast to BLE ESLs via department gateways
Emergency (All devices) esl/v1/emergency/{severity}/{message_type} Emergency broadcasts with priority routing through all paths

🎨 Display & Color Reference

Featured Display: ER-EPD042A2-1

🏷️ Recommended Model: ER-EPD042A2-1 - 4.2" color ESL display with ultra-low power consumption

📊 Technical Specs

  • Resolution: 400 × 300 pixels
  • Size: 84.80 × 63.60 mm
  • Colors: 3-color (B/W/R or B/W/Y)
  • Refresh: 4-5 seconds
  • Battery Life: 4+ years

🎨 Color Encoding

  • 00 (0): White - Background
  • 01 (1): Black - Text, borders
  • 10 (2): Red - Prices, alerts
  • 11 (3): Yellow - Eco-friendly

⚡ Power Features

  • Standby: ~3 µA
  • Update: ~6 mA
  • Partial Refresh: Supported
  • Temperature Sensor: I²C

🏪 Use Cases

  • B/W/R: Price tags, promotions
  • B/W/Y: Eco products, warnings
  • Partial: Real-time price updates
  • Full: Complete content refresh

🚀 Getting Started

Implementation Roadmap

1️⃣ Basic Integration

Start Here: Server-to-Hardware API

  • Implement MQTT client
  • Connect to server broker
  • Send display commands
  • Handle device responses
View Guide →

2️⃣ Device Development

Next Step: Hardware-to-Hardware API

  • ESL device firmware
  • Gateway coordination
  • Mesh networking
  • Power optimization
View Guide →

3️⃣ Management Platform

Final Step: Server-Only API

  • User authentication
  • Store management
  • Analytics dashboard
  • Business operations
View Guide →

📋 Complete System

Production Ready: All APIs integrated

  • End-to-end content delivery
  • Real-time monitoring
  • Business intelligence
  • Enterprise security
🎯 Goal Achieved! Full ESL ecosystem operational

Quick Links

Resource Description Link
Hardware-to-Hardware API Device and gateway communications View Documentation →
Server-to-Hardware API Server commands and device responses View Documentation →
Server-Only API Management and business operations View Documentation →
Architecture Overview System design and concepts View Architecture →
Getting Started Guide Setup and implementation Getting Started →