.. _PlatformInterface:

PlatformInterface
=================

.. cpp:namespace:: pilot::PlatformInterface

Interface
---------

The `PlatformInterface` is an interface to the hardware abstraction module running on a platform.
It allows access to hardware features such as digital inputs / outputs, analog inputs, power relays and the LCD.

Most functions require a special permission, see :ref:`pilot.permission_e`.


Functions
---------

Charging Functions
^^^^^^^^^^^^^^^^^^

.. cpp:function:: void charge()
	
	Attempts to charge the platform's batteries when connected to a charging station. Will return upon completion of charging process.
	In case of an error (such as no contact to the charging station) an exception will be thrown.
	Requires permission ``CHARGE``.
	
.. cpp:function:: void start_charging()
	
	Attempts to start the charging process at a charging station. Returns immediately in case of success, or throws an exception.
	Requires permission ``CHARGE``.
	
.. cpp:function:: void stop_charging()
	
	Stops the charging process at a charging station. Returns immediately in case of success, or throws an exception.
	Requires permission ``CHARGE``.
	
	
Input / Output Functions
^^^^^^^^^^^^^^^^^^^^^^^^

.. cpp:function:: void set_relay(int channel, bool state)
	
	Switch a relay on or off, depending on ``state``. ``channel`` is an index from 0 to 3 (in most cases) denoting the relay to switch.
	Requires permission ``RELAY_CONTROL``.
	
.. cpp:function:: void set_digital_output(int channel, bool state)
	
	Switches a digital output to the specified ``state``. ``channel`` is an index from 0 to 15 (in most cases) denoting the output pin.
	Requires permission ``RELAY_CONTROL`` as well as an installed `IOBoard`.
	
.. cpp:function:: void set_display_text(string line)
	
	Sets the first line on the LCD to the given text, for the next 30 seconds.
	Requires permission ``DISPLAY_CONTROL``.
	
.. cpp:function:: void wait_for_digital_input(int channel, bool state)
	
	Waits for a digitial input to reach the specified ``state``. If it's already reached will return immediately.
	``channel`` is an index from 0 to 15 (in most cases) denoting the input pin.
	Requires permission ``CONST_REQUEST`` as well as an installed `IOBoard`.
	
	
Other Functions
^^^^^^^^^^^^^^^
	
.. cpp:function:: void shutdown()
	
	Will terminate the process, shutdown the machine and turn off the platform.
	Cannot be undone except by turning on the platform by hand again.
	Requires permission ``SHUTDOWN_HOST``, see :ref:`vnx.permission_e`.