简单指挥官API
概述
Nav2简单（Python3）指挥官的目标是为Python3用户提供“作为库的导航”能力。我们提供了一个处理ROS 2和动作服务器任务的API，以便您可以专注于构建应用程序，利用Nav2的功能（在您使用所选的插件进行配置后）。我们还为您提供了API用法的演示和示例，以构建自主移动机器人的常见基本功能，这些位于``nav2_simple_commander``软件包中。
下面是一个简单的演示。注意：goToPose(), goThroughPoses(), ``followWaypoints()``等函数是**非阻塞**的，因此您可以在单线程应用程序中接收和处理反馈。因此，在等待任务完成时，使用``while not nav.isTaskComplete()``的设计来轮询导航完成情况的更改是必要的。如果任务没有完成，您可以执行一些对应用程序有意义的任务（例如处理反馈、处理机器人收集的数据或检查故障）。
您可以使用此简单指挥官来中断相同类型的命令（例如，您可以使用另一个``goToPose()``来中断``goToPose()``），但是如果在``goToPose()``、``goThroughPoses()``或``followWaypoints()``之间切换，您必须显式取消当前命令并发出新命令。
from nav2_simple_commander.robot_navigator import BasicNavigator
import rclpy
rclpy.init()
nav = BasicNavigator()
# ...
nav.setInitialPose(init_pose)
nav.waitUntilNav2Active() # if autostarted, else use lifecycleStartup()
# ...
path = nav.getPath(init_pose, goal_pose)
smoothed_path = nav.smoothPath(path)
# ...
nav.goToPose(goal_pose)
while not nav.isTaskComplete():
feedback = nav.getFeedback()
if feedback.navigation_duration > 600:
nav.cancelTask()
# ...
result = nav.getResult()
if result == TaskResult.SUCCEEDED:
print('Goal succeeded!')
elif result == TaskResult.CANCELED:
print('Goal was canceled!')
elif result == TaskResult.FAILED:
print('Goal failed!')
指挥官 API
基本导航器提供的方法如下所示，包括输入和预期返回值。如果服务器出现故障，可能会抛出异常或返回`None`对象，请确保在try/catch中正确包装您的导航调用，并检查返回值的`None`类型。
机器人导航器方法 |
描述 |
|---|---|
setInitialPose(initial_pose) |
将机器人的初始姿态（ |
goThroughPoses(poses, behavior_tree='') |
请求机器人按顺序通过一组姿态（``PoseStamped``列表）。 |
goToPose(pose, behavior_tree='') |
请求机器人驶向一个姿态（ |
followWaypoints(poses) |
请求机器人按照一组路径点（``PoseStamped``的列表）行进。这将在每个姿态上执行选择的``TaskExecutor``插件。 |
followPath(path, controller_id='', goal_checker_id='') |
请求机器人按照起始和目标``PoseStamped``（ |
spin(spin_dist=1.57, time_allowance=10) |
请求机器人执行给定角度的就地旋转。 |
backup(backup_dist=0.15, backup_speed=0.025, time_allowance=10) |
请求机器人后退给定距离。 |
assistedTeleop(time_allowance=30) |
请求机器人运行辅助遥控操作。 |
cancelTask() |
取消正在进行的任务，包括路径跟踪任务。 |
isTaskComplete（trackingRoute=False） |
检查任务是否已完成，超时时间为``100ms``。如果已完成则返回``True``，如果仍在进行则返回``False``。如果检查路径跟踪任务，请将默认参数设置为``True``。 |
getFeedback（trackingRoute=False） |
从任务获取反馈，返回操作服务器的反馈消息。如果在跟踪任务中获取反馈，请将默认参数设置为 |
getResult（） |
获取任务的最终结果，在 |
getPath（start，goal，planner_id=''，use_start=False） |
获取从起始点到目标点的路径，类型为 |
getPathThroughPoses（start，goals，planner_id=''，use_start=False） |
获取从起始点到一组目标点的路径，类型为一组 |
getRoute（start，goal，use_start=False） |
获取从起始点到目标点的稀疏路线和稠密路径，其中起始点和目标点可以是 |
getandTrackRoute（start，goal，use_start=False） |
获取并跟踪从起始点到目标点的稀疏路线和稠密路径，其中起始点和目标点可以是 |
smoothPath(path, smoother_id='', max_duration=2.0, check_for_collision=False) |
平滑给定类型为 |
changeMap(map_filepath) |
请求从当前地图切换到 map_filepath 的 YAML 地图。 |
clearAllCostmaps() |
清除全局和本地代价地图。 |
clearLocalCostmap() |
清除本地代价地图。 |
clearGlobalCostmap() |
清除全局代价地图。 |
getGlobalCostmap() |
返回全局代价地图， |
getLocalCostmap() |
返回本地代价地图， |
waitUntilNav2Active( navigator='bt_navigator', localizer='amcl') |
阻塞直到 Nav2 完全在线并且生命周期节点处于活动状态。与自动启动或外部生命周期引导一起使用。可以指定自定义导航器和定位器节点。 |
lifecycleStartup() |
向所有生命周期管理服务器发送请求，将它们带入活动状态。如果 |
lifecycleShutdown() |
向所有生命周期管理服务器发送请求，关闭它们。 |
destroyNode() |
释放对象使用的资源。 |
Costmap API
这是针对堆栈中 costmap 2d 消息的 Python3 API。它提供了在 costmap 2d C++ API 中找到的基本转换、获取/设置和处理语义。
Costmap Method |
描述 |
|---|---|
getSizeInCellsX() |
获取地图的单元格宽度。 |
getSizeInCellsY() |
获取地图高度（以单元格为单位）。 |
getSizeInMetersX() |
获取地图在 x 轴上的尺寸（以米为单位）。 |
getSizeInMetersY() |
获取地图在 y 轴上的尺寸（以米为单位）。 |
getOriginX() |
获取地图的 x 轴原点位置 [m]。 |
getOriginY() |
获取地图的 y 轴原点位置 [m]。 |
getResolution() |
获取地图分辨率 [m/单元格]。 |
getGlobalFrameID() |
获取全局 frame_id。 |
getCostmapTimestamp() |
获取代价地图的时间戳。 |
getCostXY(mx, my) |
使用地图坐标中的mx（ |
getCostIdx（index） |
使用索引（ |
setCost（mx，my，cost） |
使用地图坐标中的mx（ |
mapToWorld（mx，my） |
使用地图坐标中的mx（ |
worldToMapValidated（wx，wy） |
使用世界坐标XY上的wx（ |
getIndex（mx，my） |
使用地图坐标XY中的mx（ |
足迹碰撞检查器 API
这是一个用于足迹碰撞检测的Python3 API。它提供了操纵坐标和计算给定地图中足迹成本所需的方法。
足迹碰撞检查器方法 |
描述 |
|---|---|
footprintCost(footprint) |
检查隐含提供的坐标姿态处的足迹（ |
lineCost(x0, x1, y0, y1, step_size=0.5) |
沿着一条线迭代所有点，并检查是否发生碰撞。该线由 x0、y0、x1、y1、step_size（ |
worldToMapValidated（wx，wy） |
使用世界坐标XY的wx（浮点数）[m]和wy（浮点数）[m]获取地图坐标XY的mx（整数）和my（整数）。如果wx和wy坐标无效，则返回（None，None）。如果尚未通过（setCostmap（costmap））定义costmap，则返回None。 |
pointCost(x, y) |
使用地图坐标XY获取costmap中某一点的成本。（整数） |
setCostmap(costmap) |
指定足迹碰撞检测使用的costmap。（PyCostmap2D） |
footprintCostAtPose(x, y, theta, footprint) |
在地图坐标中获取特定姿态处足迹的成本。x，y，theta（浮点数）足迹（多边形）。 |
示例和演示
所有这些内容都可以在`package <https://github.com/ros-planning/navigation2/tree/main/nav2_simple_commander>`_中找到。
nav2_simple_commander 提供了一些示例，以突出显示作为用户可用的 API 函数：
example_nav_to_pose.py- 演示导航器的导航到位姿功能，以及一些辅助方法。example_nav_through_poses.py- 演示导航器通过姿势导航的能力，以及一些辅助方法。example_waypoint_follower.py- 演示导航器的路径点跟随功能，以及一些辅助方法。example_follow_path.py- 演示导航器的路径跟随能力，以及一些辅助方法，如路径平滑。example_assisted_teleop.py- 演示导航器的辅助遥控功能。example_route.py- 演示导航器的路由服务器功能。
``nav2_simple_commander``有几个演示，可以突出使用API构建的几个简单自主应用程序：
demo_security.py- 一个简单的安保机器人应用程序，展示了如何使用导航通过姿势进行巡逻路线。demo_picking.py- 一个简单的物品拾取应用程序，展示了如何让机器人驶向仓库中的特定货架，要么拾取物品，要么让人员将物品放入篮子并将其送到目的地以供发货，使用导航到位姿功能。demo_inspection.py- 一个简单的货架检查应用程序，展示了如何使用Waypoint Follower和任务执行器来拍照、RFID扫描等，以分析当前货架状态并定位仓库中的物品。