Refactor docs

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 <kbd>ctrl</kbd> + <kbd>o</kbd> and then <kbd>ctrl</kbd> + <kbd>x</kbd> 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 /<namespace>/cmd_vel
+```
 
-#### Publishes
+Additionally, you can check the link status by echoing the `/link_status` topic:
+```bash
+ros2 topic echo /<namespace>/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
+> ```

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.

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