215 lines
6.4 KiB
Markdown
215 lines
6.4 KiB
Markdown
# CtrEditor MCP Server - LLM Usage Guide
|
|
|
|
## 🤖 Quick Start for Language Models
|
|
|
|
This guide provides step-by-step instructions for LLMs to interact with CtrEditor simulations programmatically. The MCP server allows complete control over simulation objects, execution, and monitoring.
|
|
|
|
## 🚀 Basic Workflow
|
|
|
|
### 1. Initial Assessment
|
|
Start by getting the current state of the simulation:
|
|
|
|
```
|
|
🔍 list_objects - See what's currently in the simulation
|
|
🎮 get_simulation_status - Check if simulation is running
|
|
🔌 get_plc_status - Check PLC connection state
|
|
```
|
|
|
|
### 2. Object Analysis
|
|
For each object found, examine its properties to understand:
|
|
- **Position**: `Left`, `Top` coordinates in meters
|
|
- **Dimensions**: `Ancho` (width), `Alto` (height) in meters
|
|
- **Type-Specific Properties**: Flow rates, pressures, speeds, etc.
|
|
- **Connection States**: Which components are connected
|
|
- **Simulation Parameters**: Physics and hydraulic settings
|
|
|
|
### 3. Simulation Control
|
|
Control the simulation lifecycle:
|
|
- `start_simulation` - Begin physics calculations
|
|
- `stop_simulation` - Halt simulation
|
|
- Monitor changes with repeated `list_objects` calls
|
|
|
|
## 📊 Object Property Deep Dive
|
|
|
|
### Hydraulic Components
|
|
|
|
#### **osHydTank** (Hydraulic Tank)
|
|
Key Properties to Monitor:
|
|
- `TankType`: Type of tank (1=standard)
|
|
- `CrossSectionalArea`: Tank cross-section in m²
|
|
- `MaxLevel`, `MinLevel`: Level limits in meters
|
|
- `TankPressure`: Pressure in Pascal
|
|
- `IsFixedPressure`: Whether pressure is constant
|
|
|
|
#### **osHydPump** (Hydraulic Pump)
|
|
Key Properties to Monitor:
|
|
- `PumpHead`: Pump head in meters
|
|
- `MaxFlow`: Maximum flow rate in m³/s
|
|
- `SpeedRatio`: Speed ratio (0.0-1.0)
|
|
- `IsRunning`: Pump operational state
|
|
- `PumpDirection`: Flow direction (1=forward, -1=reverse)
|
|
|
|
#### **osHydPipe** (Hydraulic Pipe)
|
|
Key Properties to Monitor:
|
|
- `Length`: Pipe length in meters
|
|
- `Diameter`: Internal diameter in meters
|
|
- `Roughness`: Surface roughness
|
|
- `CurrentFlow`: Current flow rate in m³/s
|
|
- `PressureDrop`: Pressure loss across pipe
|
|
- `Id_ComponenteA`, `Id_ComponenteB`: Connected components
|
|
|
|
### Dynamic Properties
|
|
During simulation, monitor these changing values:
|
|
- Flow rates in pipes (`CurrentFlow`)
|
|
- Pressure drops (`PressureDrop`)
|
|
- Tank levels (if applicable)
|
|
- Pump performance metrics
|
|
|
|
## 🖼️ Visual Documentation
|
|
|
|
### Full Canvas Screenshots
|
|
```json
|
|
take_screenshot()
|
|
```
|
|
- Captures entire simulation at 2x resolution
|
|
- Saves to `/screenshots/` subdirectory
|
|
- Returns detailed file information
|
|
|
|
### Targeted Screenshots
|
|
```json
|
|
take_screenshot({
|
|
"x": 39.0, // Start X in meters
|
|
"y": 19.0, // Start Y in meters
|
|
"width": 7.0, // Width in meters
|
|
"height": 3.0 // Height in meters
|
|
})
|
|
```
|
|
- Captures specific region at 3x resolution (high detail)
|
|
- Perfect for component close-ups
|
|
- Use object positions to determine coordinates
|
|
|
|
### Screenshot Use Cases
|
|
1. **Component Documentation**: Capture individual components
|
|
2. **System Overview**: Full canvas for complete system view
|
|
3. **Before/After Comparison**: Screenshots before and after simulation
|
|
4. **Issue Investigation**: High-resolution captures of problem areas
|
|
|
|
## 🔧 Property Modification
|
|
|
|
### Updating Object Properties
|
|
```json
|
|
update_object({
|
|
"id": "307211",
|
|
"properties": {
|
|
"PumpHead": 75.0,
|
|
"MaxFlow": 0.015,
|
|
"IsRunning": true
|
|
}
|
|
})
|
|
```
|
|
|
|
### Safe Property Modification
|
|
- Always check current properties first with `list_objects`
|
|
- Modify only relevant properties for the object type
|
|
- Use appropriate units (meters, Pascal, m³/s, etc.)
|
|
- Verify changes by calling `list_objects` again
|
|
|
|
## 🎯 Common Debugging Workflows
|
|
|
|
### 1. Pre-Simulation Analysis
|
|
```
|
|
1. list_objects - Document initial state
|
|
2. take_screenshot() - Visual documentation
|
|
3. Analyze object configurations and connections
|
|
4. Verify proper component setup
|
|
```
|
|
|
|
### 2. Simulation Monitoring
|
|
```
|
|
1. start_simulation - Begin simulation
|
|
2. get_simulation_status - Confirm running
|
|
3. list_objects - Monitor dynamic properties
|
|
4. take_screenshot(area) - Capture specific components
|
|
5. stop_simulation - End when needed
|
|
```
|
|
|
|
### 3. Performance Investigation
|
|
```
|
|
1. list_objects - Get baseline measurements
|
|
2. start_simulation - Run simulation
|
|
3. Wait 5-10 seconds for stabilization
|
|
4. list_objects - Compare with baseline
|
|
5. take_screenshot() - Document final state
|
|
```
|
|
|
|
### 4. Component Analysis
|
|
```
|
|
1. take_screenshot(component_area) - High-res component view
|
|
2. list_objects - Get detailed properties
|
|
3. update_object - Modify parameters if needed
|
|
4. start_simulation - Test changes
|
|
5. take_screenshot(component_area) - Compare results
|
|
```
|
|
|
|
## 📈 Simulation Data Interpretation
|
|
|
|
### Flow Analysis
|
|
- **Positive Flow**: Normal direction flow
|
|
- **Negative Flow**: Reverse flow direction
|
|
- **Zero Flow**: No flow (blockage or equilibrium)
|
|
|
|
### Pressure Analysis
|
|
- **High Pressure Drop**: Potential flow restriction
|
|
- **Low Pressure Drop**: Free-flowing condition
|
|
- **Pressure Patterns**: Indicate system behavior
|
|
|
|
### Pump Performance
|
|
- **SpeedRatio**: Pump operation intensity
|
|
- **IsRunning**: Operational state
|
|
- **PumpDirection**: Flow direction control
|
|
|
|
## 🚨 Troubleshooting Guide
|
|
|
|
### Connection Issues
|
|
If MCP commands fail:
|
|
1. Check CtrEditor is running
|
|
2. Verify MCP server is active on port 5006
|
|
3. Use `get_simulation_status` to test connectivity
|
|
|
|
### Simulation Issues
|
|
If simulation behaves unexpectedly:
|
|
1. Stop simulation with `stop_simulation`
|
|
2. Check object properties with `list_objects`
|
|
3. Verify component connections
|
|
4. Take screenshots for visual verification
|
|
5. Restart simulation with `start_simulation`
|
|
|
|
### Data Inconsistencies
|
|
If properties seem wrong:
|
|
1. Get fresh data with `list_objects`
|
|
2. Compare with visual evidence via `take_screenshot`
|
|
3. Check if simulation is running vs stopped
|
|
4. Verify meter-based coordinates
|
|
|
|
## 💡 Best Practices
|
|
|
|
### Efficient Monitoring
|
|
- Use `get_simulation_status` for quick status checks
|
|
- Call `list_objects` only when detailed data is needed
|
|
- Take targeted screenshots instead of full canvas when possible
|
|
|
|
### Data Analysis
|
|
- Always compare before/after simulation states
|
|
- Monitor key performance indicators for each component type
|
|
- Use screenshots to validate data interpretations
|
|
|
|
### Documentation
|
|
- Screenshot key configurations and results
|
|
- Document property changes with timestamps
|
|
- Maintain clear before/after comparisons
|
|
|
|
### Safety
|
|
- Always stop simulation before making major changes
|
|
- Verify property updates with `list_objects`
|
|
- Use appropriate units for all parameters
|