Skip to content

Commit 417c737

Browse files
author
Sascha Jongebloed
committed
added interface description to repository
1 parent 31a36ba commit 417c737

File tree

2 files changed

+191
-2
lines changed

2 files changed

+191
-2
lines changed

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ The `knowrob_designator` package provides a ROS action interface for logging str
1212

1313
A designator is a nested symbolic description (e.g., of actions, goals, objects) expressed as a JSON structure. This structure is parsed into RDF-style triples and submitted to KnowRob using its `tell` interface.
1414

15+
For a detailed description of the interfaces, see the [Action Interface Description](scripts/README.md)
16+
1517
---
1618

1719
## Package Structure
@@ -28,8 +30,8 @@ knowrob_designator/
2830
├── README.md # You are here
2931
├── run_knowrob_designator.sh # Optional helper script (not required)
3032
├── src/
31-
│ ├── knowrob_designator/ # Source code for the action server
32-
│ │ ├── knowrob_designator.py # Main action server implementation
33+
│ ├── knowrob_designator/ # Library for the action server
34+
│ │ ├── designator_parser.py # Parses JSON designators into triples
3335
│ │ └── __init__.py # Python package initialization
3436
├── scripts/
3537
│ ├── designator_parser.py # Parses JSON designators into triples (no ROS dependency)

