add docstrings

Author: baggepinnen

ext/Render.jl

@@ -814,7 +814,7 @@ function render!(scene, ::Union{typeof(P.Spring), typeof(P.SpringDamper)}, sys,
     true
 end
 
-function render!(scene, ::Union{typeof(P.Wheel), typeof(P.SlipBasedWheelJoint)}, sys, sol, t)
+function render!(scene, ::Union{typeof(P.SimpleWheel), typeof(P.SlipBasedWheelJoint)}, sys, sol, t)
 
     r_0 = get_fun(sol, [sys.frame_a.x, sys.frame_a.y])
     rotfun = get_rot_fun_2d(sol, sys.frame_a)

src/PlanarMechanics/PlanarMechanics.jl

@@ -17,6 +17,7 @@ export Frame, FrameResolve, PartialTwoFrames, ZeroPosition, ori_2d
 include("utils.jl")
 
 export Fixed, Body, FixedTranslation, Spring, Damper, SpringDamper
+export SlipBasedWheelJoint, SimpleWheel
 include("components.jl")
 
 export Revolute, Prismatic

src/PlanarMechanics/components.jl

@@ -414,6 +414,27 @@ Linear 2D translational spring damper model
 end
 
 
+"""
+    SimpleWheel(; name, radius = 0.3, color = [1, 0, 0, 1], μ = 1e9)
+
+Simple wheel model with viscous lateral friction and a driving torque
+
+# Connectors:
+- `frame_a` (Frame) Coordinate system fixed to the component with one cut-force and cut-torque
+- `thrust` (RealInput) Input for the longitudinal force applied to the wheel
+
+# Parameters:
+- `μ`: [Ns/m] Viscous friction coefficient
+- `radius`: [m] Radius of the wheel
+- `color`: Color of the wheel in animations
+
+# Variables:
+- `θ`: [rad] Wheel angle
+- `Vx`: [m/s] Longitudinal velocity (resolved in local frame)
+- `Vy`: [m/s] Lateral velocity (resolved in local frame)
+- `Fy`: [N] Lateral friction force
+- `Fx`: [N] Applied longitudinal wheel force
+"""
 @mtkmodel SimpleWheel begin
     @structural_parameters begin
         friction_model = :viscous
@@ -503,7 +524,43 @@ end
 @register_symbolic limit_S_triple(x_max::Real, x_sat::Real, y_max::Real, y_sat::Real, x::Real)
 @register_symbolic limit_S_form(x_min::Real, x_max::Real, y_min::Real, y_max::Real, x::Real)
 
+"""
+    SlipBasedWheelJoint(;
+        name,
+        r = [1, 0],
+        N,
+        vAdhesion_min,
+        vSlide_min,
+        sAdhesion,
+        sSlide,
+        mu_A,
+        mu_S,
+        render = true,
+        color = [0.1, 0.1, 0.1, 1],
+        z = 0,
+        diameter = 0.1,
+        width = diameter * 0.6,
+        radius = 0.1,
+        w_roll = nothing,
+    )
+
+Slip-based wheel joint
+
+The ideal wheel joint models the behavior of a wheel rolling on a x,y-plane whose contact patch has slip-dependent friction characteristics. This is an approximation for wheels with a rim and a rubber tire.
+
+The force depends with friction characteristics on the slip. The slip is split into two components:
+
+- lateral slip: the lateral velocity divided by the rolling velocity.
+- longitudinal slip: the longitudinal slip velocity divided by the rolling velocity.
 
+For low rolling velocity this definition become ill-conditioned. Hence a dry-friction model is used for low rolling velocities. For zero rolling velocity, the intitialization might fail if automatic differentiation is used. Either start with a non-zero (but tiny) rolling velocity or pass `autodiff=false` to the solver.
+
+The radius of the wheel can be specified by the parameter `radius`. The driving direction (for `phi = 0`) can be specified by the parameter `r`. The normal load is set by `N`.
+
+The wheel contains a 2D connector `frame_a` for the steering on the plane. The rolling motion of the wheel can be actuated by the 1D connector `flange_a`.
+
+In addition there is an input `dynamicLoad` for a dynamic component of the normal load.
+"""
 @component function SlipBasedWheelJoint(;
     name,
     r = [1, 0],