diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index ca350f182a..7c40adb54a 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -456,6 +456,7 @@ - [Vehicles](sim_gazebo_gz/vehicles.md) - [Advanced Lift Drag Tool](sim_gazebo_gz/tools_avl_automation.md) - [Worlds](sim_gazebo_gz/worlds.md) + - [Plugins](sim_gazebo_gz/plugins.md) - [Gazebo Models Repository](sim_gazebo_gz/gazebo_models.md) - [Multi-Vehicle Sim](sim_gazebo_gz/multi_vehicle_simulation.md) - [Gazebo Classic Simulation](sim_gazebo_classic/index.md) diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md index f1629f15d9..16955fac10 100644 --- a/docs/en/_sidebar.md +++ b/docs/en/_sidebar.md @@ -457,6 +457,7 @@ - [Vehicles](/sim_gazebo_gz/vehicles.md) - [Advanced Lift Drag Tool](/sim_gazebo_gz/tools_avl_automation.md) - [Worlds](/sim_gazebo_gz/worlds.md) + - [Plugins](/sim_gazebo_gz/plugins.md) - [Gazebo Models Repository](/sim_gazebo_gz/gazebo_models.md) - [Multi-Vehicle Sim](/sim_gazebo_gz/multi_vehicle_simulation.md) - [Gazebo Classic Simulation](/sim_gazebo_classic/index.md) diff --git a/docs/en/sim_gazebo_gz/index.md b/docs/en/sim_gazebo_gz/index.md index bac64b0c9d..f4df3ea569 100644 --- a/docs/en/sim_gazebo_gz/index.md +++ b/docs/en/sim_gazebo_gz/index.md @@ -392,6 +392,11 @@ As long as the world file and the model file are in the Gazebo search path (`GZ_ However, `make px4_sitl gz__` won't work with them. ::: +## Extending Gazebo with Plugins + +World, vehicle (model), and sensor behaviour can be customised using plugins. +For more information see [Gazebo Plugins](../sim_gazebo_gz/plugins.md). + ## Multi-Vehicle Simulation Multi-Vehicle simulation is supported on Linux hosts. diff --git a/docs/en/sim_gazebo_gz/plugins.md b/docs/en/sim_gazebo_gz/plugins.md new file mode 100644 index 0000000000..3e4ea51e1d --- /dev/null +++ b/docs/en/sim_gazebo_gz/plugins.md @@ -0,0 +1,91 @@ +# Gazebo Plugins + +Gazebo plugins extend the simulator with custom functionality not provided by default. They can be attached to different entity types and allow you to add new sensors, modify world physics, or interact with the simulation environment. + +## Plugin Types + +Plugins can be attached to these entity types: + +- **World** - Global simulation behavior +- **Model** - Specific model functionality +- **Sensor** - Custom sensor implementations +- **Actor** - Dynamic entity behavior + +## Supported Plugins + +PX4 currently supports these plugins: + +- [OpticalFlowSystem](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/gz_plugins/optical_flow): Provides optical flow sensor simulation using OpenCV-based flow calculation. +- [GstCameraSystem](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/gz_plugins/gstreamer): Streams camera feeds via UDP (RTP/H.264) or RTMP with optional NVIDIA CUDA hardware acceleration. +- [MovingPlatformController](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/gz_plugins/moving_platform_controller): Controls moving platforms (ships, trucks, etc.) for takeoff and landing scenarios. + Includes configurable velocity, heading, and random fluctuations. + +## Plugin Registration + +Plugins must be registered in the [server.config](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/simulation/gz_bridge/server.config) file to be available in your world: + +```xml + + + + + + + + + + +``` + +## Creating Custom Plugins + +When developing new plugins: + +1. **Follow the plugin architecture** - Implement desired interfaces. + + You can start by copying the [Template plugin](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/gz_plugins/template_plugin) which is a simple example that only implements `ISystemPreUpdate` and `ISystemPostUpdate`. + The interfaces are specified in the official [Gazebo documentation](https://gazebosim.org/api/sim/9/createsystemplugins.html). + +2. **Register your plugin** - Add it to [server.config](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/simulation/gz_bridge/server.config) for discovery. +3. **Use the custom namespace** - Follow the pattern `custom::YourPluginName`. + +### Example Plugin Structure + +```cpp +class YourCustomSystem : + public gz::sim::System, + public gz::sim::ISystemPreUpdate, + public gz::sim::ISystemPostUpdate +{ +public: + void PreUpdate(const gz::sim::UpdateInfo &_info, + gz::sim::EntityComponentManager &_ecm) final; + void PostUpdate(const gz::sim::UpdateInfo &_info, + const gz::sim::EntityComponentManager &_ecm) final; +}; + +// Plugin registration +GZ_ADD_PLUGIN(YourCustomSystem, gz::sim::System, + YourCustomSystem::ISystemPreUpdate, + YourCustomSystem::ISystemPostUpdate) +GZ_ADD_PLUGIN_ALIAS(YourCustomSystem, "custom::YourCustomSystem") +``` + +## Enabling a Plugin + +For world plugins all you need to do is [register the plugin](#plugin-registration) (add it to the `server.config`). +It will then be available to all worlds and vehicles. + +The process for adding vehicle model/sensor plugins is not documented. +This can tracked through [PX4-Autopilot#2493](https://github.com/PX4/PX4-Autopilot/issues/24939). + +## Resources + +- **PX4 Plugins**: [Repository source code](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/gz_plugins) +- **Official Gazebo Documentation**: [System Plugins Guide](https://gazebosim.org/api/sim/9/createsystemplugins.html) +- **Server Configuration**: [Configuration Reference](https://gazebosim.org/api/sim/9/server_config.html) +- **PX4 Gazebo-classic Plugins**: [PX4 Gazebo Classic Plugins](https://github.com/PX4/PX4-SITL_gazebo-classic/tree/main/src) + +::: info +Plugins for modern Gazebo are still evolving. The plugin system differs from Gazebo Classic. +:::