youwen5/jankboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(readme): overhauled description and installation steps

Browse source
This commit is contained in:
Youwen Wu 2024-03-10 00:36:19 -08:00
parent 41aaad9927
commit 52e33e2370
Signed by: youwen5
GPG key ID: 865658ED1FE61EC3
1 changed files with 94 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

117
README.md
View file

@ -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