Skip to content

Commit

Permalink
Fix missing 2025 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
jwbonner committed Nov 16, 2024
1 parent b94cbe3 commit 18a0219
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 9 deletions.
8 changes: 5 additions & 3 deletions docs/docs/data-flow/supported-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,15 @@ Data is stored using string keys where slashes are used to denote subtables (sim

The following simple data types are currently supported:

`boolean, int, long, float, double, String, boolean[], int[], long[], float[], double[], String[], byte[]`
- Single values: `boolean, int, long, float, double, String`
- Arrays: `boolean[], int[], long[], float[], double[], String[], byte[]`
- 2D Arrays: `boolean[][], int[][], long[][], float[][], double[][], String[][], byte[][]`

### Structured

Many WPILib classes can be serialized to binary data using [structs](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/struct.adoc) or [protobufs](https://protobuf.dev). Supported classes include `Translation2d`, `Pose3d`, and `SwerveModuleState` with more coming soon. These classes can be logged as single values or arrays just like any simple type, and used as input or output fields.
Many WPILib classes can be serialized to binary data using [structs](https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/struct.adoc) or [protobufs](https://protobuf.dev). Supported classes include `Translation2d`, `Pose3d`, and `SwerveModuleState` with more coming soon. These classes can be logged as single values, arrays, or 2D arrays just like any simple type, and used as input or output fields.

AdvantageKit also supports logging the state of a `Mechanism2d` object as an output. For details, see [here](/recording-outputs/mechanism2d).
AdvantageKit also supports logging the state of a 2D mechanism object as an output. For details, see [here](/recording-outputs/mechanism2d).

### Units

Expand Down
45 changes: 41 additions & 4 deletions docs/docs/installation/version-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,16 +59,53 @@ The metadata values can be viewed using AdvantageScope's 🔍 [Metadata](https:/

## Event Deploy

Code often changes repeatedly during competition, which would normally mean running code with uncommitted change. This is a problem for log replay, since the version of code running in a particular match may be impossible to recreate afterwards. We have developed a VSCode extension to help with this issue by creating automatic commits to a temporary branch before every deploy.
Code often changes repeatedly during competition, which would normally mean running code with uncommitted change. This is a problem for log replay, since the version of code running in a particular match may be impossible to recreate afterwards.

This can be addressed by including a Gradle task to automatically commit working changes to a temporary branch before every deploy.

### Installation

To install the extension, search for "Event Deploy for WPILib" in the VSCode extensions window and click "Install". Alternatively, it can be installed it from the [online marketplace](https://marketplace.visualstudio.com/items?itemName=Mechanical-Advantage.event-deploy-wpilib) or by cloning the [GitHub repository](https://github.com/Mechanical-Advantage/EventDeployExtension) (instructions in the README).
The Gradle task is preconfigured in the AdvantageKit example projects. Add the following lines to `build.gradle`:

```groovy
// Create commit with working changes on event branches
task(eventDeploy) {
doLast {
if (project.gradle.startParameter.taskNames.any({ it.toLowerCase().contains("deploy") })) {
def branchPrefix = "event"
def branch = 'git branch --show-current'.execute().text.trim()
def commitMessage = "Update at '${new Date().toString()}'"
if (branch.startsWith(branchPrefix)) {
exec {
workingDir(projectDir)
executable 'git'
args 'add', '-A'
}
exec {
workingDir(projectDir)
executable 'git'
args 'commit', '-m', commitMessage
ignoreExitValue = true
}
println "Committed to branch: '$branch'"
println "Commit message: '$commitMessage'"
} else {
println "Not on an event branch, skipping commit"
}
} else {
println "Not running deploy task, skipping commit"
}
}
}
createVersionFile.dependsOn(eventDeploy)
```

### Usage

1. Before the event, create and check out a branch that starts with "event" such as "event_nhgrs". We recommend creating a new branch for each event.
2. When deploying, click "Deploy Robot Code (Event)" in the editor menu. This option appears directly under the normal "Deploy Robot Code" option from WPILib.
3. A commit is automatically created with all changes since the last commit, and a deploy is started normally. The name of the commit includes the current timestamp (e.g. "Update at "1/31/2022, 8:30:00 AM").
2. Deploy robot code through any method supported by WPILib.
3. A commit is automatically created with all changes since the last commit before the deploy begins. The name of the commit includes the current timestamp (e.g. "Update at "1/31/2022, 8:30:00 AM").
4. At the end of the event, the branch can be ["squashed and merged"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) back to a normal development branch, keeping the Git history clean.
5. When running log replay, find the commit hash in the log file metadata and run `git checkout` as described in the previous section. This will return to the exact version of code running on the robot (even if the commits were later squashed and merged). Since all of the changes were committed before each deploy, the simulated code is guaranteed to be identical to the original robot code.
8 changes: 6 additions & 2 deletions docs/docs/recording-outputs/mechanism2d.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,16 @@ sidebar_position: 2

# Mechanism2d

AdvantageKit can also log [`Mechanism2d`](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) objects as outputs, which can be viewed using AdvantageScope. If not using `@AutoLogOutput`, note that the logging call only records the current state of the `Mechanism2d` and so it must be called periodically.
AdvantageKit can also log 2D mechanism objects as outputs, which can be viewed using AdvantageScope. If not using `@AutoLogOutput`, note that the logging call only records the current state of the `Mechanism2d` and so it must be called periodically.

:::warning
Mechanism objects must use the **`LoggedMechanism2d`** class to be compatible with AdvantageKit. This class is otherwise equivalent to the standard `Mechanism2d` class. Equivalent `LoggedMechanismRoot2d`, `LoggedMechanismObject2d`, and `LoggedMechanismLigament2d` classes are also provided.
:::

```java
public class Example {
@AutoLogOutput // Auto logged as "Example/Mechanism"
private Mechanism2d mechanism = new Mechanism2d(3, 3);
private LoggedMechanism2d mechanism = new LoggedMechanism2d(3, 3);

public void periodic() {
// Alternative approach if not using @AutoLogOutput
Expand Down

0 comments on commit 18a0219

Please sign in to comment.