Skip to content Skip to main navigation Skip to footer

Navigation

Introduction

Navigation refers to the robot’s ability to move: the robot can travel from point A to point B, automatically plan its route along the way, and effectively avoid obstacles.

Robot navigation relies on many sensors, including the bottom LiDAR, the RGBD camera and the head IR sensor (on some models). Do not block these sensors during navigation; otherwise the robot may refuse to move or path planning may fail.

The robot can only navigate if a map has been created, the robot has been successfully localized on that map, and the LiDAR is turned on. Be sure to keep this in mind!

Navigation Status and Error Code Definitions

Reference table of the status and error codes that may occur in the navigation APIs

//============================================================
Navigation status definitions (correspond to onStatusUpdate of navigationListener)
STATUS_START_NAVIGATION = 1014; //Navigation started
STATUS_START_CRUISE = 1015; //Cruise started
STATUS_NAVI_AVOID = 1018; //Obstacle avoidance started
STATUS_NAVI_AVOID_END = 1019; //Obstacle avoidance ended
STATUS_NAVI_OUT_MAP = 1020; //Moved out of the map; we recommend calling stopNavigation to stop navigation
STATUS_NAVI_MULTI_ROBOT_WAITING = 1034; //Waiting for multi-robot dispatching
STATUS_NAVI_MULTI_ROBOT_WAITING_END = 1035; //Multi-robot dispatching wait ended
STATUS_NAVI_GO_STRAIGHT = 1036; //Started going straight
STATUS_NAVI_TURN_LEFT = 1037; //Started turning left
STATUS_NAVI_TURN_RIGHT = 1038; //Started turning right
STATUS_NAVI_GLOBAL_PATH_FAILED = 1025; //Path planning failed and navigation failed; handle the error. We recommend calling stopNavigation to stop navigation
//============================================================
Navigation error code definitions (correspond to onError of navigationListener)
ERROR_DESTINATION_NOT_EXIST = -108; //Destination does not exist
ERROR_DESTINATION_CAN_NOT_ARRAIVE = -109; //Obstacle avoidance timed out; destination unreachable
ERROR_IN_DESTINATION = -113; //Already near the destination
ERROR_NOT_ESTIMATE = -116; //Not localized
ERROR_MULTI_ROBOT_WAITING_TIMEOUT = -125; //Multi-robot dispatching wait timed out
ERROR_NAVIGATION_FAILED = -120; //Navigation failed for other reasons (catch-all failure)
ACTION_RESPONSE_ALREADY_RUN = -1; //This API has already been called; stop it before calling it again
ACTION_RESPONSE_REQUEST_RES_ERROR = -6; //Another API that controls the chassis has already been called; stop it before continuing
//============================================================

Navigate to a Specified Location

Method name: startNavigation. Result callback:

ActionListener navigationListener = new ActionListener() {
        @Override
        public void onResult(int status, String response) throws RemoteException {
            switch (status) {
                case Definition.RESULT_OK:
                    if ("true".equals(response)) {
                        //Navigation succeeded
                    } else {
                        //Navigation failed
                    }
                    break;
               case Definition.ACTION_RESPONSE_STOP_SUCCESS://Navigation task canceled successfully
                    break;
            }
        }
        @Override public void onError(int errorCode, String errorString) throws RemoteException     {
            switch (errorCode) {
                case Definition.ERROR_NOT_ESTIMATE:              //Not localized
                    break;
                case Definition.ERROR_IN_DESTINATION:              //The robot is already within the destination range
                    break;
                case Definition.ERROR_DESTINATION_NOT_EXIST:              //The navigation destination does not exist
                    break;
                case Definition.ERROR_DESTINATION_CAN_NOT_ARRAIVE://Obstacle avoidance timed out and the destination cannot be reached; the timeout is set by a parameter
                    break;
                case Definition.ACTION_RESPONSE_ALREADY_RUN:           //This API has already been called; stop it before calling it again
                    break;
                case Definition.ACTION_RESPONSE_REQUEST_RES_ERROR://Another API that controls the chassis has already been called; stop it before continuing
                    break;
            }
        }

        @Override
        public void onStatusUpdate(int status, String data, String extraData) {
            switch (status) {
                case Definition.STATUS_NAVI_AVOID:               //The current route is blocked by obstacles
                    break;
                case Definition.STATUS_NAVI_AVOID_END:               //The obstacle has been removed
                    break;
            }
        }
}

