.. _Running:

Running
=======

.. note:: If you received a license security dongle, make sure to have it attached.

You can always execute the supplied binaries directly, but for convenience
we provide little helper scripts that take care of some required command line
options.


Pilot
-----

In Windows execute the ``bin/run_pilot.bat`` file either in a terminal or by
double clicking on it.

In Ubuntu:

.. code-block:: sh

	cd ~/pilot
	./run_pilot.sh


Additional options can be provided to the scripts as such::

	./run_pilot.sh --LocalPlanner.vel_limits.max_trans_vel 0.5
	run_pilot.bat --LocalPlanner.vel_limits.max_trans_vel 0.5

Permanent options can be set by writing config files in ``config/local``, see :ref:`Configuration`.
For example a file ``config/local/LocalPlanner.json``:

.. code-block:: javascript

	{
		"vel_limits": {
			"max_trans_vel": 0.5
		}
	}

will set the default maximum velocity of the platform to 0.5 m/s.


Simulation
----------

The simulation binary will simulate the kinematics as well as sensor data
without accessing any hardware.
Otherwise there is no difference to ``run_pilot.sh``.

In Windows execute the ``bin/run_pilot_simulation.bat`` file either in a terminal
or by double clicking on it.

In Ubuntu:

.. code-block:: sh

	cd ~/pilot
	./run_pilot_simulation.sh




Replay
------

To run `PlatformPilot` in replay mode use the provided script:

.. code-block:: sh

	cd ~/pilot
	./run_pilot_replay.sh

It will try to connect to a running VNX player on ``/tmp/vnxplayer.sock``.
Replay mode is used to view what happened during a recorded drive.
Similar to simulation mode there is no hardware access.


Data Recording
--------------

To make a data recording use the provided script:

.. code-block:: sh

	cd ~/pilot
	./record_data.sh.sh

The resulting file will be in ``user/data/``.



Parameters
----------

It is possible to override the default configuration by either writing local config files in ``config/local/``
or by specifying parameters on the command line.

The following configuration options can be set for most executables above:

``self_test``
	If to perform a self test at the beginning. Will exit if it fails. (default = `true`)

``auto_shutdown``
	If to automatically shutdown the host machine in case platform is being turned off via the key switch. (default = `true`)
	
``with_hardware``
	If hardware modules should be started, ie. hardware is present on this machine and not on a remote. (default = `true`)

``enable_joystickmng``
	If to enable joystick input. (default = `true`)

``enable_http_server``
	If to enable HTTP server on port 8888. Needed for HTTP API, WebGUI, etc. (default = `true`)
	
``enable_taskhandler``
	If to enable the :ref:`TaskHandler` module. (default = `true`)
	
``enable_movechainhandler``
	If to enable the :ref:`MovechainHandler` module. (default = `true`)
	
``enable_opcua_server``
	If to enable the :ref:`vnx.opc_ua.Server` module. (default = `false`)
	
``opcua_proxy_map``
	A map of :ref:`vnx.opc_ua.Proxy` modules to start, [`module name` => `server address`].
	
``vnx_proxy_map``
	A map of :ref:`vnx.Proxy` modules to start, [`module name` => `server address`].
	
``vnx_server_map``
	A map of :ref:`vnx.Server` modules to start, [`module name` => `server endpoint`].

``vnx_jrpc_server_map``
	A map of :ref:`vnx.JRPC_Server` modules to start, [`module name` => `server endpoint`].

``footprint``
	Footprint of the platform as a JSON object, see :ref:`pilot.Footprint`.
	
``platform``
	Static platform information as a JSON object, see :ref:`pilot.PlatformInfo`.


By default the following servers are started:

``vnx.Server`` on ``.pilot_main.sock``
	Supports connections from the local machine via UNIX domain sockets, using the native VNX binary protocol.
	Almost all permissions are granted to clients connecting to this server, ie. no logins required.
	A :ref:`vnx.Proxy` is needed to connect. On Linux systems only.
	
``vnx.Server`` on ``0.0.0.0:5555``
	Supports connections from anywhere via TCP/IP sockets, using the native VNX binary protocol.
	Login is required to gain anything more than read-only permissions, see :ref:`users`.
	A :ref:`vnx.Proxy` is needed to connect.


In general, most applications accept the following command line arguments:

* The ``-h`` switch displays a small help message and exits.
* The ``-d`` switch increases the debug level of the terminal output
* The ``-c`` switch accepts a directory with configuration files.
  You can specify several directories by repeating the switch or by providing multiple directories at once.
  The order of directories matters, they are read from left to right, potentially overriding previous values.
* Finally, you can set specific config values directly on the command line.
  See :ref:`Configuration` for details.



Maps
----

The active :ref:`GridMap` and :ref:`RoadMap` are stored in the ``~/pilot/`` folder
as ``current_grid_map.grid`` and ``current_road_map.road``.

They can either be copied there by hand or uploaded via the :ref:`GTKGUI`.