Usage Examples - ESL MQTT API Documentation

Scenario Overview

This example demonstrates a bulk update operation where the server sends new 2-bit binary image data to 8 ESL devices distributed across two mesh gateways.

Scenario: Morning price update for retail store
Devices: 8 ESL devices (4 per mesh gateway)
Operation: Bulk render with staggered delivery

📚 Looking for Large-Scale Deployment?
For comprehensive examples including 1000+ ESL deployments with ultra-low power optimization and advanced caching strategies, see our Comprehensive Deployment Guide.

Network Topology

Server Layer

Server
Source of Truth

↓ Internet Connection ↓

Gateway Layer

Main Gateway
GW-MAIN-001

↓ WiFi-Mesh Network ↓

Mesh Gateways

Mesh Gateway 01
GW-MESH-001

Mesh Gateway 02
GW-MESH-002

↓ BLE Connections ↓

ESL Devices

ESL_BLE_001
ESL_BLE_002
ESL_BLE_003
ESL_BLE_004

ESL_BLE_005
ESL_BLE_006
ESL_BLE_007
ESL_BLE_008

Step-by-Step Message Flow

1

Server → Main Gateway (Bulk Operation)

Server sends bulk render command with data for all 8 devices to the main gateway

2

Main Gateway → Mesh Gateways (Distribution)

Main gateway distributes device-specific data to respective mesh gateways

3

Mesh Gateways → ESL Devices (BLE)

Each mesh gateway sends render commands to its assigned ESL devices via BLE

4

ESL Devices → Acknowledgments

ESL devices process the commands and send acknowledgments back through the chain

5

Status Reporting

Final status report is compiled and sent back to the server

Detailed Message Examples

Server → Main Gateway (Bulk Operation)

Topic: esl/v1/gateway/main/GW-MAIN-001/bulk_render

PUBLISH esl/v1/gateway/main/GW-MAIN-001/bulk_render

{
  "api_version": "1.0",
  "message_id": "bulk-render-001",
  "timestamp": "2025-05-27T14:00:00.000Z",
  "source": "server",
  "destination": "GW-MAIN-001",
  "type": "bulk_render",
  "connection_info": {
    "route": "direct_internet",
    "connection_type": "internet"
  },
  "payload": {
    "operation_id": "morning-price-update",
    "total_devices": 8,
    "mesh_distribution": {
      "GW-MESH-001": ["ESL_BLE_001", "ESL_BLE_002", "ESL_BLE_003", "ESL_BLE_004"],
      "GW-MESH-002": ["ESL_BLE_005", "ESL_BLE_006", "ESL_BLE_007", "ESL_BLE_008"]
    },
    "batch_config": {
      "batch_size": 2,
      "retry_policy": {
        "max_retries": 3,
        "retry_delay": 5000
      }
    },
    "common_config": {
      "display_size": "2.9",
      "refresh_times": ["08:00", "12:00", "18:00"],
      "encoding": "base64_2bit"
    },
    "device_data": {
      "ESL_BLE_001": {
        "image_data": {
          "width": 296,
          "height": 128,
          "data": "Gx5kMnQ7...",
          "checksum": "sha256:abc001..."
        }
      },
      "ESL_BLE_002": {
        "image_data": {
          "width": 296,
          "height": 128,
          "data": "Hx6lNoR8...",
          "checksum": "sha256:abc002..."
        }
      }
    }
  }
}
                        

Main Gateway → Mesh Gateway 01

Topic: esl/v1/mesh/GW-MESH-001/batch_render

{
  "api_version": "1.0",
  "message_id": "mesh-batch-001",
  "timestamp": "2025-05-27T14:00:05.000Z",
  "source": "GW-MAIN-001",
  "destination": "GW-MESH-001",
  "type": "batch_render",
  "connection_info": {
    "route": "wifi_mesh",
    "connection_type": "wifi_mesh",
    "original_source": "server"
  },
  "payload": {
    "operation_id": "morning-price-update",
    "parent_message_id": "bulk-render-001",
    "assigned_devices": ["ESL_BLE_001", "ESL_BLE_002", "ESL_BLE_003", "ESL_BLE_004"],
    "batch_config": {
      "batch_size": 2,
      "ble_timeout": 60000
    },
    "device_data": {
      "ESL_BLE_001": {
        "image_data": {
          "width": 296,
          "height": 128,
          "data": "Gx5kMnQ7...",
          "checksum": "sha256:abc001..."
        }
      },
      "ESL_BLE_002": {
        "image_data": {
          "width": 296,
          "height": 128,
          "data": "Hx6lNoR8...",
          "checksum": "sha256:abc002..."
        }
      }
    }
  }
}
                        

