Navigation service
The navigation service provides the robot with the ability to move from its current position to its destination. NavigationManager provides corresponding APIs for map management, positioning, and movement.
NavigationManager can be obtained through RobotContext.
NavigationManager navigationManager = robotContext.getSystemService(NavigationManager.SERVICE);
Map library
The map data file is generated by a specific map scanning machine, which specifies the map's initial direction, map origin, distance unit, marker point, and tour route, etc. (This data is set when the map is generated and cannot be modified). After the map data file is obtained, the data above needs to be imported into the map library.
- Create a map
The map consists of marker points, overlays, trajectories, and map data, which need to be added when creating a map.
//Create a marker point Marker marker/* [1] */=new Marker.Builder(point/* [2] */).build(); //Create a overlay GroundOverlay groundOverlay /* [3] */= new GroundOverlay.Builder(width, height).build(); //Create a route Polyline polyline /* [4] */= new Polyline.Builder(id).build(); //Create a map NavMap navMap /* [5] */= new NavMap.Builder(scale).build();
[1] Marker is used to describe each coordinate point, and is constructed by Marker.Builder. The instructions are as follows:
| Methods | Descriptions |
|---|---|
| Builder.constructor(point) | The construction method is to set the coordinates of the marker point. |
| Builder.setId(id) | Set ID of the coordinate, which is the unique sign. |
| Builder.setTitle(title) | Set a title |
| Builder.addTag(tag) | Add a tag |
| Builder.addTag(index,tag) | Add a tag at the specified location |
| Builder.addTagList(taglist) | Add a tag list |
| Builder.removeTag(index) | Remove the tag at a specified location |
| Builder.setDescription(description) | Set description |
| Builder.setExtension(extension) | Set extended data, the content can be customized |
[2] Point, the coordinate is the position relative to the map origin (the unit of distance is the same as the map), and the origin is the starting point of the scan.
| Type | Attributes | Descriptions |
|---|---|---|
| float | x | x-axis coordinates |
| float | y | y-axis coordinates |
[3] GroundOverlay is overlaid on the map when displayed, it is built byGroundOverlay.Builder. The instructions are as follows:
| Methods | Descriptions |
|---|---|
| Builder.constructor(width, height) | Construction method, width and height |
| Builder.setName(name) | Set the name of the overlay |
| Builder.setType(type) | Set the type of overlay |
| Builder.setOriginInImage(originInImage) | Set the origin coordinates of the overlay |
| Builder.setImage(image) | Set the URI of the local image |
| Builder.setImageUrl(imageUrl) | Set the URL of the online image |
[4] Polyline is composed of multiple [Location] (# Location) components and is built byPolyline.Builder. The instructions are as follows:
| Methods | Descriptions |
|---|---|
| Builder.constructor(id) | Construction method, add a route id, which is the only sign |
| Builder.setName(name) | Set the name |
| Builder.setDescription(description) | Set description |
| Builder.addLocation(location) | Add a list of coordinate points included in the route |
| Builder.addLocation(index,location) | Add coordinates at the specified position |
| Builder.addLocationList(locationList) | Add a list of coordinates |
| Builder.removeLocation(index) | Remove the coordinates of the specified position |
| Builder.setExtension(extension) | Set extended data, the content can be customized |
[5] NavMap is built byNavMap.Builder, the instructions are as follows:
| Methods | Descriptions |
|---|---|
| Builder.constructor(scale) | You can zoom on the map when building it. |
| Builder.setId(id) | Set map ID |
| Builder.setName(name) | Set map name |
| Builder.setNavFile(navFileUri) | Set the path of the map data file |
| Builder.addGroundOverlay(groundOverlay) | Add an overlay |
| Builder.addGroundOverlay(index, groundOverlay) | Add an overlay at a specified position in the list |
| Builder.addGroundOverlayList(groundOverlayList) | Add an overlay list |
| Builder.removeGroundOverlay(index) | Remove the overlay at the specified position in the list |
| Builder.addMarker(marker) | Add a marker |
| Builder.addMarker(index, marker) | Mark at the specified position in the list |
| Builder.addMarkerList(markerList) | Add a marker list |
| Builder.removeMarker(index) | Remove the marker at the specified position of the list |
| Builder.addPolyline(polyline) | Add navigation route |
| Builder.addPolyline(index, polyline) | Add a navigation route at a specified position in the list |
| Builder.addPolylineList(polylineList) | Add navigation route list |
| Builder.removePolyline(index) | Remove the navigation route at the specified position in the list |
- Add a map
Promise<NavMap, NavMapException> addNavMapPromise /* [1] */= navigationManager.addNavMap(navMap); /* [2] */
[1]The method that the returned result is Promise is an asynchronous method. You can obtain the execution result by registering a callback, or you can execute the get () method to convert it to a synchronous method. For details, see async.
[2]Adding a map may take a long time, you need to be careful when using the synchronization method.
- Get the map
Promise<NavMap, NavMapException> getNavMapPromise = navigationManager.getNavMap(navMapId); Promise<List<NavMap>, NavMapException> getNavMapListPromise = navigationManager.getNavMapList();
- Edit the map
Promise<NavMap, NavMapException> modifyNavMapPromise = navigationManager.modifyNavMap(navMap);
- Remove the map
Promise<NavMap, NavMapException> removeNavMapPromise = navigationManager.removeNavMap(navMapId);
Current map
You need to set a map before using position and navigation.
- Get the current map
Promise<NavMap, NavMapException> currentNavMapPromise = navigationManager.getCurrentNavMap();
- Set the current map
Promise<NavMap, NavMapException> setCurrentNavMapPromise = navigationManager.setCurrentNavMap(navMapId);
- Remove the current map
Promise<NavMap, NavMapException> unsetCurrentNavMapPromise = navigationManager.unsetCurrentNavMap();
Positioning
The robot needs to determine its position on the map before navigation.
- Query the positioning status
//If the positioning is correct boolean locatingSelf = navigationManager.isLocatingSelf(); //If the positioning is successful boolean selfLocated = navigationManager.isSelfLocated();
- Positioning
//Default position ProgressivePromise<Location /* [1] */, LocatingException, LocatingProgress> locateSelfPromise = navigationManager.locateSelf(); //Use parameter for positioning LocatingOption locatingOption /* [2] */= new LocatingOption.Builder() .setNearby(location) .setTimeout(timeout) .build(); ProgressivePromise<Location, LocatingException, LocatingProgress> locateSelfPromise = navigationManager.locateSelf(locatingOption); //Cancel the positioning locateSelfPromise.cancel();
[1] Location location data
| Attribute getter | Descriptions |
|---|---|
| position | x-axis and y-axis coordinates are equal to the map origin |
| z | z-axis coordinates |
| rotation | Orientation angle, the range is (0 ~ 360), the angle is equal to the initial angle of the map. |
[2] LocationOption is built using LocationOption.Builder. The instructions are as follows: |
| Methods | Descriptions | Default value |
|---|---|---|
| Buidler.setTimeout(timeout) | Timeout unit: ms | -1 |
| Buidler.setNearby(useNearby) | Positioning near a specified coordinate | It will not be used by default |
- Get the current location
Location currentLocation = navigationManager.getCurrentLocation();
Navigation
- Query navigation status
boolean navigating = navigationManager.isNavigating();
- Start the navigation
NavigationOption navigationOption /* [1] */= new NavigationOption.Builder(location).build(); ProgressivePromise<Void, NavigationException, NavigationProgress/* [2] */> navigatePromise = navigationManager.navigate(navigationOption);
[1] NavigationOptionis built using NavigationOption.Builder. The instructions are as follows:
| Attributes | Description |
|---|---|
| Builder.constructor(location) | Construction method, set the destination of navigation |
| Builder.setMaxSpeed(maxSpeed) | Set the maximum speed, m/s |
| Builder.setRetryCount(retryCount) | Set the number of retries |
| Builder.setRetryInterval(retryInterval) | Set the interval of retries, ms |
| Builder.setTrackMode(trackMode) | Set whether to navigate along the track (the track information is included in the map) |
[2] NavigationProgress gets the current location via getLocation()
- Stop the navigation
navigatePromise.cancel();
Monitor the location
- Set location monitor
LocationListener locationListener = new LocationListener() { @Override public void onLocationChanged(Location location) { //Change of location } }; navigationManager.registerListener(locationListener);
- Cancel the location monitoring
navigationManager.unregisterListener(locationListener);