Management Overview

The ESL MQTT API provides comprehensive device management capabilities, from initial provisioning to ongoing maintenance and monitoring. This guide covers all aspects of ESL device lifecycle management.

Key Management Areas:
  • Device provisioning and registration
  • Configuration management
  • Content updates and scheduling
  • Health monitoring and maintenance
  • Firmware updates
  • Lifecycle management

ESL Device Types

📱 WiFi ESL

Model: ESL-W Series

Connectivity: 802.11 b/g/n WiFi

Power: Rechargeable battery or external power

Update Frequency: Real-time

Best For: High-value items, dynamic pricing

Features:

  • Direct Internet connectivity
  • Instant updates
  • Built-in web server
  • OTA firmware updates

📟 BLE ESL

Model: ESL-B Series

Connectivity: Bluetooth 5.0+

Power: CR2450 coin cell (4+ years)

Update Frequency: Scheduled

Best For: Mass deployment, standard pricing

Features:

  • Ultra-low power consumption
  • Gateway-routed communication
  • Scheduled wake cycles
  • Cost-effective

Display Specifications

Size Model Resolution Colors Viewing Angle Typical Application
2.13" ZKC213 250 × 122 B/W/R/Y 180° Small items, shelf strips
2.9" ZKC29B-E4 296 × 128 B/W/R/Y 180° Standard price tags
3.5" ZKC35 384 × 240 B/W/R/Y 180° Medium displays, detailed product info
3.7" ZKC37 480 × 280 B/W/R/Y 180° Enhanced product displays, promotions
4.2" ZKC42 400 × 300 B/W/R/Y 180° Feature products, promotions
7.5" ZKC75 800 × 480 B/W/R/Y 180° Department signs, info displays

Device Provisioning

Provisioning Workflow

1

Unboxing & Power On

Device enters provisioning mode automatically on first boot

2

Network Discovery

WiFi: AP mode for configuration
BLE: Advertising for pairing

3

Initial Configuration

Set device ID, network credentials, server details

4

Registration

Device registers with server and receives initial configuration

5

First Render

Display test pattern or assigned content

Provisioning Messages

Device Registration Request

