.. _ui_usage:

Breakout Usage via GUI
======================

The following section provides a step-by-step explanation on how to initially
configure the CML :sup:`2` Breakout utility for a server, and then how the
active labs can be retrieved, enabled and used.


Server Configuration
--------------------

#. In a terminal, start the Breakout tool with ``breakout.exe ui`` (the actual
   tool name will be different depending on the platform used).

   .. seealso:: More about this can be found at the page that documents
      the :ref:`breakout_ui` command.

#. Launch your web browser and point it at http://localhost:8080 

#. Click on the **Configuration** tab at the top of the page.

   .. figure:: _static/bodoc_1.png
      :width: 800px
      :align: center
      :alt: alternate text

      **Figure 1**: Configuration Tab


#. Update the following information at a minimum:

   - **"Controller address"**: This can be either the IP address or the DNS name
     of the CML :sup:`2` server. It needs to include the ``https://`` and should
     not have any trailing slashes ``/``

   - **"Username"**:  The username used to authenticate with the CML :sup:`2` server

   - **"Password"**: The password used to authenticate with the CML :sup:`2` server

     .. note:: The Verify TLS certificates may need to be disabled, if the
        CML :sup:`2` server certificate is not trusted by the local PC.

     Other settings can be modified based upon the other executable options.

   - Click on **"Save"**.

   .. figure:: _static/bodoc_2.png
      :width: 800px
      :align: center
      :alt: alternate text

      **Figure 2**: Configuration Settings

.. warning:: If settings like "Listen Address" or "UI Server Port" were changed,
   then a restart of the utility is required to make those changes effective.
   Most other changes take effect immediately after saving them.


Lab Retrieval and Launch
------------------------

#. Launch your web browser and point it at `<http://localhost:8080>`_

#. Retrieve the list of Active Labs by clicking on the refresh icon.

   .. figure:: _static/bodoc_3.png
      :width: 800px
      :align: center
      :alt: alternate text

      **Figure 3**: Load labs from server

#. Enable the CML :sup:`2` Breakout utility for the specified lab by clicking
   on the on/off control on the right of the name.

   .. figure:: _static/bodoc_4.png
      :width: 800px
      :align: center
      :alt: alternate text

      **Figure 4**: Enabling a particular Lab

#. At this point, you can connect to your devices for that lab by attaching to
   your localhost with the specified port for that interface. If you do not know
   what the port is, you can view the mapping by clicking on the lab title as
   shown in the figure above.

#. Click on the enabled lab table row to display the lab details.

#. This screen allows you to enable or disable the CML :sup:`2` Breakout
   utility for the serial ports connecting to each device. On this screen the
   following information is available

   - **Serial Port per Device**: Displays if the virtual serial port is
     enabled, the associated localhost port number assigned to the port. The
     port number can be changed, but only when the port is "off" / disabled.

   - **Direct launch link**: A direct launch link is provided for machines that
     have the appropriate protocol mapped in their host operating system to
     launch the preferred Telnet or VNC application.

   - The port numbers will start with the number defined in the server
     configuration file. The default value is 9000. The port number then
     increments for each serial device for that node. Then the next node is
     assigned its ports.

   .. figure:: _static/bodoc_5.png
      :width: 800px
      :align: center
      :alt: alternate text

      **Figure 5**: View the lab details for a lab


.. note:: At this time, there is not a way to automatically sort off of the node
   label, but the node ID (which is generated as devices are added to a lab.)
   Ports can be modified manually, but that stays only with the Lab
   configuration file. If you want to re-use modified settings, it would be good
   to save that file with a different name, and then customize the method used
   to launch the CML :sup:`2` Breakout utility so that it specifies the server
   and configuration lab files to be used.
