Math Engine Reference: Control

문서 탐색

Math Engine 전체 목차

개요

Scalar와 3차원 vector PID controller의 중립 C API를 선언한다.

Caller-owned state와 명시적 시간 간격을 사용하며 integral clamp와 output clamp로 deterministic anti-windup 동작을 제공한다.

실행 원본: include/math_engine/math_engine_control.h
분류: 물리·운동·제어

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_control.h>

Type과 callback

`math_engine_pid_config_f64_t`

Scalar PID 계수와 대칭 clamp 한계다. 0 한계는 해당 clamp를 비활성화한다.

typedef struct math_engine_pid_config_f64 {
    double kp; /**< Proportional gain in output units per error unit; finite. */
    double ki; /**< Integral gain in output units per error-unit second; finite. */
    double kd; /**< Derivative gain in output-unit seconds per error unit; finite. */
    double integral_limit; /**< Symmetric integral clamp; nonnegative, 0 disables it. */
    double output_limit; /**< Symmetric output clamp; nonnegative, 0 disables it. */
} math_engine_pid_config_f64_t;

math_engine_pid_config_f64_t.kp
Proportional gain in output units per error unit; finite.
```
double kp;
```
math_engine_pid_config_f64_t.ki
Integral gain in output units per error-unit second; finite.
```
double ki;
```
math_engine_pid_config_f64_t.kd
Derivative gain in output-unit seconds per error unit; finite.
```
double kd;
```
math_engine_pid_config_f64_t.integral_limit
Symmetric integral clamp; nonnegative, 0 disables it.
```
double integral_limit;
```
math_engine_pid_config_f64_t.output_limit
Symmetric output clamp; nonnegative, 0 disables it.
```
double output_limit;
```

`math_engine_pid_state_f64_t`

Scalar PID의 caller-owned 누적 상태다.

typedef struct math_engine_pid_state_f64 {
    double integral; /**< Accumulated integral contribution in output units. */
    double previous_error; /**< Previous finite error used by the derivative term. */
    uint32_t has_previous_error; /**< Boolean: 1 when =previous_error= is valid. */
    uint32_t reserved; /**< Forward-compatibility field; callers initialize it to 0. */
} math_engine_pid_state_f64_t;

math_engine_pid_state_f64_t.integral
Accumulated integral contribution in output units.
```
double integral;
```
math_engine_pid_state_f64_t.previous_error
Previous finite error used by the derivative term.
```
double previous_error;
```
math_engine_pid_state_f64_t.has_previous_error
Boolean: 1 when previous_error is valid.
```
uint32_t has_previous_error;
```
math_engine_pid_state_f64_t.reserved
Forward-compatibility field; callers initialize it to 0.
```
uint32_t reserved;
```

`math_engine_pid_vec3_state_f64_t`

3축 독립 PID의 caller-owned 누적 상태다.

typedef struct math_engine_pid_vec3_state_f64 {
    math_engine_vec3_f64_t integral; /**< Per-axis accumulated contribution in output units. */
    math_engine_vec3_f64_t previous_error; /**< Previous x/y/z error sample. */
    uint32_t has_previous_error; /**< Boolean: 1 when all three previous errors are valid. */
    uint32_t reserved; /**< Forward-compatibility field; callers initialize it to 0. */
} math_engine_pid_vec3_state_f64_t;

math_engine_pid_vec3_state_f64_t.integral
Per-axis accumulated contribution in output units.
```
math_engine_vec3_f64_t integral;
```
math_engine_pid_vec3_state_f64_t.previous_error
Previous x/y/z error sample.
```
math_engine_vec3_f64_t previous_error;
```
math_engine_pid_vec3_state_f64_t.has_previous_error
Boolean: 1 when all three previous errors are valid.
```
uint32_t has_previous_error;
```
math_engine_pid_vec3_state_f64_t.reserved
Forward-compatibility field; callers initialize it to 0.
```
uint32_t reserved;
```

`math_engine_pid_derivative_mode_t`

@brief Derivative 입력을 error 또는 measurement 변화에서 선택한다.

typedef enum math_engine_pid_derivative_mode {
    MATH_ENGINE_PID_DERIVATIVE_ON_ERROR = 0, /**< Differentiate setpoint-minus-measurement error. */
    MATH_ENGINE_PID_DERIVATIVE_ON_MEASUREMENT = 1 /**< Differentiate measurement with a negative sign. */
} math_engine_pid_derivative_mode_t;

math_engine_pid_derivative_mode_t.MATH_ENGINE_PID_DERIVATIVE_ON_ERROR
Differentiate setpoint-minus-measurement error.
```
MATH_ENGINE_PID_DERIVATIVE_ON_ERROR = 0,
```
math_engine_pid_derivative_mode_t.MATH_ENGINE_PID_DERIVATIVE_ON_MEASUREMENT
Differentiate measurement with a negative sign.
```
MATH_ENGINE_PID_DERIVATIVE_ON_MEASUREMENT = 1,
```

`math_engine_pid_anti_windup_mode_t`

@brief Output saturation 때 사용할 anti-windup 정책이다.

