Solar Car 1 Engineering Dashboard

Libraries

• node.js and npm - Package manager and server workhorse
• React - Front-end library
• Chakra UI - Component library
• Chart.js & react-chartjs-2 - Graph library & React wrapper
• XlsxWriter - Python module for writing Excel files
• NumPy - Python library for working with numerical data
• FastAPI - Python library for creating REST API endpoints
• Uvicorn - Python library for hosting web services
• Redis - High performance in memory database for storing our data

Contributing to the Dashboard

Installing WSL (Windows Users)

If you're using Windows, you will likely want to install Windows Subsystem for Linux (WSL) and use it for development. You can find in-house WSL setup instructions here.

Installing Dependencies

Before continuing, ensure that you have the following installed:

• node.js - Version 20.18.2 (LTS)
  • nvm is useful for managing node versions for multiple projects
• Python 3 - Version 3.10.*
• Poetry
• Docker Desktop
  • If using Linux, you can instead install only Docker Engine if you don't want the desktop application
• Redis Stack Server
  • If you want to run the server natively on Ubuntu 24.04, you may need to install with snap
  • If you have installation issues or do not want to install it on your system, you can instead run a Docker container as needed with docker run -d --name redis-stack-server -p 6379:6379 redis/redis-stack-server:latest. See here for more info

Cloning the Repository and Initializing the Submodules

0. If you don't already have an SSH key, generate a new SSH key (only the steps under "Generating a new SSH key" are required) and add it to your GitHub account.
1. Once you have an SSH key, clone this repository to your computer. Make sure to clone it using SSH (when you go to copy the clone link, there will be an SSH option above the link).
2. Next, cd into the chase-car-dashboard repository and run git submodule update --init.

Setting up Python Environment

We use Poetry for managing our backend Python environment. To setup a Poetry environment for this project, cd into Backend/ and run poetry install. When in the Backend/ directory, run Python commands using poetry run <command>. Those with Poetry 1.8 can alternatively run poetry shell to create a nested shell and run commands normally within it.

Updating Data

0. This step assumes that the repository has been initialized as above. Also, this assumes that the terminal that you are using to run the command natively allows git commands.
1. Run the command npm run update-data. This should take care of updating the submodule and JSON files in the frontend. If the command fails to run, make sure you have the most recent dependencies and version of npm installed onto your computer.

Development

0. Make sure that you have followed all steps in the sections above.
1. Open the repository in your IDE of choice (Visual Studio Code is recommended).
2. Run npm i to install the latest dependencies to your computer. You will also need to do this when you git pull to get the most recent changes of the code on your branch.
3. Run npm run update-data to update the sc1-data-format submodule and any associated JSON files (see the "Updating Data" section). You should also do this any time the submodule might have changed (i.e. whenever the data format has been modified).
   1. To avoid pushing changes that use obsolete data, update the submodule and data constants before you git push your changes. If there are changes to the data format, run the dashboard to make sure your code still works.
4. Ensure that the Redis server is running. You can follow the instructions for your system as listed in the installation guides above (see Installing Dependencies)
5. If you want to test the engineering dashboard with the solar car dashboard, do the following:
   1. Open up two separate terminals.
   2. In the first, cd into Backend and run the command poetry run python3 main.py.
   3. With the other terminal, cd into Frontend and run the command npm start.
6. If you want to test the engineering dashboard without the solar car dashboard, do the following:
   1. Open up a third terminal.
   2. cd into DataGenerator and run the command npm start.
7. Once you have finished making your necessary changes to your code, switch to a new branch that has a good name for the feature or names the Jira issue (e.g. SC2-123/skeleton).
8. Commit related changes to that branch and push to this repository. Do this often so that it is easy to finely revert to a previous state!
9. Once you are happy with the state of your code, open a pull request and request someone to conduct a code review. It may be kicked back with some suggestions or edits, but when it is accepted, it will be merged with main. Congrats! Now it's just time to rinse and repeat.

Running the Dashboard

Natively

1. Ensure that you have:
   • Installed WSL, if needed
   • Installed all necessary dependencies
   • Cloned the repository and setup the submodules
   • Set up a Python environment for the backend
2. Run npm i to install the latest dependencies to your computer
3. Run npm run update-data to update the constants (e.g. nominal min/max values for all data) related to each piece of data listed in the submodule. See the Updating Data section
4. In a terminal, cd into frontend and run npm start to start the React frontend, then move the process to background or open a new terminal. In the new terminal, cd into backend and run poetry run python3 main.py to start the backend server

Docker

This feature is not currently supported due to complications with inter-container communication

Note to software contributors: You do not need to follow this guide, docker is for deployment only.

1. Install Docker Desktop or Docker.
2. If you are not familiar with Docker, it is recommended to install Docker Desktop.
3. Once it is installed, start Docker Desktop. If Docker is not started, you will see a message saying Docker Daemon is Starting. Wait for this to complete.
4. Look for a script in this GitHub repo that matches your OS. If you're on Windows, that script is called windows-pull-run.bat, and for Linux and Mac it is called linux-pull-run.sh.
5. To download the script, open the script in GitHub and then click "Raw". The file will open in a tab. Then do Ctrl + S or Command + S, depending on your OS, and save it. This script will create a folder called recordedData in the same spot as your script, so keep that in mind when choosing where to download it. If operating on Windows make sure to remove the ".txt" when downloading and also download the powershell script in same folder. To run, look at the bullet points below:
   • (Windows) Navigate to the folder storing the script and double click on it.
   • (MacOS/Linux) cd into the directory storing the script, and then run these commands: chmod +x linux-pull-run.sh and ./linux-pull-run.sh.
   • NOTE: Certain run configurations require specific network interface setups. Run windows-pull-run.bat -h or ./linux-pull-run.sh -h, depending on your terminal environment, and see the desciption of the "config" option for more information about these setups.

Data Recording

Raw recorded data is saved in redis database, you can access the data manually with redis-cli or using redis-insight. However, the dashboard can be used to convert this raw database data to Excel format. You can do this by simply go press on the red record button on the dashboard and select the desired start and end time for your data, and click save, the dashboard should automatically save the data to your broswer download.

Troubleshooting

Killing the Backend After Errors

If you run the backend and encounter errors, even after killing the command, the process may still be running on your computer (seen on Linux), as the file sync feature spawns an independent Python process. To check if the process is still running, run ps -ef | grep main.py and look for matches before the last line (i.e. not ... --color=auto main.py). If there aren't any matches, you're peachy. Otherwise, to kill the process, run kill -9 <PIDs>, replacing <PIDs> with the first number in each matching line except for the last.