Integration Matrix

CitadelMesh integrates with heterogeneous building systems through vendor-neutral protocol adapters. This document provides a comprehensive matrix of all supported vendor systems, protocols, integration methods, and data contracts.

Systems in Scope

System	Vendor	Category	Protocol	Status
Security Expert	Schneider Electric	Access Control	REST API + Webhooks	Production
Avigilon Control Center	Avigilon (Motorola)	Video Surveillance	REST API + Analytics	Production
EcoStruxure Building Operation	Schneider Electric	HVAC/BMS	REST + OPC UA	Production
Home Assistant	Open Source	Lighting & Automation	WebSocket + REST	Production
PowerLogic PME	Schneider Electric	Energy Management	REST + SQL Export	Production
Bosch Fire/Intrusion	Bosch	Life Safety	Read-Only Syslog/OPC	Monitoring Only

Integration Architecture

graph TB
    subgraph "CitadelMesh Edge"
        EventBus[Event Bus<br/>CloudEvents + NATS]
        OPA[OPA Policy Engine]

        subgraph "Protocol Adapters"
            SSE[Security Expert Adapter]
            AVI[Avigilon Adapter]
            EBO[EBO Adapter]
            HA[Home Assistant Adapter]
            PME[PME Adapter]
            Bosch[Bosch Adapter]
        end
    end

    subgraph "Vendor Systems"
        SchneiderSE[Schneider Security Expert]
        AvigilonCC[Avigilon Control Center]
        EcoStruxure[EcoStruxure EBO]
        HomeAssistant[Home Assistant]
        SchneiderPME[Schneider PME]
        BoschFire[Bosch Fire/Intrusion]
    end

    SSE -->|REST/Webhooks| SchneiderSE
    AVI -->|REST API| AvigilonCC
    EBO -->|REST/OPC UA| EcoStruxure
    HA -->|WebSocket| HomeAssistant
    PME -->|REST/SQL| SchneiderPME
    Bosch -->|Syslog/OPC| BoschFire

    SSE --> EventBus
    AVI --> EventBus
    EBO --> EventBus
    HA --> EventBus
    PME --> EventBus
    Bosch --> EventBus

    EventBus --> OPA

Adapter Specifications

Schneider Security Expert Adapter

System Purpose: Building access control, door management, cardholder administration

Integration Method:

• Events: REST webhooks for real-time events + periodic polling fallback
• Control: REST API for door lock/unlock, cardholder management
• Authentication: API key + mTLS (SPIFFE)

CloudEvents Mapping:

Vendor Event	CloudEvent Type	Protobuf Message
AccessGranted	citadel.security.access.granted	incidents.v1.Incident
AccessDenied	citadel.security.access.denied	incidents.v1.Incident
DoorForced	citadel.security.door.forced	incidents.v1.Incident
DoorHeld	citadel.security.door.held	incidents.v1.Incident
DoorState	citadel.telemetry.door.state	telemetry.v1.Point

Control Commands:

// Lock door
Command {
  target_id: "door.lobby.main"
  action: "lock_door"
  params: {}
  safety_token: "<OPA token>"
}

// Unlock door (temporary)
Command {
  target_id: "door.lobby.main"
  action: "unlock_door"
  params: {
    "duration_seconds": "300"  // 5 minutes
    "priority": "PRIORITY_NORMAL"
  }
  safety_token: "<OPA token>"
}

Safety Constraints:

• Never block emergency egress
• Unlock duration limited (max 15 minutes)
• Bulk unlock requires approval
• All actions audit logged

MCP Tools:

{
  "securityexpert_subscribe_events": "Subscribe to access control events",
  "securityexpert_door_lock": "Lock a door",
  "securityexpert_door_unlock": "Unlock a door temporarily",
  "securityexpert_cardholder_update": "Update cardholder permissions"
}

Avigilon Adapter

System Purpose: Video surveillance, analytics, person/object detection

Integration Method:

• Events: REST API polling for analytics events + webhooks where available
• Video: RTSP streams with HLS/WebRTC transcoding at edge
• Authentication: API credentials + camera stream tokens

CloudEvents Mapping:

Vendor Event	CloudEvent Type	Protobuf Message
PersonDetected	citadel.security.person.detected	incidents.v1.Incident
Loitering	citadel.security.loitering	incidents.v1.Incident
LineCrossing	citadel.security.line_crossed	incidents.v1.Incident
CameraOffline	citadel.telemetry.camera.offline	telemetry.v1.Point