‎scripts/README.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
## KnowRob Designator Action Interfaces
2+
3+
These interfaces enable robots to semantically log and track the lifecycle of CRAM *designators* during task execution. Each stage of a designator's usage is logged via a separate ROS action.
4+
5+
---
6+
7+
### 1. `/knowrob/designator/init`
8+
9+
**Action Type:** `DesignatorInitAction`
10+
**Purpose:** Registers a new (typically symbolic) designator with KnowRob.
11+
12+
#### When to Use
13+
14+
Call this when a designator is first created. It represents an abstract intention, such as “bring the milk to the table,” and may contain nested symbolic sub-designators.
15+
16+
#### Goal Fields
17+
18+
* `designator_id`: Unique identifier for this designator.
19+
* `parent_id`: Optional ID of a parent designator (use `""` for root).
20+
* `json_designator`: The symbolic JSON designator.
21+
* `stamp`: Time the designator was created.
22+
23+
#### Example
24+
25+
```python
26+
goal = DesignatorInitGoal()
27+
goal.designator_id = "desig_123"
28+
goal.parent_id = ""
29+
goal.json_designator = '{"anAction": {"type": "Transporting", "objectActedOn": {"anObject": {"type": "Milk"}}, "target": {"theLocation": {"goal": {"theObject": {"name": "Table1"}}}}}}'
30+
goal.stamp = rospy.Time.now()
31+
```
32+
33+
---
34+
35+
### 2. `/knowrob/designator/resolving_started`
36+
37+
**Action Type:** `DesignatorResolutionStartAction`
38+
**Purpose:** Signals that resolution (e.g., grounding of symbolic references) has started.
39+
40+
#### When to Use
41+
42+
Call this before resolving the symbolic designator into a grounded one (e.g., a pose in space).
43+
44+
#### Goal Fields
45+
46+
* `designator_id`: ID of the designator being resolved.
47+
* `json_designator`: The original symbolic JSON.
48+
* `stamp`: Time resolution started.
49+
50+
#### Example
51+
52+
```python
53+
goal = DesignatorResolutionStartGoal()
54+
goal.designator_id = "desig_123"
55+
goal.json_designator = same_json_as_init
56+
goal.stamp = rospy.Time.now()
57+
```
58+
59+
---
60+
61+
### 3. `/knowrob/designator/resolving_finished`
62+
63+
**Action Type:** `DesignatorResolutionFinishedAction`
64+
**Purpose:** Logs the grounded (resolved) version of a symbolic designator.
65+
66+
#### When to Use
67+
68+
After successful resolution of a symbolic designator, use this to log its grounded form.
69+
70+
#### Goal Fields
71+
72+
* `designator_id`: ID of the new, resolved designator.
73+
* `resolved_from_id`: ID of the original symbolic designator.
74+
* `json_designator`: The resolved JSON designator (e.g., with pose data).
75+
* `stamp`: Time resolution completed.
76+
77+
#### Example
78+
79+
```python
80+
goal = DesignatorResolutionFinishedGoal()
81+
goal.designator_id = "desig_456"
82+
goal.resolved_from_id = "desig_123"
83+
goal.json_designator = '{"anAction": {"type": "Transporting", "objectActedOn": {"anObject": {"type": "Milk"}}, "target": {"pose": {"x": 1.2, "y": 0.8, "z": 0.75, "frame": "map"}}}}'
84+
goal.stamp = rospy.Time.now()
85+
```
86+
87+
---
88+
89+
### 4. `/knowrob/designator/execution_start`
90+
91+
**Action Type:** `DesignatorExecutionStartAction`
92+
**Purpose:** Signals that the execution of a resolved designator has started.
93+
94+
#### When to Use
95+
96+
Once the robot begins acting on the resolved designator (e.g., starts moving to pick up an object), log the execution start.
97+
98+
#### Goal Fields
99+
100+
* `designator_id`: ID of the resolved designator being executed.
101+
* `json_designator`: The grounded designator (e.g., with numeric poses).
102+
* `stamp`: Time execution began.
103+
104+
#### Example
105+
106+
```python
107+
goal = DesignatorExecutionStartGoal()
108+
goal.designator_id = "desig_456"
109+
goal.json_designator = "" # Allowed to be empty, if not different from the last logged version
110+
goal.stamp = rospy.Time.now()
111+
```
112+
113+
---
114+
115+
### 5. `/knowrob/designator/execution_finished`
116+
117+
**Action Type:** `DesignatorExecutionFinishedAction`
118+
**Purpose:** Logs that the execution of the designator has been completed.
119+
120+
#### When to Use
121+
122+
After the task related to the designator is complete (e.g., object placed on table), log this event.
123+
124+
#### Goal Fields
125+
126+
* `designator_id`: ID of the resolved designator that was executed.
127+
* `json_designator`: Same designator content as before (for traceability).
128+
* `stamp`: Time execution finished.
129+
130+
#### Example
131+
132+
```python
133+
goal = DesignatorExecutionFinishedGoal()
134+
goal.designator_id = "desig_456"
135+
goal.json_designator = ""
136+
goal.stamp = rospy.Time.now()
137+
```
138+
---
139+
140+
### 6. `/knowrob/designator/push_object_designator`
141+
142+
**Action Type:** `PushObjectDesignatorAction`
143+
**Purpose:** Adds or updates an object designator in the KnowRob knowledge base.
144+
145+
#### When to Use
146+
147+
Use this action to assert the presence or update the semantic state of a physical object in the environment. This can be done after object detection, tracking, or perception to inform KnowRob about the current scene.
148+
149+
#### Goal Fields
150+
151+
* `json_designator`: JSON description of the object (type, pose, name, etc.).
152+
* `stamp`: Timestamp when the object was perceived.
153+
154+
#### Result Fields
155+
156+
* `success`: Whether the object was successfully added.
157+
* `message`: Informational message for logging or debugging.
158+
159+
#### Feedback Fields
160+
161+
* `status`: Optional feedback status.
162+
163+
#### Example
164+
165+
```python
166+
push_client = actionlib.SimpleActionClient('/knowrob/designator/push_object_designator', PushObjectDesignatorAction)
167+
168+
push_goal = PushObjectDesignatorGoal()
169+
push_goal.json_designator = """
170+
{
171+
"anObject": {
172+
"type": "Milk",
173+
"pose": {
174+
"x": 1.0,
175+
"y": 0.5,
176+
"z": 0.75,
177+
"frame": "map"
178+
}
179+
}
180+
}
181+
"""
182+
push_goal.stamp = rospy.Time.now()
183+
184+
send_action(push_client, push_goal, "PushObjectDesignator")
185+
```
186+
187+
> Note: This action can be called repeatedly to update object poses or semantic types during runtime. It is typically decoupled from task-level designator flows.

0 commit comments

Comments
 (0)