typedef enum math_engine_pid_anti_windup_mode {
    MATH_ENGINE_PID_ANTI_WINDUP_OFF = 0, /**< Integrate normally, subject only to integral bounds. */
    MATH_ENGINE_PID_ANTI_WINDUP_CONDITIONAL = 1, /**< Freeze integration that would deepen saturation. */
    MATH_ENGINE_PID_ANTI_WINDUP_BACK_CALCULATION = 2 /**< Feed saturation error back through the configured gain. */
} math_engine_pid_anti_windup_mode_t;

math_engine_pid_anti_windup_mode_t.MATH_ENGINE_PID_ANTI_WINDUP_OFF
Integrate normally, subject only to integral bounds.
```
MATH_ENGINE_PID_ANTI_WINDUP_OFF = 0,
```
math_engine_pid_anti_windup_mode_t.MATH_ENGINE_PID_ANTI_WINDUP_CONDITIONAL
Freeze integration that would deepen saturation.
```
MATH_ENGINE_PID_ANTI_WINDUP_CONDITIONAL = 1,
```
math_engine_pid_anti_windup_mode_t.MATH_ENGINE_PID_ANTI_WINDUP_BACK_CALCULATION
Feed saturation error back through the configured gain.
```
MATH_ENGINE_PID_ANTI_WINDUP_BACK_CALCULATION = 2,
```

`math_engine_pid_time_step_policy_t`

@brief 매 호출 시간 step을 검증하는 variable/fixed 정책이다.

typedef enum math_engine_pid_time_step_policy {
    MATH_ENGINE_PID_TIME_STEP_VARIABLE = 0, /**< Accept every finite positive caller-provided step. */
    MATH_ENGINE_PID_TIME_STEP_FIXED = 1 /**< Require the nominal step within its configured tolerance. */
} math_engine_pid_time_step_policy_t;

math_engine_pid_time_step_policy_t.MATH_ENGINE_PID_TIME_STEP_VARIABLE
Accept every finite positive caller-provided step.
```
MATH_ENGINE_PID_TIME_STEP_VARIABLE = 0,
```
math_engine_pid_time_step_policy_t.MATH_ENGINE_PID_TIME_STEP_FIXED
Require the nominal step within its configured tolerance.
```
MATH_ENGINE_PID_TIME_STEP_FIXED = 1,
```

`math_engine_pid_parameters_f64_t`

@brief Versioned canonical PID parameter와 finite inclusive bound다.

Integral state는 output 단위로 직접 저장한다. Fixed-step policy는 nominal_delta_seconds +/- fixed_delta_tolerance_seconds 만 허용하고 variable policy는 숨은 mode별 tuning 없이 caller가 제공한 각 양의 step을 사용한다.

typedef struct math_engine_pid_parameters_f64 {
    uint32_t struct_size; /**< Caller-provided byte size; at least =sizeof= this version. */
    uint32_t struct_version; /**< =MATH_ENGINE_PID_PARAMETERS_F64_VERSION_1=. */
    double kp; /**< Finite proportional gain in output units per error unit. */
    double ki; /**< Finite integral gain in output units per error-unit second. */
    double kd; /**< Finite derivative gain in output-unit seconds per input unit. */
    /** Nonnegative first-order filter time constant in seconds; 0 disables it. */
    double derivative_filter_time_constant_seconds;
    double integral_min; /**< Finite inclusive lower bound for =integral_term=. */
    double integral_max; /**< Finite inclusive upper bound, not below =integral_min=. */
    double output_min; /**< Finite inclusive lower bound for controller output. */
    double output_max; /**< Finite inclusive upper bound, not below =output_min=. */
    double back_calculation_gain; /**< Nonnegative saturation feedback gain; used only by back-calculation. */
    double nominal_delta_seconds; /**< Positive fixed step in seconds under FIXED policy. */
    double fixed_delta_tolerance_seconds; /**< Nonnegative allowed absolute deviation from the nominal step. */
    int32_t derivative_mode; /**< One =math_engine_pid_derivative_mode_t= value. */
    int32_t anti_windup_mode; /**< One =math_engine_pid_anti_windup_mode_t= value. */
    int32_t time_step_policy; /**< One =math_engine_pid_time_step_policy_t= value. */
    uint32_t reserved32; /**< Reserved for ABI growth; callers initialize it to 0. */
    uint64_t reserved[2]; /**< Reserved words; callers initialize both elements to 0. */
} math_engine_pid_parameters_f64_t;

