From 223902166609ea692a0f25ee6b8d0fa37cc2dca6 Mon Sep 17 00:00:00 2001
From: Mirko Waechter <mirko.waechter@kit.edu>
Date: Thu, 7 Aug 2014 12:21:38 +0200
Subject: [PATCH] Added RemoteRobot doc from Core

---
 etc/doxygen/pages/remoterobot.dox | 79 +++++++++++++++++++++++++++++++
 source/RobotAPI/CMakeLists.txt    |  1 +
 2 files changed, 80 insertions(+)
 create mode 100644 etc/doxygen/pages/remoterobot.dox

diff --git a/etc/doxygen/pages/remoterobot.dox b/etc/doxygen/pages/remoterobot.dox
new file mode 100644
index 000000000..5e15af3fe
--- /dev/null
+++ b/etc/doxygen/pages/remoterobot.dox
@@ -0,0 +1,79 @@
+/**
+\page remoterobot Robot State and Remote Robot
+
+\section remoterobot-start Starting a RobotStateComponent
+
+The RobotState component serves as a central component for storing all robot related data. For now this data covers the current joint angles of the robot.<br>
+The RobotStateComponent implements a KinematicUnitListener, hence it reacts on all joint updates that are reported by a KinematicUnit component. An exemplary startup script could look like this
+\code
+
+export CORE_PATH=${ArmarXHome_DIR}/Core
+export CORE_BIN_PATH=$CORE_PATH/build/bin
+export SCRIPT_PATH=$CORE_BIN_PATH
+
+$SCRIPT_PATH/startApplication.sh $CORE_BIN_PATH/KinematicUnitSimulationRun --Ice.Config=./config/Armar3Config.cfg &
+$SCRIPT_PATH/startApplication.sh $CORE_BIN_PATH/RobotStateComponentRun --Ice.Config=./config/Armar3Config.cfg &
+
+\endcode
+
+With the correspondign configuration in ./config/Armar3Config.cfg:
+
+\code
+# setup for KinemticUnitSimulation
+ArmarX.KinematicUnitSimulation.RobotFileName = Armar3/data/robotmodel/ArmarIII.xml
+ArmarX.KinematicUnitSimulation.RobotNodeSetName = Robot
+ArmarX.KinematicUnitSimulation.ObjectName = Armar3KinematicUnit
+
+#setup for RobotStateComponent
+ArmarX.RobotStateComponent.RobotFileName = Armar3/data/robotmodel/ArmarIII.xml
+ArmarX.RobotStateComponent.RobotNodeSetName = Robot
+ArmarX.RobotStateComponent.ObjectName = RobotStateComponent
+\endcode
+
+
+\section remoterobot-access Accessing the RobotStateComponent
+
+The RobotStateComponent provides several methods for accessing the current configuration of the robot and for getting a snapshot of the current state which is compatible with
+models of the Simox/VirtualRobot framework. With these models the whole functionality of Simox (http://simox.sf.net) can be used, e.g. IK solving, collision detection or motion and grasp planning.
+
+\par Creating a synchronized model (RemoteRobot)
+
+A RemoteRobot is a synchronized robot data structure which always represents the current state of the robot.
+Be aware, that any operations on this model (e.g. IK solving) may take long (e.g. 100 ms) due to the heavy network communication overhead.
+For complex operations it is suggested to create a local clone of the data structure and to synchronize this clone before working with it (see below).
+
+The Remote Robot can be created by getting the proxy to the RobotStateComponent and grabbing a RemoteRobot:
+\code
+std::string robotStateComponentName = "RobotState";
+armarx::RobotStateComponentInterfacePrx robotStateComponent = getProxy<RobotStateComponentInterfacePrx>(robotStateComponentName);
+armarx::RemoteRobotPtr remoteRobot(new RemoteRobot(robotStateComponent->getSynchronizedRobot()));
+\endcode
+
+The remoteRobot object can now be accessed in order to get joint angles or to convert cooridnate frames.
+
+\par Create a local robot and synchronize it by hand
+
+When complex operations should be performed on a robot model the use of a RemoteRobot could slow down the computation since each joint access induces a network transfer.
+Hence the RemoteRobot offers a method to create a local copy of the remote data.<br>
+If only the structure of the robot is needed (without 3D models, useful e.g. for kinematic calculations, coorinate transformations, etc),
+the following method can be used to create a local clone of the robot:
+\code
+VirtualRobot::RobotPtr robot = RemoteRobot::createLocalClone(robotStateComponent);
+\endcode
+The robot instance can be manually synchronized with the remote data structure (i.e. copy the joint angle values) by calling:
+\code
+RemoteRobot::synchronizeLocalClone(robot,robotStateComponent);
+\endcode
+
+If a complete robot model (including 3d models) is needed, you can pass a filename to a local file to allow the system to load the complete robot:
+\code
+std::string filename = "Armar3/data/robotmodel/ArmarIII.xml";
+ArmarXDataPath::getAbsolutePath(robotFile,robotFile);
+VirtualRobot::RobotPtr robot = RemoteRobot::createLocalClone(robotStateComponent, filename);
+\endcode
+
+This model can be synchronized in the same way as the first model.
+
+
+
+*/
diff --git a/source/RobotAPI/CMakeLists.txt b/source/RobotAPI/CMakeLists.txt
index 4c0666de8..1ba3dced6 100644
--- a/source/RobotAPI/CMakeLists.txt
+++ b/source/RobotAPI/CMakeLists.txt
@@ -10,3 +10,4 @@ add_subdirectory(drivers)
 add_subdirectory(robotstate)
 add_subdirectory(robotstate/remote)
 add_subdirectory(operations)
+
-- 
GitLab