# Data Structures

## Project status

The current workspace contains Simulink S-function code and a C2000/TMS320 motor-control implementation. It does not contain a verified STM32G474CEU6 CubeMX/Keil project. New STM32-safe wrapper structures are placed in `Core/Inc/ad_parameter_identification.h` and `Core/Inc/simulink_interface.h`.

## Main structures and globals

| Name | Type | File | Purpose | Fields | Used by | Simulink mapping | Notes |
|------|------|------|---------|--------|---------|------------------|-------|
| `AD_MotorParameters_t` | `struct` | `Core/Inc/ad_parameter_identification.h` | Portable AD parameter set | `Rs_ohm`, `Rr_ohm`, `Ls_H`, `Lr_H`, `Lm_H`, `Ll_H`, `J_kg_m2`, `B_Nm_s`, nominal values, `valid_mask` | ParamID, Simulink wrapper, telemetry | Should become a Simulink Bus Object | Values are not invented; `valid_mask` marks known fields |
| `AD_Measurements_t` | `struct` | `Core/Inc/ad_parameter_identification.h` | Runtime measurements from MCU | `ia_A`, `ib_A`, `ic_A`, `vdc_V`, phase voltages, speed, slip, temperature, timestamp, status flags | ParamID, Simulink wrapper, telemetry | Simulink input bus from MCU to model | ADC scaling/pin sources are TODO for STM32 |
| `AD_Command_t` | `struct` | `Core/Inc/ad_parameter_identification.h` | Commands from Simulink/host | `enable`, `test_mode`, `reset_faults`, limits | Simulink wrapper, ParamID | Simulink output bus from model to MCU | Power tests blocked unless explicitly enabled in compile-time config |
| `AD_ParamID_SafetyLimits_t` | `struct` | `Core/Inc/ad_parameter_identification.h` | Software safety thresholds | Current, voltage, temperature, speed, timeout | ParamID safety checks | Can be filled from Simulink command or calibration | Zero means UNKNOWN/disabled for that limit |
| `SimulinkInterface_InputBus_t` | `struct` | `Core/Inc/simulink_interface.h` | MCU-to-Simulink wrapper data | Measurements, parameters, ParamID status/fault/mode | `SimulinkInterface_*` | Simulink input Bus Object | Stable wrapper, no generated-code edits |
| `SimulinkInterface_OutputBus_t` | `struct` | `Core/Inc/simulink_interface.h` | Simulink-to-MCU wrapper data | Command, telemetry state | `SimulinkInterface_*` | Simulink output Bus Object | Contains `AD_Command_t` |
| `SimulinkTelemetryPacket_t` | `struct` | `Core/Inc/simulink_interface.h` | Binary telemetry packet | Header + payload | `SimulinkInterface_PackTelemetry` | Optional UART/CAN/USB payload | CRC16 over payload |
| `Estimate_Test_t` | `enum` | `Inu/estimate.h` | Existing identification state | `IDLE`, `RS`, `RR_L`, `LM`, `DONE` | `estimate.c`, `upr.c` | Indirect via S-function output/status | C2000/S-function reference |
| `Params_t` | `struct` | `Inu/estimate.h` | Existing estimated AD params | `Rs`, `Rr`, `Lm`, `Lk`, `Lls`, `Llr`, `Zk`, `Rk`, `Xk` | `estimate.c` | No direct Bus Object found | Candidate mapping to `AD_MotorParameters_t` |
| `RsState_t` | `struct` | `Inu/estimate.h` | Existing Rs test state | step, timers, averaged U/I | `process_Rs` | Not directly exported | Existing method: two DC current levels |
| `RrlState_t` | `struct` | `Inu/estimate.h` | Existing rotor/leakage test state | frequency sweep, RMS sums, averages | `process_RrL` | Not directly exported | Existing method: AC current injection |
| `LmState_t` | `struct` | `Inu/estimate.h` | Existing magnetizing test state | integration state, averaging | `process_Lm` | Not directly exported | Existing method: integrate `V - Rs*I` |
| `struct SgmPar` | `struct` | `Inu/def.h:465` | Runtime AD model parameters | `Rs`, `Lls`, `Rr`, `Llr`, `Lm`, derived `Ls`, `Lr`, `SigmaLs`, `Tr`, `Kl` | `detcoeff.c`, `upr.c`, `isr.c` | Values initialized in S-function setup | Existing AD parameter source |
| `struct Result` | `struct` | `Inu/def.h:400` | Raw ADC results after offsets | `udc1`, `ic1`, `ia1`, etc. | `isr.c` | Simulated through wrapper inputs | MCU runtime measurement state |
| `struct Offset` | `struct` | `Inu/def.h:357` | ADC offset calibration | current and `Udc` offsets | `detcoeff.c`, `isr.c`, `controller.c` | Parameters in S-function setup | Must be replaced by STM32 ADC calibration |
| `struct Mst` | `struct` | `Inu/def.h:343` | Commands from upper controller | start, fault reset, mode, speed/power refs, limits | `controller.c`, `isr.c`, `upr.c` | Existing S-function input vector | Maps partly to `AD_Command_t` |
| `struct Protect` | `struct` | `Inu/def.h:383` | Existing protection thresholds/state | current, voltage, speed limits and timers | `isr.c`, `detcoeff.c` | Initialized from `param[]` | Maps partly to safety limits |
| `struct Out` | `struct` | `Inu/def.h:370` | Filtered output values | `udc1`, `iac1`, `wm`, `me`, `pm` | `isr.c` | Existing S-function outputs | Telemetry candidate |
| `struct Emerg` | `struct` | `Inu/def.h:298` | Fault snapshot | voltage, current, torque, speed, power | `snapshot_emergency` | Not directly mapped | Useful for telemetry fault frame |
| `struct Cc`, `Cf`, `Csp` | `struct` | `Inu/def.h` | Current/flux/speed-power regulators | PI terms, limits, feed-forward | `upr.c` | Internal only | Runtime MCU control state |
| `struct Ivc`, `Ip` | `struct` | `Inu/def.h` | Vector-control transforms | slip, angle, sin/cos, currents, flux | `upr.c` | Internal only | Runtime MCU control state |
| `param[]` | global array | `Inu/param.h`, `Inu/detcoeff.c` | EEPROM-like parameter storage | `param[303..307]` are AD electrical params | `detcoeff.c`, `param.c`, `controller.c` | S-function initializes values | Existing format is not STM32-specific |

