.. include:: pictures.rst



Basic interface
***************

To interact with the robot there is a dedicated :term:`Python` module :py:mod:`ozobot`. This is the one module that
shall be imported by the user in any program. Module consists of two major parts:

- :py:mod:`ozobot` module itself contains all related enumerators which may be used by user when communicating
  with a robot.

- :py:meth:`ozobot.get_robot` getter which returns an object representing one robot. The robot object
  (:py:class:`~ozobot.advanced.Bot` for synchronous or :py:class:`~ozobot.advanced.BotAsync` for asynchronous access)
  is all you need to tell the robot to "do something". Simply said, robot object represents your physical robot.



Module ozobot
=============

.. automodule:: ozobot
    :imported-members:

In some cases, especially in the future when this interface may be extended, it is beneficial to know the current
OzoPy API version. For this purpose the version of the ozobot module is defined here.

.. autoclass:: Version
   :members:



Access the robot
================

As mentioned above, a robot shall be exclusively accessed using :py:meth:`ozobot.get_robot`. This getter returns a
:term:`Python` object :py:class:`~ozobot.advanced.Bot` (or eventually :py:class:`~ozobot.advanced.BotAsync`).
Every robot object can control exactly one robot.

.. autofunction:: get_robot



Environment and error handling
==============================

Similar to other :term:`Python` modules, the `ozobot` module also uses exceptions with custom exception error type
:py:class:`~ozobot.OzobotError` derived from ``RuntimeError``.

.. autoclass:: OzobotError
   :members:

.. autoclass:: ErrorCode
   :members:

.. autoclass:: EnvironmentInfo
   :members:



Robot enums
===========

In order to communicate with a robot, it is sometimes handy to have some "dictionary" of words which the robot is able
to understand. One option is to use strings (``"LEFT"``, ``"RIGHT"``, ``"RED"``, ``"GREEN"``, ...),
however strings have their own disadvantages, as parsing of them may be not that fast as their numeric (integer)
representation. It is also more easy to miss-spell a command (e.g. to use ``"FRONT1"`` instead of ``"FRONT 1"``).
In this case, intellisense is even unable to give you a good hint. Therefore, enumerators have been used
for communication with the robot. Enumerators are objects which have exactly one meaning
(e.g. :py:class:`~ozobot.advanced.Lights.FRONT_1` means first front LED light). It is also possible to combine
more enums (e.g. ``FRONT_1 | FRONT_2`` means that the first two front LEDs are affected by the command).

Here is the list of all enumerators usable with robot:


.. autoclass:: Directions
   :members:

.. autoclass:: Lights
   :members:

.. autoclass:: Note
   :members:

.. .. autoclass:: ProximitySensorLocation
..    :members:

.. autoclass:: LineColor
   :members:

.. autoclass:: SurfaceColor
   :members: