Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Production sync #286

Merged
merged 33 commits into from
Nov 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
ee8bbc1
Dingo support
roni-kreinin Nov 7, 2024
cf0100e
Split camera yaml from camera compression and added ffmpeg manual lau…
hilary-luo Nov 20, 2024
651c990
Added a camera ffmpeg tuning tutorial
hilary-luo Nov 20, 2024
d8aef56
Updated blackfly default yaml to match code
hilary-luo Nov 22, 2024
868c1cf
Added ffmpeg to blackfly yaml section
hilary-luo Nov 22, 2024
7cd25b4
Added RViz tutorial
hilary-luo Nov 22, 2024
adce802
Explain ffmpeg test setup further
hilary-luo Nov 22, 2024
fa67eb8
Rename the camera compression tutorial
hilary-luo Nov 22, 2024
09f1c71
Merge pull request #279 from clearpathrobotics/hluo/ffmpeg
tonybaltovski Nov 23, 2024
3d252d0
Domain ID changes in firmware
roni-kreinin Nov 25, 2024
1550f6c
Add the axis camera yaml page
civerachb-cpr Nov 25, 2024
dc304c2
Remove an unnecessary element from the sample YAML
civerachb-cpr Nov 25, 2024
541b0ae
Add a note about disabling PTZ for fixed cameras
civerachb-cpr Nov 25, 2024
8b8b0ab
Rename the Axis M5525-E page to be generic for all Axis PTZ cameras, …
civerachb-cpr Nov 25, 2024
32ab1c8
Move the Q62 to a new page, revert the M225-E changes
civerachb-cpr Nov 25, 2024
be42643
Enable new platform batteries
luis-camero Nov 26, 2024
c075820
Merge pull request #282 from clearpathrobotics/feature/battery
tonybaltovski Nov 26, 2024
27118e5
Added UR arm documentation
luis-camero Nov 26, 2024
3d7e473
Added changes for Humble 1.0.
tonybaltovski Nov 27, 2024
da6c9ee
Merge pull request #284 from clearpathrobotics/changelogs
tonybaltovski Nov 27, 2024
36eeade
Replace 'manipulator' with 'arm' when referencing UR arms
luis-camero Nov 27, 2024
f9f5310
Use 'arm' instead of 'robot' to avoid confusion
luis-camero Nov 27, 2024
f16a476
Added manipulator service description
luis-camero Nov 27, 2024
fae3ec6
Merge pull request #283 from clearpathrobotics/feature/ur_arm
tonybaltovski Nov 27, 2024
a33853c
Fill in the rest of the Q62 page, fix the camera page ordering. Add t…
civerachb-cpr Nov 27, 2024
71b365e
Uncomment the Q62 image
civerachb-cpr Nov 27, 2024
ce337b2
Rename the q62 image to add sensor_ prefix
civerachb-cpr Nov 27, 2024
90ee8bf
Merge pull request #281 from clearpathrobotics/cib/axis-camera
tonybaltovski Nov 27, 2024
d552234
Fix broken link, add some missing links
civerachb-cpr Nov 27, 2024
b61e5f1
Fix the name of the Axis M-series camera
civerachb-cpr Nov 27, 2024
c32783d
Merge pull request #285 from clearpathrobotics/fix-ci
tonybaltovski Nov 27, 2024
20e6d8d
Updated Humble 1.0 date.
tonybaltovski Nov 27, 2024
0de9b93
Merge pull request #280 from clearpathrobotics/humble_1.0.0
tonybaltovski Nov 27, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,216 @@
<table>
<tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots.png").default} width="250" />
</figure>
</center>
</td>
<td>

```yaml
manipulators:
arms:
- model: universal_robots
parent: default_mount
xyz: [0.0, 0.0, 0.0]
rpy: [0.0, 0.0, 0.0]
ur_type: ur5e
robot_ip: 192.168.131.40
headless: false
```
</td>
</tr>
</table>

