Skip to content

Commit a82269f

Browse files
juelgjuelg
committed
docs: improved readme content
- added readme for hardware extensions - added concrete python examples to readme
1 parent 6e75f2e commit a82269f

3 files changed

Lines changed: 151 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 91 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,34 +22,108 @@ pip install -ve .
2222

2323
## Usage
2424
The python package is called `rcs`.
25-
Import the library in python:
25+
26+
### Direct Robot Control
27+
Simple direct robot control:
2628
```python
2729
import rcs
30+
from rcs import sim
31+
from rcs._core.sim import CameraType
32+
from rcs.camera.sim import SimCameraConfig, SimCameraSet
33+
simulation = sim.Sim(rcs.scenes["fr3_empty_world"]["mjb"])
34+
urdf_path = rcs.scenes["fr3_empty_world"]["urdf"]
35+
ik = rcs.common.RL(str(urdf_path))
36+
cfg = sim.SimRobotConfig()
37+
cfg.add_id("0")
38+
cfg.tcp_offset = rcs.common.Pose(rcs.common.FrankaHandTCPOffset())
39+
robot = rcs.sim.SimRobot(simulation, ik, cfg)
40+
41+
gripper_cfg_sim = sim.SimGripperConfig()
42+
gripper_cfg_sim.add_id("0")
43+
gripper = sim.SimGripper(simulation, gripper_cfg_sim)
44+
45+
# add camera to have a rendering gui
46+
cameras = {
47+
"wrist": SimCameraConfig(
48+
identifier="wrist_0",
49+
type=CameraType.fixed,
50+
resolution_width=640,
51+
resolution_height=480,
52+
frame_rate=30,
53+
),
54+
}
55+
camera_set = SimCameraSet(simulation, cameras)
56+
simulation.open_gui()
57+
robot.set_cartesian_position(
58+
robot.get_cartesian_position() * rcs.common.Pose(translation=np.array([0.05, 0, 0]))
59+
)
60+
gripper.grasp()
61+
simulation.step_until_convergence()
62+
```
63+
### Gym Env Interface
64+
```python
65+
from rcs.envs.creators import SimEnvCreator
66+
from rcs.envs.utils import (
67+
default_mujoco_cameraset_cfg,
68+
default_sim_gripper_cfg,
69+
default_sim_robot_cfg,
70+
)
71+
from rcs.envs.base import ControlMode, RelativeTo
72+
env_rel = SimEnvCreator()(
73+
control_mode=ControlMode.JOINTS,
74+
collision_guard=False,
75+
robot_cfg=default_sim_robot_cfg(),
76+
gripper_cfg=default_sim_gripper_cfg(),
77+
cameras=default_mujoco_cameraset_cfg(),
78+
max_relative_movement=np.deg2rad(5),
79+
relative_to=RelativeTo.LAST_STEP,
80+
)
81+
env_rel.get_wrapper_attr("sim").open_gui()
82+
83+
for _ in range(10):
84+
obs, info = env_rel.reset()
85+
for _ in range(10):
86+
# sample random relative action and execute it
87+
act = env_rel.action_space.sample()
88+
print(act)
89+
obs, reward, terminated, truncated, info = env_rel.step(act)
90+
print(obs)
91+
if truncated or terminated:
92+
logger.info("Truncated or terminated!")
93+
return
2894
```
29-
Checkout the python examples that we provide in [examples](examples):
30-
- [fr3.py](python/examples/fr3.py) shows direct robot control with RCS's python bindings
31-
- [env_joint_control.py](python/examples/env_joint_control.py) and [env_cartesian_control.py](python/examples/env_cartesian_control.py) demonstrates RCS's high level [gymnasium](https://gymnasium.farama.org/) interface both for joint- and end effector space control
95+
### Examples
96+
Checkout the python examples in the [examples](examples) folder:
97+
- [fr3_direct_control.py](examples/fr3.py) shows direct robot control with RCS's python bindings
98+
- [fr3_env_joint_control.py](examples/env_joint_control.py) and [fr3_env_cartesian_control.py](examples/env_cartesian_control.py) demonstrates RCS's high level [gymnasium](https://gymnasium.farama.org/) interface both for joint- and end effector space control
3299
All of these examples work both in the MuJoCo simulation as well as on your hardware FR3.
33-
Just switch between the following settings in the example script
100+
101+
102+
### Hardware Extensions
103+
To enable hardware usage in RCS, install the needed hardware extensions via pip. RCS itself comes with a couple of supported extensions e.g. control of the FR3 via the [`rcs_fr3`](extensions/rcs_fr3) extension. All native supported extension are located in [extensions](extensions).
104+
To install extensions:
105+
```shell
106+
pip install -ve extensions/rcs_fr3
107+
```
108+
For more details real the readme file of the respective extension.
109+
110+
After the required hardware extensions are installed the examples also above work on real hardware:
111+
Switch to hardware by setting the following flag:
34112
```python
35113
ROBOT_INSTANCE = RobotPlatform.SIMULATION
36114
# ROBOT_INSTANCE = RobotPlatform.HARDWARE
37115
```
38-
and add your robot credentials to a `.env` file like this:
39-
```env
40-
DESK_USERNAME=...
41-
DESK_PASSWORD=...
42-
```
43116

