Style, comments and instructions

Signed-off-by: Louise Poubel <[email protected]>

examples/plugin/Hello_world/CMakeLists.txt → examples/plugin/hello_world/CMakeLists.txt

@@ -1,15 +1,17 @@
 cmake_minimum_required(VERSION 3.10.2 FATAL_ERROR)
 
-ign_find_package(ignition-cmake2 REQUIRED)
+find_package(ignition-cmake2 REQUIRED)
 
 project(Hello_world)
 
-find_package(ignition-plugin1 REQUIRED COMPONENTS register)
+ign_find_package(ignition-plugin1 REQUIRED COMPONENTS register)
 set(IGN_PLUGIN_VER ${ignition-plugin1_VERSION_MAJOR})
 
 ign_find_package(ignition-gazebo4 REQUIRED)
+set(IGN_GAZEBO_VER ${ignition-gazebo4_VERSION_MAJOR})
+
 add_library(HelloWorld SHARED HelloWorld)
 set_property(TARGET HelloWorld PROPERTY CXX_STANDARD 17)
 target_link_libraries(HelloWorld
   PRIVATE ignition-plugin${IGN_PLUGIN_VER}::ignition-plugin${IGN_PLUGIN_VER}
-  PRIVATE ignition-gazebo4::ignition-gazebo4)
+  PRIVATE ignition-gazebo${IGN_GAZEBO_VER}::ignition-gazebo${IGN_GAZEBO_VER})

examples/plugin/hello_world/HelloWorld.cc

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+// We'll use a string and the ignmsg command below for a brief example.
+// Remove these includes if your plugin doesn't need them.
+#include <string>
+#include <ignition/common/Console.hh>
+
+// This header is required to register plugins. It's good practice to place it
+// in the cc file, like it's done here.
+#include <ignition/plugin/Register.hh>
+
+// Don't forget to include the plugin's header.
+#include "HelloWorld.hh"
+
+// This is required to register the plugin. Make sure the interfaces match
+// what's in the header.
+IGNITION_ADD_PLUGIN(
+    hello_world::HelloWorld,
+    ignition::gazebo::System,
+    hello_world::HelloWorld::ISystemPostUpdate)
+
+using namespace hello_world;
+
+// Here we implement the PostUpdate function, which is called at every
+// iteration.
+void HelloWorld::PostUpdate(const ignition::gazebo::UpdateInfo &_info,
+    const ignition::gazebo::EntityComponentManager &/*_ecm*/)
+{
+  // This is a simple example of how to get information from UpdateInfo.
+  std::string msg = "Hello, world! Simulation is ";
+  if (!_info.paused)
+    msg += "not ";
+  msg += "paused.";
+
+  // Messages printed with ignmsg only show when running with verbosity 3 or
+  // higher (i.e. ign gazebo -v 3)
+  ignmsg << msg << std::endl;
+}
+
+
+

examples/plugin/Hello_world/HelloWorld.hh → examples/plugin/hello_world/HelloWorld.hh

@@ -18,25 +18,29 @@
 #ifndef SYSTEM_PLUGIN_HELLOWORLD_HH_
 #define SYSTEM_PLUGIN_HELLOWORLD_HH_
 
+// The only required include in the header is this one.
+// All others will depend on what your plugin does.
 #include <ignition/gazebo/System.hh>
 
+// It's good practice to use a custom namespace for your project.
 namespace hello_world
 {
-
-  class HelloWorld: 
-
+  // This is the main plugin's class. It must inherit from System and at least
+  // one other interface.
+  // Here we use `ISystemPostUpdate`, which is used to get results after
+  // physics runs. The opposite of that, `ISystemPreUpdate`, would be used by
+  // plugins that want to send commands.
+  class HelloWorld:
     public ignition::gazebo::System,
     public ignition::gazebo::ISystemPostUpdate
-
   {
-
-    public: HelloWorld();
-
-    public: ~HelloWorld();
-
+    // Plugins inheriting ISystemPostUpdate must implement the PostUpdate
+    // callback. This is called at every simulation iteration after the physics
+    // updates the world. The _info variable provides information such as time,
+    // while the _ecm provides an interface to all entities and components in
+    // simulation.
     public: void PostUpdate(const ignition::gazebo::UpdateInfo &_info,
-                const ignition::gazebo::EntityComponentManager &_ecm);
+                const ignition::gazebo::EntityComponentManager &_ecm) override;
   };
-
 }
-#endif 
+#endif

examples/plugin/hello_world/README.md

@@ -0,0 +1,42 @@
+# Hello world
+
+This example contains the bare minimum that's necessary to create a Gazebo
+system plugin.
+
+## Build
+
+From the root of the `ign-gazebo` repository, do the following to build the example:
+
+~~~
+cd ign-gazebo/examples/plugins/hello_world
+mkdir build
+cd build
+cmake ..
+make
+~~~
+
+This will generate the `HelloWorld` library under `build`.
+
+## Run
+
+The plugin must be attached to an entity to be loaded. This is demonstrated in
+the `hello_world_plugin.sdf` file that's going to be loaded.
+
+Before starting Gazebo, we must make sure it can find the plugin by doing:
+
+~~~
+cd ign-gazebo/examples/plugins/hello_world
+export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+~~~
+
+Then load the example world:
+
+    ign gazebo -v 3 hello_world_plugin.sdf
+
+You should see green messages on the terminal like:
+
+```
+[Msg] Hello, world! Simulation is paused.
+```
+
+Toggle the play / pause buttons to see the message change.

examples/plugin/hello_world/hello_world_plugin.sdf

@@ -0,0 +1,11 @@
+<?xml version="1.0" ?>
+<sdf version="1.6">
+  <world name="default">
+    <!--
+      System plugins can be loaded from <plugin> tags attached to entities like
+      the world, models, visuals, etc.
+    -->
+    <plugin filename="HelloWorld" name="hello_world::HelloWorld">
+    </plugin>
+  </world>
+</sdf>