Hardware-to-Hardware Communication Overview

This API covers local mesh communication between ESL devices, gateways, and mesh network coordination. These messages enable autonomous device management, peer-to-peer updates, and distributed network operations within the local BLE mesh network.

⚠️ Local Mesh Communication Only:
This section covers BLE mesh network communication. BLE ESL devices (nRF52832) cannot communicate directly with the server - all server communication must go through gateways as documented in the Server-to-Hardware API.
Communication Types:
Gateway-to-BLE Device: Local gateway device management (ESP32-S3/C3 → nRF52832)
BLE Device-to-BLE Device: Direct peer communication within BLE mesh (nRF52832 ↔ nRF52832)
Gateway-to-Gateway: Mesh network coordination (ESP32-S3 ↔ ESP32-C3)
Protocol: BLE 5.0 mesh with local MQTT coordination

📡 Local Mesh Gateway Network

Distributed Control: Local BLE device management

  • BLE ESL device coordination (nRF52832)
  • Local message routing within mesh
  • Offline operation support
  • Power-optimized scheduling

🔗 BLE Device-to-Device

Peer Communication: Direct BLE ESL interaction

  • Content synchronization (nRF52832 ↔ nRF52832)
  • Status sharing within mesh
  • Collective updates
  • Emergency coordination

⚡ Power Optimization

Battery-Aware Messaging: 4+ year battery life target

  • Sleep cycle coordination
  • Batch message handling
  • Priority-based wake-up
  • Energy-efficient BLE routing

🛡️ Mesh Resilience

Fault Tolerance: Self-healing BLE network

  • Automatic failover between gateways
  • Alternative routing within mesh
  • Network health monitoring
  • Graceful degradation

Hardware-to-Hardware Message Types

🌐 Gateway-to-Device Communications

