.. _monitor:

Monitor
=======

.. toctree::
   :hidden:

   tutos/index

**See also**

* :ref:`Camera Viewer Tutorial<monitor-camera-tutorial>`

What is Monitor
---------------

Monitor is a desktop application which is installed along with :ref:`Choregraphe
<choregraphe>`, as a part of Aldebaran Robotics' software suite. Monitor is
dedicated to give you an elementary feedback from your robot and a simple
access to its camera settings.

It runs on Mac, Windows and Linux.

Its modular architecture allows you to load plugins in different mobile
widgets, each of them being connected to the robot of your choice. That is to
say you can connect several robots at a time!

3 plugins are available:

- :ref:`Camera Viewer<monitor-camera>`

- :ref:`Memory Viewer<monitor-memory>`

- :ref:`Laser Viewer<monitor-laser>` -  restricted to Laser Head NAO owners.


You can open as many plugins as you want, and arrange them by dragging
them with the mouse.

.. warning::
   Opening twice the same plugin widget connected to the same robot is
   possible, but not supported.


.. _monitor-start:

Getting Started
----------------

To launch one of the Monitor plugins:

1. Run the executable file of the same name, located in your Choregraphe installation folder.

The following window is displayed.

.. image:: /medias/desktop/monitor/monitor_start.png

2. Select a plugin in the **Load Plugin** menu.

The **Browse robots** dialog box is displayed. See :ref:`connection-widget`.

3. Select the NAO to monitor.

4. Click on **Connect to** button.

A new widget is added is added to the main window.


.. _monitor-camera:

Camera Viewer
-------------

This plugin is dedicated to view a robot camera, configure it, take
pictures and record videos, through a complete panel.

To load the Camera Viewer plugin into Monitor, see the :ref:`Getting
Started<monitor-start>` section. Once loaded, the following panel is displayed:

.. image:: /medias/desktop/monitor/monitor_camera_viewer1.png

Video Widget
++++++++++++

On the right side of the panel, you can find a widget to display video frames,
with few controls below.

.. |monitor-camera-play| image:: /medias/desktop/monitor/play.png
.. |monitor-camera-pause| image:: /medias/desktop/monitor/pause.png
.. |monitor-camera-record| image:: /medias/desktop/monitor/record_start.png
.. |monitor-camera-stop| image:: /medias/desktop/monitor/record.png
.. |monitor-camera-snapshot| image:: /medias/desktop/monitor/snapshot.png

=========================    ==================================================
The Button ...                Allows you to ...
=========================    ==================================================
|monitor-camera-play|        Start retrieving and displaying images from your
                             robot in the video widget.
|monitor-camera-pause|       Pause video display and stops requesting images.
|monitor-camera-record|      Start recording a video.
|monitor-camera-stop|        Stop recording the video and prompts for a
                             destination file.
|monitor-camera-snapshot|    Take three pictures (a,b,c) of what the robot
                             sees. The files will be saved to:
                             **/home/nao/.local/share/naoqi/vision/{timestamp}{a,b,c}.jpg**
=========================    ==================================================

.. note::
   The video record has a frame rate of 15 fps, 320*240 with MJPG compression.

On the left side of the panel, two tabs are available.


 .. _monitor-camera-settings:

Video Settings tab
+++++++++++++++++++

In the **Video settings** tab, you can configure the camera.

The following settings have an impact limited to the current camera viewer:

*  **Framerate:** set the maximum framerate you want to display. The lower the
   lighter will be the charge for both your robot's CPU and your LAN.

   .. warning::
      High rates of high resolution frames sometimes cannot be reached.
      You can ensure better conditions by stopping all consuming programs and
      by setting a wired connection with your robot.

*  **Resolution**

*  **Black and white**

*  **Mark detection:** detect NAOmarks and locate them on the image.

*  **Vision recognition:** detect learnt objects and locate them on the image.

The following settings impact all the modules which uses the camera, as they directly set the
video device settings:

*  **Select bottom camera:** switches between head's front and bottom cameras.

*  **Exposure:** check **Auto exposition** to automatically set the exposition
   time. When unchecked, **Exposure** slider is enabled to let you set the
   parameter manually. A long exposition time may slow the framerate, but gets
   a brighter image with less noise.

*  **Gain:** check **Auto gain** to automatically set the gain. When unchecked,
   **Gain** slider is enabled to let you set the parameter manually. A great
   gain will make a brighter image, but may amplify noise.

*  **Exposure correction:** additional exposure correction taking place after
   exposure and gain operation.

