SleipnirGroup · calcmogul · Jan 6, 2024 · Dec 29, 2023 · Dec 29, 2023 · Dec 29, 2023
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -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
diff --git a/.prettierignore b/.prettierignore
@@ -1,7 +1,10 @@
 .vscode/
+*.md
 dist/
 public/
 choreolib/
 src-tauri/target/
+docs/
+
 .clang-format
 .clang-tidy
diff --git a/docs/choreolib/installation.md b/docs/choreolib/installation.md
@@ -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`
diff --git a/docs/choreolib/usage.md b/docs/choreolib/usage.md
@@ -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).
diff --git a/docs/contributing/building-choreo.md b/docs/contributing/building-choreo.md
@@ -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)
diff --git a/docs/contributing/contributing-guide.md b/docs/contributing/contributing-guide.md
@@ -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.
diff --git a/docs/document-settings.md b/docs/document-settings.md
@@ -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)