How to call:

  1. Default navigation speed
RobotApi.getInstance().startNavigation(reqId, destName, coordinateDeviation, time, navigationListener);

2. Default navigation speed with a specified obstacle avoidance distance (if this value is set to 0, the robot uses the default value of 0.75) <***This call is supported from V10>***

RobotApi.getInstance().startNavigation(reqId, destName, coordinateDeviation, obsDistance, time, navigationListener);

3. Specified navigation speed <***This call is supported from V4.12>***

RobotApi.getInstance().startNavigation(reqId, destName, coordinateDeviation, time, linearSpeed, angularSpeed, navigationListener);

4. Specified navigation speed with a specified obstacle avoidance distance (if this value is set to 0, the robot uses the default value of 0.75) <***This call is supported from V10>***

RobotApi.getInstance().startNavigation(reqId, destName, coordinateDeviation, obsDistance, time, linearSpeed, angularSpeed, navigationListener);

5. Specified coordinates <***This call is supported from V4.12>***

RobotApi.getInstance().startNavigation(reqId, pose, coordinateDeviation, time, navigationListener);

6. Specified coordinates with a specified obstacle avoidance distance (if this value is set to 0, the robot uses the default value of 0.75) <***This call is supported from V10>***

RobotApi.getInstance().startNavigation(reqId, pose, coordinateDeviation, obsDistance, time, navigationListener);

7. Specified navigation acceleration <***This call is supported from V4.12>***

RobotApi.getInstance().startNavigation(reqId, destName, coordinateDeviation, time, linearSpeed, angularSpeed, isAdjustAngle, destinationRange, wheelOverCurrentRetryCount, multipleWaitTime, priority, linearAcceleration, angularAcceleration, navigationListener);

Parameters:

  • destName: name of the navigation destination (must be set first with setLocation)
  • pose: coordinates of the navigation destination
  • obsDistance: maximum obstacle avoidance distance. When an obstacle is closer than this value, the robot stops. The value must be greater than 0. Default: 0.75. Unit: meters.
  • coordinateDeviation: pre-check range applied before the navigation API runs. It takes effect only once, at the moment the navigation command is issued. If the robot’s current position is closer to the destination than this value, it is considered to have arrived, does not actually start moving, and the API returns success immediately. If the distance is greater than or equal to this value, navigation starts normally and the robot travels to the destination (how close counts as arrival is determined by destinationRange). Recommended value: 0.2 meters. Unit: meters.
  • time: obstacle avoidance timeout. If the robot moves no more than 0.1 m within this time, navigation fails. Unit: milliseconds. Recommended: 30*1000.
  • linearSpeed: navigation linear speed. Range: 0.1 ~ 1.2 m/s Default: 0.7 m/s.
  • angularSpeed: navigation angular speed. Range: 0.2 ~ 1.8 rad/s Default: 1.2 rad/s The final navigation speed is derived from both the linear speed and the angular speed. Different linear and angular speeds affect how the robot moves during navigation, so we recommend keeping them in this relationship: angularSpeed = 0.4 + (linearSpeed – 0.1) / 3 * 4
  • isAdjustAngle: whether to keep the heading the robot has when navigation ends. If false is passed, the robot turns back to the angle set for the map point.
  • destinationRange: arrival range for navigation. While actually moving, the robot is considered to have arrived and ends navigation as soon as it is within this distance of the destination (default 0.0, meaning it must reach the center of the map point). When the destination is occupied or its center cannot be reached exactly, this value also determines how far from the destination the robot finally stops. Unit: meters.
  • wheelOverCurrentRetryCount: number of retries when a wheel stalls during navigation
  • multipleWaitTime: multi-robot waiting during navigation
  • priority: 0 by default is fine. Range: 0~30; the larger the value, the higher the priority. Generally used for giving way when multiple robots are navigating
  • linearAcceleration: navigation linear acceleration. Range: 0.4 ~ 0.8 m/s². Default: 0.7 m/s².
  • angularAcceleration: navigation angular acceleration. Range: 0.4 ~ 0.9 rad/s². Default: 0.8 rad/s². The final navigation angular acceleration is derived from the linear speed
  • by conversion. Different linear and angular accelerations affect how the robot moves during navigation, so we recommend keeping them in this relationship: angularAcceleration= (linearSpeed / 0.8)