44-
### Command Line Interface
117+
#### Command Line Interface
45118
Some modules include command line interfaces, e.g. rcs_fr3 defines useful commands to handle the FR3 robot without the need to use the Desk Website.
46119
You can see the available subcommands as follows:
47120
```shell
48-
python -m rcs.fr3 --help
49-
python -m rcs.realsense --help
121+
python -m rcs_fr3 --help
122+
python -m rcs_realsense --help
50123
```
51124

52125
## Development
126+
### Formatting and Linting
53127
```shell
54128
# check for c++ formatting errors
55129
make cppcheckformat
@@ -66,10 +140,13 @@ make pylint
66140
# Testing
67141
make pytest
68142
```
69-
70143
### Stub Files for Python Bindings
71144
We use autogenerated python stub files (`.pyi`) in the [`_core`](python/rcs/_core/) folder to show our linters the expected types of the C++ Python bindings.
72145
If the python bindings in the C++ code have changed you might need to regenerate them by using:
73146
```shell
74147
make stubgen
75148
```
149+
150+
### Develop Your Own Hardware Extension
151+
TODO
152+

‎extensions/README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
# Hardware Extensions
1+
# Hardware Extensions
2+
3+
To install hardware exentsion use
4+
```shell
5+
pip install -ve <extension> # e.g. rcs_fr3
6+
```
7+
Some extensions need further dependencies or further setups. Please to check out their readme pages for details.

‎extensions/rcs_fr3/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# RCS FR3 Hardware Extension
2+
Extension to control the fr3 with rcs.
3+
4+
## Installation
5+
```shell
6+
pip install -ve .
7+
```
8+
9+
Add your FR3 credentials to a `.env` file like this:
10+
```env
11+
DESK_USERNAME=...
12+
DESK_PASSWORD=...
13+
```
14+
15+
## Usage
16+
```python
17+
import rcs_fr3
18+
from rcs_fr3._core import hw
19+
from rcs_fr3.desk import FCI, ContextManager, Desk, load_creds_fr3_desk
20+
user, pw = load_creds_fr3_desk()
21+
with FCI(Desk(ROBOT_IP, user, pw), unlock=False, lock_when_done=False):
22+
urdf_path = rcs.scenes["fr3_empty_world"]["urdf"]
23+
ik = rcs.common.RL(str(urdf_path))
24+
robot = hw.FR3(ROBOT_IP, ik)
25+
robot_cfg = FR3Config()
26+
robot_cfg.tcp_offset = rcs.common.Pose(rcs.common.FrankaHandTCPOffset())
27+
robot_cfg.ik_solver = IKSolver.rcs_ik
28+
robot.set_parameters(robot_cfg)
29+
30+
gripper_cfg_hw = hw.FHConfig()
31+
gripper_cfg_hw.epsilon_inner = gripper_cfg_hw.epsilon_outer = 0.1
32+
gripper_cfg_hw.speed = 0.1
33+
gripper_cfg_hw.force = 30
34+
gripper = hw.FrankaHand(ROBOT_IP, gripper_cfg_hw)
35+
robot.set_cartesian_position(
36+
robot.get_cartesian_position() * rcs.common.Pose(translation=np.array([0.05, 0, 0]))
37+
)
38+
gripper.grasp()
39+
```
40+
For more examples see the [examples](../../examples/) folder.
41+
You can switch to hardware by setting the following flag:
42+
```python
43+
ROBOT_INSTANCE = RobotPlatform.HARDWARE
44+
# ROBOT_INSTANCE = RobotPlatform.SIMULATION
45+
```
46+
47+
48+
## CLI
49+
Defines useful commands to handle the FR3 robot without the need to use the Desk Website.
50+
You can see the available subcommands as follows:
51+
```shell
52+
python -m rcs_fr3 --help
53+
```

0 commit comments

Comments
 (0)