1. Introduction

Mechatronic design couples mechanical dynamics, electronics, and control, and errors in any one layer surface only when the layers run together. Real-time simulation lets a designer close the control loop against realistic dynamics before committing to hardware, and hardware-in-the-loop (HIL) testing lets the same controller drive a simulated plant at full rate [1], [2]. These techniques are standard in industry but are usually locked inside heavyweight commercial tools that are hard to inspect and to teach from [3].

We present an open-source Python framework that keeps hard real-time behaviour while staying small enough to read in an afternoon. Our contributions are: (i) a minimal module interface that composes mechanical, electrical, and control subsystems into a single fixed-step system; (ii) a deterministic solver with a measured timing budget; and (iii) an HIL bridge that swaps a simulated subsystem for real hardware without changing the rest of the model.

2. Related work

Block-diagram environments such as Simulink and Modelica are expressive but proprietary and opaque to students [3]. Robotics simulators such as Gazebo target rigid-body scenes rather than mixed electrical-mechanical-control models and do not guarantee a fixed real-time step [4]. Lightweight Python control libraries provide excellent analysis but stop at offline simulation [5]. Our framework occupies the gap: open, readable, and real-time, with a first-class HIL path.

3. Framework architecture

A model is a directed graph of modules. Every module implements the same interface, so the solver treats a spring-mass plant, a motor driver, and a PID controller identically:

• reset(): set initial state;

• step(inputs, h): advance the module by one step of size h and return outputs;

• outputs are wired to inputs to form the system graph.

Because the contract is this small, a subsystem can be reimplemented in C for speed, or replaced by real hardware over the HIL bridge, without touching its neighbours.

4. Real-time solver

Each module exposes continuous dynamics $\dot{x} = f(x, u)$ that the solver integrates with a fixed step $h$. We use the classical fourth-order Runge-Kutta update

$$x_{k+1} = x_k + \tfrac{h}{6}\,(k_1 + 2k_2 + 2k_3 + k_4),$$

which gives fourth-order local accuracy at a fixed, predictable cost per step, so the per-step time is bounded and schedulable [6]. The loop must satisfy the real-time constraint

$$t_{\text{sim}} + t_{\text{io}} + t_{\text{ctrl}} \le h,$$

where the three terms are the integration, input/output, and control times. We schedule the loop against a monotonic clock and record the jitter $j_k = (t_k - t_{k-1}) - h$ to verify the budget is met.

5. Case study: a two-wheeled balancing robot

Linearised about the upright equilibrium, the robot is a fourth-order plant $\dot{x} = Ax + Bu$ with state $x = [\theta, \dot{\theta}, p, \dot{p}]^{\top}$ (body angle, angular rate, position, velocity). We stabilise it with a linear-quadratic regulator $u = -Kx$, where $K$ minimises

$$J = \int_0^{\infty} \left(x^{\top} Q x + u^{\top} R u\right)\,dt.$$

The controller and plant run as two modules at $h = 1\,\text{ms}$; a third module streams state to a browser dashboard over a non-blocking queue so visualisation never steals from the control budget.

6. Results

On a single-board computer the framework sustained the one-kilohertz loop for two hours. Table 1 summarises timing across three plant complexities; even the coupled model kept mean jitter well under the step and mean CPU below half a core.

With the motor subsystem replaced by real hardware over the HIL bridge, the closed loop remained stable and the added input/output time stayed within the budget of equation (2).

7. Discussion and conclusion

The framework shows that hard real-time mechatronic simulation does not require a heavyweight toolchain: a small, uniform module interface plus a fixed-step Runge-Kutta solver is enough for both teaching and prototyping. The main limitation is single-node execution; distributing modules across cores while preserving determinism is future work. The framework, the balancing-robot model, and every figure in this paper are released as open source [7].