## Structures from Simulink

Existing S-function wrapper:

- Input vector width: `INPUT_0_WIDTH = 17` in `Inu/wrapper_inu.h`.
- Output vector width: `OUTPUT_0_WIDTH = 35` in `Inu/wrapper_inu.h`.
- Input mapping is manually unpacked in `Inu/controller.c:28..47`.
- Output mapping is manually packed in `Inu/controller.c:615..662`.

New wrapper:

- `SimulinkInterface_OutputBus_t.command` is the command path from Simulink to MCU.
- It should map to a Simulink Bus Object containing `AD_Command_t`.

## Structures sent to Simulink

- Existing: the S-function output vector contains PWM states, `state`, `faultNo`, `inuWork`, flux, speed, power, currents, torque, current limit, modulation limit, and `theta_out`.
- New: `SimulinkInterface_InputBus_t` sends `AD_Measurements_t`, `AD_MotorParameters_t`, ParamID mode/status/faults.

## Runtime MCU state

- Existing C2000 runtime state: `Result`, `Out`, `Emerg`, `Protect`, `Cc`, `Cf`, `Csp`, `Ivc`, `Ip`, `RsState_t`, `RrlState_t`, `LmState_t`.
- New STM32-safe runtime state is private in `Core/Src/ad_parameter_identification.c` and `Core/Src/simulink_interface.c`.

## Configuration state

- Existing: `param[]`, `SgmPar`, `Protect`, offset fields.
- New: `AD_ParamID_SafetyLimits_t`, `AD_Command_t`, `AD_MotorParameters_t.valid_mask`.

## Mapping notes

| Existing field | New field | Status |
|----------------|-----------|--------|
| `sgmPar.Rs` | `AD_MotorParameters_t.Rs_ohm` | Direct mapping |
| `sgmPar.Rr` | `AD_MotorParameters_t.Rr_ohm` | Direct mapping |
| `sgmPar.Ls` | `AD_MotorParameters_t.Ls_H` | Direct mapping if calculated |
| `sgmPar.Lr` | `AD_MotorParameters_t.Lr_H` | Direct mapping if calculated |
| `sgmPar.Lm` | `AD_MotorParameters_t.Lm_H` | Direct mapping |
| `sgmPar.Lls + sgmPar.Llr` | `AD_MotorParameters_t.Ll_H` | Derived mapping |
| `udc1`, `ia1Nf`, `ib1Nf`, `result.ic1` | `AD_Measurements_t` | Requires STM32 ADC scaling TODO |
| `mst.start`, `mst.faultReset`, `mst.pzMode` | `AD_Command_t` | Partial mapping |