1. Introduction

  You can access ARIA at different levels, from simply sending commands to the robot through ArRobot to development of higher-level intelligent behavior using Actions. (For a description of how to integrate parts of ARIA with your other code, see Piecemeal Use of ARIA.)
    An auxiliary library called ArNetworking is also included with ARIA. ArNetworking provides an easy to use, extensible framework for communication with remote programs over a network, such as MobileEyes.

  Click a class or function link to view its details. A selection of the most important ARIA classes is listed in Important Classes in the menu to the left, as well as Optional Classes, Device Interface Classes, Utility Classes and Predefined ArAction Classes. 

   Important Classes：

These classes are essential far all programs using Aria to control a robot. More...

 ArRobotConnector also parses some command line arguments if supplied, which can explicitly specify a remote hostname and/or port to connect with via TCP, or to specify an alternate local serial port to use for robot connection, as well as other options. If a program uses ArRobotConnector, running it with the "-help" command line argument will print a list of options.

3. Specifying Details about Robot and Device Connections

    The device interface and connector classes (ArRobotConnector, ArLaserConnector, etc.) need information about what devices are connected and how they are connected, especially if they vary from their defaults.

    This information is obtained from two sources: ARIA's parameter file(s) for the robot, and from program runtime arguments via ArArgumentParser (which reads default program argument values from /etc/Aria.args (on Linux) and the ARIAARGS environment variable (on both Linux and Windows), then reads current program arguments from the command line).

    Arguments are provided to other ARIA classes by an ArArgumentParser object. 

（1）All ARIA programs should create an ArArgumentParser, call ArArgumentParser::loadDefaultArguments() to load any arguments that appear in the /etc/Aria.args file or ARIAARGS environment variable, and provide that object to any class constructors that accept it. 

（2）Once all such objects are created, you can call Aria::logOptions() to print out a summary of all relevant options

 e.g. call Aria::logOptions(); and Aria::exit() if ArArgumentParser::checkHelpAndWarnUnparsed() returns true, because the user gave the --help option. 

       Finally, call Aria::parseArgs() to cause each of them to check the ArArgumentParser for their respective arguments.

    Here is an example which uses ArRobotConnector to connect the ArRobot and ArLaserConnector to connect to a laser rangefinder.

