[Joana] Documentation ctd

Roboy · Mar 22, 2018 · 9f71cc4 · 9f71cc4
1 parent 03bff64
commit 9f71cc4
Show file tree

Hide file tree

Showing 35 changed files with 215 additions and 323 deletions.
diff --git a/00_sphinx_documentation/documentation/BeRoboy/0_Introduction.rst b/00_sphinx_documentation/documentation/BeRoboy/0_Introduction.rst
@@ -1,6 +1,8 @@
 Introduction
 ============
 
+**NOTICE: THIS CODE IS NOT BEING MAINTAINED AND MAY THEREFORE NOT WORK CORRECTLY ANYMORE OR THE INFORMATION MAY BE OUTDATED**
+
 .. figure:: images/beroboy_poster.*
    :align: center
    :alt: BeRoboy™

diff --git a/00_sphinx_documentation/documentation/BeRoboy/1_UsersManual.rst b/00_sphinx_documentation/documentation/BeRoboy/1_UsersManual.rst
@@ -1,7 +1,7 @@
 User's Manual
 =============
 
-**NOTICE: THIS CODE IS NOT BEING MAINTAINED AS OF NOW**
+**NOTICE: THIS CODE IS NOT BEING MAINTAINED AND MAY THEREFORE NOT WORK CORRECTLY ANYMORE OR THE INFORMATION MAY BE OUTDATED**
 
 This manual will descripe the steps required to start BeRoboy.
 

diff --git a/00_sphinx_documentation/documentation/BeRoboy/2_DeveloperManual.rst b/00_sphinx_documentation/documentation/BeRoboy/2_DeveloperManual.rst
@@ -1,13 +1,13 @@
 Developer's Manual
 ==================
 
-*Note: We assume that you already have gone through the User's Manual and Getting Started to not repeat ourselves.*
+**NOTICE: THIS CODE IS NOT BEING MAINTAINED AND MAY THEREFORE NOT WORK CORRECTLY ANYMORE OR THE INFORMATION MAY BE OUTDATED**
 
 
 Gazebo Simulation
+
 -----------------
-For the gazebo part you need to create/ edit a launch/ world file(s). When the launch file is started it automa-
-tically loads the world (with all the surrounding objects) that has been specified and the version of roboy you have chosen.
+For the gazebo part a launch/ world file automatically loads the world (with all the surrounding objects) that has been specified and the version of Roboy which was chosen.
 
 
 **Example for a launch file:**

diff --git a/00_sphinx_documentation/documentation/BeRoboy/3_UseCases.rst b/00_sphinx_documentation/documentation/BeRoboy/3_UseCases.rst
@@ -1,7 +1,7 @@
 Use Cases
 =========
 
-**NOTICE: THIS CODE IS NOT BEING MAINTAINED AS OF NOW**
+**NOTICE: THIS CODE IS NOT BEING MAINTAINED AND MAY THEREFORE NOT WORK CORRECTLY ANYMORE OR THE INFORMATION MAY BE OUTDATED**
 
 The following use cases should demonstrate how the Unity side of BeRoboy deals with certain scenarios,
 it should show further which procedure calls are happening in the scene, that a developer

diff --git a/00_sphinx_documentation/documentation/BeRoboy/4_CurrentState.rst b/00_sphinx_documentation/documentation/BeRoboy/4_CurrentState.rst
@@ -1,6 +1,6 @@
 Current State
 =============
 
-**NOTICE: THIS CODE IS NOT BEING MAINTAINED AS OF NOW**
+**NOTICE: THIS CODE IS NOT BEING MAINTAINED AND MAY THEREFORE NOT WORK CORRECTLY ANYMORE OR THE INFORMATION MAY BE OUTDATED**
 
 As of now only virtual Roboys can be manipulated and controlled which are serving as subjects in the gazebo simulation. Some positions and rotations are not displayed properly, as translations and further positions and values changed. 
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/0_solution_strategy.rst b/00_sphinx_documentation/documentation/DevelopmentGraphs/0_solution_strategy.rst
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/1_building_block_view.rst b/00_sphinx_documentation/documentation/DevelopmentGraphs/1_building_block_view.rst
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/3_deployment_view.rst b/00_sphinx_documentation/documentation/DevelopmentGraphs/3_deployment_view.rst
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/images/board_full.JPG b/00_sphinx_documentation/documentation/DevelopmentGraphs/images/board_full.JPG
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/images/view_comparison.JPG b/00_sphinx_documentation/documentation/DevelopmentGraphs/images/view_comparison.JPG
diff --git a/00_sphinx_documentation/documentation/DevelopmentGraphs/images/view_single.JPG b/00_sphinx_documentation/documentation/DevelopmentGraphs/images/view_single.JPG
diff --git a/00_sphinx_documentation/documentation/GeneralUsage/2_for_users_and_developers.rst b/00_sphinx_documentation/documentation/GeneralUsage/2_for_users_and_developers.rst
@@ -19,12 +19,12 @@ The Roboy simulations which run in Gazebo is written in C++, which normally load
 The following links can be seen as a guideline, of course you can do
 the research by yourself.
 
