<<PackageHeader(rcll_fawkes_sim)>>
== Introduction ==
This package provides topics and services specific for the ROS integration with the [[https://www.fawkesrobotics.org/projects/rcll-sim/|simulation]] of the [[http://www.robocup-logistics.org|RoboCup Logistics League]] (RCLL) that is also used for the [[http://www.robocup-logistics.org/sim-comp|Planning Competition for Logistics Robots In Simulation]]. The simulation environment is based on [[http://gazebosim.org|Gazebo]] and [[https://www.fawkesrobotics.org|Fawkes]]. Detailed information about the simulation is available on the [[https://www.fawkesrobotics.org/projects/rcll-sim/|RCLL simulation website]].

The main node of this package provides access to the global pose of the robot, light signal information perceived by the robot, feedback from zone exploration, and a service to trigger navgraph generation. Additional nodes allow for automatic sending of beacons and skill execution integration (not necessary anymore, it still exists for reference if you want to interface directly with Fawkes).

The nodes should each operate in a robot-specific namespace. For an example see the included launch files.

If you use the provided USB stick, you do not need to worry about the requirements and installation requirements, it is all setup and this page only documents the available interfaces/API. Use the following instructions if you want to setup the simulation on your own system.

== Requirements ==
 * A desktop-full installation of Indigo, Jade, or Kinetic (our primary toolchain is based on Fedora 23 or later, but Ubuntu 14.04 or later will also work)
 * [[http://gazebosim.org|Gazebo]] 5 or later (if using Indigo, you must build from source using the latest system version, the included version 2 will not work)
 * [[https://www.fawkesrobotics.org/projects/rcll-sim|RCLL Simulation]], [[https://trac.fawkesrobotics.org/wiki/Carologistics/Gazsim-Setup-2015|setup instructions]] (the following components are part of the installation instructions)
   * [[https://www.robocup-logistics.org/refbox|RCLL referee box]]
   * [[https://github.com/robocup-logistics/gazebo-rcll|Gazebo models and plugins]]
   * [[https://www.fawkesrobotics.org/projects/rcll2016-release|Carologistics RCLL 2016 release]] (to be published in January 2017)
 * [[fawkes_msgs]]
 * [[rcll_fawkes_sim_msgs]]
 * [[rcll_ros]] consisting of [[rcll_ros_msgs]] and [[rcll_refbox_peer]]

For general setup instructions to setup ROS and Fawkes on your system please have a look at our wiki for [[https://trac.fawkesrobotics.org/wiki/FawkesOnFedora|installation on Fedora]], or [[https://trac.fawkesrobotics.org/wiki/FawkesOnUbuntu|Ubuntu]].

== Running the Simulation with ROS Integration ==
{{{#!wiki caution
'''The following assumes that you have successfully'''
 * installed ROS indigo, jade, or kinetic including the additional packages mentioned in the requirements
 * have a working and sufficiently recent version of Gazebo
 * setup the simulation consisting of gazebo-rcll, llsf-refbox, and fawkes-robotino (if any of those appear unknown to you check the [[https://trac.fawkesrobotics.org/wiki/Carologistics/Gazsim-Setup-2015|simulation setup instructions]] again)
}}}

Then it is time to [[https://trac.fawkesrobotics.org/wiki/Carologistics/Gazsim-Setup-2015#StarttheSimulation|start the simulation]]. First, run without the ROS integration and with the default agent that comes with the simulation.
{{{
cd fawkes-robotino/bin
./gazsim.bash -x start -r -a -t -n1
}}}
This opens a separate terminal with several tabs. Please see the [[https://trac.fawkesrobotics.org/wiki/Carologistics/Gazsim-Setup-2015#RunningaGame|instructions to run a game]] in the simulation that gives an overview of the tabs and what to do to start the game. Once you set the game to the exploration phase the robots should start moving. If you are at this point, excellent!

Then it is time to run the simulation with the ROS integration. We modify the command above to the following.
{{{
cd fawkes-robotino/bin
./gazsim.bash -x start -n 1 -r -t \
  --ros-launch-main rcll_fawkes_sim:rcll_fawkes_sim_all_1robot.launch
}}}
This will run the simulation without the original agent (no "-a" flag) and with the appropriate ROS nodes for a single robot (the robot should still appear in the refbox shell as before and {{{rostopic list}}} should show many topics, also in the robot1 namespace.

Then we instruct the robot to move to a specified machine. To do this, run the actionlib client:
{{{
rosrun actionlib axclient.py /robot1/skiller fawkes_msgs/ExecSkillAction
}}}
Then in the "Goal" box enter the following:
{{{
skillstring='ppgoto{place="C-CS1-O"}'
}}}
This instructs the robot to go with global path planning to the output side of the first cyan cap station. The robot should then start moving and the goal should show as completed once the position has been reached.

At this point you are ready to go! Have a look at the [[https://trac.fawkesrobotics.org/wiki/Carologistics/skills|list of available skills]] and make the robot do as you wish.

== Getting Help ==
If you run into trouble, please join the [[https://groups.google.com/forum/#!forum/logrobcomp|planning competition's Google group]] to ask questions.

== Nodes ==
This package contains the following nodes.

=== rcll_fawkes_sim ===
This is the main node providing RCLL-specific information.
{{{
#!clearsilver CS/NodeAPI
pub {
  0.name= rcll_sim/explore_zone_info
  0.type= rcll_fawkes_sim_msgs/ExplorationZoneInfo
  0.desc= This is used to emit special feedback during the execution of the [[https://trac.fawkesrobotics.org/wiki/Carologistics/skills/explore_zone|explore_zone skill]]. Describes certainty whether a machine has been detected in a zone. This allows, for example, to skip zones for which it cannot be determined with certainty that it contains a machine, for example because a robot was passing to this robot's field of view, and re-visit this zone later.<<BR>><<BR>>The state can be unknown, definite yes or no, or maybe, e.g., spurious registering of an obstacle, might also have been a passing robot, recommended to re-visit later if there is time. See the [[https://trac.fawkesrobotics.org/wiki/Carologistics/skills/explore_zone|explore_zone skill documentation]] for further details.

 1.name= rcll_sim/mps_marker_array
 1.type= rcll_fawkes_sim_msgs/MPSMarkerArray
 1.desc= Provides information to the markers currently visible to the robot.

 2.name= rcll_sim/mps_light_state
 2.type= rcll_fawkes_sim_msgs/MPSLightState
 2.desc= Information about the light currently in sight. Note that this also contains the information whether any light is visible at all at the moment. This could be used to write a custom behavior during exploration for light signal handling or to read out the machine state during production (which is not strictly necessary, as the information is distributed in the machine info topic of the [[rcll_refbox_peer]] node.

 3.name= rcll_sim/amcl_pose
 3.type= geometry_msgs/PoseWithCovarianceStamped
 3.desc= This gives the position of the robot in the global coordinate frame (see rulebook for the origin and alignment of this frame). It is based on the localization data and thus does contain noise and is subject to a (small) delay.<<BR>><<BR>>Note that the very same information is available through the transforms system [[tf2]] as it is published by the Fawkes plugin [[https://trac.fawkesrobotics.org/wiki/Plugins/ros-tf|ros-tf]].
}

srv {
 0.name= rcll_sim/navgraph_generate
 0.type= rcll_fawkes_sim_msgs/NavgraphWithMPSGenerate
 0.desc= If the navgraph generation is to be performed on custom information use this service to do so, e.g., to add additional points of interest or to generate the graph after doing a custom exploration. When running the simulation with the "-t" flag, the graph is automatically generated from ground truth.
}
}}}

=== rcll_beacon_sender ===
This node allows to periodically send a beacon signal to the referee box. Ideally, the same operation will be performed by your system's executive to signal aliveness of the robot and readyness to perform its task. In this case, the source of this nodes serves as an example. If it is not possible that the executive performs this task, this node may be run as an alternative. Note, however, that failures of the executive may go unnoticed then.

{{{
#!clearsilver CS/NodeAPI
sub {
 0.name= rcll_sim/amcl_pose
 0.type= geometry_msgs/PoseWithCovarianceStamped
 0.desc= Used to fill in the position information of beacon signals.
}

srv_called {
 0.name= rcll/send_beacon
 0.type= rcll_ros_msgs/SendBeaconSignal
 0.desc= Called periodically (once per second) to trigger sending of a beacon signal.
}
}}}

=== fawkes_skiller ===
This node provides an action to execute skills through the [[https://www.fawkesrobotics.org/projects/behavior-engine/|Lua-based Behavior Engine]], more specifically through its Fawkes implementation [[https://trac.fawkesrobotics.org/wiki/Plugins/skiller|skiller (skill execution and run-time]]. The current version of Fawkes provides the [[https://trac.fawkesrobotics.org/wiki/Plugins/ros-skiller|ros-skiller]] which serves the same purpose (and provides exactly the same ROS message API), please see its documentation on how to execute skills.

The fawkes_skiller node is used as it more easily supports remapping to push each robot into its own namespace.

{{{
#!clearsilver CS/NodeAPI
pub {
 0.name= skiller_status
 0.type= fawkes_msgs/SkillStatus
 0.desc= Provides monitoring of the skiller status, e.g., whether a skill is being executed and whether it succeeded or failed.
}
goal {
 0.name= skiller/goal
 0.type= fawkes_msgs/ExecSkillGoal
 0.desc= This formulates the skill string to be executed by a skiller. See the [[https://trac.fawkesrobotics.org/wiki/Plugins/skiller|skiller documentation]] for specifics on this string.
}
result {
 0.name= skiller/result
 0.type= fawkes_msgs/ExecSkillResult
 0.desc= Upon failure, contains an error string. Note that the [[actionlib]] server state machine is used to indicate success or failure.
}
feedback {
 0.name= skiller/feedback
 0.type= fawkes_msgs/ExecSkillFeedback
 0.desc= No feedback is provided.
}
}}}