MSP432 and TI-RTOS: PID Library Part 1 - Intro

What you need:

• MSP432 LaunchPad
• 1 micro-USB cable
• Code Composer Studio
• TI-RTOS for MSP43X

Why a PID Library?

When you build a power supply, you want to set the output voltage to a fixed level. And you want to keep it at that level, whatever happens.

When the user connects a heavy load, this shouldn't affect the output.

To get that working, you need to change the input signals to the circuit.

But how do you do that? How much change? How fast? How to prevent that the change pushes the output above the level?

And what if the load is removed?

That's a problem that the PID mechanism tries to resolve:

a stable control of the output, by measuring the difference with the desired output (error), using other factors (such as history) and changing the input signal (feedback) until balance is achieved.

The difference between the desired output and the actual current value is called the error.

P stands for proportional, I for Integral, D for differential. These are the mathematical terms that play a role in the calculations inside the PID library.

Why *This* Library?

Because it's based on a good one. It's an as true as possible port of Brett Beauregard's Arduino PID Library.

Because it has Tuning options.

Because it is extremely well documented. You should (really: should) read Brett's blog before continuing here: Improving the Beginner’s PID – Introduction « Project Blog.

Port for MSP432

It's not really for the MSP432, it's for any application that's in C. But I'm working on a MSP432 controlled project that needs PID.

As an object oriented design aficionado, I prefer to migrate C code to C++. In this case it's the other way around.

What's different from the Arduino lib?

We loose something along the road. Not encapsulation, because I try to expose only public functionality.

But with Brett's OO library, you can have multiple PID objects. That's useful when your instrument has to support different operating modi (e.g.: a power supply with either constant voltage or constant current).

With the Arduino library, you can create two objects, each with their own PID values. That doesn't work yet with my port.

I'm planning to add similar functionality in a later release. I need that myself.

The PID() constructor is replaced by an init function

void pidInit(double*, double*, double*, double, double, double, int)

Public constants are prefixed with "PID_"

  #define PID_AUTOMATIC 1
  #define PID_MANUAL    0
  #define PID_DIRECT  0
  #define PID_REVERSE  1

Public functions are prefixed with "pid"

    void pidInit(double*, double*, double*, double, double, double, int)
    void pidSetMode(int Mode)
    bool pidCompute()
    void pidSetOutputLimits(double, double)

    void pidSetTunings(double, double, double)
    void pidSetControllerDirection(int)
    void pidSetSampleTime(int)

    double pidGetKp()
    double pidGetKi()
    double pidGetKd()
    int pidGetMode()
    int pidGetDirection()

The Arduino millis() function internals are replaced with a TI-RTOS portable time function. This is private within the library.

    long millis() {
        long t = Timestamp_get32();
        long msecs = (t & 0x7fff) * 1000 /32768;
        return msecs;
    }

In your TI-RTOS project, you have to add this line of code to the very end of your .cfg file -  (double-click the file and then press the cfg Script tab at the bottom of the editor window):

/* ================ Application Specific Instances ================ */
var TimestampProvider = xdc.useModule('xdc.runtime.Timestamp');

The comment line is already in that file. Paste the line of code underneath it.

If you want to use this port in a non-TI-RTOS project, you'll have to build your own implementation of millis().

How is it used in an TI-RTOS project?

I'm not sure about that yet. My current project will hopefully show the right way to do it.

My current approach is to have an RTOS task schedule. The PID library prefers that the control loop runs at regular intervals.

#include "pid.h"

//Define Variables we'll be connecting to
double Setpoint, Input, Output;

/*
 *  ======== fnTaskPID ========
 *
 */
Void fnTaskPID(UArg arg0, UArg arg1)
{

    //Specify the links and initial tuning parameters
    double Kp=2, Ki=5, Kd=1; // todo make these good values for our strategy
    Setpoint = 0.0;
    pidSetSampleTime(((UInt)arg0) / Clock_tickPeriod);
    pidSetOutputLimits(0, 255);
    Input = 0.0; // 
    pidInit(&Input, &Output, &Setpoint, Kp, Ki, Kd, PID_DIRECT);

     //turn the PID on
     pidSetMode(PID_AUTOMATIC);

    while (1) {
        Task_sleep(((UInt)arg0) / Clock_tickPeriod);
    //      Input = analogRead(PIN_INPUT); todo: sample your device actual output value
            if (pidCompute()) {
              System_printf("setpoint = %f ; input = %f ; output =%f \n", Setpoint, Input, Output);
              System_flush();
    //        analogWrite(PIN_OUTPUT, Output);   todo: set your device input to this value. 
            }
    }
}

The default output range is 255. That may be rough for some situations. The bigger you set this value, the more steps the library can use.

It makes sense to define this relative to the method you're using to drive your instrument's input.

If you're using a 32-bit PWM module, you could use:

     pidSetOutputLimits(0, UINT32_MAX);

For a 14-bit DAC, you could set it to:

     pidSetOutputLimits(0, 0b11111111111111);

System.extendedFormats = '%$L%$S%$F%f';

You can register the task in source code (as done in the TI-RTOS empty example) or by setting it up in the TI-RTOS configuration editor (check here for instructions).

Choose the sleep time based on the requirements of your control process. The 1000 ms that I've put here are arbitrary. You may want to adjust your process faster or less frequent.

If you use the task code above, the PID library's sample time will automatically be initialised to the timeout you define in Argument 0.

This line of code takes care of that:

pidSetSampleTime(((UInt)arg0) / Clock_tickPeriod);

Don't forget to register the TimestampProvider in the .cfg file, as explained above.

          /*Compute all the working error variables*/
          double input = *myInput;
          double error = *mySetpoint - input;
          ITerm+= (ki * error);
          if(ITerm > outMax) ITerm= outMax;
          else if(ITerm < outMin) ITerm= outMin;
          double dInput = (input - lastInput);


          /*Compute PID Output*/
          double output = kp * error + ITerm- kd * dInput;


          if(output > outMax) output = outMax;
          else if(output < outMin) output = outMin;
          *myOutput = output;


          /*Remember some variables for next time*/
          lastInput = input;
          lastTime = now;

As you can see, my PID is WIP. The ported code is attached to this blog post as a zip archive.

(for the TM4C123GXL lovers, there's a full CCS project attached to this blog )

Have fun. Tell me if anything isn't OK please.