  -----------------------------
  MobileRobots - MobileEyes(TM)
  ----------------------------

2.2.4                           March 28, 2009

Copyright (c) 2004, 2005 ActivMedia Robotics, LLC. 
Copyright (c) 2006 - 2009 MobileRobots Inc.
All rights reserved.

The license for use of this software is described in the LICENSE.txt file.

MobileEyes(TM) is a graphical-user interface (GUI) for remote
control of a MobileRobots or ActivMedia Robotics intelligent mobile platform. 


Contents:
  Getting Started
  Basic Operation
  Toolbars
  Map and Robot
  Driving the Robot
  Controlling the Camera
  Robot Server Configuration
  Schedules

                  Getting Started
                  ===============

MobileEyes is a general user interface to the full variety of MobileRobots
ARCS products as well as development software.  MobileEyes connects over 
a network with any ARCSinside(TM) robot (running the ARAM server), with a 
central multi-robot server, or with another ArNetworking-based server 
(e.g. ARNL's example guiServer, or the example ArNetworking serverDemo).

Because MobileEyes is able to function with a wide variety of systems, 
which have a variety of configuration options and optional features, 
note that not all MobileEyes features are available or relevant to all circumstances. 

To launch MobileEyes in Windows, choose 
Start menu->Programs->MobileRobots->MobileEyes->MobileEyes or double-click
the MobileEyes icon, such as on the desktop.

In Linux, choose MobileEyes from the Gnome or KDE menu, or type
/usr/local/MobileEyes/MobileEyes in a terminal window. (Linux MobileEyes
requires that you are running X-Windows.)

MobileEyes communicates with the server via TCP/IP networking (even if
you are connecting to an ArNetworking server on the same computer).
When MobileEyes starts up, enter a hostname ("robot1", for example) or
IP address ("192.35.225.50", for example) in the "Robot Server:" field to
tell it where the robot server is located on the network. MobileEyes'
start up dialog displays the last accessed address or hostname.
Choose other recently used addresses from Robot Server's drop down menu.

If you have a user name and password for accessing this robot, enter
them in the appropriate fields. Not all robot servers are configured
to require a secure login; if this is the case, you may leave one or both
of these fields blank.

  Note: A user name and password are only required if the robot server
  has been configured to require user log in.  If user logins are
  not enabled in the robot software configuration, then you do not
  need to specify a user or password.

If you do not have a multi-robot central server, you can still control
multiple robots with the same MobileEyes by listing the robots' server
names in the Server Name field, separating each with a comma: MobileEyes
will make a seperate connection for each robot. 

Once you have entered the Server Name, click the Connect button to
access the robot over the network. You may cancel the connection by
clicking the Quit button. And if it cannot connect with the robot after
a few moments, it may tell you why the connection failed and then try
again. If it loses connection during a session, MobileEyes will give you
the option to reconnect without having to stop and restart the GUI.

Once connected, one of the first things the robot server does is send MobileEyes 
a copy of the map it is using to navigate its environment.  That map and 
the location of the robot in that map, goals, as well as other operating 
information is displayed in MobileEyes' Map window, as well as in the status
bar at the bottom of the window.


              Basic Operation
              ===============

Some of the more common MobileEyes features and operations are described 
below. This README is not a comprehensive manual. For more detail, please 
consult other manuals and documentation that came with your robot.

  Tip: Hold your mouse pointer over a control or button to see a longer 
  description of its function.

  Another Tip:  For even more information, or for a description of an 
  entire pane's features, select the Main Menu, Help, What's This? item
  and then click on the control or pane.

MobileEyes' display consists of several toolbars and panes.  Which panes,
toolbars, and buttons within toolbars are available depend on your robot
server's capabilities and configuration. Panes may also be enabled and disabled
using the View menu.  Toolbars may be enabled and disabled by right-clicking
on the toolbar area. Labels on the toolbar buttons may be enabled and disabled
by right-clicking on the toolbar area and choosing Customize, or by choosing
the Toolbar Labels item in the View menu.

 * At the top of MobileEyes is the menu bar and toolbars. 

 * The robot mode fields is always visible above the map pane. These indicate
   the current mode of the robot, and the status of that mode. 

 * The MobileEyes status bar is always visible at the bottom of the window.
   This displays status of the robot's battery, the network connection,
   MobileEyes drive mode, and mapping indicator.

 * The map pane displays the robot's self-determined location in its map,
   along with live sensor readings.  Aspects of the map and different sensor
   readings can be enabled and disabled using the Map toolbar or the Map menu.

 * If enabled and supported by the robot, a pane will also be displayed for 
   goals and routes. The Routes/Goals pane may be enabled and disabled
   using the View menu.

 * If enabled and supported by the robot, a pane will also be displayed 
   for live video, and possible audio controls as well. The Audio/Video
   pane may be enabled and disabled using the View menu.

 * If enabled, a pane will be displayed below the map pane to display some 
   details about the robot's status and activity. This pane may be 
   enabled/disabled using the Details and the Custom Details items in the
   View menu.
  
 * If you are controlling multiple robots with MobileEyes, a pane will be 
   displayed with each robot's status information, with which you may
   select a robot to control.

You can resize these panes by clicking and dragging edges that separate
panes.


  Tip: Some panes can be operated by the keyboard, e.g. to move the camera
  or drive the robot. Only one pane can accept keyboard input at a time. 
  Select a pane for keyboard input by clicking on it; the selected pane
  will contain a dark blue border.

Some panes include small toolbars with commands specific to the 
features contained within that pane. For example, a set of controls
for using the pan/tilt camera appears above the video image. Hover
your mouse pointer over a button to see a description of that button.


                  Toolbars
                  ========

The first time you start MobileEyes, most of its toolbars and buttons
appear in the display. Thereafter, you may customize the display for
the current and future sessions:

Right-click anywhere in a toolbar or in the main menu bar to activate
a pop-up menu of display options. To hide an entire toolbar, click to
deselect its checkbox.  Or click again to re-select it for display. To
hide an individual toolbar button, select the pop-up
Customize... option. Then, in the Customize Toolbar dialog's Current
Tool Button list, select the buttons you want or don't want displayed
and use the Add and Remove buttons to hide or display them.


                Map and Robot
                =============

In the Map pane, MobileEyes displays an icon representing the robot
and locates it and its travels in a 2-D map of its operating
environment.  The Map pane also contains dynamic "artifacts" that
represent what the robot's various sensors "see" in the real
environment, such as the blue-dots associated with laser readings.
Other transient lines and dots appear depending on the robot's
activities, such as a multi-segmented blue line that represents the
path the robot has planned for traversing from one goal to the next.

By default, MobileEyes starts up with the entire map visible and the
robot located somewhere within it.  You can zoom and pan the map in this
mode, but depending on those settings, your robot may disappear
off-screen.  Check the Map menu Center on Robot option or the 
corresponding toolbar button to put the robot in the center of the Map
pane and have the map move around it.  However, you cannot pan the map
when the robot is centered.
 
Zoom and pan the Map pane contents to get the best view by using the
toolbar buttons, the mouse, or the keyboard. They are not exclusive;
you may pan with the mouse and zoom from the keyboard, for example.

To pan the map contents (robot not centered) with the mouse, click and
hold the right button and move the mouse around. Zoom in and out by
rotating the mouse wheel. If you do not have a mouse wheel you can
shift left click to zoom out and shift right click to zoom in.

Also, when selected for keyboard input, you may pan the map with the left, 
right, down, and up arrow keys.  To zoom, hold the Shift key and press 
the up-arrow key (in) or down-arrow key (out).

Select the Map menu's Fit in Window option to automatically reset the map
pan and zoom to show the entire map; this can be used if you pan too far 
away from the map contents.

If you are connected to mulitple robots with MobileEyes, a tool will
appear in the toolbar called "Pick Robot". With this tool enabled, you
can click on a robot icon in the map to select that robot for control.


             Goals and Routes
             ================

If the robot has a map, it may contain named goals. These goal names 
correspond to actual places and may also specify which direction 
(heading) the robot should turn to when it reaches the goal. Goal names 
appear in the Routes and Goals pane.

To have your robot go to goal, simply double-click the goal name in the
pane, or left-click to highlight the goal name and then click the Go
To Goal button. The path that the robot plans to take to the goal
appears in the Map pane. As it progresses to the goal, the robot
automatically will adjust its path in order to avoid transient
obstacles, such as someone who is standing in its way.

You can also have the robot go to any point in the map, as long as
its path is not completely blocked, such as by a wall. Just click
the Map pane to select it, hold down the Ctrl key, and then click the 
mouse at the spot where you want the robot to go.  To select a final
heading, drag the mouse before releasing the mouse button.

In addition to goals, ARCSinside based robots can also perform Routes -- 
a series of goals and other tasks.  You can manually initiate a route 
using the Routes list above the goals.


            Driving the Robot
            =================

You may drive the robot manually from the keyboard or with the mouse. 
When manually driven, the robot normally drives in "Safe Mode", and prevents
driving into any obstacle detected by the robot's sensors.

  Warning: Safe Mode can only prevent the robot from colliding with obstacles
  it is able to detect or which are marked as forbidden areas in the map. 
  Be especially careful of small or trasparent obstacles, stairwells and other 
  undetectable objects that are not marked in the map.  Also, note that the 
  allowable distances from obstacles, as well as within what range obstacles 
  are searched for, are configurable (even configurable to zero).

To drive the robot using the mouse, click the toolbar's Drive button to 
display the Drive Robot tools.  Press the arrow buttons to move the robot
in the corresponding direction.  (The up arrow means forward, and the down
arrow means reverse.)  The speed may be adjusted using the speed slider
on the toolbar.  If the robot server is configured to allow Unsafe drive 
mode, then Safe Mode may be disabled. 

  Warning: Only use Unsafe Mode when you can clearly see the robot
  from your operating station.

When the Drive Robot tools has focus (as indicated by a dark blue rectangle
around all four buttons), you may also manually drive the robot with the
keyboard arrows.  

When arrow key drive is enabled, the robot will drive forward when you 
hold the up-arrow key; will slow to a stop and eventually go in reverse 
if you hold the down arrow key; and will turn to the right or left when 
you hold the left- or right-arrow key, respectively.  The speed at which 
these keys make the robot move is controlled by the Speed slider in the 
robot toolbar or by the Tools->Preferences->Keyboard.

Click the Stop button or simply let go of the arrow keys to stop the
robot. Click the robot arrow button or select a different drive mode
to change your robot's driving habits.

The robot can also be driven by clicking on the Map pane to select it,
then using the arrow keys while holding down the Ctrl key.


          Controlling the Camera
          ======================

Some robot servers are able to send images from a camera to MobileEyes,
and also control the pan, tilt, zoom and some settings of the camera.
To view the camera images and controls, enable the Video view from
the View menu.

Pan, tilt, and zoom slider controls may be found beneath the camera 
image in the Video view pane.

If the server supports them, then four special camera control modes
are also availabe: point-with-mouse-click, keyboard, joystick, and 
look-at-goal.

To enable point-with-mouse-click mode, press its button in the small 
toolbar immediately above the camera image.   When in this mode, 
clicking on the camera image with the left mouse button will
cause the camera to pan and tilt to look at the clicked point. The 
camera can be zoomed using the zoom slider, or the mouse wheel.

To operate with the keyboard, click on the camera image, and press the 
left- or right-arrow key to pan the camera left or right, and press the 
up- or down-arrow key to have it tilt up or down, Hold the Shift key down 
and then press the up- or down-arrow key to zoom in or out.

To operate with the keyboard, click on the camera image, and press the 
left- or right-arrow key to pan the camera left or right, and press the 
up- or down-arrow key to have it tilt up or down, Hold the Shift key down 
and then press the up- or down-arrow key to zoom in or out.

If you have a joystick, you can enable joystick control of the camera
using the button in the toolbar immediately above the camera image.

Look-at-goal mode causes the camera to pan and tilt to point towards the
robot's next goal in a route (as best as it is able).


               Robot Server Configuration
               ==========================

The robot server contains many parameters that affect the robot's 
behavior.  To configure the robot server, choose Robot Configuration
from the Tools menu.  Several levels are available: "Basic" is for
more basic or simple adjustments of robot behavior, "Intermediate"
and "Advanced" are for a variety of parameters that affect more fundamental
aspects of the robot behavior to your environment or needs but will
have greater impact on its performance or ability to function correctly. 
Depending on software, you may also have other levels of "Expert" or
"Factory": these options normally never need to be changed.

When you click "OK" or "Apply", MobileEyes sends the configuration
changes to the server and waits for the pending changes to be applied. 
The server will apply the changes only when the robot enters an "idle" 
mode; for example, if the robot is driving to a goal, the configuration 
changes will not be applied until it reaches the goal and enters the 
default Stop mode, or you press the "Stop" button to place the server 
into the Stop mode; if a robot is on a continuous patrol of goals, the
changes will be applied after finishing a round of goals, or when you
explicitly stop the robot with the "Stop" button.   Changes will also
be applied when the robot is idle after stopping to dock. While changes are 
pending and waiting to be applied, "Update Pending" will be displayed
in the status bar at the bottom of the MobileEyes window, with an animated
"spinner" icon.


  Tip: It is recommended that you save a backup copy of the robot
  configuration before changing parameters.  Then, you can revert to
  your known-to-work backup if any changes cause problems. Use the
  "File Options" menu near the bottom of the Robot Configuration dialog
  to save configuration files to your local filesystem, and later load
  them on the robot.

                 Schedules (optional feature)
                 =========

Some ARCSinside robots come equipped with a scheduler, which enables
them to automatically perform routes and special tasks at specified times
during each day of the week, week after week, including special holidays.
MobileEyes displays the robot's schedule in a tab next to Routes
and Goals. Schedule entries include both past and future routes and tasks.

Hold your mouse pointer over the small robot icon in MobileEyes' time
column to see what time the robot thinks it is: it may not be the current,
universal time. The robot follows the schedule based on what time it has,
not necessarily what time it might really be. Adjust robot time with
SetNetGo(TM)(https://<robot hostname or IP address).

The status of a schedule entry can be determined from its appearance.
MobileEyes displays current and future schedule entries with a light yellow
background. Completed schedule entries have a gray background. An icon
indicates status:

Icon                     Status
------                 ------------------------
Green triangle         In progress
Checkmark              Completed successfully
Checkmark minus        Completed with errors
X mark                 Completed unsuccessfully
! mark                 Late

Hold your mouse pointer over a schedule entry to obtain a summary of its
status and execution times.

If you want to interrupt the scheduled patrol, you have two choices:

 -- Turn on the Pause button below the calendar.  This sends a stop 
    command to all robots that are currently patrolling scheduled 
    routes.  A plain pause icon appears next to the Schedule tab label.  
    The schedule will not restart until you click the Resume button.  

 -- Command all available robots to do something else (such as stop, or 
    go to a goal).  Your commands always supercede the scheduled routes. 
    In this case, once a robot becomes available again, the schedule will 
    automatically continue after a configurable timeout.  The pause icon 
    next to the Schedule tab label is decorated with a green arrow to 
    indicate that the schedule will automatically restart.  If you want 
    to restart the schedule more quickly, click the Resume button once it 
    is enabled.  

When you use the Resume button, if any scheduled routes are overdue, a 
dialog box will appear.  You have the choice of continuing the schedule 
from the time it was paused with the robot patrolling all overdue routes, 
or restarting from the current time and skipping all overdue routes. 
