AIMA开放平台文档中心AimDK A3-ultra

7.9 Planning and Navigation

7.9 Planning and Navigation

7.9.1 Overview

The A3-Ultra robot comes preconfigured with basic mapping, localization, and navigation capabilities. Through the secondary development interfaces, users can perform tasks such as navigation by waypoint, navigation to a target pose, and navigation along a specified route. It also supports dynamic obstacle detection and avoidance.

There are multiple interfaces for issuing navigation tasks based on different navigation logic. Instead of documenting each interface separately, this section provides a unified explanation of the differences in their input and output parameters.

General notes for navigation task interfaces:

  1. Before executing a task, the robot must have completed relocalization successfully, and the map_id in the request must match the map used for relocalization.
  2. Before executing a task, switch the MC state to RL_LOCOMOTION_DEFAULT (reinforced straight-leg) mode. Otherwise, the robot may not respond correctly to PNC velocity commands.
  3. When issuing a task, set task_id. If it is not set (default is 0), PNC will generate a task_id automatically and return it in the response. The client should save this task_id for later control commands or task-status queries.

Code examples are in the examples/pnc/ directory. Each interface has a corresponding script whose purpose can be identified from the filename. A complete end-to-end example, from obtaining the map ID and selecting a waypoint ID to issuing a navigation task and monitoring task status, is available at example/pnc/pnc_demo.py.

Field descriptions

  • task_id: Task ID. If it is not set (default is 0), PNC will generate a task_id automatically and return it in the response. The client should save it for later control commands or task-status queries.
  • map_id: Map ID. Fill in the current map ID.
  • target_id: Navigation point ID.
  • pose: 2D world-coordinate pose.
  • pose_offset: Relative offset from the target point.
  • state: Unless otherwise specified, this indicates whether the request was successfully delivered and accepted. CommonState_SUCCESS means success; any other value means failure.
  • ackerman_mode: Reserved field, currently unused. Fill it in as shown in the example.
  • guide_line_id: Reserved field, currently unused. Fill it in as shown in the example.

7.9.2 Point-to-Point Navigation RPC Interfaces