math_engine_pid_parameters_f64_t.struct_size
Caller-provided byte size; at least sizeof this version.
```
uint32_t struct_size;
```
math_engine_pid_parameters_f64_t.struct_version
MATH_ENGINE_PID_PARAMETERS_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_pid_parameters_f64_t.kp
Finite proportional gain in output units per error unit.
```
double kp;
```
math_engine_pid_parameters_f64_t.ki
Finite integral gain in output units per error-unit second.
```
double ki;
```
math_engine_pid_parameters_f64_t.kd
Finite derivative gain in output-unit seconds per input unit.
```
double kd;
```
math_engine_pid_parameters_f64_t.derivative_filter_time_constant_seconds
Nonnegative first-order filter time constant in seconds; 0 disables it.
```
/** Nonnegative first-order filter time constant in seconds; 0 disables it. */
    double derivative_filter_time_constant_seconds;
```
math_engine_pid_parameters_f64_t.integral_min
Finite inclusive lower bound for integral_term.
```
double integral_min;
```
math_engine_pid_parameters_f64_t.integral_max
Finite inclusive upper bound, not below integral_min.
```
double integral_max;
```
math_engine_pid_parameters_f64_t.output_min
Finite inclusive lower bound for controller output.
```
double output_min;
```
math_engine_pid_parameters_f64_t.output_max
Finite inclusive upper bound, not below output_min.
```
double output_max;
```
math_engine_pid_parameters_f64_t.back_calculation_gain
Nonnegative saturation feedback gain; used only by back-calculation.
```
double back_calculation_gain;
```
math_engine_pid_parameters_f64_t.nominal_delta_seconds
Positive fixed step in seconds under FIXED policy.
```
double nominal_delta_seconds;
```
math_engine_pid_parameters_f64_t.fixed_delta_tolerance_seconds
Nonnegative allowed absolute deviation from the nominal step.
```
double fixed_delta_tolerance_seconds;
```
math_engine_pid_parameters_f64_t.derivative_mode
One math_engine_pid_derivative_mode_t value.
```
int32_t derivative_mode;
```
math_engine_pid_parameters_f64_t.anti_windup_mode
One math_engine_pid_anti_windup_mode_t value.
```
int32_t anti_windup_mode;
```
math_engine_pid_parameters_f64_t.time_step_policy
One math_engine_pid_time_step_policy_t value.
```
int32_t time_step_policy;
```
math_engine_pid_parameters_f64_t.reserved32
Reserved for ABI growth; callers initialize it to 0.
```
uint32_t reserved32;
```
math_engine_pid_parameters_f64_t.reserved
Reserved words; callers initialize both elements to 0.
```
uint64_t reserved[2];
```

`math_engine_pid_state_v2_f64_t`

@brief Canonical scalar PID history다. Parameter는 분리되어 immutable하다.

typedef struct math_engine_pid_state_v2_f64 {
    uint32_t struct_size; /**< Caller-provided byte size; at least =sizeof= this version. */
    uint32_t struct_version; /**< =MATH_ENGINE_PID_STATE_V2_F64_VERSION_1=. */
    double integral_term; /**< Current clamped integral contribution in output units. */
    double previous_error; /**< Previous setpoint-minus-measurement error. */
    double previous_measurement; /**< Previous measurement used by derivative-on-measurement. */
    double filtered_derivative; /**< Previous filtered derivative input per second. */
    double last_output; /**< Last committed saturated controller output. */
    uint32_t flags; /**< Bitwise OR of =MATH_ENGINE_PID_STATE_*= history flags. */
    uint32_t reserved32; /**< Reserved for ABI growth; initialize to 0. */
    uint64_t reserved[2]; /**< Reserved words; initialize both elements to 0. */
} math_engine_pid_state_v2_f64_t;

math_engine_pid_state_v2_f64_t.struct_size
Caller-provided byte size; at least sizeof this version.
```
uint32_t struct_size;
```
math_engine_pid_state_v2_f64_t.struct_version
MATH_ENGINE_PID_STATE_V2_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_pid_state_v2_f64_t.integral_term
Current clamped integral contribution in output units.
```
double integral_term;
```
math_engine_pid_state_v2_f64_t.previous_error
Previous setpoint-minus-measurement error.
```
double previous_error;
```
math_engine_pid_state_v2_f64_t.previous_measurement
Previous measurement used by derivative-on-measurement.
```
double previous_measurement;
```
math_engine_pid_state_v2_f64_t.filtered_derivative
Previous filtered derivative input per second.
```
double filtered_derivative;
```
math_engine_pid_state_v2_f64_t.last_output
Last committed saturated controller output.
```
double last_output;
```
math_engine_pid_state_v2_f64_t.flags
Bitwise OR of MATH_ENGINE_PID_STATE_* history flags.
```
uint32_t flags;
```
math_engine_pid_state_v2_f64_t.reserved32
Reserved for ABI growth; initialize to 0.
```
uint32_t reserved32;
```
math_engine_pid_state_v2_f64_t.reserved
Reserved words; initialize both elements to 0.
```
uint64_t reserved[2];
```

`math_engine_pid_result_f64_t`

@brief Scalar PID output과 deterministic 진단용 P/I/D decomposition이다.

typedef struct math_engine_pid_result_f64 {
    uint32_t struct_size; /**< Caller-provided byte size; at least =sizeof= this version. */
    uint32_t struct_version; /**< =MATH_ENGINE_PID_RESULT_F64_VERSION_1=. */
    uint32_t flags; /**< Bitwise OR of =MATH_ENGINE_PID_RESULT_*= diagnostics. */
    uint32_t reserved32; /**< Reserved for ABI growth; written as 0. */
    double output; /**< Final output after inclusive saturation. */
    double unsaturated_output; /**< Sum of P, I and D terms before output bounds. */
    double proportional_term; /**< Proportional contribution in output units. */
    double integral_term; /**< Committed integral contribution in output units. */
    double derivative_term; /**< Filtered derivative contribution in output units. */
    double error; /**< Current setpoint-minus-measurement error. */
    double derivative_input_per_second; /**< Selected filtered derivative input rate. */
    double delta_seconds; /**< Positive evaluated time interval in seconds. */
    double saturation_delta; /**< =output - unsaturated_output= in output units. */
    uint64_t reserved[2]; /**< Reserved words; written as 0. */
} math_engine_pid_result_f64_t;