Supported platforms:

GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Note: Make sure the robot is localized before calling this API.

Stop Navigating to a Specified Location

Method name: stopNavigation. How to call:

RobotApi.getInstance().stopNavigation(reqId);

Supported platforms:

GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Note: This API can only stop navigation started with startNavigation.

Navigate to Specified Coordinates

Note: This method is deprecated. We recommend using startNavigation; the goPosition API is no longer maintained.

Method name: goPosition. Result callback:

CommandListener goPositionListener = new CommandListener() {
    @Override
    public void onResult(int status, String response) {
        switch (status) {
            case Definition.RESULT_OK:
                if ("true".equals(response)) {
                    //Navigation succeeded
                } else {
                    //Navigation failed
                }
                break;
        }
    }
    @Override
    public void onError(int errorCode, String errorString) throws RemoteException {
        switch (errorCode) {
            case Definition.ACTION_RESPONSE_ALREADY_RUN:
                //This API has already been called; stop it before calling it again
                break;
            case Definition.ACTION_RESPONSE_REQUEST_RES_ERROR:
                //Another API that controls the chassis has already been called; stop it before continuing
                break;
        }
    }
    @Override public void onStatusUpdate(int status, String data) {
        switch (status) {
            case Definition.STATUS_NAVI_AVOID:
            //The current route is blocked by obstacles
            break;
            case Definition.STATUS_NAVI_AVOID_END:
            //The obstacle has been removed
            break;
        }
    }
}

How to call:

  1. Default speed
try {
    JSONObject position = new JSONObject();
    //x coordinate
    position.put(Definition.JSON_NAVI_POSITION_X, x);
    //y coordinate
    position.put(Definition.JSON_NAVI_POSITION_Y, y);
    //z coordinate
    position.put(Definition.JSON_NAVI_POSITION_THETA, theta);
    RobotApi.getInstance().goPosition(reqId, position.toString(), goPositionListener);
} catch (JSONException e) {
    e.printStackTrace();
}

2. Specified speed*<***This call is supported from V4.12>****

try {
    JSONObject position = new JSONObject();
    //x coordinate
    position.put(Definition.JSON_NAVI_POSITION_X, x);
    //y coordinate
    position.put(Definition.JSON_NAVI_POSITION_Y, y);
    //z coordinate
    position.put(Definition.JSON_NAVI_POSITION_THETA, theta);
    RobotApi.getInstance().goPosition(reqId, position.toString(),  linearSpeed, angularSpeed, goPositionListener);
} catch (JSONException e) {
    e.printStackTrace();
}

Parameters

  • position: coordinates in JSON format { “x”: “x coordinate”, “y”: “y coordinate”, “theta: “z coordinate”, }
  • linearSpeed: navigation linear speed. Range: 0.1 ~ 0.85 m/s. Default: 0.7 m/s
  • angularSpeed: navigation angular speed. Range: 0.4 ~ 1.4 m/s. Default: 1.2 m/s. The final navigation speed is derived from both the linear speed and the angular speed. Different linear and angular speeds affect how the robot moves during navigation, so we recommend keeping them in this relationship: angularSpeed = 0.4 + (linearSpeed – 0.1) / 3 * 4

Supported platforms:

GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Note: Make sure the robot is localized before calling this API.

