aactuator
LEARN / CONTROL ENGINEERING

From an angle command
to current, torque, and motion.

A moving 3D model is only the last link. Follow the signals, the feedback loops, and the limits that determine what the actuator actually does.

01 / ONE CLOSED LOOP, DIFFERENT TIME SCALES

What happens after you move the slider?

Select a block to see its input, output, units and implementation. Solid arrows carry commands or physical effects; the dashed return carries measured feedback. A load acts on mechanics, not directly on the current reference.

Closed-loop electromechanical pipelineCommand enters the 1 kHz outer loop, torque maps to current, 20 kHz current control generates voltage, SVPWM generates duty, inverter drives PMSM and gearbox. Sensors return currents and rotor and output states. External load enters the gearbox and protection inhibits the inverter. Command → outer loopq*, ω*, τff · 1 kHzOutput torque τ* [N·m] Torque → currentiq* = τ* / (N Kt)Current circle + derating d/q current controllerReference − feedbackvd, vq [V] · 20 kHz Limit + SVPWMInverse Park + Clarkeda, db, dc [0–1] Three-phase inverterDC bus → phase voltageGate state / diode paths PMSM + gearboxElectrical + mechanical ODECurrent, torque, q, ω Sensors + transformsFilter, ADC, encoder agesia,b,c → iα,β → id,q Independent protectionPhase-current thresholdBREAK → gates OFF Delayed current / rotor and output feedback Phase current before ADC delayLoad / stop reaction [N·m] Inhibit is not a torque command. Physics continues after shutdown. Vbus [V]
Conceptual signal flow, not circuit wiring. On small screens, scroll the diagram; the numbered outline below remains readable.
1 kHz / Command → τ* [N·m]

The outer loop decides how hard to push

Position and speed are output-shaft quantities. Impedance combines position error, velocity error and feed-forward torque; position mode instead drives a speed loop. Drive::tick → servo_count_ / mode switch.

20 kHz / τ* → id*, iq* [A]

Torque must become a feasible current request

The default map uses id*=0 and the controller's nominal flux and 6:1 ratio. Current mode bypasses torque conversion but not current limits. A wrong Kt can cause torque error even when current tracks perfectly.

20 kHz / idq* − idq → vdq [V]

Regulate measured current, not an ideal state

PI adds cross-coupling and back-EMF feed-forward. The alternative is a relaxed one-step predictor with integral bias; it is not constrained MPC. PiFoc / PredictiveCurrent.

20 kHz / vdq → three duties

Voltage is limited before modulation

A circular voltage limit precedes inverse transforms and zero-sequence injection. The final limited vector is fed back to anti-windup. Duty is dimensionless, not torque or amperes. svpwm().

Electrical substeps ≤5 μs / duty → phase voltage

The inverter, not the renderer, energizes the motor

The live browser uses the averaged bridge with conduction and dead-time effects. The native bench also has a switched model. Gate-off does not imply instantaneous zero current: diode paths remain. Inverter / advance_bridge.

SI physical state / no direct pose command

Motion follows current and load

dq electrical equations generate torque. Two inertias are linked by a compliant gearbox with backlash. The browser owns 1-axis mechanics; the external MuJoCo mode delegates both inertias and all poses to MuJoCo. Ownership diagram →

Mid-carrier sampling / phase currents + encoder

The controller receives a delayed observation

Filtering, noise, quantization, offset and latency sit between plant and controller. The sample-time angle is used for Park; a separate predicted angle is used for PWM. Dashboard plant-state plots are not raw ADC or controller-estimated currents.

Independent event schedule / latch → inhibit

Protection does not wait for the next FOC tick

FastTrip models comparator, blanking, BREAK and gate delay. Current crossings are observed at integration endpoints, so detection accuracy is bounded by the step. This is a virtual contract, not STM32 instruction timing or a safety-certified board.

02 / WHICH ERROR ARE YOU CONTROLLING?

Position, velocity and impedance are different promises.