#include "Aria.h"
int main(int argc, char** argv)
{
  Aria::init();
  ArArgumentParser parser(&argc, argv);
  parser.loadDefaultArguments();
  ArRobot robot;
  ArRobotConnector robotConnector(&parser, &robot);

  // Try connecting to the robot.
  if(!robotConnector.connectRobot(&robot))
  {
    // Error!
    ArLog::log(ArLog::Terse, "Error, could not connect to robot.\n");
    robotConnector.logOptions();
    Aria::exit(1);
  }

  // Run the ArRobot processing/task cycle thread.
  robot.runAsync(true);

  ArLaserConnector laserConnector(&parser, &robot, &robotConnector);

  // Parse command line arguments (there may be arguments specifying 
  // what lasers to try to connect to)
  if(!Aria::parseArgs())
  {
    Aria::logOptions();
    Aria::exit(2);
  }

  // Try connecting to all lasers specified in the robot's parameter file
  // and in command line arguments
  if(!laserConnector.connectLasers())
  {
    ArLog::log(ArLog::Terse, "Error, could not connect to lasers.\n");
    Aria::logOptions();
    Aria::exit(3);
  }

  // Now we're connected, and the robot and laser objects are running in 
  // background threads reading and processing data. (You can get access
  // to the ArLaser objects using ArRobot::findLaser() or
  // ArRobot::getLaserMap().
  ...

4. ArRobot

    ArRobot (using the ArDeviceConnection, ArRobotPacketReceiver, ArRobotPacketSender, ArRobotPacket, and ArSerialConnection classes) handles the details of constructing and sending a command packets to the robot as well as receiving and decoding the packets recieved from the “robot server”（robot platform firmware）.

Packet Handlers：

    Server Information Packets (SIPs) are packets sent by the robot server containing information updates about the robot and its accessories. The standard SIP is sent by the robot to a connected client automaticallyevery 100 milliseconds 毫秒(this frequency may be configured in the firmware parameters). It contains the robot's current position and estimates, current translational and rotational speeds, sonar reading updates, battery voltage, analog and digital I/O states, and more. These data are stored and used by ArRobot's State Reflection (see State Reflection below) and are accessible via methods of the ArRobot class. (Note, within the ArRobot source code the standard SIP is also called a "motor" packet.)

Command Packets：

    To control the robot platform, a client program sends command packets through the robot connection. This can be done using ArRobot's Motion Command Functions, using Actions, or at the most basic level, Direct Commands.

Robot Synchronization Cycle：

    To begin the processing cycle, call ArRobot::run() to enter the cycle synchronously, or ArRobot::runAsync() to run the cycle in a new background thread. ArRobot::stopRunning() stops the processing cycle.

    ArRobot provides methods to add your own sensor-interpretation and generic user task callbacks. To add a task callback, create an ArFunctor function object (see Functors) and then add it using ArRobot::addSensorInterpTask() or ArRobot::addUserTask(). These tasks can be removed using ArRobot::remSensorInterpTask() or ArRobot::remUserTask().

    ArRobot locks it's mutex (see ArRobot::lock() and ArRobot::unlock()) during each iteration of the task cycle, so your task callbacks must not lock this mutex--a deadlock will occur. (However, locks must still be used for safe access to any other thread or ArAsyncTask, such as lasers and other range devices, or ARNL's planning or localization tasks.) This mutex lock protects ArRobot data from modification by other threads (if they correctly use the lock during access), and interruption of the series of tasks. So if you access ArRobot from any other thread (including the main thread, if you used ArRobot::runAsync() to run the task cycle), you must use ArRobot::lock() and ArRobot::unlock() to lock and unlock the robot before and after any method call or use of any data in ArRobot.

    It is also possible to run the processing cycle without a connection to a robot, if desired. This alternative cycle is not triggered by receiving a packet, instead it has its own steady, "chained" cycle time (default is 100 milliseconds which you may examine and reset with ArRobot::getCycleTime() and ArRobot::setCycleTime()). You may also explicitly disassociate ArRobot's processing cycle from incoming SIP processing at any time by calling ArRobot::setCycleChained() ("Chained" means that it is the end of a previous cycle that triggers the next after suitable delay to meet the desired cycle frequency). However, in doing so, you may degrade performance, as the robot's cycle will only be run every ArRobot::getCycleTime() milliseconds, and each time only the most recently read (oldest) SIP is used (even if the robot has sent more than one since the last cycle).

    ArRobot's synchronization task list is ipmlemented as a tree, with five major branches. Though it is uncommon to do so, a client program may modify this tree or disable branch tasks of the tree. If a particular task is disabled, none of its children will be called. The root of the task tree can be obtained by calling ArRobot::getSyncTaskRoot(), which returns an ArSyncTask object.

    Warning:

    A user task or sensor interpretation task must run quickly. If one or more user tasks or actions runs such that the task cycle takes too long (more that 100ms) then the performance and behavior of the robot and of ARIA-robot communications will be negatively affected. In particular, do not call any functions that could block or wait for an unknown amount of time (such as locking a mutex that could be locked for a long time by another thread) or do any long loops waiting for a condition. Long-running activity can be performed in a separate asynchronous thread (See ArASyncTask) instead, and results can be shared with the user task via storage which is protected by a mutex only during immediate reading and writing of the storage variables.

    State Reflection

    State reflection in the ArRobot class is the way ARIA maintains a snapshot of the robot's operating conditions and values, such as estimated pose, current velocity, battery voltage, etc. as extracted from the latest standard SIP. ArRobot methods for examining these values include 

ArRobot::getPose(), ArRobot::getX(), ArRobot::getY(), ArRobot::getTh(),

ArRobot::getVel(), ArRobot::getRotVel(), ArRobot::getBatteryVoltage(), 

ArRobot::isLeftMotorStalled(), ArRobot::isRightMotorStalled(), 

