API for the qPID Controller library. More...

Data Structures
struct	qPID_Gains_t
	PID Gains structure. More...

struct	qPID_AutoTuning_t
	A PID Auto-tuning object. More...

struct	qPID_controller_t
	A PID controller object. More...

Macros
#define	QPID_AUTOTUNING_UNDEFINED
	Macro to keep the auto-tuner enabled indefinitely.

Enumerations
enum	qPID_Type_t { qPID_TYPE_P , qPID_TYPE_PD , qPID_TYPE_PI , qPID_TYPE_PID }
	Enumeration class with the operational modes for the PID controller. More...

enum	qPID_Mode_t { qPID_Automatic , qPID_Manual }
	Enumeration with the operational modes for the PID controller. More...

enum	qPID_Direction_t { qPID_Forward , qPID_Backward }
	Direction modes of the PID controller. More...

Functions
int	qPID_Setup (qPID_controller_t *const c, const float kc, const float ki, const float kd, const float dt)
	Setup and initialize the PID controller instance.

int	qPID_SetDirection (qPID_controller_t *const c, const qPID_Direction_t d)
	Set the PID control action direction.

int	qPID_SetParams (qPID_controller_t *const c, const float kc, const float ti, const float td)
	Set/Change the PID controller gains by using the [Kc, Ti Td ] triplet.

int	qPID_SetGains (qPID_controller_t *const c, const float kc, const float ki, const float kd)
	Set/Change the PID controller gains.

int	qPID_SetExtraGains (qPID_controller_t *const c, const float kw, const float kt)
	Set/Change extra PID controller gains.

int	qPID_Reset (qPID_controller_t *const c)
	Reset the internal PID controller calculations.

int	qPID_SetSaturation (qPID_controller_t *const c, const float min, const float max)
	Setup the output saturation for the PID controller.

int	qPID_SetSeries (qPID_controller_t *const c)
	Convert the controller gains to conform the series or interacting form.

int	qPID_SetEpsilon (qPID_controller_t *const c, const float eps)
	Set the minimum value considered as error.

int	qPID_SetDerivativeFilter (qPID_controller_t *const c, const float beta)
	Set the tuning parameter for the derivative filter.

int	qPID_SetReferenceWeighting (qPID_controller_t *const c, const float gb, const float gc)
	Set the PID Reference(Set-Point) Weighting. This value is used in order to avoid the increase of the rise time due to the smoothing of the reference signal applied to the closed-loop system.

int	qPID_SetManualInput (qPID_controller_t *const c, const float manualInput)
	Set the PID manual input mode. This value will be used as the manual input when the controller it set into the qPID_Manual mode. Bumpless-transfer is guaranteed.

int	qPID_SetMode (qPID_controller_t *const c, const qPID_Mode_t m)
	Change the controller operational mode. In qPID_Automatic mode, the computed output of the PID controller will be used as the control signal for the process. In qPID_Manual mode, the manual input will be used as the control signal for the process and the PID controller loop will continue operating to guarantee the bumpless-transfer when a switch to the qPID_Automatic mode its performed;.

int	qPID_SetMRAC (qPID_controller_t const c, const float modelRef, const float gamma)
	Enable the additive MRAC(Model Reference Adaptive Control) feature.

float	qPID_Control (qPID_controller_t *const c, const float w, const float y)
	Computes the control action for given PID controller instance.

int	qPID_BindAutoTuning (qPID_controller_t const c, qPID_AutoTuning_t const at)
	Binds the specified instance to enable the PID controller auto tuning algorithm.

int	qPID_EnableAutoTuning (qPID_controller_t *const c, const uint32_t tEnable)
	Set the number of time steps where the auto tuner algorithm will modify the controller gains.

int	qPID_AutoTuningComplete (const qPID_controller_t *const c)
	Verifies that the auto tuning process has finished with new gains set on the controller.

int	qPID_AutoTuningSetParameters (qPID_controller_t *const c, const float mu, const float alfa, const float lambda)
	Change parameters of the auto-tuning algorithm.

int	qPID_SetIntegrationMethod (qPID_controller_t *const c, qNumA_IntegrationMethod_t im)
	Set integration method for the PID controller.

bool	qPID_AutoTunningControllerType (qPID_controller_t *c, const qPID_Type_t t)

Detailed Description

API for the qPID Controller library.

For a brief description of this module, please read PID Controller

Enumeration Type Documentation

◆ qPID_Direction_t

