File syn_autotune.h¶

FileList > control > syn_autotune.h

Motor controller auto-tuner — feedforward ID + relay PID tuning. More...

#include "../common/syn_defs.h"
#include "../motor/syn_motor_ctrl.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_AutoTune Auto-tuner instance.
struct	SYN_AutoTune_Config Auto-tuner configuration.
struct	SYN_AutoTune_Limits Physical constraints for the one-call auto-tune.
struct	SYN_AutoTune_LogFrame Telemetry frame for Auto-Tune capture.
struct	SYN_AutoTune_Result Auto-tune results (valid when state == DONE).

Public Types¶

Type	Name
enum	SYN_AutoTune_AbortReason Reason for auto-tune abort.
enum	SYN_AutoTune_Flags Auto-tuner feature flags.
enum	SYN_AutoTune_Method PID gain formula selection for relay auto-tune.
enum	SYN_AutoTune_Mode Auto-tune operating mode.
enum	SYN_AutoTune_State Auto-tuner state machine states.

Public Functions¶

Type	Name
void	syn_autotune_abort (SYN_AutoTune * at) Abort the auto-tune and stop the motor immediately.
void	syn_autotune_apply (SYN_AutoTune * at) Apply computed gains to the motor controller.
void	syn_autotune_calc_relay_gains (int32_t Ku, uint32_t Tu_ms, SYN_AutoTune_Method method, uint16_t multiplier_pct, int32_t * kp, int32_t * ki, int32_t * kd) Calculate Ziegler-Nichols / Tyreus-Luyben PID gains from ultimate gain (Ku) and period (Tu_ms).
SYN_Status	syn_autotune_init (SYN_AutoTune * at, SYN_MotorCtrl * ctrl, const SYN_AutoTune_Config * cfg) Initialize the auto-tuner.
SYN_Status	syn_autotune_start (SYN_AutoTune * at, SYN_MotorCtrl * ctrl, const SYN_AutoTune_Limits * limits, SYN_AutoTune_Flags flags, uint16_t gain_multiplier) Start a fully automatic tune sequence.
SYN_AutoTune_State	syn_autotune_update (SYN_AutoTune * at) Update the auto-tuner — call from main loop.

Public Static Functions¶

Type	Name
SYN_AutoTune_AbortReason	syn_autotune_abort_reason (const SYN_AutoTune * at) Get the reason for abort (valid when state == ABORTED).
const SYN_AutoTune_Result *	syn_autotune_result (const SYN_AutoTune * at) Get the tuning results (valid when state == DONE).

Macros¶

Type	Name
define	SYN_ATUNE_LOG_ID `0x4154 /\* 'AT' \/` Telemetry frame ID for Auto-Tune data.*

Detailed Description¶

Safety-first design for heavy machinery: * Hard position limit — abort if displacement exceeds configured bound * Velocity limit — cut power if speed exceeds safe threshold * Motor controller soft limits are respected (checked every update) * Watchdog timeout — auto-abort if update() stops being called * Gradual ramp-up (not a step) to avoid jerking heavy loads

Two layers of API:

syn_autotune_start() (recommended) — one-call auto-tune. Runs PROBE → FF identification → braking → relay PID tuning → braking automatically. The user only provides track limits.
syn_autotune_init() (advanced) — manual mode selection. The caller configures and runs each phase (FF ident, relay) separately.

Both are non-blocking — call syn_autotune_update() from your main loop.

** **

Step 1: Home the encoder. Zero the encoder at one end of the track. The auto-tuner does NOT require zeroing in the middle — it works with any zero convention.

Step 2: Configure the motor controller. Set position_min/max to your safe operating range (in encoder counts). These are the soft limits the auto-tuner will respect.

SYN_MotorCtrl_Config cfg = SYN_MOTOR_CTRL_DEFAULTS(
    syn_dc_motor_output(&motor), encoder_read, NULL, 1000, 1000
);
cfg.position_min  = 5000;     // 0.5m from home end (10000 cts/m)
cfg.position_max  = 495000;   // 0.5m from far end
syn_motor_ctrl_init(&ctrl, &cfg);

Step 3: Start auto-tune.

SYN_AutoTune at;
SYN_AutoTune_Limits limits = {
    .position_min = 5000,
    .position_max = 495000,
    .watchdog_ms  = 1000,    // abort if update() stops for 1s
};
syn_autotune_start(&at, &ctrl, &limits, SYN_ATUNE_FLAG_ALL);

Step 4: Poll from your main loop.

while (true) {
    SYN_AutoTune_State st = syn_autotune_update(&at);
    if (st == SYN_ATUNE_DONE) {
        syn_autotune_apply(&at); // Copy gains to controller
        break;
    }
    if (st == SYN_ATUNE_ABORTED) {
        // Error handling...
        break;
    }
    syn_port_sleep_ms(1); // or run from 1kHz interrupt
}

Public Types Documentation¶

enum SYN_AutoTune_AbortReason¶

Reason for auto-tune abort.

enum SYN_AutoTune_AbortReason {
    SYN_ATUNE_OK = 0,
    SYN_ATUNE_ABORT_POSITION = 1,
    SYN_ATUNE_ABORT_VELOCITY = 2,
    SYN_ATUNE_ABORT_SOFT_LIMIT = 3,
    SYN_ATUNE_ABORT_WATCHDOG = 4,
    SYN_ATUNE_ABORT_USER = 5,
    SYN_ATUNE_ABORT_STALL = 6,
    SYN_ATUNE_ABORT_NO_MOTION = 7
};

enum SYN_AutoTune_Flags¶

