Map and Position

Introduction

Maps and localization are prerequisites for robot navigation. Creating a map tells the robot the area it can move in, and localization tells the robot where it currently is. The robot’s built-in “Map Tool” can perform all map and map point operations, but you can also implement these functions yourself with the API.

Setting a point: telling the robot the name of its current location, so that you can later navigate to this map point using the API.

Mapping and Localization

You can perform mapping and localization with the map tool built into the system.

In map coordinates, x and y are the robot’s position on the map, and theta is the direction the robot is facing (in radians).

Localization (Set the Robot’s Initial Coordinates)

Method name:setPoseEstimate

How to call:

try {
    JSONObject params = new JSONObject();
    //x coordinate
    params.put(Definition.JSON_NAVI_POSITION_X, x);
    //y coordinate
    params.put(Definition.JSON_NAVI_POSITION_Y, y);
    //z coordinate
    params.put(Definition.JSON_NAVI_POSITION_THETA, theta);
    RobotApi.getInstance().setPoseEstimate(reqId, params.toString(), new CommandListener() {
        @Override
        public void onResult(int result, String message) {
            if ("succeed".equals(message)) {
                //Localization succeeded
            }
        }
    });
} catch (JSONException e) {
    e.printStackTrace();
}

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Check Whether the Robot Is Localized

Method name:isRobotEstimate

How to call:

RobotApi.getInstance().isRobotEstimate(reqId, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        if (!"true".equals(message)) {
            //Not localized
        } else {
            //Localized
        }
    }
});

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Set the Name of the Current Location

Method name:setLocation

How to call:

RobotApi.getInstance().setLocation(reqId, placeName, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        if ("succeed".equals(message)) {
            //Location point saved
        } else {
            //Failed to save location point
        }
    }
});

Parameters

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.

Get Coordinates by Location Name

Method name: getLocation Usage:

RobotApi.getInstance().getLocation(reqId, placeName, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        try {
            JSONObject json = new JSONObject(message);
            //Whether the location exists
            boolean isExist = json.getBoolean(Definition.JSON_NAVI_SITE_EXIST);
            if (isExist) {
                //x coordinate
                double x = json.getDouble(Definition.JSON_NAVI_POSITION_X);
                //y coordinate
                double y = json.getDouble(Definition.JSON_NAVI_POSITION_Y);
                //Facing direction
                double z = json.getDouble(Definition.JSON_NAVI_POSITION_THETA);
            }
        } catch (JSONException | NullPointerException e) {
            e.printStackTrace();
        }
    }
});

Parameters:

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Note: Locations saved with setLocation are associated with the map. When you retrieve them with getLocation, the same map must be in use; otherwise getLocation fails.

Get All Location Points on the Current Map

Method name:getPlaceList

How to call:

RobotApi.getInstance().getPlaceList(reqId, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        try {
            JSONArray jsonArray = new JSONArray(message);
            int length = jsonArray.length();
            for (int i = 0; i < length; i++) {
                JSONObject json = jsonArray.getJSONObject(i);
                //Commonly used
                json.getString("name"); //Location name
                json.getDouble("x"); //x coordinate
                json.getDouble("y"); //y coordinate
                //Less commonly used
                json.getDouble("theta"); //Facing direction
                json.getString("id"); //Location id
                json.getLong("time");//Update time
                json.getInt("status"); //0: normal area, reachable 1: no-go area, unreachable 2: outside the map, unreachable
            }
        } catch (JSONException | NullPointerException e) {
            e.printStackTrace();
        }
    }
});

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Get the Robot’s Current Coordinates

Method name:getPosition

How to call:

RobotApi.getInstance().getPosition(reqId, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        try {
            JSONObject json = new JSONObject(message);
            //x coordinate
            double x = json.getDouble(Definition.JSON_NAVI_POSITION_X);
            //y coordinate
            double y = json.getDouble(Definition.JSON_NAVI_POSITION_Y);
            //Facing direction
            double z = json.getDouble(Definition.JSON_NAVI_POSITION_THETA);
        } catch (JSONException | NullPointerException e) {
            e.printStackTrace();
        }
    }
});

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.

Check Whether the Robot Is at a Location Point

Method name: isRobotInLocations Usage:

