Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
18f6d65
add docs workflow
Dec 29, 2023
6892a37
add mkdocs supporting files
Dec 29, 2023
5d57ecd
change
Dec 29, 2023
e9d4c9f
add other docs
Dec 29, 2023
4009d7d
add basic styling
Dec 29, 2023
eb9126b
remove build artifact
Dec 29, 2023
93a3243
fix docs yaml
Dec 29, 2023
1b9f26e
update references
Dec 29, 2023
977bfc8
update repo-url
Dec 29, 2023
5758fdc
convert links to relative
Dec 29, 2023
d6ee566
[Editing Paths] convert images
Dec 29, 2023
c17f8fe
add icon and favicons
Dec 29, 2023
feb1836
add header
Dec 29, 2023
eb919a9
format
Jan 2, 2024
f1bc3aa
list md extension
Jan 2, 2024
bb36b2b
add md in html extension
Jan 2, 2024
c829550
add logo
Jan 2, 2024
12f41e8
docs UI formatting
Jan 2, 2024
3c252f0
add more mkdocs extensions
Jan 2, 2024
bab93dd
broke up installation and robot config
Jan 2, 2024
ee4bbd4
add operating system table
Jan 2, 2024
75ef6d1
home refresh
Jan 2, 2024
b4a7dd2
update repo name to include sleipnirgroup
Jan 2, 2024
c2e3ca8
update license
Jan 2, 2024
73b350b
format for ci
Jan 2, 2024
2682f2e
indent further for robot config
Jan 2, 2024
135fa61
format
Jan 2, 2024
f171077
add docs to prettier ignore
Jan 2, 2024
3d6b78e
change to exclude all .md files
Jan 2, 2024
5cc9f65
append docs to pretty ignore
Jan 2, 2024
03a48ce
add contributing section
Jan 2, 2024
ad3e72f
basic contributing guide
Jan 2, 2024
1a5cdac
installation.md
Jan 2, 2024
c1949df
change windows arm64 building to ?
Jan 2, 2024
b974cd1
update accuracy card
Jan 2, 2024
fd62b61
[Editing Paths] Obstacles
Jan 2, 2024
79d0932
add pathplanner integration card commented out
Jan 2, 2024
e31a7cd
comment out pathplanner integration
Jan 2, 2024
1720513
charge field to station, clarify year + comp name
Jan 2, 2024
2e200df
clarify operating systems it runs on
Jan 2, 2024
195cdec
[Usage/Editing Paths] more accurate opening sentence
Jan 2, 2024
ba1e718
update generating path gif
Jan 2, 2024
a169acf
update saving
Jan 2, 2024
fdbd80b
cross platform card grammar
Jan 2, 2024
66480f5
add links to cards
Jan 3, 2024
31e2eda
graphical interface grammar
Jan 3, 2024
646f2b1
choreo pronunciation update
Jan 3, 2024
7d16743
MOI grammar
Jan 3, 2024
c5a9dde
clarify system identification methods
Jan 3, 2024
fc7263e
more grammar
Jan 3, 2024
60acae9
controls+shortcuts grammar
Jan 3, 2024
de7d052
mathematically optimal grammar
Jan 3, 2024
9d07d02
π formatting
Jan 3, 2024
7e679f0
translation waypoint grammar
Jan 3, 2024
26a9c6a
pose waypoint 'and' bold
Jan 3, 2024
6392219
article gramamr
Jan 3, 2024
8263e5b
parenthesis empty waypoint grammar
Jan 3, 2024
81bae1c
segment scope intuitively grammar
Jan 3, 2024
d562aa4
obstacles description grammar
Jan 3, 2024
4eba47a
circle obstacle instructions
Jan 3, 2024
a50931c
generating grammar
Jan 3, 2024
7280090
hamburger location clarification
Jan 3, 2024
543d91b
clarify sidebar location
Jan 3, 2024
41be6f8
export trajectory more readable
Jan 3, 2024
8d1a081
project details sentence grammar
Jan 3, 2024
b804575
rest of saving.md grammar
Jan 3, 2024
e3acaef
admonitions on robot-config
Jan 3, 2024
d143b6f
robot config admonitions
Jan 3, 2024
3b0e6e7
add admonition on editing paths
Jan 3, 2024
50920f2
refactor to document settings
Jan 5, 2024
d24cabf
move other links to document-settings
Jan 5, 2024
571ad76
document settings - robot config
Jan 5, 2024
396f97e
add motors data source
Jan 5, 2024
368ded1
project not saved image and saving minor changes
Jan 6, 2024
ec88d25
merge
Jan 6, 2024
9e9a02f
Merge branch 'main' into main
Jan 6, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Docs
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v3
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
3 changes: 3 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
.vscode/
*.md
dist/
public/
choreolib/
src-tauri/target/
docs/