Stop Navigating to Specified Coordinates

Method name: stopGoPosition. How to call:

RobotApi.getInstance().stopGoPosition(reqId);

Supported platforms:

GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Note: The two APIs that start navigation, goPosition and startNavigation, each have a corresponding stop API. Always use the matching pair; do not mix them.

Turn Toward a Target Point

Method name: resumeSpecialPlaceTheta

Description: This API only turns the robot left or right to face the target point; it does not actually move to the target point.

How to call:

RobotApi.getInstance().resumeSpecialPlaceTheta(reqId,
    placeName,
    new CommandListener() {
        @Override
        public void onResponse(int result, String message) {
        }
  });

Parameters

  • reqId: int, command ID
  • placeName: String, target point name
  • listener: CommandListener, message callback

Return value

  • int result 0: command executed / -1: not executed

Supported platforms:

GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Note: Make sure the robot is localized before calling this API.

Calculate the Distance Between Two Points in Line-Following Mode

Use this API to get the distance between two points (only for calculating the distance between two points on the line-following path in line-following mode).

Method name: getNaviPathInfo

Description: Calculates the distance between two points on the line-following path in line-following mode. The points passed in can be any points on the line-following path. You can get information about the points marked on the map through the map point APIs.

How to call:

//Both the start point and the end point must be on the line-following path, and line-following mode must be enabled on the robot
Pose startPos = new Pose();
startPos.setX(-0.22329703f);
startPos.setY(1.1073834f);
startPos.setTheta(-1.2297891f);
Pose endPos = new Pose();
endPos.setX(0.09533833f);
endPos.setY(-0.7406802f);
endPos.setTheta(-2.886187f);
//Use this API to get the path length, in meters
RobotApi.getInstance().getNaviPathInfo(reqID,
    startPos,
    endPos,
    new CommandListener() {
        @Override
        public void onResult(int status, String response, String extraData) {
            try {
                JSONObject json = new JSONObject(response);
                double pathLength = json.getDouble("pathLength");
            } catch (JSONException e) {
                e.printStackTrace();
            }
        }
        @Override
        public void onError(int errorCode, String errorString, String extraData) {
            Log.d('OnError',errorCode);
        }
    });
GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
YesYesYesYesYesNo

Set the Robot’s Acceleration and Deceleration Mode

When developing for LuckiBot, you can globally configure the robot’s acceleration and braking deceleration to suit your current business needs. Configure it as follows:

1. Add the following permission to your app

<uses-permission android:name="com.ainirobot.coreservice.robotSettingProvider" />

2. Use this method in your code to change the setting

public class NavigationSettings {
    //value "1" - "3"  1 gentle, 2 normal, 3 urgent
    public static final String ROBOT_SETTING_NAVIGATION_BREAK_MODE_LEVEL = "robot_setting_navigation_break_mode_level";
    //value "1" - "3" 1 gentle, 2 normal, 3 urgent
    public static final String ROBOT_SETTING_NAVIGATION_START_MODE_LEVEL = "robot_setting_navigation_start_mode_level";
    public NavigationSettings(){
    }
    public void setBreakModeLevel(int i){
        i = i > 3 ? 3 : Math.max(i, 1);
        putString(ROBOT_SETTING_NAVIGATION_BREAK_MODE_LEVEL,""+i);
    }
    public void setStartModeLevel(int i){
        i = i > 3 ? 3 : Math.max(i, 1);
        putString(ROBOT_SETTING_NAVIGATION_START_MODE_LEVEL,""+i);
    }
    private void  putString(String key ,String value) {
        if(value == ""){
            return;
        }
        try {
            sendSettingBroadcast(key, value);
            //Settings.Global.putString(mContext.getContentResolver(), key, value);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    private void sendSettingBroadcast(String key,String value) {
        RobotSettingApi.getInstance().setRobotString(key,value);
    }
}
GreetingBotGreetingBot 2GreetingBot MiniLuckiBotLuckiBot ProBigScreenBot
NoNoNoYesYesNo