LOCAL_RENDER esl/v1/mesh/{gateway_id}/local/{device_id}/render
Gateway-initiated local rendering without server involvement
{ "message_type": "local_render_command", "gateway_id": "GW-MESH-001", "device_id": "ESL_BLE_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "source": "local_cache", "cache_id": "cached_content_001", "render_priority": "normal", "power_aware": true, "display_data": { "encoding": "compressed_rle", "width": 400, "height": 300, "data": "eAP/IlbcAA==...", "checksum": "sha256:abc123..." }, "coordination": { "batch_id": "mesh_batch_001", "sequence_number": 1, "total_in_batch": 5, "delay_ms": 2000 } } }
WAKE_SCHEDULE esl/v1/mesh/{gateway_id}/wake/{device_id}
Coordinate device wake schedules for power optimization
{ "message_type": "wake_schedule_command", "gateway_id": "GW-MESH-001", "device_id": "ESL_BLE_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "wake_plan": { "next_wake_time": "2025-05-27T14:15:00.000Z", "wake_duration_seconds": 30, "wake_reason": "scheduled_update", "priority": "normal" }, "coordination": { "group_wake": true, "group_devices": ["ESL_BLE_002", "ESL_BLE_003"], "stagger_delay_ms": 500, "power_budget_ma": 50 }, "backup_schedule": { "fallback_wake_time": "2025-05-27T14:30:00.000Z", "emergency_wake_conditions": ["low_battery", "critical_update"] } } }
MESH_CONFIG esl/v1/mesh/{gateway_id}/config/{device_id}
Local mesh network configuration and optimization
{ "message_type": "mesh_config_update", "gateway_id": "GW-MESH-001", "device_id": "ESL_BLE_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "mesh_parameters": { "channel": 37, "tx_power_dbm": 0, "connection_interval_ms": 1000, "supervision_timeout_ms": 6000 }, "routing_config": { "preferred_gateway": "GW-MESH-001", "backup_gateways": ["GW-MESH-002", "GW-MAIN-001"], "route_discovery_enabled": true, "mesh_hop_limit": 3 }, "power_settings": { "sleep_mode": "deep_sleep", "wake_interval_minutes": 15, "adaptive_interval": true, "battery_threshold_low": 20 } } }

🔗 Device-to-Device Communications

PEER_SYNC esl/v1/peer/{source_device_id}/sync/{target_device_id}
Direct peer-to-peer content synchronization between nearby ESL devices
{ "message_type": "peer_sync", "source_device_id": "ESL_BLE_001", "target_device_id": "ESL_BLE_002", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "sync_type": "content_replication", "sync_reason": "backup_distribution", "content_metadata": { "content_id": "product_display_001", "content_type": "price_update", "last_modified": "2025-05-27T08:15:00.000Z", "checksum": "sha256:def456...", "size_bytes": 28500 }, "delivery_config": { "transmission_power": "low", "retry_count": 2, "ack_required": true, "compression_enabled": true }, "mesh_context": { "hop_count": 1, "rssi": -52, "link_quality": 85 } } }
PEER_STATUS esl/v1/peer/{device_id}/status/broadcast
Broadcast device status to nearby peers for mesh health monitoring
{ "message_type": "peer_status_broadcast", "device_id": "ESL_BLE_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "device_health": { "battery_level": 87, "signal_strength": -45, "last_successful_update": "2025-05-27T08:15:00.000Z", "error_count_24h": 0, "temperature_celsius": 23.4, "humidity_percentage": 46.1 }, "mesh_info": { "connected_gateway": "GW-MESH-001", "backup_gateway": "GW-MESH-002", "peer_devices_visible": 4, "mesh_role": "relay_node" }, "content_status": { "last_content_update": "2025-05-27T08:15:00.000Z", "pending_updates": 0, "cache_utilization": 45, "display_integrity": "good" }, "broadcast_scope": { "ttl_hops": 2, "target_neighbors": ["ESL_BLE_002", "ESL_BLE_003"], "broadcast_radius_meters": 10 } } }
COLLECTIVE_UPDATE esl/v1/peer/group/{group_id}/collective_update
Coordinate simultaneous updates across a group of related devices
{ "message_type": "collective_update", "group_id": "department_electronics", "initiator_device_id": "ESL_ELECTRONICS_001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "update_coordination": { "update_type": "department_wide_sale", "synchronization_time": "2025-05-27T14:05:00.000Z", "coordinator_device": "ESL_ELECTRONICS_001", "participant_devices": [ "ESL_ELECTRONICS_002", "ESL_ELECTRONICS_003", "ESL_ELECTRONICS_004" ] }, "content_distribution": { "distribution_method": "peer_relay", "source_content": { "template_id": "electronics_sale", "variable_data": { "sale_percentage": 25, "sale_end_time": "2025-05-30T23:59:59.000Z" } } }, "execution_plan": { "phase_1": { "action": "content_preparation", "start_time": "2025-05-27T14:00:00.000Z", "participants": "all" }, "phase_2": { "action": "synchronized_display", "start_time": "2025-05-27T14:05:00.000Z", "participants": "all" } } } }

🕸️ Inter-Gateway Mesh Communications

MESH_COORDINATION esl/v1/gateway/mesh/{source_gateway}/coord/{target_gateway}
Coordinate device management and load balancing between mesh gateways
{ "message_type": "mesh_coordination", "source_gateway_id": "GW-MESH-001", "target_gateway_id": "GW-MESH-002", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "coordination_type": "load_balancing", "device_handover": { "devices_to_transfer": [ { "device_id": "ESL_BLE_005", "current_rssi": -68, "target_rssi": -45, "handover_reason": "signal_optimization" } ], "handover_schedule": "2025-05-27T14:15:00.000Z" }, "mesh_topology": { "gateway_load": { "GW-MESH-001": { "connected_devices": 78, "cpu_usage": 65, "memory_usage": 45, "battery_devices_low": 3 }, "GW-MESH-002": { "connected_devices": 52, "cpu_usage": 42, "memory_usage": 38, "battery_devices_low": 1 } } }, "coordination_parameters": { "optimization_target": "signal_strength", "load_balance_threshold": 80, "handover_hysteresis": 5 } } }
MESH_DISCOVERY esl/v1/gateway/mesh/{gateway_id}/discovery
Mesh network topology discovery and health assessment
{ "message_type": "mesh_discovery", "gateway_id": "GW-MESH-001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "discovery_type": "network_health_scan", "scan_parameters": { "scan_duration_seconds": 30, "channel_scan": [37, 38, 39], "discovery_radius_meters": 50, "signal_threshold_dbm": -80 }, "discovered_topology": { "peer_gateways": [ { "gateway_id": "GW-MESH-002", "distance_meters": 25, "signal_strength": -42, "link_quality": 95, "shared_devices": 3 }, { "gateway_id": "GW-MAIN-001", "distance_meters": 45, "signal_strength": -55, "link_quality": 78, "role": "main_coordinator" } ], "mesh_devices": [ { "device_id": "ESL_BLE_001", "role": "relay_node", "connectivity_score": 92, "routing_capable": true } ] }, "health_assessment": { "network_coverage": 95.2, "redundancy_level": "high", "bottleneck_nodes": [], "optimization_recommendations": [ "consider_additional_gateway_at_coordinates_x45_y32" ] } } }
MESH_SYNC esl/v1/gateway/mesh/sync/broadcast
Synchronize configuration and content across the mesh gateway network
{ "message_type": "mesh_sync_broadcast", "source_gateway_id": "GW-MAIN-001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "sync_type": "configuration_update", "sync_scope": "all_mesh_gateways", "configuration_data": { "mesh_parameters": { "network_key": "encrypted_key_data", "channel_map": [37, 38, 39], "discovery_interval_minutes": 30 }, "device_policies": { "max_devices_per_gateway": 100, "handover_signal_threshold": -65, "battery_conservation_mode": true }, "content_caching": { "cache_size_mb": 16, "cache_policy": "lru_with_priority", "preload_templates": ["electronics_standard", "grocery_basic"] } }, "sync_coordination": { "sync_id": "mesh_sync_001", "apply_time": "2025-05-27T14:10:00.000Z", "confirmation_required": true, "rollback_timeout_minutes": 10 } } }

📡 Network Coordination Messages

POWER_COORDINATION esl/v1/mesh/power/coordinate
Coordinate power-aware operations across the mesh network
{ "message_type": "power_coordination", "coordinator_gateway": "GW-MESH-001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "power_optimization": { "target_operation": "bulk_content_update", "total_devices": 45, "estimated_power_budget_mah": 125, "operation_window": { "start": "2025-05-27T14:15:00.000Z", "duration_minutes": 30 } }, "device_power_status": [ { "device_id": "ESL_BLE_001", "battery_level": 87, "power_consumption_last_update_mah": 1.8, "sleep_schedule": ["22:00", "06:00"], "priority": "normal" }, { "device_id": "ESL_BLE_002", "battery_level": 23, "power_consumption_last_update_mah": 2.1, "sleep_schedule": ["21:00", "07:00"], "priority": "power_save" } ], "coordination_strategy": { "low_power_devices_first": true, "batch_size": 8, "inter_batch_delay_seconds": 45, "power_monitoring": true } } }
MESH_ROUTING esl/v1/mesh/routing/optimize
Dynamic mesh routing optimization for efficient message delivery
{ "message_type": "mesh_routing_optimization", "initiator_gateway": "GW-MAIN-001", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "routing_analysis": { "network_topology": { "total_nodes": 156, "gateway_nodes": 3, "relay_capable_devices": 23, "end_devices": 130 }, "current_routing_table": [ { "destination": "ESL_BLE_001", "next_hop": "GW-MESH-001", "hop_count": 1, "link_quality": 95, "path_reliability": 98.5 }, { "destination": "ESL_BLE_015", "next_hop": "ESL_BLE_002", "hop_count": 2, "link_quality": 87, "path_reliability": 94.2 } ] }, "optimization_targets": { "minimize_hops": true, "maximize_reliability": true, "balance_gateway_load": true, "prefer_high_battery_relays": true }, "routing_updates": [ { "device_id": "ESL_BLE_015", "old_route": ["GW-MESH-001", "ESL_BLE_002", "ESL_BLE_015"], "new_route": ["GW-MESH-002", "ESL_BLE_015"], "improvement": "reduced_hops_and_latency" } ] } }

🚨 Emergency & Recovery Communications

MESH_EMERGENCY esl/v1/mesh/emergency/broadcast
Emergency coordination for network failures and critical situations
{ "message_type": "mesh_emergency_broadcast", "source_gateway_id": "GW-MESH-001", "emergency_type": "gateway_failure", "timestamp": "2025-05-27T14:00:00.000Z", "payload": { "emergency_details": { "failed_component": "GW-MESH-002", "failure_time": "2025-05-27T13:55:00.000Z", "affected_devices": 52, "impact_level": "high", "estimated_resolution_time": "30_minutes" }, "failover_plan": { "backup_gateway": "GW-MESH-001", "device_reassignment": [ { "device_id": "ESL_BLE_020", "new_gateway": "GW-MESH-001", "migration_priority": "high" } ], "temporary_routing": { "route_through_devices": ["ESL_BLE_005", "ESL_BLE_008"], "max_hop_increase": 2 } }, "recovery_coordination": { "coordinator_gateway": "GW-MAIN-001", "recovery_steps": [ "assess_device_connectivity", "establish_backup_routes", "migrate_high_priority_devices", "monitor_network_stability" ], "success_criteria": { "min_device_connectivity": 95, "max_additional_latency_ms": 500 } } } }
RECOVERY_STATUS esl/v1/mesh/recovery/{recovery_id}/status
Recovery operation status and progress reporting
{ "message_type": "recovery_status_report", "recovery_id": "recovery_mesh_002_failure", "reporting_gateway": "GW-MESH-001", "timestamp": "2025-05-27T14:15:00.000Z", "payload": { "recovery_progress": { "status": "in_progress", "completion_percentage": 75, "elapsed_time_minutes": 15, "estimated_remaining_minutes": 5 }, "device_recovery": { "total_affected_devices": 52, "successfully_migrated": 39, "migration_in_progress": 8, "migration_failed": 3, "unreachable_devices": 2 }, "network_health": { "overall_connectivity": 92.3, "average_latency_increase_ms": 125, "new_routing_efficiency": 87.5, "power_consumption_impact": "minimal" }, "issues_encountered": [ { "device_id": "ESL_BLE_025", "issue": "unable_to_establish_backup_route", "severity": "medium", "workaround": "direct_connection_to_main_gateway" } ], "next_actions": [ "complete_remaining_device_migrations", "optimize_new_routing_paths", "schedule_failed_gateway_replacement" ] } }

📋 Hardware Message Summary

Category Message Type Direction QoS Purpose
Gateway-to-Device 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
Device-to-Device 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
Inter-Gateway mesh_coordination Gateway ↔ Gateway 2 Load balancing and handover
mesh_discovery Gateway → Mesh 1 Network topology discovery
mesh_sync_broadcast Gateway → All 2 Configuration synchronization
Network Coordination power_coordination Gateway → Mesh 1 Power-aware operation planning
mesh_routing_optimization Gateway → Mesh 1 Dynamic routing optimization
Emergency mesh_emergency_broadcast Gateway → All 2 Emergency coordination
recovery_status_report Gateway → Coordinator 1 Recovery progress tracking