pid - Add PID controller and associated utility functions

addons/pid/$PBOPREFIX$

@@ -0,0 +1 @@
+x\cba\addons\pid

addons/pid/CfgEventHandlers.hpp

@@ -0,0 +1,11 @@
+class Extended_PreStart_EventHandlers {
+    class ADDON {
+        init = QUOTE(call COMPILE_SCRIPT(XEH_preStart));
+    };
+};
+
+class Extended_PreInit_EventHandlers {
+    class ADDON {
+        init = QUOTE(call COMPILE_SCRIPT(XEH_preInit));
+    };
+};

addons/pid/XEH_PREP.hpp

@@ -0,0 +1,7 @@
+PREP(create);
+PREP(error_degree);
+PREP(error_linear);
+PREP(reset);
+PREP(setGains);
+PREP(setpoint);
+PREP(update);

addons/pid/XEH_preInit.sqf

@@ -0,0 +1,7 @@
+#include "script_component.hpp"
+
+ADDON = false;
+
+#include "XEH_PREP.hpp"
+
+ADDON = true;

addons/pid/XEH_preStart.sqf

@@ -0,0 +1,3 @@
+#include "script_component.hpp"
+
+#include "XEH_PREP.hpp"

addons/pid/config.cpp

@@ -0,0 +1,17 @@
+#include "script_component.hpp"
+
+class CfgPatches {
+    class ADDON {
+        name = CSTRING(component);
+        units[] = {};
+        weapons[] = {};
+        requiredVersion = REQUIRED_VERSION;
+        requiredAddons[] = {"cba_common"};
+        author = "$STR_CBA_Author";
+        authors[] = {"tcvm"};
+        url = "$STR_CBA_URL";
+        VERSION_CONFIG;
+    };
+};
+
+#include "CfgEventHandlers.hpp"

addons/pid/fnc_create.sqf

@@ -0,0 +1,57 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_create
+
+Description:
+    Creates a PID controller.
+
+Parameters:
+    _pGain          - gain for the immediate error <NUMBER>
+                      (Default: 0)
+    _iGain          - gain for the persistent error over time <NUMBER>
+                      (Default: 0)
+    _dGain          - gain for the error rate over time <NUMBER>
+                      (Default: 0)
+    _setpoint       - initial setpoint for the controller <NUMBER>
+                      (Default: 0)
+    _min            - the minimum value the controller can return <NUMBER>
+                      (Default: -1e30)
+    _max            - the maximum value the controller can return <NUMBER>
+                      (Default: 1e30)
+    _historyLength  - how many past errors are stored and used to calculate the derivative/integral <NUMBER>
+                      (Default: 10)
+    _errorFunction  - the function which calculates the error which the controller operators <CODE>
+                      (Default: <CBA_pid_fnc_error_linear>)
+
+Returns:
+    _pid            - a PID controller <LOCATION>
+
+Examples:
+    (begin example)
+        private _pid = [1, 0.05, 0.2, 5, 0, 10, 15, CBA_pid_fnc_error_linear] call CBA_pid_fnc_create;
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(create);
+params [
+    ["_pGain", 0, [0]],
+    ["_iGain", 0, [0]],
+    ["_dGain", 0, [0]],
+    ["_setpoint", 0, [0]],
+    ["_min", -LARGE_NUMBER, [0]],
+    ["_max",  LARGE_NUMBER, [0]],
+    ["_historyLength", DEFAULT_HISTORY_LENGTH, [0]],
+    ["_errorFunction", FUNC(error_linear), [{}]]
+];
+
+private _pid = call CBA_fnc_createNamespace;
+_pid setVariable [QGVAR(gains), [_pGain, _iGain, _dGain]];
+_pid setVariable [QGVAR(bounds), [_min, _max]];
+_pid setVariable [QGVAR(history), []];
+_pid setVariable [QGVAR(historyLength), _historyLength];
+_pid setVariable [QGVAR(setpoint), _setpoint];
+_pid setVariable [QGVAR(errorFunction), _errorFunction];
+
+_pid

addons/pid/fnc_error_degree.sqf