.clang-format
.clang-tidy
18 changes: 18 additions & 0 deletions docs/choreolib/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
Install ChoreoLib to your robot project by copy pasting the following link into the vendor library installation dialog:

```
https://sleipnirgroup.github.io/ChoreoLib/dep/ChoreoLib.json
```

The installation method is the same as CTRE, PathPlanner, and more. Read more on Vendor Dependencies and their installation (VSCode —> install new library (online)) [here](https://docs.wpilib.org/en/stable/docs/software/vscode-overview/3rd-party-libraries.html#installing-libraries).

## Building Manually

If you attempt to work with this project in VSCode with WPILib plugins, it will ask you if you want to import the project. Click no. This will change the project into a robot code project and break everything.

The maven artifacts can be built using `./gradlew publish` or `./gradlew publishToMavenLocal` for local library access.

The built library will be located in the respective operating system's m2 folder. By default, Maven local repository is defaulted to ${user.home}/.m2/repository folder:

- Unix/Mac OS X - `~/.m2/repository`
- Windows – `C:\Users\{your-username}\.m2\repository`
29 changes: 29 additions & 0 deletions docs/choreolib/usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
``` { .java .select }
import com.choreo.lib.*;

ChoreoTrajectory traj = Choreo.getTrajectory("Trajectory"); // (1)

// (2)
Choreo.choreoSwerveCommand(
traj, // (3)
this::getPose // (4)
new PIDController(Constants.AutoConstants.kPXController, 0.0, 0.0), // (5)
new PIDController(Constants.AutoConstants.kPXController, 0.0, 0.0), // (6)
new PIDController(Constants.AutoConstants.kPThetaController, 0.0, 0.0), // (7)
(ChassisSpeeds speeds) -> // (8)
this.drive(new Translation2d(speeds.vxMetersPerSecond, speeds.vyMetersPerSecond), ...),
true, // (9)
this, // (10)
);
```

1. Do not include .traj extension when referencing the file name. this file should be in: "{deployDirectory}/choreo/".
2. Create a swerve command for the robot to follow the trajectory.
3. Choreo trajectory from above.
4. A function that returns the current field-relative pose of the robot: your wheel or vision odometry.
5. PIDController for field-relative X translation (input: X error in meters, output: m/s).
6. PIDController for field-relative Y translation (input: Y error in meters, output: m/s).
7. PID constants to correct for rotation error.
8. A function that consumes the target robot-relative chassis speeds and commands them to the robot.
9. Whether or not to mirror the path based on alliance (this assumes the path is created for the blue alliance).
10. The subsystem(s) to require, typically your drive subsystem (this).
114 changes: 114 additions & 0 deletions docs/contributing/building-choreo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
### Development System Dependencies

Requirements for **all** platforms:

- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
- [Rust](https://www.rust-lang.org/tools/install)
- [CMake](https://cmake.org/download)
- [clang](https://releases.llvm.org/download.html)

### Windows

Choreo can be built and run on Windows, but it requires a few extra steps because CasADi requires the MinGW toolchain.

#### Windows Environment

Buliding on Windows requires [MinGW](https://github.com/niXman/mingw-builds-binaries/releases/). On the release page, download the binary labeled `x86_64`, `posix`, and `msvcrt`. Extract the `mingw64` folder to `C:\mingw64`. Add an entry to the user or system `PATH` environment variable that points to `C:\mingw64\bin`.

After installing MinGW, run `rustup default stable-gnu` to switch to the GNU toolchain that uses MinGW. This can be reverted using `rustup default stable-msvc` when returning to other rust projects.

Run `npm install` to build Node.js dependencies and TrajoptLib. Once it is finished, the libraries will be copied into `src-tauri/*.dll`. You will need to redo this step if Choreo begins using a different version of TrajoptLib.

#### Windows Dev Server

Run `npm run tauri dev -- --release` to start the dev server.

The `--release` avoids issue [#84](https://github.com/SleipnirGroup/Choreo/issues/84).

If you're having a permissions error with CMake, try first building using the `cargo` command directly:

```console
cd src-tauri
cargo build --release
```

Then try `npm run tauri dev -- --release` again.

#### Windows Bundle

To create an NSIS `.exe` installer bundle, run `npm run tauri build`. It will report the location of the bundle upon completion.

### macOS

The following steps can be used to build for arm64 or x86_64 architectures.

#### macOS Environment

Make sure Xcode command line tools are installed:

```console
xcode-select --install
```

Run `npm install` to build Node.js dependencies and TrajoptLib. Once it is finished, the libraries will be copied into `src-tauri/lib*.dylib`. You will need to redo this step if Choreo begins using a different version of TrajoptLib.

#### macOS Cross Compilation

An `arm64` or `x86_64` Mac can be used to build for `arm64` or `x86_64` targets. The target architecture will be the currently selected Rust target triple.

You can create a `config.toml` file in `src-tauri/.cargo` containing the following definition to change the target from the native architecture to the other:

```toml
[build]
target = "aarch64-apple-darwin" # arm64 (Apple Silicon) target
```

or,

```toml
[build]
target = "x86_64-apple-darwin" # x86_64 (Intel) target
```

You must first install the Rust targets using `rustup target install <target>`.

#### macOS Dev Server

Run `npm run tauri dev` to start the dev server.

#### macOS Bundle

To create a `.dmg` macOS bundle, run `npm run tauri build`. It will report the location of the bundle upon completion.

### Linux

The following steps can be used for Ubuntu Linux; others may require additional configuration. If you find any additional required steps for your distro, please create a PR or issue to add documentation for it.

#### Linux Environment

Tauri requires some libraries to function, follow their [instructions](https://tauri.app/v1/guides/getting-started/prerequisites/#setting-up-linux).

Run `npm install` to build Node.js dependencies and TrajoptLib. Once it is finished, the libraries will be copied into `src-tauri/lib*.so*`. You will need to redo this step if Choreo begins using a different version of TrajoptLib.

#### Linux Dev Server

Due to issue [#89](https://github.com/SleipnirGroup/Choreo/issues/89), you must manually copy all files matching `src-tauri/lib*.so*` into `src-tauri/target/debug/` to ensure they can be found for the next step.

Run `npm run tauri dev` to start the dev server.

#### Linux Bundle

To create a `.deb` Debian/Ubuntu bundle, run `npm run tauri build`. It will report the location of the bundle upon completion.

## Tech stack

- 📈 [CasADi](https://github.com/casadi/casadi): Numerical optimizer
- 🖥️ [Tauri](https://tauri.app/): Desktop applications
- ⚛️ [React](https://react.dev/): JS Framework
- 🚗 [TrajoptLib](https://github.com/SleipnirGroup/TrajoptLib): Uses CasADi to generate paths
- 🦀 [Rust](https://www.rust-lang.org/): Backend code
- ⚡️ [Vite](https://vitejs.dev/)

## Tauri Recommended IDE Setup

- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
51 changes: 51 additions & 0 deletions docs/contributing/contributing-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Contributing Guide

Thank you for your interest in contributing to this project! We appreciate your help in making it better.

## Table of Contents
- [Introduction](#introduction)
- [Submitting Issues](#submitting-issues)
- [Pull Requests](#pull-requests)
- [Code Style](#code-style)
- [License](#license)

## Introduction

This document outlines the guidelines for contributing to this project. It covers submitting issues, creating pull requests, and maintaining code quality.

## Submitting Issues

If you encounter any issues or have suggestions for improvements, please follow these guidelines when submitting an issue:

1. Before submitting an issue, search the issue tracker to check if the issue has already been reported.
2. Provide a clear and descriptive title for the issue.
3. Include detailed steps to reproduce the issue.
4. Include any relevant error messages or screenshots.
5. Specify the version of the project you are using.
6. Be respectful and constructive in your communication.

## Pull Requests

We welcome contributions in the form of pull requests. To submit a pull request, please follow these guidelines:

1. Fork the repository and create a new branch for your feature or bug fix.
2. Ensure your code follows the project's code style guidelines (see [Code Style](#code-style)).
3. Write clear and concise commit messages.
4. Include tests for your changes, if applicable.
5. Document any new features or changes in the project's documentation.
6. Submit the pull request and provide a detailed description of the changes made.

## Code Style

To maintain a consistent codebase, we follow a set of code style guidelines. Please ensure that your code adheres to these guidelines before submitting a pull request. Some general guidelines include:

- Use meaningful variable and function names.
- Write clear and concise comments.
- Follow the project's indentation and formatting conventions.
- Keep lines of code within a reasonable length.
- Remove any unnecessary code or comments.
- Make sure to run `npm run fixFormat` before comitting!

## License

This project is licensed under the BSD-3-Clause License. By contributing to this project, you agree to license your contributions under the same license.
91 changes: 91 additions & 0 deletions docs/document-settings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
## Start by downloading Choreo from **[Releases](https://github.com/SleipnirGroup/Choreo/releases)**

## Robot Config

The trajectory optimizer depends upon the following user-specified parameters, which are entered in the Robot Configuration panel. This helps the optimizer understand the robot's projected path very accurately.

Access the robot-config by accessing the drawer via hamburger icon on top left of screen, then clicking "Document Settings"

![Document Settings](./media/document-settings.png)

### Dimensions

- **Mass** [kg]: The mass of the robot with battery and bumpers
- **MoI** [kg * m<sup>2</sup>]: The resistance to change in rotational velocity in response to a torque applied to the robot about the vertical axis
- **Max Velocity** [m/s]: The maximum tangential speed of the wheel

!!! tip "How to measure Max Velocity"

A reasonable choice of Max Velocity is that corresponding to ~80% of free speed experienced at the drive motor(s).

- **Max Torque** [N * m]: The maximum torque applied at the wheel

!!! tip "How to measure Max Torque"

A reasonable choice of Max Torque is that corresponding to a current draw of approximately `1.5 * BreakerValue` experienced at the drive motor(s).

- **Wheelbase and Trackwidth** [m]: The largest distances between the robot's wheel centers
- **Length and Width** [m]: The overall size of the robot's _bumper_.

!!! tip "Saving Robot Config"
Saving a copy of the robotConfig somewhere safe, like the root of a robot project, is highly recommended. This is so you can correlate that robot project to your robot's specifications, and thus your paths.

!!! tip "Undo + Redo"
Undo and Redo shortcuts work for all of these values.

### Measuring Moment of Inertia (MoI)

The robot's rotational inertia has a significant impact on how quickly it can follow complex paths. For the best results, it is recommended to get as accurate an estimate of this parameter as possible. This can be accomplished via:

- Faithful CAD loaded with mass properties
- Physical experimentation
- Other System Identification methods

If none of these techniques are possible, a reasonable estimate of MoI would be mass _ length _ width / 6 based on the assumption of a rectangle of uniformly-distributed mass.

!!! tip

Of course, more precision is always better. But after ~3 decimals, you will most likely get diminishing returns.

### Drive Motor

For presets to these values, jump to [Motor Calculator](#motor-calculator)


### Theoretical

Calculated robot metrics for reference and validation.

![robot-config-theoretical.png](./media/robot-config-theoretical.png)

- **Floor Speed** [m/s]: Linear Maximum speed when not rotating
- **Floor Accel** [m/s<sup>2</sup>]: Linear Maximum acceleration when not rotating
- **Ang Speed** [rad/s]: Maximum angular speed when spinning in place
- **Ang Accel** [rad/s<sup>2</sup>]: Maximum angular acceleration when spinning in place

### Motor Calculator

![robot-config-motor-calculator](./media/robot-config-motor-calculator.png)

Choose from the following motor presets and a current limit in Amps.

In addition to modifying the above [Drive Motor](#drive-motor) values, it shows:

- **Preview Max Speed** [RPM]: Estimated speed under load (~80% of free speed)
- **Preview Max Torque** [N • m]: Motor torque at the given current limit

Motors Supported:

- Falcon 500
- Falcon with FOC
- NEO
- NEO Vortex
- Kraken X60
- Kraken with FOC
- CIM

!!! warning

Make sure to press the APPLY button, or else your values will not save. Don't worry, you can always hit undo at any time to revert.

Free Speed and Torque are from [reca.lc/motors](https://reca.lc/motors)
Loading