Control Commands:

// Capture snapshot
Command {
  target_id: "camera.lobby.01"
  action: "snapshot"
  params: {"bookmark_label": "Security Incident 001"}
}

// Start tracking
Command {
  target_id: "camera.lobby.01"
  action: "track_person"
  params: {"person_id": "person-123"}
}

Privacy Controls:

• Edge-based redaction/blur before cloud export
• Access-scoped stream permissions (SPIFFE-based)
• Retention policies (90 days edge, configurable cloud)
• PII minimization in analytics metadata

MCP Tools:

{
  "avigilon_subscribe_analytics": "Subscribe to camera analytics",
  "avigilon_snapshot": "Capture camera snapshot with bookmark",
  "avigilon_track_person": "Track person across cameras"
}

EcoStruxure (EBO) Adapter

System Purpose: HVAC control, zone temperature management, energy optimization

Integration Method:

• Telemetry: REST API + OPC UA for real-time points
• Control: REST API for setpoint writes, mode changes
• Trends: Periodic polling for historical data
• Authentication: API credentials + OPC UA certificates

CloudEvents Mapping:

Vendor Point	CloudEvent Type	Protobuf Message
Zone Temperature	citadel.telemetry.hvac.temp	telemetry.v1.Point
Zone Humidity	citadel.telemetry.hvac.humidity	telemetry.v1.Point
Setpoint Current	citadel.telemetry.hvac.setpoint	telemetry.v1.Point
Equipment Status	citadel.telemetry.hvac.status	telemetry.v1.Point

Control Commands:

// Write setpoint
Command {
  target_id: "hvac.zone1.setpoint"
  action: "write_setpoint"
  params: {
    "value": "72",
    "unit": "F",
    "priority": "8"  // BACnet priority
  }
  safety_token: "<OPA token with temp bounds>"
}

// Change mode
Command {
  target_id: "hvac.zone1.mode"
  action: "write_mode"
  params: {"mode": "auto"}
}

Safety Constraints (OPA enforced):

• Temperature bounds: 65-78°F (comfort range)
• Tighter bounds for critical zones (data center: 68-75°F)
• Night setback allowed: 60-78°F
• Rate limiting: Max 5 changes/hour per zone
• Shadow mode for new RL policies

MCP Tools:

{
  "ebo_read_point": "Read BACnet/OPC UA point",
  "ebo_write_point": "Write point value (OPA validated)",
  "ebo_read_batch_points": "Batch read multiple points",
  "ebo_get_trend": "Get historical trend data"
}

Home Assistant Adapter

System Purpose: Lighting control, scene management, IoT device aggregation

Integration Method:

• Events: WebSocket API for real-time state changes
• Control: REST API + WebSocket for commands
• Discovery: MQTT discovery protocol
• Authentication: Long-lived access token

CloudEvents Mapping:

HA Entity	CloudEvent Type	Protobuf Message
light.*	citadel.telemetry.lighting.state	telemetry.v1.Point
binary_sensor.occupancy	citadel.telemetry.occupancy	telemetry.v1.Point
scene.*	citadel.automation.scene.activated	events.v1.SceneEvent

Control Commands:

// Activate scene
Command {
  target_id: "scene.meeting_mode"
  action: "activate_scene"
  params: {}
}

// Control light
Command {
  target_id: "light.conference_room_a"
  action: "set_light"
  params: {
    "on": "true",
    "brightness": "80",
    "color_temp": "370"
  }
}

MCP Tools:

{
  "ha_activate_scene": "Activate lighting/automation scene",
  "ha_set_light": "Control individual light",
  "ha_get_state": "Get entity state"
}

Schneider PME Adapter

System Purpose: Electrical energy monitoring, power quality, demand management

Integration Method:

• Telemetry: REST API + SQL database export (read-only)
• Alarms: REST API event subscription
• Trends: Periodic polling for power/energy metrics
• Authentication: Database credentials + API key

CloudEvents Mapping:

PME Metric	CloudEvent Type	Protobuf Message
Active Power	citadel.telemetry.power.active	telemetry.v1.Point
Energy Consumption	citadel.telemetry.energy.total	telemetry.v1.Point
Demand	citadel.telemetry.power.demand	telemetry.v1.Point
Power Factor	citadel.telemetry.power.factor	telemetry.v1.Point
Alarms	citadel.incidents.power.alarm	incidents.v1.Incident

