-
Notifications
You must be signed in to change notification settings - Fork 87
Locations
There are two main use cases with regards to locations. The first is location management, and the second is location navigation. The SDK provides methods that allows developers to handle both.
Location management allows you to control temi's locations by saving, deleting, fetching and monitoring their changes, while location navigation allows you to send temi to one of those locations and monitor its navigation status while it's in motion.
Map is a combination of:
- Processed lidar data from ROBOX, the algorithm core of temi
- Map elements, including locations, green paths, and virtual walls.
- Map image, a visual abstraction of map raw data for UI presentation.
A map can be loaded, switched, backed up, and cached.
There may be some confusion as map id is referred under its context.
When reference map on algorithm wise, e.g. MapDataModel, it has a map id which is unique across algorithm map, the one from process lidar data. This id should be only used by ROBOX as an identifier, and served no other purpose.
When (SDK) users load a map, they are using the map id idenfying the combination. e.g. MapModel. This id is generated from temi cloud service when we back up a map to cloud. Thus it can be fetched from cloud, and reloaded to the robot.
When user backups or imports a map from UI or SDK, the map combination will be cached locally for quicker access next time. So when you switching between different maps, the large map file will not be downloaded every time. Starting from 129 version, there are methods to load map from cloud to cache, also force load map from cache.
From 129 version, we offered the developer access of multifloor function from SDK. This should benefit temi robots serving in complex or dynamic cartographic environments. Once enabled, all the floor APIs can be used, also a new map editor with multifloor functions will be available in temi settings.
Every floor contains a standalone map, which has all map attributes and can be created, recreated, replaced, backed up, plus the features in multifloor of like copying map from other floor. Such operations on one floor will not affect map on other floors.
All the floors and their maps are stored locally on the robot and can be switched offline until they are deleted from the user operations in the map editor.
Interface | Description |
---|---|
OnLocationsUpdatedListener | Locations updated listener |
OnGoToLocationStatusChangedListener | Go to location(position) status changed listener |
OnDistanceToLocationChangedListener | Distance to locations changed listener |
OnCurrentPositionChangedListener | Current position changed listener |
OnReposeStatusChangedListener | Listener for the status changed of repositioning |
OnLoadMapStatusChangedListener | Listener for the status changed of loading map |
OnDistanceToDestinationChangedListener | Listener for the distance left to the destination |
OnLoadFloorStatusChangedListener | Listener for the status of switching of floor |
Model | Description |
---|---|
Position | Position(coordinate) in the map |
MapDataModel | The map data |
MapImage | The map image data |
Floor | The floor data |
Use this method to save a new location for temi. Locate temi at the location you wish to save and give it a name, the location coordinates are extracted and passed automatically in the request.
-
Parameters
Parameter Type Description location String Location name you wish to save -
Return
Type Description boolean true
if save successfully,false
otherwise -
Prototype
boolean saveLocation(String location);
-
Required permissions
None.
-
Support from
0.10.36
Use this method to delete a saved location.
-
Parameters
Parameter Type Description location String Location name you wish to delete -
Return
Type Description boolean true
if delete successfully,false
otherwise -
Prototype
boolean deleteLocation(String location);
-
Required permissions
None.
-
Support from
0.10.44
Use this method to fetch a list of saved locations.
-
Return
Type Description List<String> Locations list -
Prototype
List<String> getLocations();
-
Required permissions
None.
-
Support from
0.10.36
Use this method to send temi to one of your saved locations.
-
Parameters
Parameter Type Description location String Location name you wish the robot to navigate to backwards boolean If true
will walk backwards to the destination.false
by default. Support from 0.10.80noByPass boolean If true
will disallow bypass the obstacles during go to. Passnull
to follow the Settings -> Navigation Settings. Support from 0.10.80speedLevel SpeedLevel The speed level of this single go to session. Pass null
to start with the speed level in Settings -> Navigation Settings. Support from 0.10.80 -
Prototype
void goTo(String location, boolean backwards, boolean noBypass, SpeedLevel speedLevel);
-
Required permissions
None.
-
Support from
0.10.36
Use this method to get the map data.
This method currently(0.10.70) only supports relatively small map, we will support large map in the next version.
(Fixed in version 0.10.71)
Newly added virtual walls, navigation paths and locations data in 0.10.74.
-
Return
Type Description MapDataModel The map data -
Prototype
MapDataModel getMapData();
-
Required permissions
Map
-
Support from
0.10.70
-
Note
This method is a time-consuming operation and is recommended to be used in a non-main thread. For more details please refer to the Sampe code.
Use this method to send temi to a specific position(coordinate).
-
Parameters
Parameter Type Description position Position Destination coordinate. Ignore its' attribute tiltAngle
in this method.backwards boolean If true
will walk backwards to the destination.false
by default. Support from 0.10.80noByPass boolean If true
will disallow bypass the obstacles during go to. Passnull
to follow the Settings -> Navigation Settings. Support from 0.10.80speedLevel SpeedLevel The speed level of this single go to session. Pass null
to start with the speed level in Settings -> Navigation Settings. Support from 0.10.80 -
Prototype
void goToPosition(Position position, boolean backwards, boolean noBypass, SpeedLevel speedLevel);
-
Required permissions
None.
-
Support from
0.10.70
Use this method to start repositioning if temi has lost his position(Caused by being lifted, dragged, etc.).
-
Prototype
void repose();
-
Required permissions
None.
-
Support from
0.10.72
Use this method to get the list of the backed up maps.
-
Return
Type Description List<MapModel> List of maps -
Prototype
List<MapModel> getMapList();
-
Required permissions
Map
-
Support from
0.10.74
Use this method to load the map by map ID.
-
Parameters
Parameter Type Description mapId String ID of the map backup in MapModel -
Return
Type Description String Request id. In the format of UUID, e.g. 538b44c9-fdcf-426a-9693-d72e9c0f9550. Used in onLoadMapStatusChanged callback to track load map result. Supported from 129 version, otherwise void is returned -
Prototype
String loadMap(String mapId);
-
Required permissions
Map
-
Support from
0.10.74
Use this method to load the map by map ID and the specific position of the target map.
Only map Id is required, other parameters are optional with default values set.
-
Parameters
Parameter Type Description mapId String ID of the map backup in MapModel reposeRequired boolean Need to do repose after loading map or not, default as false position Position The position of robot on the target map to loading the map. If not set, target map will be loaded from home base. Default as null offline boolean Skip fetching the latest map data of target mapId and use local cache instead, default as false. Supported from 129 version withoutUI boolean Load the map in the background without showing any blocking UI, default as false. Supported from 129 version -
Return
Type Description String Request id. In the format of UUID, e.g. 538b44c9-fdcf-426a-9693-d72e9c0f9550. Used in onLoadMapStatusChanged callback to track load map result. Supported from 129 version, otherwise void is returned -
Prototype
String loadMap(String mapId, boolean reposeRequired, Position position, boolean offline, boolean withoutUI);
-
Required permissions
Map
-
Support from
0.10.76
Enable/Disable Multi-floor function
-
Parameters
Parameter Type Description enabled boolean true to enable,false to disable -
Return
Type Description boolean true if set, false if failed -
Prototype
boolean setMultiFloorEnabled(boolean enabled);
-
Required permissions
MAP, SETTINGS
-
Support from
1.129.0
Check Multi-floor function
-
Return
Type Description boolean true if enabled, false if not, null if Robot in not initiated -
Prototype
boolean isMultiFloorEnabled();
-
Required permissions
None.
-
Support from
1.129.0
Get current floor data
-
Return
Type Description Floor Current floor data, null if service is not initiated, or lack of permission, or no floor data -
Prototype
Floor getCurrentFloor();
-
Required permissions
MAP
-
Support from
1.129.0
Get all floors' data
-
Return
Type Description List<Floor> All floors' data, empty if service is not initiated, or lack of permission, or no floor data -
Prototype
List<Floor> getAllFloors();
-
Required permissions
MAP
-
Support from
1.129.0
load target floor
-
Parameters
Parameter Type Description floorId int floor id position Position Position in map on the target floor to be loaded from -
Prototype
void loadFloor(int floorId, Position position);
-
Required permissions
MAP
-
Support from
1.129.0
Set your context to implement this listener and add the override method to get the list of saved locations every time it changes.
package com.robotemi.sdk.listeners;
interface OnLocationsUpdatedListener {}
-
Parameters
Parameter Type Description locations List<String> All saved locations list -
Prototype
abstract void onLocationsUpdated(List<String> locations)
-
Parameters
Parameter Type Description listener OnLocationsUpdatedListener An instance of a class that implements this interface -
Prototype
void addOnLocationsUpdatedListener(OnLocationsUpdatedListener listener);
-
Parameters
Parameter Type Description listener OnLocationsUpdatedListener An instance of a class that implements this interface -
Prototype
void removeOnLocationsUpdatedListener(OnLocationsUpdatedListener listener);
-
Support from
0.10.36
Set your context to implement this listener and add the override method to get navigation information regarding temi's go to location action.
package com.robotemi.sdk.listeners;
interface OnGoToLocationStatusChangedListener {}
Constant | Type | Value | Description |
---|---|---|---|
START | String | "start" | Navigation to the location has started |
CALCULATING | String | "calculating" | Calculating the route to the location |
GOING | String | "going" | Calculated the route and is on its' way |
COMPLETE | String | "complete" | Arrived at the desired location |
ABORT | String | "abort" | Navigation aborted |
REPOSING | String | "reposing" | Reposing during the navigation |
-
Parameters
Parameter Type Description location String The name of the location temi is navigating to status String Navigation status descriptionId int Numerical code that reflects the description of the status description String Verbose more informative description of the navigation status (Such as obstacle info) -
DescriptionId 对应内容
DescriptionId Description 500 "Complete" 0 "Abort General" 1003 "Abort no movement" 1004 "Abort timeout" 1005 "Abort by user" 1006 "Abort out of map bounds" 1060 "Path Plan" 2000 "Obstacle" 2001 "Ground Obstacle" 2002 "Hight Obstacle" 2003 "Lidar Obstacle" 2004 "Front Obstacle" 2005 "Back Obstacle" 2006 "Abyss Obstacle" 2007 "Virtual Wall Obstacle" 2008 "Cliff Detected" 2009 "Stuck Wheel" 1020- 1050 "Calculating" 5000- 5021 "Calculating" 10007 "Going" - "Unknown" -
Prototype
void onGoToLocationStatusChanged(String location, String status, int descriptionId, String description);
-
Parameters
Parameter Type Description listener OnGoToLocationStatusChangedListener An instance of a class that implements this interface -
Prototype
void addOnGoToLocationStatusChangedListener(OnGoToLocationStatusChangedListener listener);
-
Parameters
Parameter Type Description listener OnGoToLocationStatusChangedListener An instance of a class that implements this interface -
Prototype
void removeOnGoToLocationStatusChangedListener(OnGoToLocationStatusChangedListener listener);
-
Support from
0.10.36
Set your context to implement this listener and add the override method to get the distances to saved locations.
package com.robotemi.sdk.navigation.listener;
interface OnDistanceToLocationChangedListener {}
-
Parameters
Parameter Type Description distances Map<String, Float> A key-value pair collection with String
type key(location name) andFloat
type value(distance) -
Prototype
void onDistanceToLocationChanged(Map<String, Float> distances);
-
Parameters
Parameter Type Description listener OnDistanceToLocationChangedListener An instance of a class that implements this interface -
Prototype
void addOnDistanceToLocationChangedListener(OnDistanceToLocationChangedListener listener);
-
Parameters
Parameter Type Description listener OnDistanceToLocationChangedListener An instance of a class that implements this interface -
Prototype
void removeOnDistanceToLocationChangedListener(OnDistanceToLocationChangedListener listener);
-
Support from
0.10.70
Set your context to implement this listener and add the override method to get current position information.
package com.robotemi.sdk.navigation.listener;
interface OnCurrentPositionChangedListener {}
-
Parameters
Parameter Type Description position Position Current position -
Prototype
void onCurrentPositionChanged(Position position);
-
Parameters
Parameter Type Description listener OnCurrentPositionChangedListener An instance of a class that implements this interface -
Prototype
void addOnCurrentPositionChangedListener(OnCurrentPositionChangedListener listener);
-
Parameters
Parameter Type Description listener OnCurrentPositionChangedListener An instance of a class that implements this interface -
Prototype
void removeOnCurrentPositionChangedListener(OnCurrentPositionChangedListener listener);
-
Support from
0.10.70
Set your context to implement this listener and add the override method to listen to the status changes of repositioning.
package com.robotemi.sdk.navigation.listener;
interface OnReposeStatusChangedListener {}
All constants here are only for the status of repositioning.
Constant | Type | Value | Description |
---|---|---|---|
IDLE | int | 0 | Idle |
REPOSE_REQUIRED | int | 1 | Ready to reposition |
REPOSING_START | int | 2 | Reposition started |
REPOSING_GOING | int | 3 | Repositioning |
REPOSING_COMPLETE | int | 4 | Reposition completed |
REPOSING_OBSTACLE_DETECTED | int | 5 | Obstacle detected during repositioning |
REPOSING_ABORT | int | 6 | Reposition abort |
-
Parameters
Parameter Type Description status int Status of reposition description String Description of status -
Prototype
void onReposeStatusChanged(int status, String description);
-
Parameters
Parameter Type Description listener OnReposeStatusChangedListener An instance of a class that implements this interface -
Prototype
void addOnReposeStatusChangedListener(OnReposeStatusChangedListener listener);
-
Parameters
Parameter Type Description listener OnReposeStatusChangedListener An instance of a class that implements this interface -
Prototype
void removeOnReposeStatusChangedListener(OnReposeStatusChangedListener listener);
-
Support from
0.10.72
Set your context to implement this listener and add the override method to listen to the status changes of loading map.
package com.robotemi.sdk.map;
interface OnLoadMapStatusChangedListener {}
All constants here are only for the status of loading map.
Constant | Type | Value | Description |
---|---|---|---|
COMPLETE | int | 0 | Complete |
START | int | 1 | Start |
ERROR_UNKNOWN | int | 1000 | Unknown error |
ERROR_ABORT_FROM_ROBOX | int | 2000 | Abort by Robox |
ERROR_ABORT_ON_NOT_CHARGING | int | 2001 | Loading without charging |
ERROR_ABORT_BUSY | int | 2002 | temi is on another blocking task |
ERROR_ABORT_ON_TIMEOUT | int | 3000 | Timeout |
ERROR_PB_STREAM_FILE_INVALID | int | 4000 | Invalid PB file |
ERROR_GET_MAP_DATA | int | 5000 | Get error while getting map data from remote |
-
Parameters
Parameter Type Description status int Status of loading map requestId String Request id obtained from loadMap(), Supported from 129. -
Prototype
void onLoadMapStatusChanged(int status, String requestId);
-
Parameters
Parameter Type Description listener OnLoadMapStatusChangedListener An instance of a class that implements this interface -
Prototype
void addOnLoadMapStatusChangedListener(OnLoadMapStatusChangedListener listener);
-
Parameters
Parameter Type Description listener OnLoadMapStatusChangedListener An instance of a class that implements this interface -
Prototype
void removeOnLoadMapStatusChangedListener(OnLoadMapStatusChangedListener listener);
-
Support from
0.10.74
Set your context to implement this listener and add the override method to get the distance to the destination.
package com.robotemi.sdk.navigation.listener;
interface OnDistanceToDestinationChangedListener {}
-
Parameters
Parameter Type Description location String Location name of the destination distance float Distance to the destination -
Prototype
void onDistanceToDestinationChanged(location: String, distance: Float);
-
Parameters
Parameter Type Description listener OnDistanceToDestinationChangedListener An instance of a class that implements this interface -
Prototype
void addOnDistanceToDestinationChangedListener(OnDistanceToDestinationChangedListener listener);
-
Parameters
Parameter Type Description listener OnDistanceToDestinationChangedListener An instance of a class that implements this interface -
Prototype
void removeOnDistanceToDestinationChangedListener(OnDistanceToDestinationChangedListener listener);
-
Support from
0.10.80
Set your context to implement this listener and add the override method to get the status for loading.
package com.robotemi.sdk.map;
interface OnLoadFloorStatusChangedListener {}
-
Parameters
Parameter Type Description status int 0 complete
1 start
-1 error -
Prototype
void onLoadFloorStatusChanged(int status);
-
Parameters
Parameter Type Description listener OnLoadFloorStatusChangedListener An instance of a class that implements this interface -
Prototype
void addOnLoadFloorStatusChangedListener(OnLoadFloorStatusChangedListener listener);
-
Parameters
Parameter Type Description listener OnLoadFloorStatusChangedListener An instance of a class that implements this interface -
Prototype
void removeOnLoadFloorStatusChangedListener(OnLoadFloorStatusChangedListener listener);
-
Support from
1.129.0
Used to hold the position information.
package com.robotemi.sdk.navigation.model;
class Position {}
Attribute | Type | Description |
---|---|---|
x | float | Position coordinate x |
y | float | Position coordinate y |
yaw | float | - |
tiltAngle | int | Head tilt angle |
Used to hold the map data.
package com.robotemi.sdk.map;
class MapDataModel {}
Attribute | Type | Description |
---|---|---|
mapImage | MapImage | The map image data |
mapId | String | Map ID, this is the identifier of map data, which is different from id in MapModel, which is used to identify map backups |
mapInfo | MapInfo | Map information |
virtualWalls | List<Layer> | Layer collection of virtual walls |
greenPaths | List<Layer> | Layer collection of navigation paths |
locations | List<Layer> | Layer collection of locations |
Used to hold the map image data.
package com.robotemi.sdk.map;
class MapImage {}
Attribute | Type | Description |
---|---|---|
typeId | String | - |
rows | int | The size of the rows of the map data matrix |
cols | int | The size of the columns of the map data matrix |
dt | String | - |
data | List<Integer> | The one-dimensional array converted from map data matrix |
Used to hold the map information.
package com.robotemi.sdk.map;
class MapInfo {}
Attribute | Type | Description |
---|---|---|
height | int | height |
width | int | width |
originX | float | Origin coordinate x |
originY | float | Origin coordinate y |
resolution | float | Resolution |
Used to hold the map layer data.
package com.robotemi.sdk.map;
class Layer {}
Attribute | Type | Description |
---|---|---|
layerCreationUTC | int | Timestamp of creating the layer |
layerCategory | int | Layer category |
layerId | String | Layer ID |
layerThickness | float | Layer thickness |
layerStatus | int | Layer status |
layerPoses | List<LayerPose> | Coordinate collection of the layer |
Used to hold the coordinate data that make up the map layer.
package com.robotemi.sdk.map;
class LayerPose {}
Attribute | Type | Description |
---|---|---|
x | float | Coordinate x |
y | float | Coordinate y |
theta | float | - |
package com.robotemi.sdk.map;
class MapDataModelKt {}
Constant | Type | Value | Description |
---|---|---|---|
GREEN_PATH | int | 0 | Navigation path |
VIRTUAL_WALL | int | 3 | Virtual wall |
LOCATION | int | 4 | Location |
Constant | Type | Value | Description |
---|---|---|---|
STATUS_CURRENT | int | 0 | |
STATUS_UPDATE | int | 1 | |
STATUS_ADD_POSE | int | 2 | |
STATUS_DELETE | int | 3 |
Used to hold the map information of the backed up map list.
package com.robotemi.sdk.map;
class MapModel {}
Attribute | Type | Description |
---|---|---|
id | String | ID of the map backup |
name | String | Name of the map |
Used to hold the information of the floor.
package com.robotemi.sdk.map;
class Floor {}
Attribute | Type | Description |
---|---|---|
id | String | ID of the floor |
name | String | Name of the floor |
mapId | String | mapId of the floor, this is the one from MapDataModel |
locations | List | locations on the floor |