Interface NameInterface DescriptionURLInput ParametersOutput ParametersNotes
pb:/aimdk.protocol.PncService/PlanningNaviToGoalIssues a planned navigation task for the specified target point IDhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/PlanningNaviToGoal
text
{
  "task_id": 0,
  "map_id": 1,
  "target_id": 0,
  "guide_line_id": 0,
  "ackerman_mode": false
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
Maximum arrival accuracy is approximately 0.4 m
pb:/aimdk.protocol.PncService/PlanningNaviToPose2DIssues a planned navigation task for the specified target posehttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/PlanningNaviToPose2D
text
{
  "task_id": 0,
  "map_id": 1,
  "pose": {
    "position": {
      "x": 10,
      "y": 5
    },
    "angle": 3.14159
  },
  "ackerman_mode": false
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
Maximum arrival accuracy is approximately 0.4 m
pb:/aimdk.protocol.PncService/LinearNaviToRelativeIssues a straight-line navigation task for the specified relative target posehttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/LinearNaviToRelative
text
{
  "task_id": 1,
  "map_id": 1,
  "pose": {
    "position": {
      "x": 1,
      "y": 1
    },
    "angle": 1.57
  }
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
First performs an in-place rotation, then moves in a straight line
pb:/aimdk.protocol.PncService/LinearNaviToGoalIssues a straight-line navigation task for the specified target point IDhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/LinearNaviToGoal
text
{
  "task_id": 0,
  "map_id": 1,
  "target_id": 0
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
First performs an in-place rotation, then moves in a straight line
pb:/aimdk.protocol.PncService/LinearNaviToPose2DIssues a straight-line navigation task for the specified target posehttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/LinearNaviToPose2D
text
{
  "task_id": 0,
  "map_id": 1,
  "pose": {
    "position": {
      "x": 1,
      "y": 1
    },
    "angle": 1.57
  }
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
First performs an in-place rotation, then moves in a straight line
pb:/aimdk.protocol.PncService/DirectNaviToRelativeGoalIssues a direct-movement task for the specified target point IDhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/DirectNaviToRelativeGoal
text
{
  "task_id": 0,
  "map_id": 1,
  "target_id": 0
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
Translates and rotates simultaneously. Suitable only when the target orientation differs little from the robot orientation; otherwise the arrival error may be large
pb:/aimdk.protocol.PncService/DirectNaviToRelativeIssues a direct-movement task for the specified relative target posehttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/DirectNaviToRelative
text
{
  "task_id": 0,
  "map_id": 1,
  "pose": {
    "position": {
      "x": 1,
      "y": 1
    },
    "angle": 0
  }
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
pb:/aimdk.protocol.PncService/PreciseNaviToGoalIssues a high-precision navigation task for the specified target point IDhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/PreciseNaviToGoal
text
{
  "task_id": 0,
  "map_id": 1,
  "target_id": 0,
  "pose_offset": {
    "position": {
      "x": 1,
      "y": 1
    },
    "angle": 0
  }
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
For special high-precision arrival scenarios only. The robot first moves to a point about 0.5 m behind the target using normal planned navigation, then moves directly to the target. During direct movement it does not avoid obstacles and may adjust multiple times. Arrival accuracy is about 0.1 m. Ensure there is enough space behind the target point. This mode is not recommended unless necessary.

7.9.3 Simple Movement RPC Interfaces

Interface NameInterface DescriptionURLInput ParametersOutput ParametersNotes
pb:/aimdk.protocol.PncService/SpinTurnAndMoveForwardIssues a task for in-place rotation followed by straight forward movementhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/SpinTurnAndMoveForward
text
{
  "task_id": 0,
  "map_id": 1,
  "angle": 3.14159,
  "distance": 1
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
pb:/aimdk.protocol.PncService/SpinTurnIssues an in-place rotation taskhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/SpinTurn
text
{
  "task_id": 0,
  "map_id": 1,
  "angle": 3.14159
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
pb:/aimdk.protocol.PncService/MoveForwardIssues a straight-line translation taskhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/MoveForward
text
{
  "task_id": 0,
  "map_id": 1,
  "angle": 0,
  "distance": 1
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
The robot orientation does not change after the task finishes

7.9.4 Task Query and Control RPC Interfaces

Interface NameInterface DescriptionURLInput ParametersOutput ParametersNotes
pb:/aimdk.protocol.PncService/ActionCancelIssues a task-cancel commandhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/ActionCancel
text
{
  "task_id": 6874745825616545102
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
The command is accepted only when `task_id` matches; otherwise `CommonState_FAILURE` is returned
pb:/aimdk.protocol.PncService/ActionPauseIssues a task-pause commandhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/ActionPause
text
{
  "task_id": 6874745825616545102
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
The command is accepted only when `task_id` matches; otherwise `CommonState_FAILURE` is returned
pb:/aimdk.protocol.PncService/ActionResumeIssues a command to resume a paused taskhttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/ActionResume
text
{
  "task_id": 6874745825616545102
}
text
{
  "task_id": "9820900024371944166",
  "state": "CommonState_SUCCESS"
}
The command is accepted only when `task_id` matches; otherwise `CommonState_FAILURE` is returned
pb:/aimdk.protocol.PncService/ActionGetStateGets the navigation task statushttp://10.42.10.11:53176/rpc/aimdk.protocol.PncService/ActionGetState
text
{
  "task_id": 0
}
text
{
  "task_id": "9820900024371944166",
  "state": "PncServiceState_RUNNING"
}
  • state: Task status
    • PncServiceState_UNDEFINED: Unknown status
    • PncServiceState_IDLE: No task is currently running
    • PncServiceState_RUNNING: Task is running
    • PncServiceState_PAUSED: Task is paused
    • PncServiceState_SUCCESS: Task completed successfully
    • PncServiceState_FAILED: Task failed
If the requested `task_id` is `0`, the service returns the most recent task ID and its corresponding status. For any other non-matching `task_id`, `PncServiceState_FAILED` is returned.