Basic interaction with another simulator using HLA : the Billard example :tag:`hla`
===================================================================================

In this tutorial, you will learn how to connect Morse with another
simulator engine, using HLA. We will use the default example simulator
provided by the CERTI implementation, a billard simulator.

.. warning::

    The tutorial assumes that you are familiar with the HLA concept.

Setup
-----

First, verify that you have installed the required Morse HLA software, by following 
the HLA section in the :doc:`installation notes <../installation/mw/hla>`.

Before running a distributed simulation using HLA/CERTI, it is necessary to
launch the RTIG (Run Time Interface Gateway) which will handle the
synchronisation between the different simulators in the federation. So, open a
console and execute::

  $ rtig

We will now add our first instance to the federation, ``billard``, a poolroom
model provided by CERTI. So, in another console, start::

  $ billard -n foo -f Test -F Test.fed

where:

- **foo** is the name of the ambassador in the federation
- **test** is the name of the federation
- **Test.fed** is the name of the file describing the FOM of the federation.
  It is provided by CERTI.

You can press Enter, and normally, you will see a red ball moving. Stop it now.

Reflecting attributes in Morse
------------------------------

We will now show how to define your scenario in order to communicate with this
federation.


First, we need to create one robot to reflect the ball in the poolroom.

.. warning::

    Currently, there is no support for dynamic robot creation, so the robot name
    should be carefully chosen to match instances from other federates.


.. code-block:: python

    foo = Morsy()

The ``Test.fed`` exposes two interesting attributes ``PositionX`` and
``PositionY``. In Morse, we will consider the :doc:`teleport actuator
<../actuators/teleport>` to reflect the position of an external robot.

.. code-block:: python

    foo = Morsy()
    
    teleport = Teleport()
    foo.append(teleport)
    

Now, we need to connect this to the HLA world. We use the
``test_certi_intput`` which is designed for this specific purpose.

.. code-block:: python

    from morse.builder import *

    foo = Morsy()
    foo.scale = [10.0, 10.0, 1]

    teleport = Teleport()
    teleport.add_stream('hla', 'morse.middleware.hla.certi_test_input.CertiTestInput')
    foo.append(teleport)

    env = Environment('empty')
    env.configure_stream_manager(
            'hla', 
            fom = 'Test.fed', name = 'Morse', federation = 'Test', sync_point
            = 'Init', time_sync = True, timestep = 1.0)

    ground = bpymorse.get_object('Ground')
    ground.scale = [255.0, 55.0, 0.0065]
    ground.location = [250.0, 50.0, -0.06]
    env.set_camera_clip(0.1, 1000)
    env.set_camera_location([250, 50, 350])
    env.set_camera_rotation([0.0, 0.0, 0.0])
    env.set_camera_speed(10.0)

.. warning::

    The parameters in ``configure_stream_manager`` are really important, see
    :doc:`the hla middleware documentation <../middlewares/hla>` for a complete description.

.. note::

    You can play with the timestep value to see how it interacts with other
    simulators.

.. note::

    The ``ground`` and ``env`` configuration here is not very important, but
    used to look like more a poolroom.

Now, restart the billard, and in another console, morse. Normally, Morse
should be blocked, waiting for the synchronisation point. Press Enter in the
billard console, and you should see Morsy moving according the ball movement.

Exporting attributes from Morse
--------------------------------

Now, we will create another robot, and allow it to reflect its position in the
federation. For that, we will use a :doc:`pose sensor <../sensors/pose>` and a
keyboard to control it. 

.. code-block:: python

    bar = Morsy()
    bar.translate(x = 12, y = 12)

    kb = Keyboard()
    bar.append(kb)

    pose = Pose()
    bar.append(pose)
    pose.add_stream('hla', 'morse.middleware.hla.certi_test_output.CertiTestOutput')

If you restart the billard and Morse, you should now see a new black ball on
the billard board. Moreover, if you move the robot in Morse with the keyboard, you
should see the black ball also moving in the billard board.

At the end, your file should look like ``$MORSE_ROOT/share/morse/examples/tutorials/tutorial_hla.py``.