try {
    JSONObject params = new JSONObject();
    params.put(Definition.JSON_NAVI_TARGET_PLACE_NAME, placeName); //Location name
    params.put(Definition.JSON_NAVI_COORDINATE_DEVIATION, range); //Location range
    RobotApi.getInstance().isRobotInlocations(reqId,
            params.toString(), new CommandListener() {
                @Override
                public void onResult(int result, String message) {
                    try {
                        JSONObject json = new JSONObject(message);
                        //Whether the robot is at the target point
                        json.getBoolean(Definition.JSON_NAVI_IS_IN_LOCATION);
                    } catch (JSONException e) {
                        e.printStackTrace();
                    }
                }
            });
} catch (JSONException e) {
    e.printStackTrace();
}

Parameters

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Get the Current Map Name

Method name: getMapName Usage:

RobotApi.getInstance().getMapName(reqId, new CommandListener() {
    @Override
    public void onResult(int result, String message) {
        if (!TextUtils.isEmpty(message)) {
            //message is the map name
            String mapName = message;
        }
    }
});

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Listen for Position Status Changes

Starts a listener whose callback is triggered when the position or position status changes.

public class Pose {
    public float px, py, theta;
    public final long time;
    public String name;
    /**
     * FREE = 0;      // normal area, reachable
     * OBSTACLE = 1;  // no-go area, unreachable
     * OUTSIDE = 2;   // outside the map, unreachable
     */
    public int status;
    public float distance;
}
RobotApi.getInstance().registerStatusListener(Definition.STATUS_POSE,
    new StatusListener(){
        @Override
        public void onStatusUpdate(String type, String value) {
            Pose pose = GsonUtil.fromJson(value, Pose.class);
        }
    });

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Switch Maps

Method name: switchMap Usage:

RobotApi.getInstance().switchMap(reqId, mapName, new CommandListener(){
    @Override
    public void onResult(int result, String message) {
        if ("succeed".equals(message)) {
            //Map switched successfully
        }
    }
});

Parameters

Supported platforms:

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Note: You need to relocalize after switching maps.

Read and Display the Map PGM File (Including Map Point Coordinate Conversion)

Reading maps and converting coordinates rely on a complete set of map tools. Sample code:

    /*
     * getMap
     * Get the current map
     * The map contains the robot's current position, direction coordinates and location points that can be clicked to navigate
     * Get the current map
     * The map has current robot position information, direction coordinates and clickable navigation positions
     * Get the map.pgm file through shared memory
     * */
    private void getMap(final String name) {
        Log.d(TAG, "getMapPgmPFD: mapName=" + name);
        //Get the map.pgm file descriptor
        ParcelFileDescriptor mapPgmPFD = ShareMemoryApi.getInstance().getMapPgmPFD(name);
        FileDescriptor fd = mapPgmPFD.getFileDescriptor();
        FileInputStream fileInputStream = new FileInputStream(fd);
        //Read the data stream from the file descriptor and parse it into a RoverMap (same logic as before)
        mRoverMap = MapppUtils.loadPFD2RoverMap(fileInputStream);
        
        //TODO Custom operations
        
        //Release service-layer resources
        ShareMemoryApi.getInstance().releaseGetMapPgmPFD();
    }

    /**
     * Modify the map.pgm file through shared memory (test code)
     */
    private void setMapPgmPFD(String mapName，RoverMap roverMap) {
        byte[] bytes = MapUtils.saveRoverMapToPFDData(roverMap);
        boolean result = ShareMemoryApi.getInstance().setMapPgmPFD(mapName, bytesT);
        Log.d(TAG, "setMapPgmPFD: result=" + result);
    }

If you need this, copy or refer to the NavFragment code in the sample code. With it, you can read the map and map point information from the robot and display it as shown below.Download the code

GreetingBot	GreetingBot 2	GreetingBot Mini	LuckiBot	LuckiBot Pro	BigScreenBot
Yes	Yes	Yes	Yes	Yes	No

Enable/Disable LiDAR Data Reporting

Method name: setNavigationLineData Usage:

RobotApi.getInstance().setNavigationLineData(reqId, enabled);

Parameters

Listen for LiDAR Data

RobotApi.getInstance().registerStatusListener(Definition.STATUS_LINE_DATA,
    new StatusListener(){
        @Override
        public void onStatusUpdate(String type, String value) {
            List<Pose> list = GsonUtil.getGson().fromJson(data, new TypeToken<List<Pose>>() {
            }.getType());
        }
    });

Note: Data is only reported after you enable LiDAR data reporting with setNavigationLineData. When you are done, disable LiDAR data reporting and call unregisterStatusListener to release resources.