math_engine_pid_result_f64_t.struct_size
Caller-provided byte size; at least sizeof this version.
```
uint32_t struct_size;
```
math_engine_pid_result_f64_t.struct_version
MATH_ENGINE_PID_RESULT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_pid_result_f64_t.flags
Bitwise OR of MATH_ENGINE_PID_RESULT_* diagnostics.
```
uint32_t flags;
```
math_engine_pid_result_f64_t.reserved32
Reserved for ABI growth; written as 0.
```
uint32_t reserved32;
```
math_engine_pid_result_f64_t.output
Final output after inclusive saturation.
```
double output;
```
math_engine_pid_result_f64_t.unsaturated_output
Sum of P, I and D terms before output bounds.
```
double unsaturated_output;
```
math_engine_pid_result_f64_t.proportional_term
Proportional contribution in output units.
```
double proportional_term;
```
math_engine_pid_result_f64_t.integral_term
Committed integral contribution in output units.
```
double integral_term;
```
math_engine_pid_result_f64_t.derivative_term
Filtered derivative contribution in output units.
```
double derivative_term;
```
math_engine_pid_result_f64_t.error
Current setpoint-minus-measurement error.
```
double error;
```
math_engine_pid_result_f64_t.derivative_input_per_second
Selected filtered derivative input rate.
```
double derivative_input_per_second;
```
math_engine_pid_result_f64_t.delta_seconds
Positive evaluated time interval in seconds.
```
double delta_seconds;
```
math_engine_pid_result_f64_t.saturation_delta
output - unsaturated_output in output units.
```
double saturation_delta;
```
math_engine_pid_result_f64_t.reserved
Reserved words; written as 0.
```
uint64_t reserved[2];
```

`math_engine_pid_vec3_state_v2_f64_t`

@brief 하나의 parameter 계약을 공유하는 세 독립 scalar history다.

typedef struct math_engine_pid_vec3_state_v2_f64 {
    uint32_t struct_size; /**< Caller-provided outer byte size. */
    uint32_t struct_version; /**< =MATH_ENGINE_PID_VEC3_STATE_V2_F64_VERSION_1=. */
    math_engine_pid_state_v2_f64_t axis[3]; /**< Independent x, y and z histories in that order. */
    uint64_t reserved[2]; /**< Reserved words; initialize both elements to 0. */
} math_engine_pid_vec3_state_v2_f64_t;

math_engine_pid_vec3_state_v2_f64_t.struct_size
Caller-provided outer byte size.
```
uint32_t struct_size;
```
math_engine_pid_vec3_state_v2_f64_t.struct_version
MATH_ENGINE_PID_VEC3_STATE_V2_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_pid_vec3_state_v2_f64_t.axis
Independent x, y and z histories in that order.
```
math_engine_pid_state_v2_f64_t axis[3];
```
math_engine_pid_vec3_state_v2_f64_t.reserved
Reserved words; initialize both elements to 0.
```
uint64_t reserved[2];
```

`math_engine_pid_vec3_result_f64_t`

@brief Atomic 3-channel PID output과 축별 saturation 결정 결과다.

typedef struct math_engine_pid_vec3_result_f64 {
    uint32_t struct_size; /**< Caller-provided outer byte size. */
    uint32_t struct_version; /**< =MATH_ENGINE_PID_VEC3_RESULT_F64_VERSION_1=. */
    uint32_t axis_flags[3]; /**< Per-axis =MATH_ENGINE_PID_RESULT_*= masks in x/y/z order. */
    uint32_t reserved32; /**< Reserved for ABI growth; written as 0. */
    math_engine_vec3_f64_t output; /**< Final saturated x/y/z outputs. */
    math_engine_vec3_f64_t unsaturated_output; /**< Pre-saturation x/y/z sums. */
    math_engine_vec3_f64_t proportional_term; /**< Per-axis proportional contributions. */
    math_engine_vec3_f64_t integral_term; /**< Per-axis committed integral contributions. */
    math_engine_vec3_f64_t derivative_term; /**< Per-axis derivative contributions. */
    math_engine_vec3_f64_t error; /**< Current x/y/z setpoint-minus-measurement errors. */
    math_engine_vec3_f64_t derivative_input_per_second; /**< Per-axis filtered derivative input rates. */
    double delta_seconds; /**< Positive time interval shared by all three axes, in seconds. */
    uint64_t reserved[2]; /**< Reserved words; written as 0. */
} math_engine_pid_vec3_result_f64_t;

