Skip to content

Commit da98f7e

Browse files
harunkurtdevharunkurtdev
committed
Enhance documentation for Webots-Simulink Bridge
- Updated index.md to provide a clearer overview and structured capabilities of the bridge. - Expanded requirements.md with detailed software, hardware, and toolbox requirements, including MATLAB toolboxes and operating system support. - Revised setup.md to include platform-specific installation instructions for Webots and MATLAB, along with environment variable configuration and compiler setup. - Improved connecting.md to clarify the communication architecture and detailed steps for configuring Webots and Simulink for simulation. - Enhanced customization.md with comprehensive instructions for adding custom sensors and actuators, including wrapper functions and integration with Simulink. - Expanded running.md to provide detailed steps for starting, controlling, and monitoring simulations, including real-time monitoring techniques and common issues.
1 parent e5f19f3 commit da98f7e

8 files changed

Lines changed: 1494 additions & 154 deletions

File tree

‎docs/advanced/debugging.md‎

Lines changed: 268 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,268 @@
1-
### How to Debug the Control Architecture Simulink Block
2-
3-
#### 1. Understand the Problem
4-
- Start by clearly defining what "debugging" means in the context of the Simulink block
5-
- Reproduce the issue you're trying to debug
6-
- Use scopes and displays within Simulink to visualize signals
7-
8-
#### 2. Use Debugging Tools
9-
- Add breakpoints to your Simulink model
10-
- Step through the simulation using the Step-by-Step solver
11-
- Examine workspace variables at different time steps
12-
- Use the Display block to output signal values
13-
14-
#### 3. Log and Monitor Signals
15-
- Create subsystems to isolate different parts of your control architecture
16-
- Add To Workspace blocks to capture signals for post-simulation analysis
17-
- Plot signals using scopes or MATLAB figures
18-
19-
#### 4. Check Model Configuration
20-
- Verify solver settings (absolute/relative tolerance, step size)
21-
- Ensure proper data types and sample times are set
22-
- Check for algebraic loops and potential zero-crossing issues
23-
24-
#### 5. When Stuck
25-
- Clear the workspace and start fresh
26-
- Run a smaller, simplified version of your model
27-
- Seek help from colleagues or online forums
28-
29-
By following these steps, you can systematically identify and resolve issues within your Simulink control architecture blocks.
1+
# Debugging Guide
2+
3+
This guide provides techniques for troubleshooting issues with the Webots-Simulink Bridge.
4+
5+
---
6+
7+
## Common Issues and Solutions
8+
9+
### Connection Problems
10+
11+
| Symptom | Cause | Solution |
12+
|---------|-------|----------|
13+
| Webots not responding | Controller not set to `<extern>` | Set robot controller to `<extern>` in Webots |
14+
| MATLAB hangs on init | Webots not running | Start Webots before running MATLAB script |
15+
| Simulation freezes | Time step mismatch | Ensure TIME_STEP matches in both applications |
16+
| No sensor data | Sensors not enabled | Call `wb_*_enable()` for each sensor |
17+
18+
### Data Problems
19+
20+
| Symptom | Cause | Solution |
21+
|---------|-------|----------|
22+
| NaN values | Sensor read before initialization | Wait one TIME_STEP after enabling sensors |
23+
| Zero motor output | Motor not configured | Set position to `inf` for velocity control |
24+
| Incorrect units | Unit conversion error | Check Webots documentation for units |
25+
| Delayed response | Buffering issues | Reduce TIME_STEP value |
26+
27+
---
28+
29+
## Debugging Tools in Simulink
30+
31+
### 1. Add Display Blocks
32+
33+
Use Display blocks to show signal values during simulation:
34+
35+
```
36+
1. Drag Display block from Simulink Library Browser
37+
2. Connect to the signal you want to monitor
38+
3. Run simulation and observe values
39+
```
40+
41+
### 2. Add Scope Blocks
42+
43+
Visualize signals over time:
44+
45+
```
46+
1. Drag Scope block from Simulink Library Browser
47+
2. Connect to signals (position, velocity, control output)
48+
3. Double-click to open scope window during simulation
49+
4. Use zoom and pan to analyze data
50+
```
51+
52+
### 3. Use To Workspace Blocks
53+
54+
Log data for post-simulation analysis:
55+
56+
```matlab
57+
% After simulation, analyze logged data
58+
plot(out.position.Time, out.position.Data);
59+
xlabel('Time (s)');
60+
ylabel('Position (m)');
61+
title('Robot Position vs Time');
62+
```
63+
64+
---
65+
66+
## Step-by-Step Debugging
67+
68+
### Method 1: Single-Step Execution
69+
70+
Run the simulation one step at a time:
71+
72+
```matlab
73+
% Initialize
74+
wb_robot_init();
75+
TIME_STEP = 16;
76+
77+
% Single step with debug output
78+
while wb_robot_step(TIME_STEP) ~= -1
79+
% Read and display sensor values
80+
position = wb_gps_get_values(gps);
81+
fprintf('Step: Position = [%.4f, %.4f, %.4f]\n', position(1), position(2), position(3));
82+
83+
% Check for anomalies
84+
if any(isnan(position))
85+
warning('NaN detected in position!');
86+
break;
87+
end
88+
89+
% Manual pause for inspection
90+
pause(0.1);
91+
end
92+
```
93+
94+
### Method 2: Breakpoints in MATLAB Function Blocks
95+
96+
Set breakpoints inside MATLAB Function blocks:
97+
98+
1. Open the MATLAB Function block
99+
2. Click on the line number to set a breakpoint
100+
3. Run simulation in debug mode
101+
4. Step through code using F10 (step over) or F11 (step into)
102+
103+
### Method 3: Conditional Breakpoints
104+
105+
Stop simulation when specific conditions are met:
106+
107+
```matlab
108+
function y = fcn(sensor_value, threshold)
109+
y = sensor_value;
110+
111+
% Debug: stop if value exceeds threshold
112+
if sensor_value > threshold
113+
keyboard; % Opens debug mode
114+
end
115+
end
116+
```
117+
118+
---
119+
120+
## Solver Configuration Issues
121+
122+
### Verify Solver Settings
123+
124+
```matlab
125+
% Check current solver settings
126+
get_param('model_name', 'Solver')
127+
get_param('model_name', 'FixedStep')
128+
get_param('model_name', 'StopTime')
129+
130+
% Correct settings for Webots integration
131+
set_param('model_name', 'Solver', 'ode4');
132+
set_param('model_name', 'SolverType', 'Fixed-step');
133+
set_param('model_name', 'FixedStep', '0.016');
134+
set_param('model_name', 'StopTime', 'inf');
135+
```
136+
137+
### Algebraic Loop Detection
138+
139+
If you see algebraic loop errors:
140+
141+
1. Open **Model Settings** → **Diagnostics** → **Solver**
142+
2. Set "Algebraic loop" to "warning" temporarily
143+
3. Identify the feedback loop causing the issue
144+
4. Add a Unit Delay block to break the loop
145+
146+
---
147+
148+
## Signal Monitoring
149+
150+
### Create a Debug Subsystem
151+
152+
```matlab
153+
% Create monitoring function
154+
function debug_monitor(position, velocity, control)
155+
persistent step_count;
156+
if isempty(step_count)
157+
step_count = 0;
158+
end
159+
step_count = step_count + 1;
160+
161+
% Log every 100 steps
162+
if mod(step_count, 100) == 0
163+
fprintf('Step %d:\n', step_count);
164+
fprintf(' Position: [%.3f, %.3f, %.3f]\n', position);
165+
fprintf(' Velocity: [%.3f, %.3f, %.3f]\n', velocity);
166+
fprintf(' Control: [%.3f, %.3f, %.3f]\n', control);
167+
end
168+
end
169+
```
170+
171+
### Check Signal Dimensions
172+
173+
Verify signal dimensions match expected values:
174+
175+
```matlab
176+
function y = check_dimensions(input, expected_size)
177+
actual_size = size(input);
178+
if ~isequal(actual_size, expected_size)
179+
error('Dimension mismatch: expected [%s], got [%s]', ...
180+
num2str(expected_size), num2str(actual_size));
181+
end
182+
y = input;
183+
end
184+
```
185+
186+
---
187+
188+
## Model Configuration Checklist
189+
190+
| Setting | Expected Value | How to Check |
191+
|---------|----------------|--------------|
192+
| Solver | Fixed-step | Model Settings → Solver |
193+
| Solver Type | ode4 (Runge-Kutta) | Model Settings → Solver |
194+
| Fixed Step Size | 0.016 | Model Settings → Solver |
195+
| Stop Time | inf | Model Settings → Solver |
196+
| Data Types | double | Signal Properties |
197+
| Sample Time | 0.016 or inherited | Block Parameters |
198+
199+
---
200+
201+
## Performance Profiling
202+
203+
### Enable Simulink Profiler
204+
205+
1. Go to **Debug** → **Performance Advisor**
206+
2. Run simulation with profiling enabled
207+
3. Analyze results to identify slow blocks
208+
209+
### MATLAB Profiler
210+
211+
```matlab
212+
% Profile MATLAB code
213+
profile on
214+
run_simulation();
215+
profile off
216+
profile viewer
217+
```
218+
219+
---
220+
221+
## Error Messages Reference
222+
223+
| Error | Meaning | Solution |
224+
|-------|---------|----------|
225+
| `wb_robot_step returned -1` | Simulation ended or Webots closed | Restart Webots and reconnect |
226+
| `Device not found` | Invalid device name | Check device name in Webots scene tree |
227+
| `Algebraic loop detected` | Feedback without delay | Add Unit Delay block |
228+
| `Index exceeds array bounds` | Array dimension mismatch | Verify signal dimensions |
229+
| `Output dimensions mismatch` | Block output size incorrect | Check MATLAB Function block output |
230+
231+
---
232+
233+
## When Stuck
234+
235+
### Reset Everything
236+
237+
```matlab
238+
% Clear MATLAB state
239+
clear all;
240+
close all;
241+
clc;
242+
243+
% Reload library
244+
bdclose all;
245+
246+
% Restart from clean state
247+
wb_robot_init();
248+
```
249+
250+
### Simplify the Model
251+
252+
1. Create a minimal test case with one sensor and one actuator
253+
2. Verify basic communication works
254+
3. Add components one at a time
255+
4. Test after each addition
256+
257+
### Check Documentation
258+
259+
- [Webots Reference Manual](https://cyberbotics.com/doc/reference/index)
260+
- [Simulink Documentation](https://www.mathworks.com/help/simulink/)
261+
- [Project Examples](../examples/inverted-pendulum.md)
262+
263+
---
264+
265+
## Next Steps
266+
267+
- [ROS 2 Export](export-ros2.md): Deploy your debugged controller on real hardware
268+
- [Troubleshooting](../troubleshooting.md): Additional common issues and solutions

0 commit comments

Comments
 (0)