This chapter describes how the software is structured and how to configure it according to the requirements.
The Application consists of four layers. The “Hardware Abstraction Layer” (HAL) provides 4 drivers to communicate with the hardware. The “Motion Encoder” (MENC) provides information from the “Quadrature Encoder Interface” (QEI) to estimate the rotor position. The GPIOs capture information from the Hall-effect sensors and indicate the current state of the motor. The ADC driver provides information for the board sensors (input voltage, phase voltage, phase current). The “Motion Pulse-width modulation” (MPWM) serves to configure the PWM for the motor, to activate/deactivate the GDU and to carry out error handling.
The “Motor control layer” (MCL) retrieves information from the HAL and the latest setpoint from the “Application layer” (APPL), process them via a PI current controller and uses the output to construct the “Space vector modulation” (SVM). This modulation is then fed into the MPWM driver, which sends it to the motor. The part that retrieves information from the HAL is the “position and speed estimation” (PSE), the part that calculates the current and SVM modulation is called the “Field-oriented control” (FOC). The FOC also has a state machine, explained below, which is controlled by the APPL.
APPL consists of the main application function that is attached to a timer and it called periodically. This function handles also the error handling of the GDU and calls the APPL state machine, which in running state, calls the Speed Controller and calculates a current setpoint based on a speed setpoint specified by the user.
MATH is a library, providing the mathematical functionality used by all three layers of the application. The figure below shows the relation between all Layers in this example.
Figure 1: Program Structure
The figure below shows the folder structure of the example. The next section explained how each layer interacts.
Figure 2: Folder Structure
The application layer consists of the application main task, the application state machine and a Speed Controller. The main task receives speed feedback from the PSE and speed setpoint from the ADC driver (potentiometer). It then uses the Speed Controller to calculate and sent a latest setpoint to the FOC.
During initialization, a timer interrupt is set for the application main task, so application main task called every 5ms. Depending on the configuration in the MCL/def_par.h file, the current potentiometer value is fetched from ADC, then the router speed is approximated from the Hall-effect sensor. Finally, the APPL state machine is called.
The Speed Controller function serves to calculate a latest setpoint for the FOC based on the speed feedback, that the application receives from the PSE. For this purpose, the Speed Controller uses the PI regulator defined in Math.h.
The application state machine has the following states:
-APP_RUN - there has been a change in the speed error, therefore the Speed Controller should be activated.
-APP_IDLE - there has been no change in the speed error, do nothing.
-APP_ERROR - there has been an error while setting the current setpoint in the FOC, change FOC state to FOC_FAILED and stop the application.
-APP_STOP - the application is not running, reinitialize the Speed Controller and set the current setpoint to the FOC and set state to IDLE or RUN, depending on the speed error.
Figure 3: Application Layer
HAL include the Low-Level implementation, consist of 4 drivers ADCs, MPWM, MENC and GPIOs for position and speed estimation.
ADC: The ADC driver provides information for the board sensors - input voltage, phase voltage, phase current, etc. The channel assignment for netx90Driver board rev3 are described in the following table. The ADC driver initializes the channels at startup and update them in each MWPM_IRQHandler() call.
Table 1: MADC Matrix
GPIO: The GPIO provides information for the Hal sensor state, if PAR_USE_HALL_SPEED in par_def.h is set to 1 or 2. Set to 1 for sampling hall states. Set to 2 for interrupts. If set to zero the application will use the Quadrature Encoder(QE).
MENC: The MENC provides information from the Quadrature Encoder (QE). For the QE to be used, PAR_USE_HALL_SPEED in par_def.h has to be set to 0.
MPWM: The MPWM serves to configure the PWM for the motor, enable/disable the DRV832x 6 to 60-V Three-Phase Smart Gate Driver, as well as read relevant error information from it.
MATH is a library, providing the mathematical functionality used by all three layers of the application. It provides:
The MCL consist of the FOC and PSE modules. PSE is dedicated for getting the feedback from Hall-effect sensor or MENC. The FOC is responsible for the drive control, also FOC voltage and current control.
The FOC state machine called periodically from MPWM interrupt handler and performed current control, voltage control or disabling the GDU based on the latest state. Of course, the state should not be changed directly. The transit state has the task of changing the state, which called from APPL.
The FOC transit state machine is as follows:
Figure 4: Motor Control Layer
The state transition of the FOC is invoked by the application. Before the FOC can start its work, the current offsets have to be calculated. To do this, the FOC takes a series of measurements. When the sums of those measurements fall within predefined intervals, the current offsets are established as the average of these measurements. This process is implemented as a state machine and the following diagram describes its functionality:
Figure 5: Current offset state machine
The PSE is responsible for retrieving information from the motor. The “PSE estimate position” function as the name suggests has the task to assess the position, also calculating the speed. For the closed loop, the estimation is based on the Quadrature Encoder (QE) or Hall-effect sensors. The Hall sensor defines the sector within 60 degree intervals and the QE tracks the position based on estimated speed. For comparison, the speed is also calculated based on Hall sensors. If the estimated position does not match with Hall sensor measurement, estimated position is moved towards hall sensor measurement with a low-pass filter. This way QE position is aligned and position is not changed abruptly.
This example make uses of libc library and a simple UART console interface. The UART is routed through the USB via the FTDI-Chip on the board. The “App_TerminalHandler” function in the main loop reads one character via UART in each loop and store it in a buffer. After receiving the “carriage return” or “line feed” character, the receiving command will be checked. If the commands is valid, sends the corresponding command to the motor or receives feedback. The next chapter explains how to adapt the software to your requirements.
This chapter shows how easily the parameter could be change, feel free to tweak the parameter to your desire.
The UART default parameter are located in “libc_file_support.c”. In the case of using the UART interface for feature development, the commands can be easily expand by adding new commands in “Term_TerminalCommandHandler” function and “g_tTerminalCommandsDictionary” dictionary in “TerminalHandler.c”.
Figure 6: UART parameter
To use the potentiometer, present on the board in this example application, you need to activate the define DEMO_USE_POTENTIOMETER in par_def.h. This will allow you to control the motor speed with the potentiometer, while the motor is running. In the case of disabling, use the “FOC_APPL_setSpeedSetpoint” function to set the desired speed.
In order to modify the of the “FOC_APPL_Main” function, changing the period of the timer (eTimerPeriod) in FOC_APPL.c file is not enough. Some of the beneath-mentioned parameters may need to be changed correspondingly. First, change the PAR_APP_FREQ_HZ to the intended frequency in par_def.h file. This will cause the Current Controller and Speed Controller to be called less or more frequently. Depending on the new value of the frequency, you may have to tweak the parameters of the PI controllers to smooth the operation of motor. These parameters are PAR_SPEED_CONTROLLER_KP, PAR_SPEED_CONTROLLER_KI, PAR_CURRENT_CONTROLLER_KP and PAR_CURRENT_CONTROLLER_KI.
Figure 7: Frequency of the main application
List of changes of application parameters:
Table 2: Suggested parameter for changing of main application
The MCL parameters are defined in MCL/includes/par_def.h. These parameters control various aspects of the motor behavior. According to your application you may have tweak this parameter.
The table below shows some of the important parameter in this example.
|Number||Parameter name||Datentype||Default value||Position||Description|
|1||APP_POT_SPEED_SLOPE||Float||(7000-50)/(4095-200)||par_def.h||Slope of Potentiometer reading vs Speed request|
|2||PAR_ADC_MAX_DIG||Unsigned int||4095||par_def.h||Maximum of ADC resulotion, Internal 12bit ADC|
|3||PAR_POT_MIN_SPEED_REQ_DIG||Unsigned int||200||par_def.h||Minimum Potentiometer value for speed request|
|4||PAR_POT_HYSTERESIS_DIG||Unsigned int||100||par_def.h||Speed request hysteresis value for Pot.|
|5||PAR_MIN_SPEED_RPM||Unsigned int||50||par_def.h||Minimum speed request|
|6||PAR_STOPPED_SPEED_RPM||Unsigned int||0U||par_def.h||Motor stopped|
|7||PAR_MAX_SPEED_RPM||Unsigned int||7000||par_def.h||Maximum speed request|
|8||PAR_NUMBER_OF_CURRENT_OFFSET_MEAS||Unsigned int||8||par_def.h||Number of measurements to calculate average current offset|
|9||PAR_CURRENT_OFFSET_THRESHOLD_DIG||Unsigned int||88||par_def.h||Number of digits allowed for current offset|
|10||PAR_MAX_DUTY_CYCLE_PERCENT||Float||96.0||par_def.h||Maximum allowed duty cycle percentage|
|11||PAR_ADC_VREF_VOLTS||Float||3.3||par_def.h||Reference voltage for ADC|
|12||PAR_SHUNT_RESISTANCE_OHM||Float||0.007||par_def.h||Shunt resistor value|
|13||PAR_CURRENT_AMP_GAIN||Float||20.0||par_def.h||Gain value of op-amp.|
|14||PAR_DCBUS_VOLTAGE_GAIN||Float||((2.88 + 82.0) / 2.88)||par_def.h||DC-bus Voltage gain value, calculated from voltage divider|
|15||PAR_DCBUS_VOLTAGE_OFFSET_DIGITS||Unsigned int||10||par_def.h||DC-bus Voltage offset value, experimentally determined|
|16||PAR_PHASE_VOLTAGE_GAIN||Float||((4.99 + 82.0) / 4.99)||par_def.h||Phase Voltage gain value, calculated from voltage divider|
|17||PAR_PHASE_VOLTAGE_OFFSET_DIGITS||Unsigned int||0||par_def.h||Phase Voltage offset value|
|18||PAR_CPU_FREQ_HZ||Unsigned int||100000000||par_def.h||CPU frequency in Hz|
|19||PAR_PWM_PERIOD||Unsigned int||5000||par_def.h||PWM frequency in Hz ( Initial pwm period)|
|20||PAR_APP_FREQ_HZ||Unsigned int||200||par_def.h||Application (Speed Controller) frequency|
|21||PAR_QEI_NUMBER_OF_SLOTS||Unsigned int||256||par_def.h||Number of quadrature encoder slots|
|22||PAR_USE_MAF_CAPTURE||Unsigned int||0||par_def.h||Use moving average filter in speed estimation.Details: To enable set value to 1U. Captured position is filtered with a MAF of size 4|
|23||PAR_MOTOR_POLE_PAIRS||Unsigned int||3||par_def.h||Motor pole pair number|
|24||PAR_MAX_PHASE_CURRENT_AMP||Float||2.5||par_def.h||Maximum allowed phase current|
|25||PAR_SPEED_CONTROLLER_KP||Float||0.001||par_def.h||Proportional gain of speed controller|
|26||PAR_SPEED_CONTROLLER_KI||Float||0.00000025||par_def.h||Integral gain of speed controller|
|27||PAR_FIELDWEAK_CONTROLLER_KP||Float||0.1||par_def.h||Proportional gain of field-weakening controller|
|28||PAR_FIELDWEAK_CONTROLLER_KI||Float||0.005||par_def.h||Integral gain of field-weakening controller|
|29||PAR_FIELDWEAK_START_VOLTAGE_RATIO||Float||1.08||par_def.h||Threshold voltage vector magnitude to start field-weakening.Details:Value is less than maximum voltage vector magnitude to allow a transition region.|
|30||PAR_CURRENT_CONTROLLER_KP||Float||0.01||par_def.h||Proportional gain of current controller|
|31||PAR_CURRENT_CONTROLLER_KI||Float||0.0005||par_def.h||Integral gain of current controller|
|32||PAR_USE_OPENLOOP||-||0||par_def.h||To enable open-loop for debugging set to 1|
|33||ul_timerPeriod||Unsigned long||500000||FOC_APPL.c||Frequency of FOC APPL Main function (determine how often this function is called)|
|34||PAR_USE_HALL_SPEED||-||1||par_def.h||Determines which interface is used to calculate the speed. Default is Hall sensor|
|35||DEMO_USE_POTENTIOMETER||-||-||FOC_APPL.c||If defined, program use the Potentiometer existing on the board|
|36||FOC_CURRENT_OFFSET_MEASURE_NUMBER||uint8_t||8||FOC.c||Number of measurements for current offset|
|37||FOC_CURRENT_OFFSET_MIN||uint16_t||2048U - 88U||FOC.c||Minimum value for current offset|
|38||FOC_CURRENT_OFFSET_MAX||uint16_t||2048U + 88U||FOC.c||Maximum value for current offset|
|39||FOC_CURRENT_OFFSET_SUM_MIN||uint32_t||8(2048U - 88U)||FOC.c||Minimum value for sum of current offset|
|40||FOC_CURRENT_OFFSET_SUM_MAX||uint32_t||8(2048U + 88U)||FOC.c||Maximum value for sum of current offset|
|41||FOC_CURRENT_OFFSET_WAIT||uint16_t||20000||FOC.c||In case of current offset measurement error wait time for next measurement|
|43||FOC_PICONTROL_LOWER_LIM||Float||(-1)(96/100)/(1.73205080757/2)||FOC.c||Current PI-controller lower limit|
|44||FOC_PICONTROL_UPPER_LIM||Float||(96/100)/(1.73205080757/2)||FOC.c||Current PI-controller upper limit|
|Change the behavior of the running motor|
Table 3: user parameter
After flashing the example to the NXHX90-MC board due to the Getting started netX Studio CDT, establish a UART console connection with the board by selecting the correct COM-Port, baudrate, number of bits, data length and parity that you configured in the last chapter. Then write and send a command.
The available commands are:
To use this commands just write "motor_start", "motor_stop" or "motor_get_speed" to the console. To executed the command send the commands with “Carriage Return” (CR) or “Line Feed” (LF) at the end. If the DEMO_USE_POTENTIOMETER is activated, after sending “motor_start” command, you can adjust the motor speed bye turning the potentiometer.
Note: Make sure switches 1 and 2 are on, to enable the debugging and UART through the FTDI, and switch 4 is off, to not have the ADCs disabled. On switch S701 (for more Information on Positions of interfaces and operating elements, see the NXHX 90-MC development board).
Field Oriented Control
Position and Speed Estimation
Gate Drive Unit
Hardware Abstraction Layer
Motor Control Layer
Analog to digital converter
Quadrature Encoder Interface
Motion pulse width modulation
General purpose input output
Event counter zero
Space vector modulation