View source for OpenMower Simulation

== Introduction ==
You can test the OpenMower software stack yourself by running a simulation where you can record a map and then have it mowed in a simulation on-screen. 

It's a bit rough around the edges, but it's a good way to see the software in action without hardware.

This mini-HOWTO is meant to save you a bit of detective work and get you started, not to be a comprehensive guide to the simulation.

== Prerequisites ==
You need the OpenMower software '''on a platform that has ROS and a graphical interface''' for rviz to be able to run and show the map. Ubuntu 20 on a desktop is a good choice, possibly on VM, VirtualBox is an excellent choice, if you do not already have a running Ubuntu 20 desktop environment.

* '''Install ROS on Ubuntu''': http://wiki.ros.org/noetic/Installation/Ubuntu - use the full install
** Note: make sure that you have the ROS environment set up in your terminal by <code>echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc</code>  and log out and back in.
* '''Install the OpenMower software:''' Use the instructions here: [[Setting up ROS on a Raspberry Pi (intended to be the Rover -- OpenMower)]]
** Make sure that you have had <code>catkin_make</code> succeed (may take a few tries, often 4 or more)

You need to have a game controller for controlling the simulated bot.

== Making sure the OpenMower environment is sourced ==
''Whenever you are doing anything in a terminal with OpenMower'', you need to make sure that ROS knows your OpenMower workspace.

In every terminal that you use: <code>source ~/OpenMower/ROS/devel/setup.sh</code>

== Running the simulation ==

=== Recording a map ===
[[File:VirtualBox enable USB.png|thumb|Enable USB ports on VirtualBox]]
Attach your joystick to a USB port. If you are on a VirtualBox, make sure that the USB port of your joystick / gamepad is mapped into your Ubuntu environment (see illustration).

Open a terminal and execute

<code>roslaunch ~/OpenMower/ROS/src/open_mower_ros/open_mower/launch/sim_mower_logic.launch</code>
[[File:Simulation running.png|thumb|OpenMower simulation running]]
This will launch rviz where you can see the Rover and the map.

Use your joystick to record a map and a base. On my gamepad, the buttons are

* 1 - enable movement
* 2 - start path recording
* 4 + ↓ - end path recording
* 3 - register base

Then exit rviz and the map will be recorded in <code>~/.ros/map.bag</code>

If you want to record a new map, delete the old one, <code>rm ~/.ros/map.bag</code>

=== Running the simulation ===
<code>roslaunch ~/OpenMower/ROS/src/open_mower_ros/open_mower/launch/sim_mower_logic.launch</code>

This will launch rviz with the map and rqt_reconfigure where you can control various parameters of the simulation.

You will need to press <code>manual_start_mowing</code> in rqt_reconfigure to start the simulation. You will probably need to zoom out, find your area and then zoom in again on that in rviz.

== Diagnostics / debugging / issues ==

=== Joystick ===
[[File:Which joystick to use.png|thumb|Which joystick to use]]
Your joystick needs to be transmitting messages on the topic /joy. To test that it does:

* Run <code>roslaunch ~/OpenMower/ROS/src/open_mower_ros/open_mower/launch/sim_record_area.launch</code>
* In a new terminal run <code>rostopic echo /joy</code>
You should see messages from the joystick streaming on screen. Test that pressing buttons etc. is reflected in the messages.

If not:

* Check which joysticks your Ubuntu installation knows: <code>ls -l /dev/input/js*</code>
* Try to add/adjust which joystick the recorder uses in sim_record_area.launch to use the correct joystick, see illustration here.

===Buttons===
The control buttons can be edited here:
*movement activation button
**File: <code>~/OpenMower/ROS/src/open_mower_ros/open_mower/launch/sim_record_area.launch</code>
**Line 17: <code><param name="~enable_turbo_button" value="4"/></code>
*area and base recording buttons
**File: <code>~/OpenMower/ROS/src/open_mower_ros/mower_area_recorder/src/area_recorder.cpp</code>
**Lines 61 ff.

==Additional notes / info==

===rviz and OpenMower on different machines ===
This is all running on one platform - the OpenMower simulation AND the graphical interface, hence the choice of desktop to have a graphical environment. In the real situation, the Rover with the OpenMower software is running on a headless Pi. If you still want to have the ability to see paths and maps (which is possible) in rviz, you need to do that on a separate desktop environment. That is possible. You can use the environment that you set up here, but the Rover and on the Desktop must be on the same network and need a little setup in your <code>~/.bashrc</code> to see each other as being part of the same ROS installation.

'''On Rover, in <code>~/.bashrc</code>'''

<code>export ROS_HOSTNAME=192.168.1.126 # replace with your ip for your Rover</code>

<code>export ROS_MASTER_URI=<nowiki>http://192.168.1.126:11311</nowiki> # same as above</code>

'''On Desktop, in <code>~/.bashrc</code>'''

<code>export ROS_HOSTNAME=192.168.1.123 # replace with your ip for your Desktop environment</code>

<code>export ROS_MASTER_URI=<nowiki>http://192.168.1.126:11311</nowiki> # eplace with your ip for your Rover</code>

==== Note on network visibility and guests on VirtualBox====
To make your Ubuntu installation running as guest in VirtualBox be able to have an externally accessible ip number and be able to talk to the Rover, you must

#use a cabled network (not Wifi!!) to your computer that acts as host for VirtualBox and your Ubuntu guest OS
#use a <code>Bridged Adaptor</code> to the cabled interface for the network setup in VirtualBox for your Ubuntu host.