Aldebaran documentation What's new in NAOqi 2.4.3?

ALNavigation API

Overview | API

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

juju Pepper only

With Pepper, you can use generic navigation methods:

Deprecated methods

Methods

bool ALNavigationProxy::navigateTo(const float& x, const float& y)

There are two overloads of this function:

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:

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::navigateTo(const float& x, const float& y, const AL::ALValue& config)
Parameters:
  • x – distance along the X axis in meters.
  • y – distance along the Y axis in meters.
  • velocity – maximum velocity (unitless). [0.0 to 1.0] 0.0 is the slowest speed of the robot, 1.0 is the maximum speed of the robot. The given parameter is clipped if not in the correct range. When the given parameter is very low (near to 0.0) it can be modified to fit the move limits of the robot.
Returns:

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, [["SpeedFactor", 0.5]])
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::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:

an ALValue [Free Zone Error Code, result radius (meters), [worldMotionToRobotCenterX (meters), worldMotionToRobotCenterY (meters)]]

 
desiredRadius = 0.6
displacementConstraint = 0.5
navigationProxy.findFreeZone(desiredRadius, displacementConstraint)
AL::ALValue ALNavigationProxy::startFreeZoneUpdate()

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)

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)]]

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)
void ALNavigationProxy::setSecurityDistance(const float& distance)

Deprecated since version 1.22: Use ALMotionProxy::setOrthogonalSecurityDistance instead.

Defines the security distance used by ALNavigationProxy::moveTo.

Parameters:
float ALNavigationProxy::getSecurityDistance()

Deprecated since version 1.22: Use ALMotionProxy::getOrthogonalSecurityDistance instead.

Gets the current security distance used by ALNavigationProxy::moveTo to check dangerous obstacles.

Returns:distance in meters between any part of the robot and any obstacle in the direction of the motion.

It defines the security area in which any obstacle detection stops the robot.

Default value: 0.4m.
void ALNavigationProxy::move(const float& x, const float& y, const float& theta)

Deprecated since version 1.22: Use ALMotionProxy::move instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

There are two overloads of this function:

Like ALMotionProxy::move, makes the robot move at the given velocity, expressed in FRAME_ROBOT. Unlike ALMotionProxy::move, the robot stops as soon as it has detected an obstacle in its security area. This is a non-blocking call.

Parameters:
  • x – velocity along X-axis, in meters per second. Use negative values for backward motion
  • y – velocity along Y-axis, in meters per second. Use positive values to go to the left
  • theta – velocity around Z-axis, in radians per second. Use negative values to turn clockwise.
void ALNavigationProxy::move(const float& x, const float& y, const float& theta, const AL::ALValue moveConfig)

Deprecated since version 1.22: Use ALMotionProxy::move instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

Like ALMotionProxy::move, makes the robot move at the given velocity, expressed in FRAME_ROBOT, with a move configuration. Unlike ALMotionProxy::move, the robot stops as soon as it has detected an obstacle in its security area. This is a non-blocking call.

Parameters:
  • x – velocity along X-axis, in meters per second. Use negative values for backward motion
  • y – velocity along Y-axis, in meters per second. Use positive values to go to the left
  • theta – velocity around Z-axis, in radians per second. Use negative values to turn clockwise.
  • moveConfig – an ALValue with the custom move configuration. For further details, see: Move config.
void ALNavigationProxy::moveToward(const float& x, const float& y, const float& theta)

Deprecated since version 1.22: Use ALMotionProxy::moveToward instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

There are two overloads of this function:

Like ALMotionProxy::moveToward, makes the robot move at the given normalized velocity, expressed in FRAME_ROBOT. Unlike ALMotionProxy::moveToward, the robot stops as soon as it has detected an obstacle in its security area. This is a non-blocking call.

