From 86f42f8245d8a17df8dc75c2c5fca1478ff86e88 Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Thu, 28 Sep 2023 22:18:26 -0500 Subject: [PATCH 01/16] Update changelog and prepare for pre2 release (#2178) Signed-off-by: Addisu Z. Taddese Signed-off-by: Mabel Zhang --- CMakeLists.txt | 2 +- Changelog.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index e28d8dece1..6e89b2226b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,7 +18,7 @@ find_package(gz-cmake3 REQUIRED) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) -gz_configure_project(VERSION_SUFFIX pre1) +gz_configure_project(VERSION_SUFFIX pre2) #============================================================================ # Set project-specific options diff --git a/Changelog.md b/Changelog.md index b48cf5b264..04597a8ffc 100644 --- a/Changelog.md +++ b/Changelog.md @@ -2,6 +2,133 @@ ### Gazebo Sim 8.X.X (20XX-XX-XX) +1. TouchPlugin: Reset the plugin with the initial values + * [Pull request #2132](https://github.com/gazebosim/gz-sim/pull/2132) + +1. Fix another deadlock in sensors system + * [Pull request #2141](https://github.com/gazebosim/gz-sim/pull/2141) + +1. Documentation fixes + * [Pull request #2157](https://github.com/gazebosim/gz-sim/pull/2157) + * [Pull request #2150](https://github.com/gazebosim/gz-sim/pull/2150) + * [Pull request #2148](https://github.com/gazebosim/gz-sim/pull/2148) + * [Pull request #2147](https://github.com/gazebosim/gz-sim/pull/2147) + * [Pull request #2143](https://github.com/gazebosim/gz-sim/pull/2143) + * [Pull request #2133](https://github.com/gazebosim/gz-sim/pull/2133) + * [Pull request #2130](https://github.com/gazebosim/gz-sim/pull/2130) + * [Pull request #2128](https://github.com/gazebosim/gz-sim/pull/2128) + * [Pull request #2124](https://github.com/gazebosim/gz-sim/pull/2124) + * [Pull request #2114](https://github.com/gazebosim/gz-sim/pull/2114) + * [Pull request #2107](https://github.com/gazebosim/gz-sim/pull/2107) + +1. Fix Examples + * [Pull request #2151](https://github.com/gazebosim/gz-sim/pull/2151) + * [Pull request #2149](https://github.com/gazebosim/gz-sim/pull/2149) + * [Pull request #2145](https://github.com/gazebosim/gz-sim/pull/2145) + * [Pull request #2144](https://github.com/gazebosim/gz-sim/pull/2144) + * [Pull request #2129](https://github.com/gazebosim/gz-sim/pull/2129) + * [Pull request #2127](https://github.com/gazebosim/gz-sim/pull/2127) + * [Pull request #2123](https://github.com/gazebosim/gz-sim/pull/2123) + * [Pull request #2122](https://github.com/gazebosim/gz-sim/pull/2122) + * [Pull request #2111](https://github.com/gazebosim/gz-sim/pull/2111) + +1. Load transform control and select entities plugins in thermal camera world + * [Pull request #2139](https://github.com/gazebosim/gz-sim/pull/2139) + +1. Fixed invalid service names + * [Pull request #2121](https://github.com/gazebosim/gz-sim/pull/2121) + +1. Add automatic moment of inertia calculation for meshes + * [Pull request #2171](https://github.com/gazebosim/gz-sim/pull/2171) + * [Pull request #2166](https://github.com/gazebosim/gz-sim/pull/2166) + * [Pull request #2119](https://github.com/gazebosim/gz-sim/pull/2119) + * [Pull request #2105](https://github.com/gazebosim/gz-sim/pull/2105) + * [Pull request #2061](https://github.com/gazebosim/gz-sim/pull/2061) + +1. ign -> gz + * [Pull request #2055](https://github.com/gazebosim/gz-sim/pull/2055) + +1. Adds python demo examples + * [Pull request #2044](https://github.com/gazebosim/gz-sim/pull/2044) + +1. Add support for writing systems in Python + * [Pull request #2081](https://github.com/gazebosim/gz-sim/pull/2081) + +1. Apply mimic constraint to joints (only Bullet-featherstone) + * [Pull request #1838](https://github.com/gazebosim/gz-sim/pull/1838) + +1. Fix rendering tests + * [Pull request #2086](https://github.com/gazebosim/gz-sim/pull/2086) + +1. Make systems and tests include headers they use + * [Pull request #2100](https://github.com/gazebosim/gz-sim/pull/2100) + +1. Adds Python bindings for the Actor, Joint, Light, Link, Model, Sensor, World convenience class + * [Pull request #2043](https://github.com/gazebosim/gz-sim/pull/2043) + * [Pull request #2042](https://github.com/gazebosim/gz-sim/pull/2042) + * [Pull request #2041](https://github.com/gazebosim/gz-sim/pull/2041) + * [Pull request #2040](https://github.com/gazebosim/gz-sim/pull/2040) + * [Pull request #2039](https://github.com/gazebosim/gz-sim/pull/2039) + * [Pull request #2036](https://github.com/gazebosim/gz-sim/pull/2036) + * [Pull request #2035](https://github.com/gazebosim/gz-sim/pull/2035) + +1. Add version number to gz.common python binding + * [Pull request #2093](https://github.com/gazebosim/gz-sim/pull/2093) + +1. Infrastructure + * [Pull request #2046](https://github.com/gazebosim/gz-sim/pull/2046) + +1. Bumps in harmonic : sdformat14, gz-physics6, gz-sensors8, gz-gui8, gz-rendering8, gz-transport13, gz-msgs10, gz-fuel-tools9 + * [Pull request #2062](https://github.com/gazebosim/gz-sim/pull/2062) + * [Pull request #1892](https://github.com/gazebosim/gz-sim/pull/1892) + * [Pull request #1837](https://github.com/gazebosim/gz-sim/pull/1837) + +1. Use new sky cubemap, instead of header + * [Pull request #2060](https://github.com/gazebosim/gz-sim/pull/2060) + +1. Remove deprecations and address some todos for Harmonic + * [Pull request #2054](https://github.com/gazebosim/gz-sim/pull/2054) + * [Pull request #2053](https://github.com/gazebosim/gz-sim/pull/2053) + +1. Use ogre2 in wide angle camera and lens flares worlds + * [Pull request #2063](https://github.com/gazebosim/gz-sim/pull/2063) + +1. Use new API for creating projector + * [Pull request #2064](https://github.com/gazebosim/gz-sim/pull/2064) + +1. Fix const-correctness of the `Model::JointByName` and `Model::LinkByName` APIs + * [Pull request #2059](https://github.com/gazebosim/gz-sim/pull/2059) + +1. Change type of `Component::typeName` and address outstanding todos + * [Pull request #2049](https://github.com/gazebosim/gz-sim/pull/2049) + +1. Add Lens Flare System + * [Pull request #1933](https://github.com/gazebosim/gz-sim/pull/1933) + +1. Fix TopicInfo deprecation warnings in Harmonic + * [Pull request #1922](https://github.com/gazebosim/gz-sim/pull/1922) + +1. Add DopplerVelocityLogSystem plugin + * [Pull request #1804](https://github.com/gazebosim/gz-sim/pull/1804) + +1. GUI for Global Illumination (VCT / CI VCT) + * [Pull request #1597](https://github.com/gazebosim/gz-sim/pull/1597) + +1. Add CLI to switch to Vulkan & Metal backends + * [Pull request #1735](https://github.com/gazebosim/gz-sim/pull/1735) + +1. Remove deprecations for main/gz-sim8 + * [Pull request #1783](https://github.com/gazebosim/gz-sim/pull/1783) + +1. Acoustic comms plugin + * [Pull request #1608](https://github.com/gazebosim/gz-sim/pull/1608) + +1. Set seed value using CLI + * [Pull request #1618](https://github.com/gazebosim/gz-sim/pull/1618) + +1. ⬆️ Bump main to 8.0.0~pre1 + * [Pull request #1640](https://github.com/gazebosim/gz-sim/pull/1640) + ## Gazebo Sim 7.x ### Gazebo Sim 7.6.0 (2023-09-26) From 8b9b3a2ca6e64da1b0d6f6dc1e147bb444659dd7 Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Fri, 29 Sep 2023 13:04:40 -0500 Subject: [PATCH 02/16] Prepare for 8.0.0 Release (#2181) Signed-off-by: Addisu Z. Taddese Signed-off-by: Mabel Zhang --- CMakeLists.txt | 2 +- Changelog.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6e89b2226b..8157799113 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,7 +18,7 @@ find_package(gz-cmake3 REQUIRED) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) -gz_configure_project(VERSION_SUFFIX pre2) +gz_configure_project(VERSION_SUFFIX) #============================================================================ # Set project-specific options diff --git a/Changelog.md b/Changelog.md index 04597a8ffc..4d7d22df7a 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,6 +1,6 @@ ## Gazebo Sim 8.x -### Gazebo Sim 8.X.X (20XX-XX-XX) +### Gazebo Sim 8.0.0 (2023-09-29) 1. TouchPlugin: Reset the plugin with the initial values * [Pull request #2132](https://github.com/gazebosim/gz-sim/pull/2132) From 5db2379773a234a9f5e408345f02ca31feca386e Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Mon, 2 Oct 2023 17:11:14 -0500 Subject: [PATCH 03/16] Remove direct dependency on libdart in CI (#2187) * Remove ci-focal Signed-off-by: Addisu Z. Taddese Signed-off-by: Mabel Zhang --- .github/ci-focal/before_cmake.sh | 8 -------- .github/ci/packages.apt | 5 ----- 2 files changed, 13 deletions(-) delete mode 100755 .github/ci-focal/before_cmake.sh diff --git a/.github/ci-focal/before_cmake.sh b/.github/ci-focal/before_cmake.sh deleted file mode 100755 index 363d1168b7..0000000000 --- a/.github/ci-focal/before_cmake.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/sh -l - -set -x - -# Needed on Focal to get dart6-data for tests -apt -y install software-properties-common -apt-add-repository ppa:dartsim/ppa -apt -y install dart6-data diff --git a/.github/ci/packages.apt b/.github/ci/packages.apt index 96a302fe1f..8c85a08a1b 100644 --- a/.github/ci/packages.apt +++ b/.github/ci/packages.apt @@ -1,10 +1,5 @@ freeglut3-dev libbenchmark-dev -libdart-collision-ode-dev -libdart-dev -libdart-external-ikfast-dev -libdart-external-odelcpsolver-dev -libdart-utils-urdf-dev libfreeimage-dev libglew-dev libgz-cmake3-dev From 1b7d9efb1bdfd663a37b7c13eb34e0eabf783882 Mon Sep 17 00:00:00 2001 From: Ian Chen Date: Thu, 5 Oct 2023 15:35:52 -0700 Subject: [PATCH 04/16] Support specifying the name of light associated with lens flares (#2172) --------- Signed-off-by: Ian Chen Signed-off-by: Mabel Zhang --- src/systems/lens_flare/LensFlare.cc | 18 +++++++++++++++++- src/systems/lens_flare/LensFlare.hh | 3 +++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/src/systems/lens_flare/LensFlare.cc b/src/systems/lens_flare/LensFlare.cc index 298ab75f1b..8f099d6653 100644 --- a/src/systems/lens_flare/LensFlare.cc +++ b/src/systems/lens_flare/LensFlare.cc @@ -122,6 +122,11 @@ void LensFlare::Configure( this->dataPtr->occlusionSteps = _sdf->Get("occlusion_steps"); } + if (_sdf->HasElement("light_name")) + { + this->dataPtr->lightName = _sdf->Get("light_name"); + } + // Get Camera Name this->dataPtr->cameraName = scopedName(this->dataPtr->entity, _ecm, "::", false); @@ -187,7 +192,18 @@ void LensFlarePrivate::OnPostRender() } // get light - auto light = this->scene->LightByIndex(0); + rendering::LightPtr light; + if (!this->lightName.empty()) + { + light = this->scene->LightByName(this->lightName); + } + else if (this->scene->LightCount() > 0) + { + light = this->scene->LightByIndex(0); + } + // Light not found. Keep trying in case it's not available in the world yet. + if (!light) + return; rendering::RenderEngine *engine = this->camera->Scene()->Engine(); rendering::RenderPassSystemPtr rpSystem = engine->RenderPassSystem(); diff --git a/src/systems/lens_flare/LensFlare.hh b/src/systems/lens_flare/LensFlare.hh index 1904c9b788..95ed7a07d4 100644 --- a/src/systems/lens_flare/LensFlare.hh +++ b/src/systems/lens_flare/LensFlare.hh @@ -46,6 +46,9 @@ namespace systems /// Sets the number of steps to take in /// each direction to check for occlusions. /// The default value is set to 10. Use 0 to disable + /// Sets the light associated with the lens flares. + /// If not specified. The first light in the scene will + /// be used. class LensFlare: public System, From 606efea48b03e2232e2b69ffb7092cfc636c83f5 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Sat, 14 Oct 2023 05:18:40 -0400 Subject: [PATCH 05/16] add components tutorial Signed-off-by: Mabel Zhang --- .../apply_joint_force/ApplyJointForce.cc | 20 +++++ test/integration/joint.cc | 2 +- tutorials.md.in | 1 + tutorials/component_jointforcecmd.md | 79 +++++++++++++++++++ tutorials/terminology.md | 2 +- tutorials/using_components.md | 69 ++++++++++++++++ 6 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 tutorials/component_jointforcecmd.md create mode 100644 tutorials/using_components.md diff --git a/src/systems/apply_joint_force/ApplyJointForce.cc b/src/systems/apply_joint_force/ApplyJointForce.cc index 4bd269d8ac..734eb22a61 100644 --- a/src/systems/apply_joint_force/ApplyJointForce.cc +++ b/src/systems/apply_joint_force/ApplyJointForce.cc @@ -42,20 +42,26 @@ class gz::sim::systems::ApplyJointForcePrivate /// \brief Gazebo communication node. public: transport::Node node; + //! [jointEntityDeclaration] /// \brief Joint Entity public: Entity jointEntity; + //! [jointEntityDeclaration] /// \brief Joint name public: std::string jointName; + //! [forceDeclaration] /// \brief Commanded joint force public: double jointForceCmd; + //! [forceDeclaration] /// \brief mutex to protect jointForceCmd public: std::mutex jointForceCmdMutex; + //! [modelDeclaration] /// \brief Model interface public: Model model{kNullEntity}; + //! [modelDeclaration] }; ////////////////////////////////////////////////// @@ -65,12 +71,14 @@ ApplyJointForce::ApplyJointForce() } ////////////////////////////////////////////////// +//! [Configure] void ApplyJointForce::Configure(const Entity &_entity, const std::shared_ptr &_sdf, EntityComponentManager &_ecm, EventManager &/*_eventMgr*/) { this->dataPtr->model = Model(_entity); + //! [Configure] if (!this->dataPtr->model.Valid(_ecm)) { @@ -96,17 +104,21 @@ void ApplyJointForce::Configure(const Entity &_entity, } // Subscribe to commands + //! [cmdTopic] auto topic = transport::TopicUtils::AsValidTopic("/model/" + this->dataPtr->model.Name(_ecm) + "/joint/" + this->dataPtr->jointName + "/cmd_force"); + //! [cmdTopic] if (topic.empty()) { gzerr << "Failed to create valid topic for [" << this->dataPtr->jointName << "]" << std::endl; return; } + //! [cmdSub] this->dataPtr->node.Subscribe(topic, &ApplyJointForcePrivate::OnCmdForce, this->dataPtr.get()); + //! [cmdSub] gzmsg << "ApplyJointForce subscribing to Double messages on [" << topic << "]" << std::endl; @@ -126,12 +138,14 @@ void ApplyJointForce::PreUpdate(const UpdateInfo &_info, << "s]. System may not work properly." << std::endl; } + //! [findJoint] // If the joint hasn't been identified yet, look for it if (this->dataPtr->jointEntity == kNullEntity) { this->dataPtr->jointEntity = this->dataPtr->model.JointByName(_ecm, this->dataPtr->jointName); } + //! [findJoint] if (this->dataPtr->jointEntity == kNullEntity) return; @@ -140,12 +154,15 @@ void ApplyJointForce::PreUpdate(const UpdateInfo &_info, if (_info.paused) return; + //! [jointForceComponent] // Update joint force auto force = _ecm.Component( this->dataPtr->jointEntity); + //! [jointForceComponent] std::lock_guard lock(this->dataPtr->jointForceCmdMutex); + //! [modifyComponent] if (force == nullptr) { _ecm.CreateComponent( @@ -156,14 +173,17 @@ void ApplyJointForce::PreUpdate(const UpdateInfo &_info, { force->Data()[0] += this->dataPtr->jointForceCmd; } + //! [modifyComponent] } ////////////////////////////////////////////////// +//! [setForce] void ApplyJointForcePrivate::OnCmdForce(const msgs::Double &_msg) { std::lock_guard lock(this->jointForceCmdMutex); this->jointForceCmd = _msg.data(); } +//! [setForce] GZ_ADD_PLUGIN(ApplyJointForce, System, diff --git a/test/integration/joint.cc b/test/integration/joint.cc index 12044025c6..423d9b6e4e 100644 --- a/test/integration/joint.cc +++ b/test/integration/joint.cc @@ -280,7 +280,7 @@ TEST_F(JointIntegrationTest, SetForce) std::vector forceCmd{10}; joint.SetForce(ecm, forceCmd); - // velocity cmd should exist + // force cmd should exist EXPECT_NE(nullptr, ecm.Component(eJoint)); EXPECT_EQ(forceCmd, ecm.Component(eJoint)->Data()); diff --git a/tutorials.md.in b/tutorials.md.in index 0c6f51aab3..a8a3d6431a 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -65,6 +65,7 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively. ## Developers * \subpage createsystemplugins "Create System Plugins": Programmatically access simulation using C++ plugins. +* \subpage usingcomponents "Using components": Using components in a system plugin. * \subpage rendering_plugins "Rendering plugins": Write plugins that use Gazebo Rendering on the server and client. * \subpage test_fixture "Test Fixture": Writing automated CI tests diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md new file mode 100644 index 0000000000..30de20ca22 --- /dev/null +++ b/tutorials/component_jointforcecmd.md @@ -0,0 +1,79 @@ +\page compjointforcecmd Case Study: Using the JointForceCmd Component + +We will show how to use one of the components, +\ref gz::sim::components::JointForceCmd, in a system. +This component allows us to set the force command on a joint. + +Programmatic usage of this component can be found in the source code for +systems and integration tests, such as the +[joint integration test](https://github.com/gazebosim/gz-sim/blob/gz-sim8/test/integration/joint.cc), +the \ref gz::sim::systems::ApplyJointForce system +([source code](https://github.com/gazebosim/gz-sim/tree/gz-sim8/src/systems/apply_joint_force)), +and others. + +The corresponding world SDF is [`apply_joint_force.sdf`](https://github.com/gazebosim/gz-sim/blob/gz-sim8/examples/worlds/apply_joint_force.sdf), which you can look at in Gazebo: +``` +gz sim apply_joint_force.sdf +``` + +We will walk through the relevant lines of source code in `ApplyJointForce` +that interact with `JointForceCmd`. + +### Find the entity of interest + +First, we will need access to an entity, the \ref gz::sim::Joint entity in this +case. It is declared as a member variable: + +\snippet src/systems/apply_joint_force/ApplyJointForce.cc jointEntityDeclaration + +An entity may have been created at the time the world is loaded, or you may +create an entity at runtime if it does not exist yet. +For joints, most likely they were defined in the SDF file that specifies the +world, and all we have to do at runtime is to look for the joint by its name. + +`ApplyJointForce` happens to be a system meant to be specified under `` +in the SDF, so at the time `Configure()` is called, it has access to a model +entity from which we can extract a \ref gz::sim::Model: + +\snippet src/systems/apply_joint_force/ApplyJointForce.cc modelDeclaration +\snippet src/systems/apply_joint_force/ApplyJointForce.cc Configure + +Using the Model object, we can find the joint by its name, when `PreUpdate()` +is called. +That gives us a Joint entity: + +\snippet src/systems/apply_joint_force/ApplyJointForce.cc findJoint + +### Modify the component + +Once we have the handle to an entity, we can modify components associated with +it. +A component may have been created at the time the world is loaded, or you may +create a component at runtime if it does not exist yet. + +In this case, we use the joint entity found above to look for and modify its +`JointForceCmd` component. +This will apply a force command to the joint. + +In `PreUpdate()`, look for the component: +\snippet src/systems/apply_joint_force/ApplyJointForce.cc jointForceComponent + +Create it if it does not exist yet, and modify it: +\snippet src/systems/apply_joint_force/ApplyJointForce.cc modifyComponent + +where the scalar joint force command is declared as a member variable: + +\snippet src/systems/apply_joint_force/ApplyJointForce.cc forceDeclaration + +and a callback function allows the user to specify a force on a topic: + +\snippet src/systems/apply_joint_force/ApplyJointForce.cc cmdTopic +\snippet src/systems/apply_joint_force/ApplyJointForce.cc cmdSub +\snippet src/systems/apply_joint_force/ApplyJointForce.cc setForce + +You can test this by issuing a force command to the topic: +``` +gz topic -t /model/joint_force_example/joint/j1/cmd_force \ + -m gz.msgs.Double -p 'data: 1.0' +``` +This should move the model that the joint is attached to. diff --git a/tutorials/terminology.md b/tutorials/terminology.md index 8b812fbf37..7103fee7ec 100644 --- a/tutorials/terminology.md +++ b/tutorials/terminology.md @@ -22,7 +22,7 @@ to developers touching the source code. can also create their own by inheriting from the \ref gz::sim::components::BaseComponent "BaseComponent" class or instantiating a template of - \ref gz::sim::components::Component "Component" + \ref gz::sim::components::Component "Component". * **System**: Logic that operates on all entities that have a given set of components. Systems are plugins that can be loaded at runtime. diff --git a/tutorials/using_components.md b/tutorials/using_components.md new file mode 100644 index 0000000000..b4cb1078ac --- /dev/null +++ b/tutorials/using_components.md @@ -0,0 +1,69 @@ +\page usingcomponents Using Components in a System Plugin + +Gazebo uses the entity component system (ECS) software architecture. +See the [Terminology](./terminology.html) page for the definitions of entity, +component, system, and entity component manager (ECM) used in this tutorial. +In short, a simulation world consists of many entities, each of which is +associated with a set of components. + +System plugins can modify the simulation world by manipulating components. +The basic structure of a system plugin is outlined in the +[tutorial on creating system plugins](./createsystemplugins.html). + +Here, we will explain how a system can use components to modify the world. +You can view the list of \ref gz::sim::components in the API. + +Programmatic usage of components can be found in +[built-in systems](https://github.com/gazebosim/gz-sim/tree/gz-sim8/src/systems) +and [integration tests](https://github.com/gazebosim/gz-sim/blob/gz-sim8/test/integration) +in the source code. +Most of the built-in systems have a corresponding example SDF world. +You can find all the example worlds [here](https://github.com/gazebosim/gz-sim/tree/gz-sim8/examples/worlds). + +## Prerequisites + +This is a tutorial for developers or advanced users. +It assumes that you are familiar with basic usage of Gazebo. + +Prior to starting this tutorial, these other tutorials will help with +understanding: +- [Terminology](./terminology.html) +- [Create system plugins](./createsystemplugins.html) + +## Resources + +Quick access to resources mentioned in this tutorial: +- List of \ref gz::sim::components in the API +- List of \ref gz::sim::systems in the API +- Source code of [built-in systems](https://github.com/gazebosim/gz-sim/tree/gz-sim8/src/systems) +- Source code of [example worlds](https://github.com/gazebosim/gz-sim/tree/gz-sim8/examples/worlds) +- Source code of [integration tests](https://github.com/gazebosim/gz-sim/blob/gz-sim8/test/integration) + +## Entity Component Manager (ECM) + +The gateway to interact with entities is through the +\ref gz::sim::EntityComponentManager +([source code](https://github.com/gazebosim/gz-sim/blob/gz-sim8/include/gz/sim/EntityComponentManager.hh)), +ECM for short. +The ECM gives us access to all the entities, each of which gives us access +to its associated components. + +An ECM object is passed into all of the interfaces in a system, including +`ISystemConfigure()` and `ISystem*Update()`. +The signatures of those interfaces are specified in +\ref gz/sim/System.hh and explained in the +[tutorial on creating system plugins](./createsystemplugins.html). +We will assume that these interfaces are implemented in functions called +`Configure()` and `*Update()` in a system. + +Note that because entities are created when the world is loaded, at the time +`Configure()` is called, it may be that not all entities have finished loading. +At the time `*Update()` is called, you are more likely to have all the +entities. + +## Case studies + +The rest of the tutorial is case studies that walk through the usage of +specific components. + +- \subpage compjointforcecmd "JointForceCmd" From 1b0caba00fe0032215772b8bbe7593ffa3dfba0e Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Wed, 18 Oct 2023 02:31:17 -0400 Subject: [PATCH 06/16] document component used Signed-off-by: Mabel Zhang --- src/systems/apply_joint_force/ApplyJointForce.hh | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/systems/apply_joint_force/ApplyJointForce.hh b/src/systems/apply_joint_force/ApplyJointForce.hh index 0c93a28c20..88ada1ec84 100644 --- a/src/systems/apply_joint_force/ApplyJointForce.hh +++ b/src/systems/apply_joint_force/ApplyJointForce.hh @@ -32,6 +32,14 @@ namespace systems class ApplyJointForcePrivate; /// \brief This system applies a force to the first axis of a specified joint. + /// + /// ## Components + /// + /// This system uses the following components: + /// + /// - gz::sim::components::JointForceCmd: A std::vector of force commands + /// of type `double`. Only element `[0]` is used, for applying force to + /// the specified joint. class ApplyJointForce : public System, public ISystemConfigure, From 139c68b035fc77e3369bc3202412c9a696fff57b Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Mon, 16 Oct 2023 23:15:57 -0400 Subject: [PATCH 07/16] Update tutorials/component_jointforcecmd.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alejandro Hernández Cordero Signed-off-by: Mabel Zhang Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index 30de20ca22..fd7305f087 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -12,9 +12,9 @@ the \ref gz::sim::systems::ApplyJointForce system and others. The corresponding world SDF is [`apply_joint_force.sdf`](https://github.com/gazebosim/gz-sim/blob/gz-sim8/examples/worlds/apply_joint_force.sdf), which you can look at in Gazebo: -``` + +```bash gz sim apply_joint_force.sdf -``` We will walk through the relevant lines of source code in `ApplyJointForce` that interact with `JointForceCmd`. From c4fab59997041b5715e7f8bfa95d74a21b34fe94 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Mon, 16 Oct 2023 23:16:25 -0400 Subject: [PATCH 08/16] Update tutorials/component_jointforcecmd.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alejandro Hernández Cordero Signed-off-by: Mabel Zhang Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index fd7305f087..15d6a3437c 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -72,7 +72,8 @@ and a callback function allows the user to specify a force on a topic: \snippet src/systems/apply_joint_force/ApplyJointForce.cc setForce You can test this by issuing a force command to the topic: -``` + +```bash gz topic -t /model/joint_force_example/joint/j1/cmd_force \ -m gz.msgs.Double -p 'data: 1.0' ``` From 3529da7601c1ac697c7460ab3a05b25c40fa9b29 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Mon, 16 Oct 2023 23:16:50 -0400 Subject: [PATCH 09/16] Update tutorials/component_jointforcecmd.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alejandro Hernández Cordero Signed-off-by: Mabel Zhang Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index 15d6a3437c..b1c4106f3b 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -59,6 +59,7 @@ In `PreUpdate()`, look for the component: \snippet src/systems/apply_joint_force/ApplyJointForce.cc jointForceComponent Create it if it does not exist yet, and modify it: + \snippet src/systems/apply_joint_force/ApplyJointForce.cc modifyComponent where the scalar joint force command is declared as a member variable: From 0ed09b8030a30447b66cb2b806b5cd3e85d4a23e Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Mon, 16 Oct 2023 23:16:56 -0400 Subject: [PATCH 10/16] Update tutorials/component_jointforcecmd.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alejandro Hernández Cordero Signed-off-by: Mabel Zhang Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index b1c4106f3b..a53c411755 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -56,6 +56,7 @@ In this case, we use the joint entity found above to look for and modify its This will apply a force command to the joint. In `PreUpdate()`, look for the component: + \snippet src/systems/apply_joint_force/ApplyJointForce.cc jointForceComponent Create it if it does not exist yet, and modify it: From 9d2aa1bd2d5fdae4b64833da31f4de2943cea87d Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Tue, 31 Oct 2023 17:50:23 -0400 Subject: [PATCH 11/16] missing quotes from auto commits Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index a53c411755..c7149a4460 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -15,6 +15,7 @@ The corresponding world SDF is [`apply_joint_force.sdf`](https://github.com/gaze ```bash gz sim apply_joint_force.sdf +``` We will walk through the relevant lines of source code in `ApplyJointForce` that interact with `JointForceCmd`. From 29fbb92c4836c4ebad46eb4fdb29605f7a71a6d0 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Tue, 31 Oct 2023 17:54:33 -0400 Subject: [PATCH 12/16] exclude comment lines from doxygen snippet Signed-off-by: Mabel Zhang --- src/systems/apply_joint_force/ApplyJointForce.cc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/systems/apply_joint_force/ApplyJointForce.cc b/src/systems/apply_joint_force/ApplyJointForce.cc index 734eb22a61..19add069df 100644 --- a/src/systems/apply_joint_force/ApplyJointForce.cc +++ b/src/systems/apply_joint_force/ApplyJointForce.cc @@ -42,24 +42,24 @@ class gz::sim::systems::ApplyJointForcePrivate /// \brief Gazebo communication node. public: transport::Node node; - //! [jointEntityDeclaration] /// \brief Joint Entity + //! [jointEntityDeclaration] public: Entity jointEntity; //! [jointEntityDeclaration] /// \brief Joint name public: std::string jointName; - //! [forceDeclaration] /// \brief Commanded joint force + //! [forceDeclaration] public: double jointForceCmd; //! [forceDeclaration] /// \brief mutex to protect jointForceCmd public: std::mutex jointForceCmdMutex; - //! [modelDeclaration] /// \brief Model interface + //! [modelDeclaration] public: Model model{kNullEntity}; //! [modelDeclaration] }; @@ -138,8 +138,8 @@ void ApplyJointForce::PreUpdate(const UpdateInfo &_info, << "s]. System may not work properly." << std::endl; } - //! [findJoint] // If the joint hasn't been identified yet, look for it + //! [findJoint] if (this->dataPtr->jointEntity == kNullEntity) { this->dataPtr->jointEntity = @@ -154,8 +154,8 @@ void ApplyJointForce::PreUpdate(const UpdateInfo &_info, if (_info.paused) return; - //! [jointForceComponent] // Update joint force + //! [jointForceComponent] auto force = _ecm.Component( this->dataPtr->jointEntity); //! [jointForceComponent] From f6668faab10d1769445cdfd33c86a58108a82a01 Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Mon, 16 Oct 2023 13:58:12 -0500 Subject: [PATCH 13/16] Fix custom_sensor_system example (#2208) Signed-off-by: Addisu Z. Taddese Signed-off-by: Mabel Zhang --- examples/plugin/custom_sensor_system/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/plugin/custom_sensor_system/CMakeLists.txt b/examples/plugin/custom_sensor_system/CMakeLists.txt index 66ceb25192..32bb92dac3 100644 --- a/examples/plugin/custom_sensor_system/CMakeLists.txt +++ b/examples/plugin/custom_sensor_system/CMakeLists.txt @@ -20,7 +20,7 @@ include(FetchContent) FetchContent_Declare( sensors_clone GIT_REPOSITORY https://github.com/gazebosim/gz-sensors - GIT_TAG main + GIT_TAG gz-sensors8 ) FetchContent_Populate(sensors_clone) add_subdirectory(${sensors_clone_SOURCE_DIR}/examples/custom_sensor ${sensors_clone_BINARY_DIR}) From 299cf2044e1976930ca0c7b6856f7384fe33658f Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Fri, 27 Oct 2023 23:36:10 -0400 Subject: [PATCH 14/16] Standardize Doxygen parameter formatting for systems A-N (#2183) Signed-off-by: Mabel Zhang --- .../ackermann_steering/AckermannSteering.hh | 72 ++++++++--------- src/systems/acoustic_comms/AcousticComms.hh | 2 + .../battery_plugin/LinearBatteryPlugin.hh | 27 ++++--- src/systems/breadcrumbs/Breadcrumbs.hh | 4 +- src/systems/buoyancy/Buoyancy.hh | 5 +- src/systems/buoyancy_engine/BuoyancyEngine.hh | 51 ++++++------ .../CameraVideoRecorder.hh | 28 ++++--- src/systems/comms_endpoint/CommsEndpoint.hh | 28 ++++--- .../detachable_joint/DetachableJoint.hh | 2 +- src/systems/diff_drive/DiffDrive.hh | 70 ++++++++-------- src/systems/elevator/Elevator.hh | 16 ++-- .../environment_preload/EnvironmentPreload.hh | 5 +- src/systems/follow_actor/FollowActor.hh | 23 +++--- src/systems/hydrodynamics/Hydrodynamics.hh | 2 +- .../joint_controller/JointController.hh | 54 +++++++------ .../JointPositionController.hh | 54 ++++++------- .../JointStatePublisher.hh | 7 +- .../JointTrajectoryController.hh | 24 +++--- .../KineticEnergyMonitor.hh | 10 +-- src/systems/lens_flare/LensFlare.hh | 27 ++++--- src/systems/lift_drag/LiftDrag.hh | 55 ++++++------- src/systems/log/LogPlayback.hh | 5 +- .../log_video_recorder/LogVideoRecorder.hh | 19 +++-- .../LogicalAudioSensorPlugin.hh | 2 + src/systems/mecanum_drive/MecanumDrive.hh | 33 ++++---- .../MulticopterVelocityControl.hh | 79 ++++++++++--------- src/systems/pose_publisher/PosePublisher.hh | 46 +++++------ src/systems/user_commands/UserCommands.hh | 26 +++--- 28 files changed, 399 insertions(+), 377 deletions(-) diff --git a/src/systems/ackermann_steering/AckermannSteering.hh b/src/systems/ackermann_steering/AckermannSteering.hh index f82e0cec20..3d829d8902 100644 --- a/src/systems/ackermann_steering/AckermannSteering.hh +++ b/src/systems/ackermann_steering/AckermannSteering.hh @@ -36,106 +36,106 @@ namespace systems /// \brief Ackermann steering controller which can be attached to a model /// with any number of left and right wheels. /// - /// # System Parameters + /// ## System Parameters /// - /// ``: Boolean used to only control the steering angle + /// - ``: Boolean used to only control the steering angle /// only. Calculates the angles of wheels from steering_limit, wheel_base, /// and wheel_separation. Uses gz::msg::Double on default topic name /// `/model/{name_of_model}/steer_angle`. Automatically set True when /// `` is True, uses defaults topic name "/actuators". /// - /// `` True to enable the use of actutor message + /// - `` True to enable the use of actutor message /// for steering angle command. Relies on `` for the /// index of the position actuator and defaults to topic "/actuators". /// - /// `` used with `` to set + /// - `` used with `` to set /// the index of the steering angle position actuator. /// - /// ``: Float used to control the steering angle P gain. + /// - ``: Float used to control the steering angle P gain. /// Only used for when in steering_only mode. /// - /// ``: Name of a joint that controls a left wheel. This + /// - ``: Name of a joint that controls a left wheel. This /// element can appear multiple times, and must appear at least once. /// - /// ``: Name of a joint that controls a right wheel. This + /// - ``: Name of a joint that controls a right wheel. This /// element can appear multiple times, and must appear at least once. /// - /// ``: Name of a joint that controls steering for - /// left wheel. This element must appear once. Vehicles that steer - /// rear wheels are not currently correctly supported. + /// - ``: Name of a joint that controls steering for + /// left wheel. This element must appear once. Vehicles that steer + /// rear wheels are not currently correctly supported. /// - /// ``: Name of a joint that controls steering for - /// right wheel. This element must appear once. + /// - ``: Name of a joint that controls steering for + /// right wheel. This element must appear once. /// - /// ``: Distance between wheels, in meters. This element + /// - ``: Distance between wheels, in meters. This element /// is optional, although it is recommended to be included with an /// appropriate value. The default value is 1.0m. /// - /// ``: Distance between wheel kingpins, in meters. This + /// - ``: Distance between wheel kingpins, in meters. This /// element is optional, although it is recommended to be included with an /// appropriate value. The default value is 0.8m. Generally a bit smaller /// than the wheel_separation. /// - /// ``: Distance between front and rear wheels, in meters. This + /// - ``: Distance between front and rear wheels, in meters. This /// element is optional, although it is recommended to be included with an /// appropriate value. The default value is 1.0m. /// - /// ``: Value to limit steering to. Can be calculated by + /// - ``: Value to limit steering to. Can be calculated by /// measuring the turning radius and wheel_base of the real vehicle. /// steering_limit = asin(wheel_base / turning_radius) /// The default value is 0.5 radians. /// - /// ``: Wheel radius in meters. This element is optional, + /// - ``: Wheel radius in meters. This element is optional, /// although it is recommended to be included with an appropriate value. The /// default value is 0.2m. /// - /// ``: Odometry publication frequency. This + /// - ``: Odometry publication frequency. This /// element is optional, and the default value is 50Hz. /// - /// ``: Minimum velocity [m/s], usually <= 0. - /// ``: Maximum velocity [m/s], usually >= 0. - /// ``: Minimum acceleration [m/s^2], usually <= 0. - /// ``: Maximum acceleration [m/s^2], usually >= 0. - /// ``: jerk [m/s^3], usually <= 0. - /// ``: jerk [m/s^3], usually >= 0. + /// - ``: Minimum velocity [m/s], usually <= 0. + /// - ``: Maximum velocity [m/s], usually >= 0. + /// - ``: Minimum acceleration [m/s^2], usually <= 0. + /// - ``: Maximum acceleration [m/s^2], usually >= 0. + /// - ``: jerk [m/s^3], usually <= 0. + /// - ``: jerk [m/s^3], usually >= 0. /// - /// ``: Custom topic that this system will subscribe to in order to + /// - ``: Custom topic that this system will subscribe to in order to /// receive command messages. This element is optional, and the /// default value is `/model/{name_of_model}/cmd_vel` or when steering_only /// is true `/model/{name_of_model}/steer_angle`. /// - /// ``: Custom sub_topic that this system will subscribe to in + /// - ``: Custom sub_topic that this system will subscribe to in /// order to receive command messages. This element is optional, and /// creates a topic `/model/{name_of_model}/{sub_topic}` /// - /// ``: Custom topic on which this system will publish odometry + /// - ``: Custom topic on which this system will publish odometry /// messages. This element if optional, and the default value is /// `/model/{name_of_model}/odometry`. /// - /// ``: Custom topic on which this system will publish the + /// - ``: Custom topic on which this system will publish the /// transform from `frame_id` to `child_frame_id`. This element is optional, /// and the default value is `/model/{name_of_model}/tf`. /// - /// ``: Custom `frame_id` field that this system will use as the + /// - ``: Custom `frame_id` field that this system will use as the /// origin of the odometry transform in both the `` /// `gz.msgs.Pose_V` message and the `` /// `gz.msgs.Odometry` message. This element if optional, and the /// default value is `{name_of_model}/odom`. /// - /// ``: Custom `child_frame_id` that this system will use as + /// - ``: Custom `child_frame_id` that this system will use as /// the target of the odometry transform in both the `` - /// `gz.msgs.Pose_V` message and the `` - /// `gz.msgs.Odometry` message. This element if optional, + /// gz.msgs.Pose_V message and the `` + /// gz.msgs.Odometry message. This element is optional, /// and the default value is `{name_of_model}/{name_of_link}`. /// /// A robot with rear drive and front steering would have one each /// of left_joint, right_joint, left_steering_joint and - /// right_steering_joint + /// right_steering_joint. /// /// References: - /// https://github.com/gazebosim/gz-sim/tree/main/src/systems/ackermann_steering - /// https://www.auto.tuwien.ac.at/bib/pdf_TR/TR0183.pdf - /// https://github.com/froohoo/ackermansteer/blob/master/ackermansteer/ + /// - https://github.com/gazebosim/gz-sim/tree/main/src/systems/ackermann_steering + /// - https://www.auto.tuwien.ac.at/bib/pdf_TR/TR0183.pdf + /// - https://github.com/froohoo/ackermansteer/blob/master/ackermansteer/ class AckermannSteering diff --git a/src/systems/acoustic_comms/AcousticComms.hh b/src/systems/acoustic_comms/AcousticComms.hh index 2845436cef..45e7db8845 100644 --- a/src/systems/acoustic_comms/AcousticComms.hh +++ b/src/systems/acoustic_comms/AcousticComms.hh @@ -76,6 +76,7 @@ namespace systems /// * : Seed value to be used for random sampling. /// /// Here's an example: + /// ``` /// @@ -93,6 +94,7 @@ namespace systems /// /// /// + /// ``` class AcousticComms: public gz::sim::comms::ICommsModel diff --git a/src/systems/battery_plugin/LinearBatteryPlugin.hh b/src/systems/battery_plugin/LinearBatteryPlugin.hh index f82afa7515..2f142d37e5 100644 --- a/src/systems/battery_plugin/LinearBatteryPlugin.hh +++ b/src/systems/battery_plugin/LinearBatteryPlugin.hh @@ -39,12 +39,13 @@ namespace systems /// \brief A plugin for simulating battery usage /// - /// This system processes the following sdf parameters: + /// ## System parameters + /// /// - `` name of the battery (required) /// - `` Initial voltage of the battery (required) /// - `` Voltage at full charge /// - `` Amount of voltage decrease when no - /// charge + /// charge /// - `` Initial charge of the battery (Ah) /// - `` Total charge that the battery can hold (Ah) /// - `` Internal resistance (Ohm) @@ -52,22 +53,22 @@ namespace systems /// - `` power load on battery (required) (Watts) /// - `` If true, the battery can be recharged /// - `` If true, the start/stop signals for recharging the - /// battery will also be available via topics. The - /// regular Gazebo services will still be available. + /// battery will also be available via topics. The + /// regular Gazebo services will still be available. /// - `` Hours taken to fully charge the battery. - /// (Required if `` is set to true) + /// (Required if `` is set to true) /// - `` True to change the battery behavior to fix some issues - /// described in https://github.com/gazebosim/gz-sim/issues/225. + /// described in https://github.com/gazebosim/gz-sim/issues/225. /// - `` Whether to start draining the battery right away. - /// False by default. + /// False by default. /// - `` A topic that is used to start battery - /// discharge. Any message on the specified topic will cause the battery to - /// start draining. This element can be specified multiple times if - /// multiple topics should be monitored. Note that this mechanism will - /// start the battery draining, and once started will keep drainig. + /// discharge. Any message on the specified topic will cause the battery to + /// start draining. This element can be specified multiple times if + /// multiple topics should be monitored. Note that this mechanism will + /// start the battery draining, and once started will keep drainig. /// - `` A topic that is used to stop battery - /// discharge. Any message on the specified topic will cause the battery to - /// stop draining. + /// discharge. Any message on the specified topic will cause the battery to + /// stop draining. class LinearBatteryPlugin : public System, diff --git a/src/systems/breadcrumbs/Breadcrumbs.hh b/src/systems/breadcrumbs/Breadcrumbs.hh index 5e5b3f64e4..0e09180263 100644 --- a/src/systems/breadcrumbs/Breadcrumbs.hh +++ b/src/systems/breadcrumbs/Breadcrumbs.hh @@ -56,7 +56,7 @@ namespace systems /// model using the `` tag. /// See the example in examples/worlds/breadcrumbs.sdf. /// - /// System Paramters + /// ## System Parameters /// /// - ``: Custom topic to be used to deploy breadcrumbs. If topic is /// not set, the default topic with the following pattern would be used @@ -82,7 +82,7 @@ namespace systems /// be deployed. Defaults to false. /// - ``: This is the model used as a template for deploying /// breadcrumbs. - /// ``: If true, then topic statistics are enabled on + /// - ``: If true, then topic statistics are enabled on /// `` and error messages will be generated when messages are /// dropped. Default to false. class Breadcrumbs diff --git a/src/systems/buoyancy/Buoyancy.hh b/src/systems/buoyancy/Buoyancy.hh index 5eae0f0864..bf89e01efb 100644 --- a/src/systems/buoyancy/Buoyancy.hh +++ b/src/systems/buoyancy/Buoyancy.hh @@ -67,7 +67,8 @@ namespace systems /// /// ## Examples /// - /// ### `uniform_fluid_density` world. + /// ### uniform_fluid_density world + /// /// The `buoyancy.sdf` SDF file contains three submarines. The first /// submarine is neutrally buoyant, the second sinks, and the third /// floats. To run: @@ -76,7 +77,7 @@ namespace systems /// gz sim -v 4 buoyancy.sdf /// ``` /// - /// ### `graded_buoyancy` world + /// ### graded_buoyancy world /// /// Often when simulating a maritime environment one may need to simulate both /// surface and underwater vessels. This means the buoyancy plugin needs to diff --git a/src/systems/buoyancy_engine/BuoyancyEngine.hh b/src/systems/buoyancy_engine/BuoyancyEngine.hh index ab0ad73324..422f5a703a 100644 --- a/src/systems/buoyancy_engine/BuoyancyEngine.hh +++ b/src/systems/buoyancy_engine/BuoyancyEngine.hh @@ -38,32 +38,35 @@ namespace systems /// `/model/{namespace}/buoyancy_engine` topic for the volume of the bladder /// in *cubicmeters*. /// - /// ## Parameters - /// - The link which the plugin is attached to [required, string] - /// - The namespace for the topic. If empty the plugin will listen - /// on `buoyancy_engine` otherwise it listens on + /// ## System Parameters + /// - ``: The link which the plugin is attached to [required, + /// string] + /// - ``: The namespace for the topic. If empty the plugin will + /// listen on `buoyancy_engine` otherwise it listens on /// `/model/{namespace}/buoyancy_engine` [optional, string] - /// - Minimum volume of the engine [optional, float, + /// - ``: Minimum volume of the engine [optional, float, /// default=0.00003m^3] - /// - At this volume the engine has neutral buoyancy. Used to - /// estimate the weight of the engine [optional, float, default=0.0003m^3] - /// - The volume which the engine starts at [optional, float, + /// - ``: At this volume the engine has neutral buoyancy. Used + /// to estimate the weight of the engine [optional, float, /// default=0.0003m^3] - /// - Maximum volume of the engine [optional, float, + /// - ``: The volume which the engine starts at [optional, + /// float, default=0.0003m^3] + /// - ``: Maximum volume of the engine [optional, float, /// default=0.00099m^3] - /// - Maximum inflation rate for bladder [optional, + /// - ``: Maximum inflation rate for bladder [optional, /// float, default=0.000003m^3/s] - /// - The fluid density of the liquid its suspended in kgm^-3. - /// [optional, float, default=1000kgm^-3] - /// - The Z height in metres at which the surface of the water is. - /// If not defined then there is no surface [optional, float] + /// - ``: The fluid density of the liquid its suspended in + /// kgm^-3. [optional, float, default=1000kgm^-3] + /// - ``: The Z height in metres at which the surface of the water + /// is. If not defined then there is no surface [optional, float] /// /// ## Topics - /// * Subscribes to a gz::msgs::Double on `buoyancy_engine` or - /// `/model/{namespace}/buoyancy_engine`. This is the set point for the - /// engine. - /// * Publishes a gz::msgs::Double on `buoyancy_engine` or - /// `/model/{namespace}/buoyancy_engine/current_volume` on the current volume + /// - Subscribes to a gz::msgs::Double on `buoyancy_engine` or + /// `/model/{namespace}/buoyancy_engine`. This is the set point for the + /// engine. + /// - Publishes a gz::msgs::Double on `buoyancy_engine` or + /// `/model/{namespace}/buoyancy_engine/current_volume` on the current + /// volume /// /// ## Examples /// To get started run: @@ -72,18 +75,18 @@ namespace systems /// ``` /// Enter the following in a separate terminal: /// ``` - /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double + /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \ /// -p "data: 0.003" /// ``` - /// To see the box float up. + /// to see the box float up. /// ``` - /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double + /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \ /// -p "data: 0.001" /// ``` - /// To see the box go down. + /// to see the box go down. /// To see the current volume enter: /// ``` - /// gz topic -t /model/buoyant_box/buoyancy_engine/current_volume -e + /// gz topic -t /model/buoyant_box/buoyancy_engine/current_volume -e /// ``` class BuoyancyEnginePlugin: public gz::sim::System, diff --git a/src/systems/camera_video_recorder/CameraVideoRecorder.hh b/src/systems/camera_video_recorder/CameraVideoRecorder.hh index f19369cd13..2d3115e2a0 100644 --- a/src/systems/camera_video_recorder/CameraVideoRecorder.hh +++ b/src/systems/camera_video_recorder/CameraVideoRecorder.hh @@ -34,23 +34,25 @@ namespace systems /** \class CameraVideoRecorder CameraVideoRecorder.hh \ * gz/sim/systems/CameraVideoRecorder.hh **/ + /// /// \brief Record video from a camera sensor - /// The system takes in the following parameter: - /// Name of topic for the video recorder service. If this is - /// not specified, the topic defaults to: - /// /world//link// - /// sensor//record_video /// - /// True/false value that specifies if the video should - /// be recorded using simulation time or real time. The - /// default is false, which indicates the use of real - /// time. + /// ## System Parameters + /// + /// - ``: Name of topic for the video recorder service. If this is + /// not specified, the topic defaults to: + /// /world//link// + /// sensor//record_video + /// + /// - ``: True/false value that specifies if the video should + /// be recorded using simulation time or real time. The default is false, + /// which indicates the use of real time. /// - /// Video recorder frames per second. The default value is 25, and - /// the support type is unsigned int. + /// - ``: Video recorder frames per second. The default value is 25, and + /// the support type is unsigned int. /// - /// Video recorder bitrate (bps). The default value is - /// 2070000 bps, and the supported type is unsigned int. + /// - ``: Video recorder bitrate (bps). The default value is + /// 2070000 bps, and the supported type is unsigned int. class CameraVideoRecorder final: public System, public ISystemConfigure, diff --git a/src/systems/comms_endpoint/CommsEndpoint.hh b/src/systems/comms_endpoint/CommsEndpoint.hh index 30dacdb560..4e43b7bbba 100644 --- a/src/systems/comms_endpoint/CommsEndpoint.hh +++ b/src/systems/comms_endpoint/CommsEndpoint.hh @@ -36,22 +36,23 @@ namespace systems /// running. The system will bind this address in the broker automatically /// for you and unbind it when the model is destroyed. /// - /// The endpoint can be configured with the following SDF parameters: + /// ## System Parameters /// - /// * Required parameters: - ///
An identifier used to receive messages (string). - /// The topic name where you want to receive the messages targeted to - /// this address. + /// Required parameters: + /// - `
`: An identifier used to receive messages (string). + /// - ``: The topic name where you want to receive the messages + /// targeted to this address. /// - /// * Optional parameters: - /// Element used to capture where are the broker services. - /// This block can contain any of the next optional parameters: - /// : Service name used to bind an address. - /// The default value is "/broker/bind" - /// : Service name used to unbind from an address. - /// The default value is "/broker/unbind" + /// Optional parameters: + /// - ``: Element used to capture where are the broker services. + /// This block can contain any of the next optional parameters: + /// - ``: Service name used to bind an address. + /// The default value is "/broker/bind" + /// - ``: Service name used to unbind from an address. + /// The default value is "/broker/unbind" /// - /// Here's an example: + /// ## Example + /// ``` /// @@ -62,6 +63,7 @@ namespace systems /// /broker/unbind /// /// + /// ``` class CommsEndpoint : public System, public ISystemConfigure, diff --git a/src/systems/detachable_joint/DetachableJoint.hh b/src/systems/detachable_joint/DetachableJoint.hh index e6cb491285..c207b2d2ac 100644 --- a/src/systems/detachable_joint/DetachableJoint.hh +++ b/src/systems/detachable_joint/DetachableJoint.hh @@ -40,7 +40,7 @@ namespace systems /// model can be re-attached during simulation via a topic. The status of the /// detached state can be monitored via a topic as well. /// - /// Parameters: + /// ## System Parameters /// /// - ``: Name of the link in the parent model to be used in /// creating a fixed joint with a link in the child model. diff --git a/src/systems/diff_drive/DiffDrive.hh b/src/systems/diff_drive/DiffDrive.hh index 150621bb7c..0d16498e92 100644 --- a/src/systems/diff_drive/DiffDrive.hh +++ b/src/systems/diff_drive/DiffDrive.hh @@ -35,99 +35,99 @@ namespace systems /// \brief Differential drive controller which can be attached to a model /// with any number of left and right wheels. /// - /// # System Parameters + /// ## System Parameters /// - /// ``: Name of a joint that controls a left wheel. This + /// - ``: Name of a joint that controls a left wheel. This /// element can appear multiple times, and must appear at least once. /// - /// ``: Name of a joint that controls a right wheel. This + /// - ``: Name of a joint that controls a right wheel. This /// element can appear multiple times, and must appear at least once. /// - /// ``: Distance between wheels, in meters. This element + /// - ``: Distance between wheels, in meters. This element /// is optional, although it is recommended to be included with an /// appropriate value. The default value is 1.0m. /// - /// ``: Wheel radius in meters. This element is optional, + /// - ``: Wheel radius in meters. This element is optional, /// although it is recommended to be included with an appropriate value. The /// default value is 0.2m. /// - /// ``: Odometry publication frequency. This + /// - ``: Odometry publication frequency. This /// element is optional, and the default value is 50Hz. /// - /// ``: Custom topic that this system will subscribe to in order to + /// - ``: Custom topic that this system will subscribe to in order to /// receive command velocity messages. This element if optional, and the /// default value is `/model/{name_of_model}/cmd_vel`. /// - /// ``: Custom topic on which this system will publish odometry + /// - ``: Custom topic on which this system will publish odometry /// messages. This element if optional, and the default value is /// `/model/{name_of_model}/odometry`. /// - /// ``: Custom topic on which this system will publish the + /// - ``: Custom topic on which this system will publish the /// transform from `frame_id` to `child_frame_id`. This element is optional, /// and the default value is `/model/{name_of_model}/tf`. /// - /// ``: Custom `frame_id` field that this system will use as the + /// - ``: Custom `frame_id` field that this system will use as the /// origin of the odometry transform in both the `` - /// `gz.msgs.Pose_V` message and the `` - /// `gz.msgs.Odometry` message. This element if optional, and the + /// gz.msgs.Pose_V message and the `` + /// gz.msgs.Odometry message. This element if optional, and the /// default value is `{name_of_model}/odom`. /// - /// ``: Custom `child_frame_id` that this system will use as + /// - ``: Custom `child_frame_id` that this system will use as /// the target of the odometry trasnform in both the `` - /// `gz.msgs.Pose_V` message and the `` - /// `gz.msgs.Odometry` message. This element if optional, + /// gz.msgs.Pose_V message and the `` + /// gz.msgs.Odometry message. This element if optional, /// and the default value is `{name_of_model}/{name_of_link}`. /// - /// ``: Sets both the minimum linear and minimum angular + /// - ``: Sets both the minimum linear and minimum angular /// velocity. /// - /// ``: Sets both the maximum linear and maximum angular + /// - ``: Sets both the maximum linear and maximum angular /// velocity. /// - /// ``: Sets both the minimum linear and minimum angular + /// - ``: Sets both the minimum linear and minimum angular /// acceleration. /// - /// ``: Sets both the maximum linear and maximum angular + /// - ``: Sets both the maximum linear and maximum angular /// acceleration. /// - /// ``: Sets both the minimum linear and minimum angular jerk. + /// - ``: Sets both the minimum linear and minimum angular jerk. /// - /// ``: Sets both the maximum linear and maximum angular jerk. + /// - ``: Sets both the maximum linear and maximum angular jerk. /// - /// ``: Sets the minimum linear velocity. Overrides + /// - ``: Sets the minimum linear velocity. Overrides /// `` if set. /// - /// ``: Sets the maximum linear velocity. Overrides + /// - ``: Sets the maximum linear velocity. Overrides /// `` if set. /// - /// ``: Sets the minimum angular velocity. Overrides + /// - ``: Sets the minimum angular velocity. Overrides /// `` if set. /// - /// ``: Sets the maximum angular velocity. Overrides + /// - ``: Sets the maximum angular velocity. Overrides /// `` if set. /// - /// ``: Sets the minimum linear acceleration. + /// - ``: Sets the minimum linear acceleration. /// Overrides `` if set. /// - /// ``: Sets the maximum linear acceleration. + /// - ``: Sets the maximum linear acceleration. /// Overrides `` if set. /// - /// ``: Sets the minimum angular acceleration. + /// - ``: Sets the minimum angular acceleration. /// Overrides `` if set. /// - /// ``: Sets the maximum angular acceleration. + /// - ``: Sets the maximum angular acceleration. /// Overrides `` if set. /// - /// ``: Sets the minimum linear jerk. Overrides `` - /// if set. + /// - ``: Sets the minimum linear jerk. Overrides + /// `` if set. /// - /// ``: Sets the maximum linear jerk. Overrides `` - /// if set. + /// - ``: Sets the maximum linear jerk. Overrides + /// `` if set. /// - /// ``: Sets the minimum angular jerk. Overrides + /// - ``: Sets the minimum angular jerk. Overrides /// `` if set. /// - /// ``: Sets the maximum angular jerk. Overrides + /// - ``: Sets the maximum angular jerk. Overrides /// `` if set. class DiffDrive : public System, diff --git a/src/systems/elevator/Elevator.hh b/src/systems/elevator/Elevator.hh index 0fa6f0ea52..dc188795ee 100644 --- a/src/systems/elevator/Elevator.hh +++ b/src/systems/elevator/Elevator.hh @@ -69,37 +69,37 @@ class ElevatorPrivate; /// /// ## System Parameters /// -/// ``: System update rate. This element is optional and the +/// - ``: System update rate. This element is optional and the /// default value is 10Hz. A value of zero gets translated to the simulation /// rate (no throttling for the system). /// -/// ``: Prefix in the names of the links that function as +/// - ``: Prefix in the names of the links that function as /// a reference for each floor level. When the elevator is requested to move /// to a given floor level, the cabin is commanded to move to the height of /// the corresponding floor link. The names of the links will be expected to /// be `{prerix}i`, where \f$i=[0,N)\f$ and N is the number of floors. This /// element is optional and the default value is `floor_`. /// -/// ``: Prefix in the names of the joints that control the +/// - ``: Prefix in the names of the joints that control the /// doors of the elevator. The names of the joints will be expected to be /// `{prerix}i`, where \f$i=[0,N)\f$ and N is the number of floors. This /// element is optional and the default value is `door_`. /// -/// ``: Name of the joint that controls the position of the +/// - ``: Name of the joint that controls the position of the /// cabin. This element is optional and the default value is `lift`. /// -/// ``: Topic to which this system will subscribe in order to +/// - ``: Topic to which this system will subscribe in order to /// receive command messages. This element is optional and the default value /// is `/model/{model_name}/cmd`. /// -/// ``: Topic on which this system will publish state (current +/// - ``: Topic on which this system will publish state (current /// floor) messages. This element is optional and the default value is /// `/model/{model_name}/state`. /// -/// ``: State publication rate. This rate is bounded by +/// - ``: State publication rate. This rate is bounded by /// ``. This element is optional and the default value is 5Hz. /// -/// ``: Time to wait with a door open before the door +/// - ``: Time to wait with a door open before the door /// closes. This element is optional and the default value is 5 sec. class GZ_SIM_VISIBLE Elevator : public System, public ISystemConfigure, diff --git a/src/systems/environment_preload/EnvironmentPreload.hh b/src/systems/environment_preload/EnvironmentPreload.hh index 16a9793cc0..9b462281c1 100644 --- a/src/systems/environment_preload/EnvironmentPreload.hh +++ b/src/systems/environment_preload/EnvironmentPreload.hh @@ -32,8 +32,9 @@ namespace systems { class EnvironmentPreloadPrivate; - /// \class EnvironmentPreload EnvironmentPreload.hh - /// gz/sim/systems/EnvironmentPreload.hh + /** \class EnvironmentPreload EnvironmentPreload.hh \ + * gz/sim/systems/EnvironmentPreload.hh + **/ /// \brief A plugin to preload an Environment component /// into the ECM upon simulation start-up. class EnvironmentPreload : diff --git a/src/systems/follow_actor/FollowActor.hh b/src/systems/follow_actor/FollowActor.hh index 7a01a920cc..27076786c5 100644 --- a/src/systems/follow_actor/FollowActor.hh +++ b/src/systems/follow_actor/FollowActor.hh @@ -35,24 +35,23 @@ namespace systems /// \class FollowActor FollowActor.hh gz/sim/systems/FollowActor.hh /// \brief Make an actor follow a target entity in the world. /// - /// ## SDF parameters + /// ## System Parameters /// - /// : Name of entity to follow. + /// - ``: Name of entity to follow. /// - /// : Distance in meters to keep from target's origin. + /// - ``: Distance in meters to keep from target's origin. /// - /// : Distance in meters from target's origin when to stop - /// following. When the actor is back within range it starts - /// following again. + /// - ``: Distance in meters from target's origin when to stop + /// following. When the actor is back within range it starts following + /// again. /// - /// : Actor's velocity in m/s + /// - ``: Actor's velocity in m/s /// - /// : Actor's animation to play. If empty, the first animation in - /// the model will be used. + /// - ``: Actor's animation to play. If empty, the first animation + /// in the model will be used. /// - /// : Velocity of the animation on the X axis. Used to - /// coordinate translational motion with the actor's - /// animation. + /// - ``: Velocity of the animation on the X axis. Used to + /// coordinate translational motion with the actor's animation. class FollowActor: public System, public ISystemConfigure, diff --git a/src/systems/hydrodynamics/Hydrodynamics.hh b/src/systems/hydrodynamics/Hydrodynamics.hh index aab1a7cdb0..1ada82b467 100644 --- a/src/systems/hydrodynamics/Hydrodynamics.hh +++ b/src/systems/hydrodynamics/Hydrodynamics.hh @@ -40,7 +40,7 @@ namespace systems /// forces like linear and quadratic drag, buoyancy (not provided by this /// plugin), etc. /// - /// # System Parameters + /// ## System Parameters /// The exact description of these parameters can be found on p. 37 and /// p. 43 of Fossen's book. They are used to calculate added mass, linear and /// quadratic drag and coriolis force. diff --git a/src/systems/joint_controller/JointController.hh b/src/systems/joint_controller/JointController.hh index ae65473423..ec1b3bd381 100644 --- a/src/systems/joint_controller/JointController.hh +++ b/src/systems/joint_controller/JointController.hh @@ -37,56 +37,60 @@ namespace systems /// /// ## System Parameters /// - /// `` The name of the joint to control. Required parameter. + /// - `` The name of the joint to control. Required parameter. /// Can also include multiple `` for identical joints. /// - /// `` True to enable the controller implementation + /// - `` True to enable the controller implementation /// using force commands. If this parameter is not set or is false, the /// controller will use velocity commands internally. /// - /// `` True to enable the use of actuator message + /// - `` True to enable the use of actuator message /// for velocity command. The actuator msg is an array of floats for /// position, velocity and normalized commands. Relies on /// `` for the index of the velocity actuator and /// defaults to topic "/actuators" when `topic` or `subtopic not set. /// - /// `` used with `` to set + /// - `` used with `` to set /// the index of the velocity actuator. /// - /// `` Topic to receive commands in. Defaults to + /// - `` Topic to receive commands in. Defaults to /// `/model//joint//cmd_vel`. /// - /// `` Sub topic to receive commands in. - /// Defaults to "/model//". + /// - `` Sub topic to receive commands in. + /// Defaults to "/model//". /// - /// `` Velocity to start with. + /// - `` Velocity to start with. /// - /// ### Velocity mode: No additional parameters are required. + /// ### Velocity mode /// - /// ### Force mode: The controller accepts the next optional parameters: + /// No additional parameters are required. /// - /// `` The proportional gain of the PID. - /// The default value is 1. + /// ### Force mode /// - /// `` The integral gain of the PID. - /// The default value is 0. + /// The controller accepts the next optional parameters: /// - /// `` The derivative gain of the PID. - /// The default value is 0. + /// - `` The proportional gain of the PID. + /// The default value is 1. /// - /// `` The integral upper limit of the PID. - /// The default value is 1. + /// - `` The integral gain of the PID. + /// The default value is 0. + /// + /// - `` The derivative gain of the PID. + /// The default value is 0. + /// + /// - `` The integral upper limit of the PID. + /// The default value is 1. /// - /// `` The integral lower limit of the PID. - /// The default value is -1. + /// - `` The integral lower limit of the PID. + /// The default value is -1. /// - /// `` Output max value of the PID. - /// The default value is 1000. + /// - `` Output max value of the PID. + /// The default value is 1000. /// - /// `` Output min value of the PID. - /// The default value is -1000. + /// - `` Output min value of the PID. + /// The default value is -1000. /// - /// `` Command offset (feed-forward) of the PID. + /// - `` Command offset (feed-forward) of the PID. /// The default value is 0. class JointController : public System, diff --git a/src/systems/joint_position_controller/JointPositionController.hh b/src/systems/joint_position_controller/JointPositionController.hh index af139641d7..f7290fea29 100644 --- a/src/systems/joint_position_controller/JointPositionController.hh +++ b/src/systems/joint_position_controller/JointPositionController.hh @@ -46,56 +46,56 @@ namespace systems /// /// ## System Parameters /// - /// `` The name of the joint to control. Required parameter. - /// Can also include multiple `` for identical joints. + /// - `` The name of the joint to control. Required parameter. + /// Can also include multiple `` for identical joints. /// - /// `` Axis of the joint to control. Optional parameter. - /// The default value is 0. + /// - `` Axis of the joint to control. Optional parameter. + /// The default value is 0. /// - /// `` True to enable the use of actutor message + /// - `` True to enable the use of actutor message /// for position command. Relies on `` for the /// index of the position actuator and defaults to topic "/actuators". /// - /// `` used with `` to set + /// - `` used with `` to set /// the index of the position actuator. /// - /// `` The proportional gain of the PID. Optional parameter. - /// The default value is 1. + /// - `` The proportional gain of the PID. Optional parameter. + /// The default value is 1. /// - /// `` The integral gain of the PID. Optional parameter. - /// The default value is 0.1. + /// - `` The integral gain of the PID. Optional parameter. + /// The default value is 0.1. /// - /// `` The derivative gain of the PID. Optional parameter. - /// The default value is 0.01 + /// - `` The derivative gain of the PID. Optional parameter. + /// The default value is 0.01 /// - /// `` The integral upper limit of the PID. Optional parameter. - /// The default value is 1. + /// - `` The integral upper limit of the PID. Optional parameter. + /// The default value is 1. /// - /// `` The integral lower limit of the PID. Optional parameter. - /// The default value is -1. + /// - `` The integral lower limit of the PID. Optional parameter. + /// The default value is -1. /// - /// `` Output max value of the PID. Optional parameter. - /// The default value is 1000. + /// - `` Output max value of the PID. Optional parameter. + /// The default value is 1000. /// - /// `` Output min value of the PID. Optional parameter. - /// The default value is -1000. + /// - `` Output min value of the PID. Optional parameter. + /// The default value is -1000. /// - /// `` Command offset (feed-forward) of the PID. Optional + /// - `` Command offset (feed-forward) of the PID. Optional /// parameter. The default value is 0. /// - /// `` Bypasses the PID and creates a perfect + /// - `` Bypasses the PID and creates a perfect /// position. The maximum speed on the joint can be set using the `` /// tag. /// - /// `` If you wish to listen on a non-default topic you may specify it - /// here, otherwise the controller defaults to listening on + /// - `` If you wish to listen on a non-default topic you may specify + /// it here, otherwise the controller defaults to listening on /// "/model//joint///cmd_pos". /// - /// `` If you wish to listen on a sub_topic you may specify it + /// - `` If you wish to listen on a sub_topic you may specify it /// here "/model//". /// - /// `` Initial position of a joint. Optional parameter. - /// The default value is 0. + /// - `` Initial position of a joint. Optional parameter. + /// The default value is 0. class JointPositionController : public System, public ISystemConfigure, diff --git a/src/systems/joint_state_publisher/JointStatePublisher.hh b/src/systems/joint_state_publisher/JointStatePublisher.hh index 28d2408091..b92da24414 100644 --- a/src/systems/joint_state_publisher/JointStatePublisher.hh +++ b/src/systems/joint_state_publisher/JointStatePublisher.hh @@ -41,12 +41,13 @@ namespace systems /// a model. Use the `` system parameter, described below, to /// control which joints are published. /// - /// # System Parameters + /// ## System Parameters /// - /// ``: Name of the topic to publish to. This parameter is optional, + /// - ``: Name of the topic to publish to. This parameter is optional, /// and if not provided, the joint state will be published to /// "/world//model//joint_state". - /// ``: Name of a joint to publish. This parameter can be + /// + /// - ``: Name of a joint to publish. This parameter can be /// specified multiple times, and is optional. All joints in a model will /// be published if joint names are not specified. class JointStatePublisher diff --git a/src/systems/joint_traj_control/JointTrajectoryController.hh b/src/systems/joint_traj_control/JointTrajectoryController.hh index 09dc7d9e48..5c654e04e0 100644 --- a/src/systems/joint_traj_control/JointTrajectoryController.hh +++ b/src/systems/joint_traj_control/JointTrajectoryController.hh @@ -65,68 +65,68 @@ namespace systems /// /// ## System Parameters /// - /// `` The name of the topic that this plugin subscribes to. + /// - `` The name of the topic that this plugin subscribes to. /// Optional parameter. /// Defaults to "/model/${MODEL_NAME}/joint_trajectory". /// - /// `` If enabled, trajectory execution begins at the + /// - `` If enabled, trajectory execution begins at the /// timestamp contained in the header of received trajectory messages. /// Optional parameter. /// Defaults to false. /// - /// `` Name of a joint to control. + /// - `` Name of a joint to control. /// This parameter can be specified multiple times, i.e. once for each joint. /// Optional parameter. /// Defaults to all 1-axis joints contained in the model SDF (order is kept). /// - /// `` Initial position of a joint (for position control). + /// - `` Initial position of a joint (for position control). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// Defaults to 0 for all joints. /// - /// `<%s_p_gain>` The proportional gain of the PID. + /// - `<%s_p_gain>` The proportional gain of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is 0 (disabled). /// - /// `<%s_i_gain>` The integral gain of the PID. Optional parameter. + /// - `<%s_i_gain>` The integral gain of the PID. Optional parameter. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is 0 (disabled). /// - /// `<%s_d_gain>` The derivative gain of the PID. + /// - `<%s_d_gain>` The derivative gain of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is 0 (disabled). /// - /// `<%s_i_min>` The integral lower limit of the PID. + /// - `<%s_i_min>` The integral lower limit of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is 0 (no limit if higher than `%s_i_max`). /// - /// `<%s_i_max>` The integral upper limit of the PID. + /// - `<%s_i_max>` The integral upper limit of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is -1 (no limit if lower than `%s_i_min`). /// - /// `<%s_cmd_min>` Output min value of the PID. + /// - `<%s_cmd_min>` Output min value of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is 0 (no limit if higher than `%s_i_max`). /// - /// `<%s_cmd_max>` Output max value of the PID. + /// - `<%s_cmd_max>` Output max value of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. /// The default value is -1 (no limit if lower than `%s_i_min`). /// - /// `<%s_cmd_offset>` Command offset (feed-forward) of the PID. + /// - `<%s_cmd_offset>` Command offset (feed-forward) of the PID. /// Substitute '%s' for "position" or "velocity" (e.g. "position_p_gain"). /// This parameter can be specified multiple times. Follows joint_name order. /// Optional parameter. diff --git a/src/systems/kinetic_energy_monitor/KineticEnergyMonitor.hh b/src/systems/kinetic_energy_monitor/KineticEnergyMonitor.hh index c8d0020535..aae88a94eb 100644 --- a/src/systems/kinetic_energy_monitor/KineticEnergyMonitor.hh +++ b/src/systems/kinetic_energy_monitor/KineticEnergyMonitor.hh @@ -39,20 +39,20 @@ namespace systems /// that surpasses a specific threshold. /// This system can be used to detect when a model could be damaged. /// - /// # System Parameters + /// ## System Parameters /// - /// ``: Name of the link to monitor. This name must match + /// - ``: Name of the link to monitor. This name must match /// a name of link within the model. /// - /// ``: Threshold, in Joule (J), after which + /// - ``: Threshold, in Joule (J), after which /// a message is generated on `` with the kinetic energy value that /// surpassed the threshold. /// - /// ``: Custom topic that this system will publish to when kinetic + /// - ``: Custom topic that this system will publish to when kinetic /// energy surpasses the threshold. This element if optional, and the /// default value is `/model/{name_of_model}/kinetic_energy`. /// - /// # Example Usage + /// ## Example Usage /// /** \verbatim diff --git a/src/systems/lens_flare/LensFlare.hh b/src/systems/lens_flare/LensFlare.hh index 95ed7a07d4..9ea069d009 100644 --- a/src/systems/lens_flare/LensFlare.hh +++ b/src/systems/lens_flare/LensFlare.hh @@ -32,23 +32,26 @@ namespace systems /// \brief Private data class for LensFlare Plugin class LensFlarePrivate; - /** \class LensFlare LensFlare.hh \ + /** \class LensFlare LensFlare.hh \ * gz/sim/systems/LensFlare.hh **/ /// \brief Add lens flare effects to the camera output as a render pass - /// The system takes in the following parameter: - /// Sets the scale of the lens flare. If this is - /// not specified, the value defaults to 1.0 /// - /// Sets the color of the lens flare. The default - /// is {1.4, 1.2, 1.0} + /// ## System Parameters /// - /// Sets the number of steps to take in - /// each direction to check for occlusions. - /// The default value is set to 10. Use 0 to disable - /// Sets the light associated with the lens flares. - /// If not specified. The first light in the scene will - /// be used. + /// - ``: Sets the scale of the lens flare. If this is + /// not specified, the value defaults to 1.0 + /// + /// - ``: Sets the color of the lens flare. The default + /// is {1.4, 1.2, 1.0} + /// + /// - ``: Sets the number of steps to take in + /// each direction to check for occlusions. + /// The default value is set to 10. Use 0 to disable + /// + /// - ``: Sets the light associated with the lens flares. + /// If not specified. The first light in the scene will + /// be used. class LensFlare: public System, diff --git a/src/systems/lift_drag/LiftDrag.hh b/src/systems/lift_drag/LiftDrag.hh index 8c7cba996d..f9f33b960f 100644 --- a/src/systems/lift_drag/LiftDrag.hh +++ b/src/systems/lift_drag/LiftDrag.hh @@ -35,34 +35,35 @@ namespace systems /// \brief The LiftDrag system computes lift and drag forces enabling /// simulation of aerodynamic robots. /// - /// The following parameters are used by the system: + /// ## System Parameters /// - /// link_name : Name of the link affected by the group of lift/drag - /// properties. This can be a scoped name to reference links in - /// nested models. \sa entitiesFromScopedName to learn more - /// about scoped names. - /// air_density : Density of the fluid this model is suspended in. - /// area : Surface area of the link. - /// a0 : The initial "alpha" or initial angle of attack. a0 is also - /// the y-intercept of the alpha-lift coefficient curve. - /// cla : The ratio of the coefficient of lift and alpha slope before - /// stall. Slope of the first portion of the alpha-lift - /// coefficient curve. - /// cda : The ratio of the coefficient of drag and alpha slope before - /// stall. - /// cp : Center of pressure. The forces due to lift and drag will be - /// applied here. - /// forward : 3-vector representing the forward direction of motion in the - /// link frame. - /// upward : 3-vector representing the direction of lift or drag. - /// alpha_stall : Angle of attack at stall point; the peak angle of attack. - /// cla_stall : The ratio of coefficient of lift and alpha slope after - /// stall. Slope of the second portion of the alpha-lift - /// coefficient curve. - /// cda_stall : The ratio of coefficient of drag and alpha slope after - /// stall. - /// control_joint_name: Name of joint that actuates a control surface for this - /// lifting body (Optional) + /// - ``: Name of the link affected by the group of lift/drag + /// properties. This can be a scoped name to reference links in + /// nested models. \sa entitiesFromScopedName to learn more + /// about scoped names. + /// - ``: Density of the fluid this model is suspended in. + /// - ``: Surface area of the link. + /// - ``: The initial "alpha" or initial angle of attack. a0 is also + /// the y-intercept of the alpha-lift coefficient curve. + /// - ``: The ratio of the coefficient of lift and alpha slope before + /// stall. Slope of the first portion of the alpha-lift + /// coefficient curve. + /// - ``: The ratio of the coefficient of drag and alpha slope before + /// stall. + /// - ``: Center of pressure. The forces due to lift and drag will be + /// applied here. + /// - ``: 3-vector representing the forward direction of motion in + /// the link frame. + /// - ``: 3-vector representing the direction of lift or drag. + /// - ``: Angle of attack at stall point; the peak angle of + /// attack. + /// - ``: The ratio of coefficient of lift and alpha slope after + /// stall. Slope of the second portion of the alpha-lift + /// coefficient curve. + /// - ``: The ratio of coefficient of drag and alpha slope after + /// stall. + /// - ``: Name of joint that actuates a control surface + /// for this lifting body (Optional) class LiftDrag : public System, public ISystemConfigure, diff --git a/src/systems/log/LogPlayback.hh b/src/systems/log/LogPlayback.hh index bc8fd28110..66712a9c89 100644 --- a/src/systems/log/LogPlayback.hh +++ b/src/systems/log/LogPlayback.hh @@ -33,8 +33,9 @@ namespace systems // Forward declarations. class LogPlaybackPrivate; - /// \class LogPlayback LogPlayback.hh - /// gz/sim/systems/log/LogPlayback.hh + /** \class LogPlayback LogPlayback.hh \ + * gz/sim/systems/log/LogPlayback.hh + **/ /// \brief Log state playback class LogPlayback: public System, diff --git a/src/systems/log_video_recorder/LogVideoRecorder.hh b/src/systems/log_video_recorder/LogVideoRecorder.hh index 958f0152ce..0de7eb46ac 100644 --- a/src/systems/log_video_recorder/LogVideoRecorder.hh +++ b/src/systems/log_video_recorder/LogVideoRecorder.hh @@ -38,18 +38,21 @@ namespace systems /// \brief System which recordings videos from log playback /// There are two ways to specify what entities in the log playback to follow /// and record videos for: 1) by entity name and 2) by region. See the - /// following parameters: - /// - `` Name of entity to record. - /// - `` Axis-aligned box where entities are at start of log - /// + `` Min corner position of box region. - /// + `` Max corner position of box region. - /// - `` Sim time when recording should start - /// - `` Sim time when recording should end - /// - `` Exit gz-sim when log playback recording ends + /// system parameters. /// /// When recording is finished. An `end` string will be published to the /// `/log_video_recorder/status` topic and the videos are saved to a /// timestamped directory + /// + /// ## System Parameters + /// + /// - `` Name of entity to record. + /// - `` Axis-aligned box where entities are at start of log + /// + `` Min corner position of box region. + /// + `` Max corner position of box region. + /// - `` Sim time when recording should start + /// - `` Sim time when recording should end + /// - `` Exit gz-sim when log playback recording ends class LogVideoRecorder final: public System, public ISystemConfigure, diff --git a/src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh b/src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh index 04c93edd45..0a4873d474 100644 --- a/src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh +++ b/src/systems/logical_audio_sensor_plugin/LogicalAudioSensorPlugin.hh @@ -42,6 +42,8 @@ namespace systems /// such as speakers. This plugin is meant to check if audio /// could theoretically be heard at a certain location or not. /// + /// ## System Parameters + /// /// Secifying an audio source via SDF is done as follows: /// /// - `` A new audio source in the environment, which has the diff --git a/src/systems/mecanum_drive/MecanumDrive.hh b/src/systems/mecanum_drive/MecanumDrive.hh index 4cc910eee1..1442967687 100644 --- a/src/systems/mecanum_drive/MecanumDrive.hh +++ b/src/systems/mecanum_drive/MecanumDrive.hh @@ -35,58 +35,59 @@ namespace systems /// \brief Mecanum drive controller which can be attached to a model /// with any number of front/back left/right wheels. /// - /// # System Parameters + /// ## System Parameters /// - /// ``: Name of a joint that controls a front left wheel. + /// - ``: Name of a joint that controls a front left wheel. /// This element can appear multiple times, and must appear at least once. /// - /// ``: Name of a joint that controls a front right wheel. - /// This element can appear multiple times, and must appear at least once. + /// - ``: Name of a joint that controls a front right + /// wheel. This element can appear multiple times, and must appear at least + /// once. /// - /// ``: Name of a joint that controls a back left wheel. + /// - ``: Name of a joint that controls a back left wheel. /// This element can appear multiple times, and must appear at least once. /// - /// ``: Name of a joint that controls a back right wheel. + /// - ``: Name of a joint that controls a back right wheel. /// This element can appear multiple times, and must appear at least once. /// - /// ``: Longitudinal distance between front and back wheels, + /// - ``: Longitudinal distance between front and back wheels, /// in meters. This element is optional, although it is recommended to be /// included with an appropriate value. The default value is 1.0m. /// - /// ``: Lateral distance between left and right wheels, + /// - ``: Lateral distance between left and right wheels, /// in meters. This element is optional, although it is recommended to be /// included with an appropriate value. The default value is 1.0m. /// - /// ``: Wheel radius in meters. This element is optional, + /// - ``: Wheel radius in meters. This element is optional, /// although it is recommended to be included with an appropriate value. The /// default value is 0.2m. /// - /// ``: Odometry publication frequency. This + /// - ``: Odometry publication frequency. This /// element is optional, and the default value is 50Hz. /// - /// ``: Custom topic that this system will subscribe to in order to + /// - ``: Custom topic that this system will subscribe to in order to /// receive command velocity messages. This element if optional, and the /// default value is `/model/{name_of_model}/cmd_vel`. /// - /// ``: Custom topic on which this system will publish odometry + /// - ``: Custom topic on which this system will publish odometry /// messages. This element if optional, and the default value is /// `/model/{name_of_model}/odometry`. /// - /// ``: Custom topic on which this system will publish the + /// - ``: Custom topic on which this system will publish the /// transform from `frame_id` to `child_frame_id`. This element if optional, /// and the default value is `/model/{name_of_model}/tf`. /// - /// ``: Custom `frame_id` field that this system will use as the + /// - ``: Custom `frame_id` field that this system will use as the /// origin of the odometry transform in both the `` /// `gz.msgs.Pose_V` message and the `` /// `gz.msgs.Odometry` message. This element if optional, and the /// default value is `{name_of_model}/odom`. /// - /// ``: Custom `child_frame_id` that this system will use as + /// - ``: Custom `child_frame_id` that this system will use as /// the target of the odometry trasnform in both the `` /// `gz.msgs.Pose_V` message and the `` /// `gz.msgs.Odometry` message. This element if optional, - /// and the default value is `{name_of_model}/{name_of_link}`. + /// and the default value is `{name_of_model}/{name_of_link}`. class MecanumDrive : public System, public ISystemConfigure, diff --git a/src/systems/multicopter_control/MulticopterVelocityControl.hh b/src/systems/multicopter_control/MulticopterVelocityControl.hh index c414d1ec53..eb2cd1caf8 100644 --- a/src/systems/multicopter_control/MulticopterVelocityControl.hh +++ b/src/systems/multicopter_control/MulticopterVelocityControl.hh @@ -69,84 +69,85 @@ namespace systems /// * Maximum acceleration limit /// * Can be enabled/disabled at runtime. /// - /// # Parameters - /// The following parameters are used by the system + /// ## System Parameters /// - /// robotNamespace: All gz-transport topics subscribed to and published by - /// the system will be prefixed by this string. This is a required parameter. + /// - `robotNamespace`: All gz-transport topics subscribed to and published by + /// the system will be prefixed by this string. This is a required parameter. /// - /// commandSubTopic: The system subscribes to this topic to receive twist + /// - `commandSubTopic`: The system subscribes to this topic to receive twist /// commands. The default value is "cmd_vel". /// - /// enableSubTopic: Topic to enable or disable the system. If false, the + /// - `enableSubTopic`: Topic to enable or disable the system. If false, the /// controller sends a zero rotor velocity command once and gets disabled. If /// the vehicle is in the air, disabling the controller will cause it to fall. /// If true, the controller becomes enabled and waits for a twist message. The /// default value is "enable". /// - /// comLinkName: The link associated with the center of mass of the vehicle. - /// That is, the origin of the center of mass may not be on this link, but - /// this link and the center of mass frame have a fixed transform. Almost - /// always this should be the base_link of the vehicle. This is a required - /// parameter. + /// - `comLinkName`: The link associated with the center of mass of the + /// vehicle. That is, the origin of the center of mass may not be on this + /// link, but this link and the center of mass frame have a fixed transform. + /// Almost always this should be the base_link of the vehicle. This is a + /// required parameter. /// - /// velocityGain (x, y, z): Proportional gain on linear velocity. + /// - `velocityGain` (x, y, z): Proportional gain on linear velocity. /// attitudeGain (roll, pitch, yaw): Proportional gain on attitude. This /// parameter is scaled by the inverse of the inertia matrix so two vehicles /// with different inertial characteristics may have the same gain if other /// parameters, such as the forceConstant, are kept the same. This is a /// required parameter. /// - /// angularRateGain (roll, pitch, yaw): Proportional gain on angular velocity. - /// Even though only the yaw angle velocity is controlled, proper gain values - /// for roll and pitch velocities must be specified. This parameter is scaled - /// by the inverse of the inertia matrix so two vehicles with different - /// inertial characteristics may have the same gain if other parameters, such - /// as the forceConstant, are kept the same. This is a required parameter. + /// - `angularRateGain` (roll, pitch, yaw): Proportional gain on angular + /// velocity. Even though only the yaw angle velocity is controlled, proper + /// gain values for roll and pitch velocities must be specified. This + /// parameter is scaled by the inverse of the inertia matrix so two vehicles + /// with different inertial characteristics may have the same gain if other + /// parameters, such as the forceConstant, are kept the same. This is a + /// required parameter. /// - /// maxLinearAcceleration (x, y, z): Maximum limit on linear acceleration. + /// - `maxLinearAcceleration` (x, y, z): Maximum limit on linear acceleration. /// The default value is DBL_MAX. /// - /// maximumLinearVelocity (x, y, z): Maximum commanded linear velocity. The - /// default value is DBL_MAX. - - /// maximumAngularVelocity (roll, pitch, yaw): Maximum commanded angular + /// - `maximumLinearVelocity` (x, y, z): Maximum commanded linear velocity. + /// The default value is DBL_MAX. + /// + /// - `maximumAngularVelocity` (roll, pitch, yaw): Maximum commanded angular /// velocity. The default value is DBL_MAX. /// - /// linearVelocityNoiseMean (x, y, z): Mean of Gaussian noise on linear + /// - `linearVelocityNoiseMean` (x, y, z): Mean of Gaussian noise on linear /// velocity values obtained from simulation. The default value is (0, 0, 0). /// - /// linearVelocityNoiseStdDev (x, y, z): Standard deviation of Gaussian noise - /// on linear values obtained from simulation. A value of 0 implies noise is - /// NOT applied to the component. The default value is (0, 0, 0). + /// - `linearVelocityNoiseStdDev` (x, y, z): Standard deviation of Gaussian + /// noise on linear values obtained from simulation. A value of 0 implies + /// noise is NOT applied to the component. The default value is (0, 0, 0). /// - /// angularVelocityNoiseMean (roll, pitch, yaw): Mean of Gaussian noise on + /// - `angularVelocityNoiseMean` (roll, pitch, yaw): Mean of Gaussian noise on /// angular velocity values obtained from simulation. The default value is (0, /// 0, 0). /// - /// angularVelocityNoiseStdDev (roll, pitch, yaw): Standard deviation of + /// - `angularVelocityNoiseStdDev` (roll, pitch, yaw): Standard deviation of /// gaussian noise on angular velocity values obtained from simulation. A /// value of 0 implies noise is NOT applied to the component. The default /// value is (0, 0, 0). /// - /// rotorConfiguration: This contains a list of `` elements for each - /// rotor in the vehicle. This is a required parameter. + /// - `rotorConfiguration`: This contains a list of `` elements for + /// each rotor in the vehicle. This is a required parameter. /// - /// rotor: Contains information about a rotor in the vehicle. All the + /// - `rotor`: Contains information about a rotor in the vehicle. All the /// elements of `` are required parameters. /// - /// jointName: The name of the joint associated with this rotor. + /// - `jointName`: The name of the joint associated with this rotor. /// - /// forceConstant: A constant that multiplies with the square of the + /// - `forceConstant`: A constant that multiplies with the square of the /// rotor's velocity to compute its thrust. /// - /// momentConstant: A constant the multiplies with the rotor's thrust to - /// compute its moment. + /// - `momentConstant`: A constant the multiplies with the rotor's + /// thrust to compute its moment. + /// + /// - `direction`: Direction of rotation of the rotor. +1 is + /// counterclockwise and -1 is clockwise. /// - /// direction: Direction of rotation of the rotor. +1 is counterclockwise - /// and -1 is clockwise. + /// ## Examples /// - /// # Examples /// See examples/worlds/quadcopter.sdf for a demonstration. /// class MulticopterVelocityControl diff --git a/src/systems/pose_publisher/PosePublisher.hh b/src/systems/pose_publisher/PosePublisher.hh index db1a7e1d33..022ba2d4e6 100644 --- a/src/systems/pose_publisher/PosePublisher.hh +++ b/src/systems/pose_publisher/PosePublisher.hh @@ -37,33 +37,27 @@ namespace systems /// messages, or a single gz::msgs::Pose_V message if /// "use_pose_vector_msg" is true. /// - /// The following parameters are used by the system: + /// ## System Parameters /// - /// publish_link_pose : Set to true to publish link pose - /// publish_visual_pose : Set to true to publish visual pose - /// publish_collision_pose : Set to true to publish collision pose - /// publish_sensor_pose : Set to true to publish sensor pose - /// publish_model_pose : Set to true to publish model pose. - /// publish_nested_model_pose : Set to true to publish nested model pose. The - /// pose of the model that contains this system is - /// also published unless publish_model_pose is - /// set to false - /// use_pose_vector_msg : Set to true to publish an - /// gz::msgs::Pose_V message instead of - /// mulitple gz::msgs::Pose messages. - /// update_frequency : Frequency of pose publications in Hz. A - /// negative frequency publishes as fast as - /// possible (i.e, at the rate of the simulation - /// step) - /// static_publisher : Set to true to publish static poses on - /// a "/pose_static" topic. - /// This will cause only dynamic poses to be - /// published on the "/pose" - /// topic. - /// static_update_frequency : Frequency of static pose publications in Hz. A - /// negative frequency publishes as fast as - /// possible (i.e, at the rate of the simulation - /// step). + /// - ``: Set to true to publish link pose + /// - ``: Set to true to publish visual pose + /// - ``: Set to true to publish collision pose + /// - ``: Set to true to publish sensor pose + /// - ``: Set to true to publish model pose. + /// - ``: Set to true to publish nested model + /// pose. The pose of the model that contains this system is also published + /// unless publish_model_pose is set to false + /// - ``: Set to true to publish a gz::msgs::Pose_V + /// message instead of mulitple gz::msgs::Pose messages. + /// - ``: Frequency of pose publications in Hz. A negative + /// frequency publishes as fast as possible (i.e, at the rate of the + /// simulation step) + /// - ``: Set to true to publish static poses on a + /// "/pose_static" topic. This will cause only dynamic + /// poses to be published on the "/pose" topic. + /// - ``: Frequency of static pose publications in + /// Hz. A negative frequency publishes as fast as possible (i.e, at the + /// rate of the simulation step). class PosePublisher : public System, public ISystemConfigure, diff --git a/src/systems/user_commands/UserCommands.hh b/src/systems/user_commands/UserCommands.hh index f035c684a4..0aa396bd00 100644 --- a/src/systems/user_commands/UserCommands.hh +++ b/src/systems/user_commands/UserCommands.hh @@ -38,38 +38,38 @@ namespace systems /// \todo(louise) In the future, an interface undo/redo commands will also /// be provided. /// - /// # Spawn entity + /// ### Spawn entity /// /// * **Service**: `/world//create` - /// * **Request type*: gz.msgs.EntityFactory - /// * **Response type*: gz.msgs.Boolean + /// * **Request type**: gz.msgs.EntityFactory + /// * **Response type**: gz.msgs.Boolean /// - /// # Spawn multiple entities + /// ### Spawn multiple entities /// /// This service can spawn multiple entities in the same iteration, /// thereby eliminating simulation steps between entity spawn times. /// /// * **Service**: `/world//create_multiple` - /// * **Request type*: gz.msgs.EntityFactory_V - /// * **Response type*: gz.msgs.Boolean + /// * **Request type**: gz.msgs.EntityFactory_V + /// * **Response type**: gz.msgs.Boolean /// - /// # Set entity pose + /// ### Set entity pose /// /// This service set the pose of entities /// /// * **Service**: `/world//set_pose` - /// * **Request type*: gz.msgs.Pose - /// * **Response type*: gz.msgs.Boolean + /// * **Request type**: gz.msgs.Pose + /// * **Response type**: gz.msgs.Boolean /// - /// # Set multiple entity poses + /// ### Set multiple entity poses /// /// This service set the pose of multiple entities /// /// * **Service**: `/world//set_pose_vector` - /// * **Request type*: gz.msgs.Pose_V - /// * **Response type*: gz.msgs.Boolean + /// * **Request type**: gz.msgs.Pose_V + /// * **Response type**: gz.msgs.Boolean /// - /// Try some examples described on examples/worlds/empty.sdf + /// Try some examples described in examples/worlds/empty.sdf class UserCommands final: public System, public ISystemConfigure, From 166bcf2ef1cdf906e6a5344cecf69595935b772f Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Tue, 31 Oct 2023 21:51:05 -0400 Subject: [PATCH 15/16] rename page tag to be consistent with downstream tutorial Signed-off-by: Mabel Zhang --- tutorials/component_jointforcecmd.md | 2 +- tutorials/using_components.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/component_jointforcecmd.md b/tutorials/component_jointforcecmd.md index c7149a4460..e3a86134ac 100644 --- a/tutorials/component_jointforcecmd.md +++ b/tutorials/component_jointforcecmd.md @@ -1,4 +1,4 @@ -\page compjointforcecmd Case Study: Using the JointForceCmd Component +\page jointforcecmdcomponent Case Study: Using the JointForceCmd Component We will show how to use one of the components, \ref gz::sim::components::JointForceCmd, in a system. diff --git a/tutorials/using_components.md b/tutorials/using_components.md index b4cb1078ac..76261f1440 100644 --- a/tutorials/using_components.md +++ b/tutorials/using_components.md @@ -66,4 +66,4 @@ entities. The rest of the tutorial is case studies that walk through the usage of specific components. -- \subpage compjointforcecmd "JointForceCmd" +- \subpage jointforcecmdcomponent "JointForceCmd" From 1c1e023babf3b778d895384a885941b288a6b6e6 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Fri, 5 Jan 2024 17:19:36 -0500 Subject: [PATCH 16/16] more specific on Configure Signed-off-by: Mabel Zhang --- tutorials/using_components.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tutorials/using_components.md b/tutorials/using_components.md index 76261f1440..717beea566 100644 --- a/tutorials/using_components.md +++ b/tutorials/using_components.md @@ -56,10 +56,15 @@ The signatures of those interfaces are specified in We will assume that these interfaces are implemented in functions called `Configure()` and `*Update()` in a system. -Note that because entities are created when the world is loaded, at the time -`Configure()` is called, it may be that not all entities have finished loading. -At the time `*Update()` is called, you are more likely to have all the -entities. +Note that when `Configure()` is called, all the elements in the parent element +of the plugin have been loaded. +For example, if the plugin is attached to a ``, all the elements in that +`` would have been loaded. +Similarly for ``. +However, if you need to access entities outside the plugin's parent element, +they may not have finished loading at the time the plugin's `Configure()` is +called. +Then you may need to access those entities later, in `*Update()`. ## Case studies