math_engine_pid_vec3_result_f64_t.struct_size
Caller-provided outer byte size.
```
uint32_t struct_size;
```
math_engine_pid_vec3_result_f64_t.struct_version
MATH_ENGINE_PID_VEC3_RESULT_F64_VERSION_1.
```
uint32_t struct_version;
```
math_engine_pid_vec3_result_f64_t.axis_flags
Per-axis MATH_ENGINE_PID_RESULT_* masks in x/y/z order.
```
uint32_t axis_flags[3];
```
math_engine_pid_vec3_result_f64_t.reserved32
Reserved for ABI growth; written as 0.
```
uint32_t reserved32;
```
math_engine_pid_vec3_result_f64_t.output
Final saturated x/y/z outputs.
```
math_engine_vec3_f64_t output;
```
math_engine_pid_vec3_result_f64_t.unsaturated_output
Pre-saturation x/y/z sums.
```
math_engine_vec3_f64_t unsaturated_output;
```
math_engine_pid_vec3_result_f64_t.proportional_term
Per-axis proportional contributions.
```
math_engine_vec3_f64_t proportional_term;
```
math_engine_pid_vec3_result_f64_t.integral_term
Per-axis committed integral contributions.
```
math_engine_vec3_f64_t integral_term;
```
math_engine_pid_vec3_result_f64_t.derivative_term
Per-axis derivative contributions.
```
math_engine_vec3_f64_t derivative_term;
```
math_engine_pid_vec3_result_f64_t.error
Current x/y/z setpoint-minus-measurement errors.
```
math_engine_vec3_f64_t error;
```
math_engine_pid_vec3_result_f64_t.derivative_input_per_second
Per-axis filtered derivative input rates.
```
math_engine_vec3_f64_t derivative_input_per_second;
```
math_engine_pid_vec3_result_f64_t.delta_seconds
Positive time interval shared by all three axes, in seconds.
```
double delta_seconds;
```
math_engine_pid_vec3_result_f64_t.reserved
Reserved words; written as 0.
```
uint64_t reserved[2];
```

Anonymous enum

`anonymous_enum_at_line_86`

@brief PID 결과의 value, saturation, clamp와 filter 상태 bit다.

enum {
    MATH_ENGINE_PID_RESULT_VALUE = 1u << 0, /**< A finite output value was committed. */
    MATH_ENGINE_PID_RESULT_FIRST_SAMPLE = 1u << 1, /**< No previous sample was available for differentiation. */
    MATH_ENGINE_PID_RESULT_SATURATED_LOW = 1u << 2, /**< Output was clamped to =output_min=. */
    MATH_ENGINE_PID_RESULT_SATURATED_HIGH = 1u << 3, /**< Output was clamped to =output_max=. */
    MATH_ENGINE_PID_RESULT_INTEGRATOR_CLAMPED = 1u << 4, /**< Integral term reached an inclusive configured bound. */
    MATH_ENGINE_PID_RESULT_ANTI_WINDUP_ACTIVE = 1u << 5, /**< Selected anti-windup policy changed integration. */
    MATH_ENGINE_PID_RESULT_DERIVATIVE_FILTERED = 1u << 6 /**< Derivative low-pass filtering was applied. */
};

MATH_ENGINE_PID_RESULT_VALUE
A finite output value was committed.
```
MATH_ENGINE_PID_RESULT_VALUE = 1u << 0,
```
MATH_ENGINE_PID_RESULT_FIRST_SAMPLE
No previous sample was available for differentiation.
```
MATH_ENGINE_PID_RESULT_FIRST_SAMPLE = 1u << 1,
```
MATH_ENGINE_PID_RESULT_SATURATED_LOW
Output was clamped to output_min.
```
MATH_ENGINE_PID_RESULT_SATURATED_LOW = 1u << 2,
```
MATH_ENGINE_PID_RESULT_SATURATED_HIGH
Output was clamped to output_max.
```
MATH_ENGINE_PID_RESULT_SATURATED_HIGH = 1u << 3,
```
MATH_ENGINE_PID_RESULT_INTEGRATOR_CLAMPED
Integral term reached an inclusive configured bound.
```
MATH_ENGINE_PID_RESULT_INTEGRATOR_CLAMPED = 1u << 4,
```
MATH_ENGINE_PID_RESULT_ANTI_WINDUP_ACTIVE
Selected anti-windup policy changed integration.
```
MATH_ENGINE_PID_RESULT_ANTI_WINDUP_ACTIVE = 1u << 5,
```
MATH_ENGINE_PID_RESULT_DERIVATIVE_FILTERED
Derivative low-pass filtering was applied.
```
MATH_ENGINE_PID_RESULT_DERIVATIVE_FILTERED = 1u << 6,
```

`anonymous_enum_at_line_97`

@brief Canonical PID state에 저장된 history 상태 bit다.

enum {
    MATH_ENGINE_PID_STATE_HAS_PREVIOUS_SAMPLE = 1u << 0, /**< Previous error and measurement fields are valid. */
    MATH_ENGINE_PID_STATE_BUMPLESS_INITIALIZED = 1u << 1 /**< State was seeded for a bumpless first transition. */
};

MATH_ENGINE_PID_STATE_HAS_PREVIOUS_SAMPLE
Previous error and measurement fields are valid.
```
MATH_ENGINE_PID_STATE_HAS_PREVIOUS_SAMPLE = 1u << 0,
```
MATH_ENGINE_PID_STATE_BUMPLESS_INITIALIZED
State was seeded for a bumpless first transition.
```
MATH_ENGINE_PID_STATE_BUMPLESS_INITIALIZED = 1u << 1,
```

Macro와 constant

`MATH_ENGINE_PID_PARAMETERS_F64_VERSION_1`

Initial layout version for math_engine_pid_parameters_f64_t.

#define MATH_ENGINE_PID_PARAMETERS_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_PID_RESULT_F64_VERSION_1`

Initial layout version for math_engine_pid_result_f64_t.

