digital-twin-sync — Claude Code skill: what it does, how to install
digital-twin-sync connects BIM components with IoT telemetry, field reports, and schedule updates to maintain real-time construction digital twins.
MIT 123 installs ★ 434 updated 2026-10-19
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a claude-codeWhat digital-twin-sync does
This skill implements construction digital twin management routines in Python. It maps IFC identifiers (ifc_guid) directly to telemetry streams using dataclasses like TwinElement and DigitalTwinElement.
The system handles multiple incoming data channels: BIM geometry, IoT sensors, schedule milestones, drone surveys, and manual inputs. Each property keeps a history buffer capped at 100 recent entries with timestamps, confidence scores, and source tags.
Execution relies strictly on a local python3 binary. The twin synchronization logic will fail immediately if Python is missing from your system path.
What it helps with
- bind IoT sensor streams to specific IFC elements
- track parameter changes across construction components
- aggregate drone, schedule, and sensor readings into one twin model
- retrieve the latest telemetry status for any structural element
Example prompts for the agent
- Set up a SimpleTwin instance and bind temperature sensor TEMP-001 to element WALL-001
- Show me how to update element properties with history logging using DigitalTwinElement
- Query the latest state and sensor reading for an IFC wall element
How to install digital-twin-sync
1Skills CLI (Vercel)
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a claude-code2Manually: put the files in place
~/.claude/skills/digital-twin-sync/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/digital-twin-sync/
1Skills CLI (Vercel)
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a codex2Manually: put the files in place
.agents/skills/digital-twin-sync/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a cursor2Manually: put the files in place
.cursor/skills/digital-twin-sync/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction 5_DDC_Innovative/digital-twin-sync/SKILL.md2Manually: put the files in place
.github/skills/digital-twin-sync/SKILL.md1Skills CLI (Vercel)
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a gemini-cli2Platform CLI
gemini skills install https://github.com/datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --path 5_DDC_Innovative/digital-twin-syncManually: put the files in place
.devin/skills/digital-twin-sync/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about digital-twin-sync
How to install digital-twin-sync in Claude Code?
Run npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill digital-twin-sync -a claude-code in your terminal.
What does digital-twin-sync do?
It provides data structures and workflow scripts to synchronize BIM geometry with IoT streams and construction site logs.
What dependencies does this skill require?
It requires python3 installed on the host system (compatible with macOS, Linux, and Windows).
Source text
SKILL.md · MIT
---
name: "digital-twin-sync"
description: "Synchronize construction digital twins with real-time data. Connect BIM models with IoT sensors, progress updates, and field data for live project visualization and monitoring."
homepage: "https://datadrivenconstruction.io"
metadata: {"openclaw": {"emoji": "🚀", "os": ["darwin", "linux", "win32"], "homepage": "https://datadrivenconstruction.io", "requires": {"bins": ["python3"]}}}
---
# Digital Twin Synchronization
## Overview
This skill implements digital twin synchronization for construction projects. Connect BIM models with real-time sensor data, progress updates, and field information to create a living digital representation.
**Capabilities:**
- BIM-IoT data binding
- Real-time status updates
- Historical data tracking
- Anomaly detection
- Predictive analytics
- Multi-source data fusion
## Quick Start
```python
from dataclasses import dataclass, field
from datetime import datetime
from typing import Dict, List, Optional, Any
from enum import Enum
import json
class ElementStatus(Enum):
PLANNED = "planned"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
ISSUE = "issue"
@dataclass
class TwinElement:
element_id: str
ifc_guid: str
element_type: str
status: ElementStatus
properties: Dict[str, Any] = field(default_factory=dict)
sensor_bindings: List[str] = field(default_factory=list)
last_updated: datetime = field(default_factory=datetime.now)
@dataclass
class SensorData:
sensor_id: str
value: float
unit: str
timestamp: datetime
quality: float = 1.0
class SimpleTwin:
"""Simple digital twin implementation"""
def __init__(self, project_id: str):
self.project_id = project_id
self.elements: Dict[str, TwinElement] = {}
self.sensor_data: Dict[str, List[SensorData]] = {}
def add_element(self, element: TwinElement):
self.elements[element.element_id] = element
def bind_sensor(self, element_id: str, sensor_id: str):
if element_id in self.elements:
self.elements[element_id].sensor_bindings.append(sensor_id)
def update_sensor(self, data: SensorData):
if data.sensor_id not in self.sensor_data:
self.sensor_data[data.sensor_id] = []
self.sensor_data[data.sensor_id].append(data)
# Update linked elements
for elem in self.elements.values():
if data.sensor_id in elem.sensor_bindings:
elem.properties[f'sensor_{data.sensor_id}'] = data.value
elem.last_updated = data.timestamp
def get_element_state(self, element_id: str) -> Dict:
elem = self.elements.get(element_id)
if not elem:
return {}
state = {
'element_id': elem.element_id,
'status': elem.status.value,
'properties': elem.properties,
'last_updated': elem.last_updated.isoformat()
}
# Add latest sensor values
for sensor_id in elem.sensor_bindings:
if sensor_id in self.sensor_data and self.sensor_data[sensor_id]:
latest = self.sensor_data[sensor_id][-1]
state[f'sensor_{sensor_id}'] = {
'value': latest.value,
'unit': latest.unit,
'timestamp': latest.timestamp.isoformat()
}
return state
# Example
twin = SimpleTwin("PROJECT-001")
twin.add_element(TwinElement(
element_id="WALL-001",
ifc_guid="2O2Fr$t4X7Zf8NOew3FLOH",
element_type="IfcWall",
status=ElementStatus.IN_PROGRESS
))
twin.bind_sensor("WALL-001", "TEMP-001")
twin.update_sensor(SensorData("TEMP-001", 22.5, "°C", datetime.now()))
print(twin.get_element_state("WALL-001"))
```
## Comprehensive Digital Twin System
### Core Twin Model
```python
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from typing import Dict, List, Optional, Any, Callable
from enum import Enum
import json
import threading
from queue import Queue
import time
class DataSource(Enum):
BIM = "bim"
IOT = "iot"
SCHEDULE = "schedule"
FIELD = "field"
DRONE = "drone"
MANUAL = "manual"
@dataclass
class PropertyValue:
value: Any
unit: Optional[str]
timestamp: datetime
source: DataSource
confidence: float = 1.0
history: List[Dict] = field(default_factory=list)
@dataclass
class DigitalTwinElement:
element_id: str
ifc_guid: str
element_type: str
name: str
status: ElementStatus = ElementStatus.PLANNED
properties: Dict[str, PropertyValue] = field(default_factory=dict)
sensor_bindings: Dict[str, str] = field(default_factory=dict) # property_name -> sensor_id
geometry_ref: Optional[str] = None
parent_id: Optional[str] = None
children_ids: List[str] = field(default_factory=list)
schedule_activity_id: Optional[str] = None
created_at: datetime = field(default_factory=datetime.now)
updated_at: datetime = field(default_factory=datetime.now)
def update_property(self, name: str, value: Any, unit: str = None,
source: DataSource = DataSource.MANUAL,
confidence: float = 1.0):
"""Update property with history tracking"""
now = datetime.now()
if name in self.properties:
# Store previous value in history
prev = self.properties[name]
prev.history.append({
'value': prev.value,
'timestamp': prev.timestamp.isoformat(),
'source': prev.source.value
})
# Keep only last 100 values
prev.history = prev.history[-100:]
prev.value = value
prev.unit = unit or prev.unit
prev.timestamp = now
prev.source = source
prev.confidence = confidence
else:
self.properties[name] = PropertyValue(
value=value,
unit=unit,
timestamp=now,
source=source,
confidence=confidence
)
self.updated_at = now
@dataclass
class TwinEvent:
event_id: str
event_type: str # property_update, status_change, alert, etc.
element_id: str
timestamp: datetime
data: Dict
source: DataSource
class DigitalTwinCore:
"""Core digital twin management system"""
def __init__(self, project_id: str, project_name: str):
self.project_id = project_id
self.project_name = project_name
self.elements: Dict[str, DigitalTwinElement] = {}
self.events: List[TwinEvent] = []
self.event_handlers: Dict[str, List[Callable]] = {}
self.update_queue: Queue = Queue()
self._running = False
def import_from_ifc(self, ifc_data: List[Dict]):
"""Import elements from IFC data"""
for elem_data in ifc_data:
element = DigitalTwinElement(
element_id=elem_data.get('id', f"ELEM-{len(self.elements)}"),
ifc_guid=elem_data.get('guid', ''),
element_type=elem_data.get('type', 'IfcBuildingElement'),
name=elem_data.get('name', 'Unknown'),
geometry_ref=elem_data.get('geometry_ref')
)
# Import properties
for prop_name, prop_value in elem_data.get('properties', {}).items():
element.update_property(
prop_name,
prop_value.get('value'),
prop_value.get('unit'),
DataSource.BIM
)
self.elements[element.element_id] = element
def bind_sensor_to_property(self, element_id: str, property_name: str,
sensor_id: str, transform: Callable = None):
"""Bind IoT sensor to element property"""
element = self.elements.get(element_id)
if element:
element.sensor_bindings[property_name] = sensor_id
# Store transform function if needed
if transform:
element.sensor_bindings[f'{property_name}_transform'] = transform
def process_sensor_update(self, sensor_id: str, value: float,
unit: str, timestamp: datetime = None):
"""Process incoming sensor data"""
timestamp = timestamp or datetime.now()
# Find all elements bound to this sensor
for element in self.elements.values():
for prop_name, bound_sensor in element.sensor_bindings.items():
if bound_sensor == sensor_id and not prop_name.endswith('_transform'):
# Apply transform if exists
transform_key = f'{prop_name}_transform'
if transform_key in element.sensor_bindings:
transform = element.sensor_bindings[transform_key]
value = transform(value)
element.update_property(prop_name, value, unit, DataSource.IOT)
# Create event
self._emit_event('property_update', element.element_id, {
'property': prop_name,
'value': value,
'sensor_id': sensor_id
}, DataSource.IOT)
def update_status(self, element_id: str, status: ElementStatus,
source: DataSource = DataSource.FIELD):
"""Update element construction status"""
element = self.elements.get(element_id)
if not element:
return
old_status = element.status
element.status = status
element.updated_at = datetime.now()
self._emit_event('status_change', element_id, {
'old_status': old_status.value,
'new_status': status.value
}, source)
def _emit_event(self, event_type: str, element_id: str,
data: Dict, source: DataSource):
"""Emit twin event"""
event = TwinEvent(
event_id=f"EVT-{len(self.events):06d}",
event_type=event_type,
element_id=element_id,
timestamp=datetime.now(),
data=data,
source=source
)
self.events.append(event)
# Notify handlers
for handler in self.event_handlers.get(event_type, []):
try:
handler(event)
except Exception as e:
print(f"Event handler error: {e}")
def on_event(self, event_type: str, handler: Callable):
"""Register event handler"""
if event_type not in self.event_handlers:
self.event_handlers[event_type] = []
self.event_handlers[event_type].append(handler)
def get_element_snapshot(self, element_id: str) -> Dict:
"""Get current state snapshot of element"""
element = self.elements.get(element_id)
if not element:
return {}
return {
'element_id': element.element_id,
'ifc_guid': element.ifc_guid,
'type': element.element_type,
'name': element.name,
'status': element.status.value,
'properties': {
name: {
'value': prop.value,
'unit': prop.unit,
'timestamp': prop.timestamp.isoformat(),
'source': prop.source.value,
'confidence': prop.confidence
}
for name, prop in element.properties.items()
},
'updated_at': element.updated_at.isoformat()
}
def get_project_snapshot(self) -> Dict:
"""Get full project state snapshot"""
status_counts = {}
for elem in self.elements.values():
status = elem.status.value
status_counts[status] = status_counts.get(status, 0) + 1
return {
'project_id': self.project_id,
'project_name': self.project_name,
'timestamp': datetime.now().isoformat(),
'element_count': len(self.elements),
'status_summary': status_counts,
'recent_events': [
{
'event_id': e.event_id,
'type': e.event_type,
'element': e.element_id,
'timestamp': e.timestamp.isoformat()
}
for e in self.events[-10:]
]
}
```
### Real-Time Synchronization
```python
import asyncio
from typing import Dict, List, Callable
import websockets
import json
class TwinSynchronizer:
"""Real-time twin synchronization service"""
def __init__(self, twin: DigitalTwinCore):
self.twin = twin
self.subscribers: Dict[str, List[websockets.WebSocketServerProtocol]] = {}
self.sync_interval = 1.0 # seconds
async def start_server(self, host: str = 'localhost', port: int = 8765):
"""Start WebSocket server for real-time updates"""
async with websockets.serve(self._handle_connection, host, port):
print(f"Twin sync server running on ws://{host}:{port}")
await asyncio.Future() # Run forever
async def _handle_connection(self, websocket, path):
"""Handle WebSocket connection"""
try:
async for message in websocket:
data = json.loads(message)
await self._process_message(websocket, data)
except websockets.exceptions.ConnectionClosed:
pass
finally:
# Remove from all subscriptions
for element_id in list(self.subscribers.keys()):
if websocket in self.subscribers[element_id]:
self.subscribers[element_id].remove(websocket)
async def _process_message(self, websocket, data: Dict):
"""Process incoming message"""
msg_type = data.get('type')
if msg_type == 'subscribe':
element_id = data.get('element_id', '*')
if element_id not in self.subscribers:
self.subscribers[element_id] = []
self.subscribers[element_id].append(websocket)
# Send current state
if element_id == '*':
state = self.twin.get_project_snapshot()
else:
state = self.twin.get_element_snapshot(element_id)
await websocket.send(json.dumps({
'type': 'state',
'data': state
}))
elif msg_type == 'update':
# Handle incoming update from field
element_id = data.get('element_id')
updates = data.get('updates', {})
for prop_name, value in updates.items():
element = self.twin.elements.get(element_id)
if element:
element.update_property(prop_name, value, source=DataSource.FIELD)
# Broadcast update
await self._broadcast_update(element_id)
elif msg_type == 'status_update':
element_id = data.get('element_id')
status = ElementStatus(data.get('status'))
self.twin.update_status(element_id, status, DataSource.FIELD)
await self._broadcast_update(element_id)
async def _broadcast_update(self, element_id: str):
"""Broadcast element update to subscribers"""
state = self.twin.get_element_snapshot(element_id)
message = json.dumps({
'type': 'update',
'element_id': element_id,
'data': state
})
# Send to specific element subscribers
for ws in self.subscribers.get(element_id, []):
try:
await ws.send(message)
except:
pass
# Send to wildcard subscribers
for ws in self.subscribers.get('*', []):
try:
await ws.send(message)
except:
pass
def setup_sensor_integration(self, mqtt_client):
"""Setup MQTT integration for IoT sensors"""
def on_message(client, userdata, msg):
try:
data = json.loads(msg.payload.decode())
self.twin.process_sensor_update(
sensor_id=data.get('sensor_id'),
value=data.get('value'),
unit=data.get('unit'),
timestamp=datetime.fromisoformat(data.get('timestamp'))
)
except Exception as e:
print(f"Sensor message error: {e}")
mqtt_client.on_message = on_message
mqtt_client.subscribe("sensors/#")
```
### Schedule Integration
```python
from datetime import date, datetime
@dataclass
class ScheduleActivity:
activity_id: str
name: str
planned_start: date
planned_end: date
actual_start: Optional[date] = None
actual_end: Optional[date] = None
percent_complete: float = 0
element_ids: List[str] = field(default_factory=list)
class ScheduleTwinIntegrator:
"""Integrate schedule with digital twin"""
def __init__(self, twin: DigitalTwinCore):
self.twin = twin
self.activities: Dict[str, ScheduleActivity] = {}
def import_schedule(self, schedule_data: List[Dict]):
"""Import schedule activities"""
for act_data in schedule_data:
activity = ScheduleActivity(
activity_id=act_data['id'],
name=act_data['name'],
planned_start=date.fromisoformat(act_data['start']),
planned_end=date.fromisoformat(act_data['end']),
element_ids=act_data.get('elements', [])
)
self.activities[activity.activity_id] = activity
# Link elements to activity
for elem_id in activity.element_ids:
if elem_id in self.twin.elements:
self.twin.elements[elem_id].schedule_activity_id = activity.activity_id
def update_activity_progress(self, activity_id: str, percent_complete: float,
actual_start: date = None, actual_end: date = None):
"""Update activity progress"""
activity = self.activities.get(activity_id)
if not activity:
return
activity.percent_complete = percent_complete
if actual_start:
activity.actual_start = actual_start
if actual_end:
activity.actual_end = actual_end
# Update linked elements
status = self._determine_status(percent_complete)
for elem_id in activity.element_ids:
self.twin.update_status(elem_id, status, DataSource.SCHEDULE)
def _determine_status(self, percent: float) -> ElementStatus:
"""Determine element status from progress percentage"""
if percent == 0:
return ElementStatus.PLANNED
elif percent < 100:
return ElementStatus.IN_PROGRESS
else:
return ElementStatus.COMPLETED
def calculate_schedule_variance(self) -> Dict:
"""Calculate schedule performance"""
today = date.today()
variances = []
for activity in self.activities.values():
planned_duration = (activity.planned_end - activity.planned_start).days
if planned_duration == 0:
continue
if activity.actual_start:
start_variance = (activity.actual_start - activity.planned_start).days
else:
start_variance = None
if activity.actual_end:
end_variance = (activity.actual_end - activity.planned_end).days
else:
end_variance = None
# Calculate expected progress
if today >= activity.planned_end:
expected_progress = 100
elif today <= activity.planned_start:
expected_progress = 0
else:
elapsed = (today - activity.planned_start).days
expected_progress = elapsed / planned_duration * 100
progress_variance = activity.percent_complete - expected_progress
variances.append({
'activity_id': activity.activity_id,
'name': activity.name,
'planned_start': activity.planned_start.isoformat(),
'planned_end': activity.planned_end.isoformat(),
'actual_progress': activity.percent_complete,
'expected_progress': expected_progress,
'progress_variance': progress_variance,
'start_variance_days': start_variance,
'status': 'ahead' if progress_variance > 0 else 'behind' if progress_variance < -5 else 'on_track'
})
return {
'date': today.isoformat(),
'activities': variances,
'on_track_count': sum(1 for v in variances if v['status'] == 'on_track'),
'ahead_count': sum(1 for v in variances if v['status'] == 'ahead'),
'behind_count': sum(1 for v in variances if v['status'] == 'behind')
}
```
### Anomaly Detection
```python
import numpy as np
from collections import deque
class TwinAnomalyDetector:
"""Detect anomalies in digital twin data"""
def __init__(self, twin: DigitalTwinCore, window_size: int = 100):
self.twin = twin
self.window_size = window_size
self.value_windows: Dict[str, deque] = {} # key: element_id:property
self.thresholds: Dict[str, Dict] = {}
def set_threshold(self, element_id: str, property_name: str,
min_value: float = None, max_value: float = None,
std_multiplier: float = 3.0):
"""Set threshold for property monitoring"""
key = f"{element_id}:{property_name}"
self.thresholds[key] = {
'min': min_value,
'max': max_value,
'std_multiplier': std_multiplier
}
def check_value(self, element_id: str, property_name: str, value: float) -> Dict:
"""Check value for anomalies"""
key = f"{element_id}:{property_name}"
# Initialize window if needed
if key not in self.value_windows:
self.value_windows[key] = deque(maxlen=self.window_size)
window = self.value_windows[key]
anomaly = {
'is_anomaly': False,
'type': None,
'severity': 'normal',
'details': {}
}
# Check against thresholds
if key in self.thresholds:
thresh = self.thresholds[key]
if thresh['min'] is not None and value < thresh['min']:
anomaly['is_anomaly'] = True
anomaly['type'] = 'below_minimum'
anomaly['severity'] = 'warning'
anomaly['details']['threshold'] = thresh['min']
anomaly['details']['value'] = value
if thresh['max'] is not None and value > thresh['max']:
anomaly['is_anomaly'] = True
anomaly['type'] = 'above_maximum'
anomaly['severity'] = 'warning'
anomaly['details']['threshold'] = thresh['max']
anomaly['details']['value'] = value
# Statistical anomaly detection
if len(window) >= 10:
mean = np.mean(window)
std = np.std(window)
if std > 0:
z_score = abs(value - mean) / std
if z_score > 3:
anomaly['is_anomaly'] = True
anomaly['type'] = 'statistical_outlier'
anomaly['severity'] = 'critical' if z_score > 5 else 'warning'
anomaly['details']['z_score'] = z_score
anomaly['details']['mean'] = mean
anomaly['details']['std'] = std
# Add to window
window.append(value)
return anomaly
def monitor_element(self, element_id: str) -> List[Dict]:
"""Monitor all properties of an element for anomalies"""
element = self.twin.elements.get(element_id)
if not element:
return []
anomalies = []
for prop_name, prop in element.properties.items():
if isinstance(prop.value, (int, float)):
result = self.check_value(element_id, prop_name, prop.value)
if result['is_anomaly']:
result['element_id'] = element_id
result['property'] = prop_name
result['timestamp'] = prop.timestamp.isoformat()
anomalies.append(result)
return anomalies
```
## Quick Reference
| Data Source | Update Frequency | Reliability |
|-------------|------------------|-------------|
| BIM Model | On change | High |
| IoT Sensors | Real-time | Variable |
| Schedule | Daily | High |
| Field Updates | Event-driven | Medium |
| Drone Surveys | Periodic | High |
## Resources
- **Digital Twin Consortium**: https://www.digitaltwinconsortium.org
- **IFC/BIM Standards**: https://www.buildingsmart.org
- **DDC Website**: https://datadrivenconstruction.io
## Next Steps
- See `material-tracking-iot` for IoT integration
- See `4d-simulation` for schedule visualization
- See `bim-validation-pipeline` for model validation
© datadrivenconstruction · MIT · datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction