File syn_pid.h¶

FileList > control > syn_pid.h

General-purpose PID controller — integer arithmetic. More...

#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_PID PID controller instance — config + accumulated state.
struct	SYN_PID_Config PID controller configuration.

Public Functions¶

Type	Name
void	syn_pid_init (SYN_PID * pid, const SYN_PID_Config * cfg) Initialize PID controller.
void	syn_pid_reset (SYN_PID * pid) Reset integral and derivative state.
void	syn_pid_set_gains (SYN_PID * pid, int32_t kp, int32_t ki, int32_t kd) Update gains at runtime.
void	syn_pid_set_limits (SYN_PID * pid, int32_t out_min, int32_t out_max) Set output clamping limits.
int32_t	syn_pid_update (SYN_PID * pid, int32_t setpoint, int32_t measured, uint32_t dt_ms) Compute one PID update step.

Public Static Functions¶

Type	Name
int32_t	syn_pid_output (const SYN_PID * pid) Get the last computed output.

Macros¶

Type	Name
define	SYN_PID_GAINS (kp_f, ki_f, kd_f, scale_val, omin, omax) `/* multi line expression /` Convenience macro to create a PID config from human-readable gains.*

Detailed Description¶

A discrete-time PID with anti-windup, output clamping, derivative filtering, and configurable gain scaling. Works for motor speed, temperature, position, or any closed-loop control.

** **

All gains are integers divided by scale. This allows fractional control without floating-point:

Parameter	Effective value	Notes
kp	kp / scale	Proportional
ki	ki / (scale × 1000)	Note the ×1000 for time normalization
kd	kd / scale	Derivative (with dt normalization)

The I-term accumulates error×dt_ms, so the division by 1000 converts millisecond-accumulation into seconds. This means ki must be ~1000× larger than you'd expect compared to kp/kd for equivalent effect.

** **

Use SYN_PID_GAINS() to set gains from intuitive values:

// Instead of manually computing scaled values:
SYN_PID_Config cfg = SYN_PID_GAINS(
    1.5,    // kp (proportional)
    0.5,    // ki (integral, per-second — NOT per-millisecond)
    0.1,    // kd (derivative)
    256,    // scale
    -1000, 1000  // output range
);
// Produces: kp=384, ki=128000, kd=25, scale=256

** **

SYN_PID pid;
SYN_PID_Config cfg = {
    .kp = 100, .ki = 10000, .kd = 50,
    .scale = 100,        // gains are /100
    .out_min = -1000, .out_max = 1000,
    .d_filter_alpha = 128,
};
syn_pid_init(&pid, &cfg);

// In control loop (e.g., every 10ms):
int32_t output = syn_pid_update(&pid, setpoint, measured, dt_ms);

Public Functions Documentation¶

function syn_pid_init¶

Initialize PID controller.

void syn_pid_init (
    SYN_PID * pid,
    const SYN_PID_Config * cfg
)

If integral_max is 0, it is auto-computed from ki, scale, and out_max to allow full integral authority without windup.

Parameters:

pid PID instance.
cfg Configuration (copied internally).

function syn_pid_reset¶

Reset integral and derivative state.

void syn_pid_reset (
    SYN_PID * pid
)

Parameters:

pid PID instance.

function syn_pid_set_gains¶

Update gains at runtime.

void syn_pid_set_gains (
    SYN_PID * pid,
    int32_t kp,
    int32_t ki,
    int32_t kd
)

Parameters:

pid PID instance.
kp Proportional gain.
ki Integral gain.
kd Derivative gain.

function syn_pid_set_limits¶

Set output clamping limits.

void syn_pid_set_limits (
    SYN_PID * pid,
    int32_t out_min,
    int32_t out_max
)

Parameters:

pid PID instance.
out_min Minimum output.
out_max Maximum output.

function syn_pid_update¶

Compute one PID update step.

int32_t syn_pid_update (
    SYN_PID * pid,
    int32_t setpoint,
    int32_t measured,
    uint32_t dt_ms
)

Parameters:

pid PID instance.
setpoint Desired value.
measured Actual measured value.
dt_ms Time since last update in milliseconds. (0 is treated as 1 to avoid division by zero.)

Returns:

Clamped output value.

Public Static Functions Documentation¶

function syn_pid_output¶

Get the last computed output.

static inline int32_t syn_pid_output (
    const SYN_PID * pid
)

Parameters:

pid PID instance.

Returns:

Last output value.

Macro Definition Documentation¶

define SYN_PID_GAINS¶

Convenience macro to create a PID config from human-readable gains.

#define SYN_PID_GAINS (
    kp_f,
    ki_f,
    kd_f,
    scale_val,
    omin,
    omax
) `/* multi line expression */`

Accepts floating-point gain values and a scale factor. Computes the integer ki with the ×1000 factor built in, so you specify ki as a normal per-second integral gain.

Parameters:

kp_f Proportional gain (float).
ki_f Integral gain per second (float).
kd_f Derivative gain (float).
scale_val Integer scale divisor (e.g., 256).
omin Minimum output.
omax Maximum output.

Returns:

SYN_PID_Config struct initializer.

** **

SYN_PID_Config cfg = SYN_PID_GAINS(1.5, 0.5, 0.1, 256, -1000, 1000);
// kp = (int)(1.5 * 256)       = 384
// ki = (int)(0.5 * 256 * 1000) = 128000
// kd = (int)(0.1 * 256)       = 25

The documentation for this class was generated from the following file src/syntropic/control/syn_pid.h