-- Unity provides a lot of tutorials for the editor and the API with code samples and videos: https://unity3d.com/de/learn/tutorials
-- The UnifyWiki has a lot of example scripts for all kind of extensions: http://wiki.unity3d.com/index.php/Main_Page
-- StackOverflow is a forum where you can search for answers regarding your coding problems: http://stackoverflow.com/
-- UnityAnswers, similar to StackOverflow but only for Unity specific questions. The community is not as active and most questions
-  are really basic, so bear that in mind: http://answers.unity3d.com/
-- As we use ROS and our own custom messages, it is important to understand how ROS works and how ROS messages are built: http://wiki.ros.org/
-- Gazebo simulations rely on gazebo libraries, which are documented here: http://osrf-distributions.s3.amazonaws.com/gazebo/api/dev/index.html
-
-If you have any further questions about the project, feel free to contact the Roboy team, which will connect you with the people in charge. 
+- `Unity <https://unity3d.com/de/learn/tutorials>`_ provides a lot of tutorials for the editor and the API with code samples and videos.
+- `UnifyWiki <http://wiki.unity3d.com/index.php/Main_Page>`_ has a lot of example scripts for all kind of extensions.
+- `StackOverflow <http://stackoverflow.com/>`_ is a forum where you can search for answers regarding your coding problems.
+- `UnityAnswers <http://answers.unity3d.com/>`_, similar to StackOverflow but only for Unity specific questions. The community is not as active and most questions
+  are really basic, so bear that in mind.
+- As we use ROS and our own custom messages, it is important to understand `how ROS works <http://wiki.ros.org/>`_ and how ROS messages are built.
+- Gazebo simulations rely on gazebo libraries, which are documented `here <http://osrf-distributions.s3.amazonaws.com/gazebo/api/dev/index.html>`_
+
+If you have any further questions about the project, feel free to contact the Roboy team, which will connect you with the people in charge. 
diff --git a/...inx_documentation/documentation/Implementation/0_Unity_project_architecture.rst b/...inx_documentation/documentation/Implementation/0_Unity_project_architecture.rst
@@ -0,0 +1,23 @@
+General Project Architecture
+============================
+
+Building Blocks View
+--------------------
+
+.. figure:: images/buildingblocks.*
+   :alt: Bulding blocks overview
+
+   RoboyVR Experience has several neighbouring systems like the simulation and github,
+   it consists of various components like RoboyManager/Inputmanager and 
+   can be manipulated by the user through the HMD system and the controllers.
+
+Deployment View
+---------------
+
+.. figure:: images/deployment.*
+  :alt: Roboy simulation runs on a virtual machine, RoboyVR Experience runs on Unity.
+
+  Roboy simulation runs on Ubuntu on a seperate(virtual) machine, RoboyVR Experience runs on Unity.
+
+
+**Note:**  Further information about certain implementation strategies can also be found in the *Developer's* Manual sub-sections of the individual projects *BeRoboy*, *State Visualisation*, *Model World Loader* and *PaBi*.
diff --git a/...phinx_documentation/documentation/Implementation/0_system_scope_and_context.rst b/...phinx_documentation/documentation/Implementation/0_system_scope_and_context.rst
diff --git a/...tion/DevelopmentGraphs/2_runtime_view.rst → ...umentation/Implementation/1_Use_cases.rst b/...tion/DevelopmentGraphs/2_runtime_view.rst → ...umentation/Implementation/1_Use_cases.rst
@@ -1,6 +1,4 @@
-.. _runtime_view:
-
-Runtime View
+Use Cases
 ============
 
 Runtime Display Information regarding Roboyparts