ModeWhat the outer loop requestsUseful observation
Currentid*, iq* directly [A]No output-position regulation.
Torqueτ* = τff [output N·m]Nominal Kt map; not a torque-sensor feedback loop.
VelocityPI on ω* − ω [rad/s]A blocked joint requests torque up to its limit.
PositionSpeed request 10(q*−q)+ωff, then speed PIVelocity integral can reject a constant load.
Impedanceτ* = τff + Kp(q*−q) + Kd(ω*−ω)Behaves as a virtual spring and damper.
Kp [N·m/rad] · Kd [N·m·s/rad] At rest, away from saturation, friction and contact: q ≈ q* − τload / Kp

Try q*=0.4 rad, Kp=30 N·m/rad, and a +2 N·m load. The ideal equilibrium is 0.3333 rad. Increasing Kp reduces static deflection but raises torque demand and does not remove current, voltage, or delay limits. Run the load experiment →

Sign convention: the native plant subtracts positive external load from output torque. A reverse-side stop has a negative load reaction, so it pushes the shaft in the positive direction. A negative velocity is physical reverse rotation, not backward integration in time.

03 / WHY CHANGE COORDINATES?

AC phase currents become nearly DC in a rotating frame.

The electrical angle is θe = p θrotor, where p=7 pole pairs in this synthetic profile. It is not the output angle: the gearbox and its elastic deflection separate those coordinates. The d axis aligns with magnet flux; q is perpendicular. These are amplitude-invariant transforms, with the convention used in math.hpp.

Interactive electrical reference frameChange electrical angle to rotate d and q axes. The current vector has id zero and iq four amperes; phase currents vary but dq values stay fixed.αβdqid = 0 A · iq = 4 A · not live telemetry
ia = 0.000 A · ib = 3.464 A · ic = −3.464 A

The transform actually used

iα = (2ia − ib − ic) / 3 iβ = (ib − ic) / √3 id = cos θe · iα + sin θe · iβ iq = −sin θe · iα + cos θe · iβ

With balanced sinusoidal phases and id=0, iq is a phase-peak-equivalent amplitude, not phase RMS. In this convention, dq power is 1.5(vd id + vq iq). Omitting 1.5 or mixing RMS with peak changes the inferred power and torque.

This interactive calculation is an explanatory diagram. It does not modify the live controller.

The electrical plant behind the animation

did/dt = (vd − R id + ωe Lq iq) / Ld diq/dt = (vq − R iq − ωe(Ld id + ψ)) / Lq τem = 1.5 p [ψ iq + (Ld − Lq) id iq]

For id=0, Kt = 1.5pψ = 0.1155 N·m/A with nominal ψ=0.011 Wb. A 4 N·m output request through an ideal 6:1 ratio asks for about 5.772 A before limiting. That is a nominal conversion, not measured output-torque accuracy. The actual gearbox includes dynamics and losses. id=0 is the implemented baseline, not a claim of MTPA optimality for a salient motor.

04 / MORE GAIN IS NOT ALWAYS MORE CONTROL

Tuning must include saturation and latency.

The default PI design uses ωc=2π·600 rad/s, Kpd=Ldωc, Kpq=Lqωc and Ki=Rωc. Feed-forward cancels modeled d/q cross-coupling and back-EMF. The 600 Hz setting is a design parameter, not a measured closed-loop bandwidth for every operating point.

vd = Kpd ed + ∫Ki ed dt − ωe Lq iq vq = Kpq eq + ∫Ki eq dt + ωe(Ld id + ψ) |v*dq| ≤ Vbus / √3 × (1 − 2m), m = 0.02

At 48 V, the available vector magnitude is about 26.60 V. SVPWM applies common-mode injection after inverse transforms. PI back-calculation receives the final limited vector, not independently clipped d and q values. Current-circle limiting and thermal derating happen before voltage generation.

SymptomCheck firstDo not confuse it with
Angle stops trackingContact, current limit, torque limit, voltage saturationA renderer problem
Current rings after a changeR/L mismatch, sample age, PI bandwidthA need for maximum gain
Current is right; torque is wrongFlux/Kt, ratio, losses, current normalizationA current-loop accuracy result
Fault at high speedDC-bus regeneration, overcurrent and sensor validityA software crash to hide by resetting

