Network Topology Configuration API

Overview

This document provides comprehensive API and MQTT message structures for building maps with gateway mesh networks, MAC addresses, and location mapping in the ESL Admin system.

🎯 Key Features:

🏗️ Network Topology Configuration - Configure entire network topology directly from building map UI
📤 MQTT Configuration Messages - Send complete network configuration to main gateway
🔄 Automatic Gateway Management - Main gateway auto-discovers and configures mesh gateways
🚀 Server-Like Functionality - Main gateway acts as network server with DHCP, coordination, and management

💡 Server-Like Functionality:
The main gateway now acts like a network server that can:

Manage DHCP ranges for mesh gateways
Coordinate mesh network formation
Assign IP addresses automatically
Configure network layers and VLANs
Validate network topology
Monitor gateway health and status

🔧 MAC Address & Location Mapping:
Each gateway in the network topology includes:

MAC Address: Unique hardware identifier for network mapping and device tracking
Location Coordinates: Physical position (x, y) in meters for building map integration
Parent-Child Relationships: MAC addresses link mesh gateways to their parent gateways
Auto-Discovery: MAC addresses are automatically discovered during deployment
Manual Configuration: MAC addresses can be pre-configured for known hardware

🏗️ Network Topology Configuration API

Configure Network Topology from Building Map

POST /api/buildings/{buildingId}/network-topology/configure

Configure the entire network topology directly from the building map UI with automatic gateway discovery and configuration.

Request Body:

{
  "buildingId": "fp-001",
  "customerId": "cust-001",
  "networkConfiguration": {
    "mainGateway": {
      "id": "gw-main-001",
      "location": {
        "floorNumber": 1,
        "coordinates": {"x": 25.0, "y": 15.0, "unit": "meters"},
        "description": "Store Central Network Room"
      },
      "networkSettings": {
        "ipAddress": "192.168.1.100",
        "macAddress": "00:1A:2B:3C:4D:5E",
        "subnetMask": "255.255.255.0",
        "gateway": "192.168.1.1",
        "dnsServer": "8.8.8.8",
        "dhcpRange": {
          "start": "192.168.1.101",
          "end": "192.168.1.200"
        }
      },
      "meshSettings": {
        "meshId": "mesh-001",
        "channel": 6,
        "networkKey": "auto-generate",
        "maxDevices": 200,
        "role": "coordinator"
      }
    },
    "meshGateways": [
      {
        "id": "gw-mesh-001",
        "name": "Electronics Mesh Gateway",
        "location": {
          "floorNumber": 1,
          "coordinates": {"x": 15.0, "y": 10.0, "unit": "meters"},
          "description": "Electronics Department",
          "zone": "electronics"
        },
        "networkSettings": {
          "ipAddress": "192.168.1.101",
          "macAddress": "00:1A:2B:3C:4D:61",
          "assignmentMethod": "dhcp",
          "parentGateway": "gw-main-001",
          "parentMacAddress": "00:1A:2B:3C:4D:5E"
        },
        "meshSettings": {
          "role": "router",
          "parentId": "gw-main-001",
          "maxBleDevices": 50,
          "bleChannel": 37,
          "priority": 1
        },
        "coverage": {
          "range": 50,
          "targetDevices": 30,
          "zones": ["electronics", "accessories"]
        }
      }
    ],
    "networkLayers": {
      "layer1": {
        "name": "Core Network Layer",
        "description": "Main gateways and infrastructure",
        "gateways": ["gw-main-001"],
        "vlan": 10,
        "priority": "high"
      },
      "layer2": {
        "name": "Mesh Network Layer", 
        "description": "Department mesh gateways",
        "gateways": ["gw-mesh-001", "gw-mesh-002"],
        "vlan": 20,
        "priority": "medium"
      }
    },
    "autoConfiguration": {
      "enabled": true,
      "deploymentMode": "staged",
      "rollbackOnFailure": true,
      "validationRequired": true
    }
  }
}
                        

Response:

{
  "success": true,
  "configurationId": "config-001",
  "status": "queued",
  "message": "Network topology configuration queued for deployment",
  "deployment": {
    "totalGateways": 3,
    "deploymentStages": [
      {
        "stage": 1,
        "name": "Configure Main Gateway",
        "gateways": ["gw-main-001"],
        "estimatedTime": "2 minutes"
      },
      {
        "stage": 2,
        "name": "Deploy Mesh Gateways", 
        "gateways": ["gw-mesh-001", "gw-mesh-002"],
        "estimatedTime": "5 minutes"
      },
      {
        "stage": 3,
        "name": "Validate Network Topology",
        "gateways": ["all"],
        "estimatedTime": "3 minutes"
      }
    ]
  }
}
                        

Get Network Configuration Status

