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

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:

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