enum qPID_Direction_t

Direction modes of the PID controller.

Enumerator
qPID_Forward	Forward control action
qPID_Backward	Reverse the control action

◆ qPID_Mode_t

enum qPID_Mode_t

Enumeration with the operational modes for the PID controller.

Enumerator
qPID_Automatic	Fully operational closed-loop PID controller
qPID_Manual	Open-loop with manual input

◆ qPID_Type_t

enum qPID_Type_t

Enumeration class with the operational modes for the PID controller.

Enumerator
qPID_TYPE_P	Proportional controller
qPID_TYPE_PD	Proportional-Integral controller
qPID_TYPE_PI	Proportional-Derivative controller
qPID_TYPE_PID	Proportional-Integral-Derivative controller

Function Documentation

◆ qPID_AutoTuningComplete()

int qPID_AutoTuningComplete ( const qPID_controller_t *const c )

Verifies that the auto tuning process has finished with new gains set on the controller.

Parameters

[in] c A pointer to the PID controller instance.

Returns: 1 if auto-tuning its complete, otherwise return 0.

◆ qPID_AutoTuningSetParameters()

int qPID_AutoTuningSetParameters	(	qPID_controller_t *const	c,
		const float	mu,
		const float	alfa,
		const float	lambda )

Change parameters of the auto-tuning algorithm.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	mu	Algorithm momentum. [ 0 <= alfa <= 1 ].
[in]	alfa	Final controller speed adjustment. [ 0 < alfa <= 1 ].
[in]	lambda	Algorithm forgetting factor [ 0.8 <= lambda <= 1 ].

Returns: 1 on success, 0 on failure.

◆ qPID_BindAutoTuning()

int qPID_BindAutoTuning	(	qPID_controller_t *const	c,
		qPID_AutoTuning_t *const	at )

Binds the specified instance to enable the PID controller auto tuning algorithm.

Note: To unbind the auto-tuning algorithm, pass NULL as argument.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	at	A pointer to the PID auto tuning instance.

Returns: 1 on success, otherwise return 0.

◆ qPID_Control()

float qPID_Control	(	qPID_controller_t *const	c,
		const float	w,
		const float	y )

Computes the control action for given PID controller instance.

Precondition: Instance must be previously initialized by qPID_Setup()

Note: The user must ensure that this function is executed in the time specified in dt either by using a HW or SW timer, a real time task, or a timing service.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	w	The reference value aka SetPoint.
[in]	y	The controlled variable aka Process-variable.

Returns: The control action.

◆ qPID_EnableAutoTuning()

int qPID_EnableAutoTuning	(	qPID_controller_t *const	c,
		const uint32_t	tEnable )

Set the number of time steps where the auto tuner algorithm will modify the controller gains.

Precondition: Controller must have an qPID_AutoTuning_t object already binded wih qPID_BindAutoTuning()

Note: To disable auto-tuning pass a 0uL value to the tEnable argument.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	tEnable	The number of time steps. To keep the auto tuner enabled indefinitely pass QPID_AUTOTUNING_UNDEFINED as argument.

Returns: 1 on success, otherwise return 0.

◆ qPID_Reset()

int qPID_Reset ( qPID_controller_t *const c )

Reset the internal PID controller calculations.

Parameters

[in] c A pointer to the PID controller instance.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetDerivativeFilter()

int qPID_SetDerivativeFilter	(	qPID_controller_t *const	c,
		const float	beta )

Set the tuning parameter for the derivative filter.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	beta	The tuning parameter. [ 0 < beta < 1 ]

Returns: 1 on success, otherwise return 0.

◆ qPID_SetDirection()

int qPID_SetDirection	(	qPID_controller_t *const	c,
		const qPID_Direction_t	d )

Set the PID control action direction.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	d	Desired output direction.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetEpsilon()

int qPID_SetEpsilon	(	qPID_controller_t *const	c,
		const float	eps )

Set the minimum value considered as error.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	eps	The minimal error value.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetExtraGains()

int qPID_SetExtraGains	(	qPID_controller_t *const	c,
		const float	kw,
		const float	kt )

Set/Change extra PID controller gains.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	kw	Saturation feedback gain. Used for antiWindup and bumpless transfer. A zero value disables these features.
[in]	kt	Manual input gain.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetGains()

int qPID_SetGains	(	qPID_controller_t *const	c,
		const float	kc,
		const float	ki,
		const float	kd )

