Skip to content

Tutorials

Jump to bottom
Matteo Golin edited this page Oct 26, 2022 · 9 revisions

To contribute to the ground station UI project, please read these tutorials in order.

  1. Installing Development Dependencies
  2. Repository Setup
  3. Contributing Guidelines

If you are new to any of the languages, frameworks or libraries that this project uses, you can visit the resources section to find some documentation on how they work and guides on getting started with learning.

Installing Development Dependencies

This documentation will outline the base requirements you need to have in order to begin contributing.

Project Overview

The ground station UI uses HTML, CSS and React. React is a JavaScript framework that makes it simpler to divide parts of our HTML in components.

This allows us to re-use code snippets, and also bundles the HTML snippets with their CSS styles and JavaScript functionality. This way, each component is independent, and can be re-used multiple times anywhere in the UI.

Handy tutorials for HTML, CSS, JavaScript and React are linked in the resources section.

If you are already familiar with React, please note that this project uses functional components.

Dependencies

In order to contribute to this project, you will need to have a few dependencies installed.

Node.js

In order to be able to run the front-end, you will need to install Node.js to your machine. The installation guide can be found here, and you will just need to install the latest version for your operating system and follow the instructions that the installer displays when you run it.

Python

Install the latest version of Python for your operating system here, and similarly to Node.js, follow the installer's instructions.

Make sure that when you see the option Add Python to PATH with a checkbox, select it. Otherwise Python may cause you trouble.

Backend

The backend that will supply us with live testing data can be found here. You will need to clone the repository on your machine (anywhere is fine) using the command git clone <url> where the URL is the repository URL you will copy from the bright green code button.

This assumes you have Git installed already as per the previous meetings. If not, please Google how to install Git or ask a team member.

Backend Modules

The Python backend requires a few additional dependencies to run. These dependencies can be found here in the backend documentation.

For each of these dependencies, you will need to type pip install <module> into your terminal (the directory you are in does not matter, this installs globally). Replace <module> with the name of the module you are installing.

If you have trouble installing any modules, Google "how to install" and the name of your module.

Repository Setup

Now that everything is installed, you can set up the repository on your own machine so that you can start working on adding features.

Forking the Repository

The repository for the Ground Station UI can be found here.

To fork the repository and get it on your machine:

  1. Click the fork button the repository page and name your fork (keeping the same name is fine)
  2. Under the green code button, copy the repository URL for cloning.
  3. In your terminal, navigate to the directory (folder) where you want to store the repository
  4. Enter the command git clone <url>, where url is the URL you copied in step 2.
  5. Once the repository has been cloned, open the groud-station-ui folder in your code editor of choice (VSCode is recommended)
  6. Celebrate!

Connecting to the Original Repository

While working on your fork, you'll want to make sure your copy of the UI is up to date with the changes made to the original repository.

Adding the original repository:

  1. Open your forked repository's directory in the terminal.
  2. Enter the command git remote add upstream https://github.com/CarletonURocketry/ground-station-ui.git

Any time you want to pull the latest changes from the original repository, you can now do the following:

  1. Commit all your changes.
  2. Push your changes.
  3. Enter git fetch upstream.
  4. Enter git merge upstream/main main.

If there are any merge conflicts, you will have to resolve them yourself. It is recommended that you pull the latest changes from the original repository every time you return to working on your fork.

Running the UI

The React framework requires a lot of dependencies, called node modules. Because there are so many of these, they aren't included in the repository, or it would take forever to push and clone because so much data is being sent each time.

When you clone the repository for the first time, you will be missing these dependencies that are required to run the UI. This means you need to install them. Thankfully, package.json keeps track of everything that needs to be installed.

To install dependencies, follow these steps:

  1. Navigate to the ground-station-ui folder in your terminal
  2. Enter the command npm install
  3. Wait while all the dependencies are installed

Note: Even though you've installed the dependencies now, there may be more added libraries later. If you get an error about a missing dependency, just follow three steps above again.

Now the dependencies are installed, but you still need to run the UI. To do this, there is one easy step.

  1. Enter the command npm start in your terminal whilst in the ground-station-ui folder

You will see the UI begin at the URL localhost:3000 in your browser. It's pretty boring because it's not connected to the backend, but that's okay. Now you will connect to the backend.

Connecting to the Backend

Because the UI is supposed to run with real-time data, the backend needs to simulate that (because obviously the rocket isn't going to be launched every time we need to test the UI).

The UI connects to a websocket when you open it, so all you need to do is run the backend. For that, you will use the repository you cloned in the Installing Development Dependencies tutorial.

  1. In your terminal, navigate to the ground-station backend folder
  2. Enter the command py main.py
  3. When prompted for which port to use, enter test (newer versions don't require this step)

Now the backend is running and sending fake data. You may need to reload the UI in your browser to see this working. The UI should display connected in green at the top.

Final Note

You're now set up for development! Also note that our npm start command runs the UI in development mode. This means that it will refresh with your changes any time you edit a file in the ground-station-ui folder and save it.

Contributing Guidelines

Some instruction for contributing, as well as some tips on how to design your components.

What to do

Create an issue on the GitHub page and assign it to yourself.

For instance, if you want to add a pressure graph to the main dashboard, open an issue and title it Add Graph to Main Dash. Then you can assign the issue to yourself and begin working.

Try to create issues for yourself that don't interfere with other code as much as possible. For instance, a graph is an independent component. You would only need to edit the files you created for this component, and perhaps import into the Home page component to view it on the dashboard.

When you're done with your feature, make a pull request!

Standards

Some coding standards to ensure that all the code is compatible and consistent.

Components

  • Components will be made as functional components using React
  • All component files are to be named with the extension .jsx even though .js will work
  • All components are to be nested in the proper directory (pages in /pages, etc.)
  • Any CSS stylesheets for a component should share the same file name as it's .jsx file counterpart
    • Home.jsx will have CSS file called Home.css
  • Organize your imports in groups (components, utilities, hooks, etc.)

Hooks

  • Custom hooks should be given filenames ending with .js and be nested in the /hooks directory

Utils

  • All utility modules should be given filenames ending with .js and be nested in the /utils directory

CSS Styles

  • CSS stylesheets should use rem units for any sizing
    • This allows for easy resizing of components on different screen sizes without having to include many breakpoints (annoying CSS resizing function)
  • All colours should be pulled from the :root colour variables (found in global.css)
    • Do this using the var(--variable-name) syntax
    • Exceptions to this rule are colours that will be used very few times and cannot be substituted for a colour in the global.css file, such as the green used to colour in the board connection status

HTML

  • HTML tags should be descriptive.
    • Yes, a <div> tag would work to contain the main content of your page, but it is better practice to use the <main> tag
    • Descriptive class names, IDs and HTML tags should replace the need for comments

JavaScript

  • Use utility modules when possible
  • Document all functions and variables in utility modules
  • Use comments to make code more readable in confusing operations
  • Use descriptive variable and function names
  • Document all functions using JSDocs, and include your name as the author
Clone this wiki locally