Skip to main content

PID

The PID class simulates a PID controller. PID is an acronym for proportional, integral, derivative. PIDs are input feedback loops that try to reach a specific goal by measuring the difference between the input and the desired value, and then returning a new desired input.

A common example is a car's cruise control, which would give a PID the current speed and the desired speed, and the PID controller would return the desired throttle input to reach the desired speed.

Original code based upon the Arduino PID Library.

Properties​

POnE​

</>
PID.POnE: boolean

POnE stands for "Proportional on Error".

Set to true by default.

  • true: The PID applies the proportional calculation on the error.
  • false: The PID applies the proportional calculation on the measurement.

Setting this value to false may help the PID move smoother and help eliminate overshoot. 

local pid = PID.new(...)
pid.POnE = true|false

Functions​

new​

</>
PID.new(
min: number,--

Minimum value the PID can output

max: number,--

Maximum value the PID can output

kp: number,--

Proportional coefficient

ki: number,--

Integral coefficient

kd: number--

Derivative coefficient

) → PID

Constructs a new PID.

local pid = PID.new(0, 1, 0.1, 0, 0)

Reset​

</>
PID:Reset() → ()

Resets the PID to a zero start state.

Calculate​

</>
PID:Calculate(
setpoint: number,--

The desired point to reach

input: number--

The current inputted value

) → output: number

Calculates the new output based on the setpoint and input. For example, if the PID was being used for a car's throttle control where the throttle can be in the range of [0, 1], then the PID calculation might look like the following: 

local cruisePID = PID.new(0, 1, ...)
local desiredSpeed = 50

RunService.Heartbeat:Connect(function()
	local throttle = cruisePID:Calculate(desiredSpeed, car.CurrentSpeed)
	car:SetThrottle(throttle)
end)

Debug​

</>
PID:Debug(
name: string,--

Folder name

parent: Instance?--

Folder parent

) → ()

Creates a folder that contains attributes that can be used to tune the PID during runtime within the explorer.

Studio Only

This will only create the folder in Studio. In a real game server, this function will do nothing.

Destroy​

</>
PID:Destroy() → ()

Destroys the PID. This is only necessary if calling PID:Debug.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new PID.\n\n```lua\nlocal pid = PID.new(0, 1, 0.1, 0, 0)\n```",
            "params": [
                {
                    "name": "min",
                    "desc": "Minimum value the PID can output",
                    "lua_type": "number"
                },
                {
                    "name": "max",
                    "desc": "Maximum value the PID can output",
                    "lua_type": "number"
                },
                {
                    "name": "kp",
                    "desc": "Proportional coefficient",
                    "lua_type": "number"
                },
                {
                    "name": "ki",
                    "desc": "Integral coefficient",
                    "lua_type": "number"
                },
                {
                    "name": "kd",
                    "desc": "Derivative coefficient",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PID"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 54,
                "path": "src/pid/src/Shared/PID.lua"
            }
        },
        {
            "name": "Reset",
            "desc": "Resets the PID to a zero start state.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 70,
                "path": "src/pid/src/Shared/PID.lua"
            }
        },
        {
            "name": "Calculate",
            "desc": "Calculates the new output based on the setpoint and input. For example,\nif the PID was being used for a car's throttle control where the throttle\ncan be in the range of [0, 1], then the PID calculation might look like\nthe following:\n```lua\nlocal cruisePID = PID.new(0, 1, ...)\nlocal desiredSpeed = 50\n\nRunService.Heartbeat:Connect(function()\n\tlocal throttle = cruisePID:Calculate(desiredSpeed, car.CurrentSpeed)\n\tcar:SetThrottle(throttle)\nend)\n```",
            "params": [
                {
                    "name": "setpoint",
                    "desc": "The desired point to reach",
                    "lua_type": "number"
                },
                {
                    "name": "input",
                    "desc": "The current inputted value",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "output: number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 94,
                "path": "src/pid/src/Shared/PID.lua"
            }
        },
        {
            "name": "Debug",
            "desc": "Creates a folder that contains attributes that can be used to\ntune the PID during runtime within the explorer.\n\n:::info Studio Only\nThis will only create the folder in Studio. In a real game server,\nthis function will do nothing.",
            "params": [
                {
                    "name": "name",
                    "desc": "Folder name",
                    "lua_type": "string"
                },
                {
                    "name": "parent",
                    "desc": "Folder parent",
                    "lua_type": "Instance?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 129,
                "path": "src/pid/src/Shared/PID.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the PID. This is only necessary if calling `PID:Debug`.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 157,
                "path": "src/pid/src/Shared/PID.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "POnE",
            "desc": "POnE stands for \"Proportional on Error\".\n\nSet to `true` by default.\n\n- `true`: The PID applies the proportional calculation on the _error_.\n- `false`: The PID applies the proportional calculation on the _measurement_.\n\nSetting this value to `false` may help the PID move smoother and help\neliminate overshoot.\n\n```lua\nlocal pid = PID.new(...)\npid.POnE = true|false\n```",
            "lua_type": "boolean",
            "source": {
                "line": 39,
                "path": "src/pid/src/Shared/PID.lua"
            }
        }
    ],
    "types": [],
    "name": "PID",
    "desc": "The PID class simulates a [PID controller](https://en.wikipedia.org/wiki/PID_controller). PID is an acronym\nfor _proportional, integral, derivative_. PIDs are input feedback loops that try to reach a specific\ngoal by measuring the difference between the input and the desired value, and then returning a new\ndesired input.\n\nA common example is a car's cruise control, which would give a PID the current speed\nand the desired speed, and the PID controller would return the desired throttle input to reach the\ndesired speed.\n\nOriginal code based upon the [Arduino PID Library](https://github.com/br3ttb/Arduino-PID-Library).",
    "source": {
        "line": 17,
        "path": "src/pid/src/Shared/PID.lua"
    }
}