From 52e33e2370a2aec63e7b3838c7bb3ab1197c043e Mon Sep 17 00:00:00 2001 From: Youwen Wu Date: Sun, 10 Mar 2024 00:36:19 -0800 Subject: [PATCH] docs(readme): overhauled description and installation steps --- README.md | 117 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 94 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 8f78891..162e170 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,106 @@ # Jankboard 2 [![maintainability status](https://api.codeclimate.com/v1/badges/4bedd567dbf60ec87164/maintainability)](https://codeclimate.com/repos/65dfbdc904f9ed00bbf381c8/maintainability) +![build](https://github.com/Team-1280/Jankboard-2/actions/workflows/main.yml/badge.svg) +![build all platforms](https://github.com/Team-1280/Jankboard-2/actions/workflows/publish-all.yml/badge.svg) -A remastered version of the original Jankboard, with a focus on minimizing the Jank portion. Designed from the ground up to be easy to maintain and extend, unlike the original. -The frontend is powered by Svelte 4 (unfortunately, we had to drop support for the bleeding edge Svelte 5 due to lack of Vite support). -This project is closed source (for now) and licensed under a modified BSD 3.0 license. +Team 1280's custom, powerful, and opinionated dashboard for controlling FRC +Robots, built with [Svelte](https://svelte.dev/) and +[TypeScript](https://www.typescriptlang.org/), and powered by +[Rust (Tauri)](https://tauri.app/). + +Unlike Shuffleboard, which attempts to provide an unopinionated "blank slate" +with an easy to configure and modular environment for displaying robot data, +Jankboard 2 is purpose built for Team 1280's Swerve drivebase robots and their +needs. It's tightly integrated with our proprietary robot features, like +collision warning and detection, and displays robot drive modes. + +The UI is reminiscient of and inspired by dashboards designed by car +manufacturers, making it easy for the driver to get the information they need at +a glance, without squinting at Shuffleboard's tiny and ugly UIs. It even +includes a full 3D robot visualization, synced directly with the robot's +movements in real life. + +Even though the dashboard's layout and design are highly opinionated and not +meant to be heavily modular, features can still be easily extended via a drop-in +app system which supports easy drop-in app integration. Jankboard 2 ships with a +few apps by default, featuring a camera feed, robot settings configurator, and +even a music player and games. ## Installation guide -We recommend installing the latest stable release binaries from [our release page](https://github.com/Team-1280/Jankboard-2/releases/), if you're just looking to run the Jankboard. Alternatively, if you can't find release binaries for your system, -follow the directions below in the **For developers** section to build it from source. +We recommend installing the latest stable release binaries from +[our release page](https://github.com/Team-1280/Jankboard-2/releases/), if +you're just looking to run the Jankboard. Alternatively, if you can't find +release binaries for your system, follow the directions below in the +[For developers](#for-developers) section to build it from source. We will +periodically update the releases with new builds when we come out with stable +versions, and we follow [semantic versioning](https://semver.org/). + +## A brief footnote on the name "Jankboard 2" + +The name "Jankboard" comes from Team 1280's original attempt at creating a +custom dashboard. Though it looked and functioned superficially similar to +Jankboard 2, it was not designed with maintainability in mind and became +exceptionally difficult to extend and develop as the codebase became bloated. +Jankboard 2 is a version redesigned from the ground up with the goal of easy +maintainability and richer features. It contains both a completely rewritten +frontend and backend, which have been improved in almost every possible way. You +can view the original version at +[its archived repository.](https://github.com/Team-1280/Jankboard-Super-Jank/tree/f42715f5ae1897e95ef15103b16ba6e764d2c0be) ## For developers -If you would like to contribute to Jankboard 2, there's only a few simple steps to get the development build up and running. +If you would like to contribute to Jankboard 2, there's only a few simple steps +to get the development build up and running. ### Prerequisites -- Rust and `cargo`. Check the [Rust docs](https://www.rust-lang.org/learn) for more information. We recommend you install Rust using `rustup`. Keep in mind that this is ONLY necessary for development, release binaries do not require Rust. -- NodeJS and `npm`, for installing dependencies and the `vite` development server. -- If you would like the install the (deprecated) Python backend, you will need to install the `poetry` package manager. +- Rust and `cargo`. Check the [Rust docs](https://www.rust-lang.org/learn) for + more information. We recommend you install Rust using `rustup`. Keep in mind + that this is ONLY necessary for development, release binaries do not require + Rust. +- `pnpm`, for installing dependencies and the `vite` development server. +- Ideally, NodeJS, but it's technically not required as `pnpm` brings its own + node binary. ### Installation steps -1. Clone the repository. The `app` folder contains most of the (deprecated) Python code that powers the telemetry. The `client` folder contains the code for the desktop app. The `client/src-tauri` contains the Rust source code for the backend that interfaces with the robot via Network Tables. The python backend in `app` is currently being deprecated in favor of a Rust backend. If you need to run it for any reason, check the section below (**Troubleshooting common issues**). -2. `cd` into the `client` folder. The configuration files and `package.json`, as well as project code for the desktop app are all stored here. To install dependencies, simply run `npm i`. -3. To run the desktop app in developer mode (with automatic hot stateful reload and other useful features like error reporting), make sure you're in the `client` directory and run `npm run tauri dev`. This will install and build the Rust dependencies via `cargo` and initialize the `vite` development server for the frontend. Note that since this is basically just running the `vite` development server and then connecting the Tauri webview to it, there may be slightly inconsistent behavior in dev mode versus production mode. -4. To create a production binary, run `npm run tauri build`. Tauri cross-compilation is still in beta, so you should generally try to build targeting the same OS you're currently running. Check [the Tauri docs](https://tauri.app/v1/guides/building/) for more information. +1. Clone the repository. The `client` folder contains the vast majority of the + source code for the desktop app. +2. `cd` into the `client` folder. The configuration files and `package.json`, + This is where stuff like `package.json` and configuration files for our + various tooling are housed. The `client/src-tauri` directory contains the + Rust source code and `cargo` configuration files for the backend that + interfaces with the robot via Network Tables. +3. Run `pnpm install` to install dependencies. +4. To run the desktop app in developer mode (with automatic hot stateful reload + and other useful features like error reporting), make sure you're in the + `client` directory and run `pnpm run tauri dev`. This will install and build + the Rust dependencies via `cargo` and initialize the `vite` development + server for the frontend. Note that since this is basically just running the + `vite` development server and then connecting the Tauri webview to it, there + may be slightly inconsistent behavior in dev mode versus production mode. +5. To create a production binary, run `npm run tauri build`. Tauri + cross-compilation is still in beta, so you should generally try to build + targeting the same OS you're currently running. Check + [the Tauri docs](https://tauri.app/v1/guides/building/) for more information. + We also have some Github Actions set up to automatically compile a production + build for all platforms, but this is expensive (uses over 30 minutes of our + quota), and should only be used for publishing new major releases. ## Troubleshooting common issues -- If you're experiencing issues with TypeScript type checking or dependency resolution, try opening your editor directly in the `client` directory so it picks up the `tsconfig.json` and uses the project's own TypeScript language server. -- If you don't have access to a development environment that supports running standalone executables (eg. Github Codespaces), you can try running `npm run dev` instead of `npm run tauri dev`, which will open a development server at `localhost:5173` with the frontend running in the web. However, app behavior may be inconsistent and you will not get any features from the Rust backend. -- If for some reason you need to install and use the Python backend, run `poetry install --no-root` in the root directory of the project to install dependencies. You can start the server with `poetry run flask --app app/server.py run --host localhost --port 1280` (it must be running at port `1280` for the frontend to detect it), and it only works when the frontend is running in development mode. +- If you're experiencing issues with TypeScript type checking or dependency + resolution, try opening your editor directly in the `client` directory so it + picks up the `tsconfig.json` and uses the project's own TypeScript language + server. +- If you don't have access to a development environment that supports running + standalone executables (eg. Github Codespaces), you can try running + `npm run dev` instead of `npm run tauri dev`, which will open a development + server at `localhost:5173` with the frontend running in the web. However, app + behavior may be inconsistent and you will not get any features from the Rust + backend. ## Current progress and improvements over (original) Jankboard @@ -40,17 +108,20 @@ If you would like to contribute to Jankboard 2, there's only a few simple steps - Toast and audio cue system is much more robust - Transitions added almost everywhere to make things smoother - Tauri app created successfully, currently still using Flask backend -- Visualization vastly improved with Threlte (Three.js) powered 3D robot simulation -- Robot model ported successfully via massive optimization through polygon decimation -- Added settings app with options to disable certain features and developer tools for testing +- Visualization vastly improved with Threlte (Three.js) powered 3D robot + simulation +- Robot model ported successfully via massive optimization through polygon + decimation +- Added settings app with options to disable certain features and developer + tools for testing +- Created dynamic voice prompt system to support new languages very easily +- Overhaul backend in Rust +- Overhaul visualization (especially camera) +- Added Vlad's voice lines (AT LAST) ## TODO - Camera cutout overlay - Overhaul audio player system -- Overhaul visualization (especially camera) -- Overhaul backend in Rust - Further integrate telemetry (like GPWS, collision warning, etc) - Finish re-creating / adding various voice alerts and sequences -- Create dynamic voice prompt system to support new languages very easily -- Add dynamic voice prompt fallback to support incremental voice prompt migration