Sensorless FOC Motor Control Library Overview

1. Software Overview

Sensorless Field-Oriented Control (FOC) Library is made of three main layers: Application layer, HAL Layer, and MSPM0 DriverLib.

Sensorless FOC Architecture

Fig. 8 Sensorless FOC Architecture

1.1 Application Layer Overview

The user specific applications (such as GUI) are present in this layer. From this layer, various instances of motor driver modules can be configured and used. If the user needs to perform any hardware specific actions, the user is recommended to use the APIs from HAL module.

1.2 HAL Module

Overview

The Hardware Abstraction Layer (HAL) creates an abstraction layer that provides APIs to configure different pins and peripherals. The goal of using HAL is to abstract all device specific configurations which simplifies porting of the library to various hardware by minimizing the updates needed to other components. The HAL is meant to abstract only the required pins or peripherals required for the application while still having flexibility and scalability for porting to other MSPM0 MCUs or motor drivers.

HAL is designed to have specific number of pins or channels associated with a peripheral. For example, consider the case of GPIOs. HAL has enum HAL_GPIO_OUT_PIN which has all the GPIO output pins as members as shown below.

/*! @enum HAL_GPIO_OUT_PIN */
typedef enum{
    /*! Index associated to output GPIO PIN 0 */
    HAL_GPIO_OUT_PIN_0 = 0,
    /*! Index associated to output GPIO PIN 1 */
    HAL_GPIO_OUT_PIN_1,
    /*! Total number of output GPIO pins */
    HAL_GPIO_OUT_PIN_MAX,
}HAL_GPIO_OUT_PIN;

To map the HAL GPIO pins to the real hardware pins, a structure is used which is indexed by the members of the HAL_GPIO_OUT_PIN enum. This structure stores various members like the port instance, pin name, etc. See below the gpioOUT structure which holds data on the port and pin.

gpioOUT[HAL_GPIO_OUT_PIN_0].iomux   = GENERIC_GPIO_OUT_PINO_0_IOMUX;
gpioOUT[HAL_GPIO_OUT_PIN_0].port    = GENERIC_GPIO_OUT_PORT;
gpioOUT[HAL_GPIO_OUT_PIN_0].pin     = GENERIC_GPIO_OUT_PINO_0_PIN;

Note that GENERIC_GPIO_OUT_PINO_0_PIN is defined in the TI SysConfig generated files the specific line is shown below:

#define GENERIC_GPIO_OUT_PINO_0_PIN                             (DL_GPIO_PIN_26)

Thus, HAL_GPIO_OUT_PIN_0 indirectly refers to DL_GPIO_PIN_0, but the advantage of this mapping is that since TI SysConfig controls the generation of the GENERIC_GPIO_OUT_PINO_0_PIN, it is very easy to change the pin in the TI SysConfig GUI. The HAL automatically follows this without the user having to change any code in the HAL layer.

As seen above, when accessing the hardware through the HAL, we need to pass a HAL specific enum like HAL_GPIO_OUT_PIN_0. These enums are stored in the instances that access the HAL layer. In the case of the DRV8323RS motor driver, the instances of the important pins are initialized with its pins assigned to the HAL enums as shown in the snippet below.

drv8323rs.enable  = HAL_GPIO_OUT_PIN_0;
drv8323rs.nfault  = HAL_PWM_FAULT_0;
drv8323rs.spi     = HAL_SPI_CHANNEL_0;
drv8323rs.spiCS   = HAL_SPI_CS_2;
drv8323rs.vsenvm  = HAL_ADC_CHANNEL_1;
drv8323rs.isena   = HAL_ADC_CHANNEL_2;
drv8323rs.isenb   = HAL_ADC_CHANNEL_0;
drv8323rs.isenc   = HAL_ADC_CHANNEL_3;

If the ENABLE pin needs to be set high, the API DRV8323RS_enable() is used and passes the DRV8323RS instance with it. The code snippet is shown below:

void DRV8323RS_enable(DRV8323RS_Instance *handle)
{
    /* Enable the DRV8323RS */
    HAL_setGPIOVal(handle->enable, HAL_GPIO_VALUE_HIGH);

    /* Startup delay for the DRV8323RS SPI to be ready */
    HAL_delayMilliSeconds(DRV8323RS_SPI_READY_DELAY_MS);
}

When DRV8323RS_enable() interacts with the HAL layer, it passes the member of the DRV8323RS instance. This is the same concept for using other HAL APIs such as the timer, SPI, DAC, etc. The user is free to expand the HAL’s API to support other peripherals and features of the MSPM0 but it is strongly recommended not to modify existing API to ensure easy migration to new versions of this library.

1.3 Motor Driver Module

Motor Driver Module uses the HAL APIs to motor driver specific operations APIs like SPI read, SPI write, voltage and current measurements. The idea of this module is to be independent of the hardware and use the HAL APIs to perform the hardware tasks specific to the motor driver.

Motor Driver Pin Association

The user before using the Motor Driver module is expected to specify the HAL enums mapped to the motor driver instance. See the below code snippet.

/* Assign the pins specific for the DRV */
drv8323rs.enable  = HAL_GPIO_OUT_PIN_0;
drv8323rs.nfault  = HAL_PWM_FAULT_0;
drv8323rs.spi     = HAL_SPI_CHANNEL_0;
drv8323rs.spiCS   = HAL_SPI_CS_2;
drv8323rs.vsenvm  = HAL_ADC_CHANNEL_1;
drv8323rs.isena   = HAL_ADC_CHANNEL_2;
drv8323rs.isenb   = HAL_ADC_CHANNEL_0;
drv8323rs.isenc   = HAL_ADC_CHANNEL_3;

Motor Driver APIs

The Motor Driver Module provides simple APIs which the user can use along with an instance of the motor drive module. The motor driver module APIs also handles the motor driver specific logic while keeping the APIs generic, thus the user can use different motor drivers and not worry of any difference in the internal logic. For example, below is an API for updating the SPI registers in the drv8323rs.

void DRV8323RS_spiUpdateRegister(DRV8323RS_Instance *handle,
                      DRV8323RS_REG_ADDR addr, uint32_t mask, uint16_t data)
{
    uint16_t dataValue;
    dataValue = (uint16_t) DRV8323RS_spiRead(handle, addr);
    dataValue &= ~(mask);
    dataValue |= data;
    DRV8323RS_spiWrite(handle, addr, dataValue);
}

Note from the above code snippet that any bit in the spi register in the DRV8323RS can be updated. The register address can be different for different devices, but here the enumerator DRV8323RS_REG_ADDR is used so the user doesn’t need to know the address of each register.

1.4 Sensorless FOC Library Module

Overview

The Sensorless FOC library contains generic algorithms for 3-phase sensorless FOC motor control. This module has APIs that the user can use to configure and control the FOC motor control. This module takes care of setting the PWM modulations based on the FOC algorithm. This module uses the HAL APIs for any using any hardware resources. The user is required to map the HAL PWM channels for the FOC module. Below is the code snippet that allocates the HAL PWM channels to the foc module.

/* Assign the pins specific for FOC */
foc.pwmAHal = HAL_PWM_CHANNEL_1;
foc.pwmBHal = HAL_PWM_CHANNEL_2;
foc.pwmCHal = HAL_PWM_CHANNEL_0;

1.5 MSPM0 DriverLib Overview

MSPM0 DriverLib is a set of fully functional APIs used to configure, control, and manipulate the hardware peripherals of the MSPM0 platform. Please refer to the DriverLib documentation for more information.