org.usfirst.frc.team1736.lib.Calibration

Class Calibration

java.lang.Object

org.usfirst.frc.team1736.lib.Calibration.Calibration

public class Calibration
extends java.lang.Object

DESCRIPTION:
Single Calibration. Describes a piece of data which is usually constant, but can be overridden by a cal wrangler from a csv file on the RIO's filesystem. This enables a software team to control what a pit crew has control over (Shooter speed is a good candidate. Port number for left drivetrain motor A is a bad candidate).

USAGE:

1. Instantiate the calibration with a default value, and reference to the wrangler
2. At runtime, use the get() method to read the calibrated value. The returned value may change depending on what the wrangler has overwritten.

Field Summary

Fields

Modifier and Type	Field and Description
double	cur_val Present value for the calibration.
double	default_val Default value the calibration will take on.
double	max_cal Upper limit on the allowed calibration range
double	min_cal Lower limit on the allowed calibration range
java.lang.String	name Human-readable name for the calibration.
boolean	overridden True if the user has (somehow) made this calibration a non-default value

Constructor Summary

Constructors

Constructor and Description
Calibration(java.lang.String name_in, double default_val_in) Constructor for a new calibratable value.
Calibration(java.lang.String name_in, double default_val_in, double min_in, double max_in) Constructor for a new calibratable value with range limiting

Method Summary

Modifier and Type	Method and Description
void	acknowledgeValUpdate() For bookkeeping purposes, mark that the cal value update has been processed.
double	get() Retrieve the present value of this calibration.
double	getDefault() Get the default value of the calibration.
boolean	isChanged() Check if the calibration has been changed by the user.
void	reset() Returns the calibration back to the default value.
void	setOverride(double val_in) Set a new value to override the present calibration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

default_val

public final double default_val

Default value the calibration will take on.

name

public final java.lang.String name

Human-readable name for the calibration.

cur_val

public volatile double cur_val

Present value for the calibration. Starts at default_val, but might get changed

overridden

public volatile boolean overridden

True if the user has (somehow) made this calibration a non-default value

max_cal

public double max_cal

Upper limit on the allowed calibration range

min_cal

public double min_cal

Lower limit on the allowed calibration range

Constructor Detail

Calibration

public Calibration(java.lang.String name_in,
                   double default_val_in)

Constructor for a new calibratable value.

Parameters:

name_in - String for the name of the calibration. Best to make it the same of the variable name.

default_val_in - Default value for the calibration. Will keep this value unless the wrangler overwrites it.

Calibration

public Calibration(java.lang.String name_in,
                   double default_val_in,
                   double min_in,
                   double max_in)

Constructor for a new calibratable value with range limiting

Parameters:

name_in - String for the name of the calibration. Best to make it the same of the variable name.

default_val_in - Default value for the calibration. Will keep this value unless the wrangler overwrites it.

wrangler_in - Reference to the wrangler which will control this calibration.

min_in - Minimum allowable calibration value. If a user attempts to override the value outside this range, a WARNING: will be thrown and the calibrated value will be capped at the minimum.

max_in - Maximum allowable calibration value. If a user attempts to override the value outside this range, a WARNING: will be thrown and the calibrated value will be capped at the maximum.

Method Detail

get

public double get()

Retrieve the present value of this calibration. This is the method to use whenever the calibratable value is to be read.

Returns:

Present value of the calibration

isChanged

public boolean isChanged()

Check if the calibration has been changed by the user. Once the calibration has been changed, this method will continue to return true until the user calls the acknowledgeValUpdate() method.

The intent of this functionality is to allow software the ability to run special procedures if the value changes (ex: update and reset PID tune values). The acknowledgement makes sure any code that cares about cal value changes can always see when a new one occurs.

Note you never technically have to worry about this, for most cases. If you're reading the cal value every loop, you'll probably be ok. The bigger thing is when you need to not only read the cal value, but also start over some other piece of code or something like that.

As I was typing the above paragraph, I began to have flashbacks to my parallel processing classes in college, and just poked about 23472394732894 holes in my previous logic about "always seeing changes in cal values". There's lots of ways to break it, especially if the cal updater and the code that cares are in different theads. Ah well. The redeeming characteristic of this case is the cal values hopefully won't change too fast, because they're human entered. This should mean that we always see the cycle of change-process-acknowledge cleanly, but if we don't, well.... hmmm... let's just cross our fingers for now.

Isn't software fun?

Returns:

True if the calibration's value has changed at least once since the last acknowledgment, false if not.

acknowledgeValUpdate

public void acknowledgeValUpdate()

For bookkeeping purposes, mark that the cal value update has been processed. Not at all required to worry about, but can help with bookkeeping with code that must do something when cal values are changed.

getDefault

public double getDefault()

Get the default value of the calibration. Will not be overridden by wrangler. Do not use unless you're certain you don't wan't any updates the wrangler may apply to this calibration.

Returns:

Default value for the calibration

setOverride

public void setOverride(double val_in)

Set a new value to override the present calibration. Value will be limited to allowable min/max range for this calibration.

Parameters:

val_in - Value to set.

reset

public void reset()

Returns the calibration back to the default value.