#define MATH_ENGINE_PID_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_PID_STATE_V2_F64_VERSION_1`

Initial layout version for math_engine_pid_state_v2_f64_t.

#define MATH_ENGINE_PID_STATE_V2_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_PID_VEC3_RESULT_F64_VERSION_1`

Initial layout version for math_engine_pid_vec3_result_f64_t.

#define MATH_ENGINE_PID_VEC3_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_PID_VEC3_STATE_V2_F64_VERSION_1`

Initial layout version for math_engine_pid_vec3_state_v2_f64_t.

#define MATH_ENGINE_PID_VEC3_STATE_V2_F64_VERSION_1 UINT32_C(1)

Function

`math_engine_pid_parameters_f64_init`

P-only variable-step canonical PID parameter를 초기화한다.

매개변수 out_parameters (out): kp=1, =ki=kd=0, clamp/filter/anti-windup이 꺼진 결과.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.

Integral/output bound는 유한한 =+/-DBL_MAX=이고 모든 단위는 caller의 error/output 체계에서 결정된다.

Math Engine ownership: out_parameters=caller
Math Engine nullable: out_parameters=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_parameters_f64_init(
    math_engine_pid_parameters_f64_t* out_parameters);

`math_engine_pid_parameters_f64_validate`

Canonical PID gain, limit, mode, filter와 time-step policy를 검증한다.

매개변수 parameters (in): 검증할 initialized borrowed parameter POD.
반환: 성공 또는 size/version, unsupported mode, non-finite/범위 오류 code.

Filter time constant, back-calculation gain과 fixed-step tolerance는 0 이상이어야 하고, FIXED policy의 nominal step은 양수여야 한다. 입력을 변경하지 않는다.

Math Engine ownership: parameters=borrowed
Math Engine nullable: parameters=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_parameters_f64_validate(
    const math_engine_pid_parameters_f64_t* parameters);

`math_engine_pid_state_v2_f64_init`

History가 없는 canonical scalar PID state를 초기화한다.

매개변수 out_state (out): 모든 누적 값이 0이고 version이 설정된 caller-owned state.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_state=caller
Math Engine nullable: out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_state_v2_f64_init(
    math_engine_pid_state_v2_f64_t* out_state);

`math_engine_pid_state_v2_f64_reset`

초기화된 scalar PID state의 history를 원자적으로 지운다.

매개변수 state (in,out): size/version과 finite history를 먼저 검증할 caller-owned state.
반환: 성공 또는 storage validation 상태 code.

성공 시 ABI identity를 유지한 empty state가 되며 실패 시 기존 state를 보존한다.

Math Engine ownership: state=caller
Math Engine nullable: state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_state_v2_f64_reset(
    math_engine_pid_state_v2_f64_t* state);

`math_engine_pid_state_v2_f64_reset_bumpless`

현재 P+I가 bounded tracking output과 맞도록 bumpless state를 초기화한다.

매개변수 parameters (in): 검증된 borrowed canonical PID parameter.
매개변수 setpoint (in): 현재 setpoint 값.
매개변수 measurement (in): 현재 measurement 값.
매개변수 tracking_output (in): 추종할 현재 actuator output.
매개변수 out_state (in,out): 미리 초기화된 caller-owned state.
반환: 성공 또는 validation/non-finite/overflow 상태 code.

error=setpoint-measurement 를 history에 넣어 다음 derivative kick을 제거하고 tracking output에서 P term을 뺀 값을 integral/output bound로 clamp한다. Parameter와 state는 겹치면 안 되고 실패 시 state를 보존한다.

Math Engine ownership: parameters=borrowed out_state=caller
Math Engine nullable: parameters=false out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_state_v2_f64_reset_bumpless(
    const math_engine_pid_parameters_f64_t* parameters,
    double setpoint,
    double measurement,
    double tracking_output,
    math_engine_pid_state_v2_f64_t* out_state);

`math_engine_pid_result_f64_init`

Canonical scalar PID 연산에 전달할 빈 결과 storage를 초기화한다.

매개변수 out_result (out): size/version이 설정되고 값이 0인 caller-owned 결과.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_result_f64_init(
    math_engine_pid_result_f64_t* out_result);

`math_engine_pid_preview_f64`

Borrowed state를 변경하지 않고 한 scalar PID transition을 preview한다.

매개변수 parameters (in): gain, bound, derivative/filter와 anti-windup 정책.
매개변수 state (in): 검증된 이전 scalar history.
매개변수 setpoint (in): 현재 setpoint.
매개변수 measurement (in): 현재 measurement.
매개변수 delta_seconds (in): 양의 step(s); FIXED policy이면 nominal tolerance 안이어야 한다.
매개변수 out_state (out): 다음 history. state 와 exact alias 가능하다.
매개변수 out_result (out): P/I/D decomposition, saturation과 적용된 output.
반환: 성공 또는 validation, range/non-finite/overflow 상태 code.

Derivative-on-error/measurement, 1-pole derivative filter, integral clamp와 선택한 anti-windup을 고정 순서로 계산한다. Exact in-place state 이외의 storage overlap은 금지하며 실패 시 두 output을 보존한다. 외부 state/callback을 사용하지 않아 deterministic하다.

