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:
- 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:
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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:
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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:
- 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:
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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:
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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:
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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);
}
});
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| Yes | Yes | Yes | Yes | Yes | No |
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);
}
}
| GreetingBot | GreetingBot 2 | GreetingBot Mini | LuckiBot | LuckiBot Pro | BigScreenBot |
| No | No | No | Yes | Yes | No |