GET /api/buildings/{buildingId}/network-topology/status/{configurationId}

Monitor real-time deployment progress and status of network topology configuration.

Response:

{
  "success": true,
  "data": {
    "configurationId": "config-001",
    "status": "deploying",
    "progress": 65,
    "currentStage": 2,
    "deploymentLog": [
      {
        "timestamp": "2024-01-15T10:30:00Z",
        "stage": 1,
        "gatewayId": "gw-main-001",
        "action": "configure_network",
        "status": "completed",
        "message": "Network configuration applied successfully"
      },
      {
        "timestamp": "2024-01-15T10:32:00Z",
        "stage": 2,
        "gatewayId": "gw-mesh-001",
        "action": "join_mesh",
        "status": "in_progress",
        "message": "Connecting to mesh network..."
      }
    ],
    "failedGateways": [],
    "nextActions": [
      "Complete mesh gateway deployment",
      "Validate network connectivity",
      "Initialize device discovery"
    ]
  }
}
                        

📤 MQTT Configuration Messages to Main Gateway

Network Topology Configuration Command

{customerId}/gateways/{mainGatewayId}/config/topology Server → Main Gateway

{
  "timestamp": "2024-01-15T10:30:00Z",
  "configurationId": "config-001",
  "command": "configure_network_topology",
  "data": {
    "buildingId": "fp-001",
    "mainGateway": {
      "id": "gw-main-001",
      "role": "coordinator",
      "location": {
        "floorNumber": 1,
        "coordinates": {"x": 25.0, "y": 15.0, "unit": "meters"}
      },
      "networkConfig": {
        "ipAddress": "192.168.1.100",
        "macAddress": "00:1A:2B:3C:4D:5E",
        "subnetMask": "255.255.255.0",
        "gateway": "192.168.1.1",
        "dnsServer": "8.8.8.8",
        "dhcpRange": {
          "start": "192.168.1.101",
          "end": "192.168.1.200"
        }
      },
      "meshConfig": {
        "meshId": "mesh-001",
        "channel": 6,
        "networkKey": "generated_key_hash",
        "maxDevices": 200,
        "securityLevel": "high"
      }
    }
  }
}
                        

Main Gateway Response

{customerId}/gateways/{mainGatewayId}/config/topology/response Main Gateway → Server

{
  "timestamp": "2024-01-15T10:31:00Z",
  "configurationId": "config-001",
  "gatewayId": "gw-main-001",
  "response": "configuration_accepted",
  "data": {
    "status": "processing",
    "currentStage": 1,
    "discoveredGateways": [
      {
        "id": "gw-mesh-001",
        "macAddress": "00:1A:2B:3C:4D:61",
        "model": "ESL-GW-M500",
        "firmwareVersion": "3.1.5",
        "signalStrength": -45,
        "location": {
          "estimated": {"x": 14.8, "y": 9.9, "unit": "meters"},
          "accuracy": "high"
        },
        "status": "ready_for_config"
      }
    ],
    "networkStatus": {
      "mainGatewayConfigured": true,
      "meshNetworkInitialized": true,
      "dhcpServerActive": true,
      "availableIpAddresses": 98
    }
  }
}
                        

🏷️ MAC Address & Location Mapping

Gateway MAC Address Structure

Each gateway in the network topology includes MAC address information for unique identification and network mapping:

{
  "gateway": {
    "id": "gw-main-001",
    "macAddress": "00:1A:2B:3C:4D:5E",
    "location": {
      "floorNumber": 1,
      "coordinates": {"x": 25.0, "y": 15.0, "unit": "meters"},
      "description": "Store Central Network Room",
      "zone": "core"
    },
    "meshRelationships": {
      "parentMacAddress": null,
      "childMacAddresses": ["00:1A:2B:3C:4D:61", "00:1A:2B:3C:4D:62"],
      "role": "coordinator"
    },
    "networkMapping": {
      "ipAddress": "192.168.1.100",
      "subnetMask": "255.255.255.0",
      "dhcpRange": {
        "start": "192.168.1.101",
        "end": "192.168.1.200"
      }
    }
  }
}
                

Location-to-MAC Address Mapping

The system maintains a mapping between physical locations and MAC addresses for building map integration:

{
  "locationMapping": {
    "buildingId": "fp-001",
    "floorNumber": 1,
    "gateways": [
      {
        "macAddress": "00:1A:2B:3C:4D:5E",
        "coordinates": {"x": 25.0, "y": 15.0},
        "zone": "core",
        "role": "main"
      },
      {
        "macAddress": "00:1A:2B:3C:4D:61",
        "coordinates": {"x": 15.0, "y": 10.0},
        "zone": "electronics",
        "role": "mesh",
        "parentMac": "00:1A:2B:3C:4D:5E"
      }
    ]
  }
}
                