Math Engine ownership: parameters=borrowed state=borrowed out_state=caller out_result=caller
Math Engine nullable: parameters=false state=false out_state=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_preview_f64(
    const math_engine_pid_parameters_f64_t* parameters,
    const math_engine_pid_state_v2_f64_t* state,
    double setpoint,
    double measurement,
    double delta_seconds,
    math_engine_pid_state_v2_f64_t* out_state,
    math_engine_pid_result_f64_t* out_result);

`math_engine_pid_step_v2_f64`

Preview와 동일한 canonical scalar PID transition을 caller output에 계산한다.

매개변수 parameters (in): 검증된 borrowed parameter.
매개변수 state (in): 이전 scalar history.
매개변수 setpoint (in): 현재 setpoint.
매개변수 measurement (in): 현재 measurement.
매개변수 delta_seconds (in): 양의 시간 간격(s).
매개변수 out_state (out): 다음 history. state 와 exact alias 가능하다.
매개변수 out_result (out): P/I/D와 saturation 진단 결과.
반환: 성공 또는 validation, range/non-finite/overflow 상태 code.

math_engine_pid_preview_f64 와 bit-identical evaluator를 사용한다. 다른 storage는 분리하고 실패 시 output을 보존한다.

Math Engine ownership: parameters=borrowed state=borrowed out_state=caller out_result=caller
Math Engine nullable: parameters=false state=false out_state=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_step_v2_f64(
    const math_engine_pid_parameters_f64_t* parameters,
    const math_engine_pid_state_v2_f64_t* state,
    double setpoint,
    double measurement,
    double delta_seconds,
    math_engine_pid_state_v2_f64_t* out_state,
    math_engine_pid_result_f64_t* out_result);

`math_engine_pid_vec3_state_v2_f64_init`

세 축의 독립 canonical scalar history를 empty state로 초기화한다.

매개변수 out_state (out): outer/axis size와 version이 설정된 caller-owned state.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_state=caller
Math Engine nullable: out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_state_v2_f64_init(
    math_engine_pid_vec3_state_v2_f64_t* out_state);

`math_engine_pid_vec3_state_v2_f64_reset`

초기화된 Vec3 PID state의 세 history를 원자적으로 지운다.

매개변수 state (in,out): 검증 후 reset할 caller-owned Vec3 state.
반환: 성공 또는 outer/axis storage validation 상태 code.

실패 시 세 축 모두 기존 값을 보존한다.

Math Engine ownership: state=caller
Math Engine nullable: state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_state_v2_f64_reset(
    math_engine_pid_vec3_state_v2_f64_t* state);

`math_engine_pid_vec3_result_f64_init`

Canonical Vec3 PID 연산에 전달할 빈 결과 storage를 초기화한다.

매개변수 out_result (out): size/version이 설정되고 값이 0인 caller-owned 결과.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_result_f64_init(
    math_engine_pid_vec3_result_f64_t* out_result);

`math_engine_pid_vec3_preview_f64`

공유 parameter로 세 scalar channel의 다음 state를 원자적으로 preview한다.

매개변수 parameters (in): 세 축에 공통 적용할 borrowed canonical PID parameter.
매개변수 state (in): 세 축의 이전 history.
매개변수 setpoint (in): x/y/z setpoint vector.
매개변수 measurement (in): x/y/z measurement vector.
매개변수 delta_seconds (in): 세 축에 공통인 양의 시간 간격(s).
매개변수 out_state (out): 다음 세 축 history. state 와 exact alias 가능하다.
매개변수 out_result (out): 축별 flag, P/I/D와 output vector.
반환: 성공 또는 어느 축에서든 validation/range/non-finite/overflow 상태 code.

x,y,z 순서로 같은 scalar evaluator를 local temporary에 적용한 뒤 모두 함께 commit한다. Exact state alias 외에는 모든 storage를 분리해야 하며 실패 시 두 output을 보존한다.

Math Engine ownership: parameters=borrowed state=borrowed setpoint=borrowed measurement=borrowed out_state=caller out_result=caller
Math Engine nullable: parameters=false state=false setpoint=false measurement=false out_state=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_preview_f64(
    const math_engine_pid_parameters_f64_t* parameters,
    const math_engine_pid_vec3_state_v2_f64_t* state,
    const math_engine_vec3_f64_t* setpoint,
    const math_engine_vec3_f64_t* measurement,
    double delta_seconds,
    math_engine_pid_vec3_state_v2_f64_t* out_state,
    math_engine_pid_vec3_result_f64_t* out_result);

`math_engine_pid_vec3_step_v2_f64`

Vec3 preview와 동일한 세 channel transition을 caller output에 계산한다.

매개변수 parameters (in): 세 축 공통 borrowed parameter.
매개변수 state (in): 이전 Vec3 history.
매개변수 setpoint (in): x/y/z setpoint vector.
매개변수 measurement (in): x/y/z measurement vector.
매개변수 delta_seconds (in): 양의 공통 시간 간격(s).
매개변수 out_state (out): 다음 Vec3 history. state 와 exact alias 가능하다.
매개변수 out_result (out): 축별 flag와 P/I/D/output 결과.
반환: 성공 또는 validation/range/non-finite/overflow 상태 code.

Preview와 bit-identical evaluator를 사용한다. 다른 storage는 겹치면 안 되고 실패 시 모든 output을 보존한다.

