Skip to content

Commit

Permalink
Move existing documentation from wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
RobinsonZ committed Dec 7, 2018
1 parent b816e61 commit 053bd12
Show file tree
Hide file tree
Showing 2 changed files with 139 additions and 0 deletions.
44 changes: 44 additions & 0 deletions docs/Preference Manager.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Preference System

The Preference system, located in the `org.team1540.base.preferencemanager` package, allows persistent and non-persistent robot preferences (PID coefficients, setpoints, and other such values) to be accessed with ease.

## Example

```java
import edu.wpi.first.wpilibj.IterativeRobot;
import edu.wpi.first.wpilibj.command.Scheduler;
import org.team1540.base.preferencemanager.Preference;
import org.team1540.base.preferencemanager.PreferenceManager;

public class Robot extends IterativeRobot {
@Preference("A boolean")
public boolean b;
@Preference("A String")
public String string = "String";
@Preference("A double")
public double d = 2;
@Preference("An int")
public int i = 2;

@Preference(value = "Non-Persistent int", persistent = false)
public int velocity = 1;

@Override
public void robotInit() {
PreferenceManager.getInstance().add(this);
}

@Override
public void robotPeriodic() {
Scheduler.getInstance().run();
}
}
```

This outlines how to use the basic functionality of the manager. Variables annotated with [`@Preference`](https://flamingchickens1540.github.io/ROOSTER/index.html?org/team1540/base/triggers/SimpleButton.html) will be constantly (every time `Scheduler.getInstance().run()` is called) set with the latest values from the driver station. The label on the driver station will be the label provided as an argument to the annotation. The value of these variables will be saved to disk and restored on robot reboot. However, if you don't want that to happen, specify `persistent = false` in the annotation (due to Java rules you'll also need to add the `value = ` section as seen above).

Preference fields must be `public`, can be static or non-static, and must be of type `boolean`, `String`, `double`, or `int`.

For fields marked with `@Preference` in a class to be recognized, an instance of that class must be passed to the [`PreferenceManager`](https://flamingchickens1540.github.io/ROOSTER/index.html?org/team1540/base/triggers/SimpleButton.html) using `PreferenceManager.getInstance().add()`. For static fields, any instance will do; for non-static fields, the specific instance of the class must be passed to the manager. If multiple instances of the same class are added to the `PreferenceManager`, due to labeling limitations, all tunable fields will contain the same values.

Just because variable values are updated doesn't mean that they're updated at the places they're used. For example, when Talon SRX/Victor SPX PID coefficients are updated, they must be re-set. 
95 changes: 95 additions & 0 deletions docs/Simple Utilities.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Simple Utilities

The Simple Utilities, located in the `util` and `triggers` packages, make developing robot code easier and more ergonomic by using [lambdas](https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html) to create WPILib components (`Commands`, `Buttons`, etc.) without having to create an entire anonymous class.

## SimpleButton

[`SimpleButton`](https://flamingchickens1540.github.io/ROOSTER/index.html?org/team1540/base/triggers/SimpleButton.html) is a way to create a WPILIb `Button` class based off of an arbitrary function returning a `boolean` in one line of code. This is useful if you want to set up complex control schemes; for example, having a button that is only considered pressed if a joystick is in a certain range.

### Examples

Method reference:

```java
Button fooButton = new SimpleButton(this::getFoo);
```

Simple statement lambda:

```java
Button fooAndBarButton = new SimpleButton(() -> getFoo() && getBar());
```

More complicated logic:

```java
Button atLeast5TrueButton = new SimpleButton(() -> {
int numTrue = 0;
for (boolean b : aListOfBooleans) {
if (b) {
numTrue++;
}
}
return numTrue >= 5;
});
```

## SimpleCommand/SimpleLoopCommand

[`SimpleCommand`](https://flamingchickens1540.github.io/ROOSTER/org/team1540/base/util/SimpleCommand.html) and [`SimpleLoopCommand`](https://flamingchickens1540.github.io/ROOSTER/org/team1540/base/util/SimpleLoopCommand.html) are wrappers that allow the creation of WPILib `Commands` that run an arbitrary function when executed. `SimpleCommand` runs the provided code once before finishing, while `SimpleLoopCommand` will run until canceled or interrupted. Both types can have requirements just like normal commands.

Note that the constructor for `SimpleCommand` requires a name; this is so that the command has a sensible name that is preserved across different program runs (as otherwise the names could be different depending on what order something is initialized statically).

`SimpleCommand` in particular is very useful for putting buttons to do things on the SmartDashboard or Shuffleboard. Simply create the command and put it up using `SmartDashboard.putData()`.

### Examples

Hello world:

```java
Command printHello = new SimpleCommand("Print hello", () -> System.out.println("Hello world!"));
```

Command with requirements:

```java
Command openClaw = new SimpleCommand("Open claw", Robot.claw::open, Robot.claw);
```

Command with multiple requirements:

```java
Command openClawAndRaiseArm = new SimpleCommand("Open Claw and Raise Arm",
() -> {
Robot.claw.open();
Robot.arm.raise();
},
Robot.claw, Robot.arm);
```

Looping command:

```java
Command printTime = new SimpleLoopCommand("Print Current Time", () -> System.out.println(System.currentTimeMillis()));
```

## SimpleConditionalCommand

[`SimpleConditionalCommand`](https://flamingchickens1540.github.io/ROOSTER/org/team1540/base/util/SimpleConditionalCommand.html) is a wrapper that allows the creation of WPILib `ConditionalCommand` instances based off of an arbitrary function returning a `boolean` in one line of code. `SimpleConditionalCommands`, like `ConditionalCommands`, can run a `Command` only if the provided condition is `true`, or run one of two commands depending on the condition.

### Examples

Run a command only if `getFoo()` returns `true`:

```java
Command doSomethingIfFoo = new SimpleConditionalCommand(this::getFoo, new DoSomething());
```

Run the `DoSomething` command if `getFoo()` returns `true`, otherwise run `DoSomethingElse`:

```java
Command somethingOrSomethingElse = new SimpleConditionalCommand(this::getFoo,
new DoSomething(),
new DoSomethingElse());
```

0 comments on commit 053bd12

Please sign in to comment.