🗺️ Gateway Mapping API

Get Gateway Network Topology

GET /api/gateways/network-topology

Retrieve complete network topology including all gateways, mesh connections, and device mappings.

Query Parameters:

customerId (optional): Filter by customer ID
buildingId (optional): Filter by building/floor plan ID
includeOffline (optional): Include offline gateways (default: true)

Response Sample:

{
  "success": true,
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "topology": {
      "mainGateways": [
        {
          "id": "gw-main-001",
          "name": "Main Gateway - Store Central",
          "customerId": "cust-001",
          "location": {
            "buildingId": "fp-001",
            "floorNumber": 1,
            "coordinates": {
              "x": 25.0,
              "y": 15.0,
              "unit": "meters"
            },
            "description": "Store Central Network Room"
          },
          "network": {
            "ipAddress": "192.168.1.100",
            "macAddress": "00:1A:2B:3C:4D:5E",
            "subnetMask": "255.255.255.0",
            "gateway": "192.168.1.1",
            "dnsServer": "8.8.8.8"
          },
          "mesh": {
            "role": "coordinator",
            "channel": 6,
            "meshId": "mesh-001",
            "maxDevices": 200,
            "connectedDevices": 47
          },
          "status": {
            "online": true,
            "lastHeartbeat": "2024-01-15T10:30:00Z",
            "uptime": "15d 7h 23m",
            "cpuUsage": 23.4,
            "memoryUsage": 67.2,
            "temperature": 34.5
          }
        }
      ],
      "meshGateways": [
        {
          "id": "gw-mesh-001",
          "name": "Electronics Mesh Gateway",
          "customerId": "cust-001",
          "parentGateway": "gw-main-001",
          "location": {
            "buildingId": "fp-001",
            "floorNumber": 1,
            "coordinates": {
              "x": 15.0,
              "y": 10.0,
              "unit": "meters"
            },
            "description": "Electronics Department"
          },
          "network": {
            "ipAddress": "192.168.1.101",
            "macAddress": "00:1A:2B:3C:4D:5F",
            "parentMac": "00:1A:2B:3C:4D:5E"
          },
          "status": {
            "online": true,
            "lastHeartbeat": "2024-01-15T10:29:55Z",
            "linkQuality": 85
          }
        }
      ]
    }
  }
}
                        

📊 Usage Examples

1. Configure Network from Building Map UI

// Building map configuration
const networkConfig = {
  buildingId: "fp-001",
  customerId: "cust-001",
  networkConfiguration: {
    mainGateway: {
      id: "gw-main-001",
      location: { floorNumber: 1, coordinates: {x: 25, y: 15} },
      networkSettings: {
        ipAddress: "192.168.1.100",
        subnetMask: "255.255.255.0"
      }
    },
    meshGateways: [
      {
        id: "gw-mesh-001",
        name: "Electronics Gateway",
        location: { floorNumber: 1, coordinates: {x: 15, y: 10} },
        meshSettings: { role: "router", maxBleDevices: 50 }
      }
    ]
  }
};

// Send configuration to server
const response = await fetch('/api/buildings/fp-001/network-topology/configure', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(networkConfig)
});
                

2. Monitor Configuration Deployment

// Monitor deployment progress
const configId = "config-001";
const statusInterval = setInterval(async () => {
  const response = await fetch(`/api/buildings/fp-001/network-topology/status/${configId}`);
  const status = await response.json();
  
  console.log(`Deployment progress: ${status.data.progress}%`);
  
  if (status.data.status === 'completed') {
    clearInterval(statusInterval);
    console.log('Network topology deployment completed!');
  }
}, 5000);
                

3. Listen for Gateway Configuration Updates

// Subscribe to configuration status
client.subscribe('customer123/gateways/config/status');

client.on('message', (topic, message) => {
  const data = JSON.parse(message.toString());
  if (data.type === 'configuration_status') {
    console.log(`Gateway ${data.gatewayId}: ${data.data.status}`);
    updateGatewayStatus(data.gatewayId, data.data);
  }
});
                

🔒 Security Considerations

🔐 Authentication

All API endpoints require valid JWT tokens for access control and user identification.

🏢 Authorization

Gateway access is scoped to customer ID to ensure data isolation between customers.

🔒 MQTT Security

Use TLS encryption for all MQTT connections to protect data in transit.

📍 Location Privacy

Implement location data encryption for sensitive positioning information.

📝 Implementation Notes

📍 Location Accuracy

Use trilateration with multiple gateways for better accuracy in device positioning.

⚡ Real-time Updates

Implement WebSocket connections for real-time map updates and status changes.

🚀 Caching

Cache network topology data for improved performance and reduced API calls.

📈 Scalability

Design architecture to handle buildings with 100+ gateways efficiently.