Parameters:
  • x – normalized, unitless, velocity along X-axis. +1 and -1 correspond to the maximum velocity in the forward and backward directions, respectively.
  • y – normalized, unitless, velocity along Y-axis. +1 and -1 correspond to the maximum velocity in the left and right directions, respectively.
  • theta – normalized, unitless, velocity around Z-axis. +1 and -1 correspond to the maximum velocity in the counterclockwise and clockwise directions, respectively.
void ALNavigationProxy::moveToward(const float& x, const float& y, const float& theta, const AL::ALValue moveConfig)

Deprecated since version 1.22: Use ALMotionProxy::moveToward instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

Like ALMotionProxy::moveToward, makes the robot move at the given normalized velocity, expressed in FRAME_ROBOT, with a move configuration. Unlike ALMotionProxy::moveToward, the robot stops as soon as it has detected an obstacle in its security area. This is a non-blocking call.

Parameters:
  • x – normalized, unitless, velocity along X-axis. +1 and -1 correspond to the maximum velocity in the forward and backward directions, respectively.
  • y – normalized, unitless, velocity along Y-axis. +1 and -1 correspond to the maximum velocity in the left and right directions, respectively.
  • theta – normalized, unitless, velocity around Z-axis. +1 and -1 correspond to the maximum velocity in the counterclockwise and clockwise directions, respectively.
  • moveConfig – an ALValue with the custom move configuration. For further details, see: Move config.
bool ALNavigationProxy::moveTo(const float& x, const float& y, const float& theta)

Deprecated since version 1.22: Use ALMotionProxy::moveTo instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

There are two overloads of this function:

Like ALMotionProxy::moveTo, makes the robot move to the given pose (i.e. location + orientation). in the ground plane, relative to FRAME_ROBOT. Unlike ALMotionProxy::moveTo, the robot stops as soon as it has detected an obstacle in its security area. This is a blocking call.

For now bumpers and sonars are used to detect obstacles.

Parameters:
  • x – distance along the X axis in meters.
  • y – distance along the Y axis in meters.
  • theta – rotation around the Z axis in radians [-3.1415 to 3.1415].
Returns:

True if the robot reached the target, False if the robot was stopped by an obstacle.
bool ALNavigationProxy::moveTo(const float& x, const float& y, const float& theta, const AL::ALValue& moveConfig)

Deprecated since version 1.22: Use ALMotionProxy::moveTo instead.

Warning

If you still use this deprecated method, make sure you activate ALMotionProxy::setExternalCollisionProtectionEnabled first.

Like ALMotionProxy::moveTo, makes the robot move to the given pose (i.e. location + orientation) in the ground plane, relative to FRAME_ROBOT, with custom move configuration. Unlike ALMotionProxy::moveTo, the robot stops as soon as it has detected an obstacle in its security area. This is a blocking call.

For now bumpers and sonars are used to detect obstacles.

Parameters:
  • x – distance along the X axis in meters.
  • y – distance along the Y axis in meters.
  • theta – rotation around the Z axis in radians [-3.1415 to 3.1415].
  • moveConfig – an ALValue with the custom move configuration. For further details, see: Move config.
Returns:

True if the robot reached the target, False if the robot was stopped by an obstacle.

Events

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) –

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) –

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) –

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) –

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) –

Deprecated since version 1.22: use ALMotion/Safety/MoveFailed() instead.

Raised when status of the Safe navigator changes.

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

Deprecated since version 1.22: use ALMotion/Safety/MoveFailed() instead.

Raised when there is an obstacle preventing the robot from starting its motion.

Deprecated since version 1.22: use ALMotion/Safety/MoveFailed() instead.

Raised when robot is already at its target.

Deprecated since version 1.22: use ALMotion/Safety/MoveFailed() instead.

Use ALMotion/Safety/MoveFailed() instead.

Raised when an obstacle is detected in the security area.

Parameters:
  • eventName (std::string) – “Navigation/SafeNavigator/DangerousObstacleDetected”
  • position – Array formatted as [x, y], representing the position of the detected obstacle in FRAME_ROBOT.
  • 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