Supervision services
====================

MORSE exposes several services to remotely manage and monitor the simulator.

These services are automatically exposed on a socket interface, on port 4000.

All these services belongs to a virtual component called ``simulation`` and
follows the normal syntax for socket requests.  Thus, a request to retrieve the
list of robots would look like this::


  > telnet localhost 4000
  Connected to localhost.
  > req1 simulation list_robots
  req1 OK ['Robot1', 'Robot2']

Or using ``pymorse``

.. code-block:: python

    import pymorse
    with pymorse.Morse() as sim:
        sim.rpc('simulation', 'get_camarafp_projection_matrix')
        sim.rpc('simulation', 'set_camarafp_far_clip', 1000)


Available services
------------------

- ``list_robots`` (no parameter): returns the list of the robots currently
  available in the simulation
- ``reset_objects`` (no parameter): reset the position of all objects in the
  simulation (in other words, restart the simulation)
- ``quit`` (no parameter): quit the game mode and so terminate the simulation
- ``activate`` (component_name): Activate the functionality of the specified component
- ``deactivate`` (component_name): Deactivate  the functionality of the specified component
- ``suspend_dynamics`` (no parameter): suspend the physics at the game engine
  level
- ``restore_dynamics`` (no parameter): re-enable the physics at the game
  engine level
- ``details`` (no parameter): returns a structure containing the details about
  the simulation currently running, including the list of robots, the list of
  services and datastreams, etc.
- ``set_log_level`` ``cmpnt`` (string) ``level`` (string): changes the
  level of logging for the component ``cmpnt`` to the level ``level``.
- ``get_scene_objects`` (no parameter): returns a hierarchical dictionary
  structure of all the objects in the scene along with their positions and
  orientations (as quaternions).
- ``set_object_visibility`` ``cmpnt`` (string) ``visible`` (bool): make the
  object referenced by ``cmpnt`` visible or invisible (it still exists at
  the physics level)
- ``set_object_dynamics`` ``cmpnt`` (string) ``state`` (bool): enable or
  disable the dynamics (physics) associated with component ``cmpnt``.
- ``set_object_position`` ``cmpnt`` (string) ``[x, y, z]`` (list) ``[roll
  pitch yaw]`` (optional list): move the object referenced by ``cmpnt`` to the
  specified ``position`` and optionally ``orientation``.
- ``set_camarafp_far_clip`` Set the CamaraFP's (MORSE's environment camera) far
  clipping distance. (float)
- ``set_camarafp_position`` Set the CamaraFP's world position. [x, y, z]
- ``set_camarafp_transform`` Set the CamaraFP's world space 4x4 transform matrix.
- ``set_camarafp_projection_matrix`` Set the CamaraFP's 4x4 projection matrix.
- ``get_camarafp_projection_matrix`` Get the CamaraFP's 4x4 projection matrix.

.. note::
  Simulation services are stored in :py:mod:`morse.core.supervision_services`.