aaron/rover-ros2
1
0
Fork 0
mirror of https://github.com/SHC-ASTRA/rover-ros2.git synced 2026-02-11 09:20:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README with new template

Browse Source
This commit is contained in:
David
2025-11-04 01:12:45 -06:00
parent 3ebd2e29a3
commit 0fa2226529
1 changed files with 110 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
README.md
View File

@@ -1,120 +1,148 @@
# ASTRA Rover ROS2 Nodes # ASTRA Rover ROS2 Packages
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
## About Includes all main ROS2 packages for the rover. These are centrally located for modular rover operation.
Includes all ROS2 packages for the rover. These are centrally located for modular rover operation. You will use these packages to launch all rover-side ROS2 nodes.
You will use this package to launch all module-side ROS2 nodes. ## Table of Contents
# Table of Contents - [Software Prerequisites](#software-prerequisites)
- [Nix](#nix)
- [ROS2 Humble + rosdep](#ros2-humble--rosdep)
- [Running](#running)
- [Testing Serial](#testing-serial)
- [Connecting the GuliKit Controller](#connecting-the-gulikit-controller)
- [Common Problems/Toubleshooting](#common-problemstroubleshooting)
- [Packages](#packages)
- [Maintainers](#maintainers)
1. Title ## Software Prerequisites
3. Table of Contents
3. Software Requirements
1. ROS2 Humble
2. IP Configuration
4. Hardware Requirements
5. Recommended Programs
6. How to Use
7. Common Problems/Troubleshooting
8. Major To-Do Items
9. Author(s)
10. Maintainer(s)
# Software Requirements You need either [ROS2 Humble](https://docs.ros.org/en/humble/index.html)
with [rosdep](https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html#rosdep-installation)
or [Nix](https://nixos.org/download/#nix-install-linux) installed. We recommend
using Nix.
Since July/August of 2025, ASTRA uses NixOS. A functioning NixOS installation is assumed. ### Nix
## ROS2 Humble With Nix, all you have to do is enter the development shell:
We use [ROS2 Humble](https://docs.ros.org/en/humble/index.html), and plan on using that until support for it expires.
To install ROS2, run the following command in your /etc/nixos folder:
```nix
nix flake init --template github:lopsided98/nix-ros-overlay
```
After you install ROS2, you can install all dependencies needed by this repository by running the following commands:
```bash ```bash
$ sudo rosdep init # only run once $ cd path/to/rover-ros2
$ nix develop
```
### ROS2 Humble + rosdep
With ROS2 Humble, start by using rosdep to install dependencies:
```bash
# Setup rosdep
$ sudo rosdep init # only run if you haven't already
$ rosdep update $ rosdep update
$ rosdep install --from-path . --ignore-src -y # Install dependencies
$ cd path/to/rover-ros2
$ rosdep install --from-paths src -y --ignore-src
``` ```
## IP Configuration ## Running
- IP Address: 192.168.1.x
- This can be just about anything not already in use. I recommend something 30-39
- Net Mask: 255.255.255.0
- Gateway: 192.168.1.0
# Hardware Requirements
- A functioning computer.
# Recommended Programs
## VSCode
VSCode is a wonderful program. I used it to make this project and recommend anyone else working on it use it as well.
To install VSCode, add the following package to your pkgs array / packages.nix config file:
```nix
vscode-fhs
```
Alternatively, use a flake to install home-manager, and add to your home.nix:
```nix
vscode.enable = true;
```
# How to Use
```bash ```bash
$ colcon build $ colcon build
$ source install/setup.bash $ source install/setup.bash
# main launch files: # main launch files:
$ ros2 launch anchor_pkg rover.launch.py $ ros2 launch anchor_pkg rover.launch.py # Must be run on a computer connected to a MCU on the rover.
$ ros2 run headless_pkg headless_full $ ros2 run headless_pkg headless_full # Optionally run in a separate shell on the same or different computer.
``` ```
## Testing Serial ### Testing Serial
You can fake the presence of a Serial device (i.e., MCU) by using the following command: You can fake the presence of a Serial device (i.e., MCU) by using the following command:
```bash ```bash
socat -dd -v pty,rawer,crnl,link=/tmp/ttyACM9 pty,rawer,crnl,link=/tmp/ttyOUT $ socat -dd -v pty,rawer,crnl,link=/tmp/ttyACM9 pty,rawer,crnl,link=/tmp/ttyOUT
``` ```
## Connecting the GuliKit Controller When you go to run anchor, use the `PORT_OVERRIDE` environment variable to point it to the fake serial port, like so:
Connecting the GuliKit Controller (Recommended) ```bash
$ PORT_OVERRIDE=/tmp/ttyACM9 ros2 launch anchor_pkg rover.launch.py
```
* Connect controller to pc with USB-C ### Connecting the GuliKit Controller
These instructions apply to the black XBox-style GuliKit controller, primarily used for controlling Arm through Basestation.
* Connect the controller to your PC with a USB-C cable
* Select the "X-Input" control mode (Windows logo) on the controller. * Select the "X-Input" control mode (Windows logo) on the controller.
* Hold the button next to the symbols (windows, android, switch, etc...) * Hold the button next to the symbols (windows, android, switch, etc...)
* You'll need to release the button and press down again to cycle to the next mode * You'll need to release the button and press down again to cycle to the next mode
# Common Problems/Troubleshooting ## Common Problems/Troubleshooting
- TBD
# Major To-Do Items **Q**: When I try to launch the nodes, I receive a `package '' not found` error.
- TBD A: Make sure you have sourced the workspace in the current shell:
# Author(s) ```bash
$ source install/setup.bash # or setup.zsh if using ZSH
```
|Name| Email | **Q**: When I try to launch the nodes, I receive several `FileNotFoundError: [Errno 2]` errors.
|--|--|
| Tristan McGinnis | tlm |
| David Sharpe | ds0196@uah.edu |
# Maintainer(s) A: Sometimes the install files get messed up by running `colcon build` in different shells or updating packages. Try running the following commands to clean up your local build files:
|Name| Email | ```bash
|--|--| $ rm -rf build/ install/
| David Sharpe | ds0196@uah.edu | $ colcon build
| Riley McClain | email | ```
**Q**: When I run `colcon build` after the above suggestion, I receive several of the following errors:
```bash
[0.557s] WARNING:colcon.colcon_ros.prefix_path.ament:The path '' in the environment variable AMENT_PREFIX_PATH doesn't exist
```
A: Don't worry about it. If you had the workspace sourced, ROS2 will complain about the workspace install files not existing anymore after you deleted them. They will be re-created by `colcon build`, after which you can run `source install/setup.bash` to source the new install files.
**Q**: When I try to launch Anchor, I receive the following errors:
```bash
[anchor-5] [INFO] [1762239452.937881841] [anchor]: Unable to find MCU...
...
[ERROR] [anchor-5]: process has died [pid 101820, exit code 1, cmd '.../rover-ros2/install/anchor_pkg/lib/anchor_pkg/anchor --ros-args -r __node:=anchor --params-file /tmp/launch_params_nmv6tpw4'].
[INFO] [launch]: process[anchor-5] was required: shutting down launched system
[INFO] [bio-4]: sending signal 'SIGINT' to process[bio-4]
[INFO] [ptz-3]: sending signal 'SIGINT' to process[ptz-3]
[INFO] [core-2]: sending signal 'SIGINT' to process[core-2]
[INFO] [arm-1]: sending signal 'SIGINT' to process[arm-1]
...
```
A: To find a microcontroller to talk to, Anchor sends a ping to every Serial port on your computer. If it does not receive a 'pong' in less than one second, then it aborts. There are a few possible fixes:
- Keep trying to run it until it works
- Run `lsusb` to see if the microcontroller is detected by your computer.
- Run `ls /dev/tty*0` to see if there is a valid Serial port enumerated for the microcontroller.
- Check if you are in the `dialout` group (or whatever group shows up by running `ls -l /dev/tty*`).
## Packages
- [anchor\_pkg](./src/anchor_pkg) - Handles Serial communication between the various other packages here and the microcontroller.
- [arm\_pkg](./src/arm_pkg) - Relays controls and sensor data for the arm (socket and digit) between anchor and basestation/headless.
- [astra\_descriptions](./src/astra_descriptions) - Submodule with URDF-related packages.
- [bio\_pkg](./src/bio_pkg) - Like arm_pkg, but for CITADEL and FAERIE
- [core\_pkg](./src/core_pkg) - Like arm_pkg, but for Core
- [headless\_pkg](./src/headless_pkg) - Simple, non-graphical controller node to work in place of basestation when controlling the rover by itself. This is autostarted with anchor to allow for setup-less control of the rover.
- [latency\_tester](./src/latency_tester) - A temporary node to test comms latency over ROS2, Serial, and CAN.
- [ros2\_interfaces\_pkg](./src/ros2_interfaces_pkg) - Contains custom message types for communication between basestation and the rover over ROS2. (being renamed to `astra_msgs`).
- [servo\_arm\_twist\_pkg](./src/servo_arm_twist_pkg) - A temporary node to translate controller state from `ros2_joy` to `Twist` messages to control the Arm via IK.
## Maintainers
| Name | Email | Discord |
| ---- | ----- | ------- |
| David Sharpe | <ds0196@uah.edu> | `@ddavdd` |
| Riley McLain | <rjm0037@uah.edu> | `@ryleu` |