Use Cases:

• Real-time energy KPI dashboards
• Demand limiting (coordinate with Energy Agent)
• Demand response readiness
• Power quality anomaly detection

MCP Tools:

{
  "pme_query_power": "Query current power metrics",
  "pme_query_energy": "Query energy consumption over time window",
  "pme_subscribe_alarms": "Subscribe to power quality alarms"
}

Bosch Fire/Intrusion Adapter

System Purpose: Life safety monitoring (INFORMATION ONLY - NO CONTROL)

Integration Method:

• Events: Syslog + OPC UA (read-only)
• Control: NONE - monitoring only per AHJ requirements
• Alarms: Real-time fire/intrusion panel state
• Authentication: Certificate-based OPC UA

CloudEvents Mapping:

Bosch Event	CloudEvent Type	Protobuf Message
Fire Alarm	citadel.incidents.fire.alarm	incidents.v1.Incident
Tamper	citadel.incidents.fire.tamper	incidents.v1.Incident
Trouble	citadel.incidents.fire.trouble	incidents.v1.Incident
Intrusion Zone	citadel.incidents.intrusion.zone	incidents.v1.Incident

Safety Requirements:

• READ-ONLY: No control commands permitted
• Strict network segmentation (separate VLAN)
• AHJ compliance (Authority Having Jurisdiction)
• Audit trail for all data access
• Alerting to Ops Agent only

MCP Tools:

{
  "bosch_subscribe_fire_events": "Subscribe to fire alarm events (read-only)",
  "bosch_subscribe_intrusion_events": "Subscribe to intrusion events (read-only)"
}

Topic Naming Conventions

All adapters publish to standardized topics:

# Raw vendor events
telemetry.vendor.<adapter>.<site>.<device>

# Canonical telemetry (normalized)
telemetry.canonical.<site>.<entity>.<metric>

# Incidents
incidents.vendor.<adapter>.<site>

# Commands (outbound)
control.cmd.<site>.<entity>

# Command results (inbound)
control.res.<site>.<command_id>

Examples:

telemetry.vendor.ebo.building_a.hvac.zone1.temp
telemetry.canonical.building_a.hvac.zone1.temp
incidents.vendor.avigilon.building_a
control.cmd.building_a.door.lobby.main

Data Flow Example

End-to-end flow for HVAC setpoint adjustment:

sequenceDiagram
    participant EBO as EcoStruxure EBO
    participant Adapter as EBO Adapter
    participant Bus as Event Bus
    participant Agent as Energy Agent
    participant OPA as OPA Engine
    participant Twin as Digital Twin

    EBO->>Adapter: Temperature Reading (REST)
    Adapter->>Bus: CloudEvent(telemetry.canonical)
    Bus->>Twin: Update Entity State
    Bus->>Agent: Notify Temperature Change

    Agent->>Agent: Calculate Optimal Setpoint
    Agent->>OPA: Validate Setpoint Change
    OPA-->>Agent: Allow (temp within bounds)

    Agent->>Bus: CloudEvent(control.cmd)
    Bus->>Adapter: Execute Command
    Adapter->>EBO: Write Setpoint (REST API)
    EBO-->>Adapter: Success
    Adapter->>Bus: CloudEvent(control.res)
    Bus->>Agent: Confirm Success

Testing Strategy

Each adapter has comprehensive test coverage:

# Adapter integration test
async def test_ebo_setpoint_write():
    """Test EBO setpoint write with OPA validation."""

    # Setup
    adapter = EBOAdapter(config)
    await adapter.connect()

    # Create command
    command = Command(
        id=ulid(),
        target_id="hvac.zone1.setpoint",
        action="write_setpoint",
        params={"value": "72", "priority": "8"}
    )

    # Validate with OPA
    decision = await opa.evaluate("citadel.hvac.setpoint", command)
    assert decision["allow"]

    # Execute
    result = await adapter.execute(command)
    assert result.success

    # Verify state
    point = await adapter.read_point("hvac.zone1.setpoint")
    assert point.value == 72.0

Related Documentation

• Vendor Systems - Detailed vendor-specific integration guides
• MCP Adapters - MCP tool server implementation
• Protocol Strategy - CloudEvents and protobuf contracts
• Safety Guardrails - OPA policy enforcement

See Also

• BACnet Protocol
• OPC UA Specification
• CloudEvents Spec