# SoftBank Robotics documentation What's new in NAOqi 2.8?

# ALNavigation API

Overview | API Navigation | API Exploration

Namespace : AL

    #include <alproxies/alnavigationproxy.h>

## Method list

As any module, this module inherits methods from ALModule API. It also has the following specific methods:

class `ALNavigationProxy`

### Pepper only

#### Navigation API:

- `ALNavigationProxy::navigateTo`
- `ALNavigationProxy::moveAlong`
- `ALNavigationProxy::getFreeZone`
- `ALNavigationProxy::findFreeZone`

#### Exploration and localization API:

- `ALNavigationProxy::explore`
- `ALNavigationProxy::startMapping`
- `ALNavigationProxy::stopExploration`
- `ALNavigationProxy::saveExploration`
- `ALNavigationProxy::getMetricalMap`
- `ALNavigationProxy::getExplorationPath`
- `ALNavigationProxy::navigateToInMap`
- `ALNavigationProxy::getRobotPositionInMap`
- `ALNavigationProxy::loadExploration`
- `ALNavigationProxy::setDefaultExploration`
- `ALNavigationProxy::relocalizeInMap`
- `ALNavigationProxy::relocalizeInMapWithHint`
- `ALNavigationProxy::startLocalization`
- `ALNavigationProxy::stopLocalization`

#### Deprecated methods:

- `ALNavigationProxy::startFreeZoneUpdate`
- `ALNavigationProxy::stopAndComputeFreeZone`

## Event list

- `Navigation/AvoidanceNavigator/Status()`
- `Navigation/AvoidanceNavigator/ObstacleDetected()`
- `Navigation/AvoidanceNavigator/MovingToFreeZone()`
- `Navigation/AvoidanceNavigator/TrajectoryProgress()`
- `Navigation/AvoidanceNavigator/AbsTargetModified()`
- `Navigation/MotionDetected()`

## Methods

qi::Future<bool> `ALNavigationProxy::``navigateTo`(const float& x, const float& y)

  Makes the robot navigate to a relative metrical target pose2D expressed in FRAME_ROBOT. The robot computes a path to avoid obstacles.

  The robot is likely to perform any safety action to ensure the non collision with the environment. For example look with the head, stop to replan a new path. Thus, no motion timeline that takes the head resource can be run during a navigateTo.

  Unlike `ALMotionProxy::moveTo`, the robot can choose its own path and speed while moving around. The speed decreases the closer the robot gets to obstacles. If the obstacle avoidance becomes too dangerous (as soon as it has detected an obstacle in its security area) the robot stops like in `ALNavigationProxy::moveTo`.

  The target must be closer than 3m from the robot, otherwise the command will be ignored and a warning will be prompted.

  This is a blocking call.

  Parameters: | x – distance along the X axis in meters. y – distance along the Y axis in meters.
  Returns: | a future returning True if the robot reached its target at the end or False if it has been stopped by obstacles or if it cannot find a path to the target.

    navigationProxy.navigateTo(2.0, 0.0)

bool `ALNavigationProxy::``moveAlong`(const AL::ALValue& trajectory)

  Parameters: | trajectory – an ALValue describing either a direct trajectory [“Holonomic”, pathXY, finalTheta, finalTime], or a composed trajectory [“Composed”, direct trajectories]. pathXY is an ALValue describing a 2D path, either a direct path or a composed one: [“Composed”, direct paths]. Direct paths can be lines or arc of circles: [“Line”, [finalX, finalY]], [“Circle”, [centerX, centerY], spanAngle].
  Returns: | True when the robot executed the trajectory completely, and also when it has been definitely stopped by obstacles.

  The following command makes the robot move 1 m forward in 5 s, then 1 m backward in 10 s, without pausing:

    navigationProxy.moveAlong(["Composed", ["Holonomic", ["Line", [1.0, 0.0]], 0.0, 5.0], ["Holonomic", ["Line", [-1.0, 0.0]], 0.0, 10.0]])