Mesh Gateway → ESL Device

Topic: esl/v1/ble/mesh/ESL_BLE_001/render_command

{
  "api_version": "1.0",
  "message_id": "esl-render-001",
  "timestamp": "2025-05-27T14:00:10.000Z",
  "source": "GW-MESH-001",
  "destination": "ESL_BLE_001",
  "type": "render_command",
  "connection_info": {
    "route": "via_mesh_gateway",
    "connection_type": "ble",
    "gateway_id": "GW-MESH-001",
    "original_source": "server"
  },
  "payload": {
    "operation_id": "morning-price-update",
    "parent_message_id": "mesh-batch-001",
    "display_config": {
      "size": "2.9",
      "orientation": "landscape",
      "refresh_rate": "low_power"
    },
    "schedule": {
      "immediate": true,
      "refresh_times": ["08:00", "12:00", "18:00"],
      "timezone": "UTC"
    },
    "image_data": {
      "encoding": "base64_2bit",
      "width": 296,
      "height": 128,
      "data": "Gx5kMnQ7...",
      "checksum": "sha256:abc001..."
    }
  }
}
                        

ESL Device → Acknowledgment

Topic: esl/v1/ble/mesh/ESL_BLE_001/render_ack

{
  "api_version": "1.0",
  "message_id": "ack-001",
  "in_response_to": "esl-render-001",
  "timestamp": "2025-05-27T14:00:45.000Z",
  "source": "ESL_BLE_001",
  "destination": "GW-MESH-001",
  "type": "render_acknowledgment",
  "connection_info": {
    "route": "via_mesh_gateway",
    "connection_type": "ble",
    "gateway_id": "GW-MESH-001"
  },
  "payload": {
    "operation_id": "morning-price-update",
    "status": "success",
    "execution_time": 35000,
    "device_status": {
      "battery_level": 92,
      "signal_strength": -38,
      "display_updated": true,
      "next_wake_time": "2025-05-27T16:00:00.000Z"
    },
    "checksum_verified": true,
    "errors": []
  }
}
                        

Device Status Tracking

Monitor the status of all devices involved in the bulk operation.

ESL_BLE_001 Online

Gateway: GW-MESH-001

Battery: 92%

Signal: -38 dBm

Last Update: 14:00:45

ESL_BLE_002 Online

Gateway: GW-MESH-001

Battery: 88%

Signal: -42 dBm

Last Update: 14:01:12

ESL_BLE_005 Sleeping

Gateway: GW-MESH-002

Battery: 95%

Next Wake: 16:00:00

Last Update: 14:02:30

ESL_BLE_008 Offline

Gateway: GW-MESH-002

Battery: 23%

Issue: Low Battery

Last Seen: 13:45:00

Error Handling Examples

Device Offline Error

{
  "api_version": "1.0",
  "message_id": "error-001",
  "in_response_to": "esl-render-008",
  "timestamp": "2025-05-27T14:03:00.000Z",
  "source": "GW-MESH-002",
  "destination": "server",
  "type": "error",
  "error": {
    "code": "DEVICE_OFFLINE",
    "message": "ESL_BLE_008 is not reachable - device may be in deep sleep or battery depleted",
    "details": {
      "device_id": "ESL_BLE_008",
      "last_seen": "2025-05-27T13:45:00.000Z",
      "battery_level": 23,
      "retry_attempts": 3,
      "suggested_action": "Check device battery and physical location"
    }
  }
}
                

Checksum Mismatch Error

{
  "api_version": "1.0",
  "message_id": "error-002",
  "in_response_to": "esl-render-003",
  "timestamp": "2025-05-27T14:01:30.000Z",
  "source": "ESL_BLE_003",
  "destination": "GW-MESH-001",
  "type": "error",
  "error": {
    "code": "CHECKSUM_MISMATCH",
    "message": "Image data checksum verification failed",
    "details": {
      "expected_checksum": "sha256:abc003...",
      "received_checksum": "sha256:def003...",
      "data_size": 9472,
      "corruption_detected": true,
      "suggested_action": "Retransmit image data"
    }
  }
}
                

Performance Metrics

Metric	Value	Target	Status
Total Operation Time	3 minutes 45 seconds	< 5 minutes	Good
Success Rate	87.5% (7/8 devices)	> 95%	Below Target
Average Response Time	35 seconds	< 60 seconds	Good
Network Efficiency	92%	> 90%	Good

Note: ESL_BLE_008 failed due to low battery (23%). Consider implementing battery monitoring alerts for proactive maintenance.