#### Package and Setup
The Universal Robots arms use the `ur_description` and `ur_driver` ROS 2 Packages. The description and driver are open source, maintained by Universal Robots, and are hosted on GitHub. Refer to the [description repository](https://github.com/UniversalRobots/Universal_Robots_ROS2_Description) and [driver repository](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver).

For more specifics on the way Clearpath's configuration system adds the arm to the robot description, see the [description file](https://github.com/clearpathrobotics/clearpath_common/blob/humble/clearpath_manipulators_description/urdf/arm/universal_robots.urdf.xacro). Note, all parameters to the `xacro:macro universal_robots` can be passed through the `robot.yaml` entry above. For examples, read the sections below.


#### Teach Pendant Setup
The following sub-sections will cover the standard UR teach pendant setup, but with the specific Clearpath parameters. For the UR instructions see: [**Setting up a UR robot for ur_robot_driver**](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_robot_driver/ur_robot_driver/doc/installation/robot_setup.html) and [**Installing a URCap on a e-Series robot**](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_robot_driver/ur_robot_driver/doc/installation/install_urcap_e_series.html).

##### Networking Settings
At Clearpath, we use the `192.168.131.x` subnet and assign manipulators to the range `192.168.131.40-49`. Therefore, when setting up a UR arm, we encourage the use of the `192.168.131.40` address.

Navigate to the **Settings/System/Networking** page of the UR teach pendant and set the following:

<center>
<figure>
<img src={require("./img/universal_robots/settings_network.png").default} width="700" />
</figure>
</center>

##### URCap
In order to control the arm from an external device, the `External Control` URCap needs to be setup. You can find the latest `externalcontrol-x.x.x.urcap` in its [repository](https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases). Install it by adding it to the `programs` folder in the `/`, root directory of the arm's control box. Use a USB stick or `scp`.

Navigate to the **Settings/System/URCaps** page to install the URCap. Note, you will be prompted and must restart before using the URCap.
<center>
<figure>
<img src={require("./img/universal_robots/settings_urcaps.png").default} width="700" />
</figure>
</center>

Navigate to the **Installation/URCaps** page to configure the IP address and hostname of the external device. The standard Clearpath robot computer IP address is `192.168.131.40`. Each robot has its own hostname, we will use `cpr-a300-0000` as a placeholder:
<center>
<figure>
<img src={require("./img/universal_robots/installation_urcaps.png").default} width="700" />
</figure>
</center>

##### External Control Program
Once the URCap has been installed and configured, a program that launches the **ExternalControl** task needs to be created and set as default.

Begin by navigating to the **Programs/URCap** section, make sure the program is empty except for the addition of the **ExternalControl** task. Save the program as `external_control.urp`:
<center>
<figure>
<img src={require("./img/universal_robots/program_urcaps.png").default} width="700" />
</figure>
</center>

Now, set the program as default so that it is automatically loaded and ready to run on start-up. Navigate to the **Installation/General/Startup** page and set the `external_control.urp` program as the default:
<center>
<figure>
<img src={require("./img/universal_robots/installation_default_program.png").default} width="700" />
</figure>
</center>


##### Initializing the Arm
At start up, the arm needs to be turned on and initialized. Press the button in the bottom left corner which will bring-up the arm start-up sequence window. Follow the instructions to initialize the arm:
<table>
<tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots/initialize_0.png").default} width="700" />
</figure>
</center>
</td>
</tr>

<tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots/initialize_1.png").default} width="700" />
</figure>
</center>
</td>
</tr><tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots/initialize_2.png").default} width="700" />
</figure>
</center>
</td>
</tr><tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots/initialize_3.png").default} width="700" />
</figure>
</center>
</td>
</tr><tr>
<td>
<center>
<figure>
<img src={require("./img/universal_robots/initialize_4.png").default} width="700" />
</figure>
</center>
</td>
</tr>
</table>

Once the robot is in normal mode, you can proceed to initialize the external control program.


#### Standard Initialization (Recommended)
At start up, the robot computer will launch the arm's controller using the `clearpath-manipulators.service`. Once the arm is on and initialized through the teach pendant, start the `external_control` program, which will begin communication with the ROS driver.

Start the program by pressing the play button on the **Run** page.

##### Troubleshooting
If the following error pop-up window appears, then ensure that the arm's URCap configuration matches the robot's computer and that the robot's computer is able to ping the arm. The error also indicates that the ROS driver is not currently running or has been stopped. Restart the `clearpath-manipulators.service` and try again:
```yaml
sudo systemctl stop clearpath-manipulators.service
sudo systemctl start clearpath-manipulators.service
```

<center>
<figure>
<img src={require("./img/universal_robots/failed.png").default} width="700" />
</figure>
</center>


#### Headless Initialization
If the arm has been setup to accept external control by surrendering manual control in the teach pendant, then it is possible to bypass the manual initialization of the UR program on the tablet. If this is the case, make sure the arm has been turned on and initialized through the teach pendant, then set, `headless: true` in the `robot.yaml`. This will restart the services and the arm should connect automatically.

##### Setup
The headless setup is not recommended as it is more complicated, however it exposes the entire teach pendant's functionality to the ROS interface, and thus, provides experienced ROS users with the ability to detect arm faults, clear faults, and restart the arm programmatically.

To begin the setup, make sure that remote control is enabled in the **Settings/System/Remote Control** page:

<center>
<figure>
<img src={require("./img/universal_robots/settings_remote_control.png").default} width="700" />
</figure>
</center>

To enter **Remote Control** mode, first put the teach pendant in **Automatic**:
<center>
<figure>
<img src={require("./img/universal_robots/headless_0.png").default} width="700" />
</figure>
</center>

Then, you will be able to switch from **Automatic** to **Remote Control**:
<center>
<figure>
<img src={require("./img/universal_robots/headless_1.png").default} width="700" />
</figure>
</center>
<center>
<figure>
<img src={require("./img/universal_robots/headless_2.png").default} width="700" />
</figure>
</center>

In this mode, you will be unable to interface with the arm directly from the tablet. Instead, all commands must be sent by the external device. You can restore manual control by following the steps above in reverse.

#### Parameter: Device IP
The `robot_ip` must be set to match the networking settings of the arm's control box. By default, we use the `192.168.131.40` address.

#### Parameter: UR Type
The `ur_type` parameter can be modified to change the type of the arm. By default, it is set to `ur5e`. But, it is critical that it is changed to match the real arm type. The following types are supported: `ur3`, `ur3e`, `ur5`, `ur5e`, `ur10`, `ur10e`, `ur16e`, `ur20`, `ur30`.

#### Parameter: Calibration Parameters
By default, the default kinematics parameter file is passed to the arm's ROS controller. Because each arm has it's own measurable offsets, it is likely that without updating this calibration file the arm's movements will not be as accurate as could be. Therefore, use the [`ur_calibration`](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_robot_driver/ur_robot_driver/doc/installation/robot_setup.html#extract-calibration-information) package to obtain the calibration parameter file.

```bash
ros2 launch ur_calibration calibration_correction.launch.py robot_ip:=<robot_ip> target_filename:="${HOME}/my_robot_calibration.yaml"
```

Then, in the entry to the configuration file, pass in the path to the calibrated kinematics file.
```yaml
manipulators:
arms:
- model: universal_robots
parent: default_mount
xyz: [0.0, 0.0, 0.0]
rpy: [0.0, 0.0, 0.0]
ur_type: ur5e # ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e, ur20, ur30
robot_ip: 192.168.131.40
headless: false
kinematics_parameters_file: "/path/to/my_robot_calibration.yaml"
```
Note, you can also pass in substitution arguments:
```yaml
kinematics_parameters_file: "$(find package_name)/path/to/my_robot_calibration.yaml"
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
<table>
<tr>
<td>
<center>
<figure>
<img src={require("./img/axis_camera.png").default} width="250" />
</figure>
</center>
</td>
<td>

```yaml
camera:
- model: axis_camera
urdf_enabled: true
launch_enabled: true
parent: base_link
xyz: [0.0, 0.0, 0.0]
rpy: [0.0, 0.0, 0.0]
ros_parameters:
axis_camera:
device_type: dome_ptz

hostname: "192.168.0.90"
http_port: 80
username: "root"
password: ""
camera_info_url: ""
use_encrypted_password : False
camera : 1

width: 640
height: 480
fps: 20
tf_prefix: "axis"

ptz: True
min_pan: -3.141592653589793
max_pan: 3.141592653589793
min_tilt: 0.0
max_tilt: 1.5707963267948966
min_zoom: 1
max_zoom: 24
max_pan_speed: 2.61
max_tilt_speed: 2.61

ptz_teleop: True
button_enable_pan_tilt : -1
button_enable_zoom : -1
axis_pan : 3
axis_tilt : 4
invert_tilt : False
axis_zoom_in: 5
axis_zoom_out: 2
zoom_in_offset: -1.0
zoom_out_offset: -1.0
zoom_in_scale: -0.5
zoom_out_scale: 0.5
scale_pan : 2.61
scale_tilt : 2.61
scale_zoom : 100.0

ir: False
defog: False
wiper: False
```
</td>
</tr>
</table>

#### Package and Setup
The Axis cameras use the `axis_camera` ROS 2 driver. The driver is open source, maintained by the ROS Drivers community, and hosted on [GitHub](https://github.com/ros-drivers/axis_camera).

For specifics on the way Clearpath's configuration system launches the camera, see the Axis Camera [launch file](https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_sensors/launch/axis_camera.launch.py) and the [default parameter file](https://github.com/clearpathrobotics/clearpath_robot/blob/main/clearpath_sensors/config/axis_camera.yaml) in `clearpath_sensors`.

#### Device Type
The `device_type` parameter must be set accurately to successfully launch the node. Supported `device_type` values are:
- `q62`: the Axis Q62 camera
- `dome_ptz`: any Axis PTZ dome camera
- `dome_fixed`: any fixed-position dome camera

#### Network Connection
Axis cameras communicate over HTTP. The `hostname` parameter specifies either the resolvable hostname or IP address of the camera. By default Axis cameras use port 80 for their HTTP interface, but if this has been reconfigured on the camera the `http_port` parameter should be used to specify the port.

The `username` and `password` parameters should be set to allow the ROS node to authenticate to the camera. The specified user must have permission to control the camera's PTZ position. Refer to the Axis camera's web setup tool for information on creating and configuring users on the camera.

Some newer Axis cameras require the use of encrypted passwords for authentication. If this is required, set `use_encrypted_password` to `True`. Some older Axis cameras do not support encrypted passwords.

The `camera` parameter is an integer in the range 1-4, used to specify which camera at the given IP address/hostname is being controlled. This is only necessary if a multi-camera controller is being used, such as the [Axis F34](https://www.axis.com/products/axis-f34-surveillance-system/).

#### ROS Image and TF configuration
The resolution and framerate of the images published by the driver can be specified with the `height`, `width`, and `fps` parameters.

The `tf_prefix` parameter specifies the prefix added to the camera model's frames in the URDF. The camera model's root link is `${tf_prefix}_base_link`, and the optical frame is `${tf_prefix}_camera_link`. If multiple cameras are specified in `robot.yaml` the `tf_prefix` parameter must be unique to each camera.

#### PTZ Configuration
Pan and tilt limits can be specified in radians by using the `max_pan`, `min_pan`, `max_tilt` and `min_tilt` parameters. Pan and tilt speed are expressed in rad/s.

Zoom range is expressed in zoon factors. For example, a camera with a 24x optical zoom should specify `min_zoom` as `1` and `max_zoom` as `24`.

If the camera is a fixed-lens camera, set `ptz` to `False`. All PTZ and PTZ teleop parameters will be ignored if `ptz` is `False`.

#### PTZ Teleop Configuration
If `ptz_teleop` is `True` the `axis_camera` driver will subscribe to the robot's `joy` controller input, allowing the camera to be controlled via the game controller. The default parameters are configured for a Playstation 4/Dualshock family controller:
- Right thumbstick controls pan & tilt (`axis_pan` and `axis_tilt`). The pitch axis may be inverted by setting `invert_tilt` to `True`
- Left analogue trigger zooms out (`axis_zoom_in`)
- Right analogue trigger zooms in (`axis_zoom_out`)

For additional details on configuring PTZ teleoperation, please refer to the `axis_camera` package [on github](https://github.com/ros-drivers/axis_camera).

#### Q62-Specfic Features
The Axis Q62 camera features a wiper, infrared/night-vision mode, and a defogger. Services to control these features can be enabled by setting the `wiper`, `ir`, and `defog` parameters to `True`.
Loading