Auto-tuner feature flags.

enum SYN_AutoTune_Flags {
    SYN_ATUNE_FLAG_NONE = 0,
    SYN_ATUNE_FLAG_IDENT_KV = (1 << 0),
    SYN_ATUNE_FLAG_IDENT_KA = (1 << 1),
    SYN_ATUNE_FLAG_TUNE_PID = (1 << 2),
    SYN_ATUNE_FLAG_ALL =
        (SYN_ATUNE_FLAG_IDENT_KV | SYN_ATUNE_FLAG_IDENT_KA | SYN_ATUNE_FLAG_TUNE_PID)
};

enum SYN_AutoTune_Method¶

PID gain formula selection for relay auto-tune.

enum SYN_AutoTune_Method {
    SYN_ATUNE_ZN_CLASSIC = 0,
    SYN_ATUNE_ZN_NO_OVERSHOOT = 1,
    SYN_ATUNE_TYREUS_LUYBEN = 2
};

enum SYN_AutoTune_Mode¶

Auto-tune operating mode.

enum SYN_AutoTune_Mode {
    SYN_ATUNE_MODE_FF_IDENT = 0,
    SYN_ATUNE_MODE_RELAY = 1,
    SYN_ATUNE_MODE_AUTO = 2
};

enum SYN_AutoTune_State¶

Auto-tuner state machine states.

enum SYN_AutoTune_State {
    SYN_ATUNE_IDLE,
    SYN_ATUNE_PROBE,
    SYN_ATUNE_RAMP_UP,
    SYN_ATUNE_SETTLING,
    SYN_ATUNE_MEASURING,
    SYN_ATUNE_SETTLING_2,
    SYN_ATUNE_MEASURING_2,
    SYN_ATUNE_RELAY,
    SYN_ATUNE_BRAKING,
    SYN_ATUNE_RAMP_DOWN,
    SYN_ATUNE_DONE,
    SYN_ATUNE_ABORTED
};

Public Functions Documentation¶

function syn_autotune_abort¶

Abort the auto-tune and stop the motor immediately.

void syn_autotune_abort (
    SYN_AutoTune * at
)

Parameters:

at Auto-tuner instance.

function syn_autotune_apply¶

Apply computed gains to the motor controller.

void syn_autotune_apply (
    SYN_AutoTune * at
)

Copies ff_kv, ff_scale, and PID gains into the motor controller. Only valid when state == DONE.

Parameters:

at Auto-tuner instance.

function syn_autotune_calc_relay_gains¶

Calculate Ziegler-Nichols / Tyreus-Luyben PID gains from ultimate gain (Ku) and period (Tu_ms).

void syn_autotune_calc_relay_gains (
    int32_t Ku,
    uint32_t Tu_ms,
    SYN_AutoTune_Method method,
    uint16_t multiplier_pct,
    int32_t * kp,
    int32_t * ki,
    int32_t * kd
)

Parameters:

Ku Ultimate gain (scaled by pid_scale).
Tu_ms Ultimate period in milliseconds.
method Tuning rule (Ziegler-Nichols, Tyreus-Luyben, No-Overshoot).
multiplier_pct Gain safety multiplier percentage (1-200, e.g. 80 for 80%).
kp Output proportional gain.
ki Output integral gain.
kd Output derivative gain.

function syn_autotune_init¶

Initialize the auto-tuner.

SYN_Status syn_autotune_init (
    SYN_AutoTune * at,
    SYN_MotorCtrl * ctrl,
    const SYN_AutoTune_Config * cfg
)

Parameters:

at Auto-tuner instance.
ctrl Motor controller to tune (tuner takes control while active).
cfg Configuration. position_limit MUST be set.

Returns:

SYN_OK, or SYN_ERROR if position_limit is 0.

function syn_autotune_start¶

Start a fully automatic tune sequence.

SYN_Status syn_autotune_start (
    SYN_AutoTune * at,
    SYN_MotorCtrl * ctrl,
    const SYN_AutoTune_Limits * limits,
    SYN_AutoTune_Flags flags,
    uint16_t gain_multiplier
)

Runs probe → FF identification → braking → relay PID tune → braking as a single self-sequencing state machine. The user only provides physical constraints.

Parameters:

at Auto-tuner instance.
ctrl Motor controller to tune.
limits Physical constraints (track limits, max velocity).
flags Feature flags (e.g., SYN_ATUNE_FLAG_ALL).
gain_multiplier Safety margin for PID gains (percentage, e.g., 80).

Returns:

SYN_OK on success, or error code.

function syn_autotune_update¶

Update the auto-tuner — call from main loop.

SYN_AutoTune_State syn_autotune_update (
    SYN_AutoTune * at
)

Parameters:

at Auto-tuner instance.

Returns:

Current state. When DONE, results are in syn_autotune_result().

Public Static Functions Documentation¶

function syn_autotune_abort_reason¶

Get the reason for abort (valid when state == ABORTED).

static inline SYN_AutoTune_AbortReason syn_autotune_abort_reason (
    const SYN_AutoTune * at
)

Parameters:

at Autotuner instance.

Returns:

Abort reason code.

function syn_autotune_result¶

Get the tuning results (valid when state == DONE).

static inline const SYN_AutoTune_Result * syn_autotune_result (
    const SYN_AutoTune * at
)

Parameters:

at Autotuner instance.

Returns:

Pointer to results struct.

Macro Definition Documentation¶

define SYN_ATUNE_LOG_ID¶

Telemetry frame ID for Auto-Tune data.

#define SYN_ATUNE_LOG_ID `0x4154 /* 'AT' */`

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