The native stress profiles keep controller parameters separate from plant parameters. Use profiles/mismatch_RL.ini and profiles/linear_delay8.ini for research; changing a controller parameter is not the same as changing the simulated motor. CLI examples →

05 / A SAMPLE HAS AN AGE

One 50 μs period, not one instantaneous calculation.

Browser simulation sampling and update scheduleAt time zero the controller uses the preceding current sample, computes duty, and advances inverter and plant in steps of at most five microseconds. The next current capture occurs at twenty-five microseconds. The next control tick is fifty microseconds. Telemetry and outer servo use one millisecond intervals.Simulation time0 μs25 μs50 μsDrive::tickRead → FOC → dutyNext tickPlant + protectionSubsteps ≤5 μs; split at scheduled boundariesCurrent captureStore for a later control tickOuter servo every 20 ticks · UI telemetry every 20 ticks · +1 ms runs 20 ticks
Default browser path. Drawing is not STM32 execution time. Additional configured delay and filtering increase observation age.
θsample = p[θenc + ωenc(ageenc − agecurrent)] θPWM = p[θenc + ωenc(ageenc + Δt/2)]

The first angle aligns current measurements at their sample time. The second predicts rotor orientation for the voltage command. Those predictions use measured speed; they do not magically remove noise, model error or acceleration within the interval.

Fault handling is a state machine, not a red label.

Drive state and latched faultDisabled goes to calibrating, then ready, then armed. Faults inhibit gates and require acknowledgement while disabled and subsequent recalibration. Reset in the web UI creates a new instance instead of acknowledging hardware.DisabledCalibrating (64 samples)ReadyArmedFault latched · gates inhibitedNo auto-rearm
The native Drive acknowledges a fault only with valid input and enable/arm false. The browser Reset button discards the virtual experiment instead.

FastTrip observes phase current independently of the delayed ADC loop and schedules comparator, BREAK and gate-off events. A 5 μs integration grid still bounds crossing detection; configured sub-microsecond delays are not proof of sub-microsecond hardware response. BoardPort specifies future BSP responsibilities but does not implement them.

06 / THE MODEL MUST REMEMBER WHICH SIDE IS FREE

Why reverse rotation previously passed through the stop.

The old test was simply q > 0.60. Negative multi-turn motion never satisfied it, although the rendered pose repeats every 2π. The link could meet the back of the orange object with no reaction torque.

The browser now derives the blocked angular interval from the actual MJCF tip-sphere and link-capsule collision proxies against the stop box. Its boundaries are approximately 0.600000 and 1.101915 rad modulo 2π. When enabled at the default pose, the connected free arc is −5.181270 to +0.600000 rad. Crossing either boundary produces an opposing signed spring-damper reaction. The interval stays anchored during contact, so the solver cannot switch to the other side of the obstacle.

Front face: R = max(0, Ks(q − qmax) + Ds ω), q > qmax Reverse face: R = −max(0, Ks(qmin − q) − Ds ω), q < qmin Output dynamics subtract R. Free arc: R = 0. Ks = 6000 N·m/rad · Ds = 25 N·m·s/rad

No angle is clamped for appearance and no motor parameter was changed. Finite compliance still permits small deflection: this is not zero-penetration rigid contact. Enabling a stop while the link occupies its solid interval is rejected without teleportation or killing the running experiment.

In the lab, use Collision envelopes to inspect the conservative collision proxies around the machined visual link. Only this reduced 1-axis stop is active in browser physics. Arbitrary 3D collisions, frictional contact and free-body impacts belong to the native MuJoCo examples, not to Three.js.

Continue with signals, then code.

Signals & losses connects these equations to native current, gate, power and thermal traces. Code & API owns integration details. The annotated primary-source guide explains which reference supports each method and where it stops.

Underlying methods: FOC [1], PMSM equations [2], SVPWM [3], anti-windup [4], STM32 shutdown [10]. Source-linked implementation and fidelity boundaries remain the authority for this lab.