Math Engine ownership: parameters=borrowed state=borrowed setpoint=borrowed measurement=borrowed out_state=caller out_result=caller
Math Engine nullable: parameters=false state=false setpoint=false measurement=false out_state=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_step_v2_f64(
    const math_engine_pid_parameters_f64_t* parameters,
    const math_engine_pid_vec3_state_v2_f64_t* state,
    const math_engine_vec3_f64_t* setpoint,
    const math_engine_vec3_f64_t* measurement,
    double delta_seconds,
    math_engine_pid_vec3_state_v2_f64_t* out_state,
    math_engine_pid_vec3_result_f64_t* out_result);

`math_engine_pid_state_init_f64`

Scalar PID state를 0으로 초기화한다.

매개변수 out_state: 초기화할 caller storage.
반환: 성공 또는 음수 상태 code.
Math Engine ownership: out_state=caller
Math Engine nullable: out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_state_init_f64(
    math_engine_pid_state_f64_t* out_state);

`math_engine_pid_step_f64`

Error 한 step으로 scalar PID output과 다음 state를 계산한다.

매개변수 config: 유한한 계수와 음이 아닌 clamp를 가진 borrowed 설정.
매개변수 state: 이전 borrowed state.
매개변수 error: 현재 setpoint-minus-measurement error.
매개변수 delta_seconds: 양의 시간 간격(s).
매개변수 out_output: 결과 output을 받을 caller storage.
매개변수 out_state: 다음 state를 받을 caller storage. 입력 state와 같아도 된다.
반환: 성공 또는 음수 상태 code. 실패 시 output들은 변경하지 않는다.
Math Engine ownership: config=borrowed state=borrowed out_output=caller out_state=caller
Math Engine nullable: config=false state=false out_output=false out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_step_f64(
    const math_engine_pid_config_f64_t* config,
    const math_engine_pid_state_f64_t* state,
    double error,
    double delta_seconds,
    double* out_output,
    math_engine_pid_state_f64_t* out_state);

`math_engine_pid_vec3_state_init_f64`

3축 독립 PID state를 0으로 초기화한다.

매개변수 out_state: 초기화할 caller storage.
반환: 성공 또는 음수 상태 code.
Math Engine ownership: out_state=caller
Math Engine nullable: out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_state_init_f64(
    math_engine_pid_vec3_state_f64_t* out_state);

`math_engine_pid_vec3_step_f64`

동일 config를 사용하는 3축 독립 PID step을 계산한다.

매개변수 config: borrowed PID 설정.
매개변수 state: 이전 borrowed vector state.
매개변수 error: 현재 3축 error.
매개변수 delta_seconds: 양의 시간 간격(s).
매개변수 out_output: 결과 vector output을 받을 caller storage.
매개변수 out_state: 다음 vector state를 받을 caller storage. 입력 state와 같아도 된다.
반환: 성공 또는 음수 상태 code. 실패 시 output들은 변경하지 않는다.
Math Engine ownership: config=borrowed state=borrowed error=borrowed out_output=caller out_state=caller
Math Engine nullable: config=false state=false error=false out_output=false out_state=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_pid_vec3_step_f64(
    const math_engine_pid_config_f64_t* config,
    const math_engine_pid_vec3_state_f64_t* state,
    const math_engine_vec3_f64_t* error,
    double delta_seconds,
    math_engine_vec3_f64_t* out_output,
    math_engine_pid_vec3_state_f64_t* out_state);

Math Engine Reference: Control

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_pid_config_f64_t

math_engine_pid_state_f64_t

math_engine_pid_vec3_state_f64_t

math_engine_pid_derivative_mode_t

math_engine_pid_anti_windup_mode_t

math_engine_pid_time_step_policy_t

math_engine_pid_parameters_f64_t

math_engine_pid_state_v2_f64_t

math_engine_pid_result_f64_t

math_engine_pid_vec3_state_v2_f64_t

math_engine_pid_vec3_result_f64_t

Anonymous enum

anonymous_enum_at_line_86

anonymous_enum_at_line_97

Macro와 constant

MATH_ENGINE_PID_PARAMETERS_F64_VERSION_1

MATH_ENGINE_PID_RESULT_F64_VERSION_1

MATH_ENGINE_PID_STATE_V2_F64_VERSION_1

MATH_ENGINE_PID_VEC3_RESULT_F64_VERSION_1

MATH_ENGINE_PID_VEC3_STATE_V2_F64_VERSION_1

Function

math_engine_pid_parameters_f64_init

math_engine_pid_parameters_f64_validate

math_engine_pid_state_v2_f64_init

math_engine_pid_state_v2_f64_reset

math_engine_pid_state_v2_f64_reset_bumpless

math_engine_pid_result_f64_init

math_engine_pid_preview_f64

math_engine_pid_step_v2_f64

math_engine_pid_vec3_state_v2_f64_init

math_engine_pid_vec3_state_v2_f64_reset

math_engine_pid_vec3_result_f64_init

math_engine_pid_vec3_preview_f64

math_engine_pid_vec3_step_v2_f64

math_engine_pid_state_init_f64

math_engine_pid_step_f64

math_engine_pid_vec3_state_init_f64

math_engine_pid_vec3_step_f64