ArRobot::getCompass(), ArRobot::getAnalogPortSelected(), ArRobot::getAnalog(), ArRobot::getDigIn(), ArRobot::getDigOut().

    The standard SIP also contains sonar reading updates, which are reflected in ArRobot and examined with the methods:

ArRobot::getNumSonar(), ArRobot::getSonarRange(), ArRobot::isSonarNew(), ArRobot::getSonarReading(), 

ArRobot::getClosestSonarRange(), ArRobot::getClosestSonarNumber(). 

    The sonar interface class, ArSonarDevice, also receives this information (see Range Devices).

Robot Callbacks

    There are a number of useful callbacks invoked by ArRobot on connection events. You can add and remove them with the functions 

ArRobot::addConnectCB(), ArRobot::remConnectCB(), ArRobot::addFailedConnectCB(), ArRobot::remFailedConnectCB(), 

ArRobot::addDisconnectNormallyCB(), ArRobot::remDisconnectNormallyCB(), ArRobot::addDisconnectOnErrorCB(), 

ArRobot::remDisconnectOnErrorCB(), ArRobot::addRunExitCB(), ArRobot::remRunExitCB(). 

  Read their individual documentation pages for details.

   See also:   robotConnectionCallbacks::cpp

5. Controlling the robot with Commands and Actions

    Motion Command Functions:

    These are explicit simple movement commands sent by ArRobot's state reflection task. For example, ArRobot::setVel() to set the translational velocity, ArRobot::setRotVel to set rotational velocity, ArRobot::setVel2() to or set each wheel speeds separately, ArRobot::setHeading() to set a global heading angle to turn to, ArRobot::move() to drive a given distance, or ArRobot::stop() to stop all motion. ArRobot also provides methods for setting speed limits beyond the limits set in the firmware configuration. These motion functions work at part of with State Reflection, and ArRobot may resend commands each cycle to try to achieve the desired state.

     Be aware that a Direct or a Motion Command may conflict with controls from Actions or other upper-level processes and lead to unexpected consequences. Use ArRobot::clearDirectMotion() to cancel the overriding effect of a previously set Motion Command so that your Action is able to regain control the robot. Or limit the time a Motion Command prevents other motion actions with ArRobot::setDirectMotionPrecedenceTime(). Otherwise, the Motion Command will prevent actions forever. Use ArRobot::getDirectMotionPrecedenceTime() to see how long a Motion Command takes precedence once set.

   Actions:

    Actions are defined by creating a subclass of the ArAction the base class which overloads the ArAction::fire() method. See the actionExample::cpp example program. ARIA also includes some useful pre-made action classes (see Predefined ArAction Classes for a list). Include these in your programs, or use them as examples when creating your own custom ArAction subclass.

    Actions are attached to an ArRobot object with ArRobot::addAction(), along with a priority which determines its position in the action list. ArAction::setRobot() is called on an action object when it is added to a robot. You can override this in your action subclass. (For example, this would be useful to add a connection callback, if there were some calculations you wished to do upon connection to the robot.)

    Actions are evaluated by ArRobot's action resolver in descending order of priority (highest priority first, lowest priority last) in each task cycle just prior to State Reflection. The action resolver invokes each action's fire() method, combining their desired motion commands (the ArActionDesired objects they return) to a single ArActionDesired object, which is then used in state reflection to send motion commands to the robot.

   Action Desired:

     ArActionDesired objects are used to pass desired action channel values and strengths out of an ArAction::fire() method back to the resolver. An ArActionDesired object should always be reset (ArActionDesired::reset()) before it is reused.

    There are six action channels: velocity (ArActionDesired::setVel), heading (ArActionDesired::setDeltaHeading or ArActionDesired::setHeading for absolute heading), maximum forward translational velocity (ArActionDesired::setMaxVel), maximum reverse translational velocity (ArActionDesired::setMaxNegVel), and maximum rotational velocity (ArActionDesired::setMaxRotVel).

    An action gives each channel a strength between 0.0, the lowest, and 1.0, the highest. Strengths are used by the resolver to compute the relative effect of the associated channel when combining multiple actions' desired movements.

    The maximum velocity, maximum negative velocity, and maximum rotational velocity channels simply impose speed limits and thereby indirectly control the robot.

    For more advanced usage, ArActionDesired objects can be merged (ArActionDesired::merge) and averaged (ArActionDesired::startAverage, ArActionDesired::addAverage, ArActionDesired::endAverage).

