Controls Variable/Telemetry Names RFC

[guyfleeman]

Non urgent item, just want a place to capture thoughts.

We've had a lot of discussion about variable names w.r.t. control systems. I preliminarily suggest we standardize on the terminology used on the wiki for PID.

PID Naming:

• desired steady-state output, called setpoint or Process Variable (PV) - r(t) - setpoint OR process_variable
• calculated error - e(t) - error
• value commanded to subsystem after incorporating error (e.g. what we are able to set), called Control Variable (CV) - u(t) - control_variable
• measured system state, called the Measured Process Variable (measured PV) - y(t) - measured_process_variable

Will's suggested naming for any given feedback control system:

r(t) - setpoint
e(t) - error
u(t) - control_variable
y(t) - measured_process_variable
y(t) - estimated_process_variable (when coming from an estimator)

Filtering and Clamping:

• if the value is filtered, append the suffix _filtered
• if the value is clamped, append the suffix _clamped

Subsystem Naming:
To the extend possible control systems and debug telemetry should be encapsulated in whatever abstraction the language permits (e.g. struct, class, etc). The abstraction should be named <subsystem>_controller or more specifically <subsystem>_pid_controller. Controller names should not be duplicated in internal variables.

Example Motor Controller:

telemetry.motor_front_left_pid_controller.setpoint
telemetry.motor_front_left_pid_controller.error
telemetry.motor_front_left_pid_controller.control_variable
telemetry.motor_front_left_pid_controller.measured_process_variable

telemetry.body_velocity_controller.setpoint
telemetry.body_velocity_controller.setpoint_clamped
telemetry.body_velocity_controller.error
telemetry.body_velocity_controller.control_variable
telemetry.body_velocity_controller.control_variable_clamped
telemetry.body_velocity_controller.estimated_process_variable

RFC so obv open for comments and discussion