diff --git a/astro.config.mjs b/astro.config.mjs index 01d9115..60235c9 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -176,18 +176,39 @@ export default defineConfig({ { label: 'Teleop', collapsed: true, - items: [ - { label: 'Teleop Overview', slug: 'teleop/overview' }, - { label: 'Downloading Offline Map', slug: 'teleop/downloading-offline-map' }, - { label: 'GUI Style Checking', slug: 'teleop/gui-style-checking' }, - { label: 'Sample Vue Component', slug: 'teleop/sample-vue-component' }, - { label: 'Tailwind Introduction', slug: 'teleop/tailwind-introduction' }, - { label: 'Teleop Codebase Organization', slug: 'teleop/organization' }, - { label: 'Teleop FAQ', slug: 'teleop/faq' }, - { label: 'Teleop Quickstart', slug: 'teleop/quickstart' }, - { label: 'Teleop Starter Project', slug: 'teleop/starter-project' }, - { label: 'Vue Introduction', slug: 'teleop/vue-introduction' }, - { label: 'WebSocket Handlers Lookup', slug: 'teleop/consumers-lookup' } + items: [{ + label: 'Getting Started', + collapsed: true, + items: [ + { label: 'Teleop Overview', slug: 'teleop/overview' }, + { label: 'Teleop Quickstart', slug: 'teleop/quickstart' }, + { label: 'Teleop Starter Project', slug: 'teleop/starter-project' } + ]}, + { + label: 'Guides', + collapsed: true, + items: [ + { label: 'Vue Introduction', slug: 'teleop/vue-introduction' }, + { label: 'Sample Vue Component', slug: 'teleop/sample-vue-component' }, + { label: 'Tailwind Introduction', slug: 'teleop/tailwind-introduction' }, + { label: 'Websockets Introduction', slug: 'teleop/websockets-introduction'}, + { label: 'SQLite Introduction', slug: 'teleop/sqlite-introduction'} + ] + }, + { + label: 'Teleop Organization and Tools', + collapsed: true, + items: [ + { label: 'Teleop Codebase Organization', slug: 'teleop/organization' }, + { label: 'GUI Style Checking', slug: 'teleop/gui-style-checking' }, + { label: 'Camera Client', slug: 'teleop/camera-client' }, + { label: 'Downloading Offline Map', slug: 'teleop/downloading-offline-map' }, + { label: 'WebSocket Handlers Lookup', slug: 'teleop/consumers-lookup' } + ] + }, + { label: 'Teleop Projects', slug: 'teleop/projects' }, + { label: 'Feature Request', slug: 'teleop/feature-request' }, + { label: 'Teleop FAQ', slug: 'teleop/faq' } ] }, { diff --git a/src/content/docs/teleop/camera-client.md b/src/content/docs/teleop/camera-client.md new file mode 100644 index 0000000..a2ab0d2 --- /dev/null +++ b/src/content/docs/teleop/camera-client.md @@ -0,0 +1,7 @@ +--- +title: "Camera Client" +--- + +## Overview + +The camera client is a hub for viewing the rover's various camera feeds. It's opened by all launch files that include "```camera_client```". Controls for cameras appear on the left (including adding new cameras and changing configuration), while the actual displays are on the right. The camera client does not work with the simulator. diff --git a/src/content/docs/teleop/downloading-offline-map.md b/src/content/docs/teleop/downloading-offline-map.md index 7c27486..079b8ff 100644 --- a/src/content/docs/teleop/downloading-offline-map.md +++ b/src/content/docs/teleop/downloading-offline-map.md @@ -11,7 +11,7 @@ Python script to download offline maps directly into `teleoperation/basestation_ Run with ``` -python3 teleoperation/download_offline_maps.py --location= +python3 scripts/download_offline_maps.py --location= ``` Loc can be: diff --git a/src/content/docs/teleop/faq.md b/src/content/docs/teleop/faq.md index bc268c8..e4dd59a 100644 --- a/src/content/docs/teleop/faq.md +++ b/src/content/docs/teleop/faq.md @@ -18,7 +18,7 @@ Enter `mrover` before trying to run the basestation. You have not entered the Python virtual environment. To enter the python venv, enter `mrover` in the shell. This macro runs: ```bash -$ cd ~/ros2_ws/src/mrover && source ~/ros2_ws/src/mrover/venv/bin/activate +cd ~/ros2_ws/src/mrover && source ~/ros2_ws/src/mrover/venv/bin/activate ``` which opens the python virtual environment and allows you to run the basestation. @@ -27,7 +27,7 @@ which opens the python virtual environment and allows you to run the basestation ## CMake -### Output +### Output 1 From your `./build.sh` output: @@ -36,10 +36,30 @@ ZED not found science_hw_bridge missing ``` -### Solution +### Solution 1 Some files that CMake expects are missing. You could try and remove the `#Perception` and `#Embedded` sections in `CMakeLists`, and reach out to your team lead for help. +### Output 2 + +`./build.sh` output gives many missing file errors. + +### Solution 2 + +Try updating or deinitializing and then reinitializing git submodules. + +``` bash +git submodule update +# or +git submodule deinit +git submodule init +``` + +Submodules include; +- deps/dawn +- deps/manif +- esw/fw + --- ## Frontend not loading diff --git a/src/content/docs/teleop/feature-request.md b/src/content/docs/teleop/feature-request.md new file mode 100644 index 0000000..9750dd7 --- /dev/null +++ b/src/content/docs/teleop/feature-request.md @@ -0,0 +1,7 @@ +--- +title: "Teleop Feature Request" +--- + +## Feature Request + +Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSd-sDdytRO2hFJAeUFrdFSiaeeOY1nzcbLjtVUYSmkCp70zNw/viewform?usp=sharing&ouid=104464537546922765205) to request a feature. diff --git a/src/content/docs/teleop/gui-style-checking.md b/src/content/docs/teleop/gui-style-checking.md index b893685..1d20a00 100644 --- a/src/content/docs/teleop/gui-style-checking.md +++ b/src/content/docs/teleop/gui-style-checking.md @@ -43,6 +43,18 @@ bun run stylelint - This runs **Stylelint**, which checks CSS ordering and conventions in `.vue` and `.css` files. +:::tip +You can use + +```zsh +bun run stylelint "**/*.css" +# or +bun run stylelint "**/*.vue" +``` + +in zsh *(type of terminal shell; what you are probably already using)* to run stylelint on every css or vue file in the current directory/folder. +::: + Additionally, the **Prettier** plugin should take care of the more mundane tasks like spacing and indentation in your code when you save (Ctrl-S). --- diff --git a/src/content/docs/teleop/organization.md b/src/content/docs/teleop/organization.md index 068a0df..4cc088a 100644 --- a/src/content/docs/teleop/organization.md +++ b/src/content/docs/teleop/organization.md @@ -2,6 +2,77 @@ title: "Teleop Codebase Organization" --- -### Lockfile Tracking +## Directory Structure -Teleop does not track bun.lock. Lockfile conflicts are frequent acorss branches, and package.json should contain critical information regarding dependency and version control. Further granulated control of dependencies are not needed, and therefore the lockfile should not be tracked. \ No newline at end of file +### Summary + +*note: not all directories included below* + +``` +teleoperation +├── basestation_gui +│   ├── backend +| | ├── managers +| | ├── routes +| | └── ws +│   └── frontend +| ├── public +| | └── urdf +| └── src +| ├── components +| | ├── ControllerDataTable +| | └── three +| ├── composables +| ├── router +| ├── stores +| ├── types +| ├── utils +| └── views +└── camera_client + ├── include + └── src +``` + +--- + +### Basestation GUI + +```basestation_gui``` contains all the code for the Base Station. + +#### Backend + +Contains code for the server. + +```managers``` contains classes that handle functionality requiring a consistent state. + +```routes``` contains functions that handle HTTP requests. + +```ws``` contains WebSocket definitions. + +#### Frontend + +Contains code for the frontend. + +```public``` contains graphical assets for the frontend. ```urdf``` contains .urdf and .glb models. + +```src``` contains all the code for the frontend. +* ```components``` contains Vue components. + * ```three``` contains 3D rover display code. +* ```composables``` contains reusable logic. +* ```router``` manages paths to views. +* ```stores``` contains code that handles Pinia stores. +* ```types``` contains custom variable types. +* ```utils``` contains various APIs. +* ```views``` contains main pages. + +--- + +### Camera Client + +Contains code for the camera client. Split into header (```include```) and source (```src```) files. + +--- + +## Lockfile Tracking + +Teleop does not track bun.lock. Lockfile conflicts are frequent across branches, and package.json should contain critical information regarding dependency and version control. Further granulated control of dependencies are not needed, and therefore the lockfile should not be tracked. diff --git a/src/content/docs/teleop/overview.md b/src/content/docs/teleop/overview.md index e9aa690..2ba4f3e 100644 --- a/src/content/docs/teleop/overview.md +++ b/src/content/docs/teleop/overview.md @@ -1,13 +1,13 @@ --- title: "Teleop Overview" --- -# What is the role of the Teleoperations team? +## What is the role of the Teleoperations team? The Teleoperations (Teleop) team ensures the rover's physical systems are easily controllable by a human operator. We build and maintain key systems that allow operators to command the rover and receive feedback in real time. ## Base Station GUI -The Base Station GUI is a Vue.js web app that serves as the main interface for operating the rover. It: +The Base Station GUI is a [Vue.js](/teleop/vue-introduction) web app that serves as the main interface for operating the rover. It: - Captures controller inputs (Xbox, Thrustmaster joystick) - Displays GPS, camera, and sensor data @@ -18,12 +18,12 @@ and more... ## FastAPI Backend -To support the frontend, we have a Python FastAPI backend that bridges the GUI to ROS2. It: +To support the frontend GUI, we have a Python FastAPI backend that bridges it to Robot Operating Software 2 [(ROS2)](/general-resources/ros/intro-to-ros/). It: -- Maintains WebSocket connections per subsystem (arm, drive, nav, science, etc.) +- Maintains [WebSocket](/teleop/websockets-introduction) connections per subsystem (arm, drive, nav, science, etc.) - Forwards ROS2 topics to the frontend via msgpack-serialized WebSocket messages - Publishes controller inputs from the frontend to ROS2 topics -- Stores persistent data like GPS waypoints in SQLite +- Stores persistent data like GPS waypoints in [SQLite](/teleop/sqlite-introduction) - Computes robotic arm commands (throttle, IK position, IK velocity) ## Tech Stack @@ -31,13 +31,13 @@ To support the frontend, we have a Python FastAPI backend that bridges the GUI t | Layer | Technology | |-------|-----------| | Frontend | Vue 3, TypeScript, Vite, Pinia, Tailwind CSS | -| 3D / Maps | Three.js, Leaflet | +| Complex Visuals | Three.js (3D), Leaflet (Maps) | | Backend | Python, FastAPI, uvicorn | | Communication | WebSocket + msgpack binary serialization | | Data | SQLite | | Runtime | Bun (JS), ROS2 rclpy (Python) | -# Resources +## Resources [Teleop Quickstart](/teleop/quickstart) @@ -53,4 +53,6 @@ To support the frontend, we have a Python FastAPI backend that bridges the GUI t [Teleop Starter Project](/teleop/starter-project) -[Sample Vue Component](/teleop/sample-vue-component) +--- + +Have a suggestion for features? Put it [here](https://docs.google.com/forms/d/e/1FAIpQLSd-sDdytRO2hFJAeUFrdFSiaeeOY1nzcbLjtVUYSmkCp70zNw/viewform?usp=sharing&ouid=104464537546922765205)! diff --git a/src/content/docs/teleop/projects.md b/src/content/docs/teleop/projects.md new file mode 100644 index 0000000..fa8784b --- /dev/null +++ b/src/content/docs/teleop/projects.md @@ -0,0 +1,7 @@ +--- +title: "Teleop Projects" +--- + +## 2026 - 2027 Projects + +Projects should be accessible for members at [this spreadsheet](https://docs.google.com/spreadsheets/d/1YPRy4b-1OhNhXep2DHNy43zICfC72mdERJBsUHw-v0s/edit?gid=0#gid=0). diff --git a/src/content/docs/teleop/quickstart.md b/src/content/docs/teleop/quickstart.md index 28df5f5..c2e91b3 100644 --- a/src/content/docs/teleop/quickstart.md +++ b/src/content/docs/teleop/quickstart.md @@ -6,11 +6,11 @@ title: "Teleop Quickstart" Once you have completed the installation from the [Install ROS](/general-resources/ros/install-ros/install-ros) page, make sure you are on the `main` branch: ```bash -git checkout main +git switch main git pull ``` -Features are developed on branches checked out from `main` and merged back via pull request. In the mrover home directory, run the following commands: +Features are developed on branches switched to from `main` and merged back via pull request. In the mrover home directory, run the following commands: ```bash ./build.sh diff --git a/src/content/docs/teleop/sqlite-introduction.md b/src/content/docs/teleop/sqlite-introduction.md new file mode 100644 index 0000000..dfe2abd --- /dev/null +++ b/src/content/docs/teleop/sqlite-introduction.md @@ -0,0 +1,14 @@ +--- +title: "SQLite Introduction" +--- + +## Overview + +We use SQLite databases to store information that has to last when the page unloads. This includes recordings, waypoints, etc. These databases are typically accessed through python backend code. + +## Using Databases + +Use ```get_db_connection()``` to interface the databases. It's best to assign the return value to a variable. +Use ```get_db_connection().execute("SQL query string").fetchall()``` to query the databases. + +[SQL Cheat Sheet](https://www.sqlitetutorial.net/sqlite-cheat-sheet/) diff --git a/src/content/docs/teleop/starter-project.md b/src/content/docs/teleop/starter-project.md index 59868dc..a836313 100644 --- a/src/content/docs/teleop/starter-project.md +++ b/src/content/docs/teleop/starter-project.md @@ -2,48 +2,51 @@ title: "Teleop Starter Project" --- -# Introduction +## Introduction Here, you will complete a Vue component by: -* Creating page elements. -* Formatting page elements. -* Importing other components (```ArmControls``` and ```Rover3D```). -* Sending/receiving messages to/from the backend. +- Creating page elements. +- Formatting page elements. +- Importing other components (```ArmControls``` and ```Rover3D```). +- Sending/receiving messages to/from the backend. The tasks you complete in this project will be similar to tasks that you see in the future. Don't be afraid to ask questions if you can't understand something, or are just curious. At a quick glance, the teleop system may seem simple, but there are a lot of moving parts. --- -# Getting Started +## Getting Started + +### Opening the Code -## Opening the Code First, go to [Teleop Quickstart](/teleop/quickstart) and make sure your environment is set up. Critically, make sure you've run ```./build.sh``` and have all necessary dependencies. -Open up a terminal, and type ```mrover```. Then: +Open up a terminal, and type ```mrover```. Then: -Checkout/go to the branch that has the starter project code: +Switch/go to the branch that has the starter project code: ```bash -git checkout teleop-starter-2026 +git switch teleop-starter-2026 ``` Copy it into a new branch: ```bash -git checkout -b /starter-project-2026 -example: git checkout -b km/starter-project-2026 +git switch -c /starter-project-2026 +example: git switch -c km/starter-project-2026 ``` :::note -Whenever you create a new feature, you should make a new branch and follow the naming convention of ```/```. You'll often checkout from main, but not always. +Whenever you create a new feature, you should make a new branch and follow the naming convention of ```/```. You'll often switch from main, but not always. ::: -Now you (hopefully) have the starter code ready to be worked on. But how do you run and debug it? +Now you (hopefully) have the starter code ready to be worked on. But how do you run and debug it? -## Running the Code +### Running the Code Go to the url ```http://localhost:8080/starter``` in your browser. You should see an error page. This is because it is trying to access a server on and IP address that doesn't have any - ```localhost``` a.k.a. ```127.0.0.1``` a.k.a. **your** computer. To create the server it needs, go to your terminal, and run + ```bash +mrover ros2 launch mrover basestation.launch.py mode:=dev ``` @@ -54,20 +57,22 @@ ros2 launch mrover basestation.launch.py mode:=dev This launches both the frontend and the backend. Now once you go back to your browser, you should see a webpage with a header and some text with "Hello World!" in it after reloading. If not, make sure you did everything in [Teleop Quickstart](/teleop/quickstart), or ask for help. :::note -* The ```/starter``` part of the url specifies that you are on the "Starter" page of the basestation. You can remove it to see the main page. -* The ```:8080``` part of the url is the port number. It functions as a sort of "id" for the server on the particular computer. +- The ```/starter``` part of the url specifies that you are on the "Starter" page of the basestation. You can remove it to see the main page. +- The ```:8080``` part of the url is the port number. It functions as a sort of "id" for the server on the particular computer. ::: --- -# Vue Files and Editing +## Vue Files and Editing Now, open up ```StarterProject.vue``` in a code editor. It's easiest to just run this in a new terminal: + ```bash mrover code . ``` -Then press **ctrl-p** and type the file's name to search for it. It should look something like this: + +Then press **ctrl-p** and type the file's name to search for it. It should look something like this: ```html