AL::ALValue `ALNavigationProxy::``getFreeZone`(float desiredRadius, float displacementConstraint)

  Returns the current free zone around the robot. Does not make the robot move.

  Parameters: | desiredRadius – The radius of free space we want in meters. displacementConstraint – The max distance we accept to move to reach the found place in meters.
  Returns: | an ALValue [Free Zone Error Code, result radius (meters), [worldMotionToRobotCenterX (meters), worldMotionToRobotCenterY (meters)]]

qi::Future<AL::ALValue> `ALNavigationProxy::``findFreeZone`(float desiredRadius, float displacementConstraint)

  Looks for a free circular zone of a specified radius not farer than a specified displacement. To do this the robot moves and looks around itself. This is a blocking call.

  Parameters: | desiredRadius – The radius of free space we want in meters. displacementConstraint – The max distance we accept to move to reach the found place in meters.
  Returns: | a cancelable qi::Future<ALValue> [Free Zone Error Code, result radius (meters), [worldMotionToRobotCenterX (meters), worldMotionToRobotCenterY (meters)]]

    desiredRadius = 0.6
    displacementConstraint = 0.5
    navigationProxy.findFreeZone(desiredRadius, displacementConstraint)

### Python script for free zone

The following command makes the robot move to the center of the free zone if everything went OK.

`alnavigation.py`

    #! /usr/bin/env python
    # -*- encoding: UTF-8 -*-

    """Example: Use findFreeZone Method"""

    import qi
    import argparse
    import sys
    import almath
    import math

    def main(session):
        """
        This example uses the findFreeZone method.
        """
        # Get the services ALNavigation, ALMotion and ALRobotPosture.

        navigation_service = session.service("ALNavigation")
        motion_service = session.service("ALMotion")
        posture_service = session.service("ALRobotPosture")

        # Wake up robot
        motion_service.wakeUp()

        # Send robot to Stand Init
        posture_service.goToPosture("StandInit", 0.5)

        # Scanning the environement.
        navigation_service.startFreeZoneUpdate()
        ###########################################################################
        # Add here an animation with timelines and moves (less than 60 seconds).  #
        # For example :
        motion_service.moveTo(0.0, 0.0, 2.0 * math.pi)
        ###########################################################################
        desiredRadius = 0.6
        displacementConstraint = 0.5
        result = navigation_service.findFreeZone(desiredRadius, displacementConstraint)

        errorCode = result[0]
        if errorCode != 1:
            worldToCenterFreeZone = almath.Pose2D(result[2][0], result[2][1], 0.0)
            worldToRobot = almath.Pose2D(motion_service.getRobotPosition(True))
            robotToFreeZoneCenter = almath.pinv(worldToRobot) * worldToCenterFreeZone
            motion_service.moveTo(robotToFreeZoneCenter.x, robotToFreeZoneCenter.y, 0.0)
        else :
            print "Problem during the update of the free zone."

    if __name__ == "__main__":
        parser = argparse.ArgumentParser()
        parser.add_argument("--ip", type=str, default="127.0.0.1",
                            help="Robot IP address. On robot or Local Naoqi: use '127.0.0.1'.")
        parser.add_argument("--port", type=int, default=9559,
                            help="Naoqi port number")

        args = parser.parse_args()
        session = qi.Session()
        try:
            session.connect("tcp://" + args.ip + ":" + str(args.port))
        except RuntimeError:
            print ("Can't connect to Naoqi at ip \"" + args.ip + "\" on port " + str(args.port) +".\n"
                   "Please check your script arguments. Run with -h option for help.")
            sys.exit(1)
        main(session)

AL::ALValue `ALNavigationProxy::``startFreeZoneUpdate`()

  Deprecated since version 2.5: No more necessary: instead, directly call `ALNavigationProxy::getFreeZone`.

  Starts a loop to update the mapping of the free space around the robot. It is like `ALNavigationProxy::findFreeZone` but this time the user is responsible for the move of scanning. It is a non-blocking call. Call `ALNavigationProxy::stopAndComputeFreeZone` to get the result. The maximum time for the scanning is 60 seconds. After that the update is stopped automatically. Clears the map if called again.