Set/Change the PID controller gains.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	kc	Proportional Gain.
[in]	ki	Integral Gain.
[in]	kd	Derivative Gain.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetIntegrationMethod()

int qPID_SetIntegrationMethod	(	qPID_controller_t *const	c,
		qNumA_IntegrationMethod_t	im )

Set integration method for the PID controller.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	im	The desired integration method. Use one of the following:

qNumA_IntegralRe : Integrate using the Rectangular rule.

qNumA_IntegralTr : (default) Integrate using the Trapezoidal rule.

qNumA_IntegralSi : Integrate using the Simpson's 1/3 rule.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetManualInput()

int qPID_SetManualInput	(	qPID_controller_t *const	c,
		const float	manualInput )

Set the PID manual input mode. This value will be used as the manual input when the controller it set into the qPID_Manual mode. Bumpless-transfer is guaranteed.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	manualInput	The value of the manual input.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetMode()

int qPID_SetMode	(	qPID_controller_t *const	c,
		const qPID_Mode_t	m )

Change the controller operational mode. In qPID_Automatic mode, the computed output of the PID controller will be used as the control signal for the process. In qPID_Manual mode, the manual input will be used as the control signal for the process and the PID controller loop will continue operating to guarantee the bumpless-transfer when a switch to the qPID_Automatic mode its performed;.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	m	The desired operational mode.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetMRAC()

int qPID_SetMRAC	(	qPID_controller_t *const	c,
		const float *	modelRef,
		const float	gamma )

Enable the additive MRAC(Model Reference Adaptive Control) feature.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	modelRef	A pointer to the output of the model reference.
[in]	gamma	Adjustable parameter to indicate the adaptation speed.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetParams()

int qPID_SetParams	(	qPID_controller_t *const	c,
		const float	kc,
		const float	ti,
		const float	td )

Set/Change the PID controller gains by using the [Kc, Ti Td ] triplet.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	kc	Proportional Gain.
[in]	ti	Integral time.
[in]	td	Derivative time.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetReferenceWeighting()

int qPID_SetReferenceWeighting	(	qPID_controller_t *const	c,
		const float	gb,
		const float	gc )

Set the PID Reference(Set-Point) Weighting. This value is used in order to avoid the increase of the rise time due to the smoothing of the reference signal applied to the closed-loop system.

Note: A value close to zero en gc can be used to eliminate the reduce the effect of the phenomena called Derivative Kick

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	gb	The reference weight value for the proportional element.
[in]	gc	The reference weight value for the derivative element.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetSaturation()

int qPID_SetSaturation	(	qPID_controller_t *const	c,
		const float	min,
		const float	max )

Setup the output saturation for the PID controller.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	min	The minimal value allowed for the output.
[in]	max	The maximal value allowed for the output.

Returns: 1 on success, otherwise return 0.

◆ qPID_SetSeries()

int qPID_SetSeries ( qPID_controller_t *const c )

Convert the controller gains to conform the series or interacting form.

Parameters

[in] c A pointer to the PID controller instance.

Returns: 1 on success, otherwise return 0.

◆ qPID_Setup()

int qPID_Setup	(	qPID_controller_t *const	c,
		const float	kc,
		const float	ki,
		const float	kd,
		const float	dt )

Setup and initialize the PID controller instance.

Parameters

[in]	c	A pointer to the PID controller instance.
[in]	kc	Proportional Gain.
[in]	ki	Integral Gain.
[in]	kd	Derivative Gain.
[in]	dt	Time step in seconds.

Returns: 1 on success, otherwise return 0.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ qPID_Direction_t

◆ qPID_Mode_t

◆ qPID_Type_t

Function Documentation

◆ qPID_AutoTuningComplete()

◆ qPID_AutoTuningSetParameters()

◆ qPID_BindAutoTuning()

◆ qPID_Control()

◆ qPID_EnableAutoTuning()

◆ qPID_Reset()

◆ qPID_SetDerivativeFilter()

◆ qPID_SetDirection()

◆ qPID_SetEpsilon()

◆ qPID_SetExtraGains()

◆ qPID_SetGains()

◆ qPID_SetIntegrationMethod()

◆ qPID_SetManualInput()

◆ qPID_SetMode()

◆ qPID_SetMRAC()

◆ qPID_SetParams()

◆ qPID_SetReferenceWeighting()

◆ qPID_SetSaturation()

◆ qPID_SetSeries()

◆ qPID_Setup()