Kinetis Motor Suite API Reference Manual
Kinetis Motor Suite v1.0.0
Document Number: KMS100RMRev. 0
Feb 2016
ContentsChapter 1
Kinetis Motor Suite
1.1 Firmware Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Field Oriented Control Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Interrupt Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4 Additional Control Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 2User
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2 Sensorless Velocity Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.2.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.2.2.1 struct USER_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.2.2.2 struct USER_internal_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.2.2.3 struct USER_command_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.2.2.4 struct USER_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.2.2.5 struct USER_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.2.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 332.2.3.1 SCM_CHANGE_TIME_COUNT . . . . . . . . . . . . . . . . . . . . . . . . 332.2.3.2 SCM_HI_SCM_THD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.2.3.3 SCM_LO_SCM_THD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.2.3.4 SCM_LS_OFF_TIME_COUNT . . . . . . . . . . . . . . . . . . . . . . . . . 332.2.3.5 SCM_LS_STEADY_STATE_TIME_COUNT . . . . . . . . . . . . . . . . . 332.2.3.6 SCM_PM_STEADY_STATE_TIME_COUNT . . . . . . . . . . . . . . . . . 332.2.3.7 SCM_RS_STEADY_STATE_TIME_COUNT . . . . . . . . . . . . . . . . . 342.2.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 342.2.4.1 USER_state_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342.2.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342.2.5.1 USER_cfgBrake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Freescale SemiconductorKinetis Motor Suite API Reference Manual
iii
Section number Title Page2.2.5.2 USER_cfgInertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342.2.5.3 USER_cfgSCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.2.5.4 USER_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.2.5.5 USER_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.2.5.6 USER_initStructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.2.5.7 USER_OnEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.2.5.8 USER_onEntryBrake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.2.5.9 USER_onEntryCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.2.5.10 USER_onEntryDuty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.2.5.11 USER_onEntryFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.2.5.12 USER_onEntryIdle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392.2.5.13 USER_onEntryInertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392.2.5.14 USER_onEntryPlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.2.5.15 USER_onEntryScm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.2.5.16 USER_onEntrySpeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.2.5.17 USER_onEntryVoltage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.2.5.18 USER_OnExit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.2.5.19 USER_resetDRVCommands . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.2.5.20 USER_runBrakeStateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . 422.2.5.21 USER_runBrakeStateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . 432.2.5.22 USER_runCurrentState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.2.5.23 USER_runDutyState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.2.5.24 USER_runFaultState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.2.5.25 USER_runIdleState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452.2.5.26 USER_runInertiaState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.2.5.27 USER_runPlanState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.2.5.28 USER_runScmState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472.2.5.29 USER_runSpeedState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482.2.5.30 USER_runStartupRetry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.2.5.31 USER_runVoltageState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.2.5.32 USER_selfCommissioningState . . . . . . . . . . . . . . . . . . . . . . . . . 492.2.5.33 USER_setInertiaOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.2.5.34 USER_updateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.2.5.35 USER_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.2.6 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.2.6.1 brake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.2.6.2 inertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.2.6.3 pVelPlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.2.6.4 scm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.2.6.5 VelPlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
2.3 Sensored Velocity Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.4 Sensored Position Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
ivKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title PageChapter 3
Self Commissioning
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.2.1 struct SCM_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.2.2 struct SCM_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603.2.3 struct SCM_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 603.3.1 SCM_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 613.4.1 SCM_state_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.5.1 SCM_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.5.2 SCM_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.5.3 SCM_resetOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.5.4 SCM_updateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623.5.5 SCM_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Chapter 4Inertia
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664.2.1 struct INERTIA_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664.2.2 struct INERTIA_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674.2.3 struct INERTIA_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674.2.4 struct INERTIA_Status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 684.3.1 INERTIA_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 684.4.1 INERTIA_Status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684.5.1 INERTIA_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684.5.2 INERTIA_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684.5.3 INERTIA_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Freescale SemiconductorKinetis Motor Suite API Reference Manual
v
Section number Title Page4.5.4 INERTIA_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694.5.5 INERTIA_setOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Chapter 5Brake
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735.2.1 struct BRAKE_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735.2.2 struct BRAKE_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745.2.3 struct BRAKE_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.3.1 BRAKE_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 755.4.1 BRAKE_type_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.5.1 BRAKE_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.5.2 BRAKE_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755.5.3 BRAKE_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 6Drive State Machine
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806.2.1 struct DSM_faultThresholds_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806.2.2 union DSM_clrFaults_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816.2.3 struct DSM_clrFaults_t::DSM_clrFaultsBits_s . . . . . . . . . . . . . . . . . . . 816.2.4 union DSM_nonClrFaults_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846.2.5 struct DSM_nonClrFaults_t::DSM_nonClrFaultsBits_s . . . . . . . . . . . . . . 846.2.6 struct DSM_internal_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856.2.7 struct DSM_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866.2.8 union DSM_clrFaults_u . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866.2.9 union DSM_nonClrFaults_u . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 876.3.1 DSM_PK_CURRENT_FAULT_COUNTER . . . . . . . . . . . . . . . . . . . . 876.3.2 DSM_RESET_LINE_HOLD_TIME . . . . . . . . . . . . . . . . . . . . . . . . 87
viKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page6.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 876.4.1 DRV_control_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876.4.2 DSM_state_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886.5.1 DSM_configFaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886.5.2 DSM_faultState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886.5.3 DSM_idleState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886.5.4 DSM_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896.5.5 DSM_resetFaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896.5.6 DSM_runTimeMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896.5.7 DSM_startState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906.5.8 DSM_updateAtFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906.5.9 DSM_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916.5.10 DSMS_CalculateTemperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916.5.11 DSMS_ClearableFaultsReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916.5.12 DSMS_GetClearableFaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926.5.13 DSMS_GetNonClearableFaults . . . . . . . . . . . . . . . . . . . . . . . . . . . 926.5.14 DSMS_holdHwFaultReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926.5.15 DSMS_hwFaultReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926.5.16 DSMS_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936.5.17 DSMS_releaseHwFaultReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.6 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936.6.1 firstStartup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936.6.2 msM1Driver3ph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapter 7Field Oriented Control
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.2 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.1 FULL_SCALE_CURRENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.2 FULL_SCALE_FLUX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.3 FULL_SCALE_INDUCTANCE . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.4 FULL_SCALE_POWER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2.5 FULL_SCALE_RESISTANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.2.6 FULL_SCALE_SPEED_RPM . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.2.7 FULL_SCALE_SPEED_WE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.2.8 FULL_SCALE_TORQUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.2.9 FULL_SCALE_VOLTAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Freescale SemiconductorKinetis Motor Suite API Reference Manual
vii
Section number Title Page7.3.1 DRV_forceToIdle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.3.2 DRV_getDcbBusUnderVoltageThreshold . . . . . . . . . . . . . . . . . . . . . . 997.3.3 DRV_getDcbBusVoltage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.3.4 DRV_getIsFaultActive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.3.5 DRV_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.3.6 DRV_motorStall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.3.7 DRV_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007.3.8 UpdateAtFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.4 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007.4.1 flashSysParamsHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapter 8Trajectory - Velocity
8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058.2.1 struct TRAJVEL_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058.2.2 struct TRAJVEL_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058.2.3 struct TRAJVEL_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068.3.1 TRAJVEL_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 1068.4.1 TRAJVEL_CurveType_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068.4.2 TRAJVEL_Status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078.5.1 TRAJVEL_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078.5.2 TRAJVEL_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078.5.3 TRAJVEL_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078.5.4 TRAJVEL_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Chapter 9Trajectory - Position
9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139.2.1 struct TRAJPOS_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139.2.2 struct TRAJPOS_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
viiiKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page9.2.3 struct TRAJPOS_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159.3.1 TRAJPOS_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 1159.4.1 TRAJPOS_CurveType_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159.4.2 TRAJPOS_ProfileType_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159.4.3 TRAJPOS_Status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169.5.1 TRAJPOS_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169.5.2 TRAJPOS_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169.5.3 TRAJPOS_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169.5.4 TRAJPOS_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 10Speed Control
10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
10.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.2.1 struct SPEED_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.2.2 struct SPEED_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.2.3 struct SPEED_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 12310.3.1 SPEED_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 12310.4.1 SPEED_status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12310.5.1 SPEED_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12310.5.2 SPEED_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12410.5.3 SPEED_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12410.5.4 SPEED_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12510.5.5 SPEED_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Chapter 11Position Control
11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Freescale SemiconductorKinetis Motor Suite API Reference Manual
ix
Section number Title Page11.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12911.2.1 struct POSITION_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12911.2.2 struct POSITION_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13011.2.3 struct POSITION_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 13111.3.1 POSITION_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 13111.4.1 POSITION_status_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13111.5.1 POSITION_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13111.5.2 POSITION_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13211.5.3 POSITION_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13211.5.4 POSITION_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Chapter 12Field Weakening
12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
12.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13512.2.1 struct FW_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13512.2.2 struct FW_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13512.2.3 struct FW_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 13512.3.1 FW_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13612.4.1 FW_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13612.4.2 FW_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13612.4.3 FW_resetController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13612.4.4 FW_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Chapter 13Feedback
13.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
13.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13913.2.1 struct FEEDBACK_internal_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
xKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page13.2.2 struct FEEDBACK_calib_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14013.2.3 struct FEEDBACK_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14013.2.4 struct ADC_results_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14113.2.5 struct FEEDBACK_gains_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14113.2.6 struct FEEDBACK_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
13.3 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 14213.3.1 FEEDBACK_State_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
13.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14213.4.1 DLY_delayUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14213.4.2 FEEDBACK_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14313.4.3 FEEDBACK_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14313.4.4 FEEDBACK_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
13.5 Analog to Digital Converter Interface . . . . . . . . . . . . . . . . . . . . . . . . 14413.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14413.5.2 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 14413.5.2.1 ADC0_SAMPLEA_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . 14413.5.2.2 ADC0_SAMPLEB_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.2.3 ADC1_SAMPLEA_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.2.4 ADC1_SAMPLEB_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.2.5 HW_ADC0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.2.6 HW_ADC1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.2.7 HW_PDB0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.3.1 ADCS_disableInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14513.5.3.2 ADCS_enableInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14613.5.3.3 ADCS_getUserSamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14613.5.3.4 ADCS_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14613.5.3.5 ADCS_readRawADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Chapter 14Clarke Transform
14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
14.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15114.2.1 struct CLARKE_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15114.2.2 struct CLARKE_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
14.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15114.3.1 CLARKE_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15114.3.2 CLARKE_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xi
Section number Title PageChapter 15
Park Transform
15.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
15.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15515.2.1 struct PARK_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15515.2.2 struct PARK_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
15.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15515.3.1 PARK_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15515.3.2 PARK_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Chapter 16Startup
16.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
16.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16116.2.1 struct STARTUP_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16116.2.2 struct STARTUP_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16216.2.3 struct STARTUP_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
16.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 16216.3.1 STARTUP_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
16.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16316.4.1 STARTUP_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16316.4.2 STARTUP_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16316.4.3 STARTUP_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16316.4.4 STARTUP_updateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16316.4.5 STARTUP_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Chapter 17Sensorless Estimator
17.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
17.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16717.2.1 struct EST_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16717.2.2 struct EST_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16817.2.3 struct EST_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
xiiKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page17.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 16917.3.1 EST_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
17.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16917.4.1 EST_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16917.4.2 EST_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16917.4.3 EST_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17017.4.4 EST_updateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17017.4.5 EST_updateSlowTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Chapter 18Encoder
18.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
18.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17318.2.1 struct ENC_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17318.2.2 struct ENC_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
18.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 17318.3.1 ENC_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
18.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17318.4.1 ENC_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17318.4.2 ENC_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17418.4.3 ENC_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17418.4.4 ENC_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
18.5 Quadrature Encoder Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17618.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17618.5.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17618.5.2.1 struct QEI_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17618.5.2.2 struct QEI_internal_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.2.3 struct QEI_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.3.1 FTM_ENCODER_BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.3.2 FTM_ENCODER_INSTANCE . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.3.3 HW_CHAN0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17718.5.3.4 HW_CHAN1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17818.5.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17818.5.4.1 QEI_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17818.5.4.2 QEI_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17818.5.4.3 QEI_resetEncoderAngle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17818.5.4.4 QEI_updateAtFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xiii
Section number Title Page18.5.4.5 QEIS_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17918.5.4.6 QEIS_readPositionCounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17918.5.4.7 QEIS_swapTracks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17918.5.4.8 QEIS_writePositionCounter . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Chapter 19Current
19.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
19.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18319.2.1 struct CURRENT_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18319.2.2 struct CURRENT_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18319.2.3 struct CURRENT_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
19.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 18419.3.1 CURRENT_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
19.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18419.4.1 CURRENT_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18419.4.2 CURRENT_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18419.4.3 CURRENT_resetController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18519.4.4 CURRENT_resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18519.4.5 CURRENT_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18519.4.6 CURRENT_setIntegrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Chapter 20Inverse Park Transform
20.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
20.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18920.2.1 struct IPARK_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18920.2.2 struct IPARK_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
20.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19020.3.1 IPARK_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19020.3.2 IPARK_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19020.3.3 IPARK_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
xivKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title PageChapter 21
Space Vector Pulse Width Modulation
21.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
21.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19521.2.1 struct SVPWM_config_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19521.2.2 struct SVPWM_output_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19621.2.3 struct SVPWM_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
21.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 19621.3.1 SVPWM_PRV_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
21.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 19721.4.1 SVPWM_sector_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19721.4.2 SVPWM_state_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
21.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19721.5.1 SVPWM_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19721.5.2 SVPWM_disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19821.5.3 SVPWM_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19821.5.4 SVPWM_enableTwoPhases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19821.5.5 SVPWM_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19921.5.6 SVPWM_updateFastTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19921.5.7 SVPWM_zeroVector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
21.6 Pulse Width Modulation Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 20121.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20121.6.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20121.6.2.1 struct PWMS_duty_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20121.6.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 20221.6.3.1 HW_FTM0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20221.6.4 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20221.6.4.1 PWMS_disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20221.6.4.2 PWMS_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20221.6.4.3 PWMS_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20321.6.4.4 PWMS_setDeadTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20321.6.4.5 PWMS_setDrivePolarity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20321.6.4.6 PWMS_setDuties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20321.6.4.7 PWMS_setPins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xv
Section number Title PageChapter 22
Motion Sequence
22.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
22.2 SpinTAC™ Velocity Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20822.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20822.2.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21522.2.2.1 struct ST_PlanError_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21522.2.2.2 struct ST_VelPlan_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21622.2.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.1 __ST_PLAN_ENUM__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.2 __ST_PLAN_ERROR__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.3 ST_VEL_PLAN_ACT_DWORDS . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.4 ST_VEL_PLAN_COND_DWORDS . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.5 ST_VEL_PLAN_STATE_DWORDS . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.6 ST_VEL_PLAN_TRAN_DWORDS . . . . . . . . . . . . . . . . . . . . . . . 21722.2.3.7 ST_VEL_PLAN_VAR_DWORDS . . . . . . . . . . . . . . . . . . . . . . . 21722.2.4 Typedef Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.4.1 ST_VELPLAN_Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.5 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.5.1 ST_PlanActOptn_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.5.2 ST_PlanActTrgr_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21722.2.5.3 ST_PlanComp_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21822.2.5.4 ST_PlanCond_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21822.2.5.5 ST_PlanFsmState_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21922.2.5.6 ST_PlanStatus_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21922.2.5.7 ST_PlanVar_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21922.2.5.8 ST_VelPlan_ErrorCode_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22022.2.5.9 ST_VelPlan_ErrorId_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22122.2.6 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22122.2.6.1 STVELCTL_getOutputMaximum . . . . . . . . . . . . . . . . . . . . . . . . 22122.2.6.2 STVELPLAN_addCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22222.2.6.3 STVELPLAN_addCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . 22322.2.6.4 STVELPLAN_addCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . 22322.2.6.5 STVELPLAN_addCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22422.2.6.6 STVELPLAN_addCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22422.2.6.7 STVELPLAN_addCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . 22522.2.6.8 STVELPLAN_delCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22522.2.6.9 STVELPLAN_delCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . 22522.2.6.10 STVELPLAN_delCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22622.2.6.11 STVELPLAN_delCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22622.2.6.12 STVELPLAN_delCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22622.2.6.13 STVELPLAN_delCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 227
xviKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page22.2.6.14 STVELPLAN_getAccelerationLimit . . . . . . . . . . . . . . . . . . . . . . . 22722.2.6.15 STVELPLAN_getCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22722.2.6.16 STVELPLAN_getCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22822.2.6.17 STVELPLAN_getCfgActNum . . . . . . . . . . . . . . . . . . . . . . . . . . 22822.2.6.18 STVELPLAN_getCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . 22922.2.6.19 STVELPLAN_getCfgCondNum . . . . . . . . . . . . . . . . . . . . . . . . . 22922.2.6.20 STVELPLAN_getCfgError . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23022.2.6.21 STVELPLAN_getCfgHaltState . . . . . . . . . . . . . . . . . . . . . . . . . 23022.2.6.22 STVELPLAN_getCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23122.2.6.23 STVELPLAN_getCfgStateNum . . . . . . . . . . . . . . . . . . . . . . . . . 23122.2.6.24 STVELPLAN_getCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23122.2.6.25 STVELPLAN_getCfgTranNum . . . . . . . . . . . . . . . . . . . . . . . . . 23222.2.6.26 STVELPLAN_getCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23222.2.6.27 STVELPLAN_getCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 23322.2.6.28 STVELPLAN_getCfgVarNum . . . . . . . . . . . . . . . . . . . . . . . . . . 23322.2.6.29 STVELPLAN_getCurrentState . . . . . . . . . . . . . . . . . . . . . . . . . . 23422.2.6.30 STVELPLAN_getCurrentTimerValue_tick . . . . . . . . . . . . . . . . . . . 23422.2.6.31 STVELPLAN_getCurrentTransition . . . . . . . . . . . . . . . . . . . . . . . 23422.2.6.32 STVELPLAN_getEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23522.2.6.33 STVELPLAN_getErrorID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23522.2.6.34 STVELPLAN_getFsmState . . . . . . . . . . . . . . . . . . . . . . . . . . . 23522.2.6.35 STVELPLAN_getJerkLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . 23622.2.6.36 STVELPLAN_getReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23622.2.6.37 STVELPLAN_getStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23622.2.6.38 STVELPLAN_getVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23722.2.6.39 STVELPLAN_getVelocitySetpoint . . . . . . . . . . . . . . . . . . . . . . . 23722.2.6.40 STVELPLAN_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23722.2.6.41 STVELPLAN_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23822.2.6.42 STVELPLAN_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23822.2.6.43 STVELPLAN_runTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23822.2.6.44 STVELPLAN_setCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23822.2.6.45 STVELPLAN_setCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23922.2.6.46 STVELPLAN_setCfgArray . . . . . . . . . . . . . . . . . . . . . . . . . . . 23922.2.6.47 STVELPLAN_setCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24022.2.6.48 STVELPLAN_setCfgHaltState . . . . . . . . . . . . . . . . . . . . . . . . . . 24022.2.6.49 STVELPLAN_setCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24122.2.6.50 STVELPLAN_setCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24122.2.6.51 STVELPLAN_setCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24222.2.6.52 STVELPLAN_setCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 24222.2.6.53 STVELPLAN_setEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24322.2.6.54 STVELPLAN_setReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24322.2.6.55 STVELPLAN_setUnitProfDone . . . . . . . . . . . . . . . . . . . . . . . . . 24422.2.6.56 STVELPLAN_setVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
22.3 SpinTAC™ Position Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xvii
Section number Title Page22.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24522.3.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25322.3.2.1 struct ST_PlanError_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25322.3.2.2 struct ST_PosPlan_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25422.3.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.1 __ST_PLAN_ENUM__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.2 __ST_PLAN_ERROR__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.3 ST_POS_PLAN_ACT_DWORDS . . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.4 ST_POS_PLAN_COND_DWORDS . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.5 ST_POS_PLAN_STATE_DWORDS . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.6 ST_POS_PLAN_TRAN_DWORDS . . . . . . . . . . . . . . . . . . . . . . . 25522.3.3.7 ST_POS_PLAN_VAR_DWORDS . . . . . . . . . . . . . . . . . . . . . . . . 25522.3.4 Typedef Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.4.1 ST_POSPLAN_Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.5 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.5.1 ST_PlanActOptn_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.5.2 ST_PlanActTrgr_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.5.3 ST_PlanComp_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25622.3.5.4 ST_PlanCond_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25722.3.5.5 ST_PlanFsmState_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25722.3.5.6 ST_PlanStatus_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25822.3.5.7 ST_PlanVar_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25822.3.5.8 ST_PosPlan_ErrorCode_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25822.3.5.9 ST_PosPlan_ErrorId_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26022.3.6 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26022.3.6.1 STPOSPLAN_addCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26022.3.6.2 STPOSPLAN_addCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . 26122.3.6.3 STPOSPLAN_addCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26122.3.6.4 STPOSPLAN_addCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26222.3.6.5 STPOSPLAN_addCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26222.3.6.6 STPOSPLAN_addCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . 26322.3.6.7 STPOSPLAN_delCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26322.3.6.8 STPOSPLAN_delCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26322.3.6.9 STPOSPLAN_delCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26422.3.6.10 STPOSPLAN_delCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26422.3.6.11 STPOSPLAN_delCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26422.3.6.12 STPOSPLAN_delCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 26422.3.6.13 STPOSPLAN_getAccelerationLimit . . . . . . . . . . . . . . . . . . . . . . . 26522.3.6.14 STPOSPLAN_getCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26522.3.6.15 STPOSPLAN_getCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26522.3.6.16 STPOSPLAN_getCfgActNum . . . . . . . . . . . . . . . . . . . . . . . . . . 26622.3.6.17 STPOSPLAN_getCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26622.3.6.18 STPOSPLAN_getCfgCondNum . . . . . . . . . . . . . . . . . . . . . . . . . 26722.3.6.19 STPOSPLAN_getCfgError . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26722.3.6.20 STPOSPLAN_getCfgHaltState . . . . . . . . . . . . . . . . . . . . . . . . . . 267
xviiiKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page22.3.6.21 STPOSPLAN_getCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26822.3.6.22 STPOSPLAN_getCfgStateNum . . . . . . . . . . . . . . . . . . . . . . . . . 26822.3.6.23 STPOSPLAN_getCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26922.3.6.24 STPOSPLAN_getCfgTranNum . . . . . . . . . . . . . . . . . . . . . . . . . 26922.3.6.25 STPOSPLAN_getCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27022.3.6.26 STPOSPLAN_getCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 27022.3.6.27 STPOSPLAN_getCfgVarNum . . . . . . . . . . . . . . . . . . . . . . . . . . 27022.3.6.28 STPOSPLAN_getCurrentState . . . . . . . . . . . . . . . . . . . . . . . . . . 27122.3.6.29 STPOSPLAN_getCurrentTimerValue_tick . . . . . . . . . . . . . . . . . . . 27122.3.6.30 STPOSPLAN_getCurrentTransition . . . . . . . . . . . . . . . . . . . . . . . 27122.3.6.31 STPOSPLAN_getDecelerationLimit . . . . . . . . . . . . . . . . . . . . . . . 27222.3.6.32 STPOSPLAN_getEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27222.3.6.33 STPOSPLAN_getErrorID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27222.3.6.34 STPOSPLAN_getFsmState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27322.3.6.35 STPOSPLAN_getJerkLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . 27322.3.6.36 STPOSPLAN_getPositionStep_mrev . . . . . . . . . . . . . . . . . . . . . . 27322.3.6.37 STPOSPLAN_getReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27422.3.6.38 STPOSPLAN_getStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27422.3.6.39 STPOSPLAN_getVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27422.3.6.40 STPOSPLAN_getVelocityLimit . . . . . . . . . . . . . . . . . . . . . . . . . 27522.3.6.41 STPOSPLAN_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27522.3.6.42 STPOSPLAN_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27522.3.6.43 STPOSPLAN_run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27622.3.6.44 STPOSPLAN_runTick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27622.3.6.45 STPOSPLAN_setCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27622.3.6.46 STPOSPLAN_setCfgAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27622.3.6.47 STPOSPLAN_setCfgArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27722.3.6.48 STPOSPLAN_setCfgCond . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27722.3.6.49 STPOSPLAN_setCfgHaltState . . . . . . . . . . . . . . . . . . . . . . . . . . 27822.3.6.50 STPOSPLAN_setCfgState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27822.3.6.51 STPOSPLAN_setCfgTran . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27922.3.6.52 STPOSPLAN_setCfgVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28022.3.6.53 STPOSPLAN_setCfgVarCond . . . . . . . . . . . . . . . . . . . . . . . . . . 28022.3.6.54 STPOSPLAN_setEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28022.3.6.55 STPOSPLAN_setReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28122.3.6.56 STPOSPLAN_setUnitProfDone . . . . . . . . . . . . . . . . . . . . . . . . . 28122.3.6.57 STPOSPLAN_setVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Chapter 23Math
23.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xix
Section number Title Page23.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29023.2.1 struct FLT_butterAccT32bit_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29023.2.2 struct FLT_butterAccT16bit_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29023.2.3 struct FLT_butterAccE32bit_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29023.2.4 struct PID_pidParam32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29023.2.5 struct PID_pidReg32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29123.2.6 struct PID_piParam16_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29123.2.7 struct PID_piReg16_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29223.2.8 struct PID_piParam32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29223.2.9 struct PID_piReg32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29323.2.10 struct TRF_s3Vector32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29323.2.11 struct TRF_sVector16_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29323.2.12 struct TRF_sVector32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29423.2.13 struct TRF_rVector16_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29423.2.14 struct TRF_rVector32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29423.2.15 struct TRF_orient16_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29423.2.16 struct TRF_orient32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29423.2.17 struct FLT_butterAccT32bit_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.2.18 struct FLT_butterAccT16bit_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.2.19 struct FLT_butterAccE32bit_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
23.3 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.3.1 _L32mpyLQL32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.3.2 _LQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.3.3 _LQ14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29523.3.4 _LQ15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.5 _LQ16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.6 _LQ20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.7 _LQ20divLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.8 _LQ20mpyI32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.9 _LQ20mpyLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.10 _LQ24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.11 _LQ30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29623.3.12 _LQ30mpyLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.13 _LQ31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.14 _LQ_ASL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.15 _LQ_ASR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.16 _LQabsFast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.17 _LQdiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29723.3.18 _LQdivLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29823.3.19 _LQmpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29823.3.20 _LQmpyI32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29823.3.21 _LQmpyLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29823.3.22 _LQmpyMiniSQLQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29823.3.23 _LQmpyMiniSQLQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
xxKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page23.3.24 _LQmpySQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.25 _LQmpySQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.26 _LQsatFast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.27 _LQtoSQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.28 _LQtoSQ15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.29 _LQZmpyMiniSQLQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.30 _LQZmpySQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29923.3.31 _LQZmpySQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.32 _SQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.33 _SQ15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.34 _SQ15mpySQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.35 _SQ8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.36 _SQ_ASL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.37 _SQ_ASR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30023.3.38 _SQabsFast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.39 _SQdivISQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.40 _SQmpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.41 _SQmpySQX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.42 _SQsatFast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.43 _SQtoLQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.44 DWORD_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30123.3.45 FLT_COEFF_EULER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30223.3.46 FLT_COEFF_TUSTIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30223.3.47 FLT_INIT_E_32BIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30223.3.48 FLT_INIT_T_32BIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30323.3.49 FLT_RATIO_EULER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30323.3.50 FLT_RATIO_TUSTIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30323.3.51 GLOBAL_LQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30423.3.52 GLOBAL_SQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30423.3.53 INV_LN9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30423.3.54 LAST_INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30423.3.55 LN9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30423.3.56 LOG2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30523.3.57 MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30523.3.58 MAX_LQ_NEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30523.3.59 MAX_LQ_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30523.3.60 MAX_SQ_NEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30523.3.61 MAX_SQ_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.62 MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.63 MIN_LQ_NEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.64 MIN_LQ_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.65 MIN_SQ_NEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.66 MIN_SQ_POS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.67 PI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30623.3.68 PID_PI_REG16_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xxi
Section number Title Page23.3.69 PID_PI_REG32_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30723.3.70 PID_PID_REG32_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30723.3.71 QM_DIV_TWO_32B_16BRES . . . . . . . . . . . . . . . . . . . . . . . . . . . 30823.3.72 QM_DIV_TWO_32B_32BRES . . . . . . . . . . . . . . . . . . . . . . . . . . . 30823.3.73 SQRT2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30823.3.74 SQRT3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30823.3.75 TRF_EXT_VECTOR16_DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . 30823.3.76 TRF_EXT_VECTOR32_DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . 30923.3.77 TRF_VECTOR16_DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.3.78 TRF_VECTOR32_DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.3.79 WORD_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
23.4 Typedef Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.4.1 _lq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.4.2 _lq20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.4.3 _lq24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.4.4 _sq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30923.4.5 bitfield_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.4.6 char_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.4.7 uchar_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
23.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.5.1 _LQ20exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.5.2 _LQ20log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.5.3 _LQ20sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31023.5.4 _LQabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31123.5.5 _LQatan2PU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31123.5.6 _LQcosPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31123.5.7 _LQexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31123.5.8 _LQfrac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31223.5.9 _LQint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31223.5.10 _LQlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31223.5.11 _LQsat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31323.5.12 _LQsincosPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31323.5.13 _LQsinPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31323.5.14 _LQsqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31423.5.15 _LQXtoLQY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31423.5.16 _LQXtoSQY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31423.5.17 _LQZdivISQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31523.5.18 _LQZdivSQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31523.5.19 _LQZmpySQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31623.5.20 _SQsat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31623.5.21 _SQXtoLQY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31723.5.22 _SQZdivISQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31723.5.23 _SQZmpySQXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
xxiiKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page23.5.24 FLT_coeff_Euler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31823.5.25 FLT_coeff_Tustin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31823.5.26 FLT_hpf1stE_32bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31823.5.27 FLT_hpf1stT_32bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31823.5.28 FLT_lpf1stE_32bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31923.5.29 FLT_lpf1stT_16bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31923.5.30 FLT_lpf1stT_32bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31923.5.31 FLT_ratio_Tustin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32023.5.32 PID_processPI32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32023.5.33 PID_processPID32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32023.5.34 PID_processPIF16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32023.5.35 PID_processPIF32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32023.5.36 QM_div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32123.5.37 QM_divTwo32bSNum16bRes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32123.5.38 QM_mpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32123.5.39 qmath_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32223.5.40 TRF_clarkeLarge32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32223.5.41 TRF_iPark32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32323.5.42 TRF_park32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32323.5.43 TRF_park32_16_SQ15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32423.5.44 UTIL_angleWrapAround . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32423.5.45 UTIL_arcUponChord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Chapter 24Communication
24.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
24.2 Macro Definition Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.1 RDA_UART_BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.2 RDA_UART_INSTANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.3 UART_RX_BUFFER_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.4 UART_RX_BUFFER_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.5 UART_TX_BUFFER_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32924.2.6 UART_TX_BUFFER_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
24.3 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33024.3.1 if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33024.3.2 rda_get_number_processed_messages . . . . . . . . . . . . . . . . . . . . . . . 33024.3.3 rda_get_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33024.3.4 rda_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33024.3.5 rda_mem_address_readable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33024.3.6 rda_push_int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33124.3.7 rda_set_interrupt_freq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xxiii
Section number Title Page24.3.8 rda_tick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33124.3.9 RDA_UART_ISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33124.3.10 UART0_ERR_IRQHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33224.3.11 uart_rx_byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33224.3.12 uart_rx_data_ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33224.3.13 uart_tx_byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33224.3.14 uart_tx_empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33324.3.15 uart_tx_full . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
24.4 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33324.4.1 uart_rx_buf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33324.4.2 uart_rx_head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33324.4.3 uart_rx_tail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.4 uart_tx_buf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.5 uart_tx_head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.6 uart_tx_tail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.7 uartIsrCounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.8 uartIsrDroppedCounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.9 uartRxCounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.10 uartRxOverRunCounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33424.4.11 uartTxCounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Chapter 25Versions
25.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
25.2 Data Structure Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33925.2.1 struct ST_Ver_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
25.3 Typedef Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33925.3.1 ST_VER_Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
25.4 Enumeration Type Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 33925.4.1 ST_MathType_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
25.5 Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33925.5.1 direct_encode_16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33925.5.2 direct_encode_32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34025.5.3 GetMotorObserverNonSecureVersion . . . . . . . . . . . . . . . . . . . . . . . . 34025.5.4 GetMotorObserverSecureVersion . . . . . . . . . . . . . . . . . . . . . . . . . . 34025.5.5 GetMotorObserverSecureVersionIsCompatible . . . . . . . . . . . . . . . . . . . 34025.5.6 rda_bsp_get_app_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34125.5.7 rda_mem_address_readable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
xxivKinetis Motor Suite API Reference Manual
Freescale Semiconductor
Section number Title Page25.5.8 rda_mem_address_writable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34225.5.9 ST_getSecureROMIsCompatible . . . . . . . . . . . . . . . . . . . . . . . . . . 34225.5.10 ST_getSecureROMVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34225.5.11 ST_getVersionDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34325.5.12 ST_getVersionMath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34325.5.13 ST_getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34325.5.14 ST_initVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
25.6 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34425.6.1 __checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34425.6.2 buildDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34425.6.3 buildTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34425.6.4 flashHighAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.5 flashLowAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.6 m_data_2_end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.7 m_data_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.8 m_text_end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.9 m_text_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.10 ramHighAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34525.6.11 ramLowAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Freescale SemiconductorKinetis Motor Suite API Reference Manual
xxv
Chapter 1Kinetis Motor SuiteBased on Kinetis V series microcontrollers (MCUs), Kinetis Motor Suite (KMS) is an integrated solutionof hardware, embedded firmware, and PC software that enables rapid development of applications drivenby three phase permanent magnet or brushless DC motors.
The purpose of this document is to describe the function and API of the embedded firmware componentof KMS, known as Motor Observer, so that Motor Observer can be leveraged and adapted to suit yourapplication's specific operation.
Supporting documentation describes the other elements of KMS:
• The Kinetis V series hardware underlying KMS is explained in the appropriate KV reference man-uals.
• Specific pins and peripherals utilized by KMS are described in the KMS User's Guide.• The PC software component of KMS is described in the KMS User's Guide.• For a hands-on introduction to all three elements and the interactions among them, please refer to
the KMS Lab Guide.
1.1 Firmware ArchitectureThe core aim of KMS is to make motor control simple. This is reflected not only in the focus on anintelligent PC-based user interface, but on the design of the embedded firmware provided by KMS.
Modularity
The firmware is written in an easy-to-understand “block and pin” style. Each "block," or software mod-ule, is self-contained and has input, output, and configuration “pins,” which comprise the entirety of theinterface: you do not need full knowledge of the software underlying each module to be able to use thecode effectively.
More precisely, each block contains structures and functions.
The main structures are for:
• Configuration: sets up run-time updateable variables• Output: delivers values to other blocks or to the user• Private: defines memory used internally by the block
The main functions are for:
• Initialization: zeroes out the relevant structure and performing any prerequisites for configuration• Configuration: calculates values needed by private memory using input values• Running/Updating: performs core functionality of block using input values
(Note that the functions only work on the addresses of the relevant blocks.)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
1
Field Oriented Control Data Flow
This consistent, modular structure allows you to easily connect, disconnect, and configure blocks in orderto customize code for your specific objectives. It also accelerates debugging, because each block can betested individually.
This modularity also informs the structure of this document: chapters in this document refer to softwareblocks, and each chapter contains an introduction that outlines:
• Functionality,• Inputs & Outputs• Execution• Custom Usage
Control Flow
Maximization of code re-use and ease of debugging are further emphasized by the usage of a single controlflow path with dual interrupt service routines.
Providing a single control path means the code is guaranteed to execute in a comprehensible manner.Similarly, using a Fast Interrupt Service Routine and a Slow Interrupt Service Routine (described below)allows KMS to avoid overruns. The combination of the two means the code is comprehensible and easyto debug when customizing.
Code Partitioning
In order to balance MCU hardware and PC software integration with firmware flexibility, different aspectsof KMS firmware are accessible to different degrees.
• Execute-only locked firmware: This proprietary firmware is locked in execute-only flash memoryand is programmed onto the MCU during production. It resides in the highest section of memoryavailable so as to avoid interference with the normal design flow. Firmware is specific to the partnumber.
• Library: This firmware includes the main motor control and math functions. API functions andpublic variables provide access and control to features in the library.
• Open Source: The full source of the open firmware is provided. These modules include the KinetisSDK, the peripheral interface layer, the connections between the motor control functions, the mainfunction, and interrupts.
A high-level breakdown of how code is partitioned is provided on a module-by-module basis in the re-maining chapters of this document.
1.2 Field Oriented Control Data FlowKMS implements field-oriented, sinusoidal control ("FOC") of three phase permanent magnet or brushlessDC motors (PMSM/BLDC). It provides three different control topologies.
• Sensorless Velocity: A software algorithm calculates the motor electrical angle based on phase cur-rent feedback. The primary mode of operation is variable speed control.
2Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
• Sensored Velocity: A physical encoder provides the motor electrical angle. The primary mode ofoperation is variable speed control.
• Sensored Position: A physical encoder provides the motor electrical angle. The primary mode ofoperation is variable position control.
The modular software blocks referenced above that jointly comprise FOC are described pictorially and byfunction in this section. In the block diagrams displayed below, they will indicate which control topologythey belong to.
Block Diagrams
To support a wide variety of motor driven applications and the different stages of application design,many different modes of operation are supported within KMS. The modularity of Motor Observer enablesseamless reconfiguration of blocks to achieve these different modes of operation.
Diagrammatic representations of key operating modes are on the following pages, with block coloringdefined in the figure below.
HARDWAREMOTORCONTROL
HARDWAREABSTRACTION
Figure 1.2.1: Block Diagram Color Key
Freescale SemiconductorKinetis Motor Suite API Reference Manual
3
Field Oriented Control Data Flow
• Speed Control: Given any target speed within the operating range of the motor, KMS will act ac-cording to the following block diagrams to attempt to maintain this speed.
TRAJ
VEL
SPEE
DCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
EST
FW
DC B
us S
ense
DC B
us
Spee
d Re
f
Iq R
efId R
ef
V R
ef M
agni
tude
Spee
d Fd
b
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
Figure 1.2.2: Sensorless Velocity Control Block Diagram
4Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
TRAJ
VEL
SPEE
DCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
FW
DC B
us S
ense
DC B
us
Spee
d Re
f
Iq R
efId R
ef
V R
ef M
agni
tude
Spee
d Fd
b
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
Figure 1.2.3: Sensored Velocity Control Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
5
Field Oriented Control Data Flow
• Position Control: Given a position setpoint, KMS will act according to the following block diagramsto attempt to maintain this position.
TRAJ
POS
POSI
TIO
NCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
DC B
us S
ense
DC B
us
Pos R
ef
Iq R
ef
Pos F
db
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Posit
ion
Step
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
Id R
ef0
Figure 1.2.4: Sensored Position Control Block Diagram
6Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
• Torque Control: Instead of controlling the motor's speed, it may be preferable to control torque inapplications like electric bicycles. This exists as a operation mode within all control topologies.
CURR
ENT
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
EST
DC B
us S
ense
DC B
us
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Id S
etpo
int
Iq S
etpo
int
Figure 1.2.5: Sensorless Torque Control Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
7
Field Oriented Control Data Flow
CURR
ENT
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
&
Enco
der
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
DC B
us S
ense
DC B
us
Iq S
etpo
int
Id S
etpo
int
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
Figure 1.2.6: Sensored Torque Control Block Diagram
8Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
• Motion Sequence Control: KMS allows for simple GUI-based creation of motion state machines.This adds an additional block to typical speed or position control operation.
TRAJ
VEL
SPEE
DCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
EST
FW
DC B
us S
ense
DC B
us
Spee
d Re
f
Iq R
efId R
ef
V R
ef M
agni
tude
Spee
d Fd
b
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
PLAN
Spee
d Se
tpoi
nt
Mot
ion
Sequ
ence
Figure 1.2.7: Sensorless Velocity Motion Sequence Control Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
9
Field Oriented Control Data Flow
TRAJ
VEL
SPEE
DCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
FW
DC B
us S
ense
DC B
us
Spee
d Re
f
Iq R
efId R
ef
V R
ef M
agni
tude
Spee
d Fd
b
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
PLAN
Mot
ion
Sequ
ence
Figure 1.2.8: Sensored Velocity Motion Sequence Control Block Diagram
10Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
TRAJ
POS
POSI
TIO
NCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
DC B
us S
ense
DC B
us
Pos R
ef
Iq R
ef
Pos F
db
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Posit
ion
Step
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
PLAN
Mot
ion
Sequ
ence
Id R
ef0
Figure 1.2.9: Sensored Position Motion Sequence Control Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
11
Field Oriented Control Data Flow
• Startup: Sensorless FOC relies on a back-EMF signal that cannot occur without motor rotation. Toreach sufficient rotational speed to achieve a signal, the motor must operate slightly differently.
STAR
TUP
Flux
Pll L
ocke
d
TRAJ
VEL
CURR
ENT
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
EST
DC B
us S
ense
DC B
us
Spee
d Re
fId
q Re
f
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
elec
Figure 1.2.10: Motor Startup Block Diagram
12Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
• Alignment: Sensored FOC relies on an encoder in order to provide the motor electrical angle. It isimportant that this encoder signal is aligned with the true electrical angle of the motor.
CURR
ENT
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
&
Enco
der
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
DC B
us S
ense
DC B
us
0
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
0Fl
ex T
imer
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
Iq R
ef
Id R
ef
USE
R
Figure 1.2.11: Encoder Alignment Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
13
Field Oriented Control Data Flow
• Resistance & Inductance Measurement: KMS must energize the motor in a specific manner toidentify the motor's resistance and inductance, which enables valid FOC operation.
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
SCM
DC B
us S
ense
DC B
usV
Ref
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb0
Idq
Ref
PARK
E
CURR
ENT
Vdq
Ref
Idq
Fdb
Figure 1.2.12: Resistance and Inductance Measurement Block Diagram
14Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
• Flux Measurement: KMS must also assess the flux of the motor with a short test running the motorat a low speed.
TRAJ
VEL
CURR
ENT
IPAR
KSV
PWM
Flex
Tim
erIn
vert
erM
otor
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
STAR
TUP
DC B
us S
ense
DC B
us
Spee
d Re
f
Idq
Ref
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
db
I F
db
elec
elec
Spee
d Se
tpoi
nt
EST
Flux
SCM
Figure 1.2.13: Sensorless Velocity Flux Measurement Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
15
Field Oriented Control Data Flow
TRAJ
VEL
SPEE
DCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
DC B
us S
ense
DC B
us
Spee
d Re
f
Iq R
efId R
ef
Spee
d Fd
b
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
FLU
XEST
SCM
Flux
V
Ref
I
Fdb0
Figure 1.2.14: Sensored Velocity Flux Measurement Block Diagram
16Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Field Oriented Control Data Flow
TRAJ
POS
POSI
TIO
NCU
RREN
TIP
ARK
SVPW
MFl
ex T
imer
Inve
rter
Mot
or &
En
code
r
Shun
t Re
sisto
rsAn
alog
to
Digi
tal
Conv
erte
rFE
EDBA
CKCL
ARKE
PARK
ENC
DC B
us S
ense
DC B
us
Pos R
ef
Iq R
efId R
ef
Pos F
db
Vdq
Ref
V R
ef
Duty
Cyc
les
ADC
Coun
tsIa
bc F
dbI
Fdb
Idq
Fdb
elec
Spee
d Se
tpoi
nt
Flex
Tim
er
Enco
der
Phas
esQ
EI
Enco
der
Coun
t
FLU
XEST
SCM
Flux
V
Ref
I
Fdb0
Spee
d Pr
ofile
Figure 1.2.15: Sensored Position Flux Measurement Block Diagram
Freescale SemiconductorKinetis Motor Suite API Reference Manual
17
Interrupt Service Routines
Description of Blocks
The software blocks that make up the above diagrams can be described as follows:
• User (USER): Allows user to easily access main motor operating states.• Self Commissioning (SCM): Self commissioning module controls the automatic parameter identifi-
cation process.• Motion Sequence (PLAN): Configures and runs a user-configured motion sequence.• Trajectory - Velocity (TRAJVEL): Ramps speed command from the previous target speed to the
current target speed according to the selected curve type and acceleration and jerk limits.• Trajectory - Position (TRAJPOS): Ramps position command for the position step according to the
selected curve type and speed, acceleration, deceleration, and jerk limits.• Speed Control (SPEED): Outputs torque (Iq) reference according to speed feedback and speed ref-
erence.• Position Control (POSITION): Outputs torque (Iq) reference according to position feedback and
position reference.• Field Weakening (FW): Outputs D-phase current reference based on modulation command and rotor
speed for field weakening operation.• Feedback (FEEDBACK): Generates the three phase currents and DC bus voltage from the ADC
hardware and internal scaling, calibration and offset.• Clarke Transform (CLARKE): Converts three phase current feedback signals to two phase represen-
tation.• Park Transform (PARK): Rotates current feedback from stator reference frame to rotor reference
frame.• Startup (STARTUP): Controls startup sequencing and logic and generates sensorless angle and speed
feedback while running in the startup region.• Estimator (EST): Generates sensorless angle and speed feedback from the phase currents in the
stator reference frame.• Encoder (ENC): Generates position and speed feedback from the motor electrical angle.• Current (CURRENT): Two channel (Iq and Id) current regulator which outputs D and Q phase
voltages.• Inverse Park Transform (IPARK): Rotates voltage commands from rotor reference frame to stator
reference frame according to angle feedback.• Space Vector PWM (SVPWM): Generates modulation values for the three phase inverter from the
stator frame voltages.
Detailed descriptions of each make up the bulk of the remainder of this document.
1.3 Interrupt Service RoutinesKMS employs a dual interrupt service routine (ISR) approach. Each ISR is briefly described in this section.
Fast Interrupt
Running a motor requires running calculations at or very close to the PWM frequency. This is due to thevery fast dynamics of the electrical control of a motor. In KMS, this is called the Fast Interrupt Service
18Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Interrupt Service Routines
Routine, or Fast ISR.
During this ISR, the three motor phase currents and sampled (FEEDBACK), the sensorless angle estima-tion is performed (EST) OR the electrical angle will be provided by the sensor, the current controllers arerun to update the reference voltage (CURRENT), and the space vector modulator is called to update thethree PWM duty cycles (SVPWM). There are additional time-sensitive software components dealing withfault detection (DSM) and braking (BRAKE) that are called during this ISR.
The specifics of these software modules are individually addressed in this document, and the execution ofkey elements within these blocks is described therein.
The rate at which the Fast ISR operates is configurable in relation to the PWM switching frequency ofthe processor as well as to the operation of the Slow ISR. The PWM frequency of the system can bespecified in absolute terms (in the range 4-80 kHz). The ratio of PWM cycles to Fast ISR cycles can thenbe specified, and in turn, so too can the ratio of Fast ISR cycles to Slow ISR cycles. KMS will provide awarning if the rate of the Fast ISR will consume greater than 80% of the available processor resources.
The defaults for KV3 are as follows:
• PWM Frequency = 10 kHz• PWM tick per Fast ISR = 1• Fast ISR Frequency = 10 kHz
In other words, the Fast ISR is configured to run at the PWM frequency of 10 kHz and the Fast ISR runsat ten times the rate of the Slow ISR, which therefore runs at 1 kHz.
Slow Interrupt
While very fast dynamic response is critical for controlling a motor electrically, the mechanical responseof a motor is much slower than the electrical response which means that the control loops can be run muchslower. To achieve good control of these less time-sensitive operations, KMS relies on a Slow InterruptService Routine, or Slow ISR.
During this ISR, the feedback speed is estimated (EST) or calculated from the encoder (ENC), the refer-ence speeds are updated (TRAJ), the speed (SPEED) or position (POSITION) is controlled, and the fieldweakening controller is run (FW). There is also some additional software executed to handle the drive(DSM) and user (USER) state machines.
The blocks cited as contributing to the Fast ISR may also have less time critical elements operating in theSlow ISR. A high-level breakdown of when the code comprising a block is executed is included in eachchapter of this document.
The rate at which the Slow ISR operates is configurable in relation to the Fast ISR, which is configurablein relation to the PWM switching frequency of the processor.
The defaults for KV3 are as follows:
• Fast ISR Frequency = 10 kHz• Fast ISR per Slow ISR = 10• Slow ISR Frequency = 1 kHz
Freescale SemiconductorKinetis Motor Suite API Reference Manual
19
Additional Control Modes
In other words, the Slow ISR by default is configured to run at 1/10th the speed of both the Fast ISR andthe PWM Frequency, or 1 kHz.
1.4 Additional Control ModesBeyond speed and position control, KMS can also provide additional types of motor control.
Torque Control
In some applications the motor speed does not need to be controlled. For example, in an eBike application,the human riding the eBike is the speed controller and the throttle is a torque demand signal. KMS doessupport this type of control. Torque control merely constitutes the inner loop of the speed or positioncontrol loops. This type of control can be done either sensored or sensorlessly. Via the KMS PC GUI, thiscontrol mode is accessible in the Sensorless Velocity or Sensored Velocity control topologies.
In the below example plot, torque control used to spin the motor with a fixed torque reference. Whenthe motor was loaded down, the speed (est.output.rotorSpeed) in green reduces since the motor cannotovercome the amount of load using only the allowed current (user.command.statorRefCurrent.q) in red.This condition is represented by the estimated torque signal (est.output.torque) in blue flattening out at aconstant value.
Figure 1.4.1: Torque Control Example
When the amount of allowed current user.command.statorRefCurrent.q) in red is allowed to increase, themotor uses more current to overcome the load and the estimated torque signal (est.output.torque) in blueincreases. Additionally, the speed (est.output.rotorSpeed) in green increases as well.
20Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Additional Control Modes
Figure 1.4.2: Changing Torque Control Example
Just like in Sensorless Velocity control, startup is critical for torque control. When using Sensorless Torquecontrol via KMS the same startup mechanism is used as Sensorless Velocity control. The below plot isan example of what happens when running startup in torque control. The speed (est.output.rotorSpeed)in purple rises via the Trajectory block until it reaches the point where the Sensorless Estimator block isready to begin running (this point is called the crossover point and it indicated by the Speed Threshold).Once that point is reached, the Startup block begins blending the current onto the Q-axis and will increaseit until it is aligned with the user reference for torque. This process is shown by the gradual merge ofthe Startup current (startup.output.statorRefCurrent.q) in green to the value in the user reference (user.←↩command.statorRefCurrent.q) in blue. Once the merge process is complete the Startup block indicates thatthe control mode (startup.output.controlMode) shown in red should be 1 which indicates FOC operation.At that point the speed begins increasing very quickly.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
21
Additional Control Modes
Figure 1.4.3: Motor Startup in Torque Control
When using torque control with a sensor, the startup considerations can be ignored.
Voltage Control
For advanced motor control customers, the control of the current flowing through the motor can be by-passed. This allows the user to command a voltage to apply across the motor terminals. This can resultin the current being very large if the motor is not rotating. It is only recommended for customers who arevery comfortable with motor control topics and understand the risks involved.
When running in voltage control mode, the user is allowed to specify references which are used in placeof the references produced by the Current block. These references are in the units of modulation. Thiscontrol mode will still run the Sensorless Estimator block and can use that for the angle source whenperforming the Inverse Park transform. By default, this control mode does not run the Startup block andtherefore will not rotate, however this behaviour can be modified in the KMS firmware.
Duty Control
For advanced motor control customers, the control of the current flowing through the motor can be by-passed. This allows the user to command a voltage to apply across the motor terminals. This can resultin the current being very large if the motor is not rotating. It is only recommended for customers who arevery comfortable with motor control topics and understand the risks involved.
When running in duty control mode, the user is allowed to specify the references which are used in placeof the references produced by the Inverse Park block. These references are in the units of modulation.This control mode will still run the Sensorless Estimator but will not use that for the angle source. The
22Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Additional Control Modes
user will have the ability to directly control the commanded motor angle by adjusting the reference valuesprovided to the SVPWM block.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
23
Additional Control Modes
24Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 2User2.1 OverviewEnables easy access for the user to the main operating states.
Functional description
The User block aggregates the main motor operating states capable of being called by the user. Thisis intended to provide an easy, consistent code interface for the user to be able to command a specificoperating state and perform certain common configurations of the desired state.
For example, if you wanted the motor to run in speed control mode at 2000 rpm this is the block wherethose commands would be written. In this example, the User block would be told to operate the drive inSpeed Control mode and it would receive the commanded speed of 2000 rpm that it would provide to thetrajectory generator.
This is the block that the KMS PC GUI operates on in order to command the motor.
The User block is intended to be a multiplexer into the FOC so that only a single interface needs to beaccessed in order to run the motor. The User block is slightly different for the different control modes. Forexample, not every state is available in all control modes. Differences between the control modes will becalled out in this document.
States that can be accessed via the User block include:
• Idle• Fault• Self-commissioning (SCM)• Inertia Estimation (Inertia)• PWM Duty Control• Voltage Control• Current Control (Current)• Speed Control (Speed)• Position Control (Position) [Sensored Position]• Motion Sequence (Plan)• Braking (Brake)• Encoder Alignment (Align) [Sensored Velocity or Sensored Position]
The User block interacts with both the Drive State Machine (DSM) and the Field Oriented Control (FOC).It sends a state command to the DSM to configure the FOC and sends references (speed setpoints, positionsteps, current setpoints, etc) to the FOC depending on the selected state. The User block also containsthe more complicated blocks that exist outside of the normal control flow. Namely: INERTIA, BRAKE,
Freescale SemiconductorKinetis Motor Suite API Reference Manual
25
Overview
SCM, and PLAN. A visual representation of this is shown below.
Figure 2.1.1: USER - DSM - FOC Interaction
Block diagram detail
Figure 2.1.2: User
Configuration, inputs, and outputs
The only required configuration of the User block is for automatically retrying a failed startup for Sen-sorless. For Sensored Velocity and Sensored Position, the User block needs to be configured for encoderalignment.
26Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
The input to the User block is the requested state of operation and motor control setpoints.
The outputs of the User block are the required drive state to the Drive State Machine and the requestedcommands to the control blocks.
Code security breakdown
The table below describes the partitioning of User block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyDefinition of available operatingstates, commands for states; func-tions for initialization, configura-tion, updating
N/A N/A
Execution
As the User block aggregates different operating states, it has certain elements that are executed in theFAST ISR and certain elements executed in the SLOW ISR. The time of execution for these elementsis determined by the normal operation of the states they refer to. For example, configuration of the self-commissioning state occurs in the SLOW ISR because that is how the self-commissioning state (SCMblock) typically operates.
The User block also includes two update functions, one for FAST ISR and one for SLOW ISR.
User customization example
The user may prefer to operate in a constant voltage or torque-controlled manner for an application like aneBike, which does not require speed control. This can be achieved by effectively bypassing the Trajectoryand Speed blocks and utilizing the User block to command a constant current. Any unneeded operatingmodes for the end application can be removed from the User block.
Modules• Sensorless Velocity Control
The specific API interface for the User block inside of Sensorless Velocity Control.• Sensored Velocity Control
The specific API interface for the User block inside of Sensored Velocity Control.• Sensored Position Control
The specific API interface for the User block inside of Sensored Position Control.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
27
Sensorless Velocity Control
2.2 Sensorless Velocity Control
2.2.1 Overview
The specific API interface for the User block inside of Sensorless Velocity Control.
Data Structures
• struct USER_config_t• struct USER_internal_t• struct USER_command_t• struct USER_output_t• struct USER_t
Macros
• #define SCM_CHANGE_TIME_COUNT ((uint16_t)1024)Time interval between motor parameter measurements (in timer counts)
• #define SCM_RS_STEADY_STATE_TIME_COUNT ((uint16_t)2048)Steady-state time interval for stator resistance measurement (in timer counts)
• #define SCM_LS_STEADY_STATE_TIME_COUNT ((uint16_t)1024)Steady-state time interval for stator inductance measurement (in timer counts)
• #define SCM_LS_OFF_TIME_COUNT ((uint16_t)2048)Time interval with zero voltage during stator inductance measurement (in timer counts)
• #define SCM_HI_SCM_THD (0.9)Relative high current threshold for stator inductance measurement.
• #define SCM_LO_SCM_THD (0.1)Relative low current threshold for stator inductance measurement.
• #define SCM_PM_STEADY_STATE_TIME_COUNT ((uint16_t)4096)Steady-state time interval for PM Flux measurement (in timer counts)
Enumerations
• enum USER_state_e {USER_IDLE = 0,USER_FAULT = 1,USER_SCM = 2,USER_INERTIA = 3,USER_RUN_DUTY = 4,USER_RUN_VOLTAGE = 5,USER_RUN_CURRENT = 6,USER_RUN_SPEED = 7,USER_RUN_PLAN = 8,USER_BRAKE = 9 }
USER state-machine states.
28Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Functions
• USER_t ∗ USER_init (void ∗pMem, size_t size)Initializes USER module.
• void USER_initStructs (USER_t ∗pUSER, _lq limitAcc, _lq lq20LimitJerk, _lq IqRefMax, _lq Iq←↩RefMin)
Initializes all structs in USER module.• void USER_config (USER_t ∗pUSER, const USER_config_t ∗const config)
Configures the USER module.• void USER_updateSlowTick (USER_t ∗pUSER, DSM_t ∗pDSM, bool trajComplete, DRV_←↩
control_e controlType, _lq rotorSpeed, _lq fieldAngle, _lq trajRefSpeed)Updates the USER module at the Slow ISR.
• FAST void USER_updateFastTick (USER_t ∗pUSER, const FEEDBACK_output_t ∗const pADC,_lq speedOutMax, _lq speedOutMin)
Updates USER module at the Fast ISR.• void USER_selfCommissioningState (USER_t ∗pUSER, DSM_t ∗pDSM, bool scComplete)
Processes USER self-commissioning state.• FAST void USER_setInertiaOutput (_sq output)
Inertia Estimation update output signal.• void USER_cfgInertia (const INERTIA_config_t ∗const inertiaConfig, _lq sampleTime)
Configures the INERTIA module.• void USER_cfgBrake (const BRAKE_config_t ∗const brakeCfg)
Configures the BRAKE module.• void USER_cfgSCM (const SCM_config_t ∗const scmCfg, void ∗scmData, _sq ratedVoltage, _sq
ratedCurrent, _sq ratedSpeed, _lq lq16BaseSpeedElecFreq, _lq pwmSampleTime)• void USER_resetDRVCommands (USER_t ∗pUSER)
Resets drive commands going out of the USER module.• static bool USER_runStartupRetry (USER_t ∗pUSER, DSM_t ∗pDSM)• static void USER_OnExit (USER_t ∗pUSER)
Cleans up the USER module upon exiting a state.• static void USER_OnEntry (USER_t ∗pUSER, USER_state_e commandedState)
Sets up the USER module upon entering a state.• static void USER_runIdleState (USER_t ∗pUSER)
Runs the Idle USER state.• static USER_state_e USER_runFaultState (USER_t ∗pUSER, DSM_t ∗pDSM)
Runs the Fault USER state.• static USER_state_e USER_runScmState (USER_t ∗pUSER, _lq fieldAngle, _lq trajRefSpeed)
Runs the Self Commissioning Module USER state.• static USER_state_e USER_runInertiaState (USER_t ∗pUSER, DRV_control_e controlType, _lq
rotorSpeed)Runs the Inertia Identification USER state.
• static void USER_runDutyState (USER_t ∗pUSER)Runs the PWM Duty Control USER state.
• static void USER_runVoltageState (USER_t ∗pUSER)Runs the Voltage Control USER state.
• static void USER_runCurrentState (USER_t ∗pUSER)Runs the Current Control USER state.
• static void USER_runSpeedState (USER_t ∗pUSER)Runs the Speed Control USER state.
• static USER_state_e USER_runPlanState (USER_t ∗pUSER, bool trajComplete)Runs the Plan USER state.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
29
Sensorless Velocity Control
• static void USER_runBrakeStateFastTick (USER_t ∗pUSER, bool brakeEnable, _lq speedOutMax,_lq speedOutMin)
Runs the Braking USER state (Fast ISR)• static void USER_runBrakeStateSlowTick (USER_t ∗pUSER, _lq trajRefSpeed)
Runs the Braking USER state (Slow ISR)• static void USER_onEntryIdle (USER_t ∗pUSER)
Runs code upon entering Idle USER state.• static void USER_onEntryFault (USER_t ∗pUSER)
Runs code upon entering Fault USER state.• static void USER_onEntryScm (USER_t ∗pUSER)
Runs code upon entering Self Commissioning Module USER state.• static void USER_onEntryInertia (USER_t ∗pUSER)
Runs code upon entering Inertia Identification USER state.• static void USER_onEntryDuty (USER_t ∗pUSER)
Runs code upon entering PWM Duty Control USER state.• static void USER_onEntryVoltage (USER_t ∗pUSER)
Runs code upon entering Voltage Control USER state.• static void USER_onEntryCurrent (USER_t ∗pUSER)
Runs code upon entering Current Control USER state.• static void USER_onEntrySpeed (USER_t ∗pUSER)
Runs code upon entering Speed Control USER state.• static void USER_onEntryPlan (USER_t ∗pUSER)
Runs code upon entering Plan USER state.• static void USER_onEntryBrake (USER_t ∗pUSER)
Runs code upon entering Braking USER state.
Variables
• static SCM_t scmSCM block.
• static INERTIA_t inertiaINERTIA block.
• static BRAKE_t brakeBRAKE control block.
• static ST_VELPLAN_Handle pVelPlan• static ST_VelPlan_t VelPlan
2.2.2 Data Structure Documentation
2.2.2.1 struct USER_config_t
Data Fields
30Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
bool disable←↩FaultsinBrake
Setting this will disable all faults while applying brake
bool FWEnabled Controls if Field Weakening is allowed
uint16_t startupRetry←↩Attempts
Number of startup retries configured
uint16_t startupRetry←↩Delay
Startup retry delay counter incremented at Fast ISR sample rate
2.2.2.2 struct USER_internal_t
Data Fields
uint16_t autoRetry←↩Delay
Auto retry delay counter
uint16_t startupRetry←↩Counter
Startup retry counter
2.2.2.3 struct USER_command_t
Data Fields
_lq dutyA duty cycle to inverter { unit: [percentage], value range: [0,1.0] }
_lq dutyB duty cycle to inverter { unit: [percentage], value range: [0,1.0] }
_lq dutyC duty cycle to inverter { unit: [percentage], value range: [0,1.0] }
bool enableClamp←↩Phases
flag to clamp phases low
bool enableDC←↩Injection
configurable flag to enable DC injection
_lq IqRefMax Sets maximum Iq reference for speed loop { unit: [pu amps] }
_lq IqRefMin Sets minimum Iq reference for speed loop { unit: [pu amps] }
_lq limitAcc Profile generator acceleration limit { unit: [(pu rpm)/s] }
Freescale SemiconductorKinetis Motor Suite API Reference Manual
31
Sensorless Velocity Control
_lq lq20LimitJerk Profile generator jerk limit { unit: [(pu rpm)/s∧2] }
bool pwmDisable flag to enable/disable PWM output
bool resetFault set to true to reset a fault
bool runTrajectory Configurable value to enable/ disable profile generator
TRF_r←↩Vector16_t
statorRef←↩Current
stator reference current { unit: [pu amps] }
TRF_r←↩Vector32_t
statorRef←↩Voltage
stator reference voltage { unit: [pu volts] }
_lq targetSpeed Target speed (in pu rpm) { unit: [pu rpm] }
2.2.2.4 struct USER_output_t
Data Fields
bool disableFaults Indicates if faults are disabled
USER_←↩command_t
drvCommand USER command references to DRV
DSM_state_e dsmCommand USER command to change DSM state
USER_state_e inState USER the current USER state
USER_state_e prevState USER previous USER state
bool runEstimator USER command to run estimator
2.2.2.5 struct USER_t
Data Fields
USER_←↩command_t
command Set the desired commands
USER_config←↩_t
config Holds the configuration for the USER block
USER_←↩internal_t
internal Internal variables to USER
32Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
USER_←↩output_t
output Stores the outputs from the USER block
USER_state_e state Set the desired USER state
2.2.3 Macro Definition Documentation
2.2.3.1 #define SCM_CHANGE_TIME_COUNT ((uint16_t)1024)
Time interval between motor parameter measurements (in timer counts)
Referenced by USER_cfgSCM().
2.2.3.2 #define SCM_HI_SCM_THD (0.9)
Relative high current threshold for stator inductance measurement.
Referenced by USER_cfgSCM().
2.2.3.3 #define SCM_LO_SCM_THD (0.1)
Relative low current threshold for stator inductance measurement.
Referenced by USER_cfgSCM().
2.2.3.4 #define SCM_LS_OFF_TIME_COUNT ((uint16_t)2048)
Time interval with zero voltage during stator inductance measurement (in timer counts)
Referenced by USER_cfgSCM().
2.2.3.5 #define SCM_LS_STEADY_STATE_TIME_COUNT ((uint16_t)1024)
Steady-state time interval for stator inductance measurement (in timer counts)
Referenced by USER_cfgSCM().
2.2.3.6 #define SCM_PM_STEADY_STATE_TIME_COUNT ((uint16_t)4096)
Steady-state time interval for PM Flux measurement (in timer counts)
Referenced by USER_cfgSCM().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
33
Sensorless Velocity Control
2.2.3.7 #define SCM_RS_STEADY_STATE_TIME_COUNT ((uint16_t)2048)
Steady-state time interval for stator resistance measurement (in timer counts)
Referenced by USER_cfgSCM().
2.2.4 Enumeration Type Documentation
2.2.4.1 enum USER_state_e
USER state-machine states.
Enumerator
USER_IDLE 0: USER IDLE stateUSER_FAULT 1: USER FAULT stateUSER_SCM 2: USER self-commissioning stateUSER_INERTIA 3: USER inertia estimation stateUSER_RUN_DUTY 4: DSM run PWM duty control stateUSER_RUN_VOLTAGE 5: DSM run voltage control stateUSER_RUN_CURRENT 6: USER run current control stateUSER_RUN_SPEED 7: USER run speed control stateUSER_RUN_PLAN 8: USER run a motion plan stateUSER_BRAKE 9: USER braking state
2.2.5 Function Documentation
2.2.5.1 void USER_cfgBrake ( const BRAKE_config_t ∗const brakeCfg )
Configures the BRAKE module.
Parameters
brakeCfg - pointer to the BRAKE configuration block
Returns
none
References BRAKE_config().
2.2.5.2 void USER_cfgInertia ( const INERTIA_config_t ∗const inertiaConfig, _lqsampleTime )
Configures the INERTIA module.
34Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
inertiaConfig - pointer to the INERTIA configuration block
sampleTime - time between successive INERTIA calls
Returns
none
References INERTIA_config().
2.2.5.3 void USER_cfgSCM ( const SCM_config_t ∗const scmCfg, void ∗ scmData, _sqratedVoltage, _sq ratedCurrent, _sq ratedSpeed, _lq lq16BaseSpeedElecFreq,_lq pwmSampleTime )
References _LQ, SCM_CHANGE_TIME_COUNT, SCM_config(), SCM_HI_SCM_THD, SCM_LO_←↩SCM_THD, SCM_LS_OFF_TIME_COUNT, SCM_LS_STEADY_STATE_TIME_COUNT, SCM_P←↩M_STEADY_STATE_TIME_COUNT, and SCM_RS_STEADY_STATE_TIME_COUNT.
2.2.5.4 void USER_config ( USER_t ∗ pUSER, const USER_config_t ∗const config )
Configures the USER module.
Parameters
pUSER - pointer to the USER block
config - configuration structure for USER block
Returns
none
References USER_t::config.
2.2.5.5 USER_t ∗ USER_init ( void ∗ pMem, size_t size )
Initializes USER module.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
35
Sensorless Velocity Control
Parameters
pMem - pointer to memory where the USER block is stored
size - size of memory where the USER block is stored
Returns
handle - interface to access the USER block
References USER_IDLE.
2.2.5.6 void USER_initStructs ( USER_t ∗ pUSER, _lq limitAcc, _lq lq20LimitJerk, _lqIqRefMax, _lq IqRefMin )
Initializes all structs in USER module.
Parameters
pUSER - pointer to the USER block
limitAcc - initial acceleration limit
lq20LimitJerk - initial jerk limit
IqRefMax - initial maximum Iq reference
IqRefMin - initial minimum Iq reference
Returns
none
References BRAKE_init(), USER_t::command, USER_output_t::drvCommand, INERTIA_init(), USE←↩R_output_t::inState, USER_command_t::IqRefMax, USER_command_t::IqRefMin, USER_command←↩_t::limitAcc, USER_command_t::lq20LimitJerk, USER_t::output, SCM_init(), USER_t::state, and US←↩ER_IDLE.
2.2.5.7 static void USER_OnEntry ( USER_t ∗ pUSER, USER_state_e commandedState )[static]
Sets up the USER module upon entering a state.
36Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
commanded←↩State
- the next state commanded
Returns
none
References USER_BRAKE, USER_FAULT, USER_IDLE, USER_INERTIA, USER_onEntryBrake(),USER_onEntryCurrent(), USER_onEntryDuty(), USER_onEntryFault(), USER_onEntryIdle(), USER_←↩onEntryInertia(), USER_onEntryPlan(), USER_onEntryScm(), USER_onEntrySpeed(), USER_onEntry←↩Voltage(), USER_RUN_CURRENT, USER_RUN_DUTY, USER_RUN_PLAN, USER_RUN_SPEED,USER_RUN_VOLTAGE, and USER_SCM.
Referenced by USER_updateSlowTick().
2.2.5.8 static void USER_onEntryBrake ( USER_t ∗ pUSER ) [static]
Runs code upon entering Braking USER state.
Runs code upon entering USER Braking state.
Parameters
pUSER - pointer to the USER block
Returns
none
References BRAKE_COAST, BRAKE_DC_INJECTION, BRAKE_REGEN, BRAKE_ZERO_VECT←↩OR, BRAKE_config_t::brakingType, BRAKE_output_t::clampPhasesLow, USER_t::command, BRA←↩KE_t::config, USER_output_t::drvCommand, DSM_CURRENT, DSM_IDLE, DSM_MOTION, DSM←↩_PWM_DUTY, USER_output_t::dsmCommand, USER_command_t::enableClampPhases, BRAKE_t←↩::output, USER_t::output, USER_output_t::runEstimator, USER_command_t::runTrajectory, and USE←↩R_command_t::targetSpeed.
Referenced by USER_OnEntry().
2.2.5.9 static void USER_onEntryCurrent ( USER_t ∗ pUSER ) [static]
Runs code upon entering Current Control USER state.
Runs code upon entering USER Current control state.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
37
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, DSM_CURRENT, USER_output_t←↩::dsmCommand, USER_command_t::limitAcc, USER_command_t::lq20LimitJerk, USER_t::output, U←↩SER_output_t::runEstimator, USER_command_t::runTrajectory, and USER_command_t::targetSpeed.
Referenced by USER_OnEntry().
2.2.5.10 static void USER_onEntryDuty ( USER_t ∗ pUSER ) [static]
Runs code upon entering PWM Duty Control USER state.
Runs code upon entering USER PWM Duty state.
Parameters
pUSER - pointer to the USER block
Returns
none
References DSM_PWM_DUTY, USER_output_t::dsmCommand, USER_t::output, and USER_output←↩_t::runEstimator.
Referenced by USER_OnEntry().
2.2.5.11 static void USER_onEntryFault ( USER_t ∗ pUSER ) [static]
Runs code upon entering Fault USER state.
Runs code upon entering USER FAULT state.
Parameters
38Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
pUSER - pointer to the USER block
Returns
none
References USER_t::output, and USER_output_t::runEstimator.
Referenced by USER_OnEntry().
2.2.5.12 static void USER_onEntryIdle ( USER_t ∗ pUSER ) [static]
Runs code upon entering Idle USER state.
Runs code upon entering USER IDLE state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::output, and USER_output_t::runEstimator.
Referenced by USER_OnEntry().
2.2.5.13 static void USER_onEntryInertia ( USER_t ∗ pUSER ) [static]
Runs code upon entering Inertia Identification USER state.
Runs code upon entering USER Inertia state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, DSM_CURRENT, USER_output_t←↩::dsmCommand, INERTIA_reset(), USER_command_t::limitAcc, USER_command_t::lq20LimitJerk,USER_t::output, USER_output_t::runEstimator, and USER_command_t::runTrajectory.
Referenced by USER_OnEntry().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
39
Sensorless Velocity Control
2.2.5.14 static void USER_onEntryPlan ( USER_t ∗ pUSER ) [static]
Runs code upon entering Plan USER state.
Runs code upon entering USER Plan state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_output_t::drvCommand, DSM_MOTION, USER_output_t::dsmCommand, USER_←↩t::output, USER_output_t::runEstimator, USER_command_t::runTrajectory, STVELPLAN_setEnable(),and STVELPLAN_setReset().
Referenced by USER_OnEntry().
2.2.5.15 static void USER_onEntryScm ( USER_t ∗ pUSER ) [static]
Runs code upon entering Self Commissioning Module USER state.
Runs code upon entering USER Self Commissioning state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_command_t::limitAcc, USER←↩_command_t::lq20LimitJerk, USER_t::output, USER_output_t::runEstimator, and USER_command_t←↩::runTrajectory.
Referenced by USER_OnEntry().
2.2.5.16 static void USER_onEntrySpeed ( USER_t ∗ pUSER ) [static]
Runs code upon entering Speed Control USER state.
Runs code upon entering USER Speed control state.
40Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
Returns
none
References DSM_MOTION, USER_output_t::dsmCommand, USER_t::output, and USER_output_t←↩::runEstimator.
Referenced by USER_OnEntry().
2.2.5.17 static void USER_onEntryVoltage ( USER_t ∗ pUSER ) [static]
Runs code upon entering Voltage Control USER state.
Runs code upon entering USER Voltage control state.
Parameters
pUSER - pointer to the USER block
Returns
none
References DSM_VOLTAGE, USER_output_t::dsmCommand, USER_t::output, and USER_output_t←↩::runEstimator.
Referenced by USER_OnEntry().
2.2.5.18 static void USER_OnExit ( USER_t ∗ pUSER ) [static]
Cleans up the USER module upon exiting a state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_output_t::inState, SCM_t::output, USER_t::output, SCM_resetOutputs(), SCM_Stop,SCM_output_t::state, STVELPLAN_reset(), USER_INERTIA, USER_resetDRVCommands(), USER_←↩RUN_PLAN, and USER_SCM.
Referenced by USER_updateSlowTick().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
41
Sensorless Velocity Control
2.2.5.19 void USER_resetDRVCommands ( USER_t ∗ pUSER )
Resets drive commands going out of the USER module.
Parameters
pUSER - pointer to the USER module
Returns
none
References _LQ, _SQ15, TRF_rVector16_t::d, TRF_rVector32_t::d, USER_output_t::drvCommand,DSM_IDLE, USER_output_t::dsmCommand, USER_command_t::dutyA, USER_command_t::dutyB,USER_command_t::dutyC, USER_command_t::enableClampPhases, USER_command_t::enableDC←↩Injection, USER_t::output, USER_command_t::pwmDisable, TRF_rVector16_t::q, TRF_rVector32_t←↩::q, USER_command_t::runTrajectory, USER_command_t::statorRefCurrent, and USER_command_t←↩::statorRefVoltage.
Referenced by USER_OnExit().
2.2.5.20 static void USER_runBrakeStateFastTick ( USER_t ∗ pUSER, bool brakeEnable,_lq speedOutMax, _lq speedOutMin ) [static]
Runs the Braking USER state (Fast ISR)
Parameters
pUSER - pointer to the USER block
brakeEnable - true if braking is currently active
speedOutMax - speed loop max output
speedOutMin - speed loop min output
Returns
none
References BRAKE_COAST, BRAKE_run(), BRAKE_ZERO_VECTOR, BRAKE_config_t::braking←↩Type, BRAKE_output_t::clampPhasesLow, BRAKE_t::config, USER_t::config, BRAKE_output_t←↩::control, USER_output_t::disableFaults, USER_config_t::disableFaultsinBrake, USER_output_t::drv←↩Command, DSM_IDLE, USER_output_t::dsmCommand, USER_command_t::enableClampPhases, B←↩RAKE_t::output, USER_t::output, and USER_command_t::pwmDisable.
Referenced by USER_updateFastTick().
42Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
2.2.5.21 static void USER_runBrakeStateSlowTick ( USER_t ∗ pUSER, _lq trajRefSpeed) [static]
Runs the Braking USER state (Slow ISR)
Runs the Braking state (Slow actions)
Parameters
pUSER - pointer to the USER block
trajRefSpeed - rotor reference speed as output by the TRAJ block
Returns
none
Parameters
pUSER - pointer to the USER block
trajRefSpeed - current reference speed
Returns
none
References _LQ, _SQ15, BRAKE_COAST, BRAKE_DC_INJECTION, BRAKE_REGEN, BRAK←↩E_ZERO_VECTOR, BRAKE_config_t::brakingType, USER_t::command, BRAKE_t::config, BR←↩AKE_output_t::control, TRF_rVector16_t::d, USER_output_t::drvCommand, DSM_IDLE, USER_←↩output_t::dsmCommand, BRAKE_output_t::enableDCInjection, USER_command_t::enableDCInjection,USER_command_t::IqRefMax, USER_command_t::IqRefMin, USER_command_t::limitAcc, USE←↩R_command_t::lq20LimitJerk, BRAKE_t::output, USER_t::output, TRF_rVector16_t::q, BRAKE_←↩output_t::rotorRefSpeed, BRAKE_output_t::speedOutMax, BRAKE_output_t::speedOutMin, USER_←↩command_t::statorRefCurrent, BRAKE_output_t::statorRefCurrentD, and USER_command_t::target←↩Speed.
Referenced by USER_updateSlowTick().
2.2.5.22 static void USER_runCurrentState ( USER_t ∗ pUSER ) [static]
Runs the Current Control USER state.
Runs the Current control USER state.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
43
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_command_t::enableDCInjection,USER_command_t::limitAcc, USER_command_t::lq20LimitJerk, USER_t::output, USER_command_←↩t::statorRefCurrent, and USER_command_t::targetSpeed.
Referenced by USER_updateSlowTick().
2.2.5.23 static void USER_runDutyState ( USER_t ∗ pUSER ) [static]
Runs the PWM Duty Control USER state.
Runs the PWM Duty control USER state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_command_t::dutyA, USER_←↩command_t::dutyB, USER_command_t::dutyC, USER_command_t::enableClampPhases, and USER_←↩t::output.
Referenced by USER_updateSlowTick().
2.2.5.24 static USER_state_e USER_runFaultState ( USER_t ∗ pUSER, DSM_t ∗ pDSM )[static]
Runs the Fault USER state.
Runs the USER IDLE state.
44Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
pDSM - pointer to the DSM block
Returns
USER_state_e The next state of USER user, indication a fault has been cleared
Parameters
pUSER - pointer to the USER block
pDSM - pointer to the DSM block
Returns
none
References USER_t::command, DSM_IDLE, DSM_resetFaults(), USER_output_t::dsmCommand, U←↩SER_t::internal, USER_t::output, USER_output_t::prevState, USER_command_t::resetFault, USER←↩_internal_t::startupRetryCounter, USER_FAULT, USER_IDLE, USER_RUN_CURRENT, USER_R←↩UN_DUTY, USER_RUN_PLAN, USER_RUN_SPEED, USER_RUN_VOLTAGE, and USER_run←↩StartupRetry().
Referenced by USER_updateSlowTick().
2.2.5.25 static void USER_runIdleState ( USER_t ∗ pUSER ) [static]
Runs the Idle USER state.
Runs the USER IDLE state.
Parameters
pUSER - pointer to the USER block
Returns
none
References DSM_IDLE, USER_output_t::dsmCommand, and USER_t::output.
Referenced by USER_updateSlowTick().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
45
Sensorless Velocity Control
2.2.5.26 static USER_state_e USER_runInertiaState ( USER_t ∗ pUSER, DRV_control_econtrolType, _lq rotorSpeed ) [static]
Runs the Inertia Identification USER state.
Cleans up a USER state upon exiting it.
Parameters
pUSER - pointer to the USER block
controlType - Startup or FOC mode
rotorSpeed - Speed feedback
Returns
USER_state_e USER state that INERTIA will run in the next slow tick
Parameters
pUSER - pointer to the USER block
controlType - Startup or FOC mode
rotorSpeed - Speed feedback
Returns
USER_state_e USER state that the SCM will run in the next slow tick
References _SQ15, TRF_rVector16_t::d, USER_output_t::drvCommand, INERTIA_output_t::finished,FOC, INERTIA_run(), INERTIA_output_t::IqRef, INERTIA_t::output, USER_t::output, TRF_←↩rVector16_t::q, USER_command_t::statorRefCurrent, INERTIA_output_t::targetSpeed, USER_←↩command_t::targetSpeed, USER_IDLE, and USER_INERTIA.
Referenced by USER_updateSlowTick().
2.2.5.27 static USER_state_e USER_runPlanState ( USER_t ∗ pUSER, bool trajComplete) [static]
Runs the Plan USER state.
46Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
trajComplete - trajectory block has completed a trajectory
Returns
USER_state_e USER state that PLAN will run in the next slow tick
Parameters
pUSER - pointer to the USER block
trajStatus - trajectory block status
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_command_t::IqRefMax, USE←↩R_command_t::IqRefMin, USER_command_t::limitAcc, USER_command_t::lq20LimitJerk, USER_t←↩::output, ST_PLAN_IDLE, STVELPLAN_getAccelerationLimit(), STVELPLAN_getJerkLimit(), ST←↩VELPLAN_getStatus(), STVELPLAN_getVelocitySetpoint(), STVELPLAN_run(), STVELPLAN_run←↩Tick(), STVELPLAN_setUnitProfDone(), USER_command_t::targetSpeed, USER_IDLE, and USER_←↩RUN_PLAN.
Referenced by USER_updateSlowTick().
2.2.5.28 static USER_state_e USER_runScmState ( USER_t ∗ pUSER, _lq fieldAngle,_lq trajRefSpeed ) [static]
Runs the Self Commissioning Module USER state.
Cleans up a USER state upon exiting it.
Parameters
pUSER - pointer to the USER block
trajRefSpeed - Target speed
Freescale SemiconductorKinetis Motor Suite API Reference Manual
47
Sensorless Velocity Control
fieldAngle - field angle
Returns
USER_state_e USER state that the SCM will run in the next slow tick
Parameters
pUSER - pointer to the USER block
fieldAngle - Rotor angle
trajRefSpeed - Target speed
Returns
USER_state_e USER state that the SCM will run in the next slow tick
References _LQ, _LQsincosPU(), _SQ15, TRF_orient32_t::cosAngle, TRF_rVector16_t::d, TRF_r←↩Vector32_t::d, USER_output_t::drvCommand, DSM_CURRENT, DSM_MOTION, DSM_VOLTAGE,USER_output_t::dsmCommand, USER_command_t::enableClampPhases, SCM_output_t::enableD←↩CInjection, USER_command_t::enableDCInjection, SCM_output_t::enableLsDecay, SCM_t::output,USER_t::output, TRF_rVector16_t::q, TRF_rVector32_t::q, SCM_output_t::rotorRefCurrent, SCM_←↩output_t::rotorRefSpeed, SCM_Ls, SCM_Pm, SCM_Rs, SCM_Stop, SCM_updateSlowTick(), TRF_←↩orient32_t::sinAngle, SCM_output_t::state, USER_command_t::statorRefCurrent, USER_command_t←↩::statorRefVoltage, USER_command_t::targetSpeed, USER_IDLE, and USER_SCM.
Referenced by USER_updateSlowTick().
2.2.5.29 static void USER_runSpeedState ( USER_t ∗ pUSER ) [static]
Runs the Speed Control USER state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_command_t::IqRefMax, USE←↩R_command_t::IqRefMin, USER_command_t::limitAcc, USER_command_t::lq20LimitJerk, USER_t←↩::output, USER_command_t::runTrajectory, and USER_command_t::targetSpeed.
Referenced by USER_updateSlowTick().
48Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
2.2.5.30 static bool USER_runStartupRetry ( USER_t ∗ pUSER, DSM_t ∗ pDSM )[static]
References DSM_nonClrFaults_t::all, USER_internal_t::autoRetryDelay, DSM_clrFaults_t::bits, DS←↩M_t::clearableFaults, USER_t::config, USER_t::internal, DSM_clrFaults_t::DSM_clrFaultsBits_s::mot←↩StartupFailure, DSM_t::nonClearableFaults, USER_config_t::startupRetryAttempts, USER_internal_t←↩::startupRetryCounter, and USER_config_t::startupRetryDelay.
Referenced by USER_runFaultState().
2.2.5.31 static void USER_runVoltageState ( USER_t ∗ pUSER ) [static]
Runs the Voltage Control USER state.
Runs the Voltage control USER state.
Parameters
pUSER - pointer to the USER block
Returns
none
References USER_t::command, USER_output_t::drvCommand, USER_t::output, and USER_command←↩_t::statorRefVoltage.
Referenced by USER_updateSlowTick().
2.2.5.32 USER_selfCommissioningState ( USER_t ∗ pUSER, DSM_t ∗ pDSM, boolscComplete )
Processes USER self-commissioning state.
Parameters
pDSM - pointer to the drive module
scComplete - indicates if self commissioning is finished
Returns
none
Freescale SemiconductorKinetis Motor Suite API Reference Manual
49
Sensorless Velocity Control
2.2.5.33 void USER_setInertiaOutput ( _sq output )
Inertia Estimation update output signal.
Inertia Estimation update output.
Parameters
output - Iq ref value to be forced on the INERTIA output
Returns
none
References INERTIA_setOutput().
2.2.5.34 void USER_updateFastTick ( USER_t ∗ pUSER, const FEEDBACK_output_t∗const pADC, _lq speedOutMax, _lq speedOutMin )
Updates USER module at the Fast ISR.
Parameters
pUSER - pointer to the USER module
pADC - pointer to the FEEDBACK output
speedOutMax - max Iqref configured in the SPEED module
speedOutMin - min Iqref configured in the SPEED module
Returns
none
References USER_output_t::inState, USER_t::output, SCM_updateFastTick(), USER_BRAKE, USER←↩_runBrakeStateFastTick(), and USER_SCM.
2.2.5.35 void USER_updateSlowTick ( USER_t ∗ pUSER, DSM_t ∗ pDSM, booltrajComplete, DRV_control_e controlType, _lq rotorSpeed, _lq fieldAngle, _lqtrajRefSpeed )
Updates the USER module at the Slow ISR.
50Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensorless Velocity Control
Parameters
pUSER - pointer to the USER block
pDSM - pointer to the DSM block
trajComplete - trajectory block has completed a trajectory
controlType - control method used
rotorSpeed - Speed feedback
fieldAngle - field angle
trajRefSpeed - Target speed
Returns
none
References USER_t::command, DSM_FAULT, DSM_internal_t::inStartUpRegion, USER_output_←↩t::inState, USER_t::internal, DSM_t::internal, USER_t::output, USER_output_t::prevState, USER←↩_command_t::resetFault, USER_internal_t::startupRetryCounter, USER_t::state, DSM_t::state, US←↩ER_BRAKE, USER_FAULT, USER_IDLE, USER_INERTIA, USER_OnEntry(), USER_OnExit(),USER_RUN_CURRENT, USER_RUN_DUTY, USER_RUN_PLAN, USER_RUN_SPEED, USER_←↩RUN_VOLTAGE, USER_runBrakeStateSlowTick(), USER_runCurrentState(), USER_runDutyState(),USER_runFaultState(), USER_runIdleState(), USER_runInertiaState(), USER_runPlanState(), USER_←↩runScmState(), USER_runSpeedState(), USER_runVoltageState(), and USER_SCM.
2.2.6 Variable Documentation
2.2.6.1 brake [static]
BRAKE control block.
2.2.6.2 inertia [static]
INERTIA block.
Referenced by STPOSCTL_setInertia(), and STVELCTL_setInertia().
2.2.6.3 ST_VELPLAN_Handle pVelPlan [static]
2.2.6.4 scm [static]
SCM block.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
51
Sensorless Velocity Control
2.2.6.5 ST_VelPlan_t VelPlan [static]
52Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Sensored Velocity Control
2.3 Sensored Velocity ControlThe specific API interface for the User block inside of Sensored Velocity Control.
Differences from Sensorless Velocity
The primary difference between User block in Sensored Velocity control and Sensorless Velocity controlis that the Startup Retry mechanism has been replaced with the Alignment mechanism. The alignmentroutine forces the motor into an alignment state so that the encoder reading can be aligned to a knownmotor position. It does this by injecting D-axis current into the motor at an electrical angle of 0. Whichforces the motor to conform to this known electrical angle. The encoder reading is reset to 0, so that itwill accurately represent the motor's true angle. This is always done the first time that the User block iscommanded to go to a state where it needs to run the complete FOC. This step can be done at any time bysetting a flag to false.
For more specific details about this implementation refer to the user.c and user.h included in the SensoredVelocity reference project.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
53
Sensored Position Control
2.4 Sensored Position ControlThe specific API interface for the User block inside of Sensored Position Control.
Differences from Sensorless Velocity
One of the differences between User block in Sensored Position control and Sensorless Velocity controlis that the Startup Retry mechanism has been replaced with the Alignment mechanism. This alignmentroutine is identical to the one found in the Sensored Velocity reference project. The alignment routineforces the motor into an alignment state so that the encoder reading can be aligned to a known motorposition. It does this by injecting D-axis current into the motor at an electrical angle of 0. Which forcesthe motor to conform to this known electrical angle. The encoder reading is reset to 0, so that it willaccurately represent the motor's true angle. This is always done the first time that the User block iscommanded to go to a state where it needs to run the complete FOC. This step can be done at any time bysetting a flag to false.
The User block included for the Sensored Position reference design also has an expanded set of availablemotion commands so that position steps can be commanded and limits on velocity during a position profilecan be defined.
For more specific details about this implementation refer to the user.c and user.h included in the SensoredPosition reference project.
54Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 3Self Commissioning3.1 OverviewControls automatic motor parameter identification.
Functional description
The SCM ("self commissioning") block automatically identifies three electrical characteristics of a per-manent magnet or brushless DC motor:
• stator resistance• stator inductance• permanent magnet rotor flux
These key motor characteristics, in combination with the Basic Motor Parameters (rated current, polepairs, etc.) entered by the user, allow KMS to configure the current control loop (CURRENT) and speedand angle estimators (EST) which allow the user to spin the motor.
KMS performs resistance and inductance measurements by applying currents that are configurable aspercentages of rated current to excite the motor. During the resistance measurement, the current is slowlyincreased until it reaches the configured percentage of rated current. Once the desired current is reached,the current feedbacks are sampled and averaged over time and the stator voltage is estimated. Using Ohm’slaw, KMS is able to calculate the resistance. An example of this process is provided below.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
55
Overview
Figure 3.1.1: Resistance Measurement Example
In order to perform the inductance measurement, the current is again built up to a configurable level, andthe drive is then switched into clamp low, where all three low side switches are turned on. From this thecurrent decay is measured which when combined with the resistance, can give the inductance. An exampleof this process is provided below.
Figure 3.1.2: Inductance Measurement Example
After the resistance and inductance are calculated, the current controller is configured using pole-zerocancellation methods, and the motor is commanded to spin at an electrical frequency that is configurable
56Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
as a percentage of the motor’s rated frequency (determined by rated speed and number of pole pairs).While the motor is spinning, the instantaneous flux is calculated using values for average current and thepreviously determined stator inductance value, and instantaneous flux values are averaged to arrive at afinal permanent magnet flux value. An example of the start of this process is provided below.
Figure 3.1.3: Rotor Flux Measurement Example
In certain scenarios, SCM may require DC injection current or all phases clamped low. The SCM blockproduces outputs that will configure these functions within other blocks.
Block diagram detail
Figure 3.1.4: Self Commissioning
Freescale SemiconductorKinetis Motor Suite API Reference Manual
57
Overview
Configuration, inputs, and outputs
User configuration of the SCM block is achieved primarily by the specification of current and frequency tobe applied, as a percentage of the motor’s rated values. Additional configuration arguments include ratedmotor characteristics and time intervals for calculating resistance, inductance, and flux.
Outputs of the SCM block include measured values for stator resistance, stator inductance, permanentmagnet flux, and state of SCM operation.
Code security breakdown
The table below describes the partitioning of SCM block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyStructures for module and output;functions for initialization, configu-ration, running, and updating
N/A Implementation of functions tomeasure motor parameters automat-ically
Execution
The SCM block is executed in the slow ISR and resides outside of the control flow, as it is typicallyperformed once in the early stage of the design process to get the motor up and running. Once the motorcharacteristics are well known, it is not necessary for this function to run repetitively.
User customization example
After initially identifying the motor's parameters, the Open Source portion of the SCM block can beremoved from the firmware. Since the motor parameters typically only need to be identified during theinitial design phase, they can be stored as the defaults in the reference project.
Data Structures• struct SCM_config_t
Self Commissioning configuration structure. More...• struct SCM_output_t
Self Commissioning output structure. More...• struct SCM_t
SCM module structure. More...
Macros• #define SCM_PRV_SIZE 32
58Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
Enumerations• enum SCM_state_e {
SCM_Stop = 0,SCM_Rs,SCM_Ls,SCM_Pm }
Self Commissioning state-machine states.
Functions• SCM_t ∗ SCM_init (void ∗pMem, size_t size)
Self commissioning initialization.• void SCM_config (SCM_t ∗handle, const SCM_config_t ∗const config, void ∗scmData, _sq rated←↩
Voltage, _sq ratedCurrent, _sq ratedSpeed, _lq lq16BaseSpeedElecFreq, _lq focSampleTime,uint16_t rsSteadyStateTimeCount, uint16_t lsSteadyStateTimeCount, uint16_t lsOffTimeCount,uint16_t pmSteadyStateTimeCount, uint16_t scmChangeTimeCount, _lq scmHiThd, _lq scmLo←↩Thd)
• void SCM_updateSlowTick (SCM_t ∗handle, bool enable, bool closedLoop, const TRF_orient32_t∗const pOrient, _lq refRampOutput)
• void SCM_updateFastTick (SCM_t ∗handle, const FEEDBACK_output_t ∗const pADC)• void SCM_resetOutputs (SCM_t ∗handle)
Resets (zeroes out) the self-commissioning (SCM) module's output signals.
3.2 Data Structure Documentation
3.2.1 struct SCM_config_t
Self Commissioning configuration structure.
Data Fields
_lq R_igbt IGBT resistance / DRV_BASE_RESISTANCE { unit: [pu ohms]}
_sq relativeLs←↩Current
Percentage (rel) of rated current applied for stator inductance ID
_sq relativePm←↩FluxFrequency
Percentage (rel) of rated frequency for PM Flux ID
_sq relativeRs←↩Current
Percentage (rel) of rated current applied for stator resistance ID
Freescale SemiconductorKinetis Motor Suite API Reference Manual
59
Macro Definition Documentation
SCM_state_e state Measurement the SCM should perform
3.2.2 struct SCM_output_t
Self Commissioning output structure.
Data Fields
bool enableDC←↩Injection
Flag to indicate if SCM needs DC injection
bool enableLsDecay
bool finished true: SCM has finished a commissioning stage
_lq pmFlux Permanent Magnet flux { unit: [pu webers] }
_sq rotorRef←↩Current
Output stator reference current rs & ls calculation (SQ15) { unit:[pu amps] }
_lq rotorRefSpeed Output Rotor ref Speed for pmFlux calculation { unit: [pu rpm] }
SCM_state_e state SCM State
_lq statorInd Stator inductance { unit: [pu henries] }
_lq statorRes Stator resistance { unit: [pu ohms] }
3.2.3 struct SCM_t
SCM module structure.
Data Fields
SCM_config←↩_t
config SCM Configuration structure
SCM_output←↩_t
output SCM output structure
uint32_t prv[SCM_PR←↩V_SIZE]
Private data block
3.3 Macro Definition Documentation
3.3.1 #define SCM_PRV_SIZE 32
60Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
3.4 Enumeration Type Documentation
3.4.1 enum SCM_state_e
Self Commissioning state-machine states.
Enumerator
SCM_Stop Self Commissioning Stop (Idle) stateSCM_Rs Self Commissioning Stator Resistance stateSCM_Ls Self Commissioning Stator Inductance stateSCM_Pm Self Commissioning PM Flux state
3.5 Function Documentation
3.5.1 void SCM_config ( SCM_t ∗ handle, const SCM_config_t ∗constconfig, void ∗ scmData, _sq ratedVoltage, _sq ratedCurrent, _sqratedSpeed, _lq lq16BaseSpeedElecFreq, _lq focSampleTime,uint16_t rsSteadyStateTimeCount, uint16_t lsSteadyStateTimeCount,uint16_t lsOffTimeCount, uint16_t pmSteadyStateTimeCount, uint16_tscmChangeTimeCount, _lq scmHiThd, _lq scmLoThd )
Referenced by USER_cfgSCM().
3.5.2 SCM_init ( void ∗ pMem, size_t size )
Self commissioning initialization.
Parameters
pMem - pointer to memory where the SCM block is stored
size - size of memory where the SCM block is stored
Returns
handle - interface to access the SCM block
Referenced by USER_initStructs().
3.5.3 SCM_resetOutputs ( SCM_t ∗ handle )
Resets (zeroes out) the self-commissioning (SCM) module's output signals.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
61
Function Documentation
Parameters
handle - interface to access the SCM block
Returns
none
Referenced by USER_OnExit().
3.5.4 void SCM_updateFastTick ( SCM_t ∗ handle, const FEEDBACK_output_t∗const pADC )
Referenced by USER_updateFastTick().
3.5.5 void SCM_updateSlowTick ( SCM_t ∗ handle, bool enable, bool closedLoop,const TRF_orient32_t ∗const pOrient, _lq refRampOutput )
Referenced by USER_runScmState().
62Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 4Inertia4.1 OverviewControls automatic system inertia measurement.
Functional description
The Inertia block identifies the mechanical inertia of a motor system. Mechanical inertia consists of themotor shaft and any part of the application that is rigidly coupled to the motor shaft and will rotate withthe shaft. This is contrasted with load, better identified as load torque, which will serve as an externaltorque that must be overcome. An easy example to consider is the washing machine: the drum constitutesinertia whereas the clothes in the drum constitute load. A visual example is provided below.
Figure 4.1.1: Example of What is and isn't Inertia
An estimate of system inertia is required by KMS’ advanced velocity controller, which uses the inertiainput to determine the amount of torque required to accelerate the system and ensure precise motioncontrol.
The inertia can only be measured when the motor is operating in the field oriented control region. Oncethe motor is operating in field oriented control, the torque will be increased at a configurable rate until theconfigured goal speed is reached. It will then decelerate quickly. This motion profile allows for KMS to
Freescale SemiconductorKinetis Motor Suite API Reference Manual
63
Overview
sample velocity feedback and determine the inertia of the system. The closest block diagram to referencefor inertia identification is Torque Control with the exception that the torque reference is provided by theInertia block. An example of the inertia estimation process is provided below.
Figure 4.1.2: Example of Inertia Measurement
KMS also provides an estimate of friction via this same profile, but this is purely informational and is notrequired for successful usage of KMS’ advanced velocity controller.
The Inertia block is effectively a simplified wrapper block for the core algorithms of SpinTAC™ VelocityIdentify submodule.
Block diagram detail
Figure 4.1.3: Inertia
64Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Configuration, inputs, and outputs
User configuration of the Inertia block is achieved primarily by the specification of the speed that themotor should attempt to accelerate to and the time allotted to ramp to this speed. Additional configurationarguments include trajectory (acceleration & jerk) and current (Q-axis current) constraints.
The input to the Inertia block is the velocity feedback from the Estimator block.
The primary outputs of the Inertia block is the instantaneous Iq reference and the estimates of systeminertia and friction.
Code security breakdown
The table below describes the partitioning of Inertia block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyStructures for configuring inertiaidentification; set & get functions
N/A Implementation of automatic inertiaidentification algorithm
Execution
The Inertia block is executed in the slow ISR and resides outside of the control flow, as it is typicallyperformed once in the early stage of the design process to get the application running. Once the motorsystem inertia is well known, it is not necessary for this function to run repetitively.
User customization example
After initially identifying the system inertia and friction, the Inertia block can be removed from thefirmware. Since the system inertia and friction typically only need to be identified during the initial designphase, they can be stored as the defaults in the reference project.
This is particularly true given the insensitivity of KMS’ advanced controller to changes in inertia - de-pending on application, KMS may require only an order of magnitude approximation of inertia to achievegood operation.
Data Structures• struct INERTIA_config_t
Inertia module config structure. More...• struct INERTIA_output_t
Inertia module output structure. More...• struct INERTIA_t• struct INERTIA_Status_e
Freescale SemiconductorKinetis Motor Suite API Reference Manual
65
Data Structure Documentation
Inertia module status enum. More...
Macros• #define INERTIA_PRV_SIZE 40
Enumerations• enum INERTIA_Status_e {
INERTIA_IDLE =0,INERTIA_INIT,INERTIA_BUSY }
Functions• INERTIA_t ∗ INERTIA_init (void ∗pMem, size_t size)
Inertia Estimation initialization.• void INERTIA_config (INERTIA_t ∗handle, const INERTIA_config_t ∗const config, _lq sample←↩
Time)Inertia Estimation configuration.
• void INERTIA_run (INERTIA_t ∗handle, bool enable, bool closedLoopEnabled, _lq rotorSpeed)Inertia Estimation function.
• FAST void INERTIA_setOutput (INERTIA_t ∗handle, _sq output)Inertia Estimation update output.
• void INERTIA_reset (INERTIA_t ∗handle)Inertia module reset.
4.2 Data Structure Documentation
4.2.1 struct INERTIA_config_t
Inertia module config structure.
Data Fields
_lq goalSpeed goal speed setting of the Inertia identification { units: [pu rpm] }
uint16_t lpfTime_tick low pass filter time constant setting for the velocity feedback
_lq outMax output maximum limit configuration { units: [pu amps] }
_lq timeOut_sec maximum time allowed for the inertia estimation process { units:[sec] }
66Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
_lq torqueRamp←↩Time_sec
ramp time setting for the torque reference { units: [sec] }
4.2.2 struct INERTIA_output_t
Inertia module output structure.
Inertia module nested structure.
Data Fields
uint16_t error error ID
bool finished indicator for whether inertia ID is complete
_lq frictionEst estimated friction in PU Amp-sec/krpm { units: [(pu amps)/(purpm)] }
_lq inertiaEst estimated inertia in PU Amp-sec/krpm { units: [(pu amps)/(purpm)/s] }
_sq IqRef current reference generated by the inertia module { units: [puamps] }
INERTIA_←↩Status_e
status enum indicating the status of the inertia estimation
_lq targetSpeed target speed for successful inertia estimate { units: [pu rpm] }
4.2.3 struct INERTIA_t
Data Fields
INERTIA_←↩config_t
config configuration structure of inertia estimate module
INERTIA_←↩output_t
output output structure of inertia estimate module
uint32_t prv[INERTI←↩A_PRV_SIZE]
4.2.4 struct INERTIA_Status_e
Inertia module status enum.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
67
Function Documentation
4.3 Macro Definition Documentation
4.3.1 #define INERTIA_PRV_SIZE 40
4.4 Enumeration Type Documentation
4.4.1 enum INERTIA_Status_e
Enumerator
INERTIA_IDLE velocity Identify is in idle state, zero outputINERTIA_INIT velocity Identify is in init state, validating configured parametersINERTIA_BUSY velocity Identify is in busy state, identifying system inertia
4.5 Function Documentation
4.5.1 INERTIA_config ( INERTIA_t ∗ handle, const INERTIA_config_t ∗constconfig, _lq sampleTime )
Inertia Estimation configuration.
Parameters
handle - pointer to the INERTIA block
config - pointer to INERTIA_config structure
sampleTime - sample time of the inertia module
Returns
none
Referenced by USER_cfgInertia().
4.5.2 INERTIA_init ( void ∗ pMem, size_t size )
Inertia Estimation initialization.
Parameters
pMem - pointer to memory where the INERTIA block is stored
68Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
size - size of memory where the INERTIA block is stored
Returns
handle - interface to access the INERTIA block
Referenced by USER_initStructs().
4.5.3 INERTIA_reset ( INERTIA_t ∗ handle )
Inertia module reset.
Parameters
handle - pointer to the INERTIA block
Returns
none
Referenced by USER_onEntryInertia().
4.5.4 INERTIA_run ( INERTIA_t ∗ handle, bool enable, bool closedLoopEnabled,_lq rotorSpeed )
Inertia Estimation function.
Parameters
handle - pointer to the INERTIA block
enable - enables the current loop operation
closedLoop←↩Enabled
- indicates if closed loop control is available
rotorSpeed - rotor feedback speed { units: [pu rpm] }
Returns
none
Referenced by USER_runInertiaState().
4.5.5 INERTIA_setOutput ( INERTIA_t ∗ handle, _sq output )
Inertia Estimation update output.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
69
Function Documentation
Parameters
handle - pointer to the INERTIA block
output - current reference to update the inertia module (SQ15) { units: [pu amps] }
Returns
none
Referenced by USER_setInertiaOutput().
70Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 5Brake5.1 OverviewResponsible for halting motor.
Functional description
The Brake block is intended to force the motor to a halt and should be utilized when user wants above allelse to stop the motor. In this respect, the Brake block operates as an emergency stop function: protectionthresholds and normal kinematic constraints may be disregarded in pursuit of the overall objective ofstopping the motor.
The Brake block offers four methods of braking:
• Coast to stop: PWM output ceases and motor slows to a stop without any influence from the system• DC injection: D-axis current is ramped up to a user specified level and the electrical angle is held at
a constant 0 degrees to prevent rotation• Zero vector: Forces low side transistors of inverter on, tying motor phases together (Default braking
type)• Regenerative: Ramps the motor speed to 0 while limiting the available output of the speed controller.
Given proper hardware, harvests energy from the motor ramp-down.
These are in addition to the option of ramping to stop, which simply involves setting a target speed of zero.In this case, the motor will obey motion trajectory limits - it will slow to a stop according to the specifiedacceleration and jerk limits and is therefore like any other speed-to-speed transition.
The Brake block exists outside the normal control flow path but is engaged by the User block.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
71
Overview
Block diagram detail
Figure 5.1.1: Brake
Configuration, inputs, and outputs
Configuration of the Brake block involves specifying the desired brake type and applying any relevantlimits for the behavior implied by the chosen brake type. For instance, if DC injection braking is selected,the limit on this applied current and the rate at which the system ramps current to this level should bespecified.
Code security breakdown
The table below describes the partitioning of Brake block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyUser configurable elements - typeof braking, constraints on differentbraking types
Initialization & operation givenuser specifications
N/A
Execution
The Brake block operates in the Fast ISR to ensure that any action to stop the motor happens as quickly aspossible.
72Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
User customization example
The Brake block is configured by default to operate only when explicitly called by the user. However, theuser can easily tie an unwanted system state to an immediate halting of the motor by toggling the booleanthat applies the brake on a system trigger. Additionally a hardware GPIO or switch can be used to triggerthe Brake to be applied.
Data Structures• struct BRAKE_output_t• struct BRAKE_config_t• struct BRAKE_t
Brake module structure. More...
Macros• #define BRAKE_PRV_SIZE 3
Enumerations• enum BRAKE_type_e {
BRAKE_ZERO_VECTOR = 0,BRAKE_REGEN,BRAKE_COAST,BRAKE_DC_INJECTION }
Braking method enumerations.
Functions• BRAKE_t ∗ BRAKE_init (void ∗pMem, size_t size)
Brake initialization.• void BRAKE_config (BRAKE_t ∗handle, const BRAKE_config_t ∗const config)• FAST void BRAKE_run (BRAKE_t ∗handle, bool enable, _lq speedOutMax, _lq speedOutMin)
5.2 Data Structure Documentation
5.2.1 struct BRAKE_output_t
Data Fields
bool clampPhases←↩Low
true: Lower switches of inverter always on (zero state)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
73
Data Structure Documentation
bool control true: braking is currently active
bool enable←↩CurrentLoop
true: current loop needs to be enabled by drive
bool enableDC←↩Injection
true: DC injection needs to be enabled by drive
bool enableRun true: braking feature is enabled
bool enableSpeed←↩Loop
true: speed loop needs to be enabled by drive
_lq rotorRefSpeed Rotor reference speed output of the brake module
_lq speedOutMax Speed maximum Iq reference limit
_lq speedOutMin Speed minimum Iq reference limit
_sq statorRef←↩CurrentD
Current reference for DC injection braking
5.2.2 struct BRAKE_config_t
Data Fields
BRAKE_←↩type_e
brakingType Braking method to be used
_sq dcInjectIdRef DC injection current during DC_INJECTION_BRAKING [pu A]
_sq dcInjectMax←↩Delta
Maximum change of DC injection current during DC_INJECTI←↩ON_BRAKING [pu A]
_lq regenIqRefLim Absolute Braking torque limit during REGEN_BRAKING [puNm]
5.2.3 struct BRAKE_t
Brake module structure.
Data Fields
74Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
BRAKE_←↩config_t
config Braking configuration structure
BRAKE_←↩output_t
output Braking output structure
uint32_t prv[BRAKE_←↩PRV_SIZE]
Braking private data block
5.3 Macro Definition Documentation
5.3.1 #define BRAKE_PRV_SIZE 3
5.4 Enumeration Type Documentation
5.4.1 enum BRAKE_type_e
Braking method enumerations.
Enumerator
BRAKE_ZERO_VECTOR Zero Vector braking (High sides OFF, Low side ON) (default)BRAKE_REGEN Regenerative (FOC) brakingBRAKE_COAST Coast to stop braking (all PWM's disabled)BRAKE_DC_INJECTION DC Injection braking
5.5 Function Documentation
5.5.1 void BRAKE_config ( BRAKE_t ∗ handle, const BRAKE_config_t ∗constconfig )
Referenced by USER_cfgBrake().
5.5.2 BRAKE_init ( void ∗ pMem, size_t size )
Brake initialization.
Parameters
pMem - pointer to memory where the BRAKE block is stored
Freescale SemiconductorKinetis Motor Suite API Reference Manual
75
Function Documentation
size - size of memory where the BRAKE block is stored
Returns
handle - interface to access the BRAKE block
Referenced by USER_initStructs().
5.5.3 FAST void BRAKE_run ( BRAKE_t ∗ handle, bool enable, _lq speedOutMax,_lq speedOutMin )
Referenced by USER_runBrakeStateFastTick().
76Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 6Drive State Machine6.1 OverviewDefines motor states and transitions.
Functional description
The Drive State Machine (DSM) block is responsible for ensuring that KMS operates in accordance withits own block diagram. It is also responsible for handling interactions between available motor operatingstates and for defining faults encountered in operation.
The KMS block diagram (Figure 1) specifies the order of operation of different blocks. These blocks haveinternal operations as described elsewhere in this document, but the DSM is responsible for managing thetransition from one block to the next.
The order of operation may deviate from the flow described in the canonical diagram under certain circum-stances. This is where different available operating states and faults come into play. The DSM accountsfor user specification of, for example running in voltage control mode, and appropriately updates controlflow. Faults similarly trigger an alteration in the control flow, with the DSM responsible for properlyhalting normal operation, reporting the fault, and restoring normal operation upon clearing of the fault.
Block diagram detail
Figure 6.1.1: Drive State Machine
Freescale SemiconductorKinetis Motor Suite API Reference Manual
77
Overview
Configuration, inputs, and outputs
Configuration of the DSM block largely consists of definition of faults, as the DSM is itself a configu-ration of the manner in which different operating states interact. Inputs to the DSM block are primarilycommands from other blocks that mandate a shift in operating behavior. For example, the User block maycommand the DSM block to initiate a different motor operating mode (switching from Speed Control toVoltage Control). Outputs of the DSM block are typically commands to switch from block to block andstatus of where the system currently resides.
Code security breakdown
The table below describes the partitioning of DSM block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyDefinition of motor operating states& control type, faults, updatingfunctions
N/A N/A
Execution
Because the DSM block is responsible for managing transitions among blocks with different operatingrequirements, it has certain elements that update in the FAST ISR and certain elements that update inthe SLOW ISR. For example, peak overcurrent fault is evaluated in the FAST ISR but overspeed fault isevaluated in the SLOW ISR.
User customization example
The user may want to add an additional block of proprietary code to motor control operation and woulduse the “glue” logic defined in the DSM block to connect this proprietary code to general motor controloperation. An example of such proprietary code might be torque ripple compensation (typical of compres-sor applications) or load imbalance detection (washing machine applications). Since the DSM owns all ofthe fault handling for KMS if there are additional faults that the user wishes to add, they should be addedinto this block.
Data Structures• struct DSM_faultThresholds_t• union DSM_clrFaults_t• struct DSM_clrFaults_t::DSM_clrFaultsBits_s
Drive state-machine clearable bits structure. More...• union DSM_nonClrFaults_t
78Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
• struct DSM_nonClrFaults_t::DSM_nonClrFaultsBits_sDrive state-machine non-clearable faults bits structure. More...
• struct DSM_internal_t• struct DSM_t• union DSM_clrFaults_u
Drive state-machine clearable faults union. More...• union DSM_nonClrFaults_u
Drive state-machine non-clearable faults union. More...
Macros• #define DSM_PK_CURRENT_FAULT_COUNTER (15U)
Number of successive peak overcurrents before triggering a fault.• #define DSM_RESET_LINE_HOLD_TIME (4U)
Hold time (in us) for the reset line.
Enumerations• enum DRV_control_e {
STARTUP = 0,FOC = 1 }
Enumeration of control options offered.• enum DSM_state_e {
DSM_START = 0,DSM_IDLE,DSM_FAULT,DSM_PWM_DUTY,DSM_VOLTAGE,DSM_CURRENT,DSM_MOTION }
Drive state-machine states.
Functions• DSM_t ∗ DSM_init (void ∗pMem, size_t size)
Initializes DSM module.• void DSM_configFaults (DSM_t ∗pDSM, const DSM_faultThresholds_t ∗const faults)• void DSM_updateSlowTick (DSM_t ∗pDSM, DSM_state_e newState, const FEEDBACK_output←↩
_t ∗const pADC, DRV_control_e controlType, _lq rotorRefSpeed, _lq rotorSpeed_50Hz, boolspeedLoopEnabled, _lq filtStatorFluxSpVecMag, bool faultsDisabled)
• void FAST DSM_updateAtFastTick (DSM_t ∗pDSM, const FEEDBACK_output_t ∗const pADC,bool faultsDisabled)
• void DSM_resetFaults (DSM_t ∗pDSM)Sets the bit to reset faults in the DSM.
• void DSMS_Init (void)Platform Specific Init.
• FAST DSM_clrFaults_t DSMS_GetClearableFaults (const DSM_faultThresholds_t ∗const dsm←↩FaultThresholds)
• FAST DSM_nonClrFaults_t DSMS_GetNonClearableFaults (void)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
79
Data Structure Documentation
Get Platform Specific Non Clearable Fault bits to OR into DSM module.• void DSMS_ClearableFaultsReset (void)
Clear any active faults (Platform Specific bits)• void DSMS_CalculateTemperature (uint16_t adcTemperatureInput)
Calculates the temperature and passes it to the DSM system.• static void DSM_startState (DSM_t ∗pDSM, const FEEDBACK_output_t ∗const pADC)
Processes DSM start state.• static void DSM_idleState (DSM_t ∗pDSM, DSM_state_e newState)
Processes DSM idle state.• static void DSM_runTimeMonitor (DSM_t ∗pDSM, DSM_state_e newState, DRV_control_←↩
e controlType, bool speedLoopEnabled, _lq speedError, bool rotorSyncLoss, bool faultsDisabled)• static void DSM_faultState (DSM_t ∗pDSM)
Processes DSM fault state.• static void DSMS_hwFaultReset (void)
Performs the hardware fault reset.• static void DSMS_holdHwFaultReset (void)
Holds hardware fault reset line.• static void DSMS_releaseHwFaultReset (void)
Releases hardware fault reset line.
Variables• static bool firstStartup = true
Indicates if this is the first time that the drive has started. Used for setting up the over and under voltagethresholds.
• static DRIVER3PH_T msM1Driver3ph3-phase MOSFET driver
6.2 Data Structure Documentation
6.2.1 struct DSM_faultThresholds_t
Data Fields
bool enableFaults global fault enable
_lq minSyncSpeed Minimum rotor speed to enable loss of sync detection { unit: [purpm] }
_sq overCurrent←↩Peak
Peak over current fault threshold { unit: [pu amps] }
_sq overCurrentR←↩MS
RMS over current fault threshold { unit: [pu amps] }
80Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
uint16_t overCurrentR←↩MSCounter
RMS over current fault hysteresis setting { unit: [slow isr ticks] }
_lq overSpeed Over Speed fault threshold { unit: [pu rpm] }
_sq overTemp←↩Inverter
Inverter temperature fault threshold { unit: [deg C] }
_sq overTemp←↩Motor
Motor temperature fault threshold { unit: [deg C] }
_lq overVoltage Over voltage fault threshold { unit: [pu volts] }
_lq pmFluxSync←↩ThreshWb
Stator flux / PM flux threshold to trigger loss of sync { unit: [puwebers] }
uint16_t stallCounter Hysteresis setting for the stall fault { unit: [slow isr ticks] }
_lq stallSpeedError Speed error threshold for stall fault { unit: [pu rpm] }
uint16_t startup←↩VoltageTimer
Startup voltage Timer { unit: [slow isr ticks] }
_lq underVoltage Under voltage fault threshold { unit: [pu volts] }
6.2.2 union DSM_clrFaults_t
Data Fields
uint32_t all DSM clearable faults register
structDSM_clr←↩
FaultsBits_s
bits Drive state-machine clearable faults bits
6.2.3 struct DSM_clrFaults_t::DSM_clrFaultsBits_s
Drive state-machine clearable bits structure.
Data Fields
bitfield_t brkChopper←↩OverCurrent:1
B1.2 DSM brake chopper over-current fault bitfield
Freescale SemiconductorKinetis Motor Suite API Reference Manual
81
Data Structure Documentation
bitfield_t commsFault: 1 B3.1 DSM communications (timeout) fault bitfield
bitfield_t dcBusOver←↩Current: 1
B0.7 DSM DC bus over-curent fault bitfield
bitfield_t dcBusOver←↩Voltage: 1
B1.0 DSM DC bus over-voltage fault bitfield
bitfield_t dcBusUnder←↩Voltage: 1
B1.1 DSM DC bus under-voltage fault bitfield
bitfield_t fastIsr←↩Reentered:1
B3.2 DSM fast ISR reentered
bitfield_t hwFault: 1 B0.0 DSM hardware latched fault (peak over-current or DC busover-voltage) bitfield
bitfield_t invOver←↩Temperature:1
B1.4 DSM inverter over-temperature fault bitfield
bitfield_t motImbPhase←↩A: 1
B2.2 DSM motor phase A imbalance fault bitfield
bitfield_t motImbPhase←↩B: 1
B2.3 DSM motor phase B imbalance fault bitfield
bitfield_t motImbPhase←↩C: 1
B2.4 DSM motor phase C imbalance fault bitfield
bitfield_t motLossSync:1
B2.6 DSM motor stall bitfield - Motor stalled
bitfield_t motOpen←↩PhaseA: 1
B1.7 DSM motor open phase A fault bitfield
bitfield_t motOpen←↩PhaseB: 1
B2.0 BDSM motor open phase B fault bitfield
bitfield_t motOpen←↩PhaseC: 1
B2.1 DSM motor open phase C fault bitfield
bitfield_t motOver←↩Speed: 1
B1.5 DSM motor over-speed fault bitfield
bitfield_t motOver←↩Temperature:1
B1.6 DSM motor over-temperature fault bitfield
82Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
bitfield_t motStall: 1 B2.5 DSM motor stall bitfield - Motor stalled
bitfield_t motStartup←↩Failure: 1
B2.7 DSM motor startup bitfield - Startup failure
bitfield_t pfcOver←↩Current: 1
B1.3 DSM PFC circuit over-current fault bitfield
bitfield_t pkOver←↩CurrentA:1
B0.4 DSM peak (instantaneous) over-current fault on phase A bit-field
bitfield_t pkOver←↩CurrentB:1
B0.5 DSM peak (instantaneous) over-current fault on phase B bit-field
bitfield_t pkOver←↩CurrentC:1
B0.6 DSM peak (instantaneous) over-current fault on phase B bit-field s
bitfield_t preDriverD←↩CBusOver←↩Current:1
B3.5 DSM Pre-Driver Temp Threshold
bitfield_t preDriver←↩LowVoltage←↩Supply:1
B3.4 DSM Pre-Driver Low Voltage Supply
bitfield_t preDriver←↩PhaseError:1
B3.6 DSM Pre-Driver Phase Error
bitfield_t preDriver←↩Temp:1
B3.7 DSM Pre-Driver Temp Threshold
bitfield_t rmsOver←↩CurrentA:1
B0.1 DSM rms (steady-state) over-current fault on phase A bitfield
bitfield_t rmsOver←↩CurrentB:1
B0.2 DSM rms (steady-state) over-current fault on phase B bitfield
bitfield_t rmsOver←↩CurrentC:1
B0.3 DSM rms (steady-state) over-current fault on phase C bitfield
Freescale SemiconductorKinetis Motor Suite API Reference Manual
83
Data Structure Documentation
bitfield_t slowIsr←↩Reentered:1
B3.3 DSM slow ISR reentered
bitfield_t wdReset: 1 B3.0 DSM watchdog reset fault bitfield
6.2.4 union DSM_nonClrFaults_t
Data Fields
uint16_t all DSM non-clearable faults register
structDSM_nonClr←↩
FaultsBits_s
bits Drive state-machine non-clearable faults bits
6.2.5 struct DSM_nonClrFaults_t::DSM_nonClrFaultsBits_s
Drive state-machine non-clearable faults bits structure.
Data Fields
bitfield_t __pad0__: 5 unused bitfields
bitfield_t adcFault: 1 B0.3 DSM ADC offset fault on phase A, B or C bitfield
bitfield_t calibration←↩Fault: 1
B0.2 DSM current sensors calibration fault bitfield
bitfield_t clkFault: 1 B0.7 DSM CPU clock fault bitfield
bitfield_t encoder←↩SensorFault:1
B0.0 DSM encoder sensor fault bitfield
bitfield_t flashFault: 1 B0.5 DSM CPU flash memory fault bitfield
bitfield_t hallSensor←↩Fault: 1
B0.1 DSM Hall sensor fault bitfield
84Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
bitfield_t isrFault: 1 B1.0 DSM ISR fault bitfield
bitfield_t ramFault: 1 B0.4 DSM CPU RAM memory fault bitfield
bitfield_t regFault: 1 B0.6 DSM CPU register fault bitfield
bitfield_t secureMotor←↩Observer←↩RomIdFault:1
B1.0 DSM MotorObserver Secure ROM Incompatible fault bitfield
bitfield_t secureSpin←↩TACRomId←↩Fault: 1
B1.0 DSM SpinTAC Secure ROM Incompatible fault bitfield
6.2.6 struct DSM_internal_t
Data Fields
bool faults←↩Configured
Bool indicating whether faults are configured
uint16_t focTran←↩Counter
Counter indicating how long system has been in FOC region
bool inStartUp←↩Region
Bool indication of motor operating in startup region
uint16_t peakOver←↩Current←↩CounterA
Counter indicating peak overcurrent fault counter for Phase A
uint16_t peakOver←↩Current←↩CounterB
Counter indicating peak overcurrent fault counter for Phase B
uint16_t peakOver←↩Current←↩CounterC
Counter indicating peak overcurrent fault counter for Phase C
Freescale SemiconductorKinetis Motor Suite API Reference Manual
85
Data Structure Documentation
uint16_t rmsOver←↩Current←↩CounterA
Counter indicating RMS current fault condition for Phase A
uint16_t rmsOver←↩Current←↩CounterB
Counter indicating RMS current fault condition for Phase B
uint16_t rmsOver←↩Current←↩CounterC
Counter indicating RMS current fault condition for Phase C
uint16_t stallDetect←↩Counter
Stall detect counter
uint16_t startup←↩VoltageCounter
Startup Voltage counter
uint16_t syncDetect←↩Counter
Sync loss detection counter
6.2.7 struct DSM_t
Data Fields
DSM_clr←↩Faults_t
clearableFaults DSM clearable faults
DSM_fault←↩Thresholds_t
faultThresholds DSM configured fault thresholds
DSM_←↩internal_t
internal DSM internal counters
DSM_nonClr←↩Faults_t
nonClearable←↩Faults
DSM non-clearable faults
bool resetFault DSM reset fault
DSM_state_e state DSM state
6.2.8 union DSM_clrFaults_u
Drive state-machine clearable faults union.
86Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Enumeration Type Documentation
6.2.9 union DSM_nonClrFaults_u
Drive state-machine non-clearable faults union.
6.3 Macro Definition Documentation
6.3.1 #define DSM_PK_CURRENT_FAULT_COUNTER (15U)
Number of successive peak overcurrents before triggering a fault.
Referenced by DSM_updateAtFastTick().
6.3.2 #define DSM_RESET_LINE_HOLD_TIME (4U)
Hold time (in us) for the reset line.
Referenced by DSMS_hwFaultReset().
6.4 Enumeration Type Documentation
6.4.1 enum DRV_control_e
Enumeration of control options offered.
Enumerator
STARTUP Open Loof IF FOCFOC PMSM rotor FOC sensorless speed control
6.4.2 enum DSM_state_e
Drive state-machine states.
Enumerator
DSM_START 0: DSM start stateDSM_IDLE 1: DSM idle stateDSM_FAULT 2: DSM fault stateDSM_PWM_DUTY 3: DSM PWM duty control stateDSM_VOLTAGE 4: DSM voltage control stateDSM_CURRENT 5: DSM current control stateDSM_MOTION 6: DSM motion control state (speed or position control)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
87
Function Documentation
6.5 Function Documentation
6.5.1 void DSM_configFaults ( DSM_t ∗ pDSM, const DSM_faultThresholds_t∗const faults )
References DSM_internal_t::faultsConfigured, DSM_t::faultThresholds, and DSM_t::internal.
6.5.2 static void DSM_faultState ( DSM_t ∗ pDSM ) [static]
Processes DSM fault state.
Parameters
pDSM - pointer to the drive module
Returns
none
References DSM_clrFaults_t::all, DSM_nonClrFaults_t::all, DSM_t::clearableFaults, DSM_IDL←↩E, DSMS_ClearableFaultsReset(), DSM_internal_t::inStartUpRegion, DSM_t::internal, DSM_t::non←↩ClearableFaults, DSM_t::resetFault, and DSM_t::state.
Referenced by DSM_updateSlowTick().
6.5.3 static void DSM_idleState ( DSM_t ∗ pDSM, DSM_state_e newState )[static]
Processes DSM idle state.
Parameters
pDSM - pointer to the drive module
state change command from USER
Returns
none
References DSM_clrFaults_t::all, DSM_nonClrFaults_t::all, DSM_t::clearableFaults, DSM_CURREN←↩T, DSM_FAULT, DSM_MOTION, DSM_PWM_DUTY, DSM_VOLTAGE, DSM_faultThresholds_←↩t::enableFaults, DSM_t::faultThresholds, DSM_internal_t::inStartUpRegion, DSM_t::internal, DSM_t←↩::nonClearableFaults, and DSM_t::state.
Referenced by DSM_updateSlowTick().
88Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
6.5.4 DSM_t ∗ DSM_init ( void ∗ pMem, size_t size )
Initializes DSM module.
Parameters
pMem - pointer to memory where the DSM block is stored
size - size of memory where the DSM block is stored
Returns
handle - interface to access the DSM block
References DSM_nonClrFaults_t::bits, DSM_START, DSMS_Init(), DSM_faultThresholds_t::enable←↩Faults, DSM_t::faultThresholds, GetMotorObserverSecureVersionIsCompatible(), DSM_internal_t←↩::inStartUpRegion, DSM_t::internal, DSM_t::nonClearableFaults, DSM_nonClrFaults_t::DSM_non←↩ClrFaultsBits_s::secureMotorObserverRomIdFault, DSM_nonClrFaults_t::DSM_nonClrFaultsBits_s←↩::secureSpinTACRomIdFault, and ST_getSecureROMIsCompatible().
6.5.5 void DSM_resetFaults ( DSM_t ∗ pDSM )
Sets the bit to reset faults in the DSM.
Parameters
pDSM - pointer to the DSM module
Returns
none
References DSM_clrFaults_t::all, DSM_t::clearableFaults, and DSM_t::resetFault.
Referenced by USER_runFaultState().
6.5.6 static void DSM_runTimeMonitor ( DSM_t ∗ pDSM, DSM_state_e newState,DRV_control_e controlType, bool speedLoopEnabled, _lq speedError, boolrotorSyncLoss, bool faultsDisabled ) [static]
References _LQabsFast, DSM_clrFaults_t::all, DSM_nonClrFaults_t::all, DSM_clrFaults_t::bits, DS←↩M_t::clearableFaults, DSM_FAULT, DSM_faultThresholds_t::enableFaults, DSM_t::faultThresholds,FOC, DSM_internal_t::focTranCounter, DSM_internal_t::inStartUpRegion, DSM_t::internal, DSM←↩_clrFaults_t::DSM_clrFaultsBits_s::motLossSync, DSM_clrFaults_t::DSM_clrFaultsBits_s::motStall,
Freescale SemiconductorKinetis Motor Suite API Reference Manual
89
Function Documentation
DSM_clrFaults_t::DSM_clrFaultsBits_s::motStartupFailure, DSM_t::nonClearableFaults, DSM_fault←↩Thresholds_t::stallCounter, DSM_internal_t::stallDetectCounter, DSM_faultThresholds_t::stallSpeed←↩Error, STARTUP, DSM_t::state, and DSM_internal_t::syncDetectCounter.
Referenced by DSM_updateSlowTick().
6.5.7 static void DSM_startState ( DSM_t ∗ pDSM, const FEEDBACK_output_t∗const pADC ) [static]
Processes DSM start state.
Parameters
pDSM - pointer to the drive module
pADC - pointer to the feedback module
Returns
none
References _LQ, _LQmpy, _LQsat(), DSM_IDLE, DSM_internal_t::faultsConfigured, DSM_t::fault←↩Thresholds, firstStartup, DSM_t::internal, DSM_faultThresholds_t::overVoltage, DSM_internal_t←↩::startupVoltageCounter, DSM_faultThresholds_t::startupVoltageTimer, DSM_t::state, DSM_fault←↩Thresholds_t::underVoltage, and FEEDBACK_output_t::Vdc_200Hz.
Referenced by DSM_updateSlowTick().
6.5.8 void DSM_updateAtFastTick ( DSM_t ∗ pDSM, const FEEDBACK_output_t∗const pADC, bool faultsDisabled )
References _SQabsFast, DSM_clrFaults_t::all, DSM_nonClrFaults_t::all, DSM_clrFaults_t::bits, D←↩SM_t::clearableFaults, DSM_FAULT, DSM_PK_CURRENT_FAULT_COUNTER, DSMS_Get←↩ClearableFaults(), DSMS_GetNonClearableFaults(), DSM_faultThresholds_t::enableFaults, DSM_t←↩::faultThresholds, DSM_t::internal, FEEDBACK_output_t::Isa, FEEDBACK_output_t::Isb, FEED←↩BACK_output_t::Isc, DSM_t::nonClearableFaults, DSM_faultThresholds_t::overCurrentPeak, DSM←↩_internal_t::peakOverCurrentCounterA, DSM_internal_t::peakOverCurrentCounterB, DSM_internal←↩_t::peakOverCurrentCounterC, DSM_clrFaults_t::DSM_clrFaultsBits_s::pkOverCurrentA, DSM_clr←↩Faults_t::DSM_clrFaultsBits_s::pkOverCurrentB, DSM_clrFaults_t::DSM_clrFaultsBits_s::pkOver←↩CurrentC, and DSM_t::state.
90Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
6.5.9 void DSM_updateSlowTick ( DSM_t ∗ pDSM, DSM_state_e newState,const FEEDBACK_output_t ∗const pADC, DRV_control_e controlType,_lq rotorRefSpeed, _lq rotorSpeed_50Hz, bool speedLoopEnabled, _lqfiltStatorFluxSpVecMag, bool faultsDisabled )
References _LQabs(), _LQabsFast, _LQsqrt(), _LQtoSQ, DSM_nonClrFaults_t::DSM_nonClrFaults←↩Bits_s::adcFault, DSM_clrFaults_t::bits, DSM_nonClrFaults_t::bits, DSM_nonClrFaults_t::DSM_non←↩ClrFaultsBits_s::calibrationFault, DSM_t::clearableFaults, DSM_clrFaults_t::DSM_clrFaultsBits_s::dc←↩BusOverVoltage, DSM_clrFaults_t::DSM_clrFaultsBits_s::dcBusUnderVoltage, DSM_CURRENT, D←↩SM_FAULT, DSM_faultState(), DSM_IDLE, DSM_idleState(), DSM_MOTION, DSM_PWM_DUTY,DSM_runTimeMonitor(), DSM_START, DSM_startState(), DSM_VOLTAGE, DSM_t::faultThresholds,FEEDBACK_output_t::gainFault, DSM_t::internal, DSM_faultThresholds_t::minSyncSpeed, DSM_clr←↩Faults_t::DSM_clrFaultsBits_s::motOverSpeed, DSM_t::nonClearableFaults, FEEDBACK_output_t←↩::offsetFault, DSM_faultThresholds_t::overCurrentRMS, DSM_faultThresholds_t::overCurrentRMS←↩Counter, DSM_faultThresholds_t::overSpeed, DSM_faultThresholds_t::overVoltage, FEEDBACK_←↩output_t::rmsIsaSquare, FEEDBACK_output_t::rmsIsbSquare, DSM_clrFaults_t::DSM_clrFaultsBits←↩_s::rmsOverCurrentA, DSM_clrFaults_t::DSM_clrFaultsBits_s::rmsOverCurrentB, DSM_clrFaults_t::←↩DSM_clrFaultsBits_s::rmsOverCurrentC, DSM_internal_t::rmsOverCurrentCounterA, DSM_internal←↩_t::rmsOverCurrentCounterB, DSM_internal_t::rmsOverCurrentCounterC, DSM_t::state, DSM_fault←↩Thresholds_t::underVoltage, and FEEDBACK_output_t::Vdc_200Hz.
6.5.10 DSMS_CalculateTemperature ( uint16_t adcTemperatureInput )
Calculates the temperature and passes it to the DSM system.
Parameters
adc←↩Temperature←↩
Input
Raw input from the ADC Converter
Returns
none
6.5.11 void DSMS_ClearableFaultsReset ( void )
Clear any active faults (Platform Specific bits)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
91
Function Documentation
Returns
none
References DSMS_hwFaultReset(), and msM1Driver3ph.
Referenced by DSM_faultState().
6.5.12 DSM_clrFaults_t DSMS_GetClearableFaults ( const DSM_faultThresholds←↩_t ∗const dsmFaultThresholds )
References DSM_clrFaults_t::all, DSM_clrFaults_t::bits, DSM_clrFaults_t::DSM_clrFaultsBits_s::dc←↩BusOverCurrent, msM1Driver3ph, DSM_clrFaults_t::DSM_clrFaultsBits_s::preDriverDCBusOver←↩Current, DSM_clrFaults_t::DSM_clrFaultsBits_s::preDriverPhaseError, DSM_clrFaults_t::DSM_clr←↩FaultsBits_s::preDriverTemp, and DSM_clrFaults_t::DSM_clrFaultsBits_s::wdReset.
Referenced by DSM_updateAtFastTick().
6.5.13 DSM_nonClrFaults_t DSMS_GetNonClearableFaults ( void )
Get Platform Specific Non Clearable Fault bits to OR into DSM module.
Returns
DSM_nonClrFaults_t (Platform Specific only)
References DSM_nonClrFaults_t::all.
Referenced by DSM_updateAtFastTick().
6.5.14 static void DSMS_holdHwFaultReset ( void ) [static]
Holds hardware fault reset line.
Returns
none
Referenced by DSMS_hwFaultReset().
6.5.15 static void DSMS_hwFaultReset ( void ) [static]
Performs the hardware fault reset.
92Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Variable Documentation
Returns
none
References DLY_delayUS(), DSM_RESET_LINE_HOLD_TIME, DSMS_holdHwFaultReset(), and D←↩SMS_releaseHwFaultReset().
Referenced by DSMS_ClearableFaultsReset().
6.5.16 void DSMS_Init ( void )
Platform Specific Init.
Returns
none
References msM1Driver3ph.
Referenced by DSM_init().
6.5.17 static void DSMS_releaseHwFaultReset ( void ) [static]
Releases hardware fault reset line.
Returns
none
Referenced by DSMS_hwFaultReset().
6.6 Variable Documentation
6.6.1 firstStartup = true [static]
Indicates if this is the first time that the drive has started. Used for setting up the over and under voltagethresholds.
Referenced by DSM_startState().
6.6.2 msM1Driver3ph [static]
3-phase MOSFET driver
Referenced by DSMS_ClearableFaultsReset(), DSMS_GetClearableFaults(), and DSMS_Init().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
93
Variable Documentation
94Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 7Field Oriented Control7.1 OverviewThe "glue logic" layer between all motor control blocks.
Functional description
The Field Oriented Control (FOC) block or DRV block contains all of the motor control blocks. It de-scribes how to connect the motor control algorithm components in order to realize field oriented control.Due to the nature of this block it does not conform to the typical interfaces of the other blocks. It is merelya layer that exists in order to contain other blocks. There are three different versions of this block that con-form to the three control topologies offerd by KMS: Sensorless Velocity, Sensored Velocity, and SensoredPosition.
The common components for the three control topologies are described in this part. The implementationof these functions differs for the three control topologies. See the specific drv.c file for details. In additionto containing the interface layer between all of the motor control algorithm components, the DRV blockalso describes how to setup the complete FOC. It does this via the system.h header file. This file isgenerated by KMS so that it can tailor the reference project to the user motor and application. It contains aconst structure called flashSysParamsHeader. Upon power-up this structure is copied into flashSysParamswhich is then used to configure the FOC. When using KMS, the flashSysParams strucutre will be updatedin order to store the temporary drive configuration. It will only be placed into the reference project whenthe system.h header file is updated. The definition for flashSysParams & flashSysParamsHeader will varydepending on the control topology. See the specific sysparams.h header file for details.
Block diagram detail
The block diagrams for this part are described in the Block Diagram portion of part 1.
Code security breakdown
The connections between the various motor control blocks in KMS are provided as open source.
Open Source Library Execute-onlyFunctions to run fast and slow inter-rupt motor control tasks.
N/A N/A
Freescale SemiconductorKinetis Motor Suite API Reference Manual
95
Overview
Execution
Due to the nature of motor control algorithms, portions of this block need to run at the Fast ISR andportions need to run at the Slow ISR.
User customization example
The user may need to alter the layout of the FOC to suit their end application needs. For example, the usermay wish to remove the Field Weakening block completely if the application does not require it.
Macros• #define FULL_SCALE_VOLTAGE (36.3)
Actual voltage [V] represented by 1.0 scaled voltage [pu V] This should be set to the DC bus voltage whenthe ADC reads 3.3V.
• #define FULL_SCALE_CURRENT (8.0079)Actual current [A] represented by 1.0 scaled current [pu A] This should be set to the motor phase currentwhen the ADC reads 3.3V.
• #define FULL_SCALE_SPEED_RPM (1.2 ∗ 8000.0)Actual speed [RPM] represented by 1.0 scaled speed [pu RPM] Calculation: 1.2 [Scalar] ∗ Motor Maxi-mum Speed.
• #define FULL_SCALE_SPEED_WE (FULL_SCALE_SPEED_RPM ∗ (2 ∗ 3.1415) / 60 ∗ 2)Actual electrical speed [rad/s] represented by 1.0 scaled electrical speed [pu rad/s] Calculation: FUL←↩L_SCALE_SPEED_RPM [Base Speed in RPM] ∗ (2 ∗ 3.1415) / 60 [Unit Conversion: RPM -> rad/s] ∗Motor Pole Pairs.
• #define FULL_SCALE_RESISTANCE (FULL_SCALE_VOLTAGE / FULL_SCALE_CURRE←↩NT)
Actual resistance [Ohms] represented by 1.0 scaled resistance [pu Ohms].• #define FULL_SCALE_INDUCTANCE (FULL_SCALE_VOLTAGE / (FULL_SCALE_CURR←↩
ENT ∗ FULL_SCALE_SPEED_WE))Actual inductance [Henrys] represented by 1.0 scaled inductance [pu Henrys].
• #define FULL_SCALE_FLUX (FULL_SCALE_VOLTAGE / FULL_SCALE_SPEED_WE)Actual flux [Webers] represented by 1.0 scaled flux [pu Webers].
• #define FULL_SCALE_POWER (1.5 ∗ FULL_SCALE_VOLTAGE ∗ FULL_SCALE_CURRE←↩NT)
Actual power [W] represented by 1.0 scaled power [pu W] Calculation: 1.5 [Scalar] ∗ FULL_SCALE_←↩VOLTAGE [Base Voltage in V] ∗ FULL_SCALE_CURRENT [Base Current in A].
• #define FULL_SCALE_TORQUE (FULL_SCALE_POWER / (FULL_SCALE_SPEED_RPM ∗ (2∗ 3.1415) / 60))
Actual power [Nm] represented by 1.0 scaled power [pu Nm] Calculation: FULL_SCALE_POWER [BasePower in W] / (FULL_SCALE_SPEED_RPM [Base Speed in RPM] ∗ (2 ∗ 3.1415) / 60 [Unit Conversion:RPM -> rad/s])
Functions• void DRV_init (const SystemParams_t ∗const flashSysParams)
Initializes DRV module using the provided SystemParams_t structure.
96Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
• void DRV_updateSlowTick (void)Updates DRV module at Slow ISR tick.
• FAST void UpdateAtFastTick (const ADC_results_t ∗const adc_results)Updates DRV module at Fast ISR tick.
• bool DRV_motorStall (void)Checks if the motor is potentially stalling.
• _lq DRV_getDcbBusVoltage (void)Gets the DC bus voltage.
• _lq DRV_getDcbBusUnderVoltageThreshold (void)DC Bus Under Voltage Threshold.
• bool DRV_getIsFaultActive (void)Any clearable or non-clearable fault is active.
• void DRV_forceToIdle (void)Helper function to force control state to IDLE.
Variables• static const SystemParams_t flashSysParamsHeader
Default system parameters loaded at startup.
7.2 Macro Definition Documentation
7.2.1 #define FULL_SCALE_CURRENT (8.0079)
Actual current [A] represented by 1.0 scaled current [pu A] This should be set to the motor phase currentwhen the ADC reads 3.3V.
7.2.2 #define FULL_SCALE_FLUX (FULL_SCALE_VOLTAGE /FULL_SCALE_SPEED_WE)
Actual flux [Webers] represented by 1.0 scaled flux [pu Webers].
7.2.3 #define FULL_SCALE_INDUCTANCE (FULL_SCALE_VOLTAGE /(FULL_SCALE_CURRENT ∗ FULL_SCALE_SPEED_WE))
Actual inductance [Henrys] represented by 1.0 scaled inductance [pu Henrys].
7.2.4 #define FULL_SCALE_POWER (1.5 ∗ FULL_SCALE_VOLTAGE ∗FULL_SCALE_CURRENT)
Actual power [W] represented by 1.0 scaled power [pu W] Calculation: 1.5 [Scalar] ∗ FULL_SCALE_←↩VOLTAGE [Base Voltage in V] ∗ FULL_SCALE_CURRENT [Base Current in A].
Freescale SemiconductorKinetis Motor Suite API Reference Manual
97
Function Documentation
7.2.5 #define FULL_SCALE_RESISTANCE (FULL_SCALE_VOLTAGE /FULL_SCALE_CURRENT)
Actual resistance [Ohms] represented by 1.0 scaled resistance [pu Ohms].
7.2.6 #define FULL_SCALE_SPEED_RPM (1.2 ∗ 8000.0)
Actual speed [RPM] represented by 1.0 scaled speed [pu RPM] Calculation: 1.2 [Scalar] ∗ Motor Maxi-mum Speed.
7.2.7 #define FULL_SCALE_SPEED_WE (FULL_SCALE_SPEED_RPM ∗ (2 ∗3.1415) / 60 ∗ 2)
Actual electrical speed [rad/s] represented by 1.0 scaled electrical speed [pu rad/s] Calculation: FULL←↩_SCALE_SPEED_RPM [Base Speed in RPM] ∗ (2 ∗ 3.1415) / 60 [Unit Conversion: RPM -> rad/s] ∗Motor Pole Pairs.
7.2.8 #define FULL_SCALE_TORQUE (FULL_SCALE_POWER /(FULL_SCALE_SPEED_RPM ∗ (2 ∗ 3.1415) / 60))
Actual power [Nm] represented by 1.0 scaled power [pu Nm] Calculation: FULL_SCALE_POWER [BasePower in W] / (FULL_SCALE_SPEED_RPM [Base Speed in RPM] ∗ (2 ∗ 3.1415) / 60 [Unit Conversion:RPM -> rad/s])
7.2.9 #define FULL_SCALE_VOLTAGE (36.3)
Actual voltage [V] represented by 1.0 scaled voltage [pu V] This should be set to the DC bus voltage whenthe ADC reads 3.3V.
Includes Defines for information purposes only. Values are calculated based on KMS inputs. Do notmodify outside of KMS.
7.3 Function Documentation7.3.1 DRV_forceToIdle ( void )
Helper function to force control state to IDLE.
Returns
none
98Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
7.3.2 DRV_getDcbBusUnderVoltageThreshold ( void )
DC Bus Under Voltage Threshold.
Returns
_lq Under Voltage Threshold Voltage { unit: [pu volts] }
7.3.3 DRV_getDcbBusVoltage ( void )
Gets the DC bus voltage.
Returns
_lq DC Bus Voltage { unit: [pu volts] }
7.3.4 DRV_getIsFaultActive ( void )
Any clearable or non-clearable fault is active.
Returns
bool Fault active { True: Fault Active; False: No Fault Active }
7.3.5 DRV_init ( const SystemParams_t ∗const flashSysParams )
Initializes DRV module using the provided SystemParams_t structure.
Parameters
flashSysParams - Complete collection of FOC configuration parameters
Returns
none
7.3.6 DRV_motorStall ( void )
Checks if the motor is potentially stalling.
Returns
true if stalling, false otherwise
Freescale SemiconductorKinetis Motor Suite API Reference Manual
99
Variable Documentation
7.3.7 DRV_updateSlowTick ( void )
Updates DRV module at Slow ISR tick.
Returns
none
7.3.8 UpdateAtFastTick ( const ADC_results_t ∗const adc_results )
Updates DRV module at Fast ISR tick.
Parameters
adc_results - Pointer to a ADC_results_t containing latest ADC samples.
Returns
none
7.4 Variable Documentation
7.4.1 flashSysParamsHeader [static]
Default system parameters loaded at startup.
Global variables
100Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 8Trajectory - Velocity8.1 OverviewAutomatically generates real-time motion commands based on desired speed, acceleration, and jerk limits.
Functional description
The Trajectory block is a motion profile generator. That is, it defines motion between different commandedspeeds under constraints specified by the user. Given a start speed and an end speed, a curve type, and up-per limits on acceleration and jerk (the time derivative of acceleration), the Trajectory block will calculatethe optimum speed, acceleration, and jerk references. These reference values are then sent to the Speedblock, which is responsible for ensuring that the motor adheres to these desired values.
Note that there is no distinction made between transitions where the speed increases and transitions wherethe speed decreases - that is, there are not distinct acceleration and deceleration limits. This is because eachtransition is considered independently and is constrained by the specified limits on motion; the directionof the transition does not matter.
The available curve types provided by this Trajectory block are described in the following diagram.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
101
Overview
Figure 8.1.1: Available Velocity Curves Types
The key distinction between the available curve types is in the jerk. By smoothing out the jerk, theacceleration and therefore the velocity is also much smoother. This results in less stress on the mechanicalcomponents in end applications.
The Trajectory block is effectively a simplified wrapper block for the core algorithms of SpinTAC™Velocity Move submodule.
102Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Block diagram detail
Figure 8.1.2: Trajectory Velocity
Configuration, inputs, and outputs
Configuration available to the user involves system level parameters.
Inputs to the Trajectory block are simply the motion limits: desired speed, curve type, acceleration limit,and jerk limit.
Primary outputs of the Trajectory block are the aforementioned reference values for speed, acceleration,and jerk, to be passed to the Speed block. Additional information that may be extracted from the Trajectoryblock includes status and error conditions.
Execution
The Trajectory block is executed in the main control flow in the Slow ISR, as speed loop considerationsdo not require faster updating than that.
Code security breakdown
The table below describes the partitioning of Trajectory block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-only
Freescale SemiconductorKinetis Motor Suite API Reference Manual
103
Overview
Abstracted structures for states,curve type, configuration, output;functions for initializing, config-uring, running, resetting; detailedstructures for proprietary code; set& get functions
N/A Implementation of real-time con-straint based curve optimization
User customization example
The user may choose which curve type to use when transitioning speeds. For simple applications, thetrapezoidal curve will require the least amount of calculations of the three available curve types.
Data Structures
• struct TRAJVEL_config_tTRAJVEL config structure. More...
• struct TRAJVEL_output_tTRAJVEL output structure. More...
• struct TRAJVEL_tTRAJVEL module structure. More...
Macros• #define TRAJVEL_PRV_SIZE 50
Enumerations• enum TRAJVEL_CurveType_e {
TRAJVEL_TRAP = 0,TRAJVEL_SCRV,TRAJVEL_STCRV }
Trajectory curve types.• enum TRAJVEL_Status_e {
TRAJVEL_IDLE = 0,TRAJVEL_INIT,TRAJVEL_CONF,TRAJVEL_BUSY,TRAJVEL_HALT }
TRAJVEL state information.
Functions• TRAJVEL_t ∗ TRAJVEL_init (void ∗pMem, size_t size)
Trajectory generator initialization.• void TRAJVEL_config (TRAJVEL_t ∗handle, const TRAJVEL_config_t ∗const config, _lq20
lq20HaltLimitJerk, _lq sampleTime)
104Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
• void TRAJVEL_run (TRAJVEL_t ∗handle, bool enable)Runs the Trajectory (TRAJVEL) module.
• void TRAJVEL_reset (TRAJVEL_t ∗handle, _lq speed)Resets the Trajectory (TRAJVEL) module.
8.2 Data Structure Documentation
8.2.1 struct TRAJVEL_config_t
TRAJVEL config structure.
Data Fields
TRAJVEL_←↩CurveType_e
curve Curve Type { TRAJVEL_TRAP: Trap; TRAJVEL_SCRV: s-←↩Curve; TRAJVEL_STCRV: st-Curve }
_lq limitAcc Acceleration Limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
_lq lq20LimitJerk Jerk Limit { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
_lq startSpeed Velocity start value { unit: [pu rpm], value range: [-1.0, 1.0] }
_lq targetSpeed reference ramp setpoint { unit: [pu rpm], value range: [-1.0, 1.0] }
bool test Profile test bit { false: Not Testing; true: Testing Mode }
8.2.2 struct TRAJVEL_output_t
TRAJVEL output structure.
Data Fields
_lq actualLimitAcc Actual maximum acceleration of the profile { unit: [(pu rpm)/s],value range: (0.0, AccLim] }
uint16_t error Error ID { 0: no error; others: see error code }
_lq lq20Actual←↩LimitJerk
Actual maximum jerk of the profile { unit: [(pu rpm)/s∧2], valuerange: (0.0, JrkLim] }
_lq lq20RefJerk Jerk reference { unit: [(pu rpm)/s∧2] }
uint32_t profileTime_←↩tick
Amount of time profile will take ( unit: [tick], value range: (0,uint32_t max] }
Freescale SemiconductorKinetis Motor Suite API Reference Manual
105
Enumeration Type Documentation
_lq refAcc Acceleration reference { unit: [(pu rpm)/s] }
_lq refSpeed Velocity reference { unit: [pu rpm] }
TRAJVEL_←↩Status_e
status Trajectory generator status { TRAJVEL_IDLE, TRAJVEL_INIT,TRAJVEL_CONF, TRAJVEL_BUSY}
8.2.3 struct TRAJVEL_t
TRAJVEL module structure.
Data Fields
TRAJVEL_←↩config_t
config Trajectory configuration structure
TRAJVEL_←↩output_t
output Trajectory output structure
uint32_t prv[TRAJVE←↩L_PRV_SIZE]
Trajectory private data block
8.3 Macro Definition Documentation
8.3.1 #define TRAJVEL_PRV_SIZE 50
8.4 Enumeration Type Documentation
8.4.1 enum TRAJVEL_CurveType_e
Trajectory curve types.
Enumerator
TRAJVEL_TRAP Trapazoidal curveTRAJVEL_SCRV S-CurveTRAJVEL_STCRV ST-Curve
8.4.2 enum TRAJVEL_Status_e
TRAJVEL state information.
Enumerator
TRAJVEL_IDLE TRAJVEL is in idle state, holding velocity
106Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
TRAJVEL_INIT TRAJVEL is in init state, validating configured parametersTRAJVEL_CONF TRAJVEL is in conf state, determining the curvesTRAJVEL_BUSY TRAJVEL is in busy state, providing the curvesTRAJVEL_HALT Not used in TRAJVEL
8.5 Function Documentation
8.5.1 void TRAJVEL_config ( TRAJVEL_t ∗ handle, const TRAJVEL_config_t∗const config, _lq20 lq20HaltLimitJerk, _lq sampleTime )
8.5.2 TRAJVEL_init ( void ∗ pMem, size_t size )
Trajectory generator initialization.
Parameters
pMem - pointer to memory where the TRAJVEL block is stored
size - size of memory where the TRAJVEL block is stored
Returns
handle - interface to access the TRAJVEL block
8.5.3 TRAJVEL_reset ( TRAJVEL_t ∗ handle, _lq speed )
Resets the Trajectory (TRAJVEL) module.
Parameters
handle - interface to access the TRAJVEL block
speed - speed to initialize the module with
Returns
none
8.5.4 TRAJVEL_run ( TRAJVEL_t ∗ handle, bool enable )
Runs the Trajectory (TRAJVEL) module.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
107
Function Documentation
Parameters
handle - interface to access the TRAJVEL block
enable - run the trajectory module
Returns
none
108Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 9Trajectory - Position9.1 OverviewAutomatically generates real-time motion commands based on desired position step, speed, acceleration,deceleration, and jerk limits.
Functional description
The Trajectory block is a motion profile generator. That is, it defines motion between different commandedpositions under constraints specified by the user. Given a position step, a curve type, and upper limits onspeed, acceleration, deceleration, and jerk (the time derivative of acceleration), the Trajectory block willcalculate the optimum position, speed, acceleration, and jerk references. These reference values are thensent to the Position block, which is responsible for ensuring that the motor adheres to these desired values.
The available curve types provided by this Trajectory block are described in the following diagram.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
109
Overview
Figure 9.1.1: Available Position Curves Types
The key distinction between the available curve types is in the jerk. By smoothing out the jerk, theacceleration, velocity and therefore the position is also much smoother. This results in less stress on themechanical components in end applications.
The Trajectory block is effectively a simplified wrapper block for the core algorithms of SpinTAC™Position Move submodule.
110Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Block diagram detail
Figure 9.1.2: Trajectory Position
Configuration, inputs, and outputs
Configuration available to the user involves system level parameters.
Inputs to the Trajectory block are simply the motion limits: position step, curve type, speed limit, acceler-ation limit, deceleration limit, and jerk limit.
Primary outputs of the Trajectory block are the aforementioned reference values for position, speed, ac-celeration, and jerk, to be passed to the Position block. Additional information that may be extracted fromthe Trajectory block includes status and error conditions.
Execution
The Trajectory block is executed in the main control flow in the Slow ISR, as position loop considerationsdo not require faster updating than that.
Code security breakdown
The table below describes the partitioning of Trajectory block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-only
Freescale SemiconductorKinetis Motor Suite API Reference Manual
111
Overview
Abstracted structures for states,curve type, configuration, output;functions for initializing, config-uring, running, resetting; detailedstructures for proprietary code; set& get functions
N/A Implementation of real-time con-straint based curve optimization
User customization example
The user may choose which curve type to use when transitioning positions. For simple applications, thetrapezoidal curve will require the least amount of calculations of the three available curve types.
Data Structures
• struct TRAJPOS_config_tTRAJPOS config structure. More...
• struct TRAJPOS_output_tTRAJPOS output structure. More...
• struct TRAJPOS_tTRAJPOS module structure. More...
Macros• #define TRAJPOS_PRV_SIZE 108
Enumerations• enum TRAJPOS_ProfileType_e {
TRAJPOS_MOVE_VEL = 0,TRAJPOS_MOVE_POS }
Trajectory profile types.• enum TRAJPOS_CurveType_e {
TRAJPOS_TRAP = 0,TRAJPOS_SCRV,TRAJPOS_STCRV }
Trajectory curve types.• enum TRAJPOS_Status_e {
TRAJPOS_IDLE = 0,TRAJPOS_INIT,TRAJPOS_CONF,TRAJPOS_BUSY,TRAJPOS_HALT }
Trajectory state information.
Functions• TRAJPOS_t ∗ TRAJPOS_init (void ∗pMem, size_t size)
112Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
Trajectory generator initialization.• void TRAJPOS_config (TRAJPOS_t ∗handle, const TRAJPOS_config_t ∗const config, _lq halt←↩
LimitAcc, _lq20 lq20HaltLimitJerk, _lq sampleTime)• void TRAJPOS_run (TRAJPOS_t ∗handle, bool enable)
Runs the Trajectory (TRAJPOS) module.• void TRAJPOS_reset (TRAJPOS_t ∗handle, _lq speed, _lq position)
REsets the Trajectory (TRAJPOS) module.
9.2 Data Structure Documentation
9.2.1 struct TRAJPOS_config_t
TRAJPOS config structure.
Data Fields
TRAJPOS_←↩CurveType_e
curve Curve Type { TRAJPOS_TRAP: Trap; TRAJPOS_SCRV: s-←↩Curve; TRAJPOS_STCRV: st-Curve }
_lq limitAcc Acceleration Limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
_lq limitDec Deceleration Limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
_lq limitVel Velocity Limit { unit: [pu rpm], value range: (0.0, 1.0] }
_lq lq20LimitJerk Jerk Limit { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
_lq mrev_TO_pu Conversion between mechanical revolutions and pu speed { valuerange: }
_lq PosStart_mrev Position start value { unit: [mrev], value range: [-10, 10.0] }
_lq PosStepFrac_←↩mrev
Position step in fractional revolutions { unit: [mrev], value range:(-1.0, 1.0) }
int32_t PosStepInt_←↩mrev
Position step in whole revolutions { unit: [mrev], value range←↩: int32_t max }
TRAJPOS_←↩ProfileType_e
profile Type of profile to generate { TRAJPOS_MOVE_VEL: position-controlled velocity; TRAJPOS_MOVE_POS: position }
_lq startSpeed Velocity start value { unit: [pu rpm], value range: [-1.0, 1.0] }
_lq targetSpeed Velocity setpoint { unit: [pu rpm], value range: [-1.0, 1.0] }
Freescale SemiconductorKinetis Motor Suite API Reference Manual
113
Data Structure Documentation
bool test Profile test bit { false: Not Testing; true: Testing Mode }
9.2.2 struct TRAJPOS_output_t
TRAJPOS output structure.
Data Fields
_lq actualLimitAcc Actual maximum acceleration of the profile { unit: [(pu rpm)/s],value range: (0.0, AccLim] }
_lq actualLimitDec Actual maximum deceleration of the profile { unit: [(pu rpm)/s],value range: (0.0, DecLim] }
_lq actualLimitVel Actual maximum velocity of the profile { unit: [pu rpm], valuerange: (0.0, VelLim] }
uint16_t error Error ID { 0: no error; others: see error code }
_lq lq20Actual←↩LimitJerk
Actual maximum jerk of the profile { unit: [(pu rpm)/s∧2], valuerange: (0.0, JrkLim] }
_lq lq20RefJerk Jerk reference { unit: [(pu rpm)/s∧2] }
uint32_t profileTime_←↩mtick
Amount of time profile will take ( unit: [million ticks], valuerange: (0, uint32_t max] }
uint32_t profileTime_←↩tick
Amount of time profile will take ( unit: [tick], value range: (0,uint32_t max] }
_lq refAcc Acceleration reference { unit: [(pu rpm)/s] }
_lq refPos_mrev Position reference { unit: [mrev] }
int32_t refRollOver←↩Counts
Number of rollovers between position windows (i.e. 10 -> -10,increases count; -10 -> 10 decreases count)
_lq refSpeed Velocity reference { unit: [pu rpm] }
TRAJPOS_←↩Status_e
status Trajectory generator status { TRAJPOS_IDLE, TRAJPOS_INIT,TRAJPOS_CONF, TRAJPOS_BUSY}
9.2.3 struct TRAJPOS_t
TRAJPOS module structure.
114Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Enumeration Type Documentation
Data Fields
TRAJPOS_←↩config_t
config Trajectory configuration structure
TRAJPOS_←↩output_t
output Trajectory output structure
uint32_t prv[TRAJPO←↩S_PRV_SIZE]
Trajectory private data block
9.3 Macro Definition Documentation
9.3.1 #define TRAJPOS_PRV_SIZE 108
9.4 Enumeration Type Documentation
9.4.1 enum TRAJPOS_CurveType_e
Trajectory curve types.
Enumerator
TRAJPOS_TRAP Trapazoidal curveTRAJPOS_SCRV S-CurveTRAJPOS_STCRV ST-Curve
9.4.2 enum TRAJPOS_ProfileType_e
Trajectory profile types.
Enumerator
TRAJPOS_MOVE_VEL velocity-determined position profileTRAJPOS_MOVE_POS position-determined position profile
9.4.3 enum TRAJPOS_Status_e
Trajectory state information.
Enumerator
TRAJPOS_IDLE TRAJPOS is in idle state, holding velocityTRAJPOS_INIT TRAJPOS is in init state, validating configured parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
115
Function Documentation
TRAJPOS_CONF TRAJPOS is in conf state, determining the curvesTRAJPOS_BUSY TRAJPOS is in busy state, providing the curvesTRAJPOS_HALT TRAJPOS is in halt state, generating a profile to halt motion
9.5 Function Documentation
9.5.1 void TRAJPOS_config ( TRAJPOS_t ∗ handle, const TRAJPOS_config_t∗const config, _lq haltLimitAcc, _lq20 lq20HaltLimitJerk, _lq sampleTime )
9.5.2 TRAJPOS_init ( void ∗ pMem, size_t size )
Trajectory generator initialization.
Parameters
pMem - pointer to memory where the TRAJPOS block is stored
size - size of memory where the TRAJPOS block is stored
Returns
handle - interface to access the TRAJPOS block
9.5.3 TRAJPOS_reset ( TRAJPOS_t ∗ handle, _lq speed, _lq position )
REsets the Trajectory (TRAJPOS) module.
Parameters
handle - interface to access the TRAJPOS block
speed - speed to initialize the module
speed - position to initialize the module
Returns
none
9.5.4 TRAJPOS_run ( TRAJPOS_t ∗ handle, bool enable )
Runs the Trajectory (TRAJPOS) module.
116Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
handle - interface to access the TRAJPOS block
enable - run the trajectory module
Returns
none
Freescale SemiconductorKinetis Motor Suite API Reference Manual
117
Function Documentation
118Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 10Speed Control10.1 OverviewGenerates the torque (Iq) reference based on the real-time motion commands (speed and acceleration) andestimated speed feedback.
Functional description
The Speed block is responsible for controlling motor speed using KMS’ advanced velocity controller.This controller, based on an extended state observer, estimates and actively rejects disturbances to desiredoperation, in real-time. It is configured using two pieces of information: system inertia, provided by theInertia block, and bandwidth, the single parameter to be manually adjusted by the user.
The controller is described at a high level by the equation:
Jv(t) = f (v(t),d(t))+u(t)
In this equation, v(t), u(t), and d(t) are system output (velocity), system input (torque), and externaldisturbance respectively. f is an unknown nonlinear function, and J is the system inertia.
In traditional control design, a proportional-integral (PI) controller would be used to control these dy-namics with the proportional gain and integral gains determined experimentally. The KMS advancedcontroller, however, treats the nonlinear term f as a disturbance that can be estimated and rejected. Thisenables high performance in highly dynamic systems with a simpler tuning scheme, as only bandwidthmust be adjusted to properly calibrate the aggressiveness of disturbance rejection.
The Speed block is effectively a simplified wrapper block for the core algorithms of SpinTAC™ VelocityControl submodule.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
119
Overview
Block diagram detail
Figure 10.1.1: Speed
Configuration, inputs, and outputs
The Speed block is primarily configured by system parameters, sample time and motor maximum current,as well as controller tuning parameters, inertia, and bandwidth; inertia is provided by the Inertia block;and bandwidth is entered by the user after empirical assessment.
The inputs to the Speed block are the velocity reference and velocity feedback. Velocity reference isprovided by the Trajectory block, which creates the proper motion profile given start and target speeds.Velocity feedback is provided by the Estimator block.
The main output of the Speed block is the desired value for Q-axis (torque producing) current. Otheroutputs include status indicators for Speed block operation.
Code security breakdown
The table below describes the partitioning of Speed block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyStructures for configuring speedloop controller; set & get functions
N/A Implementation of proprietary con-trol algorithm
Execution
The Speed block runs in the main control flow in the Slow ISR.
120Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
User customization example
While the KMS advanced velocity controller offers high performance with minimal tuning effort, theuser may prefer a traditional proportional-integral controller developed specifically for an application overmultiple development cycles. Such a block, provided that it can take in a speed reference and output atorque reference, could replace the Speed block. For applications that only wish to control the torque ofan application, the Speed block can be removed.
Data Structures• struct SPEED_output_t
SPEED output structure. More...• struct SPEED_config_t
SPEED config structure. More...• struct SPEED_t
SPEED module nested structure. More...
Macros• #define SPEED_PRV_SIZE 40
Enumerations• enum SPEED_status_e {
SPEED_CONTROL_IDLE =0,SPEED_CONTROL_INIT,SPEED_CONTROL_CONF,SPEED_CONTROL_BUSY }
SPEED module status enum.
Functions• SPEED_t ∗ SPEED_init (void ∗pMem, size_t size)
Speed control loop initialization.• void SPEED_config (SPEED_t ∗handle, const SPEED_config_t ∗const config, _lq sampleTime, _sq
maxStatorCurrent, _lq pmFlux)Speed control loop configuration.
• void SPEED_reset (SPEED_t ∗handle)Resets internal states for SPEED block.
• void SPEED_run (SPEED_t ∗handle, bool enable, _lq speedRef, _lq accRef, _lq speedFdb, _sqIdRef)
Speed control loop function (regulates speed)• FAST void SPEED_set (SPEED_t ∗handle, _sq IqFdb, _lq SpeedFdb)
Speed loop set function used to initialize during transition from I-F to FOC.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
121
Data Structure Documentation
10.2 Data Structure Documentation
10.2.1 struct SPEED_output_t
SPEED output structure.
Data Fields
uint16_t errID error id of the speed module
_sq IqRef control output (SQ15) { unit: [pu amps] }
SPEED_←↩status_e
status indicator of the speed module status
_lq24 torqueRef torque reference
10.2.2 struct SPEED_config_t
SPEED config structure.
Data Fields
bool ctlFilterEnable enable low-pass Filter { false: Filter Disabled; true: Filter Enabled}
_lq friction friction coefficient { unit: [(pu amps)/(pu rpm)], value range: pos-itive _lq24 value }
_lq inertia system inertia { unit: [(pu amps)/((pu rpm)/s)], value range: posi-tive _lq24 value }
_lq IqRefComp torque compensation signal { unit: [pu amps], value range: [-1,OutMax], _lq24 format}
_sq IqRefDerate←↩Ratio
torque derating ratio { unit: [-], value range: (0,1), _sq14 format}
_lq IqRefMax control signal upper limit { unit: [pu amps], value range: [-1, 1],_lq24 format}
_lq IqRefMin control signal lower limit { unit: [pu amps], value range: [-1, Out←↩Max], _lq24 format}
122Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
_lq lq20Bw_radps Controller Bandwidth in _LQ20
10.2.3 struct SPEED_t
SPEED module nested structure.
Data Fields
SPEED_←↩config_t
config speed configuration structure
SPEED_←↩output_t
output speed output structure
uint32_t prv[SPEED_←↩PRV_SIZE]
speed private structure
10.3 Macro Definition Documentation
10.3.1 #define SPEED_PRV_SIZE 40
10.4 Enumeration Type Documentation
10.4.1 enum SPEED_status_e
SPEED module status enum.
Enumerator
SPEED_CONTROL_IDLE speed module in idle stateSPEED_CONTROL_INIT speed module in initialization stateSPEED_CONTROL_CONF speed module in configuration stateSPEED_CONTROL_BUSY speed module in busy state
10.5 Function Documentation
10.5.1 SPEED_config ( SPEED_t ∗ handle, const SPEED_config_t ∗const config,_lq sampleTime, _sq maxStatorCurrent, _lq pmFlux )
Speed control loop configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
123
Function Documentation
Parameters
handle - pointer to the SPEED block
config - pointer to SPEED_config block
sampleTime - time between successive current loop calls
maxStator←↩Current
- maximum motor current
pmFlux - measured flux of the motor
Returns
none
10.5.2 SPEED_init ( void ∗ pMem, size_t size )
Speed control loop initialization.
Parameters
pMem - pointer to memory where the SPEED block is stored
size - size of memory where the SPEED block is stored
Returns
handle - interface to access the SPEED block
10.5.3 void SPEED_reset ( SPEED_t ∗ handle )
Resets internal states for SPEED block.
Parameters
handle - pointer to the SPEED block
Returns
none
124Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
10.5.4 SPEED_run ( SPEED_t ∗ handle, bool enable, _lq speedRef, _lq accRef,_lq speedFdb, _sq IdRef )
Speed control loop function (regulates speed)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
125
Function Documentation
Parameters
handle - pointer to the SPEED block
enable - enables the speed loop operation
speedRef - speed reference to the system
accRef - acceleration reference to the system
IdRef - Id current reference
Returns
none
10.5.5 SPEED_set ( SPEED_t ∗ handle, _sq IqFdb, _lq SpeedFdb )
Speed loop set function used to initialize during transition from I-F to FOC.
Parameters
handle - pointer to the SPEED block
IqFdb - Feedback Iq Current
SpeedFdb - Speed Feedback
Returns
none
126Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 11Position Control11.1 OverviewGenerates the torque (Iq) reference based on the real-time motion commands (position, speed, and accel-eration) and position feedback.
Functional description
The Position block is responsible for controlling motor position using KMS’ advanced position controller.This controller, based on an extended state observer, estimates and actively rejects disturbances to desiredoperation, in real-time. It is configured using two pieces of information: system inertia, provided by theInertia block, and bandwidth, the single parameter to be manually adjusted by the user. The Position blockencompasses both position control and velocity control and internal contains 2 controllers.
A single instance of the controller is described at a high level by the equation:
Jv(t) = f (v(t),d(t))+u(t)
In this equation, v(t), u(t), and d(t) are system output (velocity), system input (torque), and externaldisturbance respectively. f is an unknown nonlinear function, and J is the system inertia.
In traditional control design, a proportional-integral (PI) controller would be used to control these dy-namics with the proportional gain and integral gains determined experimentally. The KMS advancedcontroller, however, treats the nonlinear term f as a disturbance that can be estimated and rejected. Thisenables high performance in highly dynamic systems with a simpler tuning scheme, as only bandwidthmust be adjusted to properly calibrate the aggressiveness of disturbance rejection.
The Position block is effectively a simplified wrapper block for the core algorithms of SpinTAC™ PositionControl submodule.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
127
Overview
Block diagram detail
Figure 11.1.1: Position
Configuration, inputs, and outputs
The Position block is primarily configured by system parameters, sample time and motor maximum cur-rent, as well as controller tuning parameters, inertia, and bandwidth; inertia is provided by the Inertiablock; and bandwidth is entered by the user after empirical assessment.
The inputs to the Position block are the position reference and position feedback. Position reference isprovided by the Trajectory block, which creates the proper motion profile given a position step. Positionfeedback is provided by the Encoder block.
The main output of the Position block is the desired value for Q-axis (torque producing) current. Otheroutputs include status indicators for Position block operation.
Code security breakdown
The table below describes the partitioning of Position block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-onlyStructures for configuring position& speed loop controllers; set & getfunctions
N/A Implementation of proprietary con-trol algorithm
Execution
The Position block runs in the main control flow in the Slow ISR.
128Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
User customization example
While the KMS advanced position controller offers high performance with minimal tuning effort, theuser may prefer a traditional proportional-integral controller developed specifically for an application overmultiple development cycles. Such a block, provided that it can take in a position reference and output atorque reference, could replace the Position block. For applications that only wish to control the torque ofan application, the Position block can be removed.
Data Structures• struct POSITION_output_t
POSITION output structure. More...• struct POSITION_config_t
POSITION config structure. More...• struct POSITION_t
POSITION module nested structure. More...
Macros• #define POSITION_PRV_SIZE 66
Enumerations• enum POSITION_status_e {
POSITION_CONTROL_IDLE =0,POSITION_CONTROL_INIT,POSITION_CONTROL_CONF,POSITION_CONTROL_BUSY }
POSITION module status enum.
Functions• POSITION_t ∗ POSITION_init (void ∗pMem, size_t size)
Position control loop initialization.• void POSITION_config (POSITION_t ∗handle, const POSITION_config_t ∗const config, _lq
sampleTime, _sq maxStatorCurrent, _lq pmFlux)Position control loop configuration.
• void POSITION_reset (POSITION_t ∗handle)Resets internal states for POSITION block.
• void POSITION_run (POSITION_t ∗handle, bool enable, _lq posRef_mrev, _lq speedRef, _lq acc←↩Ref, _lq posFdb_mrev, _sq IdRef)
11.2 Data Structure Documentation
11.2.1 struct POSITION_output_t
POSITION output structure.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
129
Data Structure Documentation
Data Fields
uint16_t errID error id of the position module
_sq IqRef control output (SQ15) { units: [pu amps] }
_lq24 posErr_mrev instantaneous position error { unit: [MRev] }
POSITION_←↩status_e
status indicator of the position module status
_lq24 torqueRef torque reference
11.2.2 struct POSITION_config_t
POSITION config structure.
Data Fields
bool ctlFilterEnable enable low-pass Filter { false: Filter Disabled; true: Filter Enabled}
_lq friction friction coefficient { unit: [(pu amps)/(pu rpm)], value range: pos-itive _lq24 value}
_lq inertia system inertia { unit: [(pu amps)/((pu rpm)/s)], value range: posi-tive _lq24 value}
_lq IqRefComp torque compensation signal { unit: [pu amps], value range: [-1,OutMax], _lq24 format}
_sq IqRefDerate←↩Ratio
torque derating ratio { unit: [-], value range: (0,1), _sq14 format}
_lq IqRefMax control signal upper limit { unit: [pu amps], value range: [-1, 1],_lq24 format}
_lq IqRefMin control signal lower limit { unit: [pu amps], value range: [-1, Out←↩Max], _lq24 format}
_lq lq20Bw_radps Controller Bandwidth in _LQ20
_lq maximum←↩Speed
maximum speed of the motor { unit: [pu rpm], value range: [-1,1],_lq24 format}
130Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
_lq mrev_TO_pu Ratio between mechanical revolutions and scaled position units
11.2.3 struct POSITION_t
POSITION module nested structure.
Data Fields
POSITION_←↩config_t
config position configuration structure
POSITION_←↩output_t
output position output structure
uint32_t prv[POSITIO←↩N_PRV_SIZE]
position private structure
11.3 Macro Definition Documentation
11.3.1 #define POSITION_PRV_SIZE 66
11.4 Enumeration Type Documentation
11.4.1 enum POSITION_status_e
POSITION module status enum.
Enumerator
POSITION_CONTROL_IDLE position module in idle statePOSITION_CONTROL_INIT position module in initialization statePOSITION_CONTROL_CONF position module in configuration statePOSITION_CONTROL_BUSY position module in busy state
11.5 Function Documentation
11.5.1 POSITION_config ( POSITION_t ∗ handle, const POSITION_config_t∗const config, _lq sampleTime, _sq maxStatorCurrent, _lq pmFlux )
Position control loop configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
131
Function Documentation
Parameters
handle - pointer to the POSITION block
config - pointer to POSITION_config block
sampleTime - time between successive position loop calls
maxStator←↩Current
- maximum motor current
pmFlux - measured flux of the motor
Returns
none
11.5.2 POSITION_init ( void ∗ pMem, size_t size )
Position control loop initialization.
Parameters
pMem - pointer to memory where the POSITION block is stored
size - size of memory where the POSITION block is stored
Returns
handle - interface to access the POSITION block
11.5.3 void POSITION_reset ( POSITION_t ∗ handle )
Resets internal states for POSITION block.
Parameters
handle - pointer to the POSITION block
Returns
none
11.5.4 void POSITION_run ( POSITION_t ∗ handle, bool enable, _lq posRef_mrev,_lq speedRef, _lq accRef, _lq posFdb_mrev, _sq IdRef )
132Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 12Field Weakening12.1 OverviewOutputs D-phase current reference based on controlling modulation command to align with maximummodulation.
Functional description
Field Weakening allows a motor to operate above its rated speed at a cost of torque. This is achieved byapplying a negative D-axis current, which will serve to reduce the flux of the motor allowing operation athigher speeds than the normal back-emf would allow.
KMS applies field weakening when the modulation index exceeds the configured maximum modulation.The default for this value is the linear region limit of 0.9069. A typical proportional-integral controller isused to control the D-axis reference current based on the error between the configured maximum modu-lation and the actual modulation. The output maximum for this controller is forced to 0 so that a positiveD-axis current will not be applied.
By default the FW block is enabled, but it can be dynamically enabled and disabled.
Block diagram detail
Figure 12.1.1: Field Weakening
Configuration, inputs, and outputs
The Field Weakening block is configured primarily by defining the output minimum of the block. Thisinforms the system as to the minimum amount (or maximum negative amount) of current that can be
Freescale SemiconductorKinetis Motor Suite API Reference Manual
133
Overview
applied for field weakening.
Inputs to the block include target speed and the signal of applied stator modulation, which is an output ofthe Estimator block.
The key output is a desired D-axis current value, which is passed to the Current block.
Code security breakdown
The table below describes the partitioning of Field Weakening block code among open source, library, andprotected execute-only.
Open Source Library Execute-onlyFunctions for initializing, configur-ing, running field weakening
Implementation of relevant func-tions
N/A
Execution
The Field Weakening block operates in the Slow ISR since it helps regulate the motor speed, it is governedby the same mechanical dynamics as the Speed block.
User customization example
Achieving operation well above rated speed is a particular challenge of certain applications like washingmachines. The user may have proprietary algorithms developed over time with his/her specific application,and in this case may prefer to replace the Field Weakening block.
Data Structures• struct FW_output_t• struct FW_config_t• struct FW_t
Macros• #define FW_PRV_SIZE 20
Functions• FW_t ∗ FW_init (void ∗pMem, size_t size)
Field Weakening initialization.• void FW_config (FW_t ∗handle, const FW_config_t ∗const config, _lq sampleTime, _lq lq16fltId←↩
RefCutoffFreqHz)• void FW_resetController (FW_t ∗handle)
Resets the FW controller.
134Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
• void FW_run (FW_t ∗handle, bool enable, _lq statorRefVoltageMagnitude, _lq rotorTrajSpeed, _lqrotorRefSpeed)
12.2 Data Structure Documentation
12.2.1 struct FW_output_t
Data Fields
_sq IdRef Id reference output from the module (SQ15) { unit: [pu amps] }
12.2.2 struct FW_config_t
Data Fields
_lq max←↩Modulation
Reference modulation for Field Weakening controller { unit←↩: [modulation percent] }
PID_pi←↩Param32_t
pi Field Weakening PI regulator parameters
_lq ratedSpeed Motor Rated speed { unit: [pu rpm] }
12.2.3 struct FW_t
Data Fields
FW_config_t config Field Weakening configuration structure
FW_output_t output Field Weakening output structure
uint32_t prv[FW_PR←↩V_SIZE]
Field Weakening private data block
12.3 Macro Definition Documentation
12.3.1 #define FW_PRV_SIZE 20
Freescale SemiconductorKinetis Motor Suite API Reference Manual
135
Function Documentation
12.4 Function Documentation
12.4.1 void FW_config ( FW_t ∗ handle, const FW_config_t ∗const config, _lqsampleTime, _lq lq16fltIdRefCutoffFreqHz )
12.4.2 FW_init ( void ∗ pMem, size_t size )
Field Weakening initialization.
Parameters
pMem - pointer to memory where the FW block is stored
size - size of memory where the FW block is stored
Returns
handle - interface to access the FW block
12.4.3 FW_resetController ( FW_t ∗ handle )
Resets the FW controller.
Parameters
handle - pointer to the FW block
Returns
none
12.4.4 void FW_run ( FW_t ∗ handle, bool enable, _lq statorRefVoltageMagnitude,_lq rotorTrajSpeed, _lq rotorRefSpeed )
136Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 13Feedback13.1 OverviewGenerates the three phase currents and DC bus voltage from the ADC hardware and internal scaling,calibration and offset.
Functional description
The Feedback block is responsible for processing the samples from the hardware analog-to-digital convert-ers (ADC) to obtain information about the state of motor and inverter operation. It is also responsible forfiltering this information and thereby passing it to the system in a usable manner. This involves checkingand configuring calibration gains, offsets, and fault status.
The most critical pieces of information are the three phase currents that are transformed to provide theactual values that are compared with desired values in the Current block.
When the SVPWM block indicates that it is running in the overmodulation region, the FEEDBACK blockwill begin to implement current reconstruction, where it will choose which phase current sample to ignorebased on the SVPWM sector.
Block diagram detail
Figure 13.1.1: Feedback
Configuration, inputs, and outputs
There is no configuration required for the Feedback block.
The inputs to the Feedback block are the ADC samples.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
137
Overview
The outputs are the processed feedback signals for phase current and bus voltage.
Code security breakdown
The table below describes the partitioning of Feedback block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-onlyDefinition of feedback states, ini-tialization, calibration, configura-tion, implementation of calibration,initialization, configuration, sam-pling, filtering
N/A N/A
Execution
The Feedback block runs in the Fast ISR, as accuracy in sampled current values is critical for motorcontrol.
User customization example
The user may want to leverage additional signals from the hardware for his/her application. For instance,Freescale reference hardware does not typically come with a thermocouple, but on custom hardware, ADCchannels can be sampled and combined with the thermocouple to provide temperature sensing capabilities.Motor and inverter temperature can then be used as any other signals in the system. At a minimum onlytwo phase currents are required to be sampled. In this reference design all three phase currents are sampledin order to provide the maximum performance. This block would need to be modified to reconstruct thenon-sampled current.
Modules• Analog to Digital Converter Interface
The Analog to Digital Converter (ADC) Interface describes how the ADC is configured and used.
Data Structures• struct FEEDBACK_internal_t
FEEDBACK internal module structure. More...• struct FEEDBACK_calib_t
FEEDBACK calibration module structure. More...• struct FEEDBACK_t
FEEDBACK module nested structure. More...• struct ADC_results_t
138Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
ADC results structure to hold raw values after ADC conversion. More...• struct FEEDBACK_gains_t
FEEDBACK calibration gains structure. More...• struct FEEDBACK_output_t
FEEDBACK output structure. More...
Enumerations• enum FEEDBACK_State_e {
FEEDBACK_CALIB = 0,FEEDBACK_RUN,FEEDBACK_FAULT }
States of the FEEDBACK block.
Functions• void DLY_delayUS (uint16_t delay)
Delays execution by x microseconds.• FEEDBACK_t ∗ FEEDBACK_init (void ∗pMem, size_t size)
Initializes FEEDBACK module.• void FEEDBACK_config (FEEDBACK_t ∗handle, const FEEDBACK_gains_t ∗const gains, _lq
focSampleTime, _lq lq16FltVdc1Hz, _lq lq16FltVdc200Hz, _lq lq16FltVdc1kHz, _lq lq16FltIsrms)• FAST void FEEDBACK_run (FEEDBACK_t ∗handle, SVPWM_state_e svpwmState, SVPWM←↩
_sector_e svpwmSector, const ADC_results_t ∗const adcResults)
13.2 Data Structure Documentation
13.2.1 struct FEEDBACK_internal_t
FEEDBACK internal module structure.
Data Fields
bool halfPWM←↩Decrementer
FLT_butter←↩AccT16bit_t
rmsIsa_halfP←↩WM
RMS Phase a current filter initialization, half the fastloop sampletime
FLT_butter←↩AccT16bit_t
rmsIsb_halfP←↩WM
RMS Phase b current filter initialization, half the fastloop sampletime
FLT_butter←↩AccT16bit_t
rmsIsc_halfP←↩WM
RMS Phase c current filter initialization, half the fastloop sampletime
Freescale SemiconductorKinetis Motor Suite API Reference Manual
139
Data Structure Documentation
FLT_butter←↩AccT16bit_t
Vdc_1Hz VDC filter at 1Hz initialization
FLT_butter←↩AccT16bit_t
Vdc_1kHz VDC filter at 1kHz initialization
FLT_butter←↩AccT16bit_t
Vdc_200Hz VDC filter at 1Hz initialization
13.2.2 struct FEEDBACK_calib_t
FEEDBACK calibration module structure.
Data Fields
FEEDBACK←↩_gains_t
gains calibration gains
uint16_t offsetIa phase A calibration offset
uint16_t offsetIb phase B calibration offset
uint16_t offsetIc phase C calibration offset
_sq offsetVdc DC bus voltage calibration offset
13.2.3 struct FEEDBACK_t
FEEDBACK module nested structure.
Data Fields
FEEDBACK←↩_calib_t
calib calibration structure
FEEDBACK←↩_internal_t
internal internal structure
FEEDBACK←↩_output_t
output output structure
140Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
FEEDBACK←↩_State_e
state state enum
13.2.4 struct ADC_results_t
ADC results structure to hold raw values after ADC conversion.
Data Fields
uint16_t adc0_a Raw ADC output of ADC0 A measurement [0 to 4095]
uint16_t adc0_b Raw ADC output of ADC0 B measurement [0 to 4095]
uint16_t adc1_a Raw ADC output of ADC1 A measurement [0 to 4095]
uint16_t adc1_b Raw ADC output of ADC1 B measurement [0 to 4095]
13.2.5 struct FEEDBACK_gains_t
FEEDBACK calibration gains structure.
Data Fields
_sq kIa phase A calibration gain (SQ)
_sq kIb phase B calibration gain (SQ)
_sq kIc phase C calibration gain (SQ)
_sq kVdc DC bus voltage calibration gain (SQ)
13.2.6 struct FEEDBACK_output_t
FEEDBACK output structure.
Data Fields
bool gainFault Indicates if a gain fault has occurred
_lq invVdc_1kHz Inverse DC bus voltage 1kHz filter { unit: [pu volts] }
Freescale SemiconductorKinetis Motor Suite API Reference Manual
141
Function Documentation
_sq Isa phase A current { unit: [pu amps] }
_sq Isb phase B current { unit: [pu amps] }
_sq Isc phase C current { unit: [pu amps] }
bool offsetFault Indicates if an offset fault has occurred
_lq rmsIsaSquare RMS current on phase A squared
_lq rmsIsbSquare RMS current on phase B squared
_lq rmsIscSquare RMS current on phase C squared
_lq Vdc DC bus voltage unfiltered { unit: [pu volts] }
_lq Vdc_1Hz DC bus voltage 1Hz filter { unit: [pu volts] }
_lq Vdc_1kHz DC bus voltage 1kHz filter { unit: [pu volts] }
_lq Vdc_200Hz DC bus voltage 200Hz filter { unit: [pu volts] }
13.3 Enumeration Type Documentation
13.3.1 enum FEEDBACK_State_e
States of the FEEDBACK block.
Enumerator
FEEDBACK_CALIB Do feedback calibrationFEEDBACK_RUN run feedback collectionFEEDBACK_FAULT faulted feedback calibration
13.4 Function Documentation
13.4.1 void DLY_delayUS ( uint16_t delay )
Delays execution by x microseconds.
Parameters
delay - delay in microseconds
Returns
none
Referenced by DSMS_hwFaultReset(), and FEEDBACK_init().
142Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
13.4.2 void FEEDBACK_config ( FEEDBACK_t ∗ handle, constFEEDBACK_gains_t ∗const gains, _lq focSampleTime, _lq lq16FltVdc1Hz,_lq lq16FltVdc200Hz, _lq lq16FltVdc1kHz, _lq lq16FltIsrms )
References _LQtoSQ, FEEDBACK_t::calib, FLT_butterAccT16bit_t::coeff, FLT_coeff_Tustin(), FEE←↩DBACK_calib_t::gains, FEEDBACK_t::internal, FEEDBACK_internal_t::rmsIsa_halfPWM, FEEDB←↩ACK_internal_t::rmsIsb_halfPWM, FEEDBACK_internal_t::rmsIsc_halfPWM, FEEDBACK_internal←↩_t::Vdc_1Hz, FEEDBACK_internal_t::Vdc_1kHz, and FEEDBACK_internal_t::Vdc_200Hz.
13.4.3 FEEDBACK_init ( void ∗ pMem, size_t size )
Initializes FEEDBACK module.
Parameters
pMem - pointer to memory where the FEEDBACK block is stored
size - size of memory where the FEEDBACK block is stored
Returns
handle - interface to access the FEEDBACK block
References ADCS_enableInt(), ADCS_init(), DLY_delayUS(), FEEDBACK_CALIB, and FEEDBAC←↩K_t::state.
13.4.4 FAST void FEEDBACK_run ( FEEDBACK_t ∗ handle, SVPWM_state_esvpwmState, SVPWM_sector_e svpwmSector, const ADC_results_t ∗constadcResults )
References _LQ, _LQdiv, _SQmpySQX, _SQtoLQ, ADC_results_t::adc0_a, ADC_results_t::adc0_b, A←↩DC_results_t::adc1_a, ADC_results_t::adc1_b, FEEDBACK_t::calib, FEEDBACK_CALIB, FEEDBA←↩CK_RUN, FLT_lpf1stT_16bit(), FEEDBACK_calib_t::gains, GLOBAL_SQ, FEEDBACK_internal_t←↩::halfPWMDecrementer, FEEDBACK_t::internal, FEEDBACK_output_t::invVdc_1kHz, FEEDBACK←↩_output_t::Isa, FEEDBACK_output_t::Isb, FEEDBACK_output_t::Isc, FEEDBACK_gains_t::kIa, FE←↩EDBACK_gains_t::kIb, FEEDBACK_gains_t::kIc, FEEDBACK_gains_t::kVdc, FEEDBACK_calib_←↩t::offsetIa, FEEDBACK_calib_t::offsetIb, FEEDBACK_calib_t::offsetIc, FEEDBACK_calib_t::offset←↩Vdc, FEEDBACK_t::output, FEEDBACK_internal_t::rmsIsa_halfPWM, FEEDBACK_output_t::rms←↩IsaSquare, FEEDBACK_internal_t::rmsIsb_halfPWM, FEEDBACK_output_t::rmsIsbSquare, FEEDB←↩ACK_internal_t::rmsIsc_halfPWM, FEEDBACK_output_t::rmsIscSquare, FEEDBACK_t::state, SVP←↩WM_NORM, SVPWM_SECT1, SVPWM_SECT2, SVPWM_SECT3, SVPWM_SECT4, SVPWM_S←↩ECT5, SVPWM_SECT6, FEEDBACK_output_t::Vdc, FEEDBACK_internal_t::Vdc_1Hz, FEEDBAC←↩K_output_t::Vdc_1Hz, FEEDBACK_internal_t::Vdc_1kHz, FEEDBACK_output_t::Vdc_1kHz, FEED←↩BACK_internal_t::Vdc_200Hz, and FEEDBACK_output_t::Vdc_200Hz.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
143
Analog to Digital Converter Interface
13.5 Analog to Digital Converter Interface
13.5.1 Overview
The Analog to Digital Converter (ADC) Interface describes how the ADC is configured and used.
Macros
• #define HW_ADC0 (0)Instance number of ADC 0.
• #define HW_ADC1 (1)Instance number of ADC 1.
• #define HW_PDB0 (0)Instance number of PDB 0.
• #define ADC0_SAMPLEA_CHANNEL (kAdc16Chn8)Channel to sample for motor control on ADC 0 Sample A Phase A Current.
• #define ADC0_SAMPLEB_CHANNEL (kAdc16Chn13)Channel to sample for motor control on ADC 0 Sample B DC Bus Voltage.
• #define ADC1_SAMPLEA_CHANNEL (kAdc16Chn0)Channel to sample for motor control on ADC 1 Sample A Phase B Current.
• #define ADC1_SAMPLEB_CHANNEL (kAdc16Chn3)Channel to sample for motor control on ADC 1 Sample B Phase C Current.
Functions
• void ADCS_init (void)Initializes ADC module.
• void ADCS_enableInt (void)Enables ADC conversion complete ISR.
• void ADCS_disableInt (void)Disables ADC conversion complete ISR.
• FAST void ADCS_readRawADC (ADC_results_t ∗const raw_adc)Reads raw ADC samples for result record.
• void ADCS_getUserSamples (uint16_t adc0Channel, uint16_t adc1Channel, uint16_t adc0HW←↩
Mux, uint16_t adc1HWMux, uint16_t ∗adc0Sample, uint16_t ∗adc1Sample)Configures the ADC to software trigger samples, blocks on conversion, returns results.
13.5.2 Macro Definition Documentation
13.5.2.1 #define ADC0_SAMPLEA_CHANNEL (kAdc16Chn8)
Channel to sample for motor control on ADC 0 Sample A Phase A Current.
Referenced by ADCS_getUserSamples(), and ADCS_init().
144Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Analog to Digital Converter Interface
13.5.2.2 #define ADC0_SAMPLEB_CHANNEL (kAdc16Chn13)
Channel to sample for motor control on ADC 0 Sample B DC Bus Voltage.
Referenced by ADCS_init().
13.5.2.3 #define ADC1_SAMPLEA_CHANNEL (kAdc16Chn0)
Channel to sample for motor control on ADC 1 Sample A Phase B Current.
Referenced by ADCS_getUserSamples(), and ADCS_init().
13.5.2.4 #define ADC1_SAMPLEB_CHANNEL (kAdc16Chn3)
Channel to sample for motor control on ADC 1 Sample B Phase C Current.
Referenced by ADCS_disableInt(), ADCS_enableInt(), ADCS_getUserSamples(), and ADCS_init().
13.5.2.5 #define HW_ADC0 (0)
Instance number of ADC 0.
Referenced by ADCS_init().
13.5.2.6 #define HW_ADC1 (1)
Instance number of ADC 1.
Referenced by ADCS_disableInt(), ADCS_enableInt(), and ADCS_init().
13.5.2.7 #define HW_PDB0 (0)
Instance number of PDB 0.
Referenced by ADCS_init().
13.5.3 Function Documentation
13.5.3.1 void ADCS_disableInt ( void )
Disables ADC conversion complete ISR.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
145
Analog to Digital Converter Interface
Returns
none
References ADC1_SAMPLEB_CHANNEL, and HW_ADC1.
13.5.3.2 void ADCS_enableInt ( void )
Enables ADC conversion complete ISR.
Returns
none
References ADC1_SAMPLEB_CHANNEL, and HW_ADC1.
Referenced by FEEDBACK_init().
13.5.3.3 void ADCS_getUserSamples ( uint16_t adc0Channel, uint16_t adc1Channel,uint16_t adc0HWMux, uint16_t adc1HWMux, uint16_t ∗ adc0Sample, uint16_t ∗adc1Sample )
Configures the ADC to software trigger samples, blocks on conversion, returns results.
Parameters
adc0Channel - Channel to sample on ADC0
adc1Channel - Channel to sample on ADC1
adc0HWMux - Channel to sample on ADC0
adc1HWMux - Channel to sample on ADC1
adc0Sample - ADC0 results (out)
adc1Sample - ADC1 results (out)
References ADC0_SAMPLEA_CHANNEL, ADC1_SAMPLEA_CHANNEL, and ADC1_SAMPLEB←↩_CHANNEL.
13.5.3.4 void ADCS_init ( void )
Initializes ADC module.
146Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Analog to Digital Converter Interface
Returns
none
References ADC0_SAMPLEA_CHANNEL, ADC0_SAMPLEB_CHANNEL, ADC1_SAMPLEA_CH←↩ANNEL, ADC1_SAMPLEB_CHANNEL, HW_ADC0, HW_ADC1, and HW_PDB0.
Referenced by FEEDBACK_init().
13.5.3.5 void ADCS_readRawADC ( ADC_results_t ∗const raw_adc )
Reads raw ADC samples for result record.
Parameters
raw_adc - pointer to the ADC_results data structure
References ADC_results_t::adc0_a, ADC_results_t::adc0_b, ADC_results_t::adc1_a, and ADC_results←↩_t::adc1_b.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
147
Analog to Digital Converter Interface
148Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 14Clarke Transform14.1 OverviewConverts three phase current feedback signals to two phase representation.
Functional description
Field oriented control of motors requires transformation from three vectors to two perpendicular vectorsin a stationary reference frame to two perpendicular vectors in a rotating reference frame, then the reverseprocess. The Clarke Transform block effects the transition between three vectors in the stationary frame(A-B-C frame) to two vectors in the stationary frame (Alpha-Beta frame).
Figure 14.1.1: Effect of Clarke Transform
This transformation is required in the feedback loop: current is sensed along the motor’s three phases inthe Feedback block, then these three phase current values are mathematically transformed into a set of twocurrent vectors.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
149
Overview
Block diagram detail
Figure 14.1.2: Clarke Transform
Configuration, inputs, and outputs
No configuration of the Clarke Transform block is required. The inputs are the sampled motor phasecurrent values as output by the Feedback block. These allow the Clarke Transform block to produce twocurrent vectors in a stationary reference frame to pass to the Park Transform block.
Code security breakdown
The table below describes the partitioning of Clarke block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyInitialization and function for run-ning transform as well as output
Implementation of transform N/A
Execution
The Clarke Transform is run in the Fast ISR because the current sensing happening in the Feedback blockoccurs rapidly and these dynamics must be accounted for rapidly in motor control operation.
150Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
User customization example
While the Clarke Transform is required for field oriented control, the user may wish to utilize differ-ent mathematical method for performing the transform. The underpinnings of this block - the code fortransformations - may be adapted for this purpose.
Data Structures• struct CLARKE_output_t• struct CLARKE_t
Functions• CLARKE_t ∗ CLARKE_init (void ∗pMem, size_t size)
Clarke transform initialization.• FAST void CLARKE_run (CLARKE_t ∗handle, const FEEDBACK_output_t ∗const input)
14.2 Data Structure Documentation
14.2.1 struct CLARKE_output_t
Data Fields
TRF_s←↩Vector16_t
vector 16 bit stationary vectors
14.2.2 struct CLARKE_t
Data Fields
CLARKE_←↩output_t
output Alpha-Beta stationary vectors
14.3 Function Documentation
14.3.1 CLARKE_init ( void ∗ pMem, size_t size )
Clarke transform initialization.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
151
Function Documentation
Parameters
pMem - pointer to memory where the CLARKE block is stored
size - size of memory where the CLARKE block is stored
Returns
handle - interface to access the CLARKE block
14.3.2 FAST void CLARKE_run ( CLARKE_t ∗ handle, constFEEDBACK_output_t ∗const input )
152Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 15Park Transform15.1 OverviewConverts three phase current feedback signals to two phase representation.
Functional description
Field oriented control of motors requires transformation from three vectors to two perpendicular vectorsin a stationary reference frame to two perpendicular vectors in a rotating reference frame, then the reverseprocess. The Park Transform block effects the transition between two vectors in the stationary frame(Alpha-Beta frame) to two vectors in the rotating frame (D-Q frame).
Figure 15.1.1: Effect of Park Transform
This transformation is required in the feedback loop: after current is sensed along the motor’s three phasesin the Feedback block and converted into two vectors via the Clarke Transform, these two vectors aretransformed into the rotating reference frame using the angular position estimate provided by the Estimatorblock.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
153
Overview
Block diagram detail
Figure 15.1.2: Park Transform
Configuration, inputs, and outputs
No configuration of the Park Transform block is required. The inputs are the stationary reference framecurrent vectors and the motor’s angular position as estimated by the Estimator block. These allow the ParkTransform block to produce two current vectors in the rotating (D- and Q-axis) reference frame to pass tothe Current block.
Code security breakdown
The table below describes the partitioning of Park Transform block code among open source, library, andprotected execute-only.
Open Source Library Execute-onlyStructures for output; functions forinitialization and running transfor-mation
Implementation of relevant func-tions
N/A
Execution
The Park Transform is run in the Fast ISR because the current sensing happening in the feedback loopoccurs rapidly and these dynamics must be accounted for rapidly in motor control operation.
154Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
User customization example
While the Park Transform is required for field oriented control, the user may wish to utilize differentmathematical method for performing the transform. The underpinnings of this block - the code for trans-formations - may be adapted for this purpose.
Data Structures• struct PARK_output_t
Rotating reference frame 16-bit extended vector type. More...• struct PARK_t
Output of Park function in stationary reference frame. More...
Functions• PARK_t ∗ PARK_init (void ∗pMem, size_t size)
Clarke transform initialization.• FAST void PARK_run (PARK_t ∗handle, const TRF_orient32_t ∗const orient, TRF_sVector16_t∗input)
Park Transformation function.
15.2 Data Structure Documentation15.2.1 struct PARK_output_t
Rotating reference frame 16-bit extended vector type.
Data Fields
TRF_r←↩Vector16_t
vector
15.2.2 struct PARK_t
Output of Park function in stationary reference frame.
Data Fields
PARK_←↩output_t
output
15.3 Function Documentation15.3.1 PARK_init ( void ∗ pMem, size_t size )
Clarke transform initialization.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
155
Function Documentation
Parameters
pMem - pointer to memory where the PARK block is stored
size - size of memory where the PARK block is stored
Returns
handle - interface to access the PARK block
15.3.2 PARK_run ( PARK_t ∗ handle, const TRF_orient32_t ∗const orient,TRF_sVector16_t ∗ input )
Park Transformation function.
Parameters
handle - pointer to the PARK block
orient - sin and cos of the motor angle
input - stationary reference frame input
Returns
none
156Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 16Startup16.1 OverviewManages motor operation when near zero speed.
Functional description
The Startup block is responsible for starting the motor from zero speed, where the back-EMF signal isinsufficient to provide knowledge of where the motor is in its rotation and thus insufficient for KMS toestimate the motor electrical angle. The Startup block increases the speed of the motor until it receivesa signal from the Sensorless Estimation block (est.output.sensorlessEnabled in purple), alerting Startupthat it should begin to merge the two motor angles together to provide a seamless transition from open-loop to closed-loop. When the angle merge is complete, Startup sends a signal to the rest of the FOC(startup.output.controlType in blue). An example of this is shown below.
Figure 16.1.1: Startup Example
The Startup block relies on controlling current. Specifically, it involves applying a current on the D-axis, or direct axis, which is aligned with the rotor's magnetic flux. This current implicitly forces therotor to align to a rotating D-axis (startup.output.statorRefCurrent.d in purple), which begins to spin themotor. The amount of current dynamically ramps up as necessary to ensure that the motor can start tospin despite applied load (though dynamic ramp-up may be disabled if a fixed current value is preferred).
Freescale SemiconductorKinetis Motor Suite API Reference Manual
157
Overview
Startup determines if the current applied to the D-axis needs to be increased by looking at the motor fluxto determine if the motor is indeed rotating. An example of this is shown in the figure below.
Figure 16.1.2: Startup with Increasing Current
Once the speed reference has crossed the Speed Threshold, the Startup block begins blending (or merging)the angle produced by the Startup block with the angle generated by the Sensorless Estimator block. It willalso blend current along the D-axis (startup.output.statorRefCurrent.d in red) with current on the Q-axis(startup.output.statorRefCurrent.q in green) [quadrature axis, perpendicular to the D-axis, for producingtorque] to avoid abrupt changes in current, as in normal operation current should be applied on the torqueproducing axis. Startup then loads the Q-axis current into the speed controller (speed.output.IqRef inpurple) and switches over from current control to closed loop speed control (startup.output.controlType inblue). This process is shown in the below figure.
158Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Figure 16.1.3: Startup Current Blend
In addition to starting the motor from zero speed, Startup will also take control of the motor when tran-sitioning from positive speeds to negative speeds and vice versa. An example of this is shown below. Inthis example the control method (startup.output.controlType in blue) is set to open-loop when the speedreference (trajvel.output.refSpeed in red) drops below the Speed Threshold. The control method is setback to closed-loop when the speed reference exceeds the Speed Threshold.
Figure 16.1.4: Startup Current Blend
Freescale SemiconductorKinetis Motor Suite API Reference Manual
159
Overview
Block diagram detail
Figure 16.1.5: Startup
Configuration, inputs, and outputs
Configuration of the Startup block primarily involves defining the behavior of dynamic current ramp-up.While defaults are assumed, the user may specify percentages of rated current that will bound the range ofcurrent allowed for dynamic current ramp-up and the speed with which the current will ramp.
Additional inputs include base speed and sample time.
The outputs of the Startup block are reference currents to drive the motor and indicators of ability totransition to closed loop control.
Code security breakdown
The table below describes the partitioning of Startup block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyStructures for module and output;functions for initialization, configu-ration, and updating
N/A Implementation of soft start, angleblending, crossover logic, updatingfunctions
Execution
The Startup block is primarily operated in the Fast ISR because the objective is to move the system intoclosed loop control as quickly as possible, and this requires the best possible information. Some Startuproutines execute in the Slow ISR due to the less time-critical nature of those routines.
160Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
User customization example
Sensorless startup is among the most difficult of challenges in motor control, and wide applicability ofany one solution is not guaranteed. Consequently, the user may have proprietary startup algorithms thathave proven successful over multiple product development cycles. In this case, the user may choose toremove the Startup block entirely in favor of connecting a proprietary startup to KMS’ normal closed loopoperation.
Data Structures• struct STARTUP_config_t• struct STARTUP_output_t• struct STARTUP_t
Macros• #define STARTUP_PRV_SIZE 16
Functions• STARTUP_t ∗ STARTUP_init (void ∗pMem, size_t size)
Startup initialization.• void STARTUP_config (STARTUP_t ∗handle, _lq(∗startup_LQsinPU)(_lq x), const STARTUP_←↩
config_t ∗const config, _lq lq16BaseSpeedElecFreq, _lq focSampleTime, _lq lq16AngDiffCutoff←↩FreqHz)
• void STARTUP_updateSlowTick (STARTUP_t ∗handle, _lq rotorRefSpeed, _lq filtStatorFluxSp←↩VecMag)
• void STARTUP_reset (STARTUP_t ∗handle)Startup reset.
• void STARTUP_updateFastTick (STARTUP_t ∗handle, _lq angleEst, bool sensorlessEnabled, _lqrotorRefSpeed, _sq currentFdbIq)
16.2 Data Structure Documentation
16.2.1 struct STARTUP_config_t
Data Fields
bool enableSoftStart user configurable variable to enable soft start-up
_lq minSyncSpeed Minimum speed above which Soft Start works
Freescale SemiconductorKinetis Motor Suite API Reference Manual
161
Macro Definition Documentation
_lq percentMax maximum percent of rated current for a Soft Start (in real worldpercentage)
_lq percentMin minimum percent of rated current for a Soft Start in real worldpercentage
_lq pmFluxSync←↩ThreshWb
PM Flux in Wb which triggers a stall
_sq ratedCurrent rated motor current (in pu Arms)
_lq risingTime time to rise from percentMin to percentMax during a Soft Start (inseconds)
16.2.2 struct STARTUP_output_t
Data Fields
DRV_control←↩_e
controlType motor control type (startup or FOC)
_lq fieldAngle rotor field angle (in pu radians)
TRF_r←↩Vector16_t
statorRef←↩Current
stator reference dq current (in pu Arms)
16.2.3 struct STARTUP_t
Data Fields
STARTUP_←↩config_t
config Configuration structure for startup module
STARTUP_←↩output_t
output Output structure for startup module
uint32_t prv[STARTU←↩P_PRV_SIZE]
Private variables
16.3 Macro Definition Documentation
16.3.1 #define STARTUP_PRV_SIZE 16
162Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
16.4 Function Documentation
16.4.1 void STARTUP_config ( STARTUP_t ∗ handle, _lq(∗)(_lq x)startup_LQsinPU, const STARTUP_config_t ∗const config, _lqlq16BaseSpeedElecFreq, _lq focSampleTime, _lq lq16AngDiffCutoffFreqHz)
16.4.2 STARTUP_init ( void ∗ pMem, size_t size )
Startup initialization.
Parameters
pMem - pointer to memory where the STARTUP block is stored
size - size of memory where the STARTUP block is stored
Returns
handle - interface to access the STARTUP block
16.4.3 STARTUP_reset ( STARTUP_t ∗ handle )
Startup reset.
Parameters
handle - pointer to the STARTUP block
Returns
none
16.4.4 void STARTUP_updateFastTick ( STARTUP_t ∗ handle, _lq angleEst, boolsensorlessEnabled, _lq rotorRefSpeed, _sq currentFdbIq )
16.4.5 void STARTUP_updateSlowTick ( STARTUP_t ∗ handle, _lq rotorRefSpeed,_lq filtStatorFluxSpVecMag )
Freescale SemiconductorKinetis Motor Suite API Reference Manual
163
Function Documentation
164Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 17Sensorless Estimator17.1 OverviewGenerates sensorless angle and speed feedback from the phase currents in the stator reference frame. Partof this block runs in the fast ISR and part runs in the slow ISR.
Functional description
The Sensorless Estimator block is primarily responsible for providing an estimate of the motor’s electricalangular position. This estimate allows for properly transforming the voltage references from rotating tostationary reference frame and thereby ensures that maximum torque will be generated by applied voltage.The estimate also allows for the calculation of an estimated speed, which serves as the speed feedback tothe Speed block and thereby allows the velocity controller to assess then compensate for the differencebetween desired and “actual” (estimated) speed.
The angle estimate is achieved by relying on the rotation of the motor to induce back-electromotive force.This form of angle estimation relies on having accurate motor parameters (Stator Resistance, Stator Induc-tance, and Rotor Flux). It is not dependent on knowing the motor's saliency. In order to improve estimationaccuracy KMS also uses device model information (Resistive Loss, Voltage Loss, and Deadtime). Thereis no tuning required for the angle estimation.
The speed estimate is achieved by using the estimated electrical angle. A PLL is used in order to filterthe delta electrical angle used for speed calculation. There is a single tuning parameter to adjust for thespeed estimate, PLL Bandwidth. The initial value for PLL Bandwidth will typically work for a motordisconnected from any load or inertia. If the motor is coupled with a large inertia, the PLL Bandwidthshould be decreased by half. This is because the PLL Bandwidth is related to the system's ability toaccelerate.
The complete Sensorless Estimator block is only required for Sensorless Velocity control. For SensoredVelocity and Sensored Position control a subset of the Sensorless Estimator called Flux Estimator is avail-able. Its primary objective is to estimate the amount of rotor flux which is used for torque estimation andfor fault detection.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
165
Overview
Block diagram detail
Figure 17.1.1: Sensorless
Configuration, inputs, and outputs
The Sensorless Estimator block is configured with the motor and system parameters.
The inputs are the stationary reference currents in the Alpha-Beta (two vector stationary reference frame).Additional current and voltage inputs are also required for data collection and other estimations.
The primary outputs are the electrical angle and speed estimates. There are additional outputs for torqueand power estimates.
Code security breakdown
The table below describes the partitioning of Sensorless Estimator block code among open source, library,and protected execute-only.
Open Source Library Execute-onlyDefinition of outputs such as angle,speed, power; configuration and up-dating functions
N/A Implementation of sensorless ob-server, torque & power estimators
Execution
The main operations of the Sensorless Estimator run in both the Fast ISR and Slow ISR, as the performanceof the system relies substantially on the angular position estimate and the speed feedback estimate.
166Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
User customization example
Sensorless rotor position detection algorithms are a key area of research and development for any com-pany developing motor control IP. The user may wish to use algorithms developed internally for his/herapplication and may therefore wish to eliminate the Sensorless Estimator.
Another method for customizing the Sensorless Estimator block revolves around other outputs of theblock. Torque and power estimates for example may prove useful for triggering certain application behav-iors.
Data Structures• struct EST_config_t
Estimator configuration structure. More...• struct EST_output_t
Estimator output structure. More...• struct EST_t
Estimator structure. More...
Macros• #define EST_PRV_SIZE 91
Functions• EST_t ∗ EST_init (void ∗pMem, size_t size)
Estimator initialization.• void EST_config (EST_t ∗handle, const EST_config_t ∗const config, _lq lq16BaseSpeedElecFreq,
_lq focSampleTime, _lq slowSampleTime, _lq deadTimePerTs, _lq lq16SpeedCutoffFreqHz, _←↩lq lq16PowerCutoffFreqHz, _lq lq16IsdqCutoffFreqHz, _lq lq16FluxCutoffFreqHz, _lq lq16Ang←↩OffsetCutoffFreqHz)
• void EST_reset (EST_t ∗handle)Resets the Estimator module.
• void EST_updateSlowTick (EST_t ∗handle, bool enable, _lq rotorRefSpeed, _lq invVdc, boolenableDCInjection)
• void EST_updateFastTick (EST_t ∗handle, const SVPWM_output_t ∗const pSVPWMOutput, constFEEDBACK_output_t ∗const pADC, TRF_sVector16_t ∗statorCurrentAB, _lq statorRefVoltage←↩Magnitude, TRF_rVector16_t ∗statorCurrentDQ)
17.2 Data Structure Documentation
17.2.1 struct EST_config_t
Estimator configuration structure.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
167
Data Structure Documentation
Data Fields
_lq FOCLowSpeed Rotor Speed (pu) threshold for sensorless speed control
PID_pi←↩Param32_t
pll PI parameter structure
_lq pllFiltBwHz Pll P Error filter bandwidth in Hz
_lq pmFlux Permanent magnet flux (pu)
_lq pmFluxDivLsq PM Flux / q-axis Stator inductance
_lq R_igbt IGBT resistance / DRV_BASE_RESISTANCE (pu)
_lq statorDInd d-axis Stator inductance (pu)
_lq statorQInd q-axis Stator inductance (pu)
_lq statorRes Stator resistance (pu)
_lq V_igbt IGBT voltage drop / ADC_BASE_VOLTAGE (pu)
_lq vBasedFlux←↩CoeffA
Flux estimator co-efficient A
_lq vBasedFlux←↩CoeffB
Flux estimator co-efficient B
17.2.2 struct EST_output_t
Estimator output structure.
Data Fields
_lq activePower Active power (pu)
_lq reactivePower Reactive power (pu)
_lq rotorAngle Estimated rotor angle (-1 to +1)
_lq rotorSpeed Estimated rotor speed (pu)
_lq rotorSpeed_←↩50Hz
Filtered rotor speed (pu)
void ∗ SCM_data Estimates for the SCM module
bool sensorless←↩Enabled
true: speed sensorless control enabled
168Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
_lq statorCurrent←↩Magnitude
Stator Current magnitude (pu)
_lq statorFlux←↩Magnitude
Stator Flux Magnitude (pu)
_lq statorRef←↩Voltage←↩Magnitude
DRV_statorRefVoltageMagnitude
_lq statorVoltage←↩Magnitude
DRV_statorVoltageMagnitude
_lq torque Estimated torque (pu)
17.2.3 struct EST_t
Estimator structure.
Data Fields
EST_config_t config Estimator configuration structure
EST_output_t output Estimator output structure
uint32_t prv[EST_PR←↩V_SIZE]
Estimator private data block
17.3 Macro Definition Documentation
17.3.1 #define EST_PRV_SIZE 91
17.4 Function Documentation
17.4.1 void EST_config ( EST_t ∗ handle, const EST_config_t ∗const config, _lqlq16BaseSpeedElecFreq, _lq focSampleTime, _lq slowSampleTime, _lqdeadTimePerTs, _lq lq16SpeedCutoffFreqHz, _lq lq16PowerCutoffFreqHz,_lq lq16IsdqCutoffFreqHz, _lq lq16FluxCutoffFreqHz, _lqlq16AngOffsetCutoffFreqHz )
17.4.2 EST_init ( void ∗ pMem, size_t size )
Estimator initialization.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
169
Function Documentation
Parameters
pMem - pointer to memory where the EST block is stored
size - size of memory where the EST block is stored
Returns
handle - interface to access the EST block
17.4.3 EST_reset ( EST_t ∗ handle )
Resets the Estimator module.
Parameters
handle - pointer to the EST block
Returns
none
17.4.4 void EST_updateFastTick ( EST_t ∗ handle, const SVPWM_output_t∗const pSVPWMOutput, const FEEDBACK_output_t ∗const pADC,TRF_sVector16_t ∗ statorCurrentAB, _lq statorRefVoltageMagnitude,TRF_rVector16_t ∗ statorCurrentDQ )
17.4.5 void EST_updateSlowTick ( EST_t ∗ handle, bool enable, _lqrotorRefSpeed, _lq invVdc, bool enableDCInjection )
170Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 18Encoder18.1 OverviewProvides sensored angular position and velocity feedback.
Functional description
The Encoder block converts the motor electrical angle into speed a position signals usable by the speedand position control system. The motor electrical angle is generated from the QEI block each iterationof the Fast ISR. The Encoder block uses the delta between the previous electrical angle and the currentelectrical angle in order to perform its speed and position calculations. Since it relies on this delta, it doesnot need to be called at the Fast ISR rate.
The Encoder block is effectively a simplified wrapper block for the core algorithms of SpinTAC™ PositionConvert submodule.
Block diagram detail
Figure 18.1.1: Encoder
Configuration, inputs, and outputs
The Encoder blocks relies on sample time, pole pairs, and the base electrical speed in order to be configuredcorrectly.
The input to the Encoder block is the motor electrical angle with is the output of the QEI block.
The outputs consist of the motor speed and the motor mechanical angle.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
171
Overview
Code security breakdown
The table below describes the partitioning of Encoder block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-onlyStructures for configuring encoderand functions for running encodercalculation
Implementation of speed and posi-tion calculation
N/A
Execution
Since the output of the Encoder block is speed and position feedback signals used for motion control, it isexecuted in the Slow ISR.
User customization example
For speed control applications, the Encoder block could be replaced with a similar function that determinesthe motor speed in the correct scaled units. For position control it is not recommended to replace this blocksince the motor mechanical angle output format is aligned with the outputs of the Trajectory block and theinputs of the Position block.
Modules• Quadrature Encoder Interface
The Quadrature Encoder Interface uses the FlexTimer hardware on the MCU to decode the incomingencoder phases into a motor electrical angle.
Data Structures• struct ENC_output_t
Encoder output structure. More...• struct ENC_t
Encoder structure. More...
Macros• #define ENC_PRV_SIZE 42
Functions• ENC_t ∗ ENC_init (void ∗pMem, size_t size)
Encoder initialization.• void ENC_config (ENC_t ∗handle, _lq sampleTime, uint16_t polePairs, _lq lq16BaseSpeedElec←↩
Freq, _lq lq16SpeedCutoffFreqHz)
172Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Configure Encoder block.• void ENC_run (ENC_t ∗handle, _lq rotorAngle_erev)
Run Encode calculations.• void ENC_reset (ENC_t ∗handle)
Reset ENC block.
18.2 Data Structure Documentation
18.2.1 struct ENC_output_t
Encoder output structure.
Data Fields
uint16_t errID Error ID { 0: no error; others: see error code }
int32_t rollOverCounts Number of rollovers between position windows (i.e. 10 -> -10,increases count; -10 -> 10 decreases count)
_lq rotorAngle_←↩Mrev
Position { unit: [MRev] }
_lq rotorSpeed Speed unfiltered { unit: [pu rpm] }
_lq rotorSpeed_←↩50Hz
Speed filtered { unit: [pu rpm] }
18.2.2 struct ENC_t
Encoder structure.
Data Fields
ENC_output_t output
uint32_t prv[ENC_PR←↩V_SIZE]
18.3 Macro Definition Documentation
18.3.1 #define ENC_PRV_SIZE 42
18.4 Function Documentation
18.4.1 ENC_config ( ENC_t ∗ handle, _lq sampleTime, uint16_t polePairs, _lqlq16BaseSpeedElecFreq, _lq lq16SpeedCutoffFreqHz )
Configure Encoder block.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
173
Function Documentation
Parameters
handle - pointer to the ENC block
sampleTime - slow interrupt period { unit: [sec] }
polePairs - number of motor pole pairs
lq16Base←↩SpeedElecFreq
- base electrical speed (in rad/sec)
lq16Speed←↩CutoffFreqHz
- feedback speed filter freq (Q16.16, Hz)
Returns
none
18.4.2 ENC_init ( void ∗ pMem, size_t size )
Encoder initialization.
Parameters
pMem - pointer to memory where the ENC block is stored
size - size of memory where the ENC block is stored
Returns
handle - interface to access the ENC block
18.4.3 ENC_reset ( ENC_t ∗ handle )
Reset ENC block.
Parameters
handle - pointer to the ENC block
18.4.4 ENC_run ( ENC_t ∗ handle, _lq rotorAngle_erev )
Run Encode calculations.
174Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
handle - pointer to the ENC block
rotorAngle_←↩erev
- feedback electrical angle { unit: [elec angle] }
Returns
none
Freescale SemiconductorKinetis Motor Suite API Reference Manual
175
Quadrature Encoder Interface
18.5 Quadrature Encoder Interface
18.5.1 Overview
The Quadrature Encoder Interface uses the FlexTimer hardware on the MCU to decode the incomingencoder phases into a motor electrical angle.
Data Structures
• struct QEI_output_tQEI output variables. More...
• struct QEI_internal_tQEI internal variables. More...
• struct QEI_tQEI module. More...
Macros
• #define FTM_ENCODER_INSTANCE (1U) /∗ FTM Instance Number user for encoder ∗/• #define FTM_ENCODER_BASE FTM1 /∗ FTM_Type∗ at FTM 1 Base Address ∗/• #define HW_CHAN0 (0U) /∗ FTM Channel Assignment for PHA ∗/• #define HW_CHAN1 (1U) /∗ FTM Channel Assignment for PHB ∗/
Functions
• QEI_t ∗ QEI_init (void ∗pMem, size_t size)• void QEI_config (QEI_t ∗handle, uint16_t encoderPulses, uint16_t polePairs)
Configures QEI module.• FAST void QEI_updateAtFastTick (QEI_t ∗handle)
Update QEI module at Fast tick.• void QEI_resetEncoderAngle (QEI_t ∗handle)
Resets encoder angle (virtual and real)• void QEIS_init (uint16_t qeiMaxPosCount)
Initializes QEI system.• uint16_t QEIS_readPositionCounter (void)
Reads 16-bit position counter.• void QEIS_writePositionCounter (uint16_t value)• void QEIS_swapTracks (bool swapIt)
Swaps encoder tracks A and B.
18.5.2 Data Structure Documentation
18.5.2.1 struct QEI_output_t
QEI output variables.
176Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Quadrature Encoder Interface
Data Fields
_lq rotorAngle motor angle { unit: [electrical revolutions] }
18.5.2.2 struct QEI_internal_t
QEI internal variables.
Data Fields
_lq angleScalar Scale factor to convert encoder counts into electrical angle
int32_t encoderMax←↩Count
Maximum post-quadrature count on the encoder
uint16_t polePairs Number of motor pole pairs
18.5.2.3 struct QEI_t
QEI module.
Data Fields
QEI_internal←↩_t
internal Internal data structure for QEI module
QEI_output_t output Output structure for QEI module
18.5.3 Macro Definition Documentation
18.5.3.1 #define FTM_ENCODER_BASE FTM1 /∗ FTM_Type∗ at FTM 1 Base Address ∗/
Referenced by QEIS_init(), QEIS_readPositionCounter(), QEIS_swapTracks(), and QEIS_write←↩PositionCounter().
18.5.3.2 #define FTM_ENCODER_INSTANCE (1U) /∗ FTM Instance Number user forencoder ∗/
Referenced by QEIS_init().
18.5.3.3 #define HW_CHAN0 (0U) /∗ FTM Channel Assignment for PHA ∗/
Referenced by QEIS_init().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
177
Quadrature Encoder Interface
18.5.3.4 #define HW_CHAN1 (1U) /∗ FTM Channel Assignment for PHB ∗/
Referenced by QEIS_init().
18.5.4 Function Documentation
18.5.4.1 void QEI_config ( QEI_t ∗ handle, uint16_t encoderPulses, uint16_t polePairs )
Configures QEI module.
Parameters
handle - point to the QEI block
encoderPulses - number of pulses on the encoder
polePairs - number of motor pole pairs
Returns
none
18.5.4.2 QEI_t∗ QEI_init ( void ∗ pMem, size_t size )
18.5.4.3 void QEI_resetEncoderAngle ( QEI_t ∗ handle )
Resets encoder angle (virtual and real)
Parameters
handle - point to the QEI block
Returns
none
18.5.4.4 void QEI_updateAtFastTick ( QEI_t ∗ handle )
Update QEI module at Fast tick.
178Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Quadrature Encoder Interface
Parameters
handle - point to the QEI block
Returns
none
18.5.4.5 void QEIS_init ( uint16_t qeiMaxPosCount )
Initializes QEI system.
Parameters
qeiMaxPos←↩Count
- maximum position count
Returns
none
References FTM_ENCODER_BASE, FTM_ENCODER_INSTANCE, HW_CHAN0, and HW_CHAN1.
18.5.4.6 uint16_t QEIS_readPositionCounter ( void )
Reads 16-bit position counter.
Returns
16-bit unsigned position value
References FTM_ENCODER_BASE.
18.5.4.7 void QEIS_swapTracks ( bool negativeDirection )
Swaps encoder tracks A and B.
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
179
Quadrature Encoder Interface
swapIt - true to swap tracks, false otherwise
Returns
none
References FTM_ENCODER_BASE.
18.5.4.8 void QEIS_writePositionCounter ( uint16_t value )
References FTM_ENCODER_BASE.
180Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 19Current19.1 OverviewTwo channel (Iq and Id) current regulator which outputs D and Q phase voltages.
Functional description
The Current block is responsible for taking in a current reference value, comparing it to actual sensedcurrent, then outputting a voltage reference for the D-axis and Q-axis to be used to correct the currenterror and perpetuate the rotating magnetic field that induces rotation in the motor.
This is achieved by means of applying traditional proportional-integral controllers to the direct and quadra-ture axes, where feedback current is always provided by the Park Transform block and the origin of refer-ence current depends on the state of operation. During normal closed loop speed control, the Speed blockprovides a current reference. When starting from zero, the Park Transform block still provides feedback.Finally, at high modulation and speed, the Field Weakening block provides current reference. If runningin torque control mode the current references are provided from the User inputs.
The Current controller gains are automatically tuned during the SCM process but can be manually updatedby changing current loop bandwidth or gains in the user interface.
Block diagram detail
Figure 19.1.1: Current
Freescale SemiconductorKinetis Motor Suite API Reference Manual
181
Overview
Configuration, inputs, and outputs
Configuration of the Current block primarily involves setting the gains for PI controller that compensatesfor error between desired and actual current.
The main inputs are the current references and feedbacks for both D and Q axes.
The outputs are the reference voltages used to adjust the amount of current flowing through the motor.
Code security breakdown
The table below describes the partitioning of Current block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyInitialization, configuration, resets,function for performing currentcontrol
Calculation and implementation ofcurrent loop gains
N/A
Execution
The Current block runs in the Fast ISR to perform real-time control action based on rapidly changingcurrent feedback.
User customization example
The user may wish to utilize a custom advanced control algorithm (e.g., gain scheduling) specific to his/herapplication. This could be used to replace the PI based controller structure provided that input current errorresults in a voltage reference.
Data Structures• struct CURRENT_output_t• struct CURRENT_config_t• struct CURRENT_t
Current module structure. More...
Macros• #define CURRENT_PRV_SIZE 26
Functions• CURRENT_t ∗ CURRENT_init (void ∗pMem, size_t size)
182Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
Current control loop initialization.• void CURRENT_config (CURRENT_t ∗handle, const CURRENT_config_t ∗const config, _lq foc←↩
SampleTime, _lq lq16fltIdqErrorCutoffFrq, _lq voltageGain)Current control loop configuration.
• void CURRENT_resetController (CURRENT_t ∗handle)Resets internal states for CURRENT block.
• void CURRENT_resetFilters (CURRENT_t ∗handle)Resets internal states for filters.
• FAST void CURRENT_run (CURRENT_t ∗handle, bool enable, _lq Vdc, _lq invVdc, TRF_r←↩Vector16_t ∗pRefCurrent, TRF_rVector16_t ∗pFbkCurrent)
Current control loop function (regulates current in a d-q domain)• void CURRENT_setIntegrator (CURRENT_t ∗handle, _lq Vdc, const TRF_rVector32_t ∗const p←↩
RefVoltage)
19.2 Data Structure Documentation
19.2.1 struct CURRENT_output_t
Data Fields
TRF_r←↩Vector32_t
statorRef←↩VoltageDQ
19.2.2 struct CURRENT_config_t
Data Fields
PID_pi←↩Param16_t
Id
PID_pi←↩Param16_t
Iq
19.2.3 struct CURRENT_t
Current module structure.
Data Fields
Freescale SemiconductorKinetis Motor Suite API Reference Manual
183
Function Documentation
CURRENT_←↩config_t
config
CURRENT_←↩output_t
output
uint32_t prv[CURRE←↩NT_PRV_SI←↩ZE]
19.3 Macro Definition Documentation
19.3.1 #define CURRENT_PRV_SIZE 26
19.4 Function Documentation
19.4.1 CURRENT_config ( CURRENT_t ∗ handle, const CURRENT_config_t∗const config, _lq focSampleTime, _lq lq16fltIdqErrorCutoffFrq, _lqvoltageGain )
Current control loop configuration.
Parameters
handle - pointer to the CURRENT block
config - pointer to CURRENT_config block
focSampleTime - time between successive current loop calls
lq16fltIdq←↩ErrorCutoffFrq
- current filter cutoff freq (Hz)
voltageGain - gain to scale Vdc
Returns
none
19.4.2 CURRENT_init ( void ∗ pMem, size_t size )
Current control loop initialization.
184Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
pMem - pointer to memory where the CURRENT block is stored
size - size of memory where the CURRENT block is stored
Returns
handle - interface to access the CURRENT block
19.4.3 void CURRENT_resetController ( CURRENT_t ∗ handle )
Resets internal states for CURRENT block.
Parameters
handle - pointer to the CURRENT block
Returns
none
19.4.4 CURRENT_resetFilters ( CURRENT_t ∗ handle )
Resets internal states for filters.
Parameters
handle - pointer to the CURRENT block
Returns
none
19.4.5 CURRENT_run ( CURRENT_t ∗ v, bool enable, _lq Vdc, _lq invVdc,TRF_rVector16_t ∗ pRefCurrent, TRF_rVector16_t ∗ pFbkCurrent )
Current control loop function (regulates current in a d-q domain)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
185
Function Documentation
Parameters
handle - pointer to the CURRENT block
enable - enables the current loop operation
Vdc - DC Bus Voltage filtered at 1kHz
invVdc - Inverse DC Bus Voltage filtered at 1kHz
pRefCurrent - pointer to the reference d-q current vector
pFbkCurrent - pointer to the feedback d-q current vector
Returns
none
19.4.6 void CURRENT_setIntegrator ( CURRENT_t ∗ handle, _lq Vdc, constTRF_rVector32_t ∗const pRefVoltage )
186Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 20Inverse Park Transform20.1 OverviewRotates current feedback from stator reference frame to rotor reference frame.
Functional description
Field oriented control of motors requires transformation from three vectors to two perpendicular vectorsin a stationary reference frame to two perpendicular vectors in a rotating reference frame, then the reverseprocess. The Inverse Park Transform block effects the transition between two vector rotating referenceframe (D-Q frame) to two vector stationary reference frame (Alpha-Beta frame).
Figure 20.1.1: Effect of Inverse Park Transform
Freescale SemiconductorKinetis Motor Suite API Reference Manual
187
Overview
Block diagram detail
Figure 20.1.2: Inverse Park Transform
Configuration, inputs, and outputs
No configuration of the Inverse Park Transform block is required.
The inputs are the desired voltages or currents in the rotating frame (D-Q frame) and the angular positionof the rotor as estimated by the Sensorless Estimator block.
The outputs are the same values on the stationary frame (Alpha-Beta frame).
Code security breakdown
The table below describes the partitioning of Inverse Park Transform block code among open source,library, and protected execute-only.
Open Source Library Execute-onlyStructures for output; functions forinitialization and running transfor-mation
Implementation of relevant func-tions
N/A
Execution
The Inverse Park Transform block is executed in the Fast ISR to ensure real-time adaptation to quicklychanging electrical dynamics.
188Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
User customization example
While the Inverse Park Transform is required for field oriented control, the user may wish to utilize dif-ferent mathematical method for performing the transform. The underpinnings of this block - the code fortransformations - may be adapted for this purpose.
Data Structures• struct IPARK_output_t
Stationary reference frame (alpha/beta) 32-bit vector type. More...• struct IPARK_t
Output of inverse park function. More...
Functions• IPARK_t ∗ IPARK_init (void ∗pMem, size_t size)
Inverse Park transform initialization.• void IPARK_reset (IPARK_t ∗handle)
Inverse Park transform reset.• FAST void IPARK_run (IPARK_t ∗handle, const TRF_orient32_t ∗const orient, TRF_rVector32_t∗input)
Inverse Park Transformation function.
20.2 Data Structure Documentation
20.2.1 struct IPARK_output_t
Stationary reference frame (alpha/beta) 32-bit vector type.
Magnitude of alpha/beta vectors
Data Fields
_lq magnitude Magnitude of stationary vectors
TRF_s←↩Vector32_t
vector 32 bit stationary vectors
20.2.2 struct IPARK_t
Output of inverse park function.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
189
Function Documentation
Data Fields
IPARK_←↩output_t
output
20.3 Function Documentation
20.3.1 IPARK_init ( void ∗ pMem, size_t size )
Inverse Park transform initialization.
Parameters
pMem - pointer to memory where the IPARK block is stored
size - size of memory where the IPARK block is stored
Returns
handle - interface to access the IPARK block
20.3.2 IPARK_reset ( IPARK_t ∗ handle )
Inverse Park transform reset.
Parameters
handle - pointer to the IPARK block
20.3.3 IPARK_run ( IPARK_t ∗ handle, const TRF_orient32_t ∗const orient,TRF_rVector32_t ∗ input )
Inverse Park Transformation function.
Parameters
handle - pointer to the IPARK block
190Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
orient - sin and cos of motor angle
input - rotational reference frame input
Returns
none
Freescale SemiconductorKinetis Motor Suite API Reference Manual
191
Function Documentation
192Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 21Space Vector Pulse Width Modulation21.1 OverviewSpace vector PWM block generates modulation values for the three phase inverter from the stator framevoltages.
Functional description
Space vector pulse width modulation, or SVPWM, is a means of sending signals to a three phase inverterto control its switches such that a direct current supply can be transformed into three phase alternatingcurrent. This is a standard implementation of Space Vector Modulation that features the ability to go intoovermodulation region 1. Deadtime insertion is handled by the FlexTimer hardware and not the algorithminside the SVPWM block.
Block diagram detail
Figure 21.1.1: SVPWM
Configuration, inputs, and outputs
The configuration of the SVPWM block primarily consists of defining special characteristics: whetherdead-time compensation is on; whether to enable PWM on only two phases (and thus avoid space vectorentirely); and whether to clamp inverter phases to a specific value.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
193
Overview
The primary input to the SVPWM block is the voltage reference vector in the Alpha-Beta frame that comesfrom the Inverse Park Transform block. This reference vector is acted on by the SVPWM block to producerelative duty cycles for phases A, B, and C, which will command the switches of the inverter in such away as to persist sinusoidal currents to be applied to the motor.
Additional outputs include status indicators.
Code security breakdown
The table below describes the partitioning of SVPWM block code among open source, library, and pro-tected execute-only.
Open Source Library Execute-onlyStructures and functions defin-ing configuration, PWM operation,dead-time, zero vector
PWM implementation based on op-erating sector
N/A
Execution
The SVPWM block is executed in the Fast ISR because the proper switching commands for the invertermust be processed as quickly as possible to ensure appropriate driving of current and thus the motor.
User customization example
The user may have a different, preferred strategy of implementing pulse width modulation. This canreplace the SVPWM block.
Modules• Pulse Width Modulation Interface
The Pulse Width Modulation (PWM) Interface describes how the FlexTimer is configured and used.
Data Structures• struct SVPWM_config_t
SVPWM module configuration. More...• struct SVPWM_output_t
SVPWM module output. More...• struct SVPWM_t
SVPWM module nested structure. More...
Macros• #define SVPWM_PRV_SIZE 10
194Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
Enumerations• enum SVPWM_sector_e {
SVPWM_SECT1 = 1,SVPWM_SECT2 = 2,SVPWM_SECT3 = 3,SVPWM_SECT4 = 4,SVPWM_SECT5 = 5,SVPWM_SECT6 = 6 }
• enum SVPWM_state_e {SVPWM_NORM = 0,SVPWM_OPWM1,SVPWM_OPWM2 }
SVPWM states.
Functions• SVPWM_t ∗ SVPWM_init (void ∗pMem, size_t size)
Initializes SVPWM module.• void SVPWM_config (SVPWM_t ∗handle, const SVPWM_config_t ∗const config, uint32_t pwm←↩
FreqHz, uint32_t sysFreqHz, uint16_t dtPeriod, _sq pwmCurrentDeadband, _lq dutyMin, _lq dead←↩TimePerTs, bool isHighSideActiveLow, bool isLowSideActiveLow)
Configures the SVPWM block.• FAST void SVPWM_enable (SVPWM_t ∗handle)
Enables PWM operation.• void SVPWM_enableTwoPhases (SVPWM_t ∗handle)
Enables PWM operation on two phases only.• FAST void SVPWM_disable (SVPWM_t ∗handle)
Disables PWM operation.• FAST void SVPWM_updateFastTick (SVPWM_t ∗handle, const FEEDBACK_output_t ∗const p←↩
ADC, TRF_sVector32_t ∗const pStatorVoltage, _lq magnitude)Updates PWM duty cycles.
• void SVPWM_zeroVector (SVPWM_t ∗handle, bool enableZeroVector)Outputs zero vector state (0,0,0). Low sides are held ON.
21.2 Data Structure Documentation
21.2.1 struct SVPWM_config_t
SVPWM module configuration.
Data Fields
Freescale SemiconductorKinetis Motor Suite API Reference Manual
195
Macro Definition Documentation
bool enableClamp←↩Phases
Clamps inverter phases low
21.2.2 struct SVPWM_output_t
SVPWM module output.
Data Fields
_lq drivePwmA Relative duty cycle for phase A
_lq drivePwmB Relative duty cycle for phase B
_lq drivePwmC Relative duty cycle for phase C
bool enable Enable/disable PWM operation
SVPWM_←↩sector_e
sector PWM SVPWM sector
SVPWM_←↩state_e
state PWM state
21.2.3 struct SVPWM_t
SVPWM module nested structure.
Data Fields
SVPWM_←↩config_t
config Configuration structure
SVPWM_←↩output_t
output ouput structure
uint32_t prv[SVPWM←↩_PRV_SIZE]
21.3 Macro Definition Documentation
21.3.1 #define SVPWM_PRV_SIZE 10
196Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
21.4 Enumeration Type Documentation
21.4.1 enum SVPWM_sector_e
Enumerator
SVPWM_SECT1 sector 1 (between 0 and 60 degrees)SVPWM_SECT2 sector 2 (between 60 and 120 degrees)SVPWM_SECT3 sector 3 (between 120 and 180 degrees)SVPWM_SECT4 sector 4 (between 180 and 240 degrees)SVPWM_SECT5 sector 5 (between 240 and 300 degrees)SVPWM_SECT6 sector 6 (between 300 and 360 degrees)
21.4.2 enum SVPWM_state_e
SVPWM states.
Enumerator
SVPWM_NORM Space Vector PWM (SVPWM)SVPWM_OPWM1 Over-modulation region ISVPWM_OPWM2 Over-modulation region II-III
21.5 Function Documentation
21.5.1 SVPWM_config ( SVPWM_t ∗ handle, const SVPWM_config_t ∗constconfig, uint32_t pwmFreqHz, uint32_t sysFreqHz, uint16_t dtPeriod,_sq pwmCurrentDeadband, _lq dutyMin, _lq deadTimePerTs, boolisHighSideActiveLow, bool isLowSideActiveLow )
Configures the SVPWM block.
Parameters
handle - interface to access the SVPWM block
config - pointer to SVPWM structure
pwmFreqHz - PWM carrier frequency
sysFreqHz - System clock frequency
Freescale SemiconductorKinetis Motor Suite API Reference Manual
197
Function Documentation
dtPeriod - dead time period in counts
pwmCurrent←↩Deadband
- pwm current dead band
dutyMin - minimum duty
deadTimePerTs - dead time duty
isHighSide←↩ActiveLow
- true if high side is active low
isLowSide←↩ActiveLow
- true if low side is active low
Returns
none
21.5.2 SVPWM_disable ( SVPWM_t ∗ handle )
Disables PWM operation.
Parameters
handle - interface to access the SVPWM block
Returns
none
21.5.3 SVPWM_enable ( SVPWM_t ∗ handle )
Enables PWM operation.
Parameters
handle - interface to access the SVPWM block
Returns
none
21.5.4 SVPWM_enableTwoPhases ( SVPWM_t ∗ handle )
Enables PWM operation on two phases only.
198Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
handle - interface to access the SVPWM block
Returns
none
21.5.5 SVPWM_init ( void ∗ pMem, size_t size )
Initializes SVPWM module.
Parameters
pMem - pointer to memory where the SVPWM block is stored
size - size of memory where the SVPWM block is stored
Returns
handle - interface to access the SVPWM block
21.5.6 SVPWM_updateFastTick ( SVPWM_t ∗ handle, const FEEDBACK_←↩output_t ∗const pADC, TRF_sVector32_t ∗const pStatorVoltage, _lqmagnitude )
Updates PWM duty cycles.
Parameters
handle - interface to access the SVPWM block
pADC - pointer to the FEEDBACK module output
pStatorVoltage - pointer to the stationary stator voltage vector
magnitude - stator voltage vector magnitude
Returns
none
21.5.7 SVPWM_zeroVector ( SVPWM_t ∗ handle, bool enableZeroVector )
Outputs zero vector state (0,0,0). Low sides are held ON.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
199
Function Documentation
Parameters
handle - interface to access the SVPWM block
enableZero←↩Vector
- true / false
Returns
none
200Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Pulse Width Modulation Interface
21.6 Pulse Width Modulation Interface
21.6.1 Overview
The Pulse Width Modulation (PWM) Interface describes how the FlexTimer is configured and used.
Data Structures
• struct PWMS_duty_tDuty cycles to load into PWM module. More...
Macros
• #define HW_FTM0 (0)Instance number of FlexTimer 0.
Functions
• void PWMS_init (uint16_t swPeriod, uint16_t dtPeriod)• void PWMS_enable (void)
Enables PWM signal buffer.• void PWMS_disable (void)
Disables PWM signal buffer.• void PWMS_setDuties (const PWMS_duty_t ∗const duties)
Sets duties into the PWM module.• void PWMS_setPins (void)
Sets pins of PWM module.• void PWMS_setDeadTime (uint16_t deadTime, uint16_t deadTimePS)
Sets dead time in processor time count.• void PWMS_setDrivePolarity (bool isHighSideActiveLow, bool isLowSideActiveLow)
Sets the drive polarity as active-high or active-low.
21.6.2 Data Structure Documentation
21.6.2.1 struct PWMS_duty_t
Duty cycles to load into PWM module.
Data Fields
Freescale SemiconductorKinetis Motor Suite API Reference Manual
201
Pulse Width Modulation Interface
uint16_t phaseAhi Duty cycle for Phase A High Side { unit: [PWM ticks] }
uint16_t phaseAlo Duty cycle for Phase A Low Side { unit: [PWM ticks] }
uint16_t phaseBhi Duty cycle for Phase B High Side { unit: [PWM ticks] }
uint16_t phaseBlo Duty cycle for Phase B Low Side { unit: [PWM ticks] }
uint16_t phaseChi Duty cycle for Phase C High Side { unit: [PWM ticks] }
uint16_t phaseClo Duty cycle for Phase C Low Side { unit: [PWM ticks] }
21.6.3 Macro Definition Documentation
21.6.3.1 #define HW_FTM0 (0)
Instance number of FlexTimer 0.
Referenced by PWMS_disable(), PWMS_enable(), PWMS_init(), PWMS_setDeadTime(), and PWMS←↩_setDuties().
21.6.4 Function Documentation
21.6.4.1 void PWMS_disable ( void )
Disables PWM signal buffer.
Returns
none
Parameters
swPeriod - switching period count
Returns
none
References HW_FTM0.
21.6.4.2 void PWMS_enable ( void )
Enables PWM signal buffer.
202Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Pulse Width Modulation Interface
Returns
none
References HW_FTM0.
21.6.4.3 void PWMS_init ( uint16_t swPeriod, uint16_t dtPeriod )
References HW_FTM0.
21.6.4.4 void PWMS_setDeadTime ( uint16_t deadTime, uint16_t deadTimePS )
Sets dead time in processor time count.
Parameters
deadTime - dead time in processor time count
deadTimePS - dead time prescaler for System clock.
Returns
none
References HW_FTM0.
21.6.4.5 void PWMS_setDrivePolarity ( bool isHighSideActiveLow, boolisLowSideActiveLow )
Sets the drive polarity as active-high or active-low.
Parameters
isHighSide←↩ActiveLow
- true if high side is active low
isLowSide←↩ActiveLow
- true if low side is active low
Returns
none
21.6.4.6 void PWMS_setDuties ( const PWMS_duty_t ∗const duties )
Sets duties into the PWM module.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
203
Pulse Width Modulation Interface
Parameters
duties - duty cycles to command on the next PWM update
Returns
none
References HW_FTM0, PWMS_duty_t::phaseAhi, PWMS_duty_t::phaseAlo, PWMS_duty_t::phaseBhi,PWMS_duty_t::phaseBlo, PWMS_duty_t::phaseChi, and PWMS_duty_t::phaseClo.
21.6.4.7 void PWMS_setPins ( void )
Sets pins of PWM module.
Returns
none
204Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 22Motion Sequence22.1 OverviewAllows for easy, consistent creation of motion sequences.
Functional description
The Motion Sequence block is the back-end of the Motion Sequence Builder graphical user interface: itis the infrastructure that the code generated by Motion Sequence Builder relies upon to execute a user-specified motion sequence. Since Motion Sequence Builder can create the code that uses this API already,it is not expected that most users will need to understand this API. However there are some run-timeconfiguration features that can prove useful so the complete API is provided for reference.
The building block components of Plans, States, Transitions, Conditions, Variables, and Actions are de-fined, as are the different options available for each. For instance, each of the comparison relationshipsthat can be used to determine whether a Condition has been met are enumerated.
Additionally, the common configuration options for each building block are spelled out - the ability to adda component, gets & sets, etc.
The Motion Sequence block is effectively a simplified wrapper block for the core algorithms of SpinTA←↩C™ Velocity Plan or SpinTAC™ Position Plan submodule.
Block diagram detail
Figure 22.1.1: Motion Sequence
Freescale SemiconductorKinetis Motor Suite API Reference Manual
205
Overview
Configuration, inputs, and outputs
Configuration of the Motion Sequence block is effectively represented by State Machine Builder. It in-volves defining the
• different states of motion,• transitions between speeds,• conditions upon which these transitions occur,• variables that underpin conditions, and• actions to be taken• that comprise the desired motion of a motor-driven application.
Inputs are encapsulated by configuration, and the outputs are a series of trajectory commands sent to beacted upon by the Trajectory block.
Code security breakdown
The table below describes the partitioning of Motion Sequence block code among open source, library,and protected execute-only.
Open Source Library Execute-onlyEnumeration of possible statuses,conditions, comparisons, actions,etc; set & get functions
Implementation of state machineengine
N/A
Execution
As with other blocks revolving largely around motion control, the Motion Sequence block operates in theSlow ISR, as motion control is not as time-sensitive as current control.
User customization example
The Motion Sequence block is a framework and can be customized to virtually any application where aseries of constant speeds or position steps need to be reached based on different conditions of the system.The companion KMS Lab Guide briefly walks through a simplistic example of a ceiling fan.
Modules• SpinTAC™ Velocity Plan
SpinTAC™ Velocity Plan is the code infrastructure for Motion Sequence Builder for velocity control ap-plications.
• SpinTAC™ Position Plan
206Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
SpinTAC™ Position Plan is the code infrastructure for Motion Sequence Builder for position controlapplications.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
207
SpinTAC™ Velocity Plan
22.2 SpinTAC™ Velocity Plan
22.2.1 Overview
SpinTAC™ Velocity Plan is the code infrastructure for Motion Sequence Builder for velocity controlapplications.
Data Structures
• struct ST_PlanError_tDefines the ST_PlanError_t data. More...
• struct ST_VelPlan_t
Macros
• #define ST_VEL_PLAN_ACT_DWORDS (5)• #define ST_VEL_PLAN_COND_DWORDS (3)• #define ST_VEL_PLAN_VAR_DWORDS (2)• #define ST_VEL_PLAN_TRAN_DWORDS (5)• #define ST_VEL_PLAN_STATE_DWORDS (6)• #define __ST_PLAN_ENUM__• #define __ST_PLAN_ERROR__
Typedefs
• typedef struct _ST_VELPLAN_Handle_ ∗ ST_VELPLAN_Handle
Enumerations
• enum ST_PlanStatus_e {ST_PLAN_IDLE =0,ST_PLAN_INIT,ST_PLAN_BUSY,ST_PLAN_HALT,ST_PLAN_WAIT,ST_PLAN_IDLE =0,ST_PLAN_INIT,ST_PLAN_BUSY,ST_PLAN_HALT,ST_PLAN_WAIT }
• enum ST_PlanCond_e {
208Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
ST_COND_NC =0,ST_COND_FC,ST_COND_AND,ST_COND_OR,ST_COND_NC =0,ST_COND_FC,ST_COND_AND,ST_COND_OR }
• enum ST_PlanComp_e {ST_COMP_NA =0,ST_COMP_EQ,ST_COMP_NEQ,ST_COMP_GT,ST_COMP_EGT,ST_COMP_LW,ST_COMP_ELW,ST_COMP_In,ST_COMP_EIn,ST_COMP_InE,ST_COMP_EInE,ST_COMP_Out,ST_COMP_EOut,ST_COMP_OutE,ST_COMP_EOutE,ST_COMP_NA =0,ST_COMP_EQ,ST_COMP_NEQ,ST_COMP_GT,ST_COMP_EGT,ST_COMP_LW,ST_COMP_ELW,ST_COMP_In,ST_COMP_EIn,ST_COMP_InE,ST_COMP_EInE,ST_COMP_Out,ST_COMP_EOut,ST_COMP_OutE,ST_COMP_EOutE }
• enum ST_PlanActOptn_e {ST_ACT_EQ =0,ST_ACT_ADD,ST_ACT_EQ =0,ST_ACT_ADD }
• enum ST_PlanActTrgr_e {
Freescale SemiconductorKinetis Motor Suite API Reference Manual
209
SpinTAC™ Velocity Plan
ST_ACT_ENTR =0,ST_ACT_EXIT,ST_ACT_ENTR =0,ST_ACT_EXIT }
• enum ST_PlanFsmState_e {ST_FSM_STATE_STAY =0,ST_FSM_STATE_COND,ST_FSM_STATE_TRAN,ST_FSM_STATE_STAY =0,ST_FSM_STATE_COND,ST_FSM_STATE_TRAN }
• enum ST_PlanVar_e {ST_VAR_INOUT =0,ST_VAR_IN,ST_VAR_OUT,ST_VAR_INOUT =0,ST_VAR_IN,ST_VAR_OUT }
• enum ST_VelPlan_ErrorCode_e {
210Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
No_ErrorCode = 0,Plan_running = 1,Max_States_exceed = 2,Max_Cond_exceed = 3,Max_Trans_exceed = 4,Max_Act_exceed = 5,Max_Var_exceed = 6,Invalid_Sampletime = 7,Invalid_LoopENB = 11,Invalid_HaltAccLim = 13,Invalid_HaltJrkLim = 14,Invalid_Timer_tick = 15,Invalid_State_index = 16,Invalid_Condition_index = 17,Invalid_Trans_index = 18,Invalid_Action_index = 19,Invalid_Var_index = 20,Invalid_Var_type = 21,Invalid_Value_Comp = 22,Invalid_Operation = 23,Invalid_AndOr = 24,Improper_Var_type = 25,Improper_Val_Comparison = 26,Improper_State_index = 27,Improper_Cond_Idx = 28,Improper_EnterExit = 29,Cannot_delete_Var_Cond = 30,Cannot_delete_Var_Act = 31,PlanCfg_array_Small = 37,Cannot_delete_State_Tran = 38,Cannot_delete_State_Act = 39,Invalid_Var_Compare = 40,Invalid_Var_indexes = 41,Invalid_Cond_Index = 42,Cannot_Delete_Cond_Tran = 43,Cannot_Delete_Cond_Act = 45 }
Enumeration for the Velocity Plan Error Codes.• enum ST_VelPlan_ErrorId_e {
Freescale SemiconductorKinetis Motor Suite API Reference Manual
211
SpinTAC™ Velocity Plan
No_ErrorId = 0,Error_STVELPLAN_addCfgCond = 3000,Error_STVELPLAN_delCfgCond = 3001,Error_STVELPLAN_setCfgCond = 3002,Error_STVELPLAN_getCfgCond = 3003,Error_STVELPLAN_addCfgTran = 3004,Error_STVELPLAN_delCfgTran = 3005,Error_STVELPLAN_setCfgTran = 3006,Error_STVELPLAN_getCfgTran = 3007,Error_STVELPLAN_addCfgAct = 3008,Error_STVELPLAN_delCfgAct = 3009,Error_STVELPLAN_setCfgAct = 3010,Error_STVELPLAN_getCfgAct = 3011,Error_STVELPLAN_addCfgVar = 3012,Error_STVELPLAN_delCfgVar = 3013,Error_STVELPLAN_setCfgVar = 3014,Error_STVELPLAN_getCfgVar = 3015,Error_STVELPLAN_addCfgState = 3016,Error_STVELPLAN_delCfgState = 3017,Error_STVELPLAN_setCfgState = 3018,Error_STVELPLAN_setVar = 3019,Error_STVELPLAN_getVar = 3020,Error_STVELPLAN_setCfg = 3021,Error_STVELPLAN_setCfgHaltState = 3022,Error_STVELPLAN_setCfgArray = 3023,Error_STVELPLAN_addCfgVarCond = 3024,Error_STVELPLAN_delCfgVarCond = 3025,Error_STVELPLAN_setCfgVarCond = 3026,Error_STVELPLAN_getCfgVarCond = 3027,Invalid_STLicense = 4001,Invalid_RomVersion = 4003 }
Enumeration for the Velocity Plan Error Id, indicates the function which caused the error.
Functions
• static _lq24 STVELPLAN_getVelocitySetpoint (ST_VELPLAN_Handle handle)Gets the Velocity Setpoint (VelEnd) for SpinTAC Velocity Plan.
• static _lq24 STVELPLAN_getAccelerationLimit (ST_VELPLAN_Handle handle)Gets the Acceleration Limit (AccLim) for SpinTAC Velocity Plan.
• static _lq20 STVELPLAN_getJerkLimit (ST_VELPLAN_Handle handle)Gets the Jerk Limit (JrkLim) for SpinTAC Velocity Plan.
• static void STVELPLAN_setEnable (ST_VELPLAN_Handle handle, bool enb)Sets the Enable signal (ENB) for SpinTAC Velocity Plan.
• static bool STVELPLAN_getEnable (ST_VELPLAN_Handle handle)Gets the Enable signal (ENB) for SpinTAC Velocity Plan.
212Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
• static void STVELPLAN_setReset (ST_VELPLAN_Handle handle, bool res)Sets the Reset signal (RES) for SpinTAC Velocity Plan.
• static bool STVELPLAN_getReset (ST_VELPLAN_Handle handle)Gets the Reset signal (RES) for SpinTAC Velocity Plan.
• static ST_PlanStatus_e STVELPLAN_getStatus (ST_VELPLAN_Handle handle)Gets the Status value (STATUS) for SpinTAC Velocity Plan.
• static uint16_t STVELPLAN_getCurrentState (ST_VELPLAN_Handle handle)Gets the Current State (CurState) for SpinTAC Velocity Plan.
• static uint16_t STVELPLAN_getCurrentTransition (ST_VELPLAN_Handle handle)Gets the Current Transition (CurTran) for SpinTAC Velocity Plan.
• static ST_PlanFsmState_e STVELPLAN_getFsmState (ST_VELPLAN_Handle handle)Gets the State Machine State (FsmState) for SpinTAC Velocity Plan.
• static int32_t STVELPLAN_getCurrentTimerValue_tick (ST_VELPLAN_Handle handle)Gets the Current Time Value (Timer_tick) for SpinTAC Velocity Plan.
• static uint16_t STVELPLAN_getCfgError (ST_VELPLAN_Handle handle, uint16_t ∗ERR_idx,uint16_t ∗ERR_code)
Gets the Configuration Error for SpinTAC Velocity Plan.• static uint16_t STVELPLAN_getErrorID (ST_VELPLAN_Handle handle)• void STVELPLAN_getCfgStateNum (ST_VELPLAN_Handle handle, uint16_t ∗StateNum)
Returns the number of configured States in SpinTAC Velocity Plan.• void STVELPLAN_getCfgVarNum (ST_VELPLAN_Handle handle, uint16_t ∗VarNum)
Returns the number of configured Variables in SpinTAC Velocity Plan.• void STVELPLAN_getCfgCondNum (ST_VELPLAN_Handle handle, uint16_t ∗CondNum)
Returns the number of configured Conditions in SpinTAC Velocity Plan.• void STVELPLAN_getCfgTranNum (ST_VELPLAN_Handle handle, uint16_t ∗TranNum)
Returns the number of configured Transitions in SpinTAC Velocity Plan.• void STVELPLAN_getCfgActNum (ST_VELPLAN_Handle handle, uint16_t ∗ActNum)
Returns the number of configured Actions in SpinTAC Velocity Plan.• void STVELPLAN_addCfgCond (ST_VELPLAN_Handle handle, uint16_t VarIdx, ST_Plan←↩
Comp_e Comp, _lq24 Value1, _lq24 Value2)Adds a Condition to the SpinTAC Velocity Plan configuration.
• void STVELPLAN_delCfgCond (ST_VELPLAN_Handle handle, uint16_t CondIdx)Deletes a Condition from the SpinTAC Velocity Plan configuration.
• void STVELPLAN_setCfgCond (ST_VELPLAN_Handle handle, uint16_t CondIdx, uint16_t Var←↩Idx, ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2)
Modifies a Condition in the SpinTAC Velocity Plan configuration.• void STVELPLAN_getCfgCond (ST_VELPLAN_Handle handle, uint16_t CondIdx, uint16_←↩
t ∗VarIdx, ST_PlanComp_e ∗Comp, _lq24 ∗Value1, _lq24 ∗Value2)Returns a Condition from the SpinTAC Velocity Plan configuration.
• void STVELPLAN_addCfgVarCond (ST_VELPLAN_Handle handle, uint16_t VarIdx1, uint16_tVarIdx2, ST_PlanComp_e Comp)
Adds a Variable Condition to the SpinTAC Velocity Plan configuration.• void STVELPLAN_delCfgVarCond (ST_VELPLAN_Handle handle, uint16_t CondIdx)
Deletes a Variable Condition from the SpinTAC Velocity Plan configuration.• void STVELPLAN_setCfgVarCond (ST_VELPLAN_Handle handle, uint16_t CondIdx, uint16_t
VarIdx1, uint16_t VarIdx2, ST_PlanComp_e Comp)Modifies a Varaible Condition to the SpinTAC Velocity Plan configuration.
• void STVELPLAN_getCfgVarCond (ST_VELPLAN_Handle handle, uint16_t CondIdx, uint16_t∗VarIdx1, uint16_t ∗VarIdx2, ST_PlanComp_e ∗Comp)
Returns a Variable Condition from the SpinTAC Velocity Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
213
SpinTAC™ Velocity Plan
• void STVELPLAN_addCfgTran (ST_VELPLAN_Handle handle, uint16_t FromState, uint16_←↩t ToState, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, _lq24 AccLim, _lq20JrkLim)
Adds a Transition to the SpinTAC Velocity Plan configuration.• void STVELPLAN_delCfgTran (ST_VELPLAN_Handle handle, uint16_t TranIdx)
Deletes a Transition from the SpinTAC Velocity Plan configuration.• void STVELPLAN_setCfgTran (ST_VELPLAN_Handle handle, uint16_t TranIdx, uint16_t From←↩
State, uint16_t ToState, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, _lq24AccLim, _lq20 JrkLim)
Modifies a Transition in the SpinTAC Velocity Plan configuration.• void STVELPLAN_getCfgTran (ST_VELPLAN_Handle handle, uint16_t TranIdx, uint16_←↩
t ∗FromState, uint16_t ∗ToState, ST_PlanCond_e ∗AndOr, uint16_t ∗CondIdx1, uint16_t ∗Cond←↩Idx2, _lq24 ∗AccLim, _lq20 ∗JrkLim)
Return a Transition from the SpinTAC Velocity Plan configuration.• void STVELPLAN_addCfgAct (ST_VELPLAN_Handle handle, uint16_t State, ST_PlanCond_←↩
e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx, ST_PlanActOptn_e Opt, _lq24Value, ST_PlanActTrgr_e EnterExit)
Adds an action to the SpinTAC Velocity Plan configuration.• void STVELPLAN_delCfgAct (ST_VELPLAN_Handle handle, uint16_t ActIdx)
Deletes an action from the SpinTAC Velocity Plan configuration.• void STVELPLAN_setCfgAct (ST_VELPLAN_Handle handle, uint16_t ActIdx, uint16_t State,
ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx, ST_PlanAct←↩Optn_e Opt, _lq24 Value, ST_PlanActTrgr_e EnterExit)
Modifies an action in the SpinTAC Velocity Plan configuration.• void STVELPLAN_getCfgAct (ST_VELPLAN_Handle handle, uint16_t ActIdx, uint16_t ∗State,
ST_PlanCond_e ∗AndOr, uint16_t ∗CondIdx1, uint16_t ∗CondIdx2, uint16_t ∗VarIdx, ST_Plan←↩ActOptn_e ∗Opt, _lq24 ∗Value, ST_PlanActTrgr_e ∗EnterExit)
Returns an action from the SpinTAC Velocity Plan configuration.• void STVELPLAN_addCfgVar (ST_VELPLAN_Handle handle, ST_PlanVar_e Type, _lq24 Value)
Adds a variable to the SpinTAC Velocity Plan configuration.• void STVELPLAN_delCfgVar (ST_VELPLAN_Handle handle, uint16_t VarIdx)
Deletes a Variable from the SpinTAC Velocity Plan configuration.• void STVELPLAN_setCfgVar (ST_VELPLAN_Handle handle, uint16_t VarIdx, ST_PlanVar_←↩
e Type, _lq24 Value)Modifies a variable in the SpinTAC Velocity Plan configuration.
• void STVELPLAN_getCfgVar (ST_VELPLAN_Handle handle, uint16_t VarIdx, ST_PlanVar_←↩e ∗Type, _lq24 ∗Value)
Returns a variable from the SpinTAC Velocity Plan configuration.• void STVELPLAN_setVar (ST_VELPLAN_Handle handle, uint16_t VarIdx, _lq24 Value)
Sets the value of a SpinTAC Velocity Plan variable.• void STVELPLAN_getVar (ST_VELPLAN_Handle handle, uint16_t VarIdx, _lq24 ∗Value)
Gets the value of a SpinTAC Velocity Plan variable.• void STVELPLAN_setUnitProfDone (ST_VELPLAN_Handle handle, bool ProDON)
Sets a flag in SpinTAC Velocity Plan to indicate if the unit profile is complete.• void STVELPLAN_setCfg (ST_VELPLAN_Handle handle, _lq24 T_sec, bool LoopENB)
Configures SpinTAC Velocity Plan.• void STVELPLAN_getCfg (ST_VELPLAN_Handle handle, _lq24 ∗T_sec, bool ∗LoopENB)
Gets the SpinTAC Velocity Plan configuration.• void STVELPLAN_setCfgHaltState (ST_VELPLAN_Handle handle, _lq24 VelEnd, _lq24 Acc←↩
214Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Lim, _lq20 JrkLim, int32_t Timer_tick)Configures the SpinTAC Velocity Plan Halt state.
• void STVELPLAN_getCfgHaltState (ST_VELPLAN_Handle handle, _lq24 ∗VelEnd, _lq24∗AccLim, _lq20 ∗JrkLim, int32_t ∗Timer_tick)
Gets the SpinTAC Velocity Plan Halt state configuration.• void STVELPLAN_addCfgState (ST_VELPLAN_Handle handle, _lq24 VelEnd, int32_t Timer_←↩
tick)Adds a State to the SpinTAC Velocity Plan configuration.
• void STVELPLAN_delCfgState (ST_VELPLAN_Handle handle, uint16_t StateIdx)Deletes a state from the SpinTAC Velocity Plan configuration.
• void STVELPLAN_setCfgState (ST_VELPLAN_Handle handle, uint16_t StateIdx, _lq24 VelEnd,int32_t Timer_tick)
Modifies a state in the SpinTAC Velocity Plan configuration.• void STVELPLAN_getCfgState (ST_VELPLAN_Handle handle, uint16_t StateIdx, _lq24 ∗Vel←↩
End, int32_t ∗Timer_tick)Returns a state from the SpinTAC Velocity Plan configuration.
• void STVELPLAN_reset (ST_VELPLAN_Handle handle)Resets the Velocity Plan component.
• ST_VELPLAN_Handle STVELPLAN_init (void ∗pMemory, const size_t numBytes)Initializes the SpinTAC Velocity Plan component.
• void STVELPLAN_run (ST_VELPLAN_Handle handle)• void STVELPLAN_runTick (ST_VELPLAN_Handle handle)
Updates the SpinTAC Velocity Plan Timer.• void STVELPLAN_setCfgArray (ST_VELPLAN_Handle handle, uint32_t ∗cfgArray, const size_t
numBytes, uint16_t MaxActNum, uint16_t MaxCondNum, uint16_t MaxVarNum, uint16_t Max←↩TranNum, uint16_t MaxStateNum)
Prepares SpinTAC Velocity Plan configuration array.• static _lq24 STVELCTL_getOutputMaximum (ST_VELCTL_Handle handle)
Gets the Maximum Output (cfg.OutMax) for SpinTAC Velocity Controller.
22.2.2 Data Structure Documentation
22.2.2.1 struct ST_PlanError_t
Defines the ST_PlanError_t data.
The ST_PlanError_t object contains error debugging information for the Position Plan component
Data Fields
uint16_t ERR_code Function specific condition that caused the error. Function specificcondition that caused the error
Freescale SemiconductorKinetis Motor Suite API Reference Manual
215
SpinTAC™ Velocity Plan
uint16_t ERR_idx Plan component index that caused the error. Plan component indexthat caused the error
22.2.2.2 struct ST_VelPlan_t
Data Fields
_lq24 AccLim Acceleration limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
ST_PlanError←↩_t
CfgError Error decoding structure
uint16_t CurState Current state of the state machine
uint16_t CurTran Current transition of the state machine
bool ENB Enable bit { false: disabled; true: enabled }
uint16_t ERR_ID Error ID { 0: no error; others: see error code }
ST_PlanFsm←↩State_e
FsmState State of the state machine
_lq20 JrkLim Jerk Limit { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
bool RES Reset bit { false: not reset; true: reset }
uint32_t s0[26]
ST_Plan←↩Status_e
STATUS Plan status { ST_PLAN_IDLE, ST_PLAN_INIT, ST_PLAN_B←↩USY, ST_PLAN_HALT, ST_PLAN_WAIT}
int32_t Timer_tick State Timer { unit: [tick] }
_lq24 VelEnd Velocity setpoint { unit: [pu rpm], value range: [-1.0, 1.0] }
216Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
22.2.3 Macro Definition Documentation
22.2.3.1 #define __ST_PLAN_ENUM__
22.2.3.2 #define __ST_PLAN_ERROR__
22.2.3.3 #define ST_VEL_PLAN_ACT_DWORDS (5)
22.2.3.4 #define ST_VEL_PLAN_COND_DWORDS (3)
22.2.3.5 #define ST_VEL_PLAN_STATE_DWORDS (6)
22.2.3.6 #define ST_VEL_PLAN_TRAN_DWORDS (5)
22.2.3.7 #define ST_VEL_PLAN_VAR_DWORDS (2)
22.2.4 Typedef Documentation
22.2.4.1 typedef struct _ST_VELPLAN_Handle_∗ ST_VELPLAN_Handle
22.2.5 Enumeration Type Documentation
22.2.5.1 enum ST_PlanActOptn_e
Enumerator
ST_ACT_EQ Action will set the variable equal to a value.ST_ACT_ADD Action will add a value to the variable.ST_ACT_EQ Action will set the variable equal to a valueST_ACT_ADD Action will add a value to the variable
22.2.5.2 enum ST_PlanActTrgr_e
Enumerator
ST_ACT_ENTR Action will be considered when entering the state.ST_ACT_EXIT Action will be considered when exiting the state.ST_ACT_ENTR Action will be considered when entering the stateST_ACT_EXIT Action will be considered when exiting the state
Freescale SemiconductorKinetis Motor Suite API Reference Manual
217
SpinTAC™ Velocity Plan
22.2.5.3 enum ST_PlanComp_e
Enumerator
ST_COMP_NA No comparison.ST_COMP_EQ Compares, VarIdx == Value1 OR VarIdx1 == VarIdx2.ST_COMP_NEQ Compares, VarIdx != Value1 OR VarIdx1 != VarIdx2.ST_COMP_GT Compares, VarIdx > Value1 OR VarIdx1 > VarIdx2.ST_COMP_EGT Compares, VarIdx >= Value1 OR VarIdx1 >= VarIdx2.ST_COMP_LW Compares, VarIdx < Value1 OR VarIdx1 < VarIdx2.ST_COMP_ELW Compares, VarIdx <= Value1 OR VarIdx1 <= VarIdx2.ST_COMP_In Compares, Value1 <= VarIdx <= Value2.ST_COMP_EIn Compares, Value1 < VarIdx <= Value2.ST_COMP_InE Compares, Value1 <= VarIdx < Value2.ST_COMP_EInE Compares, Value1 < VarIdx < Value2.ST_COMP_Out Compares, Value1 >= VarIdx >= Value2.ST_COMP_EOut Compares, Value1 > VarIdx >= Value2.ST_COMP_OutE Compares, Value1 >= VarIdx > Value2.ST_COMP_EOutE Compares, Value1 > VarIdx > Value2.ST_COMP_NA No comparisonST_COMP_EQ Compares, VarIdx == Value1 OR VarIdx1 == VarIdx2ST_COMP_NEQ Compares, VarIdx != Value1 OR VarIdx1 != VarIdx2ST_COMP_GT Compares, VarIdx > Value1 OR VarIdx1 > VarIdx2ST_COMP_EGT Compares, VarIdx >= Value1 OR VarIdx1 >= VarIdx2ST_COMP_LW Compares, VarIdx < Value1 OR VarIdx1 < VarIdx2ST_COMP_ELW Compares, VarIdx <= Value1 OR VarIdx1 <= VarIdx2ST_COMP_In Compares, Value1 <= VarIdx <= Value2ST_COMP_EIn Compares, Value1 < VarIdx <= Value2ST_COMP_InE Compares, Value1 <= VarIdx < Value2ST_COMP_EInE Compares, Value1 < VarIdx < Value2ST_COMP_Out Compares, Value1 >= VarIdx >= Value2ST_COMP_EOut Compares, Value1 > VarIdx >= Value2ST_COMP_OutE Compares, Value1 >= VarIdx > Value2ST_COMP_EOutE Compares, Value1 > VarIdx > Value2
22.2.5.4 enum ST_PlanCond_e
Enumerator
ST_COND_NC Transition/Action with no conditions satisfied.ST_COND_FC Transition/Action with first condition satisfied.ST_COND_AND Transition/Action with both conditions satisfied.ST_COND_OR Transition/Action with either condition satisfied.ST_COND_NC Transition/Action with no conditions satisfiedST_COND_FC Transition/Action with first condition satisfied
218Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
ST_COND_AND Transition/Action with both conditions satisfiedST_COND_OR Transition/Action with either condition satisfied
22.2.5.5 enum ST_PlanFsmState_e
Enumerator
ST_FSM_STATE_STAY Plan is staying in a state until the timer is up.ST_FSM_STATE_COND Plan is waiting for a transition condition to be true.ST_FSM_STATE_TRAN Plan is in transition with a motion profile.ST_FSM_STATE_STAY Plan is staying in a state until the timer is upST_FSM_STATE_COND Plan is waiting for a transition condition to be trueST_FSM_STATE_TRAN Plan is in transition with a motion profile
22.2.5.6 enum ST_PlanStatus_e
Enumerator
ST_PLAN_IDLE idle state, holding positionST_PLAN_INIT init state, initialize internal statesST_PLAN_BUSY busy state, running state machineST_PLAN_HALT halt state, return to the position reference in idle stateST_PLAN_WAIT wait state, holding the position reference in idle stateST_PLAN_IDLE idle state, holding velocityST_PLAN_INIT init state, initialize internal statesST_PLAN_BUSY busy state, running state machineST_PLAN_HALT halt state, return to the speed reference in idle stateST_PLAN_WAIT wait state, holding the speed reference in idle state
22.2.5.7 enum ST_PlanVar_e
Enumerator
ST_VAR_INOUT Variable type input/output.ST_VAR_IN Variable type input.ST_VAR_OUT Variable type output.ST_VAR_INOUT Variable type input/outputST_VAR_IN Variable type inputST_VAR_OUT Variable type output
Freescale SemiconductorKinetis Motor Suite API Reference Manual
219
SpinTAC™ Velocity Plan
22.2.5.8 enum ST_VelPlan_ErrorCode_e
Enumeration for the Velocity Plan Error Codes.
Enumerator
No_ErrorCode No error codePlan_running Cannot change config while Plan is runningMax_States_exceed Maximum number of States exceededMax_Cond_exceed Maximum number of Conditions exceededMax_Trans_exceed Maximum number of Transitions exceededMax_Act_exceed Maximum number of Actions exceededMax_Var_exceed Maximum number of Variables exceededInvalid_Sampletime Sample Time is out of rangeInvalid_LoopENB Loop Enable is out of rangeInvalid_HaltAccLim Acceleration Limit is out of rangeInvalid_HaltJrkLim Jerk Limit is out of rangeInvalid_Timer_tick State Timer is out of rangeInvalid_State_index State Index is greater than Maximum number of StatesInvalid_Condition_index Condition Index is greater than Maximum number of ConditionsInvalid_Trans_index Transition Index is greater than Maximum number of TransitionsInvalid_Action_index Action Index is greater than Maximum number of ActionsInvalid_Var_index Varaible Index is greater than Maximum number of VariablesInvalid_Var_type Variable Type is out of rangeInvalid_Value_Comp Value Comparison is out of rangeInvalid_Operation Action Operation is out of rangeInvalid_AndOr And/Or Selection is out of rangeImproper_Var_type Indicated Variable cannot be used for this operationImproper_Val_Comparison With a multiple value comparison, Value 1 must be < Value 2Improper_State_index Maximum number of States exceeded OR From State cannot be equal to To
StateImproper_Cond_Idx Maximum number of Conditions exceeded OR Condition 1 cannot be equal to
Condition 2Improper_EnterExit Enter/Exit Selection is out of rangeCannot_delete_Var_Cond Variable is used by a ConditionCannot_delete_Var_Act Variable is used by an ActionPlanCfg_array_Small Plan Configuration Array is not large enoughCannot_delete_State_Tran State is used by a TransitionCannot_delete_State_Act State is used by an ActionInvalid_Var_Compare Cannot select range comparisonInvalid_Var_indexes Variable 1 cannot be equal to Variable 2Invalid_Cond_Index Wrong type of Condition specifiedCannot_Delete_Cond_Tran Condition is used by a TransitionCannot_Delete_Cond_Act Condition is used by an Action
220Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
22.2.5.9 enum ST_VelPlan_ErrorId_e
Enumeration for the Velocity Plan Error Id, indicates the function which caused the error.
Enumerator
No_ErrorId No error idError_STVELPLAN_addCfgCondError_STVELPLAN_delCfgCondError_STVELPLAN_setCfgCondError_STVELPLAN_getCfgCondError_STVELPLAN_addCfgTranError_STVELPLAN_delCfgTranError_STVELPLAN_setCfgTranError_STVELPLAN_getCfgTranError_STVELPLAN_addCfgActError_STVELPLAN_delCfgActError_STVELPLAN_setCfgActError_STVELPLAN_getCfgActError_STVELPLAN_addCfgVarError_STVELPLAN_delCfgVarError_STVELPLAN_setCfgVarError_STVELPLAN_getCfgVarError_STVELPLAN_addCfgStateError_STVELPLAN_delCfgStateError_STVELPLAN_setCfgStateError_STVELPLAN_setVarError_STVELPLAN_getVarError_STVELPLAN_setCfgError_STVELPLAN_setCfgHaltStateError_STVELPLAN_setCfgArrayError_STVELPLAN_addCfgVarCondError_STVELPLAN_delCfgVarCondError_STVELPLAN_setCfgVarCondError_STVELPLAN_getCfgVarCondInvalid_STLicenseInvalid_RomVersion
22.2.6 Function Documentation
22.2.6.1 STVELCTL_getOutputMaximum ( ST_VELCTL_Handle handle ) [inline],[static]
Gets the Maximum Output (cfg.OutMax) for SpinTAC Velocity Controller.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
221
SpinTAC™ Velocity Plan
Runs SpinTAC Velocity Plan calculation.
Gets the Error ID for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Controller Object
Returns
_lq24 - OutMax Control signal upper limit { unit: [pu amps], value range: [-1.0, 1.0] }
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
uint16_t - ERR_ID Error ID { 0: no error; others: see error code }
Parameters
handle - The handle for the Velocity Plan structure
Returns
none
References ST_VelCtl_t::cfg, and ST_VelCtlCfg_t::OutMax.
22.2.6.2 STVELPLAN_addCfgAct ( ST_VELPLAN_Handle handle, uint16_t State,ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx,ST_PlanActOptn_e Opt, _lq24 Value, ST_PlanActTrgr_e EnterExit )
Adds an action to the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
222Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
State - Index of the State the Action happens in
AndOr - Condition option for the Action
CondIdx1 - Index of the first Condition to consider for the Action
CondIdx2 - Index of the second Condition to consider for the Action
VarIdx - Index of the Varaible to be acted upon
Opt - Type of Action to perform on the Varaible
Value - Value to use in the Action
EnterExit - State event that will trigger the Action
Returns
none
22.2.6.3 STVELPLAN_addCfgCond ( ST_VELPLAN_Handle handle, uint16_t VarIdx,ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2 )
Adds a Condition to the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Plan Variable that will be compared
Comp - Type of comparison that will be done
Value1 - First value to use in the comparison
Value2 - Second value to use in the comparison
Returns
none
22.2.6.4 STVELPLAN_addCfgState ( ST_VELPLAN_Handle handle, _lq24 VelEnd,int32_t Timer_tick )
Adds a State to the SpinTAC Velocity Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
223
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VelEnd - Velocity setpoint for State { unit: [pu rpm], value range: [-1.0, 1.0] }
Timer_tick - Minimum time to stay in State { unit: [tick] }
Returns
none
22.2.6.5 STVELPLAN_addCfgTran ( ST_VELPLAN_Handle handle, uint16_t FromState,uint16_t ToState, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_tCondIdx2, _lq24 AccLim, _lq20 JrkLim )
Adds a Transition to the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
FromState - Index of the from State
ToState - Index of the to State
AndOr - Condition option for the Transition
CondIdx1 - Index of the first Condition to consider for the Transition
CondIdx2 - Index of the second Condition to consider for the Transition
AccLim - Acceleration limit for the Transition { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
JrkLim - Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
Returns
none
22.2.6.6 STVELPLAN_addCfgVar ( ST_VELPLAN_Handle handle, ST_PlanVar_e Type,_lq24 Value )
Adds a variable to the SpinTAC Velocity Plan configuration.
224Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Type - Type of Variable
Value - Initial value of the Variable
Returns
none
22.2.6.7 STVELPLAN_addCfgVarCond ( ST_VELPLAN_Handle handle, uint16_t VarIdx1,uint16_t VarIdx2, ST_PlanComp_e Comp )
Adds a Variable Condition to the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx1 - Index of the first Plan Variable that will be compared
VarIdx2 - Index of the second Plan Variable that will be compared
Comp - Type of comparison that will be done
Returns
none
22.2.6.8 STVELPLAN_delCfgAct ( ST_VELPLAN_Handle handle, uint16_t ActIdx )
Deletes an action from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
ActIdx - Index of the Action to delete
Returns
none
22.2.6.9 STVELPLAN_delCfgCond ( ST_VELPLAN_Handle handle, uint16_t CondIdx )
Deletes a Condition from the SpinTAC Velocity Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
225
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to delete
Returns
none
22.2.6.10 STVELPLAN_delCfgState ( ST_VELPLAN_Handle handle, uint16_t StateIdx )
Deletes a state from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
StateIdx - Index of the State to delete
Returns
none
22.2.6.11 STVELPLAN_delCfgTran ( ST_VELPLAN_Handle handle, uint16_t TranIdx )
Deletes a Transition from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
TranIdx - Index of the Transition to delete
Returns
none
22.2.6.12 STVELPLAN_delCfgVar ( ST_VELPLAN_Handle handle, uint16_t VarIdx )
Deletes a Variable from the SpinTAC Velocity Plan configuration.
226Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Variable to delete
Returns
none
22.2.6.13 STVELPLAN_delCfgVarCond ( ST_VELPLAN_Handle handle, uint16_tCondIdx )
Deletes a Variable Condition from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to delete
Returns
none
22.2.6.14 STVELPLAN_getAccelerationLimit ( ST_VELPLAN_Handle handle )[inline], [static]
Gets the Acceleration Limit (AccLim) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
_lq24 - AccLim Acceleration limit { unit: [(pu rpm)/s], value range: [0.001, 120.0] }
References ST_VelPlan_t::AccLim.
Referenced by USER_runPlanState().
22.2.6.15 STVELPLAN_getCfg ( ST_VELPLAN_Handle handle, _lq24 ∗ T_sec, bool ∗LoopENB )
Gets the SpinTAC Velocity Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
227
SpinTAC™ Velocity Plan
Parameters
handle - handle The handle for the SpinTAC Velocity Plan Object
∗T - Sample Time { unit: [sec], value range: (0, 0.01] }
∗LoopENB - Sets if SpinTAC Velocity Plan should continuously run after it reaches the end {false: Do not continuously run Plan; true: Continuously run Plan }
Returns
none
22.2.6.16 STVELPLAN_getCfgAct ( ST_VELPLAN_Handle handle, uint16_t ActIdx,uint16_t ∗ State, ST_PlanCond_e ∗ AndOr, uint16_t ∗ CondIdx1, uint16_t∗ CondIdx2, uint16_t ∗ VarIdx, ST_PlanActOptn_e ∗ Opt, _lq24 ∗ Value,ST_PlanActTrgr_e ∗ EnterExit )
Returns an action from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
ActIdx - Index of the Action to modify
∗State - Index of the State the Action happens in
∗AndOr - Condition option for the Action
∗CondIdx1 - Index of the first Condition to consider for the Action
∗CondIdx2 - Index of the second Condition to consider for the Action
∗VarIdx - Index of the Varaible to be acted upon
∗Opt - Type of Action to perform on the Varaible
∗Value - Value to use in the Action
∗EnterExit - State event that will trigger the Action
Returns
none
22.2.6.17 STVELPLAN_getCfgActNum ( ST_VELPLAN_Handle handle, uint16_t ∗ActNum )
Returns the number of configured Actions in SpinTAC Velocity Plan.
228Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗ActNum - The number of configured Actions in SpinTAC Velocity Plan
Returns
none
22.2.6.18 STVELPLAN_getCfgCond ( ST_VELPLAN_Handle handle, uint16_t CondIdx,uint16_t ∗ VarIdx, ST_PlanComp_e ∗ Comp, _lq24 ∗ Value1, _lq24 ∗ Value2 )
Returns a Condition from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to return
∗VarIdx - Index of the Plan Variable that will be compared
∗Comp - Type of comparison that will be done
∗Value1 - First value to use in the comparison
∗Value2 - Second value to use in the comparison
Returns
none
22.2.6.19 STVELPLAN_getCfgCondNum ( ST_VELPLAN_Handle handle, uint16_t ∗CondNum )
Returns the number of configured Conditions in SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Freescale SemiconductorKinetis Motor Suite API Reference Manual
229
SpinTAC™ Velocity Plan
∗CondNum - The number of configured Conditions in SpinTAC Velocity Plan
Returns
none
22.2.6.20 STVELPLAN_getCfgError ( ST_VELPLAN_Handle handle, uint16_t ∗ ERR_idx,uint16_t ∗ ERR_code ) [inline], [static]
Gets the Configuration Error for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗ERR_idx - Component index where error occurred { 0: no index; others: see error code }
∗ERR_code - Specific configuration error { 0: no additional information; others: see error code }
Returns
uint16_t ERR_ID Error ID { 0: no error; others: see error code }
References ST_VelPlan_t::CfgError, ST_PlanError_t::ERR_code, ST_VelPlan_t::ERR_ID, and ST_←↩PlanError_t::ERR_idx.
22.2.6.21 STVELPLAN_getCfgHaltState ( ST_VELPLAN_Handle handle, _lq24 ∗ VelEnd,_lq24 ∗ AccLim, _lq20 ∗ JrkLim, int32_t ∗ Timer_tick )
Gets the SpinTAC Velocity Plan Halt state configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗VelEnd - Velocity setpoint during Halt state { unit: [pu rpm], value range: [-1.0, 1.0] }
∗AccLim - Acceleration limit for Halt state { unit: [(pu rpm)/s], value range: [0.001, 120.0] }
∗JrkLim - Jerk limit for Halt state { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
230Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
∗Timer_tick - Minimum amount of time to stay in Halt state { unit: [tick] }
Returns
none
22.2.6.22 STVELPLAN_getCfgState ( ST_VELPLAN_Handle handle, uint16_t StateIdx,_lq24 ∗ VelEnd, int32_t ∗ Timer_tick )
Returns a state from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
StateIdx - Index of the State to modify
∗VelEnd - Velocity setpoint for State { unit: [pu rpm], value range: [-1.0, 1.0] }
∗Timer_tick - Minimum time to stay in State { unit: [tick] }
Returns
none
22.2.6.23 STVELPLAN_getCfgStateNum ( ST_VELPLAN_Handle handle, uint16_t ∗StateNum )
Returns the number of configured States in SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗StateNum - The number of configured States in SpinTAC Velocity Plan
Returns
none
22.2.6.24 STVELPLAN_getCfgTran ( ST_VELPLAN_Handle handle, uint16_t TranIdx,uint16_t ∗ FromState, uint16_t ∗ ToState, ST_PlanCond_e ∗ AndOr, uint16_t ∗CondIdx1, uint16_t ∗ CondIdx2, _lq24 ∗ AccLim, _lq20 ∗ JrkLim )
Return a Transition from the SpinTAC Velocity Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
231
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
TranIdx - Index of the Transition to modify
∗FromState - Index of the from State
∗ToState - Index of the to State
∗AndOr - Condition option for the Transition
∗CondIdx1 - Index of the first Condition to consider for the Transition
∗CondIdx2 - Index of the second Condition to consider for the Transition
∗AccLim - Acceleration limit for the Transition { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
∗JrkLim - Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
Returns
none
22.2.6.25 STVELPLAN_getCfgTranNum ( ST_VELPLAN_Handle handle, uint16_t ∗TranNum )
Returns the number of configured Transitions in SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗TranNum - The number of configured Transitions in SpinTAC Velocity Plan
Returns
none
22.2.6.26 STVELPLAN_getCfgVar ( ST_VELPLAN_Handle handle, uint16_t VarIdx,ST_PlanVar_e ∗ Type, _lq24 ∗ Value )
Returns a variable from the SpinTAC Velocity Plan configuration.
232Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Variable to return
∗Type - Type of Variable
∗Value - Initial value of the Variable
Returns
none
22.2.6.27 STVELPLAN_getCfgVarCond ( ST_VELPLAN_Handle handle, uint16_tCondIdx, uint16_t ∗ VarIdx1, uint16_t ∗ VarIdx2, ST_PlanComp_e ∗ Comp )
Returns a Variable Condition from the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to return
∗VarIdx1 - Index of the first Plan Variable that will be compared
∗VarIdx2 - Index of the second Plan Variable that will be compared
∗Comp - Type of comparison that will be done
Returns
none
22.2.6.28 STVELPLAN_getCfgVarNum ( ST_VELPLAN_Handle handle, uint16_t ∗VarNum )
Returns the number of configured Variables in SpinTAC Velocity Plan.
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
233
SpinTAC™ Velocity Plan
handle - The handle for the SpinTAC Velocity Plan Object
∗VarNum - The number of configured Variables in SpinTAC Velocity Plan
Returns
none
22.2.6.29 STVELPLAN_getCurrentState ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the Current State (CurState) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
uint16_t - CurState Current state of the state machine
References ST_VelPlan_t::CurState.
22.2.6.30 STVELPLAN_getCurrentTimerValue_tick ( ST_VELPLAN_Handle handle )[inline], [static]
Gets the Current Time Value (Timer_tick) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
int32_t - Timer_tick State Timer { unit: [tick] }
References ST_VelPlan_t::Timer_tick.
22.2.6.31 STVELPLAN_getCurrentTransition ( ST_VELPLAN_Handle handle )[inline], [static]
Gets the Current Transition (CurTran) for SpinTAC Velocity Plan.
234Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
uint16_t - CurTran Current transition of the state machine
References ST_VelPlan_t::CurTran.
22.2.6.32 STVELPLAN_getEnable ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the Enable signal (ENB) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
bool - EN B Enable bit { false: disable; true: enable }
References ST_VelPlan_t::ENB.
22.2.6.33 static uint16_t STVELPLAN_getErrorID ( ST_VELPLAN_Handle handle )[inline], [static]
References ST_VelPlan_t::ERR_ID.
22.2.6.34 STVELPLAN_getFsmState ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the State Machine State (FsmState) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
ST_PlanFsmState_e - FsmState Current operation of the state machine
References ST_VelPlan_t::FsmState.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
235
SpinTAC™ Velocity Plan
22.2.6.35 STVELPLAN_getJerkLimit ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the Jerk Limit (JrkLim) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
_lq20 - JrkLim Jerk Limit { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
References ST_VelPlan_t::JrkLim.
Referenced by USER_runPlanState().
22.2.6.36 STVELPLAN_getReset ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the Reset signal (RES) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
bool - RES Reset bit { false: reset; true: not reset }
References ST_VelPlan_t::RES.
22.2.6.37 STVELPLAN_getStatus ( ST_VELPLAN_Handle handle ) [inline],[static]
Gets the Status value (STATUS) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
ST_PlanStatus_e - STATUS Status { ST_VEL_ID_IDLE, ST_VEL_ID_INIT, ST_VEL_ID_BUSY}
References ST_VelPlan_t::STATUS.
Referenced by USER_runPlanState().
236Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
22.2.6.38 STVELPLAN_getVar ( ST_VELPLAN_Handle handle, uint16_t VarIdx, _lq24 ∗Value )
Gets the value of a SpinTAC Velocity Plan variable.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Variable to get
∗Value - Value to get from the Variable
Returns
none
22.2.6.39 STVELPLAN_getVelocitySetpoint ( ST_VELPLAN_Handle handle )[inline], [static]
Gets the Velocity Setpoint (VelEnd) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
_lq24 - VelEnd Velocity setpoint { unit: [pu rpm], value range: [-1.0, 1.0] }
References ST_VelPlan_t::VelEnd.
Referenced by USER_runPlanState().
22.2.6.40 STVELPLAN_init ( void ∗ pMemory, const size_t numBytes )
Initializes the SpinTAC Velocity Plan component.
Parameters
∗pMemory - Pointer to the memory for ST_VelPlan_t
Freescale SemiconductorKinetis Motor Suite API Reference Manual
237
SpinTAC™ Velocity Plan
numBytes - The number of bytes in the ST_VelPlan_t
Returns
ST_VELPLAN_Handle - handle The handle for the SpinTAC Velocity Plan Object
22.2.6.41 STVELPLAN_reset ( ST_VELPLAN_Handle handle )
Resets the Velocity Plan component.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
none
Referenced by USER_OnExit().
22.2.6.42 void STVELPLAN_run ( ST_VELPLAN_Handle handle )
Referenced by USER_runPlanState().
22.2.6.43 STVELPLAN_runTick ( ST_VELPLAN_Handle handle )
Updates the SpinTAC Velocity Plan Timer.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
Returns
none
Referenced by USER_runPlanState().
22.2.6.44 STVELPLAN_setCfg ( ST_VELPLAN_Handle handle, _lq24 T_sec, boolLoopENB )
Configures SpinTAC Velocity Plan.
238Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
T - Sample Time { unit: [sec], value range: (0, 0.01] }
LoopENB - Sets if SpinTAC Velocity Plan should continuously run after it reaches the end {false: Do not continuously run Plan; true: Continuously run Plan }
Returns
none
22.2.6.45 void STVELPLAN_setCfgAct ( ST_VELPLAN_Handle handle, uint16_t ActIdx,uint16_t State, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2,uint16_t VarIdx, ST_PlanActOptn_e Opt, _lq24 Value, ST_PlanActTrgr_eEnterExit )
Modifies an action in the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
ActIdx - Index of the Action to modify
State - Index of the State the Action happens in
AndOr - Condition option for the Action
CondIdx1 - Index of the first Condition to consider for the Action
CondIdx2 - Index of the second Condition to consider for the Action
VarIdx - Index of the Varaible to be acted upon
Opt - Type of Action to perform on the Varaible
Value - Value to use in the Action
EnterExit - State event that will trigger the Action
Returns
none
22.2.6.46 STVELPLAN_setCfgArray ( ST_VELPLAN_Handle handle, uint32_t ∗ cfgArray,const size_t numBytes, uint16_t MaxActNum, uint16_t MaxCondNum, uint16_tMaxVarNum, uint16_t MaxTranNum, uint16_t MaxStateNum )
Prepares SpinTAC Velocity Plan configuration array.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
239
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
∗cfgArray - Pointer to the SpinTAC Velocity Plan configuration array
numBytes - The number of bytes in the SpinTAC Velocity Plan configuration array
MaxActNum - Number of Actions
MaxCondNum - Number of Conditions
MaxVarNum - Number of Variables
MaxTranNum - Number of Transitions
MaxStateNum - Number of States
Returns
none
22.2.6.47 STVELPLAN_setCfgCond ( ST_VELPLAN_Handle handle, uint16_t CondIdx,uint16_t VarIdx, ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2 )
Modifies a Condition in the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to modify
VarIdx - Index of the Plan Variable that will be compared
Comp - Type of comparison that will be done
Value1 - First value to use in the comparison
Value2 - Second value to use in the comparison
Returns
22.2.6.48 STVELPLAN_setCfgHaltState ( ST_VELPLAN_Handle handle, _lq24 VelEnd,_lq24 AccLim, _lq20 JrkLim, int32_t Timer_tick )
Configures the SpinTAC Velocity Plan Halt state.
240Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VelEnd - Velocity setpoint during Halt state { unit: [pu rpm], value range: [-1.0, 1.0] }
AccLim - Acceleration limit for Halt state { unit: [(pu rpm)/s], value range: [0.001, 120.0] }
JrkLim - Jerk limit for Halt state { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
Timer_tick - Minimum amount of time to stay in Halt state { unit: [tick] }
Returns
none
22.2.6.49 STVELPLAN_setCfgState ( ST_VELPLAN_Handle handle, uint16_t StateIdx,_lq24 VelEnd, int32_t Timer_tick )
Modifies a state in the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
StateIdx - Index of the State to modify
VelEnd - Velocity setpoint for State { unit: [pu rpm], value range: [-1.0, 1.0] }
Timer_tick - Minimum time to stay in State { unit: [tick] }
Returns
none
22.2.6.50 STVELPLAN_setCfgTran ( ST_VELPLAN_Handle handle, uint16_t TranIdx,uint16_t FromState, uint16_t ToState, ST_PlanCond_e AndOr, uint16_tCondIdx1, uint16_t CondIdx2, _lq24 AccLim, _lq20 JrkLim )
Modifies a Transition in the SpinTAC Velocity Plan configuration.
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
241
SpinTAC™ Velocity Plan
handle - The handle for the SpinTAC Velocity Plan Object
TranIdx - Index of the Transition to modify
FromState - Index of the from State
ToState - Index of the to State
AndOr - Condition option for the Transition
CondIdx1 - Index of the first Condition to consider for the Transition
CondIdx2 - Index of the second Condition to consider for the Transition
AccLim - Acceleration limit for the Transition { unit: [(pu rpm)/s], value range: [0.001, 120.0]}
JrkLim - Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }
Returns
none
22.2.6.51 STVELPLAN_setCfgVar ( ST_VELPLAN_Handle handle, uint16_t VarIdx,ST_PlanVar_e Type, _lq24 Value )
Modifies a variable in the SpinTAC Velocity Plan configuration.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Variable to modify
Type - Type of Variable
Value - Initial value of the Variable
Returns
none
22.2.6.52 STVELPLAN_setCfgVarCond ( ST_VELPLAN_Handle handle, uint16_tCondIdx, uint16_t VarIdx1, uint16_t VarIdx2, ST_PlanComp_e Comp )
Modifies a Varaible Condition to the SpinTAC Velocity Plan configuration.
242Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Velocity Plan
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
CondIdx - Index of the Plan Condition to modify
VarIdx1 - Index of the first Plan Variable that will be compared
VarIdx2 - Index of the second Plan Variable that will be compared
Comp - Type of comparison that will be done
Returns
none
22.2.6.53 STVELPLAN_setEnable ( ST_VELPLAN_Handle handle, bool enb )[inline], [static]
Sets the Enable signal (ENB) for SpinTAC Velocity Plan.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
enb - Enable bit { false: disable; true: enable }
Returns
none
References ST_VelPlan_t::ENB.
Referenced by USER_onEntryPlan().
22.2.6.54 STVELPLAN_setReset ( ST_VELPLAN_Handle handle, bool res )[inline], [static]
Sets the Reset signal (RES) for SpinTAC Velocity Plan.
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
243
SpinTAC™ Velocity Plan
handle - The handle for the SpinTAC Velocity Plan Object
res - Reset bit { false: reset; true: not reset }
Returns
none
References ST_VelPlan_t::RES.
Referenced by USER_onEntryPlan().
22.2.6.55 STVELPLAN_setUnitProfDone ( ST_VELPLAN_Handle handle, bool ProDON )
Sets a flag in SpinTAC Velocity Plan to indicate if the unit profile is complete.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
ProDON - Indicates if the unit profile is completed
Returns
none
Referenced by USER_runPlanState().
22.2.6.56 STVELPLAN_setVar ( ST_VELPLAN_Handle handle, uint16_t VarIdx, _lq24Value )
Sets the value of a SpinTAC Velocity Plan variable.
Parameters
handle - The handle for the SpinTAC Velocity Plan Object
VarIdx - Index of the Variable to set
Value - Value to set to the Variable
Returns
none
244Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
22.3 SpinTAC™ Position Plan
22.3.1 Overview
SpinTAC™ Position Plan is the code infrastructure for Motion Sequence Builder for position controlapplications.
Data Structures
• struct ST_PlanError_tDefines the ST_PlanError_t data. More...
• struct ST_PosPlan_tDefines the ST_PosPlan_t data. More...
Macros
• #define ST_POS_PLAN_ACT_DWORDS (5)Defines the amount of memory that needs to be allocated for each component.
• #define ST_POS_PLAN_COND_DWORDS (3)Each configured Condition takes 3 double words of memory.
• #define ST_POS_PLAN_VAR_DWORDS (2)Each configured Variable takes 2 double words of memory.
• #define ST_POS_PLAN_TRAN_DWORDS (7)Each configured Transition takes 7 double words of memory.
• #define ST_POS_PLAN_STATE_DWORDS (7)Each configured State takes 7 double words of memory.
• #define __ST_PLAN_ENUM__• #define __ST_PLAN_ERROR__
Typedefs
• typedef ST_PosPlan_t ∗ ST_POSPLAN_Handle
Freescale SemiconductorKinetis Motor Suite API Reference Manual
245
SpinTAC™ Position Plan
Enumerations
• enum ST_PlanStatus_e {ST_PLAN_IDLE =0,ST_PLAN_INIT,ST_PLAN_BUSY,ST_PLAN_HALT,ST_PLAN_WAIT,ST_PLAN_IDLE =0,ST_PLAN_INIT,ST_PLAN_BUSY,ST_PLAN_HALT,ST_PLAN_WAIT }
Enumeration for the Plan Status States.• enum ST_PlanCond_e {
ST_COND_NC =0,ST_COND_FC,ST_COND_AND,ST_COND_OR,ST_COND_NC =0,ST_COND_FC,ST_COND_AND,ST_COND_OR }
Enumeration for the Plan Condition options.• enum ST_PlanComp_e {
246Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
ST_COMP_NA =0,ST_COMP_EQ,ST_COMP_NEQ,ST_COMP_GT,ST_COMP_EGT,ST_COMP_LW,ST_COMP_ELW,ST_COMP_In,ST_COMP_EIn,ST_COMP_InE,ST_COMP_EInE,ST_COMP_Out,ST_COMP_EOut,ST_COMP_OutE,ST_COMP_EOutE,ST_COMP_NA =0,ST_COMP_EQ,ST_COMP_NEQ,ST_COMP_GT,ST_COMP_EGT,ST_COMP_LW,ST_COMP_ELW,ST_COMP_In,ST_COMP_EIn,ST_COMP_InE,ST_COMP_EInE,ST_COMP_Out,ST_COMP_EOut,ST_COMP_OutE,ST_COMP_EOutE }
Enumeration for the Plan Compare options.• enum ST_PlanActOptn_e {
ST_ACT_EQ =0,ST_ACT_ADD,ST_ACT_EQ =0,ST_ACT_ADD }
Enumeration for the Plan Action Options.• enum ST_PlanActTrgr_e {
ST_ACT_ENTR =0,ST_ACT_EXIT,ST_ACT_ENTR =0,ST_ACT_EXIT }
Enumeration for the Plan Action trigger point types.• enum ST_PlanFsmState_e {
Freescale SemiconductorKinetis Motor Suite API Reference Manual
247
SpinTAC™ Position Plan
ST_FSM_STATE_STAY =0,ST_FSM_STATE_COND,ST_FSM_STATE_TRAN,ST_FSM_STATE_STAY =0,ST_FSM_STATE_COND,ST_FSM_STATE_TRAN }
Enumeration for the Plan FSM states.• enum ST_PlanVar_e {
ST_VAR_INOUT =0,ST_VAR_IN,ST_VAR_OUT,ST_VAR_INOUT =0,ST_VAR_IN,ST_VAR_OUT }
Enumeration for the Plan variable types.• enum ST_PosPlan_ErrorCode_e {
248Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
No_ErrorCode = 0,Plan_running = 1,Max_States_exceed = 2,Max_Cond_exceed = 3,Max_Trans_exceed = 4,Max_Act_exceed = 5,Max_Var_exceed = 6,Invalid_Sampletime = 7,Invalid_LoopENB = 11,Invalid_HaltAccLim = 13,Invalid_HaltJrkLim = 14,Invalid_Timer_tick = 15,Invalid_State_index = 16,Invalid_Condition_index = 17,Invalid_Trans_index = 18,Invalid_Action_index = 19,Invalid_Var_index = 20,Invalid_Var_type = 21,Invalid_Value_Comp = 22,Invalid_Operation = 23,Invalid_AndOr = 24,Improper_Var_type = 25,Improper_Val_Comparison = 26,Improper_State_index = 27,Improper_Cond_Idx = 28,Improper_EnterExit = 29,Cannot_delete_Var_Cond = 30,Cannot_delete_Var_Act = 31,Invalid_HaltVelLim = 32,Invalid_HaltDecLim = 32,Invalid_PosStep = 35,PlanCfg_array_Small = 37,Cannot_delete_State_Tran = 38,Cannot_delete_State_Act = 39,Invalid_Var_Compare = 40,Invalid_Var_indexes = 41,Invalid_Cond_Index = 42,Cannot_Delete_Cond_Tran = 43,Invalid_InitState_Step = 44,Cannot_Delete_Cond_Act = 45 }
Enumeration for the Position Plan Error Codes.• enum ST_PosPlan_ErrorId_e {
Freescale SemiconductorKinetis Motor Suite API Reference Manual
249
SpinTAC™ Position Plan
No_ErrorId = 0,Error_STPOSPLAN_addCfgCond = 3000,Error_STPOSPLAN_delCfgCond = 3001,Error_STPOSPLAN_setCfgCond = 3002,Error_STPOSPLAN_getCfgCond = 3003,Error_STPOSPLAN_addCfgTran = 3004,Error_STPOSPLAN_delCfgTran = 3005,Error_STPOSPLAN_setCfgTran = 3006,Error_STPOSPLAN_getCfgTran = 3007,Error_STPOSPLAN_addCfgAct = 3008,Error_STPOSPLAN_delCfgAct = 3009,Error_STPOSPLAN_setCfgAct = 3010,Error_STPOSPLAN_getCfgAct = 3011,Error_STPOSPLAN_addCfgVar = 3012,Error_STPOSPLAN_delCfgVar = 3013,Error_STPOSPLAN_setCfgVar = 3014,Error_STPOSPLAN_getCfgVar = 3015,Error_STPOSPLAN_addCfgState = 3016,Error_STPOSPLAN_delCfgState = 3017,Error_STPOSPLAN_setCfgState = 3018,Error_STPOSPLAN_setVar = 3019,Error_STPOSPLAN_getVar = 3020,Error_STPOSPLAN_setCfg = 3021,Error_STPOSPLAN_setCfgHaltState = 3022,Error_STPOSPLAN_setCfgArray = 3023,Error_STPOSPLAN_addCfgVarCond = 3024,Error_STPOSPLAN_delCfgVarCond = 3025,Error_STPOSPLAN_setCfgVarCond = 3026,Error_STPOSPLAN_getCfgVarCond = 3027,Invalid_STLicense = 4001,Invalid_RomVersion = 4003 }
Enumeration for the Position Plan Error Id, indicates the function which caused the error.
Functions
• static void STPOSPLAN_getPositionStep_mrev (ST_POSPLAN_Handle handle, int32_t ∗pos←↩StepInt_mrev, _lq24 ∗posStepFrac_mrev)
Gets the Position Step (posStepInt_mrev, posStepFrac_mrev) for SpinTAC Position Plan.• static _lq24 STPOSPLAN_getVelocityLimit (ST_POSPLAN_Handle handle)
Gets the Velocity Limit (VelLim) for SpinTAC Position Plan.• static _lq24 STPOSPLAN_getAccelerationLimit (ST_POSPLAN_Handle handle)
Gets the Acceleration Limit (AccLim) for SpinTAC Position Plan.• static _lq24 STPOSPLAN_getDecelerationLimit (ST_POSPLAN_Handle handle)
Gets the Deceleration Limit (DecLim) for SpinTAC Position Plan.• static _lq20 STPOSPLAN_getJerkLimit (ST_POSPLAN_Handle handle)
250Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Gets the Jerk Limit (JrkLim) for SpinTAC Position Plan.• static void STPOSPLAN_setEnable (ST_POSPLAN_Handle handle, bool enb)
Sets the Enable signal (ENB) for SpinTAC Position Plan.• static bool STPOSPLAN_getEnable (ST_POSPLAN_Handle handle)
Gets the Enable signal (ENB) for SpinTAC Position Plan.• static void STPOSPLAN_setReset (ST_POSPLAN_Handle handle, bool res)
Sets the Reset signal (RES) for SpinTAC Position Plan.• static bool STPOSPLAN_getReset (ST_POSPLAN_Handle handle)
Gets the Reset signal (RES) for SpinTAC Position Plan.• static ST_PlanStatus_e STPOSPLAN_getStatus (ST_POSPLAN_Handle handle)
Gets the Status value (STATUS) for SpinTAC Position Plan.• static uint16_t STPOSPLAN_getCurrentState (ST_POSPLAN_Handle handle)
Gets the Current State (CurState) for SpinTAC Position Plan.• static uint16_t STPOSPLAN_getCurrentTransition (ST_POSPLAN_Handle handle)
Gets the Current Transition (CurTran) for SpinTAC Position Plan.• static ST_PlanFsmState_e STPOSPLAN_getFsmState (ST_POSPLAN_Handle handle)
Gets the State Machine State (FsmState) for SpinTAC Position Plan.• static int32_t STPOSPLAN_getCurrentTimerValue_tick (ST_POSPLAN_Handle handle)
Gets the Current Time Value (Timer_tick) for SpinTAC Position Plan.• static uint16_t STPOSPLAN_getCfgError (ST_POSPLAN_Handle handle, uint16_t ∗ERR_idx,
uint16_t ∗ERR_code)Gets the Configuration Error for SpinTAC Position Plan.
• static uint16_t STPOSPLAN_getErrorID (ST_POSPLAN_Handle handle)Gets the Error value (ERR_ID) for SpinTAC Position Plan.
• void STPOSPLAN_getCfgStateNum (ST_POSPLAN_Handle handle, uint16_t ∗StateNum)Returns the number of configured States in SpinTAC Position Plan.
• void STPOSPLAN_getCfgVarNum (ST_POSPLAN_Handle handle, uint16_t ∗VarNum)Returns the number of configured Variables in SpinTAC Position Plan.
• void STPOSPLAN_getCfgCondNum (ST_POSPLAN_Handle handle, uint16_t ∗CondNum)Returns the number of configured Conditions in SpinTAC Position Plan.
• void STPOSPLAN_getCfgTranNum (ST_POSPLAN_Handle handle, uint16_t ∗TranNum)Returns the number of configured Transitions in SpinTAC Position Plan.
• void STPOSPLAN_getCfgActNum (ST_POSPLAN_Handle handle, uint16_t ∗ActNum)Returns the number of configured Actions in SpinTAC Position Plan.
• void STPOSPLAN_addCfgCond (ST_POSPLAN_Handle handle, uint16_t VarIdx, ST_Plan←↩Comp_e Comp, _lq24 Value1, _lq24 Value2)
Adds a Condition to the SpinTAC Position Plan configuration.• void STPOSPLAN_delCfgCond (ST_POSPLAN_Handle handle, uint16_t CondIdx)
Deletes a Condition from the SpinTAC Position Plan configuration.• void STPOSPLAN_setCfgCond (ST_POSPLAN_Handle handle, uint16_t CondIdx, uint16_t Var←↩
Idx, ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2)Modifies a Condition in the SpinTAC Position Plan configuration.
• void STPOSPLAN_getCfgCond (ST_POSPLAN_Handle handle, uint16_t CondIdx, uint16_←↩t ∗VarIdx, ST_PlanComp_e ∗Comp, _lq24 ∗Value1, _lq24 ∗Value2)
Returns a Condition from the SpinTAC Position Plan configuration.• void STPOSPLAN_addCfgVarCond (ST_POSPLAN_Handle handle, uint16_t VarIdx1, uint16_←↩
t VarIdx2, ST_PlanComp_e Comp)Adds a Variable Condition to the SpinTAC Position Plan configuration.
• void STPOSPLAN_delCfgVarCond (ST_POSPLAN_Handle handle, uint16_t CondIdx)Deletes a Variable Condition from the SpinTAC Position Plan configuration.
• void STPOSPLAN_setCfgVarCond (ST_POSPLAN_Handle handle, uint16_t CondIdx, uint16_←↩
Freescale SemiconductorKinetis Motor Suite API Reference Manual
251
SpinTAC™ Position Plan
t VarIdx1, uint16_t VarIdx2, ST_PlanComp_e Comp)Modifies a Variable Condition to the SpinTAC Position Plan configuration.
• void STPOSPLAN_getCfgVarCond (ST_POSPLAN_Handle handle, uint16_t CondIdx, uint16_t∗VarIdx1, uint16_t ∗VarIdx2, ST_PlanComp_e ∗Comp)
Returns a Variable Condition from the SpinTAC Position Plan configuration.• void STPOSPLAN_addCfgTran (ST_POSPLAN_Handle handle, uint16_t FromState, uint16_t To←↩
State, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, _lq24 VelLim, _lq24 Acc←↩Lim, _lq24 DecLim, _lq20 JrkLim)
Adds a Transition to the SpinTAC Position Plan configuration.• void STPOSPLAN_delCfgTran (ST_POSPLAN_Handle handle, uint16_t TranIdx)
Deletes a Transition from the SpinTAC Position Plan configuration.• void STPOSPLAN_setCfgTran (ST_POSPLAN_Handle handle, uint16_t TranIdx, uint16_t From←↩
State, uint16_t ToState, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, _lq24VelLim, _lq24 AccLim, _lq24 DecLim, _lq20 JrkLim)
Modifies a Transition in the SpinTAC Position Plan configuration.• void STPOSPLAN_getCfgTran (ST_POSPLAN_Handle handle, uint16_t TranIdx, uint16_←↩
t ∗FromState, uint16_t ∗ToState, ST_PlanCond_e ∗AndOr, uint16_t ∗CondIdx1, uint16_t ∗Cond←↩Idx2, _lq24 ∗VelLim, _lq24 ∗AccLim, _lq24 ∗DecLim, _lq20 ∗JrkLim)
Get a Transition from the SpinTAC Position Plan configuration.• void STPOSPLAN_addCfgAct (ST_POSPLAN_Handle handle, uint16_t State, ST_PlanCond_←↩
e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx, ST_PlanActOptn_e Opt, _lq24Value, ST_PlanActTrgr_e EnterExit)
Adds an action to the SpinTAC Position Plan configuration.• void STPOSPLAN_delCfgAct (ST_POSPLAN_Handle handle, uint16_t ActIdx)
Deletes an action from the SpinTAC Position Plan configuration.• void STPOSPLAN_setCfgAct (ST_POSPLAN_Handle handle, uint16_t ActIdx, uint16_t State, S←↩
T_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx, ST_PlanActOptn←↩_e Opt, _lq24 Value, ST_PlanActTrgr_e EnterExit)
Modifies an action in the SpinTAC Position Plan configuration.• void STPOSPLAN_getCfgAct (ST_POSPLAN_Handle handle, uint16_t ActIdx, uint16_t ∗State,
ST_PlanCond_e ∗AndOr, uint16_t ∗CondIdx1, uint16_t ∗CondIdx2, uint16_t ∗VarIdx, ST_Plan←↩ActOptn_e ∗Opt, _lq24 ∗Value, ST_PlanActTrgr_e ∗EnterExit)
Returns an action from the SpinTAC Position Plan configuration.• void STPOSPLAN_addCfgVar (ST_POSPLAN_Handle handle, ST_PlanVar_e Type, _lq24 Value)
Adds a variable to the SpinTAC Position Plan configuration.• void STPOSPLAN_delCfgVar (ST_POSPLAN_Handle handle, uint16_t VarIdx)
Deletes a Variable from the SpinTAC Position Plan configuration.• void STPOSPLAN_setCfgVar (ST_POSPLAN_Handle handle, uint16_t VarIdx, ST_PlanVar_←↩
e Type, _lq24 Value)Modifies a variable in the SpinTAC Position Plan configuration.
• void STPOSPLAN_getCfgVar (ST_POSPLAN_Handle handle, uint16_t VarIdx, ST_PlanVar_←↩e ∗Type, _lq24 ∗Value)
Returns a variable from the SpinTAC Position Plan configuration.• void STPOSPLAN_setVar (ST_POSPLAN_Handle handle, uint16_t VarIdx, _lq24 Value)
Sets the value of a SpinTAC Position Plan variable.• void STPOSPLAN_getVar (ST_POSPLAN_Handle handle, uint16_t VarIdx, _lq24 ∗Value)
Gets the value of a SpinTAC Position Plan variable.• void STPOSPLAN_setUnitProfDone (ST_POSPLAN_Handle handle, bool ProDON)
Sets a flag in SpinTAC Position Plan to indicate if the unit profile is complete.
252Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
• void STPOSPLAN_setCfg (ST_POSPLAN_Handle handle, _lq24 T_sec, bool LoopENB)Configures SpinTAC Position Plan.
• void STPOSPLAN_getCfg (ST_POSPLAN_Handle handle, _lq24 ∗T_sec, bool ∗LoopENB)Gets the SpinTAC Position Plan configuration.
• void STPOSPLAN_setCfgHaltState (ST_POSPLAN_Handle handle, int32_t PosStepInt_mrev, _←↩lq24 PosStepFrac_mrev, _lq24 VelLim, _lq24 AccLim, _lq20 JrkLim, int32_t Timer_tick)
Configures the SpinTAC Position Plan Halt state.• void STPOSPLAN_getCfgHaltState (ST_POSPLAN_Handle handle, int32_t ∗PosStepInt_mrev, ←↩
_lq24 ∗PosStepFrac_mrev, _lq24 ∗VelLim, _lq24 ∗AccLim, _lq20 ∗JrkLim, int32_t ∗Timer_tick)Gets the SpinTAC Position Plan Halt state.
• void STPOSPLAN_addCfgState (ST_POSPLAN_Handle handle, int32_t PosStepInt_mrev, _lq24PosStep_Fracmrev, int32_t Timer_tick)
Adds a State to the SpinTAC Position Plan configuration.• void STPOSPLAN_delCfgState (ST_POSPLAN_Handle handle, uint16_t StateIdx)
Deletes a state from the SpinTAC Position Plan configuration.• void STPOSPLAN_setCfgState (ST_POSPLAN_Handle handle, uint16_t StateIdx, int32_t Pos←↩
StepInt_mrev, _lq24 PosStepFrac_mrev, int32_t Timer_tick)Modifies a state in the SpinTAC Position Plan configuration.
• void STPOSPLAN_getCfgState (ST_POSPLAN_Handle handle, uint16_t StateIdx, int32_t ∗Pos←↩StepInt_mrev, _lq24 ∗PosStepFrac_mrev, int32_t ∗Timer_tick)
Returns a state from the SpinTAC Position Plan configuration.• void STPOSPLAN_reset (ST_POSPLAN_Handle handle)
Resets the SpinAC Position Plan component.• ST_POSPLAN_Handle STPOSPLAN_init (void ∗pMemory, const size_t numBytes)
Initializes the SpinTAC Position Plan component.• void STPOSPLAN_run (ST_POSPLAN_Handle handle)
Runs SpinTAC Position Plan calculation.• void STPOSPLAN_runTick (ST_POSPLAN_Handle handle)
Runs SpinTAC Position Plan Timing. Call this only from an ISR.• void STPOSPLAN_setCfgArray (ST_POSPLAN_Handle handle, uint32_t ∗cfgArray, const size_t
numBytes, uint16_t MaxActNum, uint16_t MaxCondNum, uint16_t MaxVarNum, uint16_t Max←↩TranNum, uint16_t MaxStateNum)
Prepares SpinTAC Position Plan data structure.
22.3.2 Data Structure Documentation
22.3.2.1 struct ST_PlanError_t
Defines the ST_PlanError_t data.
The ST_PlanError_t object contains error debugging information for the Position Plan component
Data Fields
Freescale SemiconductorKinetis Motor Suite API Reference Manual
253
SpinTAC™ Position Plan
uint16_t ERR_code Function specific condition that caused the error. Function specificcondition that caused the error
uint16_t ERR_idx Plan component index that caused the error. Plan component indexthat caused the error
22.3.2.2 struct ST_PosPlan_t
Defines the ST_PosPlan_t data.
The ST_PosPlan_t object contains all configuration parameters of the Position Plan component
Data Fields
_lq24 AccLim Acceleration limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}.
ST_PlanError←↩_t
CfgError Error decoding structure.
uint16_t CurState Current state of the state machine.
uint16_t CurTran Current transition of the state machine.
_lq24 DecLim Deceleration limit { unit: [(pu rpm)/s], value range: [0.001, 120.0]}.
bool ENB Enable bit { false: disabled; true: enabled }.
uint16_t ERR_ID Error ID { 0: no error; others: see error code }.
ST_PlanFsm←↩State_e
FsmState State of the state machine.
_lq20 JrkLim Jerk Limit { unit: [(pu rpm)/s∧2], value range: [0.0005, 2000.0] }.
_lq24 PosStepFrac_←↩mrev
Position Step fraction part { unit: [MRev], value range: (-1.0, 1.←↩0)}.
int32_t PosStepInt_←↩mrev
Position Step Integer part { unit: [MRev] }.
bool RES Reset bit { false: not reset; true: reset }.
uint32_t s0[31]
254Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
ST_Plan←↩Status_e
STATUS Plan status { ST_PLAN_IDLE, ST_PLAN_INIT, ST_PLAN_B←↩USY, ST_PLAN_HALT, ST_PLAN_WAIT}.
int32_t Timer_tick State Timer { unit: [tick] }.
_lq24 VelLim Velocity limit { unit: [pu rpm], value range: (0.0, 1.0] }.
22.3.3 Macro Definition Documentation
22.3.3.1 #define __ST_PLAN_ENUM__
22.3.3.2 #define __ST_PLAN_ERROR__
22.3.3.3 #define ST_POS_PLAN_ACT_DWORDS (5)
Defines the amount of memory that needs to be allocated for each component.
Each configured Action takes 3 double words of memory
22.3.3.4 #define ST_POS_PLAN_COND_DWORDS (3)
Each configured Condition takes 3 double words of memory.
22.3.3.5 #define ST_POS_PLAN_STATE_DWORDS (7)
Each configured State takes 7 double words of memory.
22.3.3.6 #define ST_POS_PLAN_TRAN_DWORDS (7)
Each configured Transition takes 7 double words of memory.
22.3.3.7 #define ST_POS_PLAN_VAR_DWORDS (2)
Each configured Variable takes 2 double words of memory.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
255
SpinTAC™ Position Plan
22.3.4 Typedef Documentation
22.3.4.1 typedef ST_PosPlan_t∗ ST_POSPLAN_Handle
22.3.5 Enumeration Type Documentation
22.3.5.1 enum ST_PlanActOptn_e
Enumeration for the Plan Action Options.
Enumerator
ST_ACT_EQ Action will set the variable equal to a value.ST_ACT_ADD Action will add a value to the variable.ST_ACT_EQ Action will set the variable equal to a valueST_ACT_ADD Action will add a value to the variable
22.3.5.2 enum ST_PlanActTrgr_e
Enumeration for the Plan Action trigger point types.
Enumerator
ST_ACT_ENTR Action will be considered when entering the state.ST_ACT_EXIT Action will be considered when exiting the state.ST_ACT_ENTR Action will be considered when entering the stateST_ACT_EXIT Action will be considered when exiting the state
22.3.5.3 enum ST_PlanComp_e
Enumeration for the Plan Compare options.
Enumerator
ST_COMP_NA No comparison.ST_COMP_EQ Compares, VarIdx == Value1 OR VarIdx1 == VarIdx2.ST_COMP_NEQ Compares, VarIdx != Value1 OR VarIdx1 != VarIdx2.ST_COMP_GT Compares, VarIdx > Value1 OR VarIdx1 > VarIdx2.ST_COMP_EGT Compares, VarIdx >= Value1 OR VarIdx1 >= VarIdx2.ST_COMP_LW Compares, VarIdx < Value1 OR VarIdx1 < VarIdx2.ST_COMP_ELW Compares, VarIdx <= Value1 OR VarIdx1 <= VarIdx2.ST_COMP_In Compares, Value1 <= VarIdx <= Value2.ST_COMP_EIn Compares, Value1 < VarIdx <= Value2.
256Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
ST_COMP_InE Compares, Value1 <= VarIdx < Value2.ST_COMP_EInE Compares, Value1 < VarIdx < Value2.ST_COMP_Out Compares, Value1 >= VarIdx >= Value2.ST_COMP_EOut Compares, Value1 > VarIdx >= Value2.ST_COMP_OutE Compares, Value1 >= VarIdx > Value2.ST_COMP_EOutE Compares, Value1 > VarIdx > Value2.ST_COMP_NA No comparisonST_COMP_EQ Compares, VarIdx == Value1 OR VarIdx1 == VarIdx2ST_COMP_NEQ Compares, VarIdx != Value1 OR VarIdx1 != VarIdx2ST_COMP_GT Compares, VarIdx > Value1 OR VarIdx1 > VarIdx2ST_COMP_EGT Compares, VarIdx >= Value1 OR VarIdx1 >= VarIdx2ST_COMP_LW Compares, VarIdx < Value1 OR VarIdx1 < VarIdx2ST_COMP_ELW Compares, VarIdx <= Value1 OR VarIdx1 <= VarIdx2ST_COMP_In Compares, Value1 <= VarIdx <= Value2ST_COMP_EIn Compares, Value1 < VarIdx <= Value2ST_COMP_InE Compares, Value1 <= VarIdx < Value2ST_COMP_EInE Compares, Value1 < VarIdx < Value2ST_COMP_Out Compares, Value1 >= VarIdx >= Value2ST_COMP_EOut Compares, Value1 > VarIdx >= Value2ST_COMP_OutE Compares, Value1 >= VarIdx > Value2ST_COMP_EOutE Compares, Value1 > VarIdx > Value2
22.3.5.4 enum ST_PlanCond_e
Enumeration for the Plan Condition options.
Enumerator
ST_COND_NC Transition/Action with no conditions satisfied.ST_COND_FC Transition/Action with first condition satisfied.ST_COND_AND Transition/Action with both conditions satisfied.ST_COND_OR Transition/Action with either condition satisfied.ST_COND_NC Transition/Action with no conditions satisfiedST_COND_FC Transition/Action with first condition satisfiedST_COND_AND Transition/Action with both conditions satisfiedST_COND_OR Transition/Action with either condition satisfied
22.3.5.5 enum ST_PlanFsmState_e
Enumeration for the Plan FSM states.
Enumerator
ST_FSM_STATE_STAY Plan is staying in a state until the timer is up.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
257
SpinTAC™ Position Plan
ST_FSM_STATE_COND Plan is waiting for a transition condition to be true.ST_FSM_STATE_TRAN Plan is in transition with a motion profile.ST_FSM_STATE_STAY Plan is staying in a state until the timer is upST_FSM_STATE_COND Plan is waiting for a transition condition to be trueST_FSM_STATE_TRAN Plan is in transition with a motion profile
22.3.5.6 enum ST_PlanStatus_e
Enumeration for the Plan Status States.
Enumerator
ST_PLAN_IDLE idle state, holding positionST_PLAN_INIT init state, initialize internal statesST_PLAN_BUSY busy state, running state machineST_PLAN_HALT halt state, return to the position reference in idle stateST_PLAN_WAIT wait state, holding the position reference in idle stateST_PLAN_IDLE idle state, holding velocityST_PLAN_INIT init state, initialize internal statesST_PLAN_BUSY busy state, running state machineST_PLAN_HALT halt state, return to the speed reference in idle stateST_PLAN_WAIT wait state, holding the speed reference in idle state
22.3.5.7 enum ST_PlanVar_e
Enumeration for the Plan variable types.
Enumerator
ST_VAR_INOUT Variable type input/output.ST_VAR_IN Variable type input.ST_VAR_OUT Variable type output.ST_VAR_INOUT Variable type input/outputST_VAR_IN Variable type inputST_VAR_OUT Variable type output
22.3.5.8 enum ST_PosPlan_ErrorCode_e
Enumeration for the Position Plan Error Codes.
Enumerator
No_ErrorCode No error code
258Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Plan_running Cannot change config while Plan is runningMax_States_exceed Maximum number of States exceededMax_Cond_exceed Maximum number of Conditions exceededMax_Trans_exceed Maximum number of Transitions exceededMax_Act_exceed Maximum number of Actions exceededMax_Var_exceed Maximum number of Variables exceededInvalid_Sampletime Sample Time is out of rangeInvalid_LoopENB Loop Enable is out of rangeInvalid_HaltAccLim Acceleration Limit is out of rangeInvalid_HaltJrkLim Jerk Limit is out of rangeInvalid_Timer_tick State Timer is out of rangeInvalid_State_index State Index is greater than Maximum number of StatesInvalid_Condition_index Condition Index is greater than Maximum number of ConditionsInvalid_Trans_index Transition Index is greater than Maximum number of TransitionsInvalid_Action_index Action Index is greater than Maximum number of ActionsInvalid_Var_index Varaible Index is greater than Maximum number of VariablesInvalid_Var_type Variable Type is out of rangeInvalid_Value_Comp Value Comparison is out of rangeInvalid_Operation Action Operation is out of rangeInvalid_AndOr And/Or Selection is out of rangeImproper_Var_type Indicated Variable cannot be used for this operationImproper_Val_Comparison With a multiple value comparison, Value 1 must be < Value 2Improper_State_index Maximum number of States exceeded OR From State cannot be equal to To
StateImproper_Cond_Idx Maximum number of Conditions exceeded OR Condition 1 cannot be equal to
Condition 2Improper_EnterExit Enter/Exit Selection is out of rangeCannot_delete_Var_Cond Variable is used by a ConditionCannot_delete_Var_Act Variable is used by an ActionInvalid_HaltVelLim Velocity Limit is out of rangeInvalid_HaltDecLim Deceleration Limit is out of rangeInvalid_PosStep Halt Positon Step is out of rangePlanCfg_array_Small Plan Configuration Array is not large enoughCannot_delete_State_Tran State is used by a TransitionCannot_delete_State_Act State is used by an ActionInvalid_Var_Compare Cannot select range comparisonInvalid_Var_indexes Variable 1 cannot be equal to Variable 2Invalid_Cond_Index Wrong type of Condition specifiedCannot_Delete_Cond_Tran Condition is used by a TransitionInvalid_InitState_Step First State must have 0 Postion StepCannot_Delete_Cond_Act Condition is used by an Action
Freescale SemiconductorKinetis Motor Suite API Reference Manual
259
SpinTAC™ Position Plan
22.3.5.9 enum ST_PosPlan_ErrorId_e
Enumeration for the Position Plan Error Id, indicates the function which caused the error.
Enumerator
No_ErrorId No error idError_STPOSPLAN_addCfgCondError_STPOSPLAN_delCfgCondError_STPOSPLAN_setCfgCondError_STPOSPLAN_getCfgCondError_STPOSPLAN_addCfgTranError_STPOSPLAN_delCfgTranError_STPOSPLAN_setCfgTranError_STPOSPLAN_getCfgTranError_STPOSPLAN_addCfgActError_STPOSPLAN_delCfgActError_STPOSPLAN_setCfgActError_STPOSPLAN_getCfgActError_STPOSPLAN_addCfgVarError_STPOSPLAN_delCfgVarError_STPOSPLAN_setCfgVarError_STPOSPLAN_getCfgVarError_STPOSPLAN_addCfgStateError_STPOSPLAN_delCfgStateError_STPOSPLAN_setCfgStateError_STPOSPLAN_setVarError_STPOSPLAN_getVarError_STPOSPLAN_setCfgError_STPOSPLAN_setCfgHaltStateError_STPOSPLAN_setCfgArrayError_STPOSPLAN_addCfgVarCondError_STPOSPLAN_delCfgVarCondError_STPOSPLAN_setCfgVarCondError_STPOSPLAN_getCfgVarCondInvalid_STLicenseInvalid_RomVersion
22.3.6 Function Documentation
22.3.6.1 void STPOSPLAN_addCfgAct ( ST_POSPLAN_Handle handle, uint16_t State,ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2, uint16_t VarIdx,ST_PlanActOptn_e Opt, _lq24 Value, ST_PlanActTrgr_e EnterExit )
Adds an action to the SpinTAC Position Plan configuration.
260Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in State Index of the State the Action happens in
in AndOr Condition option for the Action
in CondIdx1 Index of the first Condition to consider for the Action
in CondIdx2 Index of the second Condition to consider for the Action
in VarIdx Index of the Varaible to be acted upon
in Opt Type of Action to perform on the Varaible
in Value Value to use in the Action
in EnterExit State event that will trigger the Action
22.3.6.2 void STPOSPLAN_addCfgCond ( ST_POSPLAN_Handle handle, uint16_tVarIdx, ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2 )
Adds a Condition to the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Plan Variable that will be compared
in Comp Type of comparison that will be done
in Value1 First value to use in the comparison
in Value2 Second value to use in the comparison
22.3.6.3 void STPOSPLAN_addCfgState ( ST_POSPLAN_Handle handle, int32_tPosStepInt_mrev, _lq24 PosStep_Fracmrev, int32_t Timer_tick )
Adds a State to the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Freescale SemiconductorKinetis Motor Suite API Reference Manual
261
SpinTAC™ Position Plan
in PosStepInt_←↩mrev
Position step integer part in State { unit: [MRev], value range: 32 bitinteger (-2∧31, 2∧31) }
in PosStepFrac_←↩mrev
Position step fraction part in State { unit: [MRev], value range: (-1.0,1.0) }
in Timer_tick Minimum time to stay in State { unit: [tick] }
22.3.6.4 void STPOSPLAN_addCfgTran ( ST_POSPLAN_Handle handle, uint16_tFromState, uint16_t ToState, ST_PlanCond_e AndOr, uint16_t CondIdx1,uint16_t CondIdx2, _lq24 VelLim, _lq24 AccLim, _lq24 DecLim, _lq20 JrkLim )
Adds a Transition to the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in FromState Index of the from State
in ToState Index of the to State
in AndOr Condition option for the Transition
in CondIdx1 Index of the first Condition to consider for the Transition
in CondIdx2 Index of the second Condition to consider for the Transition
in VelLim Velocity limit for the Transition { unit: [pu rpm], value range: (0.0, 1.0]}
in AccLim Acceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
in DecLim Deceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
in JrkLim Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005,2000.0] }
22.3.6.5 void STPOSPLAN_addCfgVar ( ST_POSPLAN_Handle handle, ST_PlanVar_eType, _lq24 Value )
Adds a variable to the SpinTAC Position Plan configuration.
262Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in Type Type of Variable
in Value Initial value of the Variable
22.3.6.6 void STPOSPLAN_addCfgVarCond ( ST_POSPLAN_Handle handle, uint16_tVarIdx1, uint16_t VarIdx2, ST_PlanComp_e Comp )
Adds a Variable Condition to the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx1 Index of the first Plan Variable that will be compared
in VarIdx2 Index of the second Plan Variable that will be compared
in Comp Type of comparison that will be done
22.3.6.7 void STPOSPLAN_delCfgAct ( ST_POSPLAN_Handle handle, uint16_t ActIdx )
Deletes an action from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in ActIdx Index of the Action to delete
22.3.6.8 void STPOSPLAN_delCfgCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx )
Deletes a Condition from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Freescale SemiconductorKinetis Motor Suite API Reference Manual
263
SpinTAC™ Position Plan
in CondIdx Index of the Plan Condition to delete
22.3.6.9 void STPOSPLAN_delCfgState ( ST_POSPLAN_Handle handle, uint16_tStateIdx )
Deletes a state from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in StateIdx Index of the State to delete
22.3.6.10 void STPOSPLAN_delCfgTran ( ST_POSPLAN_Handle handle, uint16_tTranIdx )
Deletes a Transition from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in TranIdx Index of the Transition to delete
22.3.6.11 void STPOSPLAN_delCfgVar ( ST_POSPLAN_Handle handle, uint16_t VarIdx )
Deletes a Variable from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Variable to delete
22.3.6.12 void STPOSPLAN_delCfgVarCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx )
Deletes a Variable Condition from the SpinTAC Position Plan configuration.
264Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in CondIdx Index of the Plan Condition to delete
22.3.6.13 static _lq24 STPOSPLAN_getAccelerationLimit ( ST_POSPLAN_Handle handle) [inline], [static]
Gets the Acceleration Limit (AccLim) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
_lq24 AccLim Acceleration limit { unit: [(pu rpm)/s], value range: (0.0, 120.0] }
References ST_PosPlan_t::AccLim.
22.3.6.14 void STPOSPLAN_getCfg ( ST_POSPLAN_Handle handle, _lq24 ∗ T_sec,bool ∗ LoopENB )
Gets the SpinTAC Position Plan configuration.
Parameters
in handle handle The handle for the SpinTAC Position Plan Object
out ∗T_sec Sample Time { unit: [sec], value range: (0, 0.01] }
out ∗LoopENB Sets if SpinTAC Position Plan should continuously run after it reachesthe end { false: Do not continuously run Plan; true: Continuously runPlan }
22.3.6.15 void STPOSPLAN_getCfgAct ( ST_POSPLAN_Handle handle, uint16_t ActIdx,uint16_t ∗ State, ST_PlanCond_e ∗ AndOr, uint16_t ∗ CondIdx1, uint16_t∗ CondIdx2, uint16_t ∗ VarIdx, ST_PlanActOptn_e ∗ Opt, _lq24 ∗ Value,ST_PlanActTrgr_e ∗ EnterExit )
Returns an action from the SpinTAC Position Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
265
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in ActIdx Index of the Action to return
out ∗State Index of the State the Action happens in
out ∗AndOr Condition option for the Action
out ∗CondIdx1 Index of the first Condition to consider for the Action
out ∗CondIdx2 Index of the second Condition to consider for the Action
out ∗VarIdx Index of the Varaible to be acted upon
out ∗Opt Type of Action to perform on the Varaible
out ∗Value Value to use in the Action
out ∗EnterExit State event that will trigger the Action
22.3.6.16 void STPOSPLAN_getCfgActNum ( ST_POSPLAN_Handle handle, uint16_t ∗ActNum )
Returns the number of configured Actions in SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
out ∗ActNum The number of configured Actions in SpinTAC Position Plan
22.3.6.17 void STPOSPLAN_getCfgCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx, uint16_t ∗ VarIdx, ST_PlanComp_e ∗ Comp, _lq24 ∗ Value1, _lq24 ∗Value2 )
Returns a Condition from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in CondIdx Index of the Plan Condition to return
out ∗VarIdx Index of the Plan Variable that will be compared
266Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
out ∗Comp Type of comparison that will be done
out ∗Value1 First value to use in the comparison
out ∗Value2 Second value to use in the comparison
22.3.6.18 void STPOSPLAN_getCfgCondNum ( ST_POSPLAN_Handle handle, uint16_t∗ CondNum )
Returns the number of configured Conditions in SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
out ∗CondNum The number of configured Conditions in SpinTAC Position Plan
22.3.6.19 static uint16_t STPOSPLAN_getCfgError ( ST_POSPLAN_Handle handle,uint16_t ∗ ERR_idx, uint16_t ∗ ERR_code ) [inline], [static]
Gets the Configuration Error for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
out ∗ERR_idx Component index where error occurred { 0: no index; others: see errorcode }
out ∗ERR_code Specific configuration error { 0: no additional information; others: seeerror code }
Returns
uint16_t ERR_ID Error ID { 0: no error; others: see error code }
References ST_PosPlan_t::CfgError, ST_PlanError_t::ERR_code, ST_PosPlan_t::ERR_ID, and ST_←↩PlanError_t::ERR_idx.
22.3.6.20 void STPOSPLAN_getCfgHaltState ( ST_POSPLAN_Handle handle, int32_t ∗PosStepInt_mrev, _lq24 ∗ PosStepFrac_mrev, _lq24 ∗ VelLim, _lq24 ∗ AccLim,_lq20 ∗ JrkLim, int32_t ∗ Timer_tick )
Gets the SpinTAC Position Plan Halt state.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
267
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
out ∗PosStepInt_←↩mrev
Position step integer part for Halt State { unit: [MRev] }
out ∗PosStepFrac←↩_mrev
Position step fraction part for Halt State { unit: [MRev], value range:(-1.0, 1.0) }
out ∗VelLim Velocity limit during Halt state { unit: [pu rpm], value range: (0, 1] }
out ∗AccLim Acceleration limit for Halt state { unit: [(pu rpm)/s], value range: [0.←↩001, 120.0] }
22.3.6.21 void STPOSPLAN_getCfgState ( ST_POSPLAN_Handle handle, uint16_tStateIdx, int32_t ∗ PosStepInt_mrev, _lq24 ∗ PosStepFrac_mrev, int32_t ∗Timer_tick )
Returns a state from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in StateIdx Index of the State to modify
out ∗PosStepInt_←↩mrev
Position step integer part in State { unit: [MRev] }
out ∗PosStepFrac←↩_mrev
Position step fraction part in State { unit: [MRev] }
out ∗Timer_tick Minimum time to stay in State { unit: [tick] }
22.3.6.22 void STPOSPLAN_getCfgStateNum ( ST_POSPLAN_Handle handle, uint16_t ∗StateNum )
Returns the number of configured States in SpinTAC Position Plan.
Parameters
268Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
in handle The handle for the SpinTAC Position Plan Object
out ∗StateNum The number of configured States in SpinTAC Position Plan
22.3.6.23 void STPOSPLAN_getCfgTran ( ST_POSPLAN_Handle handle, uint16_tTranIdx, uint16_t ∗ FromState, uint16_t ∗ ToState, ST_PlanCond_e ∗ AndOr,uint16_t ∗ CondIdx1, uint16_t ∗ CondIdx2, _lq24 ∗ VelLim, _lq24 ∗ AccLim,_lq24 ∗ DecLim, _lq20 ∗ JrkLim )
Get a Transition from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in TranIdx Index of the Transition to return
out ∗FromState Index of the from State
out ∗ToState Index of the to State
out ∗AndOr Condition option for the Transition
out ∗CondIdx1 Index of the first Condition to consider for the Transition
out ∗CondIdx2 Index of the second Condition to consider for the Transition
out ∗VelLim Velocity limit for the Transition { unit: [pu rpm], value range: (0.0, 1.0]}
out ∗AccLim Acceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
out ∗DecLim Deceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
out ∗JrkLim Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005,2000.0] }
22.3.6.24 void STPOSPLAN_getCfgTranNum ( ST_POSPLAN_Handle handle, uint16_t ∗TranNum )
Returns the number of configured Transitions in SpinTAC Position Plan.
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
269
SpinTAC™ Position Plan
in handle The handle for the SpinTAC Position Plan Object
out ∗TranNum The number of configured Transitions in SpinTAC Position Plan
22.3.6.25 void STPOSPLAN_getCfgVar ( ST_POSPLAN_Handle handle, uint16_t VarIdx,ST_PlanVar_e ∗ Type, _lq24 ∗ Value )
Returns a variable from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Variable to return
out ∗Type Type of Variable
out ∗Value Initial value of the Variable
22.3.6.26 void STPOSPLAN_getCfgVarCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx, uint16_t ∗ VarIdx1, uint16_t ∗ VarIdx2, ST_PlanComp_e ∗ Comp )
Returns a Variable Condition from the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in CondIdx Index of the Plan Condition to return
out ∗VarIdx1 Index of the first Plan Variable that will be compared
out ∗VarIdx2 Index of the second Plan Variable that will be compared
out ∗Comp Type of comparison that will be done
22.3.6.27 void STPOSPLAN_getCfgVarNum ( ST_POSPLAN_Handle handle, uint16_t ∗VarNum )
Returns the number of configured Variables in SpinTAC Position Plan.
Parameters
270Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
in handle The handle for the SpinTAC Position Plan Object
out ∗VarNum The number of configured Variables in SpinTAC Position Plan
22.3.6.28 static uint16_t STPOSPLAN_getCurrentState ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Current State (CurState) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
uint16_t CurState Current state of the state machine
References ST_PosPlan_t::CurState.
22.3.6.29 static int32_t STPOSPLAN_getCurrentTimerValue_tick ( ST_POSPLAN_Handlehandle ) [inline], [static]
Gets the Current Time Value (Timer_tick) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
int32_t Timer State Timer { unit: [tick] }
References ST_PosPlan_t::Timer_tick.
22.3.6.30 static uint16_t STPOSPLAN_getCurrentTransition ( ST_POSPLAN_Handlehandle ) [inline], [static]
Gets the Current Transition (CurTran) for SpinTAC Position Plan.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
271
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
uint16_t CurTran Current transition of the state machine
References ST_PosPlan_t::CurTran.
22.3.6.31 static _lq24 STPOSPLAN_getDecelerationLimit ( ST_POSPLAN_Handle handle) [inline], [static]
Gets the Deceleration Limit (DecLim) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
_lq24 DecLim Deceleration limit { unit: [(pu rpm)/s], value range: (0.0, 120.0] }
References ST_PosPlan_t::DecLim.
22.3.6.32 static bool STPOSPLAN_getEnable ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Enable signal (ENB) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
bool ENB Enable bit { false: disable; true: enable }
References ST_PosPlan_t::ENB.
22.3.6.33 static uint16_t STPOSPLAN_getErrorID ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Error value (ERR_ID) for SpinTAC Position Plan.
272Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
uint16_t ERR_ID Error ID { 0: no error; others: see error code }
References ST_PosPlan_t::ERR_ID.
22.3.6.34 static ST_PlanFsmState_e STPOSPLAN_getFsmState ( ST_POSPLAN_Handlehandle ) [inline], [static]
Gets the State Machine State (FsmState) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
ST_PlanFsmState_e FsmState Current operation of the state machine
References ST_PosPlan_t::FsmState.
22.3.6.35 static _lq20 STPOSPLAN_getJerkLimit ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Jerk Limit (JrkLim) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
_lq20 JrkLim Jerk Limit { unit: [(pu rpm)/s∧2], value range: (0.0, 2000.0] }
References ST_PosPlan_t::JrkLim.
22.3.6.36 static void STPOSPLAN_getPositionStep_mrev ( ST_POSPLAN_Handlehandle, int32_t ∗ posStepInt_mrev, _lq24 ∗ posStepFrac_mrev ) [inline],[static]
Gets the Position Step (posStepInt_mrev, posStepFrac_mrev) for SpinTAC Position Plan.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
273
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
out ∗posStepInt_←↩mrev
Position Step integer part value { unit: [MRev], value range: 32-bitinteger }
out ∗posStepFrac←↩_mrev
Position Step fraction part value { unit: [MRev], value range: (-1.0, 1.0)}
References ST_PosPlan_t::PosStepFrac_mrev, and ST_PosPlan_t::PosStepInt_mrev.
22.3.6.37 static bool STPOSPLAN_getReset ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Reset signal (RES) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
bool RES Reset bit { false: reset; true: not reset }
References ST_PosPlan_t::RES.
22.3.6.38 static ST_PlanStatus_e STPOSPLAN_getStatus ( ST_POSPLAN_Handlehandle ) [inline], [static]
Gets the Status value (STATUS) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
ST_PlanStatus_e STATUS Status { ST_VEL_ID_IDLE, ST_VEL_ID_INIT, ST_VEL_ID_BUSY}
References ST_PosPlan_t::STATUS.
22.3.6.39 void STPOSPLAN_getVar ( ST_POSPLAN_Handle handle, uint16_t VarIdx,_lq24 ∗ Value )
Gets the value of a SpinTAC Position Plan variable.
274Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Variable to get
out ∗Value Value to get from the Variable
22.3.6.40 static _lq24 STPOSPLAN_getVelocityLimit ( ST_POSPLAN_Handle handle )[inline], [static]
Gets the Velocity Limit (VelLim) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
Returns
_lq24 VelLim Velocity limit { unit: [pu rpm], value range: [-1.0, 1.0] }
References ST_PosPlan_t::VelLim.
22.3.6.41 ST_POSPLAN_Handle STPOSPLAN_init ( void ∗ pMemory, const size_tnumBytes )
Initializes the SpinTAC Position Plan component.
Parameters
in ∗pMemory Pointer to the memory for ST_PosPlan_t
in numBytes The number of bytes in the ST_PosPlan_t
Returns
ST_POSPLAN_Handle handle The handle for the SpinTAC Position Plan Object
22.3.6.42 void STPOSPLAN_reset ( ST_POSPLAN_Handle handle )
Resets the SpinAC Position Plan component.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
275
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
22.3.6.43 void STPOSPLAN_run ( ST_POSPLAN_Handle handle )
Runs SpinTAC Position Plan calculation.
Parameters
in handle The handle for the Position Plan structure
22.3.6.44 void STPOSPLAN_runTick ( ST_POSPLAN_Handle handle )
Runs SpinTAC Position Plan Timing. Call this only from an ISR.
Parameters
in handle The handle for the Position Plan structure
22.3.6.45 void STPOSPLAN_setCfg ( ST_POSPLAN_Handle handle, _lq24 T_sec, boolLoopENB )
Configures SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in T_sec Sample Time { unit: [sec], value range: (0, 0.01] }
in LoopENB Sets if SpinTAC Position Plan should continuously run after it reachesthe end { false: Do not continuously run Plan; true: Continuously runPlan }
22.3.6.46 void STPOSPLAN_setCfgAct ( ST_POSPLAN_Handle handle, uint16_t ActIdx,uint16_t State, ST_PlanCond_e AndOr, uint16_t CondIdx1, uint16_t CondIdx2,uint16_t VarIdx, ST_PlanActOptn_e Opt, _lq24 Value, ST_PlanActTrgr_eEnterExit )
Modifies an action in the SpinTAC Position Plan configuration.
276Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in ActIdx Index of the Action to modify
in State Index of the State the Action happens in
in AndOr Condition option for the Action
in CondIdx1 Index of the first Condition to consider for the Action
in CondIdx2 Index of the second Condition to consider for the Action
in VarIdx Index of the Varaible to be acted upon
in Opt Type of Action to perform on the Varaible
in Value Value to use in the Action
in EnterExit State event that will trigger the Action
22.3.6.47 void STPOSPLAN_setCfgArray ( ST_POSPLAN_Handle handle, uint32_t ∗cfgArray, const size_t numBytes, uint16_t MaxActNum, uint16_t MaxCondNum,uint16_t MaxVarNum, uint16_t MaxTranNum, uint16_t MaxStateNum )
Prepares SpinTAC Position Plan data structure.
Parameters
in handle The handle for the Position Plan structure
in ∗cfgArray Pointer to the SpinTAC Position Plan configuration array
in numBytes The number of bytes in the SpinTAC Position Plan configuration array
in MaxActNum Number of Actions
in MaxCondNum Number of Conditions
in MaxVarNum Number of Variables
in MaxTranNum Number of Transitions
in MaxStateNum Number of States
22.3.6.48 void STPOSPLAN_setCfgCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx, uint16_t VarIdx, ST_PlanComp_e Comp, _lq24 Value1, _lq24 Value2)
Modifies a Condition in the SpinTAC Position Plan configuration.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
277
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in CondIdx Index of the Plan Condition to modify
in VarIdx Index of the Plan Variable that will be compared
in Comp Type of comparison that will be done
in Value1 First value to use in the comparison
in Value2 Second value to use in the comparison
22.3.6.49 void STPOSPLAN_setCfgHaltState ( ST_POSPLAN_Handle handle, int32_tPosStepInt_mrev, _lq24 PosStepFrac_mrev, _lq24 VelLim, _lq24 AccLim,_lq20 JrkLim, int32_t Timer_tick )
Configures the SpinTAC Position Plan Halt state.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in PosStepInt_←↩mrev
Position step integer part for Halt State { unit: [MRev], value range: 32bit integer [-2, 2] }
in PosStepFrac_←↩mrev
Position step fraction part for Halt State { unit: [MRev], value range:(-1.0, 1.0) }
in VelLim Velocity limit during Halt state { unit: [pu rpm], value range: (0, 1] }
in AccLim Acceleration limit for Halt state { unit: [(pu rpm)/s], value range: [0.←↩001, 120.0] }
in JrkLim Jerk limit for Halt state { unit: [(pu rpm)/s∧2], value range: [0.0005,2000.0] }
in Timer_tick Minimum amount of time to stay in Halt state { unit: [tick] }
22.3.6.50 void STPOSPLAN_setCfgState ( ST_POSPLAN_Handle handle, uint16_tStateIdx, int32_t PosStepInt_mrev, _lq24 PosStepFrac_mrev, int32_t Timer_tick)
Modifies a state in the SpinTAC Position Plan configuration.
278Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
Parameters
in handle The handle for the SpinTAC Position Plan Object
in StateIdx Index of the State to modify
in PosStepInt_←↩mrev
Position step integer part in State { unit: [MRev], value range: 32 bitinteger (-2∧31, 2∧31) }
in PosStepFrac_←↩mrev
Position step fraction part in State { unit: [MRev], value range: (-1.0,1.0) }
in Timer_tick Minimum time to stay in State { unit: [tick] }
22.3.6.51 void STPOSPLAN_setCfgTran ( ST_POSPLAN_Handle handle, uint16_tTranIdx, uint16_t FromState, uint16_t ToState, ST_PlanCond_e AndOr,uint16_t CondIdx1, uint16_t CondIdx2, _lq24 VelLim, _lq24 AccLim, _lq24DecLim, _lq20 JrkLim )
Modifies a Transition in the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in TranIdx Index of the Transition to modify
in FromState Index of the from State
in ToState Index of the to State
in AndOr Condition option for the Transition
in CondIdx1 Index of the first Condition to consider for the Transition
in CondIdx2 Index of the second Condition to consider for the Transition
in VelLim Velocity limit for the Transition { unit: [pu rpm], value range: [-1.0,1.0] }
in AccLim Acceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
in DecLim Deceleration limit for the Transition { unit: [(pu rpm)/s], value range:[0.001, 120.0] }
Freescale SemiconductorKinetis Motor Suite API Reference Manual
279
SpinTAC™ Position Plan
in JrkLim Jerk limit for the Transition { unit: [(pu rpm)/s∧2], value range: [0.0005,2000.0] }
22.3.6.52 void STPOSPLAN_setCfgVar ( ST_POSPLAN_Handle handle, uint16_t VarIdx,ST_PlanVar_e Type, _lq24 Value )
Modifies a variable in the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Variable to modify
in Type Type of Variable
in Value Initial value of the Variable
22.3.6.53 void STPOSPLAN_setCfgVarCond ( ST_POSPLAN_Handle handle, uint16_tCondIdx, uint16_t VarIdx1, uint16_t VarIdx2, ST_PlanComp_e Comp )
Modifies a Variable Condition to the SpinTAC Position Plan configuration.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in CondIdx Index of the Plan Condition to modify
in VarIdx1 Index of the first Plan Variable that will be compared
in VarIdx2 Index of the second Plan Variable that will be compared
in Comp Type of comparison that will be done
22.3.6.54 static void STPOSPLAN_setEnable ( ST_POSPLAN_Handle handle, bool enb) [inline], [static]
Sets the Enable signal (ENB) for SpinTAC Position Plan.
Parameters
280Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
SpinTAC™ Position Plan
in handle The handle for the SpinTAC Position Plan Object
in enb Enable bit { false: disable; true: enable }
References ST_PosPlan_t::ENB.
22.3.6.55 static void STPOSPLAN_setReset ( ST_POSPLAN_Handle handle, bool res )[inline], [static]
Sets the Reset signal (RES) for SpinTAC Position Plan.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in res Reset bit { false: reset; true: not reset }
References ST_PosPlan_t::RES.
22.3.6.56 void STPOSPLAN_setUnitProfDone ( ST_POSPLAN_Handle handle, boolProDON )
Sets a flag in SpinTAC Position Plan to indicate if the unit profile is complete.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in ProDON Indicates if the unit profile is completed
22.3.6.57 void STPOSPLAN_setVar ( ST_POSPLAN_Handle handle, uint16_t VarIdx,_lq24 Value )
Sets the value of a SpinTAC Position Plan variable.
Parameters
in handle The handle for the SpinTAC Position Plan Object
in VarIdx Index of the Variable to set
in Value Value to set to the Variable
Freescale SemiconductorKinetis Motor Suite API Reference Manual
281
SpinTAC™ Position Plan
282Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 23Math23.1 OverviewProvides core math functions for application.
Functional description
KMS includes files defining the QMath utilized in all other blocks. KMS utilizes Q24 (lq) numbers inthe vast majority of cases, with Q20 and Q16 otherwise specified. For sq numbers, currents are typicallydefined as Q15 with all others being Q14.
The Math block also includes definitions for various PI(D) controllers, frame transforms, and filters.
Code security breakdown
The table below describes the partitioning of Math block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyDifferent available types, conver-sions, PID options that the customercan use
Implementation of PID N/A
Execution
Execution of Math functions depends on where and how they are utilized.
Data Structures• struct FLT_butterAccT32bit_t• struct FLT_butterAccT16bit_t• struct FLT_butterAccE32bit_t• struct PID_pidParam32_t• struct PID_pidReg32_t• struct PID_piParam16_t• struct PID_piReg16_t• struct PID_piParam32_t• struct PID_piReg32_t• struct TRF_s3Vector32_t• struct TRF_sVector16_t
Freescale SemiconductorKinetis Motor Suite API Reference Manual
283
Overview
• struct TRF_sVector32_t• struct TRF_rVector16_t• struct TRF_rVector32_t• struct TRF_orient16_t• struct TRF_orient32_t• struct FLT_butterAccT32bit_s
First order Butterworth filter accumulator type/structure (32-bit, Tustin) More...• struct FLT_butterAccT16bit_s
First order Butterworth filter accumulator type/structure (16-bit, Tustin) More...• struct FLT_butterAccE32bit_s
First order Butterworth filter accumulator type/structure (32-bit, Euler) More...
Macros• #define FLT_RATIO_TUSTIN(cutOffFreqHz, sampleTime) (PI ∗ ((cutOffFreqHz) ∗ (sample←↩
Time)))Calculates filter ratio of Butterworth filter (Tustin implementation) as Pi ∗ (cut-off frequency) ∗ sampletime.
• #define FLT_COEFF_TUSTIN(cutOffFreqHz, sampleTime) (FLT_RATIO_TUSTIN((cutOff←↩FreqHz), (sampleTime)) / (1.0 + FLT_RATIO_TUSTIN((cutOffFreqHz), (sampleTime))))
Calculates Butterworth filter coefficient (Tustin implementation)• #define FLT_RATIO_EULER(cutOffFreqHz, sampleTime) 2.0 ∗ FLT_RATIO_TUSTIN((cutOff←↩
FreqHz), (sampleTime))Calculates filter ratio of Butterworth filter (Euler implementation) as Pi ∗ (cut-off frequency) ∗ sampletime.
• #define FLT_COEFF_EULER(cutOffFreqHz, sampleTime) FLT_RATIO_EULER((cutOffFreq←↩Hz), (sampleTime))
Calculates Butterworth filter coefficient (Euler implementation)• #define FLT_INIT_T_32BIT(cutOffFreqHz, sampleTime) {_LQ(0.0), _LQ(0.0), _LQ(FLT_COE←↩
FF_TUSTIN((cutOffFreqHz), (sampleTime)))}Initializer macro for low/high-pass filter FLT_butterAccT16bit_t type variables (32-bit, Tustin implemen-tation)
• #define FLT_INIT_E_32BIT(cutOffFreqHz, sampleTime) {_LQ(0.0), _LQ(FLT_COEFF_EULE←↩R((cutOffFreqHz), (sampleTime)))}
Initializer macro for low/high-pass filter FLT_butterAccE32bit_t type variables (32-bit, Euler implemen-tation)
• #define PID_PID_REG32_INIT(pid)32-bit PID default initializer for the regulation structure
• #define PID_PI_REG16_INIT(pi)16-bit PI default initializer for the regulation structure
• #define PID_PI_REG32_INIT(pi)32-bit PI default initializer for the regulation structure
• #define MAX(x, y) (((x) > (y))? (x) : (y))Finds maximum of two variables x and y.
• #define MIN(x, y) (((x) < (y))? (x) : (y))Finds minimum of two variables x and y.
• #define GLOBAL_SQ 14Global SQ format definition (value between 1 and 15)
• #define GLOBAL_LQ 24Global LQ format definition (value between 1 and 31)
• #define MAX_LQ_POS ((_lq)0x7FFFFFFFUL)
284Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Maximum positive number in LQ format.• #define MAX_LQ_NEG ((_lq)0x80000000UL)
Maximum negative number in LQ format.• #define MIN_LQ_POS ((_lq) 1)
Minimum positive number in LQ format.• #define MIN_LQ_NEG ((_lq)-1)
Minimum negative number in LQ format.• #define _LQ31(A) ((_lq)((A) ∗ 2147483648.0L))
Converts floating-point number A to LQ31 fixed-point format.• #define _LQ30(A) ((_lq)((A) ∗ 1073741824.0L))
Converts floating-point number A to LQ30 fixed-point format.• #define _LQ24(A) ((_lq)((A) ∗ 16777216.0L))
Converts floating-point number A to LQ24 fixed-point format.• #define _LQ20(A) ((_lq)((A) ∗ 1048576.0L))
Converts floating-point number A to LQ20 fixed-point format.• #define _LQ16(A) ((_lq)((A) ∗ 65536.0L))
Converts floating-point number A to LQ16 fixed-point format.• #define _LQ15(A) ((_lq)((A) ∗ 32768.0L))
Converts floating-point number A to LQ15 fixed-point format.• #define _LQ14(A) ((_lq)((A) ∗ 16384.0L))
Converts floating-point number A to LQ14 fixed-point format.• #define _LQ(A) ((_lq)((A) ∗ 16777216.0L))
Converts floating-point number A to LQ fixed-point format.• #define MAX_SQ_POS ((_sq)0x7FFFU)
Maximum positive number in SQ format.• #define MAX_SQ_NEG ((_sq)0x8000U)
Maximum negative number in SQ format.• #define MIN_SQ_POS ((_sq) 1)
Minimum positive number in SQ format.• #define MIN_SQ_NEG ((_sq)-1)
Minimum negative number in SQ format.• #define _SQ15(A) ((_sq)((A) ∗ 32768.0))
Converts floating-point number A to SQ15 fixed-point format.• #define _SQ8(A) ((_sq)((A) ∗ 256.0))
Converts floating-point number A to SQ8 fixed-point format.• #define _SQ(A) ((_sq)((A) ∗ 16384.0))
Converts floating-point number A to SQ fixed-point format.• #define _LQ_ASR(A, x) /∗lint -save -e649 -e704 -esym(960, 12.7) ∗/ ((_lq)(A) >> (x)) /∗lint -
restore ∗/Arithmetic (signed) shift rigth of 32-bit integer number.
• #define _LQ_ASL(A, x) /∗lint -save -e649 -e703 -esym(960, 12.7) ∗/ ((_lq)(A) << (x)) /∗lint -restore ∗/
Arithmetic (signed) shift left of 32-bit integer number.• #define _SQ_ASR(A, x) /∗lint -save -e649 -e702 -esym(960, 12.7) ∗/ ((_sq)(A) >> (x)) /∗lint -
restore ∗/Arithmetic (signed) shift rigth of 16-bit integer number.
• #define _SQ_ASL(A, x) /∗lint -save -e649 -e701 -esym(960, 12.7) ∗/ ((_sq)(A) << (x)) /∗lint -restore ∗/
Arithmetic (signed) shift left of 16-bit integer number.• #define _SQtoLQ(qx) _SQXtoLQY((qx), GLOBAL_SQ, GLOBAL_LQ)
Converts SQ variable to LQ.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
285
Overview
• #define _LQtoSQ(lq) _LQXtoSQY((lq), GLOBAL_LQ, GLOBAL_SQ)Converts LQ variable to SQ.
• #define _LQtoSQ15(lq) _LQXtoSQY((lq), GLOBAL_LQ, 15)Converts LQ variable to SQ15.
• #define _SQabsFast(x) ((_sq)(((x) < 0) ? (-(x)) : (x)))Calculates absolute value of number in SQ global format (without checking for overflow)
• #define _SQsatFast(x, max, min) (((x) >= (max))? (max) : (((x) <= (min))? (min) : (x)))Limits the value of number in SQ global format between min and max value (fast macro)
• #define _SQmpy(sqx, sqy) _SQZmpySQXY((sqx), GLOBAL_SQ, (sqy), GLOBAL_SQ, GLOB←↩AL_SQ)
Multiplies two numbers in SQ format and gives result in SQ format.• #define _SQmpySQX(sqx, fx, sqy, fy) _SQZmpySQXY(sqx, fx, sqy, fy, GLOBAL_SQ)
Multiplies a number in SQX format with a number in SQY format and gives result in SQ format.• #define _LQmpySQ(sqx, sqy) _LQZmpySQXY((sqx), GLOBAL_SQ, (sqy), GLOBAL_SQ, GL←↩
OBAL_LQ)Multiplies two numbers in SQ format and gives result in LQ format.
• #define _LQZmpySQ(sqx, sqy, fz) _LQZmpySQXY((sqx), GLOBAL_SQ, (sqy), GLOBAL_SQ,(fz))
Multiplies two numbers in SQ format and gives result in LQZ format.• #define _LQZmpySQX(sqx, fx, sqy, fy, fz) _LQZmpySQXY((sqx), (fx), (sqy), (fy), (fz))
Multiplies two numbers in SQX and SQY format and gives result in LQZ format.• #define _LQmpySQX(sqx, fx, sqy, fy) _LQZmpySQXY((sqx), (fx), (sqy), (fy), GLOBAL_LQ)
Multiplies two numbers in SQX and SQY format respectively and gives result in LQ format.• #define _SQ15mpySQX(sqx, fx, sqy, fy) QM_mpy((_lq)(sqx), (_lq)(sqy), (fx) + (fy) - 15)
Multiplies two numbers in SQX and SQY format respectively and gives result in SQ15 format.• #define QM_DIV_TWO_32B_16BRES(x, y) ((_sq)((x) / (y)))
Macro which divides two 32-bit numbers and gives a 16-bit result.• #define QM_DIV_TWO_32B_32BRES(x, y) ((_lq)((x) / (y)))
Macro which divides two 32-bit numbers and gives a 32-bit result.• #define _SQdivISQ(lqx, sqy) _SQZdivISQXY((lqx), GLOBAL_LQ, (sqy), GLOBAL_SQ, GLO←↩
BAL_SQ)Divides two numbers in LQ and SQ format respectively and gives result in SQ format.
• #define _LQabsFast(x) ((_lq)(((x) < 0L) ? (-(x)) : (x)))Calculates absolute value of number in LQ global format (without checking for overflow)
• #define _LQsatFast(x, max, min) (((x) >= (max))? (max) : (((x) <= (min))? (min) : (x)))Limits the value of number in LQ global format between min and max value (fast macro)
• #define _LQmpy(lqx, lqy) QM_mpy((lqx), (lqy), GLOBAL_LQ)Multiplies two signed 32-bit numbers in LQ format and returns a signed 32-bit number in LQ format.
• #define _LQZmpyMiniSQLQXY(sqx, fx, lqy, fy, fz) QM_mpy((_lq)(sqx), (lqy), (((fx) +(fy)) - (fz)))Multiplies a 16-bit signed number with a 32-bit signed number in SQX and LQY formats and returns asigned 32-bit number in LQZ format.
• #define _LQmpyMiniSQLQ(sqx, lqy) QM_mpy((_lq)(sqx), (lqy), GLOBAL_SQ + GLOBAL_LQ- GLOBAL_LQ)
Multiplies a 16-bit signed number with a 32-bit signed number in SQ and LQ formats and returns a signed32-bit number in LQ format.
• #define _LQmpyMiniSQLQX(sqx, fx, lqy, fy) QM_mpy((_lq)(sqx), (lqy), ((fx) + (fy)) - GLOBA←↩L_LQ)
Multiplies two signed a 16-bit signed number with a 32-bit signed number in SQX and LQY formats andreturns a signed 32-bit number in LQ format.
• #define _L32mpyLQL32(l32, lqy) QM_mpy((l32), (lqy), GLOBAL_LQ + 0 - 0)
286Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Multiplies two signed 32-bit numbers in LQ and int32 (LQ0) format respectively and returns a signed32-bit number in LQ0 format.
• #define _LQ20mpyI32(lqx, lqy) QM_mpy((lqx), (lqy), 0)Multiplies two signed 32-bit numbers in LQ20 and int32 format respectively and returns a signed 32-bitnumber in LQ20 format.
• #define _LQmpyI32(lqx, lqy) QM_mpy((lqx), (lqy), 0)Multiplies two signed 32-bit numbers in LQ and int32 format respectively and returns a signed 32-bitnumber in LQ format.
• #define _LQmpyLQX(lqx, fx, lqy, fy) QM_mpy((lqx), (lqy), ((fx) + (fy)) - GLOBAL_LQ)Multiplies two signed 32-bit numbers in LQX and LQY format respectively and returns a signed 32-bitnumber in LQ format.
• #define _LQdiv(lqx, lqy) QM_div((lqx), (lqy), GLOBAL_LQ)Divides two signed 32-bit numbers in LQ format and returns a signed 32-bit number in LQ format.
• #define _LQdivLQX(lqx, fx, lqy, fy) QM_div((lqx), (lqy), GLOBAL_LQ - ((fx) - (fy)))Divides two signed 32-bit numbers in LQX and LQY format respectively and returns a signed 32-bit num-ber in LQ format.
• #define _LQ30mpyLQX(lqx, fx, lqy, fy) QM_mpy((lqx), (lqy), ((fx) + (fy)) - 30)Multiplies two numbers in LQX and LQY format respectively and gives result in LQ30 format.
• #define _LQ20mpyLQX(lqx, fx, lqy, fy) QM_mpy((lqx), (lqy), ((fx) + (fy)) - 20)Multiplies two numbers in LQX and LQY format respectively and gives result in LQ20 format.
• #define _LQ20divLQX(lqx, fx, lqy, fy) QM_div((lqx), (lqy), 20 - ((fx) - (fy)))Divides two numbers in LQX and LQY format respectively and gives result in LQ20 format.
• #define TRF_VECTOR16_DEFAULTS {_SQ(0.0), _SQ(0.0)}16-bit vector initializer
• #define TRF_VECTOR32_DEFAULTS {_LQ(0.0), _LQ(0.0)}32-bit vector initializer
• #define TRF_EXT_VECTOR16_DEFAULTS {TRF_VECTOR16_DEFAULTS, TRF_VECTO←↩R16_DEFAULTS}
16-bit extended vector initializer• #define TRF_EXT_VECTOR32_DEFAULTS {TRF_VECTOR32_DEFAULTS, TRF_VECTO←↩
R32_DEFAULTS}32-bit extended vector initializer
• #define PI (3.1415926535897932384626433832795F)• #define SQRT2 (1.4142135623730950488016887242097F)
Square root of two value.• #define SQRT3 (1.7320508075688772935274463415059F)
Square root of three value.• #define LN9 (2.1972245773362193827904904738451F)
Natural logarithm of 9, i.e ln(9)• #define INV_LN9 (0.45511961331341869680712008286804F)
Inverse of Natural logarithm of 9, i.e 1 / ln(9)• #define LOG2(x)
A quazy-log2 function macro that determines bit-width of input parameter.• #define WORD_SIZE(variable) ((uint16_t)(sizeof(variable) / 2U))
Macro which gives word size (16-bit) for a given variable.• #define DWORD_SIZE(variable) ((uint16_t)(sizeof(variable) / 4U))
Macro which gives double word size (32-bit) for a given variable.• #define LAST_INDEX(table) ((int16_t)(((uint16_t)sizeof(table) / (uint16_t)sizeof((table)[0])) - 1←↩
U))Macro which determines last index of the look-up table/array regardles of the element type (16-bit or
Freescale SemiconductorKinetis Motor Suite API Reference Manual
287
Overview
32-bit)
Typedefs• typedef int32_t _lq
LQ type definition.• typedef _lq _lq24• typedef _lq _lq20• typedef int16_t _sq
SQ type definition.• typedef char char_t
Signed char type.• typedef unsigned char uchar_t
Unsigned char type.• typedef unsigned int bitfield_t
Bitfield type.
Functions• _lq FLT_ratio_Tustin (_lq lq16cutoffHz, _lq Ts)• _lq FLT_coeff_Tustin (_lq lq16cutoffHz, _lq Ts)• _lq FLT_coeff_Euler (_lq lq16cutoffHz, _lq Ts)• FAST _lq FLT_lpf1stT_32bit (FLT_butterAccT32bit_t ∗pflt, _lq input)
Executes first order low-pass Butterworth filter (32-bit Tustin implementation)• FAST _sq FLT_lpf1stT_16bit (FLT_butterAccT16bit_t ∗pflt, _sq input)
Executes first order low-pass Butterworth filter (16-bit Tustin implementation)• FAST _lq FLT_hpf1stT_32bit (FLT_butterAccT32bit_t ∗pflt, _lq input)
Executes first order high-pass Butterworth filter (32-bit Tustin implementation)• FAST _lq FLT_lpf1stE_32bit (FLT_butterAccE32bit_t ∗pflt, _lq input)
Executes first order low-pass Butterworth filter (32-bit forward Euler implementation)• FAST _lq FLT_hpf1stE_32bit (FLT_butterAccE32bit_t ∗pflt, _lq input)
Executes first order high-pass Butterworth filter (32-bit forward Euler implementation)• void PID_processPID32 (PID_pidReg32_t ∗v)
Processes a 32-bit PID regulator.• void PID_processPI32 (PID_piReg32_t ∗v)
Processes a 32-bit PI regulator.• void PID_processPIF32 (PID_piReg32_t ∗v, _lq flterr)
Processes a 32-bit PIF regulator.• void PID_processPIF16 (PID_piReg16_t ∗v, _sq flterr)• static int32_t _LQint (_lq x)
Returns integer value of LQ number.• static _lq _LQfrac (_lq x)
Returns fractional value of LQ number.• static _lq QM_mpy (_lq x, _lq y, int16_t format)
Multiplies two LQ numbers and returns an LQ number.• static _lq _LQXtoLQY (_lq lqx, int16_t x, int16_t y)
Converts signed 32-bit LQx to signed 32-bit LQy representation.• static _sq _LQXtoSQY (_lq lqx, int16_t x, int16_t y)
Converts signed 32-bit LQx to signed 16-bit SQy representation.• static _lq _SQXtoLQY (_sq qx, int16_t x, int16_t y)
Converts signed 16-bit SQx to signed 32-bit LQy representation.• int16_t QM_divTwo32bSNum16bRes (int32_t numerator, int32_t denominator)
288Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Overview
Divides two 32-bit signed integer numbers and returns a 16-bit signed integer number.• _sq _SQsat (_sq x, _sq max, _sq min)
Limits the value of number in SQ global format between min and max value.• static _lq _LQZmpySQXY (_sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz)
Multiplies two signed numbers in SQX and SQY formats and returns result in LQZ format.• static _sq _SQZmpySQXY (_sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz)
Multiplies two signed numbers in SQX and SQY formats and returns result in SQZ format.• static _lq _LQZdivSQXY (_sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz)
Divides two signed numbers in SQX and SQY format and returns number in LQZ format.• static _sq _SQZdivISQXY (_lq lqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz)
Divides two signed numbers (32 and 16-bit) in LQX ans SQY format and gives result in SQZ format.• static _lq _LQZdivISQXY (_lq lqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz)
Divides two signed numbers (32 and 16-bit) in LQX ans SQY format and gives result in LQZ format.• _lq QM_div (_lq numerator, _lq denominator, int16_t format)
Divides two LQ numbers and returns an LQX number in a designated X format.• _lq _LQabs (_lq x)• _lq _LQsat (_lq x, _lq max, _lq min)
Limits the value of number in LQ global format between min and max value.• _lq _LQsinPU (_lq angle)
Returns sine of PU angle (-1 to 1, which corresponds to -PI to PI)• _lq _LQcosPU (_lq angle)
Returns cosine of PU angle (-1 to 1, which corresponds to -PI to PI)• _lq _LQsqrt (_lq x)
Square-root function (for input values 0-1)• _lq20 _LQ20sqrt (_lq20 input)
Square-root function (for input values 0-1)• _lq _LQexp (_lq x)
Exponential function (for input values 0-1)• _lq20 _LQ20exp (_lq20 x)
Exponential function (for input values 0-1)• _lq24 _LQlog (_lq24 x)
Log base 10 function (for input values 0-1)• _lq20 _LQ20log (_lq20 x)
Log base 10 function (for input values 0-1)• _lq _LQatan2PU (_lq lqy, _lq lqx)
Returns angle of atan(y/x) in PU range (-PI, PI)• void _LQsincosPU (_lq angle, _lq ∗pSin, _lq ∗pCos)• int32_t qmath_version (void)
Returns the version number of the QMath Library.• static void TRF_park32 (const TRF_orient32_t ∗const pOrient, const TRF_sVector32_t ∗const p←↩
VectorAB, TRF_rVector32_t ∗const pVectorDQ)Direct Park transform of a 32-bit alpha-beta vector into a 32-bit d-q vector.
• static void TRF_park32_16_SQ15 (const TRF_orient32_t ∗pOrient, const TRF_sVector16_t ∗p←↩VectorAB, TRF_rVector16_t ∗pVectorDQ)
Direct Park transform of a 16-bit alpha-beta vector into a 16-bit d-q vector (by using 32-bit sine/cosinevalues)
• static void TRF_iPark32 (const TRF_orient32_t ∗pOrient, const TRF_rVector32_t ∗pVectorDQ, T←↩RF_sVector32_t ∗pVectorAB)
Inverse Park transform of a 32-bit d-q vector into a 32-bit alpha-beta vector.• static void TRF_clarkeLarge32 (_lq a, _lq b, _lq c, TRF_sVector32_t ∗pVectorAB)
Direct Clarke transform of a 32-bit a-b-c vector into a 32-bit alpha-beta vector.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
289
Data Structure Documentation
• static _lq UTIL_angleWrapAround (const _lq inputAngle)Angle wrap-around function.
• static _sq UTIL_arcUponChord (bool enableDCInjection, _lq speedEst, _lq anglexTslowscale, _←↩lq(∗p_LQsinPU)(_lq x))
23.2 Data Structure Documentation
23.2.1 struct FLT_butterAccT32bit_t
Data Fields
_lq coeff Butterworth filter coefficient
_lq inputOld Butterworth filter old input sample
_lq outputOld Butterworth filter old output sample
23.2.2 struct FLT_butterAccT16bit_t
Data Fields
_sq coeff Butterworth filter coefficient
_sq inputOld Butterworth filter old input sample
_sq outputOld Butterworth filter old output sample
23.2.3 struct FLT_butterAccE32bit_t
Data Fields
_lq coeff Butterworth filter coefficient
_lq outputOld Butterworth filter old output sample
23.2.4 struct PID_pidParam32_t
Data Fields
290Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
bool activeTustin Tustin or Euler implementation
_lq Kd Derivative gain
_lq Ki Integral gain
_lq Kp Proportional gain
_lq outMax Maximum output limit
_lq outMin Minimum output limit
23.2.5 struct PID_pidReg32_t
Data Fields
_lq error PID error term
_lq errorOld PID old error term
_lq outPreSat Pre-saturated output
_lq output PID output
PID_pid←↩Param32_t
const ∗
pid Pointer to PID parameters
_lq Ud Derivative term
_lq Ui Integral term
_lq Up Proportional term
_lq upOld Old proportional term
23.2.6 struct PID_piParam16_t
Data Fields
bool activeTustin Tustin or Euler implementation
_sq Kc Anti-windup correction gain (SQ)
_sq Ki Integral gain (SQ)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
291
Data Structure Documentation
_sq Kp Proportional gain (UQ)
_sq outMax Maximum output limit (SQ)
_sq outMin Minimum output limit (SQ)
23.2.7 struct PID_piReg16_t
Data Fields
_sq error PI error term
_sq errorOld PI old error term
_lq feedForward Feed-forward term
_lq outPreSat Pre-saturated output
_lq output PI output
PID_pi←↩Param16_t
const ∗
pi Pointer to PI parameters
_sq satErr Saturated difference
_lq Ui Integral term
_lq Up Proportional term
23.2.8 struct PID_piParam32_t
Data Fields
bool activeTustin Tustin or Euler implementation
_lq Kc Anti-windup correction gain
_lq Ki Integral gain
_lq Kp Proportional gain
_lq outMax Maximum output limit
292Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Data Structure Documentation
_lq outMin Minimum output limit
23.2.9 struct PID_piReg32_t
Data Fields
_lq error PI error term
_lq errorOld PI old error term
_lq feedForward Feed-forward term
_lq outPreSat Pre-saturated output
_lq output PI output
PID_pi←↩Param32_t
const ∗
pi Pointer to PI parameters
_lq satErr Saturated difference
_lq Ui Integral term
_lq Up Proportional term
23.2.10 struct TRF_s3Vector32_t
Data Fields
_lq a a axis component
_lq b b axis component
_lq c c axis component
23.2.11 struct TRF_sVector16_t
Data Fields
Freescale SemiconductorKinetis Motor Suite API Reference Manual
293
Data Structure Documentation
_sq A Alpha axis component
_sq B Beta axis component
23.2.12 struct TRF_sVector32_t
Data Fields
_lq A Alpha axis component
_lq B Beta axis component
23.2.13 struct TRF_rVector16_t
Data Fields
_sq d D-axis component
_sq q Q-axis component
23.2.14 struct TRF_rVector32_t
Data Fields
_lq d D-axis component
_lq q Q-axis component
23.2.15 struct TRF_orient16_t
Data Fields
_sq cosAngle cosine value of the field angle
_sq sinAngle sine value of the field angle
23.2.16 struct TRF_orient32_t
294Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
Data Fields
_lq cosAngle cosine value of the field angle
_lq sinAngle sine value of the field angle
23.2.17 struct FLT_butterAccT32bit_s
First order Butterworth filter accumulator type/structure (32-bit, Tustin)
23.2.18 struct FLT_butterAccT16bit_s
First order Butterworth filter accumulator type/structure (16-bit, Tustin)
23.2.19 struct FLT_butterAccE32bit_s
First order Butterworth filter accumulator type/structure (32-bit, Euler)
23.3 Macro Definition Documentation
23.3.1 #define _L32mpyLQL32( l32, lqy ) QM_mpy((l32), (lqy), GLOBAL_LQ + 0- 0)
Multiplies two signed 32-bit numbers in LQ and int32 (LQ0) format respectively and returns a signed32-bit number in LQ0 format.
23.3.2 #define _LQ( A ) ((_lq)((A) ∗ 16777216.0L))
Converts floating-point number A to LQ fixed-point format.
Referenced by DSM_startState(), FEEDBACK_run(), TRF_clarkeLarge32(), USER_cfgSCM(), USE←↩R_resetDRVCommands(), USER_runBrakeStateSlowTick(), USER_runScmState(), UTIL_angleWrap←↩Around(), and UTIL_arcUponChord().
23.3.3 #define _LQ14( A ) ((_lq)((A) ∗ 16384.0L))
Converts floating-point number A to LQ14 fixed-point format.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
295
Macro Definition Documentation
23.3.4 #define _LQ15( A ) ((_lq)((A) ∗ 32768.0L))
Converts floating-point number A to LQ15 fixed-point format.
23.3.5 #define _LQ16( A ) ((_lq)((A) ∗ 65536.0L))
Converts floating-point number A to LQ16 fixed-point format.
23.3.6 #define _LQ20( A ) ((_lq)((A) ∗ 1048576.0L))
Converts floating-point number A to LQ20 fixed-point format.
23.3.7 #define _LQ20divLQX( lqx, fx, lqy, fy ) QM_div((lqx), (lqy), 20 - ((fx) -(fy)))
Divides two numbers in LQX and LQY format respectively and gives result in LQ20 format.
23.3.8 #define _LQ20mpyI32( lqx, lqy ) QM_mpy((lqx), (lqy), 0)
Multiplies two signed 32-bit numbers in LQ20 and int32 format respectively and returns a signed 32-bitnumber in LQ20 format.
23.3.9 #define _LQ20mpyLQX( lqx, fx, lqy, fy ) QM_mpy((lqx), (lqy), ((fx) + (fy))- 20)
Multiplies two numbers in LQX and LQY format respectively and gives result in LQ20 format.
23.3.10 #define _LQ24( A ) ((_lq)((A) ∗ 16777216.0L))
Converts floating-point number A to LQ24 fixed-point format.
23.3.11 #define _LQ30( A ) ((_lq)((A) ∗ 1073741824.0L))
Converts floating-point number A to LQ30 fixed-point format.
Referenced by TRF_park32_16_SQ15().
296Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
23.3.12 #define _LQ30mpyLQX( lqx, fx, lqy, fy ) QM_mpy((lqx), (lqy), ((fx) +(fy)) - 30)
Multiplies two numbers in LQX and LQY format respectively and gives result in LQ30 format.
23.3.13 #define _LQ31( A ) ((_lq)((A) ∗ 2147483648.0L))
Converts floating-point number A to LQ31 fixed-point format.
23.3.14 #define _LQ_ASL( A, x ) /∗lint -save -e649 -e703 -esym(960, 12.7) ∗/((_lq)(A) << (x)) /∗lint -restore ∗/
Arithmetic (signed) shift left of 32-bit integer number.
Referenced by _LQXtoLQY(), _LQZdivISQXY(), _LQZdivSQXY(), _LQZmpySQXY(), and _SQXto←↩LQY().
23.3.15 #define _LQ_ASR( A, x ) /∗lint -save -e649 -e704 -esym(960, 12.7) ∗/((_lq)(A) >> (x)) /∗lint -restore ∗/
Arithmetic (signed) shift rigth of 32-bit integer number.
Referenced by _LQXtoLQY(), _LQZdivISQXY(), _LQZdivSQXY(), _LQZmpySQXY(), and _SQXto←↩LQY().
23.3.16 #define _LQabsFast( x ) ((_lq)(((x) < 0L) ? (-(x)) : (x)))
Calculates absolute value of number in LQ global format (without checking for overflow)
Referenced by DSM_runTimeMonitor(), DSM_updateSlowTick(), and UTIL_arcUponChord().
23.3.17 #define _LQdiv( lqx, lqy ) QM_div((lqx), (lqy), GLOBAL_LQ)
Divides two signed 32-bit numbers in LQ format and returns a signed 32-bit number in LQ format.
Referenced by FEEDBACK_run().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
297
Macro Definition Documentation
23.3.18 #define _LQdivLQX( lqx, fx, lqy, fy ) QM_div((lqx), (lqy), GLOBAL_LQ- ((fx) - (fy)))
Divides two signed 32-bit numbers in LQX and LQY format respectively and returns a signed 32-bitnumber in LQ format.
23.3.19 #define _LQmpy( lqx, lqy ) QM_mpy((lqx), (lqy), GLOBAL_LQ)
Multiplies two signed 32-bit numbers in LQ format and returns a signed 32-bit number in LQ format.
Referenced by DSM_startState(), TRF_clarkeLarge32(), TRF_iPark32(), TRF_park32(), and UTIL_arc←↩UponChord().
23.3.20 #define _LQmpyI32( lqx, lqy ) QM_mpy((lqx), (lqy), 0)
Multiplies two signed 32-bit numbers in LQ and int32 format respectively and returns a signed 32-bitnumber in LQ format.
23.3.21 #define _LQmpyLQX( lqx, fx, lqy, fy ) QM_mpy((lqx), (lqy), ((fx) + (fy)) -GLOBAL_LQ)
Multiplies two signed 32-bit numbers in LQX and LQY format respectively and returns a signed 32-bitnumber in LQ format.
23.3.22 #define _LQmpyMiniSQLQ( sqx, lqy ) QM_mpy((_lq)(sqx), (lqy),GLOBAL_SQ + GLOBAL_LQ - GLOBAL_LQ)
Multiplies a 16-bit signed number with a 32-bit signed number in SQ and LQ formats and returns a signed32-bit number in LQ format.
23.3.23 #define _LQmpyMiniSQLQX( sqx, fx, lqy, fy ) QM_mpy((_lq)(sqx),(lqy), ((fx) + (fy)) - GLOBAL_LQ)
Multiplies two signed a 16-bit signed number with a 32-bit signed number in SQX and LQY formats andreturns a signed 32-bit number in LQ format.
298Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
23.3.24 #define _LQmpySQ( sqx, sqy ) _LQZmpySQXY((sqx), GLOBAL_SQ,(sqy), GLOBAL_SQ, GLOBAL_LQ)
Multiplies two numbers in SQ format and gives result in LQ format.
23.3.25 #define _LQmpySQX( sqx, fx, sqy, fy ) _LQZmpySQXY((sqx), (fx),(sqy), (fy), GLOBAL_LQ)
Multiplies two numbers in SQX and SQY format respectively and gives result in LQ format.
23.3.26 #define _LQsatFast( x, max, min ) (((x) >= (max))? (max) : (((x) <=(min))? (min) : (x)))
Limits the value of number in LQ global format between min and max value (fast macro)
Referenced by TRF_park32_16_SQ15().
23.3.27 #define _LQtoSQ( lq ) _LQXtoSQY((lq), GLOBAL_LQ, GLOBAL_SQ)
Converts LQ variable to SQ.
Referenced by DSM_updateSlowTick(), FEEDBACK_config(), and UTIL_arcUponChord().
23.3.28 #define _LQtoSQ15( lq ) _LQXtoSQY((lq), GLOBAL_LQ, 15)
Converts LQ variable to SQ15.
23.3.29 #define _LQZmpyMiniSQLQXY( sqx, fx, lqy, fy, fz) QM_mpy((_lq)(sqx), (lqy), (((fx) +(fy)) - (fz)))
Multiplies a 16-bit signed number with a 32-bit signed number in SQX and LQY formats and returns asigned 32-bit number in LQZ format.
Referenced by TRF_park32_16_SQ15().
23.3.30 #define _LQZmpySQ( sqx, sqy, fz ) _LQZmpySQXY((sqx),GLOBAL_SQ, (sqy), GLOBAL_SQ, (fz))
Multiplies two numbers in SQ format and gives result in LQZ format.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
299
Macro Definition Documentation
23.3.31 #define _LQZmpySQX( sqx, fx, sqy, fy, fz ) _LQZmpySQXY((sqx),(fx), (sqy), (fy), (fz))
Multiplies two numbers in SQX and SQY format and gives result in LQZ format.
23.3.32 #define _SQ( A ) ((_sq)((A) ∗ 16384.0))
Converts floating-point number A to SQ fixed-point format.
Referenced by UTIL_arcUponChord().
23.3.33 #define _SQ15( A ) ((_sq)((A) ∗ 32768.0))
Converts floating-point number A to SQ15 fixed-point format.
Referenced by USER_resetDRVCommands(), USER_runBrakeStateSlowTick(), USER_runInertia←↩State(), and USER_runScmState().
23.3.34 #define _SQ15mpySQX( sqx, fx, sqy, fy ) QM_mpy((_lq)(sqx),(_lq)(sqy), (fx) + (fy) - 15)
Multiplies two numbers in SQX and SQY format respectively and gives result in SQ15 format.
23.3.35 #define _SQ8( A ) ((_sq)((A) ∗ 256.0))
Converts floating-point number A to SQ8 fixed-point format.
23.3.36 #define _SQ_ASL( A, x ) /∗lint -save -e649 -e701 -esym(960, 12.7) ∗/((_sq)(A) << (x)) /∗lint -restore ∗/
Arithmetic (signed) shift left of 16-bit integer number.
Referenced by _SQZdivISQXY().
23.3.37 #define _SQ_ASR( A, x ) /∗lint -save -e649 -e702 -esym(960, 12.7) ∗/((_sq)(A) >> (x)) /∗lint -restore ∗/
Arithmetic (signed) shift rigth of 16-bit integer number.
Referenced by _SQZdivISQXY().
300Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
23.3.38 #define _SQabsFast( x ) ((_sq)(((x) < 0) ? (-(x)) : (x)))
Calculates absolute value of number in SQ global format (without checking for overflow)
Referenced by DSM_updateAtFastTick().
23.3.39 #define _SQdivISQ( lqx, sqy ) _SQZdivISQXY((lqx), GLOBAL_LQ,(sqy), GLOBAL_SQ, GLOBAL_SQ)
Divides two numbers in LQ and SQ format respectively and gives result in SQ format.
Referenced by UTIL_arcUponChord().
23.3.40 #define _SQmpy( sqx, sqy ) _SQZmpySQXY((sqx), GLOBAL_SQ, (sqy),GLOBAL_SQ, GLOBAL_SQ)
Multiplies two numbers in SQ format and gives result in SQ format.
23.3.41 #define _SQmpySQX( sqx, fx, sqy, fy ) _SQZmpySQXY(sqx, fx, sqy,fy, GLOBAL_SQ)
Multiplies a number in SQX format with a number in SQY format and gives result in SQ format.
Referenced by FEEDBACK_run().
23.3.42 #define _SQsatFast( x, max, min ) (((x) >= (max))? (max) : (((x) <=(min))? (min) : (x)))
Limits the value of number in SQ global format between min and max value (fast macro)
23.3.43 #define _SQtoLQ( qx ) _SQXtoLQY((qx), GLOBAL_SQ, GLOBAL_LQ)
Converts SQ variable to LQ.
Referenced by FEEDBACK_run().
23.3.44 #define DWORD_SIZE( variable ) ((uint16_t)(sizeof(variable) / 4U))
Macro which gives double word size (32-bit) for a given variable.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
301
Macro Definition Documentation
Parameters
variable - variable which size has to be determined
Returns
16-bit unsigned number that represent the double word size
23.3.45 #define FLT_COEFF_EULER( cutOffFreqHz, sampleTime) FLT_RATIO_EULER((cutOffFreqHz), (sampleTime))
Calculates Butterworth filter coefficient (Euler implementation)
Parameters
cutOffFreqHz - cut-off frequency in Hz
sampleTime - sample time in s
23.3.46 #define FLT_COEFF_TUSTIN( cutOffFreqHz, sampleTime) (FLT_RATIO_TUSTIN((cutOffFreqHz), (sampleTime)) / (1.0 +FLT_RATIO_TUSTIN((cutOffFreqHz), (sampleTime))))
Calculates Butterworth filter coefficient (Tustin implementation)
Parameters
cutOffFreqHz - cut-off frequency in Hz
sampleTime - sample time in s
23.3.47 #define FLT_INIT_E_32BIT( cutOffFreqHz, sampleTime ) {_LQ(0.0),_LQ(FLT_COEFF_EULER((cutOffFreqHz), (sampleTime)))}
Initializer macro for low/high-pass filter FLT_butterAccE32bit_t type variables (32-bit, Euler implemen-tation)
302Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
Parameters
cutOffFreqHz - Butterworth filter cut-off frequency in Hz
sampleTime - sample time in s
23.3.48 #define FLT_INIT_T_32BIT( cutOffFreqHz, sampleTime ) {_LQ(0.0),_LQ(0.0), _LQ(FLT_COEFF_TUSTIN((cutOffFreqHz), (sampleTime)))}
Initializer macro for low/high-pass filter FLT_butterAccT16bit_t type variables (32-bit, Tustin implemen-tation)
Parameters
cutOffFreqHz - Butterworth filter cut-off frequency in Hz
sampleTime - sample time in s
23.3.49 #define FLT_RATIO_EULER( cutOffFreqHz, sampleTime ) 2.0 ∗FLT_RATIO_TUSTIN((cutOffFreqHz), (sampleTime))
Calculates filter ratio of Butterworth filter (Euler implementation) as Pi ∗ (cut-off frequency) ∗ sampletime.
Parameters
cutOffFreqHz - cut-off frequency in Hz
sampleTime - sample time in s
23.3.50 #define FLT_RATIO_TUSTIN( cutOffFreqHz, sampleTime ) (PI ∗((cutOffFreqHz) ∗ (sampleTime)))
Calculates filter ratio of Butterworth filter (Tustin implementation) as Pi ∗ (cut-off frequency) ∗ sampletime.
Filter coefficients
Parameters
Freescale SemiconductorKinetis Motor Suite API Reference Manual
303
Macro Definition Documentation
cutOffFreqHz - cut-off frequency in Hz
sampleTime - sample time in s
23.3.51 #define GLOBAL_LQ 24
Global LQ format definition (value between 1 and 31)
Referenced by TRF_park32_16_SQ15().
23.3.52 #define GLOBAL_SQ 14
Global SQ format definition (value between 1 and 15)
Referenced by FEEDBACK_run().
23.3.53 #define INV_LN9 (0.45511961331341869680712008286804F)
Inverse of Natural logarithm of 9, i.e 1 / ln(9)
23.3.54 #define LAST_INDEX( table ) ((int16_t)(((uint16_t)sizeof(table) /(uint16_t)sizeof((table)[0])) - 1U))
Macro which determines last index of the look-up table/array regardles of the element type (16-bit or32-bit)
Parameters
table - loop-up table/array
Returns
16-bit signed number that represent the last index
23.3.55 #define LN9 (2.1972245773362193827904904738451F)
Natural logarithm of 9, i.e ln(9)
304Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
23.3.56 #define LOG2( x )
Value:
/*lint -save -e506 */ \((((int8_t)(x)) > 128)? 8 : \((((int8_t)(x)) > 64)? 7 : \((((int8_t)(x)) > 32)? 6 : \((((int8_t)(x)) > 16)? 5 : \((((int8_t)(x)) > 8)? 4 : \((((int8_t)(x)) > 4)? 3 : \((((int8_t)(x)) > 2)? 2 : \((((int8_t)(x)) > 1)? 1 : \0)))))))) /*lint -restore */
A quazy-log2 function macro that determines bit-width of input parameter.
Parameters
x - input parameter (byte size maximum)
23.3.57 #define MAX( x, y ) (((x) > (y))? (x) : (y))
Finds maximum of two variables x and y.
Parameters
x - vairable x
y - variable y
23.3.58 #define MAX_LQ_NEG ((_lq)0x80000000UL)
Maximum negative number in LQ format.
23.3.59 #define MAX_LQ_POS ((_lq)0x7FFFFFFFUL)
Maximum positive number in LQ format.
23.3.60 #define MAX_SQ_NEG ((_sq)0x8000U)
Maximum negative number in SQ format.
Referenced by _LQXtoSQY().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
305
Macro Definition Documentation
23.3.61 #define MAX_SQ_POS ((_sq)0x7FFFU)
Maximum positive number in SQ format.
Referenced by _LQXtoSQY().
23.3.62 #define MIN( x, y ) (((x) < (y))? (x) : (y))
Finds minimum of two variables x and y.
Parameters
x - variable x
y - variable y
23.3.63 #define MIN_LQ_NEG ((_lq)-1)
Minimum negative number in LQ format.
23.3.64 #define MIN_LQ_POS ((_lq) 1)
Minimum positive number in LQ format.
23.3.65 #define MIN_SQ_NEG ((_sq)-1)
Minimum negative number in SQ format.
23.3.66 #define MIN_SQ_POS ((_sq) 1)
Minimum positive number in SQ format.
23.3.67 #define PI (3.1415926535897932384626433832795F)
Referenced by UTIL_arcUponChord().
23.3.68 #define PID_PI_REG16_INIT( pi )
Value:
306Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
{ \&(pi), /**< Address of PI parameters structure */ \_SQ(0.0), /**< PI error term */ \_SQ(0.0), /**< PI old error term */\_LQ(0.0), /**< Proportional term */ \_LQ(0.0), /**< Integral term */ \_LQ(0.0), /**< Feed-forward */ \_LQ(0.0), /**< Pre-saturated output */ \_SQ(0.0), /**< Saturated difference */ \_LQ(0.0) /**< PI output */ \
}
16-bit PI default initializer for the regulation structure
Parameters
pi - 16-bit PI regulation structure
23.3.69 #define PID_PI_REG32_INIT( pi )
Value:
{ \&(pi), /**< Address of PI parameters structure */ \_LQ(0.0), /**< PI error term */ \_LQ(0.0), /**< PI old error term */\_LQ(0.0), /**< Proportional term */ \_LQ(0.0), /**< Integral term */ \_LQ(0.0), /**< Feed-forward */ \_LQ(0.0), /**< Pre-saturated output */ \_LQ(0.0), /**< Saturated difference */ \_LQ(0.0) /**< PI output */ \
}
32-bit PI default initializer for the regulation structure
Parameters
pi - 32-bit PI regulation structure
23.3.70 #define PID_PID_REG32_INIT( pid )
Value:
{ \&(pid), /**< Address of PID parameters structure */ \_LQ(0.0), /**< PID error term */ \_LQ(0.0), /**< PID old error term */ \_LQ(0.0), /**< Proportional term */ \_LQ(0.0), /**< Old proportional term */ \_LQ(0.0), /**< Integral term */ \
Freescale SemiconductorKinetis Motor Suite API Reference Manual
307
Macro Definition Documentation
_LQ(0.0), /**< Derivative term */ \_LQ(0.0), /**< Pre-saturated output */ \_LQ(0.0) /**< PID output */ \
}
32-bit PID default initializer for the regulation structure
Parameters
pid - 32-bit PID regulation structure
23.3.71 #define QM_DIV_TWO_32B_16BRES( x, y ) ((_sq)((x) / (y)))
Macro which divides two 32-bit numbers and gives a 16-bit result.
Referenced by _SQZdivISQXY().
23.3.72 #define QM_DIV_TWO_32B_32BRES( x, y ) ((_lq)((x) / (y)))
Macro which divides two 32-bit numbers and gives a 32-bit result.
Referenced by _LQZdivISQXY(), and _LQZdivSQXY().
23.3.73 #define SQRT2 (1.4142135623730950488016887242097F)
Square root of two value.
23.3.74 #define SQRT3 (1.7320508075688772935274463415059F)
Square root of three value.
Referenced by TRF_clarkeLarge32().
23.3.75 #define TRF_EXT_VECTOR16_DEFAULTS {TRF_VECTOR16_DEFAULT←↩S, TRF_VECTOR16_DEFAULTS}
16-bit extended vector initializer
308Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Typedef Documentation
23.3.76 #define TRF_EXT_VECTOR32_DEFAULTS {TRF_VECTOR32_DEFAULT←↩S, TRF_VECTOR32_DEFAULTS}
32-bit extended vector initializer
23.3.77 #define TRF_VECTOR16_DEFAULTS {_SQ(0.0), _SQ(0.0)}
16-bit vector initializer
23.3.78 #define TRF_VECTOR32_DEFAULTS {_LQ(0.0), _LQ(0.0)}
32-bit vector initializer
23.3.79 #define WORD_SIZE( variable ) ((uint16_t)(sizeof(variable) / 2U))
Macro which gives word size (16-bit) for a given variable.
Parameters
variable - variable which size has to be determined
Returns
16-bit unsigned number that represent the word size
23.4 Typedef Documentation
23.4.1 _lq
LQ type definition.
23.4.2 typedef _lq _lq20
23.4.3 typedef _lq _lq24
23.4.4 _sq
SQ type definition.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
309
Function Documentation
23.4.5 bitfield_t
Bitfield type.
23.4.6 char_t
Signed char type.
23.4.7 uchar_t
Unsigned char type.
23.5 Function Documentation23.5.1 _lq _LQ20exp ( _lq20 x )
Exponential function (for input values 0-1)
Parameters
x - Exponential argument (LQ20 format)
Returns
Exponential value (LQ20 format)
23.5.2 _lq _LQ20log ( _lq20 x )
Log base 10 function (for input values 0-1)
Parameters
x - Log argument (LQ20 format)
Returns
Log base 10 value (LQ20 format)
23.5.3 _lq20 _LQ20sqrt ( _lq20 x )
Square-root function (for input values 0-1)
310Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
x - square-root argument (LQ20 format)
Returns
Square-root value (LQ20 format)
23.5.4 _lq _LQabs ( _lq x )
Referenced by DSM_updateSlowTick().
23.5.5 _lq _LQatan2PU ( _lq lqy, _lq lqx )
Returns angle of atan(y/x) in PU range (-PI, PI)
Parameters
lqy numerator argument (LQ format)
lqx denominator argument (LQ format)
Returns
PU angle (LQ format)
23.5.6 _lq _LQcosPU ( _lq angle )
Returns cosine of PU angle (-1 to 1, which corresponds to -PI to PI)
Parameters
angle - PU angle (LQ format)
Returns
Cosine value (LQ format)
23.5.7 _lq _LQexp ( _lq x )
Exponential function (for input values 0-1)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
311
Function Documentation
Parameters
x - Exponential argument (LQ format)
Returns
Exponential value (LQ format)
23.5.8 _lq _LQfrac ( _lq x ) [inline], [static]
Returns fractional value of LQ number.
Parameters
x - LQ number to return fractional portion of
Returns
fractional portion of LQ number x
23.5.9 _lq _LQint ( _lq x ) [inline], [static]
Returns integer value of LQ number.
Parameters
x - LQ number to return integer portion of
Returns
integer portion of LQ number x
23.5.10 _lq _LQlog ( _lq24 x )
Log base 10 function (for input values 0-1)
312Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
x - Log argument (LQ format)
Returns
Log base 10 value (LQ format)
23.5.11 _lq _LQsat ( _lq x, _lq max, _lq min )
Limits the value of number in LQ global format between min and max value.
Parameters
x - number in LQ global format
max - upper limit
min - lower limit
Returns
Limited value
Referenced by DSM_startState().
23.5.12 void _LQsincosPU ( _lq angle, _lq ∗ pSin, _lq ∗ pCos )
Referenced by USER_runScmState().
23.5.13 _lq _LQsinPU ( _lq angle )
Returns sine of PU angle (-1 to 1, which corresponds to -PI to PI)
Parameters
angle - PU angle (LQ format)
Returns
Sine value (LQ format)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
313
Function Documentation
23.5.14 _lq _LQsqrt ( _lq x )
Square-root function (for input values 0-1)
Parameters
x - square-root argument (LQ format)
Returns
Square-root value (LQ format)
Referenced by DSM_updateSlowTick().
23.5.15 _lq _LQXtoLQY ( _lq lqx, int16_t x, int16_t y ) [inline], [static]
Converts signed 32-bit LQx to signed 32-bit LQy representation.
Parameters
lqx - LQx format number to convert
x - input significance (1 <= x <= 31)
y - output significance (1 <= y <= 31)
Returns
LQy representation of LQx
References _LQ_ASL, and _LQ_ASR.
Referenced by _LQXtoSQY().
23.5.16 _sq _LQXtoSQY ( _lq lqx, int16_t x, int16_t y ) [inline], [static]
Converts signed 32-bit LQx to signed 16-bit SQy representation.
Parameters
314Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
lqx - LQx format number to convert
x - input significance (1 <= x <= 31)
y - output significance (0 <= y <= 15)
Returns
SQy representation of LQx
References _LQXtoLQY(), MAX_SQ_NEG, and MAX_SQ_POS.
Referenced by TRF_park32_16_SQ15().
23.5.17 _lq _LQZdivISQXY ( _lq lqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz )[inline], [static]
Divides two signed numbers (32 and 16-bit) in LQX ans SQY format and gives result in LQZ format.
Parameters
lqx - signed number in LQX format
fx - format of lqx number
sqy- signed number in SQY format
fy - format of sqy number
fz - format of the result
Returns
number in LQZ format
References _LQ_ASL, _LQ_ASR, and QM_DIV_TWO_32B_32BRES.
23.5.18 _lq _LQZdivSQXY ( _sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz )[inline], [static]
Divides two signed numbers in SQX and SQY format and returns number in LQZ format.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
315
Function Documentation
Parameters
sqx - signed number in SQX format
fx - format of sqx number
sqy - signed number in SQY format
fy - format of sqy number
fz - format of the result
Returns
number in LQZ format
References _LQ_ASL, _LQ_ASR, and QM_DIV_TWO_32B_32BRES.
23.5.19 _lq _LQZmpySQXY ( _sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz )[inline], [static]
Multiplies two signed numbers in SQX and SQY formats and returns result in LQZ format.
Parameters
sqx - signed number in SQX format
fx - format of sqx number
sqy - signed number in SQY format
fy - format of sqy number
fz - format of the result
Returns
number in LQZ format
References _LQ_ASL, and _LQ_ASR.
Referenced by _SQZmpySQXY().
23.5.20 _sq _SQsat ( _sq x, _sq max, _sq min )
Limits the value of number in SQ global format between min and max value.
316Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
x - number in SQ global format
max - upper limit
min - lower limit
Returns
Limited value
23.5.21 _lq _SQXtoLQY ( _sq qx, int16_t x, int16_t y ) [inline], [static]
Converts signed 16-bit SQx to signed 32-bit LQy representation.
Parameters
qx - SQx number to convert
x - input significance (0 <= x <= 15)
y - output significance (1 <= y <= 31)
Returns
LQy representation of SQx
References _LQ_ASL, and _LQ_ASR.
23.5.22 _sq _SQZdivISQXY ( _lq lqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz )[inline], [static]
Divides two signed numbers (32 and 16-bit) in LQX ans SQY format and gives result in SQZ format.
Parameters
lqx - signed number in LQX format
fx - format of lqx number
sqy- signed number in SQY format
fy - format of sqy number
fz - format of the result
Freescale SemiconductorKinetis Motor Suite API Reference Manual
317
Function Documentation
Returns
number in SQZ format
References _SQ_ASL, _SQ_ASR, and QM_DIV_TWO_32B_16BRES.
23.5.23 _sq _SQZmpySQXY ( _sq sqx, int16_t fx, _sq sqy, int16_t fy, int16_t fz )[inline], [static]
Multiplies two signed numbers in SQX and SQY formats and returns result in SQZ format.
Parameters
sqx - number in SQX format
fx - format of sqx number
sqy - number in SQY format
fy - format of sqy number
fz - format of the result (SQZ)
Returns
number in SQZ format
References _LQZmpySQXY().
23.5.24 _lq FLT_coeff_Euler ( _lq lq16cutoffHz, _lq Ts )
23.5.25 _lq FLT_coeff_Tustin ( _lq lq16cutoffHz, _lq Ts )
Referenced by FEEDBACK_config().
23.5.26 _lq FLT_hpf1stE_32bit ( FLT_butterAccE32bit_t ∗ pflt, _lq input )
Executes first order high-pass Butterworth filter (32-bit forward Euler implementation)
Parameters
∗pflt - pointer to the Butterworth coefficients
input - input variables
318Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Returns
filtered variable H(s) = s / (s + wc)
23.5.27 _lq FLT_hpf1stT_32bit ( FLT_butterAccT32bit_t ∗ pflt, _lq input )
Executes first order high-pass Butterworth filter (32-bit Tustin implementation)
Parameters
∗pflt - pointer to the Butterworth coefficients
input - input variable
Returns
filtered variable
23.5.28 _lq FLT_lpf1stE_32bit ( FLT_butterAccE32bit_t ∗ pflt, _lq input )
Executes first order low-pass Butterworth filter (32-bit forward Euler implementation)
Parameters
∗pflt - pointer to the Butterworth coefficients
input - input variables
Returns
filtered variable H(s) = wc / (s + wc)
23.5.29 _lq FLT_lpf1stT_16bit ( FLT_butterAccT16bit_t ∗ pflt, _sq input )
Executes first order low-pass Butterworth filter (16-bit Tustin implementation)
Parameters
∗pflt - pointer to the Butterworth coefficients
input - input variables
Returns
filtered variable
Referenced by FEEDBACK_run().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
319
Function Documentation
23.5.30 _lq FLT_lpf1stT_32bit ( FLT_butterAccT32bit_t ∗ pflt, _lq input )
Executes first order low-pass Butterworth filter (32-bit Tustin implementation)
Parameters
∗pflt - pointer to the Butterworth coefficients
input - input variables
Returns
filtered variable
23.5.31 _lq FLT_ratio_Tustin ( _lq lq16cutoffHz, _lq Ts )
23.5.32 PID_processPI32 ( PID_piReg32_t ∗ v )
Processes a 32-bit PI regulator.
Parameters
v - pointer to a PI 32-bit regulator structure
Returns
none
23.5.33 PID_processPID32 ( PID_pidReg32_t ∗ v )
Processes a 32-bit PID regulator.
Parameters
v - pointer to a PID 32-bit regulator structure
Returns
none
320Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
23.5.34 void PID_processPIF16 ( PID_piReg16_t ∗ v, _sq flterr )
23.5.35 PID_processPIF32 ( PID_piReg32_t ∗ v, _lq flterr )
Processes a 32-bit PIF regulator.
Parameters
v - pointer to a PI 32-bit regulator structure
flterr - filtered error
Returns
none
23.5.36 _lq QM_div ( _lq numerator, _lq denominator, int16_t format )
Divides two LQ numbers and returns an LQX number in a designated X format.
Parameters
numerator - dividend (_lq)
denominator - divisor (_lq)
format - desired result format (int16_t)
Returns
Result/quotient (_lq)
23.5.37 int16_t QM_divTwo32bSNum16bRes ( int32_t numerator, int32_tdenominator )
Divides two 32-bit signed integer numbers and returns a 16-bit signed integer number.
Parameters
numerator - dividend (int32_t)
denominator - divisor (int32_t)
Returns
Result/quotient (int16_t)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
321
Function Documentation
23.5.38 _lq QM_mpy ( _lq x, _lq y, int16_t format ) [inline], [static]
Multiplies two LQ numbers and returns an LQ number.
Parameters
x - multiplicator x (_lq)
y - multiplicator y (_lq)
format - difference between the sum of two input formats and the output format (int16_t)
Returns
Result/product (_lq)
23.5.39 int32_t qmath_version ( void )
Returns the version number of the QMath Library.
Returns
Version number for QMath Library
Referenced by rda_bsp_get_app_version().
23.5.40 void TRF_clarkeLarge32 ( _lq a, _lq b, _lq c, TRF_sVector32_t ∗pVectorAB ) [inline], [static]
Direct Clarke transform of a 32-bit a-b-c vector into a 32-bit alpha-beta vector.
Parameters
a - phase A variable
b - phase B variable
c - phase C variable
pVectorAB - pointer to an alpha-beta reference frame vector
Returns
none
References _LQ, _LQmpy, TRF_sVector32_t::A, TRF_sVector32_t::B, and SQRT3.
322Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
23.5.41 void TRF_iPark32 ( const TRF_orient32_t ∗ pOrient, constTRF_rVector32_t ∗ pVectorDQ, TRF_sVector32_t ∗ pVectorAB )[inline], [static]
Inverse Park transform of a 32-bit d-q vector into a 32-bit alpha-beta vector.
Parameters
pOrient - pointer to the reference frame orientation variable
pVectorDQ - pointer to a d-q reference frame vector
pVectorAB - pointer to an alpha-beta reference frame vector
Returns
none
References _LQmpy, TRF_sVector32_t::A, TRF_sVector32_t::B, TRF_orient32_t::cosAngle, TRF_r←↩Vector32_t::d, TRF_rVector32_t::q, and TRF_orient32_t::sinAngle.
23.5.42 void TRF_park32 ( const TRF_orient32_t ∗const pOrient, constTRF_sVector32_t ∗const pVectorAB, TRF_rVector32_t ∗const pVectorDQ) [inline], [static]
Direct Park transform of a 32-bit alpha-beta vector into a 32-bit d-q vector.
Parameters
pOrient - pointer to the reference frame orientation variable
pVectorAB - pointer to an alpha-beta frame vector
pVectorDQ - pointer to a d-q frame vector
Freescale SemiconductorKinetis Motor Suite API Reference Manual
323
Function Documentation
Returns
none
References _LQmpy, TRF_sVector32_t::A, TRF_sVector32_t::B, TRF_orient32_t::cosAngle, TRF_r←↩Vector32_t::d, TRF_rVector32_t::q, and TRF_orient32_t::sinAngle.
23.5.43 void TRF_park32_16_SQ15 ( const TRF_orient32_t ∗ pOrient, constTRF_sVector16_t ∗ pVectorAB, TRF_rVector16_t ∗ pVectorDQ )[inline], [static]
Direct Park transform of a 16-bit alpha-beta vector into a 16-bit d-q vector (by using 32-bit sine/cosinevalues)
Parameters
pOrient - pointer to the reference frame orientation variable
pVectorAB - pointer to an alpha-beta frame vector
pVectorDQ - pointer to a d-q frame vector
Returns
none
References _LQ30, _LQsatFast, _LQXtoSQY(), _LQZmpyMiniSQLQXY, TRF_sVector16_t::A, TRF←↩_sVector16_t::B, TRF_orient32_t::cosAngle, TRF_rVector16_t::d, GLOBAL_LQ, TRF_rVector16_t::q,and TRF_orient32_t::sinAngle.
23.5.44 UTIL_angleWrapAround ( const _lq inputAngle ) [inline], [static]
Angle wrap-around function.
Parameters
inputAngle - input angle
Returns
Wrapped angle
References _LQ.
Referenced by UTIL_arcUponChord().
324Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
23.5.45 static _sq UTIL_arcUponChord ( bool enableDCInjection, _lq speedEst,_lq anglexTslowscale, _lq(∗)(_lq x) p_LQsinPU ) [inline], [static]
References _LQ, _LQabsFast, _LQmpy, _LQtoSQ, _SQ, _SQdivISQ, PI, and UTIL_angleWrapAround().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
325
Function Documentation
326Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 24Communication24.1 OverviewProvides communication between target MCU and PC GUI.
Functional description
KMS relies on a serial communication protocol including an agent embedded on chip to transfer data fromthe chip to the PC-based user interface. This embedded agent comprises the Communication block.
Code security breakdown
The table below describes the partitioning of Communication block code among open source, library, andprotected execute-only.
Open Source Library Execute-onlyFunctions for initializing, receiving,transmitting
N/A N/A
Execution
For real-time debugging purposes, the Communication block operates at the Fast ISR frequency.
User customization example
If the user advances toward production and no longer requires the KMS graphical user interface for motorcontrol configuration or debugging purposes, the user may choose to remove the Communication block.This will save memory and execution cycles.
Macros• #define RDA_UART_INSTANCE 0• #define RDA_UART_BASE (g_uartBase[RDA_UART_INSTANCE])• #define UART_RX_BUFFER_SIZE (64U)
UART receive buffer size (in Bytes)• #define UART_TX_BUFFER_SIZE (256U)
UART transmit buffer size (in Bytes)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
327
Overview
• #define UART_RX_BUFFER_MASK (UART_RX_BUFFER_SIZE - 1U)UART Receive buffer mask.
• #define UART_TX_BUFFER_MASK (UART_TX_BUFFER_SIZE - 1U)UART Transmit buffer mask.
Functions• void rda_init (uint8_t ∗push_buffer, uint16_t push_buffer_len, uint16_t freqHz)
Initializes RDA module.• void rda_tick (void)
RDA runtime function.• FAST void rda_push_int (void)
Perform push data collection.• uint32_t rda_get_version (void)• void rda_set_interrupt_freq (uint16_t freqHz)• uint16_t rda_get_number_processed_messages (void)
Counts wraps at uint16_t max.• bool rda_mem_address_readable (uint32_t address)
Platform specific readable address check. Agent with NACK read requests to address if this functionreturns false.
• uint8_t uart_rx_byte (void)Receives a character from UART.
• bool uart_rx_data_ready (void)Checks for data that is waiting in UART.
• void uart_tx_byte (uint8_t data)Transmits a character over UART.
• bool uart_tx_full (void)Checks if transmit buffer is full.
• static bool uart_tx_empty (void)Checks if transmit buffer is empty.
• void UART0_ERR_IRQHandler (void)ISR for UART ORIE.
• void RDA_UART_ISR (void)Single ISR for UART.
• if (UART_HAL_GetStatusFlag(RDA_UART_BASE, kUartTxDataRegEmpty))
Variables• static uint32_t uartRxCounts = 0UL
UART receive interrupt count (Diagnostics)• static uint32_t uartTxCounts = 0UL
UART transmit interrupt count (Diagnostics)• static uint32_t uartIsrDroppedCounts = 0UL
Number of dropped bytes due to Rx Buffer full (Diagnostics)• static uint32_t uartRxOverRunCounts = 0UL
Number of Rx FIFO Overrun Errors reset by Error ISR Handler (Diagnostics)• static uint32_t uartIsrCounts = 0UL
Number of (Tx Empty / Rx Full) ISR (Diagnostics)• static uint8_t uart_rx_buf [UART_RX_BUFFER_SIZE]
UART software receive buffer (head-tail ring buffer)• static uint8_t uart_tx_buf [UART_TX_BUFFER_SIZE]
328Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Macro Definition Documentation
UART software transmit buffer (head-tail ring buffer)• static volatile uint32_t uart_rx_head = 0U
UART receive buffer head variable.• static volatile uint32_t uart_rx_tail = 0U
UART receive buffer tail variable.• static volatile uint32_t uart_tx_head = 0U
UART transmit buffer head variable.• static volatile uint32_t uart_tx_tail = 0U
UART transmit buffer tail variable.
24.2 Macro Definition Documentation
24.2.1 #define RDA_UART_BASE (g_uartBase[RDA_UART_INSTANCE])
Referenced by if(), RDA_UART_ISR(), UART0_ERR_IRQHandler(), and uart_tx_byte().
24.2.2 #define RDA_UART_INSTANCE 0
Referenced by UART0_ERR_IRQHandler().
24.2.3 #define UART_RX_BUFFER_MASK (UART_RX_BUFFER_SIZE - 1U)
UART Receive buffer mask.
Referenced by RDA_UART_ISR(), and uart_rx_byte().
24.2.4 #define UART_RX_BUFFER_SIZE (64U)
UART receive buffer size (in Bytes)
24.2.5 #define UART_TX_BUFFER_MASK (UART_TX_BUFFER_SIZE - 1U)
UART Transmit buffer mask.
Referenced by if(), uart_tx_byte(), and uart_tx_full().
24.2.6 #define UART_TX_BUFFER_SIZE (256U)
UART transmit buffer size (in Bytes)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
329
Function Documentation
24.3 Function Documentation24.3.1 if ( UART_HAL_GetStatusFlag(RDA_UART_BASE, kUartTxDataRegEmpty)
)
References RDA_UART_BASE, UART_TX_BUFFER_MASK, and uart_tx_empty().
24.3.2 void rda_get_number_processed_messages ( void )
Counts wraps at uint16_t max.
Returns
Total Number of RDA Requests Processed
24.3.3 void rda_get_version ( void )
Returns
revision id
Referenced by rda_bsp_get_app_version().
24.3.4 void rda_init ( uint8_t ∗ push_buffer, uint16_t push_buffer_len, uint16_tfreqHz )
Initializes RDA module.
Parameters
push_buffer - pointer to push buffer
push_buffer_←↩len
- length (depth) of the push buffer
freqHz - sample frequency (for data pushing)
Returns
none
24.3.5 uint16_t rda_mem_address_readable ( uint32_t address )
Platform specific readable address check. Agent with NACK read requests to address if this functionreturns false.
330Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
address - address of read
Returns
true if safe to dereference otherwise false.
References ramLowAddress.
24.3.6 void rda_push_int ( void )
Perform push data collection.
Returns
none
24.3.7 void rda_set_interrupt_freq ( uint16_t freqHz )
24.3.8 void rda_tick ( void )
RDA runtime function.
Returns
none
24.3.9 void RDA_UART_ISR ( void )
Single ISR for UART.
Returns
none
References RDA_UART_BASE, UART_RX_BUFFER_MASK, uart_rx_head, and uart_tx_tail.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
331
Function Documentation
24.3.10 void UART0_ERR_IRQHandler ( void )
ISR for UART ORIE.
Returns
none
References RDA_UART_BASE, and RDA_UART_INSTANCE.
24.3.11 uint8_t uart_rx_byte ( void )
Receives a character from UART.
Returns
Received character
References UART_RX_BUFFER_MASK, uart_rx_data_ready(), and uart_rx_tail.
24.3.12 bool uart_rx_data_ready ( void )
Checks for data that is waiting in UART.
Returns
TRUE if data is present, FALSE if it is nottrue if data is variable, false if it is not
References uart_rx_head.
Referenced by uart_rx_byte().
24.3.13 void uart_tx_byte ( uint8_t data )
Transmits a character over UART.
Parameters
332Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Variable Documentation
data - charcter to be transmitted
Returns
none
References RDA_UART_BASE, UART_TX_BUFFER_MASK, and uart_tx_head.
24.3.14 static bool uart_tx_empty ( void ) [static]
Checks if transmit buffer is empty.
Returns
true if transmit buffer is empty, false if not
References uart_tx_tail.
Referenced by if().
24.3.15 bool uart_tx_full ( void )
Checks if transmit buffer is full.
Returns
TRUE if transmit buffer is full, FALSE if nottrue if transmit buffer is full, false if not
References UART_TX_BUFFER_MASK.
24.4 Variable Documentation
24.4.1 uart_rx_buf [static]
UART software receive buffer (head-tail ring buffer)
24.4.2 uart_rx_head = 0U [static]
UART receive buffer head variable.
Referenced by RDA_UART_ISR(), and uart_rx_data_ready().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
333
Variable Documentation
24.4.3 uart_rx_tail = 0U [static]
UART receive buffer tail variable.
Referenced by uart_rx_byte().
24.4.4 uart_tx_buf [static]
UART software transmit buffer (head-tail ring buffer)
24.4.5 uart_tx_head = 0U [static]
UART transmit buffer head variable.
Referenced by uart_tx_byte().
24.4.6 uart_tx_tail = 0U [static]
UART transmit buffer tail variable.
Referenced by RDA_UART_ISR(), and uart_tx_empty().
24.4.7 uartIsrCounts = 0UL [static]
Number of (Tx Empty / Rx Full) ISR (Diagnostics)
24.4.8 uartIsrDroppedCounts = 0UL [static]
Number of dropped bytes due to Rx Buffer full (Diagnostics)
24.4.9 uartRxCounts = 0UL [static]
UART receive interrupt count (Diagnostics)
24.4.10 uartRxOverRunCounts = 0UL [static]
Number of Rx FIFO Overrun Errors reset by Error ISR Handler (Diagnostics)
334Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Variable Documentation
24.4.11 uartTxCounts = 0UL [static]
UART transmit interrupt count (Diagnostics)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
335
Variable Documentation
336Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Chapter 25Versions25.1 OverviewProvides version information about the subcomponents of the firmware.
Functional description
KMS firmware is updated on a regular basis. The Version block allows for tracking of KMS subcompo-nents to allow for accelerated troubleshooting and debugging.
Code security breakdown
The table below describes the partitioning of Version block code among open source, library, and protectedexecute-only.
Open Source Library Execute-onlyFunctions for determining versionsof math and other subcomponentsas well as dates
N/A N/A
Execution
As this operation is not time-critical, the Version block operates in the Slow ISR.
User customization example
The user will likely consider this code primarily for reporting any bugs to Freescale and to determinealignment of multiple instances of KMS.
Data Structures• struct ST_Ver_t
Typedefs• typedef ST_Ver_t ∗ ST_VER_Handle
Handle to the ST_Ver_t structure.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
337
Overview
Enumerations• enum ST_MathType_e {
FIXED_POINT_16b = 0,FIXED_POINT_32b,FLOAT_POINT_32b }
Defines the math implementations available for the SpinTAC Library.
Functions• uint32_t GetMotorObserverSecureVersion (void)• uint32_t GetMotorObserverNonSecureVersion (void)• bool GetMotorObserverSecureVersionIsCompatible (void)• static void ST_getVersionNumber (ST_VER_Handle handle, uint16_t ∗major, uint16_t ∗minor,
uint16_t ∗revision)Gets the Version Number (Major, Minor, Revision) for SpinTAC Version.
• static int32_t ST_getVersionMath (ST_VER_Handle handle)Gets the Version Math Implementation (FixedPt) for SpinTAC Version.
• static int32_t ST_getVersionDate (ST_VER_Handle handle)Gets the Version Date (Date) for SpinTAC Version.
• static int32_t ST_getSecureROMVersion (ST_VER_Handle handle)Gets the ROM Version Number (SecureROM) for SpinTAC Version.
• ST_VER_Handle ST_initVersion (void ∗pMemory, const size_t numBytes)Initializes the SpinTAC Version object.
• bool ST_getSecureROMIsCompatible (void)Initializes the SpinTAC Version object.
• static void direct_encode_16 (uint8_t ∗pData, uint16_t value)Splits 16-bit data into 2 bytes (Big Endian)
• static void direct_encode_32 (uint8_t ∗pData, uint32_t value)Splits 32-bit data into 4 bytes (Little Endian)
• uint16_t rda_bsp_get_app_version (uint8_t ∗dst, uint16_t buffSize)Give a platform specific version stream to RDA for Read Identity Response.
• bool rda_mem_address_writable (uint32_t address)Platform specific writable address check. Agent with NACK write requests to address if this functionreturns false.
• bool rda_mem_address_readable (uint32_t address)Platform specific readable address check. Agent with NACK read requests to address if this functionreturns false.
Variables• static const char buildDate [ ] = __DATE__• static const char buildTime [] = __TIME__• const uint32_t __checksum• uint32_t m_data_start• uint32_t ramLowAddress = (uint32_t)(&m_data_start)• uint32_t m_data_2_end• uint32_t ramHighAddress = (uint32_t)(&m_data_2_end)• uint32_t m_text_start• uint32_t flashLowAddress = (uint32_t)(&m_text_start)• uint32_t m_text_end• uint32_t flashHighAddress = (uint32_t)(&m_text_end)
338Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
25.2 Data Structure Documentation
25.2.1 struct ST_Ver_t
Data Fields
int32_t Date Date the library was compiled { format: YYYYMMDD }
uint_least8_t Label[10] Version label
uint16_t Major Major revision number
ST_Math←↩Type_e
MathType Math implementation type
uint16_t Minor Minor revision number
uint16_t Revision Revision number
uint32_t SecureROM Secure ROM Version Number
25.3 Typedef Documentation
25.3.1 ST_VER_Handle
Handle to the ST_Ver_t structure.
25.4 Enumeration Type Documentation
25.4.1 enum ST_MathType_e
Defines the math implementations available for the SpinTAC Library.
Enumerator
FIXED_POINT_16b Fixed point 16 bit implementationFIXED_POINT_32b Fixed point 32 bit implementationFLOAT_POINT_32b Floating point 32 bit implementation
25.5 Function Documentation
25.5.1 void direct_encode_16 ( uint8_t ∗ pData, uint16_t value ) [static]
Splits 16-bit data into 2 bytes (Big Endian)
Freescale SemiconductorKinetis Motor Suite API Reference Manual
339
Function Documentation
Parameters
pData - pointer to byte data
value - value
Returns
none
Referenced by rda_bsp_get_app_version().
25.5.2 void direct_encode_32 ( uint8_t ∗ pData, uint32_t value ) [static]
Splits 32-bit data into 4 bytes (Little Endian)
Parameters
pData - pointer to byte data
value - value
Returns
none
Referenced by rda_bsp_get_app_version().
25.5.3 uint32_t GetMotorObserverNonSecureVersion ( void )
Referenced by rda_bsp_get_app_version().
25.5.4 uint32_t GetMotorObserverSecureVersion ( void )
Referenced by rda_bsp_get_app_version().
25.5.5 bool GetMotorObserverSecureVersionIsCompatible ( void )
Referenced by DSM_init().
340Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
25.5.6 uint16_t rda_bsp_get_app_version ( uint8_t ∗ dst, uint16_t buffSize )
Give a platform specific version stream to RDA for Read Identity Response.
Gets the version of the libraries.
Parameters
dst - pointer to buffer to populate
buffSize - length dst buffer
Returns
number of uint8_t(char) written.
Parameters
dst - pointer to byte data
value - value
Returns
number of bytes in this stream
References __checksum, buildDate, buildTime, ST_Ver_t::Date, direct_encode_16(), direct_encode_←↩32(), GetMotorObserverNonSecureVersion(), GetMotorObserverSecureVersion(), ST_Ver_t::Label, ST←↩_Ver_t::Major, ST_Ver_t::MathType, ST_Ver_t::Minor, qmath_version(), rda_get_version(), ST_Ver_t←↩::Revision, ST_Ver_t::SecureROM, and ST_initVersion().
25.5.7 bool rda_mem_address_readable ( uint32_t address )
Platform specific readable address check. Agent with NACK read requests to address if this functionreturns false.
Parameters
address - address of read
Returns
true if safe to dereference otherwise false.
References ramLowAddress.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
341
Function Documentation
25.5.8 bool rda_mem_address_writable ( uint32_t address )
Platform specific writable address check. Agent with NACK write requests to address if this functionreturns false.
Gets if memory address is writable.
Parameters
address - address of write
Returns
true if safe to write otherwise false.
Parameters
address to attempt write
Returns
true if the memory is writable
References ramLowAddress.
25.5.9 ST_getSecureROMIsCompatible ( void )
Initializes the SpinTAC Version object.
Returns
True if ROM and PUBLIC Libs are compatible
Referenced by DSM_init().
25.5.10 ST_getSecureROMVersion ( ST_VER_Handle handle ) [inline],[static]
Gets the ROM Version Number (SecureROM) for SpinTAC Version.
342Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Function Documentation
Parameters
handle - The handle for the SpinTAC Version Object
Returns
int32_t SecureROM Secure ROM Version Number
References ST_Ver_t::SecureROM.
25.5.11 ST_getVersionDate ( ST_VER_Handle handle ) [inline], [static]
Gets the Version Date (Date) for SpinTAC Version.
Parameters
handle - The handle for the SpinTAC Version Object
Returns
int32_t Date Date the library was compiled { format: YYYYMMDD }
References ST_Ver_t::Date.
25.5.12 ST_getVersionMath ( ST_VER_Handle handle ) [inline], [static]
Gets the Version Math Implementation (FixedPt) for SpinTAC Version.
Parameters
handle - The handle for the SpinTAC Version Object
Returns
ST_MathType_e MathType Math implementation used in library
References ST_Ver_t::MathType.
25.5.13 ST_getVersionNumber ( ST_VER_Handle handle, uint16_t ∗ major,uint16_t ∗ minor, uint16_t ∗ revision ) [inline], [static]
Gets the Version Number (Major, Minor, Revision) for SpinTAC Version.
Freescale SemiconductorKinetis Motor Suite API Reference Manual
343
Variable Documentation
Parameters
∗major - Major version number
∗minor - Minor version number
∗revision - Revision version number
Returns
none
References ST_Ver_t::Major, ST_Ver_t::Minor, and ST_Ver_t::Revision.
25.5.14 ST_initVersion ( void ∗ pMemory, const size_t numBytes )
Initializes the SpinTAC Version object.
Parameters
∗pMemory Pointer to the memory for ST_Ver_t
numBytes The number of bytes in the ST_Ver_t
Returns
ST_VER_Handle handle The handle for the SpinTAC Version Object
Referenced by rda_bsp_get_app_version().
25.6 Variable Documentation
25.6.1 const uint32_t __checksum
Referenced by rda_bsp_get_app_version().
25.6.2 const char buildDate[ ] = __DATE__ [static]
Referenced by rda_bsp_get_app_version().
25.6.3 const char buildTime[ ] = __TIME__ [static]
Referenced by rda_bsp_get_app_version().
344Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
Variable Documentation
25.6.4 uint32_t flashHighAddress = (uint32_t)(&m_text_end)
25.6.5 uint32_t flashLowAddress = (uint32_t)(&m_text_start)
25.6.6 uint32_t m_data_2_end
25.6.7 uint32_t m_data_start
25.6.8 uint32_t m_text_end
25.6.9 uint32_t m_text_start
25.6.10 uint32_t ramHighAddress = (uint32_t)(&m_data_2_end)
25.6.11 uint32_t ramLowAddress = (uint32_t)(&m_data_start)
Referenced by rda_mem_address_readable(), and rda_mem_address_writable().
Freescale SemiconductorKinetis Motor Suite API Reference Manual
345
Variable Documentation
346Kinetis Motor Suite API Reference Manual
Freescale Semiconductor
How to Reach Us:
Home Page:freescale.com
Web Support:freescale.com/support
Information in this document is provided solely to enable system andsoftware implementers to use Freescale products. There are no expressor implied copyright licenses granted hereunder to design or fabricateany integrated circuits based on the information in this document.
Freescale reserves the right to make changes without further notice toany products herein. Freescale makes no warranty, representation, orguarantee regarding the suitability of its products for any particularpurpose, nor does Freescale assume any liability arising out of theapplication or use of any product or circuit, and specifically disclaimsany and all liability, including without limitation consequential orincidental damages. “Typical” parameters that may be provided inFreescale data sheets and/or specifications can and do vary in differentapplications, and actual performance may vary over time. All operatingparameters, including “typicals,” must be validated for each customerapplication by customer’s technical experts. Freescale does not conveyany license under its patent rights nor the rights of others. Freescalesells products pursuant to standard terms and conditions of sale, whichcan be found at the following address:freescale.com/SalesTermsandConditions.
Freescale, the Freescale logo, Kinetis, Processor Expert are trademarksof Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. Tower is atrademark of Freescale Semiconductor, Inc. All other product or servicenames are the property of their respective owners. ARM, ARM Poweredlogo, and Cortex are registered trademarks of ARM Limited (or itssubsidiaries) in the EU and/or elsewhere. SpinTAC is a trademark ofLineStream Technologies, Inc. All rights reserved.
© 2016 Freescale Semiconductor, Inc.
Document Number: KMS100RM
Rev. 0
02/2016