.. _LocalPlanner:

LocalPlanner
============

.. cpp:namespace:: pilot::LocalPlanner

Module
------

The `LocalPlanner` module generates velocity commands to keep the robot on a given path or to reach a certain goal which is in reach.
Usually the given path is generated by the :ref:`HybridPlanner` and depending on configuration further optimized by the `LocalPlanner`.

Most functions require a special permission, see :ref:`pilot.permission_e`.


Functions
---------

Common Parameters
^^^^^^^^^^^^^^^^^

``goal_options_t options``
	Optional goal options, see :ref:`pilot.goal_options_t`. If not specified will use default values.
	
``Hash64 job``
	Optional job id, to identify the new goal. If not specified (or set to zero) will generate a new random id. See :ref:`vnx.Hash64`.

General Functions
^^^^^^^^^^^^^^^^^

.. cpp:function:: Path2D* get_path() const
	
	Returns the current map path being followed, if any. See :ref:`pilot.Path2D`.
	
.. cpp:function:: LocalPlannerState get_state() const
	
	Returns the current planner state. See :ref:`pilot.LocalPlannerState`.
	
Movement Functions
^^^^^^^^^^^^^^^^^^

.. cpp:function:: void cancel_goal()
	
	Will cancel any pending goal and bring the robot to an immediate stop.
	Requires permission ``MOVE``.
	
.. cpp:function:: void set_path(Path2D* path, goal_options_t options)
	
	Sets a new path to be followed and returns immediately. Any pending goal is canceled beforehand.
	The path needs to be in map coordinates.
	See :ref:`pilot.Path2D`. Requires permission ``MOVE``.
	
.. cpp:function:: void update_path(Path2D* path, goal_options_t options)
	
	Updates the current path to be followed without stopping or canceling the current goal.
	If the new path does not include the current position (to within some tolerance) a failure will be issued.
	The path needs to be in map coordinates and it's ``job`` id needs to match the current job id.
	See :ref:`pilot.Path2D`. Requires permission ``MOVE``.
	
.. cpp:function:: void follow_path(Path2D* path, goal_options_t options)
	
	Same as ``set_path(...)`` but will block until the goal is reached or canceled.
	See :ref:`pilot.Path2D`. Requires permission ``MOVE``.
	
.. cpp:function:: void set_goal(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Sets a new goal position, either relative to the current position or an absolute map position.
	The new goal must be within reach, with a maximum distance depending on configuration, but usually around 1 m.
	See :ref:`pilot.PathPoint2D`. Requires permission ``MOVE``.
	
.. cpp:function:: void move_to(PathPoint2D goal, goal_options_t options, Hash64 job)
	
	Same as ``set_goal(...)`` but will block until the goal is reached or canceled.
	See :ref:`pilot.PathPoint2D`. Requires permission ``MOVE``.