New format of documentation

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: check-added-large-files
         # mesh files has to be taken into account
-        args: ["--maxkb=3000"]
+        args: ["--maxkb=3500"]
       - id: check-ast
       - id: check-json
         # vscode .json files do not follow the standard JSON format

panther_battery/README.md

@@ -1,56 +1,46 @@
-[//]: # (ROS_API_PACKAGE_START)
-[//]: # (ROS_API_PACKAGE_NAME_START)
-
 # panther_battery
 
-[//]: # (ROS_API_PACKAGE_NAME_END)
-[//]: # (ROS_API_PACKAGE_DESCRIPTION_START)
+The package containing nodes monitoring and publishing the internal battery state of the Husarion Panther robot.
 
-Package containing nodes monitoring and publishing the internal battery state of the Husarion Panther robot.
+## Launch Files
 
-[//]: # (ROS_API_PACKAGE_DESCRIPTION_END)
+This package contains:
 
-## ROS Nodes
+- [`battery.launch.py`](#batterylaunchpy---arguments) - is responsible for activating battery node, which dealing with reading and publishing battery data.
+
+### battery.launch.py - Arguments
 
-[//]: # (ROS_API_NODE_START)
-[//]: # (ROS_API_NODE_COMPATIBLE_1_0)
-[//]: # (ROS_API_NODE_COMPATIBLE_1_2)
-[//]: # (ROS_API_NODE_NAME_START)
+| Argument    | Description <br/> ***Type:*** `Default`                                         |
+| ----------- | ------------------------------------------------------------------------------- |
+| `namespace` | Add namespace to all launched nodes. <br/> ***string:*** `env(ROBOT_NAMESPACE)` |
 
-### battery_driver
+### battery.launch.py - Nodes
 
-[//]: # (ROS_API_NODE_NAME_END)
-[//]: # (ROS_API_NODE_DESCRIPTION_START)
+| Node name            | *Type*                             |
+| ---------------- | ---------------------------------- |
+| `battery_driver` | [*panther_batter/battery_node*](.) |
 
-Publishes battery state read from ADC unit for Panther version 1.2 and above, or based on Roboteq motor controllers' data for earlier versions of the robot.
+## ROS Nodes
 
-[//]: # (ROS_API_NODE_DESCRIPTION_END)
+- `battery_node`: Publishes battery state read from ADC unit for Panther version 1.2 and above, or based on Roboteq motor controllers' data for earlier versions of the robot.
 
-#### Publishes
+### battery_node
 
-[//]: # (ROS_API_NODE_PUBLISHERS_START)
+#### Publishes
 
 - `_battery/battery_1_status_raw` [*sensor_msgs/BatteryState*]: first battery raw state.
 - `_battery/battery_2_status_raw` [*sensor_msgs/BatteryState*]: second battery raw state. Published if second battery detected.
 - `battery/battery_status` [*sensor_msgs/BatteryState*]: mean values of both batteries if Panther has two batteries. Otherwise, the state of the single battery will be published.
 - `battery/charging_status` [*panther_msgs/ChargingStatus*]: battery charging status.
 - `diagnostics` [*diagnostic_msgs/DiagnosticArray*]: battery diagnostic messages.
 
-[//]: # (ROS_API_NODE_PUBLISHERS_END)
-
 #### Subscribes
 
-[//]: # (ROS_API_NODE_SUBSCRIBERS_START)
-
 - `hardware/io_state` [*panther_msgs/IOState*]: current state of IO.
 - `hardware/motor_controllers_state` [*panther_msgs/DriverState*]: current motor controllers' state and error flags. Subscribed if using Roboteq motor controllers data.
 
-[//]: # (ROS_API_NODE_SUBSCRIBERS_END)
-
 #### Parameters
 
-[//]: # (ROS_API_NODE_PARAMETERS_START)
-
 - `~/adc/device0` [*string*, default: **/dev/adc0**]: ADC nr 0 IIO device. Used with Panther version 1.2 and above.
 - `~/adc/device1` [*string*, default: **/dev/adc1**]: ADC nr 1 IIO device. Used with Panther version 1.2 and above.
 - `~/adc/path` [*string*, default: **/sys/bus/iio/devices/**]: path of ADC devices mount.
@@ -60,6 +50,3 @@ Publishes battery state read from ADC unit for Panther version 1.2 and above, or
 - `~/ma_window_len/voltage` [*int*, default: **10**]: window length of a moving average, used to smooth out battery voltage readings.
 - `~/ma_window_len/current` [*int*, default: **10**]: window length of a moving average, used to smooth out battery current readings.
 - `~/roboteq/driver_state_timeout` [*float*, default: **0.2**]: specifies timeout in seconds after which driver state messages will be considered old. Used with Panther version 1.06 and earlier.
-
-[//]: # (ROS_API_NODE_PARAMETERS_END)
-[//]: # (ROS_API_NODE_END)

panther_bringup/CMakeLists.txt

@@ -3,6 +3,6 @@ project(panther_bringup)
 
 find_package(ament_cmake REQUIRED)
 
-install(DIRECTORY launch config DESTINATION share/${PROJECT_NAME})
+install(DIRECTORY launch DESTINATION share/${PROJECT_NAME})
 
 ament_package()

panther_controller/CONFIGURATION.md

@@ -0,0 +1,9 @@
+# panther_controller
+
+## Changing Velocity Smoothing Parameters
+
+The Panther use [diff_drive_controller](https://control.ros.org/master/doc/ros2_controllers/diff_drive_controller/doc/userdoc.html) from [ros2 control](https://control.ros.org/master/index.html). This controller can be customized, among others: by modifying the robot's dynamic parameters (e.g. smooth the speed or limit the robot's speed and acceleration). Its parameters can be found in the [panther_controller](https://github.com/husarion/panther_ros/tree/ros2-devel/panther_controller/config). By default, these values correspond to the upper limits of the robot's velocities and accelerations.
+
+## Changing Wheel Type
+
+Changing wheel types is possible and can be done for both the real robot and the simulation. By default, three types of wheels are supported using the launch argument `wheel_type`. If you want to use custom wheels, all you need to do is point to the new wheel and controller configuration files using the `wheel_config_path` and `controller_config_path` parameters. These files should be based on the default files, i.e. [WH01_controller.yaml](./config/WH01_controller.yaml) and [WH01.yaml](../panther_description/config/WH01.yaml).

panther_controller/README.md

@@ -1,122 +1,68 @@
-[//]: # (ROS_API_PACKAGE_START)
-[//]: # (ROS_API_PACKAGE_NAME_START)
-
 # panther_controller
 
-[//]: # (ROS_API_PACKAGE_NAME_END)
-[//]: # (ROS_API_PACKAGE_DESCRIPTION_START)
-
 The package contains the default configuration and launch files necessary to start all the basic functionalities of the Husarion Panther robot.
 
-[//]: # (ROS_API_PACKAGE_DESCRIPTION_END)
-
-## Default Nodes Launched
+## Launch Files
 
-- `ros2_control_node` [*[controller_manager/controller_manager](https://github.com/ros-controls/ros2_control/blob/master/controller_manager)*]: Controller Manager performs two main functions. First, it manages controllers and their required interfaces, handling tasks like loading, activating, deactivating, and unloading. Second, it interacts with hardware components, ensuring access to their interfaces. For more information, refer to  [controller_manager](https://control.ros.org/master/doc/ros2_control/controller_manager/doc/userdoc.html). This node manages the following controllers:
-  - `imu_broadcaster` [*[imu_sensor_broadcaster/imu_sensor_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/imu_sensor_broadcaster)*]: The broadcaster to publish readings of IMU sensors.
-  - `joint_state_broadcaster` [*[joint_state_broadcaster/joint_state_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/joint_state_broadcaster)*]: The broadcaster reads all state interfaces and reports them on specific topics.
-  - `drive_controller` [*[diff_drive_controller/diff_drive_controller](https://github.com/ros-controls/ros2_controllers/tree/master/diff_drive_controller)* ]: Controller which manages mobile robots with a differential drive. It converts velocity commands for the robot body into wheel commands for the base. It also calculates odometry from hardware feedback and shares it.
-- `robot_state_publisher` [*[robot_state_publisher/robot_state_publisher](https://github.com/ros/robot_state_publisher)*]: The Robot State Publisher broadcasts a robot's state to tf2 using a provided URDF model and joint states. It updates the model and broadcasts poses for fixed and movable joints to tf2 topics.
+- [`controller.launch.py`](#controllerlaunchpy---arguments) - establishes communication with the hardware by loading the robot's URDF with plugins and configures the controllers to exchange information between the engine driver and the IMU.
 
-[//]: # (ROS_API_PACKAGE_START)
-[//]: # (ROS_API_PACKAGE_NAME_START)
+### controller.launch.py - Arguments
 
-## External ROS Nodes
+| Argument                 | Description <br/> ***Type:*** `Default`                                                                                                                                                                                                                                                                                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `battery_config_path`    | Path to the Ignition LinearBatteryPlugin configuration file. This configuration is intended for use in simulations only. <br/> ***string:*** `''`                                                                                                                                                                                                              |
+| `components_config_path` | Additional components configuration file. Components described in this file are dynamically included in Panther's urdf. Panther options are described [here](https://husarion.com/manuals/panther/panther-options/). <br/> ***string:*** [`components.yaml`](../panther_description/config/components.yaml)                                                    |
+| `controller_config_path` | Path to controller configuration file. <br/> ***string:*** [`{wheel_type}_controller.yaml`](../panther_controller/config/)                                                     |
+| `namespace`              | Add namespace to all launched nodes. <br/> ***string:*** `env(ROBOT_NAMESPACE)`                                                                                                                                                                                                                                                                                |
+| `publish_robot_state`    | Whether to publish the default Panther robot description.  <br/>  ***bool:*** `True` (choices: `True`, `False`)                                                                                                                                                                                                                                                |
+| `use_sim`                | Whether simulation is used.  <br/>  ***bool:*** `False` (choices: `True`, `False`)                                                                                                                                                                                                                                                                             |
+| `wheel_config_path`      | Path to wheel configuration file.   <br/>  ***string:*** [`{wheel_type}.yaml`](../panther_description/config)                                                                                   |
+| `wheel_type`             | Type of wheel. If you choose a value from the preset options ('WH01', 'WH02', 'WH04'), you can ignore the 'wheel_config_path' and 'controller_config_path' parameters. For custom wheels, please define these parameters to point to files that accurately describe the custom wheels. <br/>  ***string:*** `WH01` (choices: `WH01`, `WH02`, `WH04`, `custom`) |
 
-[//]: # (ROS_API_PACKAGE_NAME_END)
+### controller.launch.py - Nodes
 
-[//]: # (ROS_API_NODE_START)
+| Node name                 | *Type*                                                                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ros2_control_node`       | *[controller_manager/controller_manager](https://github.com/ros-controls/ros2_control/blob/master/controller_manager)*                    |
+| `imu_broadcaster`         | *[imu_sensor_broadcaster/imu_sensor_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/imu_sensor_broadcaster)*    |
+| `joint_state_broadcaster` | *[joint_state_broadcaster/joint_state_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/joint_state_broadcaster)* |
+| `drive_controller`        | *[diff_drive_controller/diff_drive_controller](https://github.com/ros-controls/ros2_controllers/tree/master/diff_drive_controller)*       |
+| `robot_state_publisher`   | *[robot_state_publisher/robot_state_publisher](https://github.com/ros/robot_state_publisher)*                                             |
 
-[//]: # (ROS_API_NODE_COMPATIBLE_1_0)
-[//]: # (ROS_API_NODE_COMPATIBLE_1_2)
+## ROS Nodes
 
-[//]: # (ROS_API_NODE_NAME_START)
+- `ros2_control_node`: Controller Manager performs two main functions. First, it manages controllers and their required interfaces, handling tasks like loading, activating, deactivating, and unloading. Second, it interacts with hardware components, ensuring access to their interfaces. For more information, refer to  [controller_manager](https://control.ros.org/master/doc/ros2_control/controller_manager/doc/userdoc.html). This node manages the following controllers:
+  - `imu_broadcaster`: The broadcaster to publish readings of IMU sensors.
+  - `joint_state_broadcaster`: The broadcaster reads all state interfaces and reports them on specific topics.
+  - `drive_controller`: Controller which manages mobile robots with a differential drive. It converts velocity commands for the robot body into wheel commands for the base. It also calculates odometry from hardware feedback and shares it.
+- `robot_state_publisher`: The Robot State Publisher broadcasts a robot's state to tf2 using a provided URDF model and joint states. It updates the model and broadcasts poses for fixed and movable joints to tf2 topics.
 
 ### imu_broadcaster
 
-[//]: # (ROS_API_NODE_NAME_END)
-
-[//]: # (ROS_API_NODE_DESCRIPTION_START)
-
-External node type:*[imu_sensor_broadcaster/imu_sensor_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/imu_sensor_broadcaster)*.
-
-The broadcaster to publish readings of IMU sensors.
-
-[//]: # (ROS_API_NODE_DESCRIPTION_END)
-
 #### Publishers
 
-[//]: # (ROS_API_NODE_PUBLISHERS_START)
-
 - `imu/data` [*sensor_msgs/msg/Imu*]: data from IMU sensor.
 
-[//]: # (ROS_API_NODE_PUBLISHERS_END)
-[//]: # (ROS_API_NODE_END)
-
-[//]: # (ROS_API_NODE_START)
-
-[//]: # (ROS_API_NODE_COMPATIBLE_1_0)
-[//]: # (ROS_API_NODE_COMPATIBLE_1_2)
-
-[//]: # (ROS_API_NODE_NAME_START)
-
 ### joint_state_broadcaster
 
-[//]: # (ROS_API_NODE_NAME_END)
-
-[//]: # (ROS_API_NODE_DESCRIPTION_START)
-
-External node type:*[joint_state_broadcaster/joint_state_broadcaster](https://github.com/ros-controls/ros2_controllers/tree/master/joint_state_broadcaster)*.
-
-The broadcaster reads all state interfaces and reports them on specific topics.
-
-[//]: # (ROS_API_NODE_DESCRIPTION_END)
-
 #### Publishers
 
-[//]: # (ROS_API_NODE_PUBLISHERS_START)
-
 - `dynamic_joint_states` [*control_msgs/msg/DynamicJointState*] - provides information about the state of various movable joints in a robotic system.
 - `joint_states` [*sensor_msgs/msg/JointState*] - provides information about the state of various joints in a robotic system.
 
-[//]: # (ROS_API_NODE_PUBLISHERS_END)
-[//]: # (ROS_API_NODE_END)
-
-[//]: # (ROS_API_NODE_START)
-
-[//]: # (ROS_API_NODE_COMPATIBLE_1_0)
-[//]: # (ROS_API_NODE_COMPATIBLE_1_2)
-
-[//]: # (ROS_API_NODE_NAME_START)
-
 ### drive_controller
 
-[//]: # (ROS_API_NODE_NAME_END)
-
-[//]: # (ROS_API_NODE_DESCRIPTION_START)
-
-External node type:*[diff_drive_controller/diff_drive_controller](https://github.com/ros-controls/ros2_controllers/tree/master/diff_drive_controller)*.
-
-Controller which manages mobile robots with a differential drive. It converts velocity commands for the robot body into wheel commands for the base. It also calculates odometry from hardware feedback and shares it.
-
-[//]: # (ROS_API_NODE_DESCRIPTION_END)
-
 #### Subscribers
 
-[//]: # (ROS_API_NODE_SUBSCRIBERS_START)
-
 - `cmd_vel` [*geometry_msgs/msg/Twist*]: command linear and angular velocity values.
 
-[//]: # (ROS_API_NODE_SUBSCRIBERS_END)
-
 #### Publishers
 
-[//]: # (ROS_API_NODE_PUBLISHERS_START)
-
 - `/tf` [*tf2_msgs/msg/TFMessage*]: tf tree. Published only if `enable_odom_tf=true`
 - `odometry/wheels` [*nav_msgs/msg/Odometry*]: odometry data from wheel encoders.
 
-[//]: # (ROS_API_NODE_PUBLISHERS_END)
-[//]: # (ROS_API_NODE_END)
+### robot_state_publisher
+
+#### Publishers
 
-[//]: # (ROS_API_PACKAGE_END)
+- `/robot_description` [*std_msgs/msg/String*]: contains information about robot description from URDF file.

panther_controller/launch/controller.launch.py

@@ -73,7 +73,7 @@ def generate_launch_description():
         ),
         description=(
             "Path to controller configuration file. By default, it is located in"
-            " 'panther_controller/config/<wheel_type arg>_controller.yaml'. You can also specify"
+            " 'panther_controller/config/{wheel_type}_controller.yaml'. You can also specify"
             " the path to your custom controller configuration file here. "
         ),
     )
@@ -115,7 +115,7 @@ def generate_launch_description():
         ),
         description=(
             "Path to wheel configuration file. By default, it is located in "
-            "'panther_description/config/<wheel_type arg>.yaml'. You can also specify the path "
+            "'panther_description/config/{wheel_type}.yaml'. You can also specify the path "
             "to your custom wheel configuration file here. "
         ),
     )