Merge pull request #40 from TrickfireRobotics/adamc/documentation

added more detailed documentation

README.md

@@ -1,41 +1,18 @@
 # Mission Control
 
-The mission control is the human interface to communicate bidirectionally (Sends and receives information) with the rover. For example, sending joystick inputs to the rover or displaying the rover's camera feed in realtime. This is done through a websocket.
+The Mission Control Team designs and develops the application that serves as the operational hub for monitoring the rover's performance during competitions. This application enables the team to interpret real-time data, coordinate task execution, and ensure smooth communication between the rover and its operators, providing the tools necessary for seamless mission management.
 
 ![image](https://github.com/user-attachments/assets/a93314da-d956-468a-8d9c-59329f747919)
 
-## Design choices
+### `Getting Started`
 
-We are using Vue for its reactivity and lightweightness along side Pinia, a global state management to handle the growing amount of state shared among components. We use Typescript to make the code more readable and more maintainable. Because ROS uses the publisher and subscriber paradigm, we use Roslibjs library to easily interact with ROS in TypesScript, allowing us to use publishers, subscribers, and services. The websocket and the protocol is through Rosbridge Suite
+For an introduction on mission control, please refer to the [Getting Started Guide](./docs/getting_started.md).
 
-### Structure of Code:
+For a code-level overview, check out the [Code Overview](./docs/code_overview.md).
 
-- **components**: single file component vue files that contain logic and UI and styling. If the state does not need to be global, put it in the component. Pubs and Subs related to a component should be ran into them
-- **store**: Put all global states here
-  - Use Services for 1-time actions like turn-on-off the camera
-  - Use Sub/Pub when data is continuous like video feed
-- **App.vue**: Pubs and Subs that don't have a component should be ran here
-- **lib**: [Vue Composables](https://vuejs.org/guide/reusability/composables), and any large amount of .ts files goes here
-- **types.ts** Put all global types in here
+### Installation
 
-## Resources & Library Documentation:
-
-If unfamiliar with Vue and Typescript here are some resources:
-
-- [Official Vue Tutorial](https://vuejs.org/tutorial/#step-1)
-- [Typescript Documentation](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-oop.html) -
-- There is not a lot of documentation/tutorial on RosBridge and Roslib library but here is a collection of resources:
-  [RosBridge Protocol](https://github.com/RobotWebTools/rosbridge_suite/blob/ros1/ROSBRIDGE_PROTOCOL.md)
-- Overview: [https://foxglove.dev/images/blog/using-rosbridge-with-ros2/hero.webp](https://foxglove.dev/images/blog/using-rosbridge-with-ros2/hero.webp)
-- [Roslibjs source code]: https://github.com/RobotWebTools/roslibjs
-
-## Recommended IDE Setup
-
-- [VSCode](https://code.visualstudio.com/)
-
-- [Vue DevTools Chrome Extension](https://devtools.vuejs.org/getting-started/installation): Can Inspect Components State and integrated with Pinia, allowing to see store's state
-
-## Project Setup
+To develop code for the mission control, please follow the setup below:
 
 1. Install Node.js version 22.11.0 (LTS) (Long-term support Updated 11/6/2024)
    - **Windows and macOS**:
@@ -52,4 +29,4 @@ If unfamiliar with Vue and Typescript here are some resources:
 1. Run `npm run dev`
 2. While running open another VSCode window to the URC repo in the docker environment
    - Run `./build.sh` and `./launch.sh` commands in the container terminal
-3. If the Websocket circle becomes **green**, you are connected!
+3. If the Websocket icon becomes **green**, you are connected!

docs/code_overview.md

@@ -0,0 +1,50 @@
+# Code Overview
+
+Picture below shows how Camera and Controller interact with the codebase
+![mission control overview](./resources/mission_control_overview.png)
+
+- **store**: Put all global states here. Every store should have one purpose. Put subscribers and publishers here, so that there is one place to find the topic names.
+- **components**: Single file component vue files that contain localized state (aka other components will not use it). Do not directly use createSubscriber and createPublisher here. Instead put them into the store.
+- **lib**: [Vue Composables](https://vuejs.org/guide/reusability/composables) and any large amount of .ts files goes here.
+- **pages** Each tab in the navbar has its pages. Generally, there should be no state stored here as the components and store should have them.
+- **App.vue**: Pubs and Subs that are always running and not part of a component such as the controller should be ran here.
+- **types.ts** Put all global types here.
+
+## Design choices
+
+We are using Vue for its reactivity and lightweightness alongside Pinia, a global state management to handle the growing amount of state shared among components. Pinia has the benefit of running before the app, ensuring the ros object is always initialized. We use Typescript to make the code more readable and maintainable. Because ROS uses the publisher and subscriber paradigm, we use Roslibjs library to easily interact with ROS in TypeScript, allowing us to use publishers, subscribers, and services, without having to manually create our own protocol to send data back and forward between the rover and the mission control. The WebSocket and the protocol is through Rosbridge Suite.
+
+## How the Rover and the Mission Control communicates under the hood
+
+The rover runs Ros server which creates a WebSocket server that then the mission control connects to as it is ran on the browser. The connection is TCP and is able to send data bidirectional. Any interactions such as subscribing and publishing under the hood are just JSON sent back and forward. This is all done for us and we simply use the Roslibjs library. Below is an example of Chrome dev tools-> network-> WS (WebSocket) on what the JSON message being sent looks like.
+
+![image](./resources/rosbridge_heartbeat_json.png)
+
+For a deeper dive, refer to the [Rosbridge_Protocol.md](https://github.com/RobotWebTools/rosbridge_suite/blob/ros2/ROSBRIDGE_PROTOCOL.md).
+
+## Module System
+
+To easily move components around, we will create "Modules" to fit in the 2x3 grid system. Most Modules will be 1x1, but if necessary, can be bigger such as 2x2 1x2, and 2x1.
+
+![image of modules](./resources/module_2x3.png)
+
+## Code Philosophy
+
+Philosophy on keeping the codebase clean and efficient.
+
+1. **Don't send or receive unnecessary data**: Due to the distance between the Rover and the base station during competition (~1 km), the rover will have limited bandwidth. So whenever a component like a camera is not being used, unsubscribe from that topic.
+
+Example in `ExampleComponent.vue`:
+
+```Typescript
+// Starts subscriber when in view
+onActivated(() => {
+  example.helloWorldSub.start();
+});
+// Cleanup Auto unsubscribes when not loaded to save bandwidth
+onDeactivated(() => {
+  example.helloWorldSub.stop();
+});
+```
+
+2. **Do not directly use the Ros object**: The ros object has a lot of functionalities, and many ways to code the same thing. For standardization and encapsulation purposes, use createPublisher and createSubscribers instead. If there is a feature like getTopics(), create a function in useRoslib that returns it. If the feature is more reusable, like services, create a composite for it.

docs/getting_started.md

@@ -0,0 +1,53 @@
+# Getting Started
+
+Welcome to the mission control subteam! We hope that you will stick around and learn quite a bit of things about frontend development and networking! However, before you can do that, you should review the resources given in this document to familiarize yourself.
+
+If completely new, please refer to the [urc's getting_started.md](https://github.com/TrickfireRobotics/urc-2023/blob/main/docs/getting_started.md) as that gives an overall view of everything. For local development you will need to follow the instructions to setup Docker to run the urc-2023 repository.
+
+## What's the mission control?
+
+The mission control is the human interface to communicate bidirectionally (Sends and receives information) with the rover. For example, sending joystick inputs to the rover or displaying the rover's camera feed in real time.
+
+## Difference between urc-2023 and mission-control GitHub Repository
+
+The urc-2023 repo is the code that is run on the rover itself. Due to the code being very hardware specific, the docker container you run on your computer ensures standardization with the rover. Think of the rover as the "server".
+
+The mission-control repo is completely separate from the urc-2023 as it is webpage-based, meaning the code is ran in the browser—and with modern browsers' standardization of features, a docker container is not needed. Think of the mission control as the "client".
+
+## Recommended IDE Setup
+
+- [VSCode](https://code.visualstudio.com/)
+
+- [Vue DevTools Chrome Extension](https://devtools.vuejs.org/getting-started/installation): Can Inspect Components State and integrated with Pinia, allowing to see store's state.
+
+## Libraries/Tools/Technologies that We Utilize
+
+In this particular codebase, we use the following libraries/tools/technologies. Please familiarize yourself with the concepts below:
+
+- Vue [Official Tutorial](https://vuejs.org/tutorial/#step-1) (We specifically use Vue 3 Composition API Single File Component)
+  - Prop drilling
+  - Reactiveness (when to use refs vs not)
+  - Lifecycle Hooks
+    - Read about Keep Alive onActivate() and onDeactivated() hooks vs onMounted() and onUnmounted() hooks
+- [Typescript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-oop.html)
+  - Difference between Primitives and object types and their respective naming convention
+- [Pinia](https://pinia.vuejs.org/) (Global state management store)
+  - How to create a store
+  - How to use a store
+- ROS2 (Robot Operating System)
+  - high level understanding of:
+    - Subscribers and Publisher paradigm
+    - Topics, messageTypes
+  - Please refer to the [urc-2023 documentation](https://github.com/TrickfireRobotics/urc-2023) for more information about Ros
+- HTML/SCSS
+- [Roslibjs Source Code](https://github.com/RobotWebTools/roslibjs)
+- Node Package Manager (NPM)
+  - Difference between dependency and Dev-dependency and when installing packages, which one to install too.
+
+## So... what should I do now?
+
+Please look at the [mission-control GitHub issues](https://github.com/TrickfireRobotics/mission-control/issues) and look for **_Good First Issue_**. Some issues might only require only a fraction of the concepts above like UI related ones.
+
+If you got here this far. I really appreciate you reading the documentation :)
+
+-Adam Chhor, creator of the mission control repository