9.4 KiB
Physical Simulation Plan
Goal: Replace the current manually calculated rudder sweep with a solver-driven simulation in which the macro commands only the servo angle and the physics engine moves the linkage and rudder automatically.
Architecture: FreeCAD remains the CAD source and visualizer. Project Chrono Multibody solves rigid-body motion, joints, motors, contacts, friction, mass, and inertia. Chrono FSI is added later for water and fluid-structure interaction. A bridge transfers the commanded servo angle to Chrono and returns body transforms and diagnostic forces to FreeCAD.
Target repository: org1/rc_yacht
Scope and acceptance criteria
The first milestone is the dry rudder mechanism, not the complete yacht hydrodynamics.
The first milestone must prove:
- the FreeCAD macro sends only a servo target angle;
- the servo motor joint is the only commanded degree of freedom;
- the physics solver moves the horn, pushrod, tiller, rudder stock, and rudder;
- the hull, servo mount, ESP32 tray, and electronics remain fixed;
- the pushrod remains connected at both ends;
- revolute-joint limits are enforced;
- collision detection reports no forbidden intersections across the servo range;
- returned transforms can be displayed in the remote FreeCAD document;
- the result is explicitly classified as solver-driven rigid-body simulation, not as the existing placement sweep.
The later water milestone must additionally prove that Chrono FSI applies water forces to the hull and submerged appendages with a documented fluid domain, resolution, timestep, material model, and convergence checks.
Phase 1: Freeze and inspect the CAD interface
- Treat the current
RudderMechanismgroup as the CAD interface. - Record the coordinate system, units, rotation axes, attachment points, and neutral placements.
- Separate visual CAD shapes from solver collision shapes.
- Define the fixed bodies:
- hull;
- rudder servo housing and mount;
- ESP32 tray and board envelope;
- other structural parts that must not move.
- Define the moving bodies:
- servo horn;
- pushrod;
- tiller;
- rudder stock;
- rudder.
- Add a machine-readable mechanism specification under
parameters/containing body IDs, joint IDs, axes, attachment points, limits, masses, and inertias.
Validation:
- all body IDs resolve to existing FreeCAD objects;
- every joint has explicit frames on both bodies;
- the neutral configuration matches the validated CAD model;
- no body is silently both fixed and dynamic.
Likely files:
parameters/design_parameters.json;- new
parameters/rudder_mechanism.json; MiniMaxHull.FCStd;reports/virtual_simulation_report.json.
Phase 2: Build a Chrono Multibody dry mechanism
- Select the Chrono version and Python/C++ API available on the simulation host.
- Build fixed and dynamic rigid bodies from simplified collision geometry.
- Add a motorized revolute joint for the servo horn.
- Add a revolute joint for the rudder stock.
- Add the pushrod as a rigid body with appropriate endpoint constraints.
- Add the tiller and horn attachment constraints.
- Set masses, centers of mass, inertias, gravity, joint limits, solver tolerances, and timestep.
- Define the servo command as a target angle or target position only.
- Record solver positions, velocities, constraint errors, reaction forces, and collision events at every timestep.
Validation:
- at servo angle zero, the solver configuration matches the CAD neutral pose;
- the solver can reach both mechanical endpoints;
- constraint errors remain below a defined tolerance;
- the pushrod length remains within the declared tolerance;
- fixed bodies have zero velocity and zero displacement;
- no forbidden collision occurs.
Likely files:
- new
simulation/chrono_rudder.pyorsimulation/chrono_rudder.cpp; - new
simulation/chrono_model.py; - new
simulation/requirementsor build configuration; - new solver diagnostics under
reports/.
Phase 3: Connect the solver to FreeCAD
- Define a small bridge protocol carrying:
- model identifier;
- servo target angle;
- simulation timestep or number of steps;
- returned body transforms;
- joint errors;
- reaction forces;
- collision results;
- solver status.
- Keep the physics process independent from the FreeCAD GUI process.
- Use the existing remote FreeCAD XML-RPC access only for CAD inspection and transform application, unless a direct local bridge is proven more reliable.
- Replace the current manual Placement loop with a bridge client that sends the servo angle.
- Apply only solver-returned transforms to moving FreeCAD objects.
- Keep static FreeCAD objects unchanged and verify their placements before and after each step.
- Add a dry-run mode that uses a deterministic mock solver for bridge testing.
Validation:
- changing the macro input changes only the servo command;
- the FreeCAD macro does not calculate the rudder angle from the servo angle;
- every moving transform comes from solver output;
- a disconnected or failed solver produces
FAIL, not a plausible-looking CAD motion; - repeated runs with the same initial state and command produce reproducible results.
Likely files:
scripts/RudderMotionSweep.FCMacro;- new
scripts/ChronoRudderBridge.FCMacro; - new
simulation/bridge_protocol.py; reports/virtual_simulation_report.json.
Phase 4: Add collision and contact qualification
- Use simplified collision shapes for solver stability.
- Use the detailed FreeCAD B-rep shapes for post-step geometric intersection checks.
- Check collisions at every solver step, not only at endpoint angles.
- Distinguish intended interfaces from forbidden collisions.
- Record minimum clearances and maximum intersection volumes.
- Test the mechanism with nominal and perturbed joint geometry.
- Test servo range, hard-stop range, and out-of-range commands.
Acceptance:
- forbidden collision volume is zero or below a documented numerical tolerance;
- intended interfaces are listed separately;
- joint limits prevent impossible configurations;
- the mechanism fails safely when constraints cannot converge.
Phase 5: Add Chrono FSI for the water model
Chrono FSI is a later layer, not a replacement for Chrono Multibody. The FSI module must be evaluated using the actual Chrono build and backend available on the simulation host.
- Select the FSI backend and document whether the model uses SPH or TDPF.
- Create a fluid domain with documented dimensions and resolution.
- Define water density, viscosity, gravity, free-surface level, and initial conditions.
- Couple the hull and appendages to the fluid solver.
- Include the mass, inertia, center of gravity, and ballast configuration from the CAD qualification model.
- Start with a static buoyancy test.
- Add controlled rudder motion in still water.
- Add prescribed wind and wave inputs only after the static and still-water tests converge.
- Compare buoyancy, draft, pitch, roll, and rudder forces with the existing preliminary estimates.
- Record timestep, particle spacing or grid resolution, boundary conditions, convergence criteria, and computational cost.
FSI acceptance is not established by a running animation. It requires mesh/particle and timestep sensitivity evidence plus comparison to a known static or analytical result.
Likely files:
- new
simulation/chrono_fsi_hydrostatics.pyor C++ equivalent; parameters/design_parameters.json;- new
parameters/fsi_parameters.json; reports/virtual_simulation_report.json;- new
docs/chrono_fsi_validation.md.
Phase 6: Verification and reporting
Run the following checks before classifying the result as qualified:
python3 -m json.tool reports/virtual_simulation_report.json
git diff --check
FreeCAD geometry validation
Chrono solver convergence validation
Joint-limit validation
Pushrod-length validation
Fixed-body displacement validation
Forbidden-collision sweep
Repeatability run
Report separate statuses:
cad_geometry
kinematic_reference
chrono_multibody
bridge
contact_and_collision
chrono_fsi
physical_validation
The overall status must remain PASS_WITH_REVIEW until the solver and FSI results are independently validated against physical measurements.
Risks and decisions
- Chrono FSI is a separate solver module, not a FreeCAD workbench button.
- FSI does not automatically create the servo linkage; Multibody joints must be defined first.
- A visually plausible animation is not evidence of physical correctness.
- FreeCAD B-rep geometry should not be used blindly as high-resolution collision geometry.
- The current SG90 model is an envelope, not a validated motor torque model.
- The current water and wind calculations are preliminary and cannot serve as full FSI validation.
- The remote FreeCAD host may not have Chrono, its Python bindings, or the required FSI backend installed.
- The first implementation should therefore be a dry Chrono Multibody proof before any FSI installation or water simulation.
Definition of done
The plan is complete only when:
- a reproducible Chrono Multibody environment is available;
- the servo angle is the only command issued by the FreeCAD macro;
- Chrono moves the remaining mechanism bodies through constraints;
- FreeCAD displays the solver transforms;
- joint errors, contacts, collisions, and fixed-body invariants are recorded;
- Chrono FSI is separately enabled and validated for the water phase;
- all limitations and numerical parameters are recorded in the repository report.