Add example documentation for primary_pipeline_calibration

Author: urfeex

doc/examples.rst

@@ -4,6 +4,10 @@ Usage examples
 This library contains a number of examples how this library can be used. You can use them as a
 starting point for your own applications.
 
+All examples take a robot's IP address as a first argument and some of them take a maximum run
+duration (in seconds) as second argument. If the second argument is omitted, some of the examples
+may be running forever until manually stopped.
+
 .. note:: Most of these examples use the driver's headless mode. Therefore, on an e-Series (PolyScope 5) robot, the robot has to be
    in *remote control mode* to work.
 
@@ -15,4 +19,5 @@ starting point for your own applications.
    examples/freedrive
    examples/instruction_executor
    examples/primary_pipeline
+   examples/primary_pipeline_calibration
    examples/ur_driver

doc/examples/primary_pipeline_calibration.rst

@@ -0,0 +1,52 @@
+:github_url: https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/doc/examples/primary_pipeline_calibration.rst
+
+.. _primary_pipeline_calibration_example:
+
+Primary Pipeline Calibration example
+====================================
+
+This example is very similar to the :ref:`primary_pipeline_example`. However, it uses a
+specialized consumer that will analyze the calibration data sent from the robot instead of the
+``ShellConsumer``.
+
+Consumer setup
+--------------
+
+This example uses a specialized type of consumer that stores data about the received robot
+calibration.
+
+.. literalinclude:: ../../examples/primary_pipeline_calibration.cpp
+   :language: c++
+   :caption: examples/primary_pipeline_calibration.cpp
+   :linenos:
+   :lineno-match:
+   :start-at: class CalibrationConsumer
+   :end-at: };
+
+Since the producer is reading every package from the primary interface, the consumer has to be able
+to consume any primary package.
+
+Assemble the pipeline
+---------------------
+
+The rest of the pipeline setup is the same as in the other pipeline example, just that we create a
+``CalibrationConsumer`` instead of a ``ShellConsumer``:
+
+.. literalinclude:: ../../examples/primary_pipeline_calibration.cpp
+   :language: c++
+   :caption: examples/primary_pipeline_calibration.cpp
+   :linenos:
+   :lineno-match:
+   :start-at: // The calibration consumer
+   :end-at: calib_pipeline.run()
+
+Again, product handling will be happening in the background, so in the rest of the program we wait
+until the calibration consumer received and processed data and then print information about that:
+
+.. literalinclude:: ../../examples/primary_pipeline_calibration.cpp
+   :language: c++
+   :caption: examples/primary_pipeline_calibration.cpp
+   :linenos:
+   :lineno-match:
+   :start-at: while (!calib_consumer
+   :end-at: return 0

examples/primary_pipeline_calibration.cpp

@@ -31,8 +31,11 @@ class CalibrationConsumer : public urcl::comm::IConsumer<urcl::primary_interface
   }
   virtual ~CalibrationConsumer() = default;
 
+  // This will consume any primary package
   virtual bool consume(std::shared_ptr<urcl::primary_interface::PrimaryPackage> product)
   {
+    // Try to cast the product to a KinematicsInfo package. If that succeeds, we handle the
+    // calibration information.
     auto kin_info = std::dynamic_pointer_cast<urcl::primary_interface::KinematicsInfo>(product);
     if (kin_info != nullptr)
     {
@@ -105,11 +108,11 @@ int main(int argc, char* argv[])
 
   if (calib_consumer.isCalibrated())
   {
-    printf("The robot on IP: %s is calibrated\n", robot_ip.c_str());
+    printf("The robot on IP: %s is calibrated.\n", robot_ip.c_str());
   }
   else
   {
-    printf("The robot controller on IP: %s do not have a valid calibration\n", robot_ip.c_str());
+    printf("The robot controller on IP: %s does not have a valid calibration.\n", robot_ip.c_str());
     printf("Remeber to turn on the robot to get calibration stored on the robot!\n");
   }