The Action Resolver:

    ArResolver is the base action resolver class. ArPriorityResolver is the default resolver used by ArRobot.

The resolver used by ArRobot may be changed by calling ArRobot::setResolver, if you wish to create an alternative ArResolver implementation. There may only be one resolver per ArRobot object. (Though a resolver could contain within it multiple resolvers of its own.) Note that although a robot has one particular resolver bound to it, a resolver instance is not tied to any robot.

    The priority resolver works by iterating through the action list in descending priority (from greatest priority value to lowest), setting each robot movement channel (trans. velocity, heading, max. velocity, etc.) based on the contributing actions' desired values (as returned from their fire() methods) in proportion to their respective strengths as well as the actions' priorities, updating each movement channel until its strength becomes 1.0 or the action list is exhausted. Once a channel's accumulated strength reaches 1.0, no more changes may be made to that channel (this is how higher priority actions can prevent lower priority actions from changing a channel). Same-priority actions are averaged together if they both provide outputs for the same channel.

    As an example, the following table illustrates at each step an action's desired value and strength for the velocity channel, and the resulting change to the resolver's final velocity channel value and strength decision, for four fictional actions (A, B, C and D):

    Notice in the example that the same-priority actions B and C are averaged before being combined with the previously computed values from step 1. The resulting combination is: ( (B desired velocity: -100) X (B velocity strength: 1.0) + (C desired velocity: 200) X (C velocity strength: 0.5) ) / 2 => (-100 + 100) / 2 => 0 Therefore actions B and C end up cancelling each other out. Combining this result with the "currentDesired" values computed in step 1 gives (step 1 desired velocity: -400) X (step 1 velocity strength: 0.25) + (step 4 desired velocity: 0) X (step 4 velocity strength: 0.75) => -100.

    In this example, it turns out that at step 5, action D has no effect since the strength for this channel has reached 1.0 at step 4, before that action was considered by the resolver.

    The same method is used for all of the other channels.

Now learn  teleopActionsExample::cpp  and  wander::cpp

Action Groups

    Action groups allow you to easily enable (activate) or disable (de-activate) a set of actions at once. You must first create an ArActionGroup attached to an ArRobot. Then, when you add an ArAction to the ArActionGroup, it is automatically added to the ArRobot, as well as to the group.

6. Range Devices

    ArRangeDevice also includes some methods to help find the closest reading to the robot within a selected box, or a polar sector: ArRangeDevice::currentReadingPolar(), ArRangeDevice::currentReadingBox(), ArRangeDevice::cumulativeReadingPolar(), ArRangeDevice::cumulativeReadingBox().

    ArRobot also includes similar methods to do common operations on all attached range devices, including ArRobot::checkRangeDevicesCurrentPolar(), ArRobot::checkRangeDevicesCurrentBox(), ArRobot::checkRangesDevicesCumulativePolar(), and ArRobot::checkRangeDevicesCumulativeBox() to find the closest range reading to the robot within some region.

    Each range device has a mutex 互斥锁(Use ArRangeDevice::lockDevice() and ArRangeDevice::unlockDevice() to lock and unlock it) so that it can be accessed safely by multiple threads. For example, ArLMS2xx uses a thread to read data from a laser, but the checkRangeDevice functions in ArRobot lockDevice() so they can read the data without conflicting with ArLMS2xx's data-reading thread, then use unlockDevice() when done. See Threading for more about threading in ARIA.

7. Functors

  Functor is short for function pointer. A Functor lets you call a function without knowing the declaration of the function. Instead, the compiler and linker figure out how to properly call the function.

When creating a functor object, however, you must also provide the type and instance of an object to invoke the method of; or explicitly state that the function is a class-less global function. Do this by using one of the concrete base classes of ArFunctor instead of the abstract classes: ArFunctorC, ArFunctor1C, ArFunctor2C, ArRetFunctorC, ArRetFunctor1C, ArRetFunctor2C, ArGlobalFunctor, ArGlobalFunctor1, etc.