diff --git a/...ntation/DevelopmentGraphs/4_Libraries.rst → ...umentation/Implementation/3_Libraries.rst b/...ntation/DevelopmentGraphs/4_Libraries.rst → ...umentation/Implementation/3_Libraries.rst
diff --git a/00_sphinx_documentation/documentation/Implementation/3_Selectionwheel.rst b/00_sphinx_documentation/documentation/Implementation/3_Selectionwheel.rst
diff --git a/00_sphinx_documentation/documentation/Implementation/4_ROSBridge.rst b/00_sphinx_documentation/documentation/Implementation/4_ROSBridge.rst
@@ -0,0 +1,132 @@
+ROSBridge
+=========
+
+ROS overview
+^^^^^^^^^^^^
+
+The ROSBridge is a main part of this project as it connects the Unity project on Windows and the simulation
+on Ubuntu. We recommend to have a look at the tutorials `here <http://wiki.ros.org/ROS/Tutorials>`_ to get a basic understanding
+of ROS. The short version follows below.
+
+The ROS core establishes connections between clients and creates topics.
+Topics are similar to a public blackboard, where entities can decide to publish - write on the blackboard, or subscribe - read from it.
+
+Publisher
+---------
+
+The publisher **sends** message over **one** topic. When you create the publisher you have to announce to ROS which type of message is to be sent as well as the name of the topic over which it is sent.  Therefore at first you have to advertise the new publisher with providing this information. Afterwards you can publish
+data with the defined message type.
+
+Subscriber
+----------
+
+A subscriber *receives* data from one topic. The topic name as well as the message type need to be defined and announced to the ROS server as was previously the case for teh publisher. 
+
+Every time a message is published, the subscribing entities receive these. A CallBack function is triggered which handles the received data **Note: this is handled using threads**. Here, it can parse the message and process it.
+
+Service
+-------
+
+A service works differently compared to the publisher and subscriber pattern. It serves like function call in which the the service is invoked via a topic. This means that you as the *service client* call the *service server* with the required data depending on the certain service via a *service request*. Then the server responds to you via a
+*service response*. This is useful when you need to do certain tasks only on rare occasions e.g. reset a world.
+
+
+Messages
+--------
+To communicate the necessary information, different standard or already defined messages can be chosen, addiitionally, new messages can be defined. As the communication is between a Ubuntu side and a Windows computer using a ROSBridge as a mediator, messages must to be defined on both sides and need to match exactly. 
+
+**Messages for the simulation**
+Examples can be found in the previously mentioned tutorials. The conversion from the message type to the `YAML format <https://en.wikipedia.org/wiki/YAML>`_, which is used by ROS, is automatically applied when implementing simulations and plugins using the designated libraries. The message needs to be defined in an extra file and its path must be sourced, so that ROS is able to find and use the message type.
+
+**Messages in Unity**
+In Unity, messages need to be converted manually. Looking at all custom messages defined in Unity gives a good insight into the structure and construction of messages. A ToYAMLString() method for each message type is defined, to parse the given message into a format expected and accepted by ROS. On the other side, messages which arrive at the Unity side need to be parsed so that these can be further processed. 
+
+**Important**
+
+Gazebo and Unity have different coordinate systems, therefore, to avoid confusion and missing or superfluous conversions, **outgoing coordinates and rotations must be translated into the Gazebo coordinate space**, while **incoming messages must be parsed to Unity coodrinate space**. It is sufficient to only implement constructors and ToYamlString() parser, in case messages of this type are only designed to be published.
+
+.. code-block:: c#
+
+  public override string ToYAMLString()
+  {
+	  // format the message ... 
+      return string_in_yaml_format;
+  }
+
+Respectively, messages which will only ever be received only need to define a function which parses the messages into the correct format, as can be seen below. 
+
+.. code-block:: c#
+
+  public CustomMessage(JSONNode msg)
+  {
+      // parse message here
+  }
+
+Wrap-Up
+-------
+
+**Messages**
+To define a custom message: 
+
+1) Define and source the message on Ubuntu side
+2) Create a class for the message on Windows side: Derive the message class from *ROSBridgeMsg* so the ROSBridge knows that this is a message. Implement the constructor and/or the ToYAMLString method depending on the purpose. 
+
+**Subscribers/Publishers/Services**
+With a newly created message, create a subscriber, publisher or or a service for this message type and a given topic name. To implement this on the Ubuntu side, just follow the tutorial.
+
+In Unity, a new subscriber/ publisher / service needs to be defined. Each of this ros types have different requirements to be valid but each of these have to derive from the corresponding base class, e.g. CustomPublisher : ROSBridgePublisher
+
+The publisher needs to have:
+
+1) GetMessageType()
+2) GetMessageTopic()
+
+The subscriber needs to have:
+
+1) CallBack()
+2) GetMessageType()
+3) GetMessageTopic()
+4) ParseMessage()
+
+The service needs to have:
+
+1) ServiceCallBack
+
+All methods must be public and static. If you forget to implement one of these the ROSBridge will throw an expcetion
+which tells you which method is missing.
+
+
+Wrapper
+^^^^^^^
+
+Originally we got the template from `this git project <https://github.com/michaeljenkin/unityros>`_. To make it more
+usable and developer-friendly we wrote a wrapper. The Wrapper consists of two main classes.
+
+**ROSObject**
+
+A ROSObject retrieves all ros subscrivers, publishers and services which are components of the same gameObject. These are communicated to the *ROSBridge* to announce all entities on start-up and remove all entities when disabling this ROSObject.
+
+**ROSBridge**
+
+The ROSBridge is the main part of the wrapper. It forwards the needed calls to *ROSBridgeWebsocketConnection* which establishes a websocket and is the actual backend.
+
+Scene Setup
+^^^^^^^^^^^
+
+When you created your custom publishers etc. and messages you need to edit your scene such as the ROSBridge is informed of these. First a ROSBridge prefab must be present in the scene (either drag and drop or create a custom version). Enter the IP adress and port of the ROS server to which you want to connect.
+
+.. figure:: ../images/rosbridge.png
+	:align: center
+	:alt: ROSBridge
+
+	ROSBridge
+
+Attach the ROSObject script to the game object which also holds the subscriber, publisher and / or service components. 
+
+.. figure:: ../images/ros_object.png
+	:align: center
+	:alt: ROSObject
+
+	ROSObject
+
+Now, all publishers and subscribers should automatically be registered and announced as well as removed according to the ROSObject state. 
diff --git a/...on/documentation/Implementation/4_API.rst → ...on/documentation/Implementation/5_API.rst b/...on/documentation/Implementation/4_API.rst → ...on/documentation/Implementation/5_API.rst