@@ -0,0 +1,39 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_error_degree
+
+Description:
+    Error function that is adjusted for degree values.
+    This function will account for wraparound with values in the domain of [-180, 180] or [0, 360]
+
+Parameters:
+    _observed           - the observed value <NUMBER>
+    _setpoint           - the setpoint <NUMBER>
+
+Returns:
+    Wrapped error of `setpoint - observed` <NUMBER>
+
+Examples:
+    (begin example)
+        private _error = [350, 5] call CBA_pid_fnc_error_degree;
+        // _error == 15
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(error_degree);
+params [
+    ["_observed", 0, [0]],
+    ["_setpoint", 0, [0]]
+];
+
+private _absoluteError = _setpoint - _observed;
+private _error = _absoluteError;
+if (_absoluteError < -180) then {
+    _error = 360 + _absoluteError;
+};
+if (_absoluteError > 180) then {
+    _error = _absoluteError - 360;
+};
+_error

addons/pid/fnc_error_linear.sqf

@@ -0,0 +1,30 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_error_linear
+
+Description:
+    Linear error function.
+
+Parameters:
+    _observed           - the observed value <NUMBER>
+    _setpoint           - the setpoint <NUMBER>
+
+Returns:
+    Error of `setpoint - observed` <NUMBER>
+
+Examples:
+    (begin example)
+        private _error = [2, 5] call CBA_pid_fnc_error_linear;
+        // _error == 3
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(error_linear);
+params [
+    ["_observed", 0, [0]],
+    ["_setpoint", 0, [0]]
+];
+
+_setpoint - _observed

addons/pid/fnc_reset.sqf

@@ -0,0 +1,29 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_reset
+
+Description:
+    Reset a PID controller's history.
+
+Parameters:
+    _pid           - the controller <LOCATION>
+
+Returns:
+    Nothing
+
+Examples:
+    (begin example)
+        _pid call CBA_pid_fnc_reset;
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(reset);
+params [
+    ["_pid", locationNull, [locationNull]]
+];
+
+if (isNull _pid) exitWith {};
+
+_pid setVariable [QGVAR(history), []];

addons/pid/fnc_setGains.sqf

@@ -0,0 +1,50 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_setGains
+
+Description:
+    Set new gains for a PID controller.
+
+Parameters:
+    _pid        - a pid controller <LOCATION>
+    _pGain      - the new proportional gain <NUMBER><NIL> (Default: `nil`)
+                  OR
+                  `nil`, to keep the current gain
+    _iGain      - the new integral gain <NUMBER><NIL> (Default: `nil`)
+                  OR
+                  `nil`, to keep the current gain 
+    _dGain      - the new derivative gain <NUMBER><NIL> (Default: `nil`)
+                  OR
+                  `nil`, to keep the current gain
+Returns:
+    Nothing
+
+Examples:
+    (begin example)
+        [_pid, 5, nil, 0.2] call CBA_pid_fnc_setGains;
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(setGains);
+params [
+    ["_pid", locationNull, [locationNull]],
+    ["_pGain", nil, [0, nil]],
+    ["_iGain", nil, [0, nil]],
+    ["_dGain", nil, [0, nil]]
+];
+
+if (isNull _pid) exitWith {};
+
+(_pid getVariable [QGVAR(gains), [0, 0, 0]]) params ["_currentPGain", "_currentIGain", "_currentDGain"];
+if !(isNil "_pGain") then {
+    _currentPGain = _pGain;
+};
+if !(isNil "_iGain") then {
+    _currentIGain = _iGain;
+};
+if !(isNil "_dGain") then {
+    _currentDGain = _dGain;
+};
+_pid setVariable [QGVAR(gains), [_currentPGain, _currentIGain, _currentDGain]];

addons/pid/fnc_setpoint.sqf

@@ -0,0 +1,36 @@
+#include "script_component.hpp"
+/* ----------------------------------------------------------------------------
+Function: CBA_pid_fnc_setpoint
+
+Description:
+    Set a new setpoint for a PID controller.
+
+Parameters:
+    _pid        - a pid controller <LOCATION>
+    _setpoint   - the new target setpoint for the controller <NUMBER>
+    _reset      - if we want to reset the PID for the new setpoint <BOOL> (Default: true)
+
+Returns:
+    Nothing
+
+Examples:
+    (begin example)
+        [_pid, 42] call CBA_pid_fnc_setpoint;
+    (end)
+
+Author:
+    tcvm
+---------------------------------------------------------------------------- */
+SCRIPT(setpoint);
+params [
+    ["_pid", locationNull, [locationNull]],
+    ["_setpoint", 0, [0]],
+    ["_reset", true, [true]]
+];
+
+if (isNull _pid) exitWith {};
+
+_pid setVariable [QGVAR(setpoint), _setpoint];
+if (_reset) then {
+    _pid setVariable [QGVAR(history), []];
+};