Example:

    class ExampleClass {
    public:
        void aFunction(int n);
    };
  
    ...
      
    ExampleClass obj;
    ArFunctor1C<ExampleClass, int> functor(&obj, &ExampleClass::aFunction);

    ...

    functor.invoke(42);

  ExampleClass is a class which contains a function called aFunction(). The functor functor is declared as an ArFunctor1C, a functor which invokes a class method and takes one argument. The template parameters specify the type of the class (ExampleClass) and the type of the method argument (int). functor is then initialized with a pointer to the ExampleClass instance to call the method on, and a pointer to the class method to call. When a functor is contained within the class, it is typcially initialized in the constructor, giving this as the object instance.

    A functor must be initialized with the method to call and, if a "C" functor, a class instance. An unitilialized functor will crash at runtime when invoked.

    It is also possible to give values for the method arguments in the functor initialization, see ArFunctor documentation for details.

Once the functor object is created in this fashion, it can now be passed to another function or object that wants a callback functor. And the method ExampleClass::aFunction() will be called on the object obj when the functor is invoked.

    To invoke a functor, simply call the invoke() function on the functor. If it takes arguments, call invoke() with those arguments. If the functor has a return value, call invokeR. The return value of the function will be passed back through the invokeR() function. If the functor was initialized with argument values, and invoke() is called without argument values, the argument values provided at initialization are passed.

8. Keyboard and Joystick Input

    ARIA provides several classes getting live joystick and keyboard input, and action classes (see Actions) that use that input to drive the robot.

    ArJoyHandler is a cross-platform interface to joystick data. It's key functions are ArJoyHandler::getButtons, ArJoyHandler::getAdjusted, ArJoyHandler::setSpeeds, and ArJoyHandler::getDoubles.

    ArKeyHandler is a cross-platform interface for recieving single keystroke events (instead of buffered lines of text). It's key function is ArKeyHandler::addKeyHandler, which binds a specific key to a given functor. It contains an enum ArKeyHandler::KEY that contains values for special keys. You can also attach a key handler to a robot with ArRobot::attachKeyHandler(), which adds some default key handlers, including a handler for Escape that disconnects and exits the program (especially useful on Windows, where Ctrl-C or the terminal close box won't properly clean up). Since a PC can only have ony keyboard, ARIA keeps an ArKeyHandler pointer globally, which may be queried with Aria::getKeyHandler().

Note:

if you are using Linux, creating a key handler will make the program hang if put into the background with Ctrl-Z.

    ARIA provides two simple actions, ArActionKeydrive and ArActionJoydrive, to drive a robot from keyboard and joystick input. These actions are used by the teleopActionsExample::cpp example program. ARIA also provides a more flexible ArActionRatioInput, which can combine several input sources (such as keyboard, computer joystick, robot-platform (microcontroller) joystick, or teleoperation commands recieved via ArNetworking) in a more consistent and configurable manner. See the class documentation for more details.

9. Threading

     ArSocket sock("host.name.com", 4040, ArSocket::TCP);

     ArSocket sock;
     sock.connect("host.name.com", 4040, ArSocket::TCP);

     ArSocket sock(4040, true, ArSocket::TCP);

     void foo(int number = 3);

     // Use the default value for the argument:
     foo();

     // Or, use don't use the default:
     foo(99);   

  void foo(int number)
  { 
    //...
  }

     class BaseClass
     {
     public:
       BaseClass(int someNumber);
     };

     class SubClass : public BaseClass
     {
     public:
       SubClass(void);
       int anotherNumber;
     };

     SubClass::SubClass(void) : BaseClass(3), anotherNumber(37)
     {
         // ...
     }

  ArTcpConnection con;
  ArRobot robot;

 con.setPort();
 if (!con.openSimple())
  {
    printf("Open failed.");
    Aria::shutdown();
    return 1;
  }

  robot.setDeviceConnection(&con);
  if (!robot.blockingConnect())
  {
    printf("Could not connect to robot... Exiting.");
    Aria::shutdown();
    return 1;
  }