1# An intent is an abstract description of an operation to be performed by the
2# robot.
3#
4# While inspired by the Android intents
5# (https://developer.android.com/reference/android/content/Intent), ROS intents
6# are primarily designed to capture user-initiated intents. For instance, a
7# button click on a touchscreen, the result of a chatbot-based verbal
8# interaction, a command started by a remote user interface.
9#
10# Intents comprise of two mandatory fields: the `intent`, which should be one
11# of the available predefined intents, and the `data` which must be a JSON
12# object containing the data required to fully instantiate the intent. While
13# the exact content of the JSON object is up to the application, the following
14# standard keys can be used to specify the intent's semantic roles (also called
15# thematic roles or theta roles):
16#
17# - `agent`: the agent expected to perform the intent (if omitted, the robot
18# itself is assumed)
19# - `object` (also named *theme* or *patient* in the linguistics literature): entity
20# undergoing the effect of the intent
21# - `goal`: entity towards which the intent is directed or moves
22# - `recipient`: entity that receives the object (denoted as the `theme`)
23#
24# Examples:
25#
26# - "I want you to go to the kitchen":
27# - intent: `move_to`
28# - data: {"goal":"kitchen_1"}
29#
30# - "Can you take the groceries to Luke in the kitchen?"
31# - intent: `bring`
32# - data: {"object": "groceries",
33# "goal":"kitchen_1",
34# "recipient": "person_luke"}
35
36##########################################################################
37# Intent name
38#
39# A string describing the intent.
40#
41# Where suitable, the intent SHOULD be one of the constant defined below.
42# However, we recognise that the list of intents is possibly large. Therefore,
43# custom strings are also permissible. If you believe your intent name should
44# be standardised and added to the list of pre-defined intents, fill the
45# corresponding entry in the "thematic roles" table below and submit a pull
46# request on this repository.
47string intent
48
49# 'intent' constants
50# see table below for a short description of each.
51
52# this special intent represents a raw user input, without any specific intent recognised.
53# It is used as a fallback to mean that no user intent was (yet) extracted from the user input
54# It might happen when, for instance, a chatbot is unable to recognise an intent.
55# An application receiving this intent can choose to ignore it, or further process it by other
56# means.
57string RAW_USER_INPUT = __raw_user_input__
58
59string ENGAGE_WITH = __intent_engage_with__
60string MOVE_TO = __intent_move_to__
61string GUIDE = __intent_guide__
62string GRAB_OBJECT = __intent_grab_object__
63string BRING_OBJECT = __intent_bring_object__
64string PLACE_OBJECT = __intent_place_object__
65string GREET = __intent_greet__
66string SAY = __intent_say__
67string PRESENT_CONTENT = __intent_present_content__
68string PERFORM_MOTION = __intent_perform_motion__
69string START_ACTIVITY = __intent_start_activity__
70string STOP_ACTIVITY = __intent_stop_activity__
71string WAKEUP = __intent_wakeup__
72string SUSPEND = __intent_suspend__
73
74
75##########################################################################
76# Intent data
77#
78# a JSON object containing the data required to fully instantiate the intent.
79# The keys of the object should be one of the thematic role defined above, or
80# the general `other_data`.
81#
82# Each intent defines a specific set of required and optional thematic roles,
83# listed in the following table (note that the `agent` role can be optionally
84# added to all intents, and is omitted from the table for clarity):
85#
86# .. [please keep the RST table syntax below, as it is used to automatically parse the list of intents by some nodes]#
87# .. BEGIN_INTENTS_TABLE
88# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
89# | **Intent** | **Description** | **Required thematic roles** | **Optional thematic roles** |
90# +==================+=============================================================================+=============================================================+===========================================================================+
91# | `RAW_USER_INPUT` | the intent was not successfully extracted | - `input`: the raw input received from the user | - `locale`: the language code of the input, if available |
92# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
93# | `ENGAGE_WITH` | an agent wants to engage with another one | - `recipient` | |
94# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
95# | `MOVE_TO` | navigates to a specific location | - `goal` | |
96# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
97# | `GUIDE` | guides someone somewhere | - `goal` | |
98# | | | - `recipient` | |
99# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
100# | `GRAB_OBJECT` | pick-up a specific object | - `object` | |
101# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
102# | `BRING_OBJECT` | bring a specific object to a specific place | - `object` | |
103# | | | - `recipient` | |
104# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
105# | `PLACE_OBJECT` | put an object on a support (eg a table) | - `recipient` | - `object` (only required if more that one object could be placed) |
106# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
107# | `GREET` | greet an agent | - `recipient` | |
108# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
109# | `SAY` | says some text, optionally annotated with gestures or expressions | - `object` (the text to say) | - `recipient` |
110# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
111# | `PRESENT_CONTENT`| present (via a screen, pre-recorded text...) predefined content | - `object` (the content identifier; special values | - `recipient` |
112# | | | '__back__' and '__next__' mean 'go backwards/forwards') | |
113# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
114# | `PERFORM_MOTION` | performs a motion (eg, a dance or a specific gesture like pointing, waving) | - `object` (the system-specific name of the motion/gesture) | - `recipient` |
115# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
116# | `START_ACTIVITY` | start a scripted behaviour/activity | - `object` (the name of the activity) | - any additional parameter required to start the activity |
117# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
118# | `STOP_ACTIVITY` | request cancelation of an activity | | - `object` (the name of the activity. If unset, current main activity) |
119# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
120# | `WAKEUP` | request reactivation of the system | | |
121# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
122# | `SUSPEND` | request suspension of the system | | |
123# +------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------+---------------------------------------------------------------------------+
124# .. END_INTENTS_TABLE
125#
126string data
127
128##########################################################################
129# Intent source
130#
131# a string describing the source of the intent. This is *not* the node
132# which published the intent, but instead the actual agent who expressed the
133# intent/command/desire.
134# `source` can be either one of the constant below, or the specific id of the
135# person/agent expressing the intent. In a REP-155 compliant system, this ID
136# must be the person ID of the agent.
137string source
138
139# 'source' constants:
140
141# for intents originating from the robot itself
142string ROBOT_ITSELF = __myself__
143# for intents originating from a external robot control system (for instance, a remote control tablet)
144string REMOTE_SUPERVISOR = __remote_supervisor__
145# for intents coming from an agent interacting with the robot, but not uniquely
146# identified
147string UNKNOWN_AGENT = __unknown_agent__
148# for unknown sources
149string UNKNOWN = __unknown__
150
151
152##########################################################################
153# Intent modality
154#
155# modality used to originally convey the intent: verbal, via the touchscreen,
156# via a gesture...
157# The special modality MODALITY_INTERNAL must be used for intents coming for the
158# robot's internal processes (eg 'battery low, I need to charge')
159# MUST be one of the MODALITY_ constant below.
160string modality
161
162# 'modality' constants:
163
164string MODALITY_SPEECH = __modality_speech__
165# both gestures (eg waving) and displacement (eg approaching)
166string MODALITY_MOTION = __modality_motion__
167string MODALITY_TOUCHSCREEN = __modality_touchscreen__
168string MODALITY_OTHER = __modality_other__
169string MODALITY_INTERNAL = __modality_internal__
170
171
172##########################################################################
173# Intent priority
174#
175# the priority of this intent. This MIGHT be used as a hint by the robot's task
176# scheduler, however is scheduler is *not* forced to respect this priority
177# level. 0 is the lowest priority, 128 is the default priority, 255 is the
178# highest priority.
179uint8 priority
180
181##########################################################################
182# Intent confidence
183#
184# a value between 0.0 (no confidence) and 1.0 (full confidence) that the intent
185# was correctly perceived and interpreted.
186#
187# For instance, a 'waving' gesture could be interpreted as an implicit request
188# from a user for the robot to greet back or engage. As this interpretation is
189# not certain, the confidence of the intent may be below 1.0.
190float32 confidence