Server-to-Hardware Communication Overview

This API covers all communication between the central server and ESL hardware (devices and gateways). Includes server commands, device responses, status reporting, and bulk operations.

Communication Patterns:
Server → Hardware: Commands, configurations, content
Hardware → Server: Status, responses, error reports
Protocol: MQTT 3.1.1/5.0 over TLS
QoS: 0 (status), 1 (commands), 2 (critical ops)

📤 Server Commands

Content & Control: Display updates and device management

  • Display rendering commands
  • Configuration updates
  • Firmware distribution
  • Bulk operations

📥 Device Responses

Status & Feedback: Health and operation confirmations

  • Render confirmations
  • Health status reports
  • Error notifications
  • Performance metrics

🌐 Gateway Operations

Infrastructure Management: Network coordination

  • Bulk device coordination
  • Mesh network management
  • Device discovery
  • Load balancing

🔄 Synchronization

Data Consistency: Content and configuration sync

  • Real-time price updates
  • Template distribution
  • Configuration synchronization
  • Content caching

Server-to-Hardware Message Types

🖥️ Display Commands (Server → Hardware)

RENDER_COMMAND esl/v1/wifi/direct/{device_id}/render_command
Server command to update WiFi ESL display (ESP32-S3) with new content - Direct connection
{ "message_type": "render_command", "device_id": "ESL_WIFI_ELECTRONICS_001", "priority": "normal", "qos": 1, "payload": { "display_config": { "size": "4.2", "orientation": "landscape", "refresh_mode": "normal", "color_mode": "3_color_bwr" }, "image_data": { "encoding": "base64_3bit_compressed", "width": 400, "height": 300, "data": "H4sIAAAAAAAAA+1YS2sCMRSd...", "checksum": "sha256:abc123..." }, "schedule": { "immediate": true, "scheduled_time": "2025-05-28T06:00:00.000Z" }, "product_context": { "sku": "PHONE_SAMSUNG_S24", "price": 849.99, "template_id": "electronics_premium" } } }
BLE_RENDER_COMMAND esl/v1/gateway/main/{gateway_id}/ble_render_command
Server command to update BLE ESL display (nRF52832) via gateway - Gateway-routed connection
{ "message_type": "ble_render_command", "gateway_id": "GW-MAIN-001", "target_device_id": "ESL_BLE_ELECTRONICS_001", "priority": "normal", "qos": 1, "payload": { "routing": { "mesh_gateway": "GW-MESH-001", "device_wake_schedule": "2025-05-28T06:00:00.000Z", "max_retry_attempts": 3, "timeout_seconds": 300 }, "display_config": { "size": "4.2", "orientation": "landscape", "refresh_mode": "normal", "color_mode": "3_color_bwr" }, "image_data": { "encoding": "base64_3bit_compressed", "width": 400, "height": 300, "data": "H4sIAAAAAAAAA+1YS2sCMRSd...", "checksum": "sha256:abc123..." }, "schedule": { "immediate": false, "scheduled_time": "2025-05-28T06:00:00.000Z", "power_optimized": true }, "product_context": { "sku": "PHONE_SAMSUNG_S24", "price": 849.99, "template_id": "electronics_premium" } } }
RENDER_COMPLETE esl/v1/wifi/direct/{device_id}/response/render_complete
WiFi ESL device response confirming successful display update - Direct response
{ "message_type": "render_complete", "device_id": "ESL_WIFI_ELECTRONICS_001", "correlation_id": "render-001", "timestamp": "2025-05-27T14:00:15.000Z", "payload": { "render_result": { "status": "success", "render_time_ms": 4200, "image_checksum_verified": true, "display_quality": "excellent" }, "device_state": { "battery_consumed_mah": 0.8, "temperature_during_render": 24.1, "next_scheduled_update": "2025-05-28T06:00:00.000Z" } } }
BLE_RENDER_COMPLETE esl/v1/gateway/main/{gateway_id}/response/ble_render_complete
Gateway response confirming BLE ESL device successfully updated display - Gateway-routed response
{ "message_type": "ble_render_complete", "gateway_id": "GW-MAIN-001", "source_device_id": "ESL_BLE_ELECTRONICS_001", "correlation_id": "ble-render-001", "timestamp": "2025-05-27T14:00:15.000Z", "payload": { "routing_info": { "mesh_gateway": "GW-MESH-001", "hop_count": 2, "delivery_time_ms": 8500, "wake_successful": true }, "render_result": { "status": "success", "render_time_ms": 4200, "image_checksum_verified": true, "display_quality": "excellent" }, "device_state": { "battery_consumed_mah": 0.3, "temperature_during_render": 24.1, "signal_strength": -52, "next_wake_time": "2025-05-28T06:00:00.000Z" } } }

