Page tree
Skip to end of metadata
Go to start of metadata

Software setup

This chapter describes how the software is structured and how to configure it according to the requirements.

1.1 Program Structure

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.

Program structure

Figure 1: Program Structure

1.2 Folder Structure

The figure below shows the folder structure of the example. The next section explained how each layer interacts.

Figure 2: Folder Structure

1.2.1 Application Layer [APPL]

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

1.2.2 Hardware Abstraction Layer [HAL]

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.











SIN240_HC (X901)


















SIN0_HA (X901)

AIM (X901)

POT (R33)




NTC (R39)



SIN120_HB (X901)

AI (X901)







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.

1.2.3 MATH Library [MATH]

MATH is a library, providing the mathematical functionality used by all three layers of the application. It provides:

  • The PI controller ,
  • Sin/Cos functionality
  • The space vector modulation Duty Calculation, 
  • The Clarke transformation, used in space vector modulation control of three-phase inverters
  • The inverse Clarke transformation
  • The Park transformation. The Park Transformation converts the time-domain components of a three-phase system in an abc reference frame to direct, quadrature, and zero components in a rotating reference frame
  • The inverse Park transformation

1.2.4 Motor Control Layer [MCL]

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:

  • FOC_IDLE - Disable GDU (Gate Drive Unit)
  • FOC_CURRENT_OFFSET - proceed to the Current Offset State Machine
  • FOC_CURRENT_CONTROL - calculate current via CurrentControl()
  • FOC_VOLTAGE_CONTROL - voltage control for open loop systems (disabled for this example)
  • FOC_PWM_PATTERN - FOC manual PWM pattern. Not used.
  • FOC_FAILED - disable GDU

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. 

1.2.5 User Interface

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.

1.3 Configuring the parameter in the Software

This chapter shows how easily the parameter could be change, feel free to tweak the parameter to your desire.

1.3.1 Console parameter

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

1.3.2 Enable/Disable the potentiometer

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.

1.3.3 Modifying frequency of the main application

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:

Default Value
Example1 Value
Example2 Value

Table 2: Suggested parameter for changing of main application 

1.3.4 Other parameters

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.