*  **White balance:** check **Auto white balance** to automatically set the
   white balance. When unchecked, **Blue / Red chroma:** sliders are enabled
   to let you set color proportions in the image manually.

*  **Brightness / Contrast / Hue**

*  **Vertical / Horizontal flip**

.. _monitor-camera-video:

Video Recorder tab
++++++++++++++++++
In the **Video Recorder** tab, you can choose the filename of the video you want to record.


.. _monitor-memory:

Memory Viewer
--------------

This plugin allows you to watch the data held by the :ref:`ALMemory module
<memory>` of a given NAOqi. Number-like data evolution can also be plotted.
This is very useful to diagnose behaviors through the internal data they use.

You can also follow hardware data like those you can see on your :ref:`NAO's
web page<opennao-web-page>` in the Advanced > Hardware section.

**Architecture overview**

.. figure:: /medias/desktop/monitor_stm_viewer_diag.png

There are a lot of data keys in :ref:`ALMemory<memory-almemory>`. That is why it is
recommended to select a restricted set of keys to watch, saved as an XML
**configuration file**, instead of gathering all the values, which is much
slower.

When you load the Memory Viewer plugin, as explained in :ref:`Getting Started
<monitor-start>` section, several possibilities are offered:

.. figure:: /medias/desktop/monitor/monitor_config_dialog.png


#. **New configuration file:** select a new set keys to track.

#. **Open configuration file:** select a previously saved set of keys.

#. **Do not use a config file (slow):** select every data key and filter them
   manually.

Once you have your configuration set up, the plugin will load its main window:

.. image:: /medias/desktop/monitor/monitor_memory_viewer.png

Plot Widget
++++++++++++

On the right side of the widget, you can see the plot viewer. Every key which
option **Graph** is checked will be shown in this plot.

Managing the Key list
+++++++++++++++++++++

On the left side of the widget, is displayed the list of keys defined
in the configuration file. The list shows several columns:

*  **Name**

*  **Watch:** whether to track the value or not.

*  **Graph:** whether to add the value to the plot. Overrides **Watch**, as
   the value must be tracked to be plotted.

*  **Type:** the value type. Can be **bool**, **int**, **float**, **string**
   or **invalid**.

*  **Value:** the value.

*  **Color:** the color of the curve representing the key values in the plot.

Below the list, you can also select **Watch all** or **Graph all**, to easily
have an overiew of all the keys.

Managing the Subscription Mode
+++++++++++++++++++++++++++++++

*  **Subscription Mode** controls the refresh rate of the key list values. When
   selecting the mode "Every <nb> ms", you will be prompted the refresh period
   you like. Selecting the mode "No subscription" disables automatic update of
   the values.

*  The blue arrow button allow you to refresh manually the values of
   the list. This is useful whenever you set the **Subscription mode** to "No
   subscription".

.. note::
   The subscription period parameter does not affect the plot scroll. It may
   only affect plot resolution.

Managing configuration file
++++++++++++++++++++++++++++

You can save every change you have done on this panel by clicking the
save button in the **Save/Merge config** section, at the bottom left of the
widget.

You can also import configuration files using the second button, so that it is
merged with your current configuration.

Managing the plot
+++++++++++++++++

Along with this view, few options below are available:

*  **Start/Stop graph:** start / stop value plotting.

*  **Speed in pixel/second:** set here the plot auto-scrolling speed.

*  **Autoscale:** when checked, the widget will zoom the plot to fit exactly
   the minimum and maximum values displayed. **Min** and **Max** are enabled
   only when **Autoscale** is disabled, and allows you to set the vertical
   bounds of the plot manually.


.. _monitor-laser:

Laser Viewer
------------

This feature is only available to NAO Laser Head owners.

This plugin allows you to easily display what is seen by the laser telemeter.

To load the Laser Monitor, use the **Load Plugin** menu, as described
in the :ref:`Getting Started<monitor-start>` section. Once the plugin is loaded and
you have connected the desired robot, the Laser Monitor appears this way:

.. image:: /medias/desktop/monitor/allaser_lasermonitor.png

Distances mesured by the laser sensor, are projected as cross dots on a polar
graph, with the correct angular ratio and offsets.

The scrollbar at the bottom of the widget simply filters the points, so you
can focus on closer obstacles, it has no effect on the laser sensor.

:ref:`Read more about the Laser Head and its module ALLaser<allaser>`.

.. _monitor-troubleshooting:

FAQ
----

Why some controls are disabled
+++++++++++++++++++++++++++++++

- If some controls of Monitor are disabled, it might mean that something is
  going wrong with your connection, but usually it just means the corresponding
  parameter is disabled.