From 9cd94f4627ff9cbe9320dd931f17ec2ece447e7b Mon Sep 17 00:00:00 2001 From: Milosz Lagan Date: Thu, 9 Jan 2025 09:55:26 +0000 Subject: [PATCH] Refactor docs --- README.md | 171 +++++++++++++++++++++++++++++++++++++++++++-------- ROS_API.md | 57 +++++++++++++++++ compose.yaml | 3 +- 3 files changed, 203 insertions(+), 28 deletions(-) create mode 100644 ROS_API.md diff --git a/README.md b/README.md index 6b69f1f..de6097f 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,161 @@ # husarion_ugv_crsf_teleop +## Getting started + This ROS 2 package allows you to control robots using a CRSF compatible remote control. A receiver should be connected to the robot's computer via USB-UART converter or be integrated as a hardware USB dongle. The CRSF protocol parser is implemented based on the following [specification](https://github.com/crsf-wg/crsf/wiki). -## Launch Files +To run the RadioMaster TX16S, you must meet certain requirements listed below: + +### Software + +- [**Docker Engine and Docker Compose**](https://docs.docker.com/engine/install/). +- Device with Linux based OS (e.g. robot, laptop) and [ROS 2 Humble](https://docs.ros.org/en/humble/Installation.html) installed. + +### Hardware + +- Hardware receiver dongle (ELRS receiver with an integrated USB to UART converter) connected to a USB port of the User Computer. + +## Demo + +[husarion_ugv_crsf_teleop](https://github.com/husarion/husarion_ugv_crsf_teleop) package creates a ROS 2 node, allowing control of the ROS-powered mobile and manipulation robots with a CRSF compatible RC remote such as RadioMaster TX16S. `crsf_teleop` node converts received CRSF packets from the receiver dongle to `geometry_msgs/Twist` message type in order to provide velocity commands for the robot. + +The result of this demo will be the publication of a velocity messages on the ROS topic `/cmd_vel`. An example with a mobile robot will be described below. + +### Start guide + +#### 1. Setup udev rules + +> [!WARNING] Husarion OS +> If you are using Husarion OS, you can skip this step as the udev rules are already set up. + +To be able to distinguish between connected devices it is necessary to add a rule that aliases detected hardware dongle to a known symlink file. + +Open (or create) the udev rules file: + +```bash +sudo nano /etc/udev/rules.d/99-local.rules +``` + +Append the following line to the file: + +```udev +ACTION=="add", ,ATTRS{interface}=="PAD02 Dongle", SYMLINK+="ttyUSBPAD" +``` + +Press ctrl + o and then ctrl + x to save and quit. + +Reload rules by executing: + +```bash +sudo udevadm control --reload-rules +sudo udevadm trigger +``` + +#### 2. Test receiver dongle + +Connect receiver dongle to the USB port of your robot. You can verify that the device is detected by typing: + +```bash +ls /dev | grep "ttyUSBPAD" +``` + +You should see a file named `ttyUSBPAD` in the output. + +#### 3. Get a Docker Compose file from the repository + +```bash +curl -O https://raw.githubusercontent.com/husarion/husarion_ugv_crsf_teleop/refs/heads/master/compose.yaml +``` + +#### 4. (Optional) Edit Parameters File + +> [!NOTE] +> When using default settings there is no need to add or edit parameters file as the model of your Husarion robot is deduced automatically from environment variables. + +If you want to change the default parameters, you can do so by providing a parameters file. Detailed information about the parameters can be found in the ROS API. + +Get a reference file from the repository for Panther: + +```bash +curl -o params.yaml https://raw.githubusercontent.com/husarion/husarion_ugv_crsf_teleop/refs/heads/master/husarion_ugv_crsf_teleop/config/crsf_teleop_panther.yaml +``` + +Or for Lynx: + +```bash +curl -o params.yaml https://raw.githubusercontent.com/husarion/husarion_ugv_crsf_teleop/refs/heads/master/husarion_ugv_crsf_teleop/config/crsf_teleop_lynx.yaml +``` + +In the `compose.yaml` file, pass `params.yaml` under `volumes` section: + +```yaml + volumes: + - /dev:/dev + - ./params.yaml:/params.yaml +``` + +And add parameter file as launch argument: + +```yaml + command: ros2 launch husarion_ugv_crsf_teleop crsf_teleop.launch.py params_file:=/params.yaml +``` + +#### 5. Start Docker service + +```bash +docker compose up -d +``` + +You can view the logs of the running container by typing: + +```bash +docker compose logs -f +``` -- `teleop.launch.py`: Launches crsf_teleop_node node. Automatically respawns node if it exits. Node's namespace can be set using the `namespace` launch argument. Custom parameters file can be provided by setting the `params_file` launch argument. +After a successful connection to the RC remote, you should see the following message: -## Configuration Files +```ros +[panther.crsf_teleop]: Connected +[panther.crsf_teleop]: Link quality restored: 100% +``` -- [`crsf_teleop_panther.yaml`](./husarion_ugv_crsf_teleop/config/crsf_teleop_panther.yaml): Sets default Panther robot parameter values for the crsf_teleop_node when `teleop.launch.py` is launched. -- [`crsf_teleop_lynx.yaml`](./husarion_ugv_crsf_teleop/config/crsf_teleop_lynx.yaml): Sets default Lynx robot parameter values for the crsf_teleop_node when `teleop.launch.py` is launched. +### Result -## ROS Nodes +Now you should see the relevant ROS 2 topic: -### crsf_teleop_node +```bash +user@hostname:~$ ros2 topic list +/panther/cmd_vel +/panther/link_status +/parameter_events +/rosout +``` -Translates received CRSF commands to velocity commands for the robot. +Tilting sticks on the RC controller should result in `/cmd_vel` topic being updated with velocity commands. Namespace fields should be updated with used robot model name (e.g. `panther`). -The following channels are used for controlling the robot via the TX16S remote control: -- Channel 2 - Right gimbal up/down - forward/backward velocity -- Channel 4 - Left gimbal left/right - turning (angular) velocity -- Channel 5 - SF switch - emergency stop -- Channel 7 - SA switch (down position) - silence `cmd_vel` messages, allows other nodes to control the robot while enabling e_stop functionality -- Channel 11 - SG switch - tristate switch, selects robot speed +```bash +ros2 topic echo //cmd_vel +``` -#### Publishes +Additionally, you can check the link status by echoing the `/link_status` topic: +```bash +ros2 topic echo //link_status +``` -- `cmd_vel` [*geometry_msgs/Twist*]: Publishes velocity commands to the robot. -- `link_status` [*panther_crsf_teleop_msgs/LinkStatus*]: Describes radio link status between the remote control and the robot. Parameters are described in the [CRSF_FRAMETYPE_LINK_STATISTICS frame documentation](https://github.com/crsf-wg/crsf/wiki/CRSF_FRAMETYPE_LINK_STATISTICS). +Sticks are mapped to the following axes: -#### Service Clients +- Left stick horizontal: angular velocity +- Right stick vertical: linear velocity -- `hardware/e_stop_trigger` [*std_srvs/Trigger*]: Triggers an emergency stop. -- `hardware/e_stop_reset` [*std_srvs/Trigger*]: Triggers an emergency stop reset. +RC controller has some additional buttons that can be used for different functionalities: -#### Parameters +- SG switch - tri-state switch, selects robot speed from values specified in the parameters yaml file (slow, normal, fast) +- SF switch - emergency stop +- SA switch (down position) - silence `cmd_vel` messages, allows other nodes to control the robot while enabling e_stop functionality -- `serial_port` [*string*, default: **/dev/ttyUSB0**]: Serial port to which the CRSF receiver is connected. -- `baudrate` [*int*, default: **576000**]: Baudrate of the serial port. -- `e_stop_republish` [*bool*, default: **False**]: Rebroadcasts asserted emergency stop signal once per second. Will override other emergency stop sources. -- `enable_cmd_vel_silence_switch`[*bool*, default: **False**]: Enables remote to disable publishing `cmd_vel` messages on demand. Can be used as a remote emergency stop when using other nodes to control the robot. -- `linear_speed_presets` [*double_array*, default: **[0.5, 1.0, 2.0]**]: Selectable robot maximum linear speed for `cmd_vel` topic. -- `angular_speed_presets` [*double_array*, default: **[0.5, 1.0, 2.0]**]: Selectable robot maximum angular speed for the `cmd_vel` topic. +> [!WARNING] SF switch +> By default the SA switch has no functionality assigned. You can enable silence mode by adding the following line to the custom `params.yaml` file: +> +> ```yaml +> silence_cmd_vel: true +> ``` diff --git a/ROS_API.md b/ROS_API.md new file mode 100644 index 0000000..8862325 --- /dev/null +++ b/ROS_API.md @@ -0,0 +1,57 @@ +# ROS 2 API + +## `husarion_ugv_crsf_interfaces` + +Contains custom message definitions for the `husarion_ugv_crsf_teleop` node. Currently, it only contains the `LinkStatus` message. + +## `husarion_ugv_crsf_teleop` + +Main package for the CRSF teleoperation node. Allows for controlling the robot using a RadioMaster TX16S remote control. + +### Launch Files + +- `teleop.launch.py`: Launches crsf_teleop_node node. Automatically respawns node if it exits. Node's namespace can be set using the `namespace` launch argument. Custom parameters file can be provided by setting the `params_file` launch argument. + +#### Parameters + +- `namespace` [*string*, default: **""**]: Namespace for the node. +- `params_file` [*string*, default: **"config/crsf_teleop_${ROBOT_MODEL}.yaml"**]: Path to the `crsf_teleop_node` parameters file. +- `robot_model` [*string*, default: **"${ROBOT_MODEL_NAME}"**]: Husarion robot model. If not provided, the model is deduced from the environment variables. Available options are **panther** and **lynx**. + +### Configuration Files + +- [`crsf_teleop_panther.yaml`](./husarion_ugv_crsf_teleop/config/crsf_teleop_panther.yaml): Sets default Panther robot parameter values for the crsf_teleop_node when `teleop.launch.py` is launched. +- [`crsf_teleop_lynx.yaml`](./husarion_ugv_crsf_teleop/config/crsf_teleop_lynx.yaml): Sets default Lynx robot parameter values for the crsf_teleop_node when `teleop.launch.py` is launched. + +### ROS Nodes + +#### crsf_teleop_node + +Translates received CRSF commands to velocity commands for the robot. + +The following channels are used for controlling the robot via the TX16S remote control: + +- Channel 2 - Right gimbal up/down - forward/backward velocity +- Channel 4 - Left gimbal left/right - turning (angular) velocity +- Channel 5 - SF switch - emergency stop +- Channel 7 - SA switch (down position) - silence `cmd_vel` messages, allows other nodes to control the robot while enabling e_stop functionality +- Channel 11 - SG switch - tristate switch, selects robot speed + +##### Publishes + +- `cmd_vel` [*geometry_msgs/Twist*]: Publishes velocity commands to the robot. +- `link_status` [*panther_crsf_teleop_msgs/LinkStatus*]: Describes radio link status between the remote control and the robot. Parameters are described in the [CRSF_FRAMETYPE_LINK_STATISTICS frame documentation](https://github.com/crsf-wg/crsf/wiki/CRSF_FRAMETYPE_LINK_STATISTICS). + +##### Service Clients + +- `hardware/e_stop_trigger` [*std_srvs/Trigger*]: Triggers an emergency stop. +- `hardware/e_stop_reset` [*std_srvs/Trigger*]: Triggers an emergency stop reset. + +##### Parameters + +- `serial_port` [*string*, default: **/dev/ttyUSB0**]: Serial port to which the CRSF receiver is connected. +- `baudrate` [*int*, default: **576000**]: Baudrate of the serial port. +- `e_stop_republish` [*bool*, default: **False**]: Rebroadcasts asserted emergency stop signal once per second. Will override other emergency stop sources. +- `enable_cmd_vel_silence_switch`[*bool*, default: **False**]: Enables remote to disable publishing `cmd_vel` messages on demand. Can be used as a remote emergency stop when using other nodes to control the robot. +- `linear_speed_presets` [*double_array*, default: **[0.5, 1.0, 2.0]**]: Selectable robot maximum linear speed for `cmd_vel` topic. +- `angular_speed_presets` [*double_array*, default: **[0.5, 1.0, 2.0]**]: Selectable robot maximum angular speed for the `cmd_vel` topic. diff --git a/compose.yaml b/compose.yaml index 3434121..34dac32 100644 --- a/compose.yaml +++ b/compose.yaml @@ -10,7 +10,8 @@ services: - RMW_IMPLEMENTATION=${RMW_IMPLEMENTATION:-rmw_cyclonedds_cpp} - ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-0} - ROBOT_MODEL_NAME=${ROBOT_MODEL_NAME:-panther} + - ROBOT_NAMESPACE=${ROBOT_NAMESPACE:-panther} volumes: - /dev:/dev command: > - ros2 launch husarion_ugv_crsf_teleop teleop.launch.py namespace:=panther + ros2 launch husarion_ugv_crsf_teleop teleop.launch.py