BLDC framework system specification¶
Public system requirements and interface contract.
Objective and existing baseline¶
The BLDC framework provides Hall and sensorless six-step control, typed data, shared algorithm library components, an independently validated host plant, and autoMBD HSP 0.1.0 target generation and PIL for S32K144 and S32K344. Normal and SIL remain the host functional and numerical references.
Requirements¶
| ID | Requirement and observable completion evidence |
|---|---|
| B1 | A repository-relative ambd_mc("setup","bldc") initializes types, persistent dictionary and calibrations in a fresh session, repeatedly without destructive reset; Markdown and generated types agree. |
| B2 | BLDCFramework preserves McKernel, McTuning, McEventHub, McFault, McStateMachine, McDataFlow and McDebug responsibilities; BldcControllerLibrary shares the algorithm and application wrappers own native API calls. |
| B3 | Explicit single-precision controller state at the selected fast rate (16 kHz host/S32K344, 8 kHz S32K144); integer divide-by-16 or divide-by-8 speed loop at 1 kHz; fault/reset priority and disabled outputs deterministic even without a driving tick. |
| B4 | Hall six-step uses measured Hall edges for sector/direction/speed, including invalid codes, illegal transitions and timeout diagnostics. Sensorless control uses sampled terminal voltages, currents and the actual prior commutation state, without rotor speed/angle or internal BEMF truth. |
| B5 | Alignment, forced-current startup, qualified zero crossing, 30-degree delayed commutation, closed-loop run, controlled stop, reversal/restart, protection, explicit safe reset and declared low-speed behavior are exercised. Loss of qualified feedback cannot silently sustain uncontrolled drive. |
| B6 | Anti-windup speed PI and current PI regulate positive motoring current in the selected direction; bounded current reference and bipolar modulation; complementary active legs and one floating leg. Every run checks no simultaneous physical high/low gate command, current envelope, finite outputs and safe fault disable. |
| B7 | Independent phase-domain trapezoidal motor/inverter validation includes RL and coast analytic oracles, torque/power consistency, Kirchhoff current conservation, commutation continuity, diode/float terminal behavior, integration-step convergence and a MathWorks native physical comparison. |
| B8 | Hall and sensorless host top models run Normal and actual ERT C SIL. Record exact input replay, source/harness hashes, compiler and executed EXE evidence. Both loops pass physical criteria independently. |
| B9 | Full scenario matrix covers signed speed, load/bus disturbance, stop/restart, reversal, startup/transition stop, current saturation/recovery, invalid Hall/stall, external/bus/overcurrent faults, sensorless acquisition/loss and parameter variation. Negative tests prove the acceptance checks reject invalid traces. |
| B10 | Fresh-session scripts reproduce results below .agent-env; both motor families pass their regression suites, with source hashes and actual execution evidence recorded for each validation run. |
Quantitative acceptance¶
The following values describe the generic host baseline. Kit-specific current, voltage, motor and timing calibrations are selected by the target profile and require their own electrical-reference and hardware acceptance.
- Feasible steady operating points: electrical-speed mean error no greater than max(5 rad/s, 5% of requested magnitude), ripple peak-to-peak no greater than 15% of request or 10 rad/s; directional overshoot at most 20% after acquisition. Startup alignment is evaluated separately from commanded steady-speed windows.
- Current reference at most 6 A; measured phase-current envelope below 9.9 A in ordinary scenarios, and 10 A trip faults disable by the next fast sample. Fault injection may intentionally exceed the envelope only in its declared window.
- Voltage bounds 8–16 V, nominal 12 V; invalid/nonfinite measured inputs fault. Invalid Hall codes 0/7 and nonadjacent sector changes fault in Hall mode.
- Stops/reversals must reach the declared idle/coast criterion within 1.5 s; no opposite drive while prior-direction speed remains above the stop threshold. A low sensorless request is declared forced-commutation operation; it is never reported as observed closed-loop regulation. A lost ZC sequence while closed-loop drives safely to fault/disable, with an explicit timeout and no auto-restart.
- Replay: status, fault, sector, masks, timing, integer diagnostics and PWM counts exact; floating outputs abs 1e-5 + rel 1e-5. Record strict bitwise equality also. No post-result tolerance relaxation without a documented physical rationale.
- Independent closed-loop Normal/SIL drift limits: 1 electrical rad/s speed, 0.1 A phase current and 1e-3 modulation; faults/masks/gate exact. These budgets are smaller than the physical performance allowance and do not replace it.
External boundary¶
All inputs/outputs execute at the selected model period: 62.5 us for the generic host/S32K344 baseline and 125 us for S32K144. Electrical angle increases in the declared A-B-C forward direction; electrical speed equals pole pairs times mechanical speed.
| Input | Type / units | Meaning |
|---|---|---|
| CurrentRaw | uint16[3], ADC counts | Phase currents into motor; offset 32768, 1000 count/A |
| Hall | uint8 | Encoded Hall signals, LUT specified in architecture; ignored in sensorless mode |
| TerminalVoltage | single[3], V | Sampled terminal voltages relative to DC negative, aligned with current |
| Control | uint8 | 0 safe reset, 1 run, 2 controlled stop |
| Fault | boolean | External protection request |
| CommandEvent, DrivingEvent, TimerEvent | boolean each | Synchronous command latch, fast tick and timing event |
| SpeedReq | single, electrical rad/s | Signed request, clamp to ±250 |
| Vdc | single, V | DC bus measurement for the sampled interval |
| AppliedSector | uint8 | Sector active during the measured interval, 0 if disabled |
| AppliedDirection | int8 | Source/sink orientation during the measured interval, ±1 |
| VoltageValid | boolean | Whether terminal voltage is a usable aligned acquisition |
| Output | Type | Meaning |
|---|---|---|
| DutyA, DutyB, DutyC | uint16 each | High-side timer counts, period 65535 |
| PhaseEnable | boolean[3] | Enabled leg uses complementary high/low PWM; false means both switches off |
| GateEnable | boolean | Global enable; false overrides all phases |
| Debug | typed bus | Versioned fixed-size diagnostics |
| Monitor | typed bus | State, faults, feedback, requests, PI/commutation/timing diagnostics |
Controller defaults use Hall mode (PositionMode=0); sensorless mode is 1.
Mode choice and startup/gain calibrations are latched only while disarmed.
Plant parameters are separate from controller calibrations for mismatch testing.
Operating domain and exclusions¶
Virtual motor parameters come from this repository's PMSM baseline for controlled comparison: phase R=0.56 ohm, nonsalient phase L=0.4 mH, pole pairs=2, flux constant=0.0039052261 Wb, J=1.2e-5 kg m², B=0.0005 N m s/rad. These are declared simulation assumptions, not measured BLDC identification. The phase BEMF coefficient per mechanical speed is p*flux, torque is its dot product with normalized trapezoid and phase currents. Host Normal/SIL uses Windows x64 generated C. Target generation and PIL use the HSP target integration. Physical current calibration, gate waveforms, loaded motor operation and normal-run WCET require separate hardware verification; configuration or PIL alone does not establish these results.
References¶
MathWorks documents terminal-voltage ZC detection, alignment/open-loop acquisition, demagnetization blanking and 30-degree commutation delay in Sensorless Six-Step Commutation. The controller here is independently authored, not a copied example. The BLDC physical block supplies an independent oracle for three-phase trapezoidal flux dynamics. Local R2026a API and parameter behavior must be inspected before building that reference harness.