NumberParameter nameDatentypeDefault valuePositionDescription
1APP_POT_SPEED_SLOPEFloat(7000-50)/(4095-200)par_def.hSlope of Potentiometer reading vs Speed request
2PAR_ADC_MAX_DIGUnsigned int4095par_def.hMaximum of ADC resulotion, Internal 12bit ADC
3PAR_POT_MIN_SPEED_REQ_DIGUnsigned int200par_def.hMinimum Potentiometer value for speed request
4PAR_POT_HYSTERESIS_DIGUnsigned int100par_def.hSpeed request hysteresis value for Pot.
5PAR_MIN_SPEED_RPMUnsigned int50par_def.hMinimum speed request
6PAR_STOPPED_SPEED_RPMUnsigned int0Upar_def.hMotor stopped
7PAR_MAX_SPEED_RPMUnsigned int7000par_def.h Maximum speed request
8PAR_NUMBER_OF_CURRENT_OFFSET_MEASUnsigned int8par_def.hNumber of measurements to calculate average current offset
9PAR_CURRENT_OFFSET_THRESHOLD_DIGUnsigned int88par_def.hNumber of digits allowed for current offset
10PAR_MAX_DUTY_CYCLE_PERCENTFloat 96.0par_def.hMaximum allowed duty cycle percentage
11PAR_ADC_VREF_VOLTSFloat3.3par_def.hReference voltage for ADC
12PAR_SHUNT_RESISTANCE_OHMFloat0.007par_def.hShunt resistor value
13PAR_CURRENT_AMP_GAINFloat20.0par_def.hGain value of op-amp.
14PAR_DCBUS_VOLTAGE_GAINFloat((2.88 + 82.0) / 2.88)par_def.h DC-bus Voltage gain value, calculated from voltage divider
15PAR_DCBUS_VOLTAGE_OFFSET_DIGITSUnsigned int10par_def.hDC-bus Voltage offset value, experimentally determined
16PAR_PHASE_VOLTAGE_GAIN Float((4.99 + 82.0) / 4.99)par_def.hPhase Voltage gain value, calculated from voltage divider
17PAR_PHASE_VOLTAGE_OFFSET_DIGITS Unsigned int0par_def.h Phase Voltage offset value
18PAR_CPU_FREQ_HZ Unsigned int100000000par_def.hCPU frequency in Hz
19PAR_PWM_PERIODUnsigned int5000par_def.hPWM frequency in Hz ( Initial pwm period)
20PAR_APP_FREQ_HZUnsigned int200par_def.hApplication (Speed Controller) frequency
21PAR_QEI_NUMBER_OF_SLOTSUnsigned int256par_def.hNumber of quadrature encoder slots
22PAR_USE_MAF_CAPTUREUnsigned int0par_def.hUse moving average filter in speed estimation.Details: To enable set value to 1U. Captured position is filtered with a MAF of size 4
23PAR_MOTOR_POLE_PAIRSUnsigned int3par_def.hMotor pole pair number
24PAR_MAX_PHASE_CURRENT_AMPFloat2.5par_def.hMaximum allowed phase current
25PAR_SPEED_CONTROLLER_KPFloat0.001par_def.hProportional gain of speed controller
26PAR_SPEED_CONTROLLER_KIFloat 0.00000025par_def.hIntegral gain of speed controller
27PAR_FIELDWEAK_CONTROLLER_KPFloat 0.1par_def.hProportional gain of field-weakening controller
28PAR_FIELDWEAK_CONTROLLER_KIFloat0.005par_def.hIntegral gain of field-weakening controller
29PAR_FIELDWEAK_START_VOLTAGE_RATIOFloat1.08par_def.hThreshold voltage vector magnitude to start field-weakening.Details:Value is less than maximum voltage vector magnitude to allow a transition region.
30PAR_CURRENT_CONTROLLER_KPFloat0.01par_def.hProportional gain of current controller
31PAR_CURRENT_CONTROLLER_KIFloat0.0005par_def.hIntegral gain of current controller
32PAR_USE_OPENLOOP-0par_def.hTo enable open-loop for debugging set to 1
33ul_timerPeriodUnsigned long500000FOC_APPL.cFrequency of FOC APPL Main function (determine how often this function is called)
34PAR_USE_HALL_SPEED-1par_def.hDetermines which interface is used to calculate the speed. Default is Hall sensor
35DEMO_USE_POTENTIOMETER--FOC_APPL.cIf defined, program use the Potentiometer existing on the board
36FOC_CURRENT_OFFSET_MEASURE_NUMBERuint8_t8FOC.cNumber of measurements for current offset
37FOC_CURRENT_OFFSET_MINuint16_t2048U - 88UFOC.cMinimum value for current offset
38FOC_CURRENT_OFFSET_MAXuint16_t2048U + 88UFOC.cMaximum value for current offset
39FOC_CURRENT_OFFSET_SUM_MINuint32_t8(2048U - 88U)FOC.cMinimum value for sum of current offset
40FOC_CURRENT_OFFSET_SUM_MAXuint32_t8(2048U + 88U)FOC.cMaximum value for sum of current offset
41FOC_CURRENT_OFFSET_WAITuint16_t20000FOC.cIn case of current offset measurement error wait time for next measurement
42FOC_SVM_LIMITFloat(96/100)/(1.73205080757/2)FOC.cSpace-Vector-Modulation limit
43FOC_PICONTROL_LOWER_LIMFloat(-1)(96/100)/(1.73205080757/2)FOC.cCurrent PI-controller lower limit
44FOC_PICONTROL_UPPER_LIMFloat(96/100)/(1.73205080757/2)FOC.cCurrent PI-controller upper limit
Motor dependent
Change the behavior of the running motor

Table 3: user parameter

2 Sending commands

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:

  • APP_TERMINAL_HANDLER_COMMAND_MOTOR_START- this command starts the motor at the speed defined by DEMO_MOTOR_START_SPEED. If DEMO_USE_POT is defined, then the motor speed is regulated by the potentiometer.
  • APP_TERMINAL_HANDLER_COMMAND_MOTOR_GET_SPEED - this command retrieves the current speed of the motor in RPM from the PSE and prints it on the standard output. 
  • APP_TERMINAL_HANDLER_COMMAND_MOTOR_STOP - this command stops the motor.

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).

3 Abbreviations




Field Oriented Control


Position and Speed Estimation


Gate Drive Unit


Hardware Abstraction Layer


Motor Control Layer


Application Layer


Carriage Return


Line Feed


Analog to digital converter


Motion Control


Quadrature Encoder Interface


Motion Encoder


Motion pulse width modulation


General purpose input output


Event counter zero


Space vector modulation

4 Attachments

  File Modified
Microsoft Excel Spreadsheet par_def.xlsx 2021-02-26 by Farzad R. [X]

  • No labels