diff --git a/README.md b/README.md index 4f0c6ff7..8615702c 100644 --- a/README.md +++ b/README.md @@ -1,279 +1,37 @@ -# Cabrillo ROV 2023 +
CRC Logo
+ +## SeaHawk II +SeaHawk is a project designed by a team of community college students from [Cabrillo College](https://www.cabrillo.edu/) in Aptos, California. Our latest project, SeaHawk II continues Cabrillo Robotics legacy of [SeaHawk I](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/releases/tag/MATEROV-2023) and [Hydrozoa](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2022) and will compete in the 2024 [MATE](https://materovcompetition.org/world-championship) International Competition. MATE challenges teams worldwide to build a Remotely Operated Vehicle (ROV) that can complete simulated real-world tasks underwater. Teams also demonstrate their robot's functionality and design rationale through marketing, documentation, a presentation, and more. Previously, Cabrillo Robotics has competed in the Pioneer division of the competition and took home first place the last two consecutive years. This year, we take on the challenge of developing a ROV to compete in the highest class of the competition: Explore. + +## Getting started developing +Are you new here? If so, welcome to Cabrillo Robotics Club! To get started developing for this project, the following documents will be useful. + +| Documentation content | File | +| ---- | ---- | +| Getting started developing | [getting_started.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/getting_started.md) | +| Running the project | [run.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/run.md) | + +The additional resources below may also be of assistance. +| Resource | Link | +| ---- | ---- | +| ROS2 Humble documentation | [ROS 2 Documentation: Humble Hawksbill](https://docs.ros.org/en/humble/index.html) +| Software team onboarding repo | [TinyHawk GitHub](https://github.com/CabrilloRoboticsClub/tiny_hawk) +| Software team onboarding videos | [TinyHawk YouTube Playlist](https://www.youtube.com/watch?v=hzFErKeImTs&list=PLrhUbqBwgd2hjlbSZ6VrAEFjsnTWKxhTc) + + +## Documentation +Documentation for the software in this repo is found in the [`doc`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/tree/main/doc) directory. + +| Documentation content | File | +| ---- | ---- | +| Project architecture | [architecture.md ](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/architecture.md) | +| Notes on the cameras| [camera_notes.md ](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/camera_notes.md) | +| Getting started developing | [getting_started.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/getting_started.md) | +| Using Git/GitHub | [github.md ](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/github.md) | +| ROS parameters and the SetRemoteParams class| [params.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/params.md) | +| Using and updating RViz | [rviz.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/rviz.md) | +| Running the project | [run.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/run.md) | +| Collecting and running ROS bags | [ros_bags.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/ros_bags.md) | +| Miscellaneous notes on the ROS packaging process | [rosdep_notes.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/rosdep_notes.md) | +| Project style guide (Python) | [style_guide_python.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/style_guide_python.md) | -Cabrillo College Robotics Club repo for the MATE ROV 2023 competition. This README file has information to get you started developing the robot. - -## Setup GitHub - -In order to use this repository you should have generated SSH keys and uploaded your public key to GitHub. If you have not yet created an SSH key on your machine do the following. **Skip these steps if you have an SSH key in GitHub already**. - -1. Create an SSH key if you don't have one already. - ```console - ssh-keygen -t ed25519 - ``` - Use the default location, set a password if you like. -1. Copy and paste your public key into GitHub - ```console - cat ~/.ssh/id_ed25519.pub - ``` - Full instructions for how to add a public key to GitHub can be found in [GitHub's official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account). - -## Checkout the Code - -**These instructions are for Mac, Windows and Linux.** On Windows you should use PowerShell, not the old command line. - -To get the code in this repository on your computer, dev box or RPi you should run the following commands. These commands assume that you have setup your SSH keys in GitHub according to the instructions in the "Setup GitHub" section above. - -1. Check if you have `git` installed on your computer. - ```console - git --version - ``` - **If you don't have Git installed:** - 1. Install Git on your platform by following the official [GIT Getting Started Instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 1. Setup `git` by entering in your name and email address. The email address should be the one you have registered with GitHub. - ```console - git config --global user.name "Your Name" - git config --global user.email "you@you.com" - ``` - -1. Check out this repository into your home directory. - - ```console - cd - git clone git@github.com:CabrilloRoboticsClub/cabrillo_rov_2023.git - cd ~/cabrillo_rov_2023 - git submodule init - git submodule update - ``` - -Now you have the source code on your computer and you should be able to make new branches and your own changes. - -## Getting Started (Mac and Windows Setup) - -If you have a Windows or Mac desktop (or Linux that's not Ubuntu 22.04) you can use Docker and Development Containers in vscode to do local development. This is the fastest and easiest way to get setup and eables you to run and test nodes on your computer. That's good for learning but you won't be able to use the ROS2 network or use devices like a joystick or camera. - -1. [Install vscode](https://code.visualstudio.com/) -1. [Install Docker Desktop](https://www.docker.com/products/docker-desktop/) -1. Follow the [Dev Containers Tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) -1. In vscode open the `cabrillo_rov_2023` directory that you checked out using the "Checkout the Code" procedure above with the `File -> Open Folder` menu. Vscode will prompt you to create a dev container. Follow the prompts. Building the container could take 10 to 20 minutes but you only have to do it once. -1. Create a Terminal in your vscode window with the `Terminal -> New Terminal` menu. -1. Build the software in your dev container: - - **Run this command in the dev container terminal.** - - ```console - make - ``` - -Alternatively, if you don't want to use the container inside of VSCode, you can run -```console -docker build -t ros2-container: .devcontainer -docker run --user vscode -v .:/home/vscode/cabrillo_rov_2023 --network host -it ros2-container: -``` - -## Ubuntu 22.04 Desktop Setup - -If you have Ubuntu 22.04 on your desktop you don't need a dev container because you can run everything natively. Only Ubuntu machines will be able to use hardware and communicate with other machines in the ROS2 network. These instructions assume you have already cloned the repository by following the "Checkout the Code" procedure above. - -1. Install the necessary software packages - ```console - sudo apt update -y && sudo apt install -y git ansible python3-pip vim - ``` -1. Use `make` to install ROS2 and all the necessary packages. - ```console - make devbox-install - ``` - **This will take a while!** - -1. Put ROS on your path - ```console - echo 'if [ -z "$ROS_DISTRO" ]; then source /opt/ros/humble/setup.bash; fi' >> ~/.bashrc - ``` -1. **Start a new shell** and build the repository - ```console - make - ``` - -You Desktop is now a dev box. - -## Raspberry Pi 4 Setup - -Start by creating a bootable SD card image: - -1. On your local computer download and install [Raspberry Pi Imager](https://www.raspberrypi.com/software/) -1. Attach a Micro SD card to your local computer -1. Open Raspberry Pi Imager - * `CHOOSE OS` > `Other general-purpose OS` > `Ubuntu` > `Ubuntu Server 22.04 LTS (64-bit)` - * Choose the Micro SD card as the storage and hit `WRITE` -1. Unplug the Micro SD card from your local computer, plug it back in to your local computer. -1. Copy the `user-data` file from `setup/image` into the `system-boot` volume that shows up (overwrite the existing file). -1. Install the SD card into the Raspberry Pi -1. Connect the Pi to an ethernet connection with internet access -1. Plug the power cable in to the Pi. - -The Pi will boot, then reboot. Give it 10 minutes or so. The hostname and passwords are now set. SSH is enabled. You can connect with: - -```console -ssh -A ubuntu@seahawk.local -``` - -Once you have SSHed into the new Pi image run the ROV specific playbooks: - -1. Check out this repository into your home directory. - ```console - cd - git clone https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023.git - cd ~/cabrillo_rov_2023 - git submodule init - git submodule update - ``` -1. Install make and Ansible command - ```console - sudo apt install make ansible - ``` -1. Use `make` to install ROS2 and all the necessary packages. - ```console - make rov-install - ``` - **This could take a long, long time!** up to 30 minutes. - -1. Reboot the Pi - ```console - sudo reboot - ``` - -The `make rov-install` command installs ROS2 and creates user accounts on the Raspberry Pi. After rebooting you should be able to login with your own username. - -## Using vscode to Connect to a Pi - -The best way to access the Raspberry Pi for software development is using vscode. You can use the access to develop and test nodes that run on the Pi or to just start the ROV during development of deck nodes. Assuming you have your own computer setup per the instructions above, perform the following steps to access the Pi. - -1. Install the [Remote SSH plugin](https://code.visualstudio.com/docs/remote/remote-overview) into vscode -1. Click the remote status bar on the very bottom left of the window. (You can find some tips in the [Remote SSH tutorial](https://code.visualstudio.com/docs/remote/ssh-tutorial).) - - ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/remote-status-bar.png) - - The Remote Status bar item can quickly show you in which context VS Code is running (local or remote) and clicking on the item will bring up the Remote - SSH commands. - - ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/remote-ssh-commands.png) -1. Type the ssh command into the top bar: - - ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/set-user-host.png) - - > The command will look like: **ssh yourname@seachicken.local -A** - -1. Follow the prompts: - 1. Choose the first option for where to save the configuration. - 1. Choose "Linux" type if asked. - 1. Choose "Yes" if this is your first time connecting to this Pi. - -1. You should see that you are connected: - - ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/ssh-status-bar.png) - -1. Now that you're connected, start a new Terminal using the `Terminal -> New Terminal` menu. -1. Create a copy of the repo in your home directory: - - ```console - cd - git clone git@github.com:CabrilloRoboticsClub/cabrillo_rov_2023.git - cd ~/cabrillo_rov_2023 - git submodule init - git submodule update - ``` - -1. Configure git on the Pi4: - - ```console - git config --global user.name "Your Name" - git config --global user.email "you@you.com" - ``` - -1. Add ROS to your startup scripts: - - ```console - echo 'if [ -z "$ROS_DISTRO" ]; then source /opt/ros/humble/setup.bash; fi' >> ~/.bashrc - ``` - -1. Exit your current terminal and start a new one. -1. Build the ROS project - - ```console - cd ~/cabrillo_rov_2023 - make - ``` - -Vscode will remember everything for next time. You should only have to do this once. - - -## Building the Nodes - -The ROS nodes are built with the `colcon` program. A `makefile` is present to help me remember what the `colcon` commands are. Build the project with: - -```console -make -``` - -The build artifacts are in: - -- `build` -- `install` -- `log` - -Clean the build with: - -```console -make clean -``` - -## Starting the ROV and Deck ROS2 Nodes - -The easiest way to launch is by `make`. To launch the deck nodes and RQT viewer run: - -```console -$ make deck -``` - -To launch all the nodes on the ROV run: - -```console -$ make rov -``` - -## Launch Files - -We've migrated all the launch files to their respective ROS packages. To use the launch files you must first run the `install/local_setup.XXX` script. - -```console -ros2 launch seahawk rov.launch.py -``` - -To launch all the nodes on the deck: - -```console -ros2 launch seahawk deck.launch.py -``` - -## Running Individual Nodes - -The built nodes are a part of a local build area. Source the following script to setup your paths: - -```console -source install/setup.bash # Choose one that matches your shell. -``` - -Run the Python examples: - -```console -ros2 run seahawk example_pub -ros2 run seahawk example_sub -``` - -## Launching the Kinematics Debug Nodes - -Do this to launch the debug nodes. It also starts RViz: - -```console -$ ros2 launch seahawk kinematics_viz.launch.py -``` - -You have to separately launch the other deck nodes. diff --git a/bags/joy_recording/README.md b/bags/joy_recording/joy_recording.md similarity index 100% rename from bags/joy_recording/README.md rename to bags/joy_recording/joy_recording.md diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 00000000..253c1ba7 --- /dev/null +++ b/doc/architecture.md @@ -0,0 +1,150 @@ +# Software Architecture +Much its predecessors, [SeaHawk I](https://github.com/CabrilloRoboticsClub/cabrillo_rov_202/releases/tag/MATEROV-2023) and [Hydrozoa](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2022), SeaHawk II uses the Robot Operating System (ROS) for its modularity and tools for developing software for robotics. Specifically, SeaHawk II uses [ROS2 Humble](https://docs.ros.org/en/humble/index.html). ROS provides a framework in which nodes perform tasks and then communicate messages over topics. This document describes the organization of nodes, their function, and the topics over which they communicate. + +## Graph +```mermaid +flowchart LR + subgraph seahawk_deck + direction LR + id_in --- id_desired_twist[desired_twist]:::top--> id_thrust(thrust):::node + id_thrust--- id_motor_values[motor_values]:::top--->id_rviz(rviz_markers) + id_motor_values ---> id_motor_encoding(motor_encoding):::node + end + + subgraph seahawk_rov + direction LR + debug_id(debug) + end + + subgraph external + direction TB + id_xbox(Xbox One Controller):::out ---> id_joy_n(joy_node):::out + id_joy_n(joy_node):::out --- id_joy_t[joy]:::top ---> id_in(pilot_input):::node + end + classDef node stroke:#9172f8, fill:#373038 + classDef out stroke:#F12626, fill:#573838 + classDef top fill:#949494, stroke:#949494 +``` + +## Nodes + +### joy_node +- **Publishes to:** [`/joy`](http://docs.ros.org/en/api/sensor_msgs/html/msg/Joy.html) + +**Run the node:** +```console + ros2 run joy joy_node +``` + +**Description:** +The `joy_node` node from the [joy](http://wiki.ros.org/joy) package reads input from a Linux joystick controller and publishes it to the `/joy` topic. The message of type `Joy` contains the current state of the joystick buttons and axes in two arrays. The buttons and axes of an Xbox One are mapped in the following configuration for an Xbox One Controller: + + + + +
Xbox One Controller
buttons arrayaxes array
+ +| Index | Button | +| ----- | ------ | +| 0 | A | +| 1 | B | +| 2 | X | as +| 3 | Y | +| 4 | LB | +| 5 | RB | +| 6 | Window | +| 7 | Menu | +| 8 | Xbox | +| 9 | Left stick press | +| 10 | Right stick press | + + + +| Index | Axes | +| ----- | ---- | +| 0 | Left stick x | +| 1 | Left stick y | +| 2 | LT | +| 3 | Right stick x | +| 4 | Right stick y | +| 5 | RT | +| 6 | Dpad x | +| 7 | Dpad y | + +
+ + +--- +### pilot_input +- **File:** [`pilot_input.py`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/src/seahawk/seahawk_deck/pilot_input.py) +- **Subscribes to:** [`/joy`](http://docs.ros.org/en/api/sensor_msgs/html/msg/Joy.html) +- **Publishes to:** `/desired_twist`, `/claw_state` +- **Parameters:** `throttle_curve_choice` + +**Run the node:** +```console + ros2 run seahawk pilot_input +``` + +**Description:** The `pilot_input` node subscribes to the `/joy` topic, mapping `Joy` message contents to its functionality piloting the robot. Values from the controller are modified if requested, and then republished to topics. + +The bumpers and sticks (axes) are mapped to driving the robot in linear and angular space. From these values, a [`Twist`](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/Twist.html) message is created specifying the direction ($\pm$ linear/angular x, y, z) and percent of max throttle the pilot wants the robot to move. The throttle may be modified from default by initiating bambi mode and by using throttle curves. Bambi mode cuts all inputs in half for precise movements. Throttle curves change the relationship between the position of the stick and the amount of throttle produced. The pilot may choose a throttle curve using the keyboard, which remotely updates the curve selection on this node using parameters. + +Additionally, buttons on the controller contribute to the behavior of the robot. This includes triggering the claw, whose state is published to the`claw_state` topic. The complete controller mapping can be found below. + + + +--- +### thrust +- **File:** [`thrust.py`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/src/seahawk/seahawk_deck/thrust.py) +- **Subscribes to:** `/desired_twist` +- **Publishes to:** `/motor_values` +- **Parameters:** `center_of_mass_offset` + +**Run the node:** +```console + ros2 run seahawk thrust +``` + +**Description:** The `thrust` node converts a `Twist` message specifying the pilot's desired direction ($\pm$ linear/angular x, y, z) and percent of max throttle into the amount of thrust in Newtons each motor should produce. + +--- + +### rviz_markers +- **File:** [`rviz_markers.py`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/architecture/src/seahawk/seahawk_deck/rviz_markers.py) +- **Subscribes to:** `/motor_values` +- **Publishes to:** `/motor_debug` +- **See:** [rviz.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/architecture/doc/rviz.md) + +**Run the node:** +``` +# Run the node +ros2 run seahawk rviz_markers + +# Launch Rviz +ros2 launch seahawk kinematics_viz.launch.py +``` + +**Description:** [Rviz](http://wiki.ros.org/rviz) (ROS Visualization) is a 3D tool which enables developers to view the functionality of a robot virtually. This is useful for software development before the physical robot is completed or for remote work. The `rviz_markers` node uses RViz to visualize water propulsion from the motors. + +--- + +### debug_node +- **File:** [`debug.py`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/src/seahawk/seahawk_rov/debug.py) +- **Publishes to:** `/debug_info` + +**Run the node:** +``` +ros2 run seahawk debug +``` + +**Description:** Publishes diagnostic information from the Raspberry Pi. The message published to `/debug_info` contains the following contents +| Type | Name | Description | +|:----| :---- | :---------- | +| `float64` | `cpu_usage` | The CPU usage in %| +| `float64` | `memory_usage` | The memory usage in %| +| `float64` | `cpu_temperature` | The CPU temperature in C| +| `string` | `net_sent` | The number of bytes sent, string contains denomination| +| `string` | `net_recv` | The number of bytes received, string contains denomination | +| `float64` | `time` | The time of when measurements were read | + diff --git a/doc/camera_notes.md b/doc/camera_notes.md index 00393f25..96e92359 100644 --- a/doc/camera_notes.md +++ b/doc/camera_notes.md @@ -1,3 +1,4 @@ +*from 2023* # Camera Notes ## Camera Nodes diff --git a/doc/dev_notes.md b/doc/dev_notes.md deleted file mode 100644 index 138c41d6..00000000 --- a/doc/dev_notes.md +++ /dev/null @@ -1,22 +0,0 @@ -# SETUP NOTES - -ROV build code: - -- `git clone https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023.git` -- `cd cabrillo_rov_2023` -- `git submodule init` -- `git submodule update` -- `sudo rosdep init` -- `rosdep update` -- `rosdep install -i --from-path src/ --rosdistro humble -y` -- `source /opt/ros/humble/setup.bash` -- `make` - -loop: - -- `rosdep update` -- `rosdep install -i --from-path src/ --rosdistro humble -y` -- `source /opt/ros/humble/setup.bash` -- `make` -- `source install/setup.bash` -- `ros2 launch` diff --git a/doc/getting_started.md b/doc/getting_started.md new file mode 100644 index 00000000..18f8721f --- /dev/null +++ b/doc/getting_started.md @@ -0,0 +1,175 @@ + +# Getting started +This file has information to get you started developing the robot. + +## 1 Checkout the code +*If you have used git and GitHub before, follow this quick start guide. If not, navigate to [github.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/github.md).* + +**These instructions are for Mac, Windows and Linux.** On Windows you should use PowerShell, not the old command line. To get the code in this repository on your computer, dev box or RPi you should run the following commands. These commands assume that you have setup your SSH keys in GitHub. + +```sh +cd +git clone git@github.com:CabrilloRoboticsClub/cabrillo_rov_2023.git +cd ~/cabrillo_rov_2023 +git submodule init +git submodule update +``` + +Now you have the source code on your computer and you should be able to make new branches and your own changes. + + +## 2 Mac and windows setup +If you have a Windows or Mac desktop (or Linux that's not Ubuntu 22.04) you can use Docker and Development Containers in vscode to do local development. This is the fastest and easiest way to get setup and enables you to run and test nodes on your computer. That's good for learning but you won't be able to use the ROS2 network or use devices like a joystick or camera. + +1. [Install vscode](https://code.visualstudio.com/) +1. [Install Docker Desktop](https://www.docker.com/products/docker-desktop/) +1. Follow the [Dev Containers Tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) +1. In vscode open the `cabrillo_rov_2023` directory that you checked out using the "1 Checkout the code" procedure above with the `File -> Open Folder` menu. Vscode will prompt you to create a dev container. Follow the prompts. Building the container could take 10 to 20 minutes but you only have to do it once. +1. Create a Terminal in your vscode window with the `Terminal -> New Terminal` menu. +1. Build the software in your dev container: + + **Run this command in the dev container terminal.** + + ```sh + make + ``` + +Alternatively, if you don't want to use the container inside of VSCode, you can run +```sh +docker build -t ros2-container: .devcontainer +docker run --user vscode -v .:/home/vscode/cabrillo_rov_2023 --network host -it ros2-container: +``` + +## 2 Ubuntu 22.04 Desktop Setup + +If you have Ubuntu 22.04 on your desktop you don't need a dev container because you can run everything natively. Only Ubuntu machines will be able to use hardware and communicate with other machines in the ROS2 network. These instructions assume you have already cloned the repository by following the "1 Checkout the code" procedure above. + +1. Install the necessary software packages + ```sh + sudo apt update -y && sudo apt install -y git ansible python3-pip vim + ``` +1. Use `make` to install ROS2 and all the necessary packages. **This will take a while!** + ```sh + make devbox-install + ``` + +1. Put ROS on your path + ```sh + echo 'if [ -z "$ROS_DISTRO" ]; then source /opt/ros/humble/setup.bash; fi' >> ~/.bashrc + ``` +1. **Start a new shell** and build the repository + ```sh + make + ``` + +You Desktop is now a dev box. + +## 2 Raspberry Pi 4 Setup + +### Start by creating a bootable SD card image + +1. On your local computer download and install [Raspberry Pi Imager](https://www.raspberrypi.com/software/) +1. Attach a Micro SD card to your local computer +1. Open Raspberry Pi Imager + * `CHOOSE OS` > `Other general-purpose OS` > `Ubuntu` > `Ubuntu Server 22.04 LTS (64-bit)` + * Choose the Micro SD card as the storage and hit `WRITE` +1. Unplug the Micro SD card from your local computer, plug it back in to your local computer. +1. Copy the `user-data` file from `setup/image` into the `system-boot` volume that shows up (overwrite the existing file). +1. Install the SD card into the Raspberry Pi +1. Connect the Pi to an ethernet connection with internet access +1. Plug the power cable in to the Pi. +The Pi will boot, then reboot. Give it 10 minutes or so. The hostname and passwords are now set. SSH is enabled. You can connect with: + ```sh + ssh -A ubuntu@seahawk.local + ``` + +### Once you have SSHed into the new Pi image run the ROV specific playbooks + +1. Check out this repository into your home directory. + ```sh + cd + git clone https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023.git + cd ~/cabrillo_rov_2023 + git submodule init + git submodule update + ``` +1. Install make and Ansible command + ```sh + sudo apt install make ansible + ``` +1. Use `make` to install ROS2 and all the necessary packages. + ```sh + make rov-install + ``` + **This could take a long, long time!** up to 30 minutes. + +1. Reboot the Pi + ```sh + sudo reboot + ``` + +The `make rov-install` command installs ROS2 and creates user accounts on the Raspberry Pi. After rebooting you should be able to login with your own username. + +### Using vscode to Connect to a Pi + +The best way to access the Raspberry Pi for software development is using vscode. You can use the access to develop and test nodes that run on the Pi or to just start the ROV during development of deck nodes. Assuming you have your own computer setup per the instructions above, perform the following steps to access the Pi. + +1. Install the [Remote SSH plugin](https://code.visualstudio.com/docs/remote/remote-overview) into vscode +1. Click the remote status bar on the very bottom left of the window. (You can find some tips in the [Remote SSH tutorial](https://code.visualstudio.com/docs/remote/ssh-tutorial).) + + ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/remote-status-bar.png) + + The Remote Status bar item can quickly show you in which context VS Code is running (local or remote) and clicking on the item will bring up the Remote - SSH commands. + + ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/remote-ssh-commands.png) +1. Type the ssh command into the top bar: + + ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/set-user-host.png) + + > The command will look like: **ssh yourname@seachicken.local -A** + +1. Follow the prompts: + 1. Choose the first option for where to save the configuration. + 1. Choose "Linux" type if asked. + 1. Choose "Yes" if this is your first time connecting to this Pi. + +1. You should see that you are connected: + + ![](https://code.visualstudio.com/assets/docs/remote/ssh-tutorial/ssh-status-bar.png) + +1. Now that you're connected, start a new Terminal using the `Terminal -> New Terminal` menu. +1. Create a copy of the repo in your home directory: + + ```sh + cd + git clone git@github.com:CabrilloRoboticsClub/cabrillo_rov_2023.git + cd ~/cabrillo_rov_2023 + git submodule init + git submodule update + ``` + +1. Configure git on the Pi4: + + ```sh + git config --global user.name "Your Name" + git config --global user.email "you@you.com" + ``` + +1. Add ROS to your startup scripts: + + ```sh + echo 'if [ -z "$ROS_DISTRO" ]; then source /opt/ros/humble/setup.bash; fi' >> ~/.bashrc + ``` + +1. Exit your current terminal and start a new one. +1. Build the ROS project + + ```sh + cd ~/cabrillo_rov_2023 + make + ``` + +Vscode will remember everything for next time. You should only have to do this once. + +## 3 Next steps +Navigate to [`run.md`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/run.md) for information on how to run the project. \ No newline at end of file diff --git a/doc/github.md b/doc/github.md new file mode 100644 index 00000000..22f05296 --- /dev/null +++ b/doc/github.md @@ -0,0 +1,126 @@ +# Using Git and GitHub +## 1 Installing git +1. By default, git should be installed. +2. Confirm git is installed by running the following command in your terminal. + ```sh + git --version + ``` + You should get back something that looks like `git version 2.39.0` +3. If you did not get a version number, follow the this guide: [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + + +## 2 Create a GitHub account +GitHub is the free web based platform we and many other software engineers use to share and collaborate on projects as well as control version history. + +1. Go to [GitHub](https://github.com/) and follow the steps to create an account. + + Note: As a Cabrillo student, you can get a bunch of free goodies from GitHub Education. For now, you should continue following this guide, but later, don't forget to go to [education.github.com](https://education.github.com/). You will have to add your `STUDENTID@student.cabrillo.edu` email (it's a Gmail account). +2. Return to the terminal to configure git. +3. Set up your username using the following command where `` is the username you chose when creating your GitHub account + ```sh + git config --global user.name + ``` +4. Set up your email using the following command where `` is the email you used when creating your GitHub account + ```sh + git config --global user.email + ``` + + +## 3️ Generate an SSH key +1. Generate an SSH key to connect your system to your GitHub account if you do not already have one. + ```sh + ssh-keygen -t ed25519 + ``` + - When it asks for the file location, press enter to save it to the default location (`~/.ssh`). + - Hit enter when it asks for the password to not save a password or enter one if you think you can remember it. +2. Copy the generated ssh key + ```sh + cat ~/.ssh/id_ed25519.pub + ``` + + +## 4 Add the SSH key to GitHub +1. Return to GitHub and open your [settings](https://github.com/settings/) by clicking on your icon then ⚙️ `settings` +2. Scroll to 🔑 `SSH and GPG keys` + + Tabs + +4. Click the New SSH Key button located in the top right corner. +1. Choose a name for the key (something such that you'll remember what computer/system it was for) +2. Paste the key from step 2 into the `Key` box +3. Save the key by clicking Add SSH Key + + +## 5️ Clone the repository to your system +1. Return to your terminal and navigate using `cd` to where you would like this repo's contents to live with your file system. +2. Clone the repo and its sub modules. + ```sh + git clone git@github.com:CabrilloRoboticsClub/cabrillo_rov_2023.git + cd ~/cabrillo_rov_2023 + git submodule init + git submodule update + ``` +3. To confirm the clone was successful list your files with `ls`. You should see the name of the cloned repo in your current directory. + + +# Development using git + +## 0️ Sync and pull the changes +1. Next navigate to the repo on your system +2. Enter the command `git pull` to pull the changes on GitHub onto your device + ```sh + git pull origin main + ``` + +## 1️ Make a branch +1. Pull the meta data from the remote repo to update the remote branches + ```sh + git fetch + ``` +2. Create a branch. + ```sh + git checkout -b branch_name + ``` + +## 2️ Add and commit your changes +Once you make some changes you would like to be documented you need to `commit` them. Committing changes is how you can mark versions of your code you would like to be tracked. It is a good idea to commit changes after you add/remove a feature that way there is a record of your changes. +1. Add all files you wish to commit with `git add`. All files you all will be committed under the same commit + ``` + git add my_file.py + ``` +1. To commit changes you use the `git commit` command. The parts of the command are as follows: + - `git`: Denotes we are using a git command + - `commit`: The name of the command is commit, this is what we would like to do + - `-m`: This is a flag that says we would like to add a commit message + - `"Message here`: Between quotes state what changes you are committing + + All together the git commit command syntax looks like this: + ```sh + git commit -m "Message here" + ``` + If you want to write a longer commit message use the `-v` flag. This will open a CLI editor. + ```sh + git commit -v + ``` +2. You will receive a short message summarizing the changes + +
+ +## 3️ Push your changes +Once you have finished a coding session it is a good idea to `push` your commits. The `push` command is basically the opposite of `pull`. `push` takes the changes (commits) you made on your local system and sends them to GitHub. +1. Enter the command `git push origin branch_name` to push the changes from your system to GitHub where `branch_name` is the name of the branch you are on + ``` + git commit origin branch_name + ``` +2. You can confirm this worked by heading to Github and seeing the changes reflected on your repo page. + +## 4️ Create a pull request +When you think your code is ready to merge into the main Cabrillo Robotics Code create a pull request. +1. Go to the pull requests page on GitHub and click on new pull request. +2. Select your branch as the branch to compare to. +3. Add a description of what changes you made and why. + +# What are Git and GitHub +## Recording +*Click on the image to open the [video](https://youtu.be/hzFErKeImTs)* +[![Watch the video](img/what_are_git_and_github_yt.png)](https://youtu.be/Opt-DSF9d_Y?si=3k5_N0q704sF5LPl "Tiny Hawk: What are Git and GitHub") diff --git a/doc/hardware_notes.md b/doc/hardware_notes.md deleted file mode 100644 index 5b6b29ed..00000000 --- a/doc/hardware_notes.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Hardware Notes - -## i2c Addresses - -```console -ubuntu@SeaHawk-ROV:~$ i2cdetect -y 1 - 0 1 2 3 4 5 6 7 8 9 a b c d e f -00: -- -- -- -- -- -- -- -- -10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -40: 40 41 -- -- -- -- -- -- -- -- 4a -- -- -- -- -- -50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -60: 60 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -70: 70 -- -- -- -- -- 76 77 -``` - -* Sensors - - * BNO085 (default) - * 0x4a - - * BNO085 (Pin DI High) - * 0x4b - - * BME280 (unbridged) - * 0x77 - - * BME280 (bridged) - * 0x76 - -* PCA9685 PWM Drivers - - Note that address 0x70 is the "all call" address for the controller chip on the HAT. All boards will respond to address 0x70 - regardless of the address jumper settings. - - * Servo Driver Hat - * 0x40 - - * Motor Driver Hat - * 0x60 - - * Servo Driver (A0 Bridged) - * 0x41 diff --git a/doc/img/CRC_logo_orange.svg b/doc/img/CRC_logo_orange.svg new file mode 100644 index 00000000..4a697df9 --- /dev/null +++ b/doc/img/CRC_logo_orange.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/img/add_ssh.png b/doc/img/add_ssh.png new file mode 100644 index 00000000..16099b09 Binary files /dev/null and b/doc/img/add_ssh.png differ diff --git a/doc/img/controller_map.png b/doc/img/controller_map.png new file mode 100644 index 00000000..adf88f04 Binary files /dev/null and b/doc/img/controller_map.png differ diff --git a/doc/img/github_settings_menu.png b/doc/img/github_settings_menu.png new file mode 100644 index 00000000..3bb74ec9 Binary files /dev/null and b/doc/img/github_settings_menu.png differ diff --git a/doc/img/new_pr.png b/doc/img/new_pr.png new file mode 100644 index 00000000..6cfe9ae4 Binary files /dev/null and b/doc/img/new_pr.png differ diff --git a/doc/img/new_ssh.png b/doc/img/new_ssh.png new file mode 100644 index 00000000..531fba65 Binary files /dev/null and b/doc/img/new_ssh.png differ diff --git a/doc/img/what_are_git_and_github_yt.png b/doc/img/what_are_git_and_github_yt.png new file mode 100644 index 00000000..d4d1d299 Binary files /dev/null and b/doc/img/what_are_git_and_github_yt.png differ diff --git a/doc/params.md b/doc/params.md index d18b1753..13b4ae94 100644 --- a/doc/params.md +++ b/doc/params.md @@ -6,7 +6,7 @@ *The client node is the node which makes a request to update another node's parameters* 1. Import the `SetRemoteParams` class to any node on the deck with the following syntax. The `SetRemoteParams` class from [`set_remote_params.py`](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/src/seahawk/seahawk_deck/set_remote_params.py) provides functionality for nodes to modify each other's [ROS parameters](https://docs.ros.org/en/humble/Concepts/Basic/About-Parameters.html) using [services](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Services/Understanding-ROS2-Services.html). The `SetRemoteParams` class streamlines setting another node's parameters to a user-friendly abstraction to reduce redundancy, creating cleaner code and increased ease-of-use. ```py - ffrom seahawk_deck.set_remote_params import SetRemoteParams + from seahawk_deck.set_remote_params import SetRemoteParams ``` 2. Create an instance of the class in the `__init__()` function, and pass it `self` (the current node) and the name of the node of whose parameters shall be set. ```py diff --git a/doc/ros_bags.md b/doc/ros_bags.md new file mode 100644 index 00000000..454536f9 --- /dev/null +++ b/doc/ros_bags.md @@ -0,0 +1,26 @@ +# ROS Bags +ROS bags used to record and the replay messages sent over a topic. This can be useful for debugging behavior after it happens or for remote development. + +## Project ROS bags +| Content | Bag | Documentation | +| ----- | ------ | ----- | +| H264 recording | [h264_recording](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/tree/docs/bags/h264_recording) | [h264_recording.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/docs/bags/h264_recording/h264_recording.md) +| IMU recording | [imu_recording](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/tree/docs/bags/imu_recording) | None +| Joystick recording | [joy_recording](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/tree/docs/bags/joy_recording) | [joy_recording.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/docs/bags/h264_recording/h264_recording.md) + +## Creating a ROS bag +To create a ROS bag use `ros2 bag record`. Specify the name of the topic (`/topic`) to record and the destination of the recording (`bag_name`) as shown in the following command. +``` +ros2 bag record -o bag_name /topic +``` +**Example:** +```sh +ros2 bag record -o h264_recording /image_raw/h264 +``` +Kill the process with `CTRL-C` when completed. + +## Running a ROS bag +A ROS bag is played using `ros2 bag play`. +```sh +ros2 bag play bags/h264_recording +``` \ No newline at end of file diff --git a/doc/rosdep_notes.md b/doc/rosdep_notes.md index e0d074e8..6d3659e5 100644 --- a/doc/rosdep_notes.md +++ b/doc/rosdep_notes.md @@ -1,3 +1,4 @@ +*from 2023* # Miscellaneous Notes on the ROS Packaging Process ## Tools and Files diff --git a/doc/run.md b/doc/run.md new file mode 100644 index 00000000..d1b5925b --- /dev/null +++ b/doc/run.md @@ -0,0 +1,56 @@ +# Running the project +## 1 Make +The ROS nodes are built with the `colcon` program. A `makefile` is present so we do not have to remember those commands. This should be ran once per session developing in a separate terminal in the `cabrillo_rov_2023` directory. You will only need to rerun `make` during that session if you modify the launch/setup files. +```sh +make +``` +The build artifacts are in: + +- `build` +- `install` +- `log` + +Clean the build with: + +```sh +make clean +``` + +## 2 Source +1. Open a new terminal. +1. Source ROS. It is recommended to put this in your `.shell_name.rc` file so you do not need to run this every time you open a new terminal. + ```sh + source /opt/ros/humble/setup.shell_name + # Where shell_name is the name of your shell (zsh, bash, etc) + ``` +3. Source the local setup created by `make`. This should be ran for each new terminal in the `cabrillo_rov_2023` directory. + ```sh + source ./install/local_setup.shell_name + # Where shell_name is the name of your shell (zsh, bash, etc) + ``` + + +## 3 Launch Files +We've migrated all the launch files to their respective ROS packages. Launch only after completing the steps above in the the `cabrillo_rov_2023` directory. + +```sh +ros2 launch seahawk rov.launch.py +``` + +```sh +ros2 launch seahawk deck.launch.py +``` + +## 3 Running Individual Nodes +Nodes can be ran individually using the following syntax, where `pkg_name` is the name of the package (this will usually be `seahawk`) and `node_name` is the name of the node to run. Run nodes only only after completing the steps above in the the `cabrillo_rov_2023` directory. +```sh +ros2 run pkg_name node_name +``` + +**Example:** +```sh +ros2 run seahawk pilot_input +``` + +## 3 Run RViz +See [rviz.md](https://github.com/CabrilloRoboticsClub/cabrillo_rov_2023/blob/main/doc/rviz.md) \ No newline at end of file diff --git a/doc/setup_procedure.md b/doc/setup_procedure.md index e11f2507..ba42e368 100644 --- a/doc/setup_procedure.md +++ b/doc/setup_procedure.md @@ -1,3 +1,4 @@ +*from 2023* # Setup Procedure This is the procedure to use for our 5 minutes alloted setup time at the competition diff --git a/doc/shutdown-procedure.md b/doc/shutdown-procedure.md index 15683a97..994d4ee7 100644 --- a/doc/shutdown-procedure.md +++ b/doc/shutdown-procedure.md @@ -1,3 +1,4 @@ +*from 2023* # Shutdown Procedure This is the procedure for packing up from a product demo diff --git a/doc/guidelines/style_guide_python.md b/doc/style_guide_python.md similarity index 100% rename from doc/guidelines/style_guide_python.md rename to doc/style_guide_python.md