This folder encapsulates the task execution interface packages that dictate the high level behaviour of the stretch robot. The packages are:
task_execution_msgs
- The interface(s) between the task execution and monitoring nodestask_executor
- Creates nodes with action clients, service clients, subscribers, publishers, etc. to communicate with the rest of the robot and dictate other nodes to perform the task. Also contains code to sequence the capabilities as necessary.task_monitor
- Creates nodes to monitor the progress of tasks on the task executor. In the event of task failure, the nodes in this package figure out recovery mechanisms.
Note: Task monitor implementation does not contain any monitors as of now
By default, the task_executor
nodes and the task_monitor
nodes should startup with the following command:
roslaunch task_executor stretchit.launch
Each of the packages does have a primary launch file that is invoked by stretchit.launch
:
Further details can be found in the respective packages.
The overall architecture between the packages is shown in the following figure.
At a high level, the flow of control is as follows:
- Tasks, defined as sequences of robot actions, are assigned to the
task_executor
node using anExecuteActionGoal
. The available tasks are generally defined attasks.yaml
- The
task_executor
calls various actions, services, etc. in the robot system to accomplish the task. As part of the execution, there are 2 sources of information that the executor can use to parameterize its actions or the control flow: Link to the Task Executor README- The
database
node contains known locations and/or joint poses in the environment that can be used as inputs for actions. The entries in thedatabase
are generally available indata.yaml
- The
beliefs
node is designed to keep track of semantic aspects of the robot or world state through the progress of the task. Beliefs are continuous values between 0 and 1 that can be updated by any node in a non-Bayesian manner by publishing to/execution_monitor/trace
. The beliefs that are tracked are defined atBeliefKeys.msg
- The
- If the task succeeds, or is preempted, the
task_executor
returns the corresponding status (actionlib_msgs/GoalStatus
) and result - If the
task_executor
encounters an error, it generates aRequestAssistanceActionGoal
for thetask_monitor
and then awaits aRequestAssistanceActionResult
from it, which contains aresume_hint
on how to (or not to) proceed with the task - When addressing a
RequestAssistanceActionGoal
, thetask_monitor
has the option of executing recovery actions itself. It can do this through therecovery_executor
, which is simply another instantiation of thetask_executor
- In order to decide the recovery strategies to use, the
task_monitor
has access to a trace of tasks that have been completed or the faults that have manifested through theexecution_monitor
- The
execution_monitor
logsExecutionEvent
messages, which are sent out on the topic/execution_monitor/trace
- The
task_executor
publishes the status of each of its actions, as they are completed or not, to/execution_monitor/trace
- Dedicated fault monitors also publish the fault statuses of different components to
/execution_monitor/trace
- Since belief updates are also sent out the
/execution_monitor/trace
, theexecution_monitor
contains a log of how the beliefs might change over the course of the task
- The
The API documentation of the packages in this folder is likely to go out of date very quickly as new functionality is developed. Therefore, we use sphinx
to automatically generate documentation from docstrings in the source code.
If you are developing new functionality in task_executor
or task_monitor
, please copy the precedent set by existing code in writing docstrings so that the API documentation can remain parse-able
- Make sure you have the necessary
pip
dependencies ofsphinx
installed. They are specified insetup_ws.sh
- Navigate to
docs
and build the documentation:make html
- Navigate to
docs/build/html
(this folder will be generated by the previous command) and start a simple server:python -m SimpleHTTPServer
. - Navigate to
http://localhost:8000
in your browser.
Since the docs are generated with sphinx
, it's a good idea to get familiar with it, and with reStructuredText, which is format used to specify each page of the documentation (think of the latter as markdown++). Here are some resources:
- Intro to reStructuredText
- Common "commands" for reStructuredText
- Python specific "commands"
- reStructuredText cheat sheet
The most frequent update that is likely to happen to the documentation is with the addition or changes of actions in tasks, so here are the steps that one should follow for that:
- Create your action file in
task_executor.actions
- Define your action
class
, which should derive fromAbstractStep
. Make sure to follow the precedent set by the actions that are already in the code base - Add the action's name and
class
to__init__.py
- Add the action to the actions documentation page
task_executor.actions.rst
. Follow the syntax of other actions that are already in that file.