AL::ALValue `ALNavigationProxy::``stopAndComputeFreeZone`(float desiredRadius, float displacementConstraint)

  Deprecated since version 2.5: No more necessary: instead, cancel the future of `ALNavigationProxy::findFreeZone`.

  Stops the update and returns the result. If the update was not running it returns error code 1.

  Parameters: | desiredRadius – The radius of free space we want in meters. displacementConstraint – The max distance we accept to move to reach the found place in meters.
  Returns: | an ALValue [Free Zone Error Code, result radius (meters), [worldMotionToRobotCenterX (meters), worldMotionToRobotCenterY (meters)]]

## Events

Event: `"Navigation/AvoidanceNavigator/Status"`
callback(std::string eventName, AL::ALValue status, std::string subscriberIdentifier)

  Raised when status of the local navigator changes.

  Parameters: | eventName (std::string) – “Navigation/AvoidanceNavigator/Status” status – New local navigator status. Please refer to ALNavigation for details. subscriberIdentifier (std::string) –

Event: `"Navigation/AvoidanceNavigator/ObstacleDetected"`
callback(std::string eventName, AL::ALValue position, std::string subscriberIdentifier)

  Raised when an obstacle is detected in the close area.

  Parameters: | eventName (std::string) – “Navigation/AvoidanceNavigator/ObstacleDetected” position – Array formatted as [x, y], representing the position of the detected obstacle in FRAME_ROBOT. subscriberIdentifier (std::string) –

Event: `"Navigation/AvoidanceNavigator/MovingToFreeZone"`
callback(std::string eventName, AL::ALValue status, std::string subscriberIdentifier)

  Raised when the robot starts or stops a motion to leave an obstacle neighbourhood.

  Parameters: | eventName (std::string) – “Navigation/AvoidanceNavigator/MovingToFreeZone” status – 1.0 when the robot starts and 0.0 when it has finished its motion. subscriberIdentifier (std::string) –

Event: `"Navigation/AvoidanceNavigator/TrajectoryProgress"`
callback(std::string eventName, AL::ALValue progress, std::string subscriberIdentifier)

  Raised when the trajectory progress is updated.

  Parameters: | eventName (std::string) – “Navigation/AvoidanceNavigator/TrajectoryProgress” progress – percentage of the current trajectory accomplished, between 0.0 and 1.0. subscriberIdentifier (std::string) –

Event: `"Navigation/AvoidanceNavigator/AbsTargetModified"`
callback(std::string eventName, AL::ALValue newTarget, std::string subscriberIdentifier)

  Raised when the required target is unreachable because it is inside an obstacle.

  The robot then computes the closest target to the initial one.

  Parameters: | eventName (std::string) – “Navigation/AvoidanceNavigator/AbsTargetModified” newTarget – the new target of the robot in FRAME_WORLD. subscriberIdentifier (std::string) –

Event: `"Navigation/MotionDetected"`
callback(std::string eventName, AL::ALValue sensorData, std::string subscriberIdentifier)

  Raised when a sensor detects that something is moving around the robot.

  Current implementation is based solely on Pepper Infra-Red.

  Parameters: | eventName (std::string) – “Navigation/MotionDetected” sensorData – Array formated as [Sensor, Position, Detected], where: Sensor is the name of the sensor that detected the motion; Position is the 3D position, in FRAME_WORLD, of the detected movement around Pepper; Detected is a boolean equals to true if the movement corresponds to something arriving in Pepper’s vicinity and false if it corresponds to something leaving Pepper’s vicinity. subscriberIdentifier (std::string) –

## Free Zone Error Code

Error code | meanning
--- | ---
0 | OK. You can trust the result center and radius, and asked constraints were respected.
1 | KO. There was a problem, do not take into account the returned center and radius.
2 | CONSTRAINT KO. There was no problem but the asked constraints are not fullfilled, returned best approching solution

Glossary Site map Index Support Contact Legal Notices