.. _alsonar-api:

ALSonar API
===========

:ref:`Overview <alsonar>` | API

.. seealso::

   - :ref:`naoqi-sensors`
   - :ref:`Sonars Hardware <hardware-sonar>`

Namespace : **AL**

.. code-block:: cpp

  #include <alproxies/alsonarproxy.h>

Method list
-----------

.. cpp:class:: ALSonarProxy

  * Methods:

    * :cpp:func:`ALSonarProxy::getCurrentPeriod`
    * :cpp:func:`ALSonarProxy::getCurrentPrecision`
    * :cpp:func:`ALSonarProxy::getMyPeriod`
    * :cpp:func:`ALSonarProxy::getMyPrecision`
    * :cpp:func:`ALSonarProxy::getOutputNames`
    * :cpp:func:`ALSonarProxy::getSubscribersInfo`
    * :cpp:func:`ALSonarProxy::subscribe`
    * :cpp:func:`ALSonarProxy::unsubscribe`
    * :cpp:func:`ALSonarProxy::updatePeriod`
    * :cpp:func:`ALSonarProxy::updatePrecision`

Event list
----------

* :naoqi:event:`SonarLeftDetected`
* :naoqi:event:`SonarRightDetected`
* :naoqi:event:`SonarLeftNothingDetected`
* :naoqi:event:`SonarRightNothingDetected`

.. seealso::

  * :ref:`Methods inherited from ALModule <almodule-api>`

Methods
-------

.. cpp:function:: int ALSonarProxy::getCurrentPeriod()

  Gets the current period.

  :return: Refresh period (in milliseconds).

.. cpp:function:: float ALSonarProxy::getCurrentPrecision()

  Gets the current precision.

  :return: Precision of the extractor.

.. cpp:function:: int ALSonarProxy::getMyPeriod(const std::string& name)

  Gets the period for a specific subscription.

  :param name: Name of the module which has subscribed.

  :return: Refresh period (in milliseconds).

.. cpp:function:: float ALSonarProxy::getMyPrecision(const std::string& name)

  Gets the precision for a specific subscription.

  :param name: name of the module which has subscribed

  :return: precision of the extractor

.. cpp:function:: std::vector<std::string> ALSonarProxy::getOutputNames()

  Get the list of values updated in ALMemory.

  :return: Array of values updated by this extractor in ALMemory

.. cpp:function:: AL::ALValue ALSonarProxy::getSubscribersInfo()

  Gets the parameters given by the module.

  :return: Array of names and parameters of all subscribers.

.. cpp:function:: void ALSonarProxy::subscribe( const std::string& name, const int& period, const float& precision )

  Subscribes to the extractor. This causes the extractor to start writing information to memory using the keys described by getOutputNames(). These can be accessed in memory using ALMemory.getData("keyName"). In many cases you can avoid calling subscribe on the extractor by just calling ALMemory.subscribeToEvent() supplying a callback method. This will automatically subscribe to the extractor for you.

  :param name: Name of the module which subscribes.

  :param period: Refresh period (in milliseconds) if relevant.

  :param precision: Precision of the extractor if relevant.

.. cpp:function:: void ALSonarProxy::subscribe(const std::string& name)

  Subscribes to the extractor. This causes the extractor to start writing information to memory using the keys described by getOutputNames(). These can be accessed in memory using ALMemory.getData("keyName"). In many cases you can avoid calling subscribe on the extractor by just calling ALMemory.subscribeToEvent() supplying a callback method. This will automatically subscribe to the extractor for you.

  :param name: Name of the module which subscribes.

.. cpp:function:: void ALSonarProxy::unsubscribe(const std::string& name)

  Unsubscribes from the extractor.

  :param name: Name of the module which had subscribed.

.. cpp:function:: void ALSonarProxy::updatePeriod( const std::string& name, const int& period )

  Updates the period if relevant.

  :param name: Name of the module which has subscribed.

  :param period: Refresh period (in milliseconds).

.. cpp:function:: void ALSonarProxy::updatePrecision( const std::string& name, const float& precision )

  Updates the precision if relevant.

  :param name: Name of the module which has subscribed.

  :param precision: Precision of the extractor.


Events
------

.. naoqi:event:: SonarLeftDetected(float dist)

  raised when there is someting in front of NAO (left side) at less than 0.5m.

  :param dist: the obstacle distance in meter


.. naoqi:event:: SonarRightDetected(float dist)

  raised when there is someting in front of NAO (right side) at less than 0.5m.

  :param dist: the obstacle distance in meter


.. naoqi:event:: SonarLeftNothingDetected(float val)

  raised when there is nothing in front of NAO nor on his left side.

  :param val: always 0.0


.. naoqi:event:: SonarRightNothingDetected(float val)

  raised when there is nothing in front of NAO nor on his right side.

  :param val: always 0.0