|
1 | | -# CRTK Python client library |
| 1 | +# CRTK Python client library for ROS2 |
2 | 2 |
|
3 | | -This Python package provides some tools to facilitate the development of a CRTK compatible client over ROS, i.e. create a "proxy" class to communicate with an existing CRTK compatible ROS device. |
4 | | - |
5 | | -CRTK specifications can be found on the [CRTK github page](https://github.com/collaborative-robotics/documentation/wiki/Robot-API). |
6 | | - |
7 | | -Examples of CRTK devices with a CRTK/ROS interface: |
8 | | -* [Raven II](https://github.com/uw-biorobotics/raven2/tree/crtk) |
9 | | -* [dVRK](https://github.com/jhu-dvrk/sawIntuitiveResearchKit/wiki) |
10 | | - |
11 | | -# Build |
12 | | - |
13 | | -To build this package, we recommend to use the catkin build tools, i.e. `catkin build`. |
14 | | -You will need to clone this repository as well as the repository with CRTK specific ROS messages: |
15 | | -```bash |
16 | | -cd ~/catkin_ws/src # or wherever your catkin workspace is |
17 | | -git clone https://github.com/collaborative-robotics/crtk_msgs |
18 | | -git clone https://github.com/collaborative-robotics/crtk_python_client |
19 | | -catkin build |
20 | | -``` |
21 | | - |
22 | | -Once these packages are built, you should source your `setup.bash`: `source ~/catkin_ws/devel/setup.bash`. |
23 | | -At that point, you should be able to import the crtk python package in Python using `import crtk`. |
24 | | - |
25 | | -# Usage |
26 | | - |
27 | | -The main class in the CRTK Python client library is `crtk.utils`. It can be used to quickly populate an existing class by adding CRTK like methods. |
28 | | -These methods will handle the following for you: |
29 | | -* declare all required ROS publishers and wrap publisher calls in methods to send data to the device. |
30 | | -* declare all required ROS subscribers and provide callbacks to receive the data from the device. |
31 | | -* convert ROS messages to more convenient Python data types, i.e. numpy arrays for joint values and PyKDL types for cartesian data. |
32 | | -* some events to manage asynchronous communication between the device and the "proxy" class. |
33 | | - |
34 | | -The class `crtk.utils` is designed to add CRTK features "a la carte", i.e. it doesn't assume that all CRTK features are available. This allows to: |
35 | | -* match only the features that are available on the CRTK devices one wants to use (server side) |
36 | | -* reduce the number of features to those strictly needed for the application (client side). Reducing the number of ROS topics used helps in terms of performance. |
37 | | - |
38 | | -## Base class and `crtk.utils` |
39 | | - |
40 | | -You can find some examples in the `scripts` directory. Overall, the approach is always the same, i.e. create a class and populate it with `crtk.utils`. You can then use an instance of this class. For example: |
41 | | - |
42 | | -```python |
43 | | -class crtk_move_cp_example: |
44 | | - # constructor |
45 | | - def __init__(self, device_namespace): |
46 | | - # ROS initialization |
47 | | - if not rospy.get_node_uri(): |
48 | | - rospy.init_node('crtk_move_cp_example', anonymous = True, log_level = rospy.WARN) |
49 | | - # populate this class with all the ROS topics we need |
50 | | - self.crtk_utils = crtk.utils(self, device_namespace) |
51 | | - self.crtk_utils.add_measured_cp() |
52 | | - self.crtk_utils.add_move_cp() |
53 | | -``` |
54 | | - |
55 | | -What is happening behind the scene: |
56 | | -* `device_namespace` is the ROS namespace used by the device. E.g. if the namespace is `left`, we assume the device will have its CRTK ROS topics under `/left`. |
57 | | -* `get_node_uri()` and `init_node()` are not strictly needed but helps if the user did not properly initialize the ROS node |
58 | | -* Add an instance of `crtk.utils` in your class. The first parameter indicates which Python object should be "populated", i.e. which object will have the CRTK methods added to its dictionary. |
59 | | -* `add_measured_cp()`: |
60 | | - * Creates a subscriber for the topic, e.g. : `/left/measured_cp` |
61 | | - * Registers a built-in callback for the topic. The callback will store the latest `measured_cp` ROS message in `crtk_utils` |
62 | | - * Provides a method to read the latest `measured_cp` message as a PyKDL frame. |
63 | | - * Adds the method `measured_cp()` to the user class (`crtk_move_cp_example`) |
64 | | -* `add_move_cp()`: |
65 | | - * Creates a publisher for the topic, e.g. : `/left/move_cp` |
66 | | - * Provides a method to send a PyKDL frame (goal), internally converts to a ROS message. |
67 | | - * Adds the method `move_cp()` to the user class (`crtk_move_cp_example`) |
68 | | - |
69 | | -Once the class is defined, the user can use it: |
70 | | -```python |
71 | | -example = crtk_move_cp_example('left') |
72 | | -position = example.measured_cp() |
73 | | -position.p[2] += 0.05 # move by 5 cm |
74 | | -example.move_cp(position) |
75 | | -``` |
76 | | - |
77 | | -## Motion Commands |
78 | | - |
79 | | -`crtk.utils` supports the following CRTK features: |
80 | | -* subscribers: |
81 | | - * `add_setpoint_js`, `add_setpoint_cp` |
82 | | - * `add_measured_js`, `add_measured_cp`, `add_measured_cv`, `add_measured_cf` |
83 | | - * ... |
84 | | -* publishers |
85 | | - * `add_servo_jp`, `add_servo_jf`, `add_servo_cp`, `add_servo_cf` |
86 | | - * `add_move_jp`, `add_move_cp` |
87 | | - * ... |
88 | | - |
89 | | -All methods relying on subscribers to get data have the following two _optional_ parameters: `age` and `wait`: |
90 | | -```python |
91 | | - setpoint_cp(age = None, wait = None) |
92 | | -``` |
93 | | -The parameter `age` specifies how old the data can be to be considered valid and `wait` specifies how long to wait for the next message if the data currently cached is too old. By default, both are based on the expected interval provided when creating an instance of `crtk.utils`. The expected interval should match the publishing rate from the CRTK device. Setting the `age` to zero means that any cached data should be used and the method shouldn't wait for new messages. |
94 | | - |
95 | | -All move commands (`move_jp` and `move_cp`) return a ROS time object. This is the time just before sending (i.e., publishing) the move command to the device. This timestamp can be used to wait for motion completion using: |
96 | | -```python |
97 | | -# wait until robot is not busy, i.e. move has ended |
98 | | -h = example.move_cp(goal) # record time move was sent |
99 | | -h.wait() |
100 | | -# compact syntax |
101 | | -example.move_cp(goal).wait() |
102 | | -# other example, wait until move has started |
103 | | -example.move_cp(goal).wait(is_busy = True) |
104 | | -``` |
105 | | - |
106 | | -The method `wait_for_busy` used by `handle.wait()` depends on the CRTK device operating state and can be added to the example class using `crtk.utils.add_operating_state`. See section below. |
107 | | - |
108 | | -## Operating States |
109 | | - |
110 | | -`crtk.utils.add_operating_state` adds: |
111 | | -* State status `operating_state()` and helper queries: `is_enabled()`,`is_homed()`, `is_busy()` |
112 | | -* State command `operating_state_command()` and helper commands: `enable()`, `disable()`, `home()`, `unhome()` |
113 | | -* Timer/event utilities: |
114 | | - * For subscribers: `wait_for_valid_data` |
115 | | - * For publishers (used by move commands): , `wait_for_busy()` |
116 | | - * For state changes (used by `enable()`, `home()`...): `wait_for_operating_state()` |
117 | | - |
118 | | -# Examples |
119 | | - |
120 | | -## dVRK |
121 | | - |
122 | | -For the dVRK, one can use the classes `dvrk.arm`, `dvrk.psm`, `dvrk.mtm`... that use the `crtk.utils` to provide as many features as possible. This is convenient for general purpose testing, for example in combination with iPython to test snippets of code. In general, it is recommended to use your own class and only add the features you need to reduce the number of ROS messages and callbacks. |
123 | | - |
124 | | -The dVRK arm class implementation can be found in the [dvrk_python](https://github.com/jhu-dvrk/dvrk-ros/blob/devel/dvrk_python/src/dvrk/arm.py) package. |
125 | | - |
126 | | -Example of use: |
127 | | -```python |
128 | | -import dvrk |
129 | | -p = dvrk.arm('PSM1') |
130 | | -p.enable() |
131 | | -p.home() |
132 | | - |
133 | | -# get measured joint state |
134 | | -[position, velocity, effort, time] = p.measured_js() |
135 | | -# get only position |
136 | | -position = p.measured_jp() |
137 | | -# get position and time |
138 | | -[position, time] = p.measured_jp(extra = True) |
139 | | - |
140 | | -# move in joint space |
141 | | -import numpy |
142 | | -p.move_jp(numpy.array([0.0, 0.0, 0.10, 0.0, 0.0, 0.0])) |
143 | | - |
144 | | -# move in cartesian space |
145 | | -import PyKDL |
146 | | -# start position |
147 | | -goal = p.setpoint_cp() |
148 | | -# move 5cm in z direction |
149 | | -goal.p[2] += 0.05 |
150 | | -p.move_cp(goal).wait() |
151 | | - |
152 | | -import math |
153 | | -# start position |
154 | | -goal = p.setpoint_cp() |
155 | | -# rotate tool tip frame by 25 degrees |
156 | | -goal.M.DoRotX(math.pi * 0.25) |
157 | | -p.move_cp(goal).wait() |
158 | | -``` |
| 3 | +See crtk-robotics.readthedocs.io |
0 commit comments