diff --git a/docs/assets/airframes/rover/high_level_structure.png b/docs/assets/airframes/rover/high_level_structure.png new file mode 100644 index 0000000000..4a9dd2b2d3 Binary files /dev/null and b/docs/assets/airframes/rover/high_level_structure.png differ diff --git a/docs/assets/config/rover/rover_position_controller.png b/docs/assets/config/rover/rover_position_controller.png index bbf1cfa98d..4fcf84af63 100644 Binary files a/docs/assets/config/rover/rover_position_controller.png and b/docs/assets/config/rover/rover_position_controller.png differ diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 23aa661d41..f5f55b0e51 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -422,6 +422,7 @@ - [Hiwonder Tracked Chassi](complete_vehicles_rover/hiwonder_tracked.md) - [Hiwonder Mecanum Chassi](complete_vehicles_rover/hiwonder_mecanum.md) - [Aion Robotics R1 (Discontinued)](complete_vehicles_rover/aion_r1.md) + - [Developer Guide](frames_rover/developer_guide.md) - [Submarines (experimental)](frames_sub/index.md) - [BlueROV2](frames_sub/bluerov2.md) - [Airframes Reference](airframes/airframe_reference.md) diff --git a/docs/en/frames_rover/developer_guide.md b/docs/en/frames_rover/developer_guide.md new file mode 100644 index 0000000000..02b25daa2b --- /dev/null +++ b/docs/en/frames_rover/developer_guide.md @@ -0,0 +1,69 @@ +# Developer Guide + +This developer guide aims to provide information on the structure and design philosophy of the rover modules to kick-start your development. +The guide is structured into the following sections: +- [Developer Guide](#developer-guide) + - [Module Structure](#module-structure) + - [Control Structure](#control-structure) + - [High Level Structure](#high-level-structure) + - [Code Structure](#code-structure) + - [Testing in Simulation](#testing-in-simulation) + - [Contributing](#contributing) + +## Module Structure +The rover modules are structured with a focus on modularity and clearly defined interfaces. This allows a developer to work on a specific area or add a new feature without having to worry about the rest of the codebase. +In the following we will elaborate on this structure on different levels: + +### Control Structure +The rover modules use a hierarchical structure in which sepoints can be injected at various level through rover specific uORB messages: + +![Control Structure](../../assets/middleware/ros2/px4_ros2_interface_lib/rover_control_structure.svg) + +The individual controllers (indicated with green boxes) will subscribe to the setpoint coming from the controller one level above and publish a setpoint to the lower level (setpoints indicated with blue boxes). +The strucutre leads to a cascaded PID controller: + +![Rover Position Controller](../../assets/config/rover/rover_position_controller.png) + +This cascaded structure is highly modular, we only run the loops that are required to control the highest level setpoint that is provided. + +### High Level Structure +Putting the control structure into context of the setpoint generation gives us the full picture of the rover module including its external interfaces: + +![High Level Structure](../../assets/airframes/rover/high_level_structure.png) + +Important to note, is that the highest setpoint that is provided to the control structure will cause the lower setpoints to be overriden by the controllers. +The highest level setpoint is either provided by PX4 if the vehicle is in a PX4 internal drive mode or injected through the API (DDS Bridge). + +### Code Structure + +The bulk of the rover related code is located in [src/modules](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules). Each rover type has its own subfolder i.e. [src/modules/rover_ackermann](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/rover_ackermann). +Inside the subfolder you will find the following structure exemplified with the ackermann rover module (some files are excluded here): + +| Folder or File Names | Purpose | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| RoverAckermann.hpp/cpp | Entry Point for the rover module. Responsible for configuring the module, generating Setpoints if the vehicle is in a PX4 internal drive mode and calling the individual controllers. | +| module.yaml | Definition of parameters specific to the rover type. | +| AckermannDriveModes | Contains implementations of the PX4 internal drive modes. | +| AckermannPosControl | Position Controller: Turns position setpoints into speed and attitude setpoints. | +| AckermannSpeedControl | Speed Controller: Turns speed sepoints into throttle setpoints. | +| AckermannAttControl | Attitude Controller: Turns attitude setpoints into rate setpoints. | +| AckermannRateControl | Rate Controller: Turns rate setpoints into normalized steering setpoints. | +| AckermannActControl | Actuator Controller: Turns normalized steering/throttle setpoints into actuator setpoints. | + +Additionally, there is a [src/lib/rover_control](https://github.com/PX4/PX4-Autopilot/tree/main/src/lib/rover_control) library that includes functions and parameter definitions that are shared among the rover modules. + +## Testing in Simulation + +PX4 provides synthetic simulation models for [Gazebo](../sim_gazebo_gz/index.md) of all three rover types to test the software and validate changes and new features: + +- [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) +- [Mecanum rover](../sim_gazebo_gz/vehicles.md#mecanum-rover) + +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) + +## Contributing +When adding new features it is important to maintain the interfaces of the [High Level Structure](#high-level-structure). +Before opening a PR test your features/improvements in simulation and ideally also on hardware. +In your PR you should include a concise description of your changes and ideally provide logs, screenshots or videos of your code in action. + diff --git a/docs/en/frames_rover/index.md b/docs/en/frames_rover/index.md index 3a76f3177b..baac305cf0 100644 --- a/docs/en/frames_rover/index.md +++ b/docs/en/frames_rover/index.md @@ -5,6 +5,7 @@ :::warning Support for rover is [experimental](../airframes/index.md#experimental-vehicles). Maintainer volunteers, [contribution](../contribute/index.md) of new features, new frame configurations, or other improvements would all be very welcome! +Check the [Rover Developer Guide](../frames_rover/developer_guide.md) to kick-start your development! ::: ![Rovers](../../assets/airframes/rover/hiwonder_rovers/hiwonder_rovers.png) @@ -61,13 +62,4 @@ Each wheel is driven by its own motor, and by controlling the speed and directio - [Configuration/Tuning](../config_rover/index.md) - [Apps & API](../flight_modes_rover/api.md) - [Complete Vehicles](../complete_vehicles_rover/index.md) - -## Simulation - -PX4 provides synthetic simulation models for [Gazebo](../sim_gazebo_gz/index.md) of all three rover types to test the software and validate changes and new features: - -- [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -- [Mecanum rover](../sim_gazebo_gz/vehicles.md#mecanum-rover) - -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) +- [Developer Guide](../frames_rover/developer_guide.md)