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

Unit	Ch0	Ch1	Ch2	Ch3	Ch4	Ch5	Ch6	Ch7
ADC0	SIN240_HC (X901)	ISENA (DRV8323R)	TSENS (INTERNAL)	VREF_ADC (INTERNAL)	-	-	-	-
ADC1	-	ISENB (DRV8323R)	VDDIO/2 (INTERNAL)	VREF_ADC (INTERNAL)	-	-	-	-
ADC2	SIN0_HA (X901)	AIM (X901)	POT (R33)	VSENA (J5)	VSENVM (J1)	-	NTC (R39)	-
ADC3	SIN120_HB (X901)	AI (X901)	ISENC (DRV8323R)	VSENB (J5)	-	VSENC (J5)	-	-

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:

Parameter	Default Value	Example1 Value
PAR_APP_FREQ_HZ	1000U	200U
PAR_SPEED_CONTROLLER_KP	0.004f	0.001f
PAR_SPEED_CONTROLLER_KI	0.000001f	0.00000025f
PAR_CURRENT_OFFSET_THRESHOLD_DIG	48U	88U

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.

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

Abbreviations	Description
FOC	Field Oriented Control
PSE	Position and Speed Estimation
GDU	Gate Drive Unit
HAL	Hardware Abstraction Layer
MCL	Motor Control Layer
APPL	Application Layer
CR	Carriage Return
LF	Line Feed
ADC	Analog to digital converter
MC	Motion Control
QEI	Quadrature Encoder Interface
MENC	Motion Encoder
MPWM	Motion pulse width modulation
GPIO	General purpose input output
ECZ	Event counter zero
SVM	Space vector modulation

4 Attachments

	File	Modified
Labels No labels Preview View	Microsoft Excel Spreadsheet par_def.xlsx	2021-02-26 by Nico Mäding

Software application note FOC (old)