{ "api_version": "1.0", "message_id": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2025-05-27T10:30:00.000Z", "source": "ESL_NEW_001", "destination": "server", "type": "registration_request", "payload": { "device_info": { "model": "ZKC29B-E4", "firmware_version": "2.1.0", "hardware_version": "1.0", "serial_number": "SN2025052700001", "capabilities": { "display": { "size": "2.9", "resolution": "296x128", "colors": ["white", "black", "red", "yellow"] }, "connectivity": ["ble"], "sensors": ["temperature", "battery"], "features": ["partial_update", "low_power_mode"] } }, "network_info": { "connection_type": "ble", "gateway_id": "GW-MESH-001", "signal_strength": -65 } } }

Registration Response

{ "api_version": "1.0", "message_id": "660e8400-e29b-41d4-a716-446655440001", "timestamp": "2025-05-27T10:30:01.000Z", "source": "server", "destination": "ESL_NEW_001", "type": "registration_response", "payload": { "status": "success", "device_id": "ESL_BLE_001", "configuration": { "display_settings": { "orientation": "landscape", "refresh_mode": "full", "power_save_enabled": true }, "schedule": { "wake_times": ["08:00", "12:00", "18:00"], "timezone": "UTC", "slot_offset_ms": 0 }, "server_endpoints": { "primary": "mqtt://server.example.com:1883", "backup": "mqtt://backup.example.com:1883" } } } }

Bulk Provisioning

For large deployments, use CSV import or automated provisioning:

serial_number,device_id,location,gateway_id,wake_schedule SN2025052700001,ESL_BLE_001,Aisle-1-Shelf-A,GW-MESH-001,standard SN2025052700002,ESL_BLE_002,Aisle-1-Shelf-B,GW-MESH-001,standard SN2025052700003,ESL_BLE_003,Aisle-2-Shelf-A,GW-MESH-002,frequent SN2025052700004,ESL_WIFI_001,Entrance-Display,direct,realtime

Configuration Management

Display Configuration

Update Display Settings

{ "type": "config_update", "payload": { "display_settings": { "orientation": "landscape", "brightness": 100, "contrast": 50, "refresh_mode": "partial", "dithering_enabled": true, "color_mapping": { "white": 0, "black": 1, "red": 2, "yellow": 3 }, "power_save_settings": { "enabled": true, "idle_timeout_minutes": 30, "deep_sleep_enabled": true } } } }

Display Modes

Mode Description Power Usage Update Speed
Full Refresh Complete screen update, best quality High 2-3 seconds
Partial Update Update changed regions only Medium 0.5-1 second
Fast Mode Quick update, may have ghosting Low <0.5 second
Ultra Low Power Minimal updates, maximum battery Minimal 3-5 seconds

Network Configuration

WiFi ESL Network Settings

{ "type": "config_update", "payload": { "network_settings": { "wifi": { "ssid": "ESL-Network", "password": "encrypted_password", "security": "WPA2-PSK", "channel": "auto", "power_save": "enabled" }, "mqtt": { "broker_url": "mqtt://server.example.com:1883", "username": "esl_device", "password": "encrypted_password", "keep_alive": 60, "qos": 1, "clean_session": true }, "fallback": { "ap_mode_timeout": 300, "retry_count": 3, "retry_delay": 5000 } } } }

BLE ESL Gateway Assignment

{ "type": "gateway_assignment", "payload": { "primary_gateway": "GW-MESH-001", "backup_gateways": ["GW-MESH-002", "GW-MAIN-001"], "connection_params": { "advertising_interval": 1000, "connection_interval": 50, "slave_latency": 4, "supervision_timeout": 4000 } } }

Schedule Configuration

Wake Schedule Templates

🏪 Retail Standard

{ "name": "retail_standard", "wake_times": ["06:00", "09:00", "12:00", "15:00", "18:00", "21:00"], "business_hours": { "open": "08:00", "close": "22:00" } }

🏢 Office Hours

{ "name": "office_hours", "wake_times": ["08:00", "12:00", "17:00"], "weekend_schedule": { "enabled": false } }

🏥 24/7 Operations

{ "name": "always_on", "wake_times": ["00:00", "04:00", "08:00", "12:00", "16:00", "20:00"], "night_mode": { "reduced_frequency": false } }

Custom Schedule Definition

{ "type": "schedule_update", "payload": { "schedule": { "type": "custom", "timezone": "America/New_York", "regular_schedule": { "monday": ["08:00", "12:00", "18:00"], "tuesday": ["08:00", "12:00", "18:00"], "wednesday": ["08:00", "12:00", "15:00", "18:00"], "thursday": ["08:00", "12:00", "18:00"], "friday": ["08:00", "11:00", "14:00", "17:00", "20:00"], "saturday": ["09:00", "13:00", "17:00", "21:00"], "sunday": ["10:00", "14:00", "18:00"] }, "special_dates": { "2025-12-24": ["08:00", "10:00", "12:00", "14:00", "16:00"], "2025-12-25": ["12:00"] } } } }

Advanced Configuration

Sensor Settings

{ "type": "config_update", "payload": { "sensor_config": { "temperature": { "enabled": true, "reporting_interval": 3600, "thresholds": { "low": 0, "high": 40, "alert_on_breach": true } }, "battery": { "low_threshold": 20, "critical_threshold": 10, "reporting_interval": 86400 }, "motion": { "enabled": false, "sensitivity": "medium" } } } }

Debug and Diagnostics

{ "type": "config_update", "payload": { "debug_settings": { "log_level": "info", "diagnostic_mode": false, "test_patterns": { "enabled": false, "pattern": "checkerboard" }, "performance_monitoring": { "enabled": true, "metrics": ["render_time", "battery_usage", "connection_quality"] } } } }

Content Management

Content Types

💰 Price Tags

Product name, price, unit price, promotions

📊 Information Displays

Product details, specifications, QR codes

🏷️ Promotional Tags

Sale indicators, special offers, limited time

📍 Location Markers

Aisle numbers, department signs, directions

Image Preparation

Best practices for preparing images for ESL displays:

Image Guidelines:
  • Use exact display resolution (e.g., 296×128 for 2.9")
  • Limit to 4 colors: White, Black, Red, Yellow
  • Use high contrast for better readability
  • Avoid small text (<12pt equivalent)
  • Test dithering for gradients and photos

Template System

{ "template_id": "price_tag_v1", "layout": { "zones": [ { "id": "product_name", "type": "text", "bounds": { "x": 10, "y": 10, "width": 276, "height": 40 }, "style": { "font": "bold", "size": 24, "color": "black" } }, { "id": "price", "type": "text", "bounds": { "x": 10, "y": 50, "width": 150, "height": 60 }, "style": { "font": "bold", "size": 48, "color": "black" } }, { "id": "unit_price", "type": "text", "bounds": { "x": 170, "y": 70, "width": 116, "height": 20 }, "style": { "font": "regular", "size": 14, "color": "black" } }, { "id": "promo_banner", "type": "rectangle", "bounds": { "x": 0, "y": 0, "width": 296, "height": 30 }, "style": { "fill": "red", "visible": "${has_promotion}" } }, { "id": "promo_text", "type": "text", "bounds": { "x": 148, "y": 5, "width": 296, "height": 20 }, "style": { "font": "bold", "size": 16, "color": "white", "align": "center" } } ] } }

Monitoring & Maintenance

Health Monitoring

Metric Good Warning Critical Action
Battery Level >50% 20-50% <20% Schedule replacement
Signal Strength >-70 dBm -70 to -85 dBm <-85 dBm Relocate gateway/device
Update Success Rate >95% 80-95% <80% Check connectivity
Temperature 0-40°C -10-0°C, 40-50°C <-10°C, >50°C Environmental control
Last Check-in <24 hours 24-48 hours >48 hours Investigate device

Status Dashboard Example

{ "dashboard": { "total_devices": 1250, "device_status": { "online": 1205, "offline": 45, "maintenance": 12 }, "battery_status": { "good": 1100, "low": 125, "critical": 25 }, "recent_alerts": [ { "device_id": "ESL_BLE_042", "type": "battery_critical", "level": 8, "timestamp": "2025-05-27T14:30:00Z" }, { "device_id": "ESL_WIFI_003", "type": "connection_lost", "last_seen": "2025-05-27T12:00:00Z" } ] } }

Maintenance Procedures

1

Regular Health Check

Query all devices for status every 24 hours

2

Battery Monitoring

Track trends and predict replacement needs

3

Display Testing

Periodic full refresh to prevent image retention

4

Firmware Updates

Roll out updates in batches during off-hours

5

Performance Analysis

Review logs and optimize configurations

Firmware Updates

Update Process

Firmware updates are critical for security, features, and bug fixes. The ESL system supports OTA (Over-The-Air) updates.

Firmware Update Message

{ "api_version": "1.0", "type": "firmware_update", "payload": { "firmware_info": { "version": "2.2.0", "release_date": "2025-05-15", "size_bytes": 524288, "checksum": "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730", "release_notes": "Bug fixes and performance improvements" }, "update_config": { "update_window": { "start": "02:00", "end": "05:00", "timezone": "local" }, "strategy": "rolling", "batch_size": 10, "retry_policy": { "max_attempts": 3, "backoff_minutes": 30 } }, "download_url": "https://updates.example.com/firmware/esl/2.2.0/esl-ble-fw-2.2.0.bin" } }

Update Strategies

Strategy Description Pros Cons
Rolling Update Update devices in small batches Safe, can halt if issues Takes longer
Canary Test on small group first Very safe, early detection Complex management
Big Bang Update all at once Fast completion Risky, hard to rollback
Scheduled Update during maintenance window Predictable, off-hours Fixed timing

Management Best Practices

🚀 Deployment

  • Plan network coverage before deployment
  • Use consistent naming conventions
  • Document device locations
  • Test in small batches first

🔧 Operations

  • Monitor battery levels proactively
  • Schedule updates during off-hours
  • Keep firmware up to date
  • Regular health checks

📊 Performance

  • Optimize wake schedules
  • Use appropriate refresh modes
  • Balance battery life vs responsiveness
  • Monitor network load

🛡️ Security

  • Use encrypted connections
  • Regular security updates
  • Implement access controls
  • Audit device access logs