📊 Device Status (Hardware → Server)

WIFI_STATUS_UPDATE esl/v1/wifi/direct/{device_id}/response/status_update
Regular WiFi ESL device health and status reports to server - Direct connection
{ "message_type": "wifi_status_update", "device_id": "ESL_WIFI_ELECTRONICS_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "device_info": { "firmware_version": "v1.3.2", "hardware_version": "v2.1", "model": "ER-EPD042A2-1", "display_size": "4.2", "chip_type": "ESP32-S3" }, "health_status": { "state": "online", "battery_level": 87, "wifi_signal_strength": -42, "temperature_celsius": 23.4, "humidity_percentage": 45.8, "last_refresh": "2025-05-27T13:45:00.000Z", "error_count_24h": 0 }, "connectivity": { "wifi_ssid": "Store_WiFi_5G", "ip_address": "192.168.1.105", "mqtt_broker_connected": true, "last_ping_ms": 45 }, "performance_metrics": { "average_refresh_time_ms": 4350, "successful_updates_percentage": 99.8, "last_communication": "2025-05-27T13:58:00.000Z" } } }
BLE_STATUS_UPDATE esl/v1/gateway/main/{gateway_id}/response/ble_status_update
Regular BLE ESL device health and status reports via gateway - Gateway-routed connection
{ "message_type": "ble_status_update", "gateway_id": "GW-MAIN-001", "source_device_id": "ESL_BLE_ELECTRONICS_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "routing_info": { "mesh_gateway": "GW-MESH-001", "hop_count": 2, "rssi": -52, "delivery_time_ms": 3200 }, "device_info": { "firmware_version": "v1.2.1", "hardware_version": "v1.5", "model": "ER-EPD042A2-1", "display_size": "4.2", "chip_type": "nRF52832" }, "health_status": { "state": "sleeping", "battery_level": 91, "ble_signal_strength": -52, "temperature_celsius": 23.1, "humidity_percentage": 47.2, "last_refresh": "2025-05-27T08:15:00.000Z", "error_count_24h": 0 }, "connectivity": { "connected_gateway": "GW-MESH-001", "backup_gateway": "GW-MESH-002", "last_wake_time": "2025-05-27T13:45:00.000Z", "next_scheduled_wake": "2025-05-27T14:15:00.000Z" }, "performance_metrics": { "average_refresh_time_ms": 4850, "successful_updates_percentage": 98.5, "last_communication": "2025-05-27T13:45:00.000Z", "wake_success_rate": 99.2 } } }
GATEWAY_ENVIRONMENTAL_STATUS esl/v1/gateway/main/{gateway_id}/response/environmental_status
Gateway environmental sensor data and infrastructure health reporting
{ "message_type": "gateway_environmental_status", "gateway_id": "GW-MAIN-001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "gateway_info": { "firmware_version": "v2.1.0", "hardware_version": "v3.0", "model": "ESP32-S3-DevKitC", "gateway_type": "main_gateway" }, "environmental_sensors": { "temperature_celsius": 28.5, "humidity_percentage": 52.3, "pressure_hpa": 1013.2, "air_quality_index": 45, "sensor_last_calibrated": "2025-05-20T10:00:00.000Z" }, "gateway_health": { "cpu_usage_percentage": 35, "memory_usage_percentage": 42, "storage_usage_percentage": 15, "wifi_signal_strength": -38, "power_consumption_watts": 3.2, "uptime_hours": 168 }, "managed_devices": { "total_connected_devices": 145, "wifi_devices": 67, "ble_devices": 78, "offline_devices": 3, "devices_with_low_battery": 5 }, "environmental_alerts": [ { "alert_type": "high_temperature", "threshold_exceeded": true, "current_value": 28.5, "threshold_value": 25.0, "severity": "warning", "triggered_at": "2025-05-27T13:45:00.000Z" } ] } }

📊 Bulk Operations (Server ↔ Gateways)

BULK_RENDER esl/v1/gateway/main/{gateway_id}/bulk_render
Server-initiated bulk update operation through gateway
{ "message_type": "bulk_render", "gateway_id": "GW-MAIN-001", "operation_id": "morning-price-update", "timestamp": "2025-05-27T06:00:00.000Z", "payload": { "batch_config": { "total_devices": 67, "batch_size": 8, "inter_batch_delay_seconds": 30 }, "mesh_distribution": { "GW-MESH-001": { "device_count": 22, "devices": ["ESL_BLE_001", "ESL_BLE_002"] } }, "retry_policy": { "max_retries": 3, "retry_delay_seconds": 60, "failure_threshold_percentage": 15 } } }

⚙️ Configuration (Server → Hardware)

CONFIG_UPDATE esl/v1/config/sync/{device_id}
Update device configuration from server
{ "message_type": "config_update", "device_id": "ESL_PRODUCE_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "power_management": { "sleep_schedule": ["22:00", "06:00"], "wake_interval_minutes": 15, "battery_saver_mode": true }, "display_settings": { "brightness": 95, "contrast": 85, "refresh_mode": "normal" }, "communication": { "heartbeat_interval_minutes": 5, "mqtt_keep_alive_seconds": 300 } } }

⚠️ Error Handling (Hardware → Server)

DEVICE_ERROR esl/v1/{connection_type}/direct/{device_id}/response/error
Device error reporting to server with diagnostic information
{ "message_type": "device_error", "device_id": "ESL_CLOTHING_042", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "error": { "error_code": "DISPLAY_REFRESH_FAILED", "severity": "high", "message": "Display refresh failed after 3 attempts", "details": { "attempted_refreshes": 3, "last_successful_refresh": "2025-05-27T08:15:00.000Z", "error_data": "temperature_out_of_range" } }, "device_state": { "battery_level": 45, "temperature_celsius": 52.3, "signal_strength": -67 }, "diagnostic_info": { "probable_cause": "overheating_due_to_direct_sunlight", "recommended_action": "relocate_device_or_add_shade", "manual_intervention_required": true } } }

📋 Server-Hardware Message Summary

Category Message Type Direction Connection Type QoS Purpose
WiFi ESL Display Commands render_command Server → WiFi ESL Direct (ESP32-S3) 1 Display content updates
partial_render_command Server → WiFi ESL Direct (ESP32-S3) 1 Fast partial updates
clear_display_command Server → WiFi ESL Direct (ESP32-S3) 1 Clear display content
BLE ESL Display Commands ble_render_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Display content updates via gateway
ble_partial_render_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Fast partial updates via gateway
ble_clear_display_command Server → Gateway → BLE ESL Gateway-routed (nRF52832) 1 Clear display content via gateway
WiFi ESL Status Reports wifi_status_update WiFi ESL → Server Direct (ESP32-S3) 0 Device health reporting
heartbeat WiFi ESL → Server Direct (ESP32-S3) 0 Connectivity confirmation
render_complete WiFi ESL → Server Direct (ESP32-S3) 1 Update completion confirmation
BLE ESL Status Reports ble_status_update BLE ESL → Gateway → Server Gateway-routed (nRF52832) 0 Device health reporting via gateway
ble_heartbeat BLE ESL → Gateway → Server Gateway-routed (nRF52832) 0 Connectivity confirmation via gateway
ble_render_complete BLE ESL → Gateway → Server Gateway-routed (nRF52832) 1 Update completion confirmation via gateway
Bulk Operations bulk_render Server → Gateway Gateway coordination 2 Multi-device coordination
bulk_status Gateway → Server Gateway coordination 1 Bulk operation progress
Configuration config_update Server → ESL Device-specific routing 2 Device configuration changes
firmware_update Server → ESL Device-specific routing 2 Firmware distribution
Error Handling device_error ESL → Server Device-specific routing 1 Error reporting
recovery_command Server → ESL Device-specific routing 2 Recovery procedures
🔄 Communication Flow Summary:
  • WiFi ESL devices (ESP32-S3): Direct bidirectional communication with server
  • BLE ESL devices (nRF52832): All communication routed through gateways
  • Main Gateways (ESP32-S3): Bridge server commands to BLE mesh network
  • Mesh Gateways (ESP32-C3): Extend BLE coverage and route through main gateway