diff --git a/README.md b/README.md index 5a75cc7..eff7747 100644 --- a/README.md +++ b/README.md @@ -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) -## 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 -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 Prerequisites -# 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 - -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: +With Nix, all you have to do is enter the development shell: ```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 install --from-path . --ignore-src -y + # Install dependencies +$ cd path/to/rover-ros2 +$ rosdep install --from-paths src -y --ignore-src ``` -## IP Configuration - -- 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 +## Running ```bash $ colcon build $ source install/setup.bash # main launch files: -$ ros2 launch anchor_pkg rover.launch.py -$ ros2 run headless_pkg headless_full +$ 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 # 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: ```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. -* 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 + * 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 -# Common Problems/Troubleshooting - -- TBD +## Common Problems/Troubleshooting -# 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 | -|--|--| -| Tristan McGinnis | tlm | -| David Sharpe | ds0196@uah.edu | +**Q**: When I try to launch the nodes, I receive several `FileNotFoundError: [Errno 2]` errors. -# 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 | -|--|--| -| David Sharpe | ds0196@uah.edu | -| Riley McClain | email | +```bash +$ rm -rf build/ install/ +$ colcon build +``` + +**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 | | `@ddavdd` | +| Riley McLain | | `@ryleu` |