Merge pull request #280 from clearpathrobotics/humble_1.0.0

Humble 1.0

docs_versioned_docs/version-ros2humble/components/yaml/manipulators/universal_robots.mdx

@@ -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"
+```

docs_versioned_docs/version-ros2humble/components/yaml/sensors/axis_camera.mdx

@@ -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`.

docs_versioned_docs/version-ros2humble/robots/accessories/sensors/cameras/axis_m5525_e.mdx

@@ -4,6 +4,7 @@ sidebar_position: 2
 ---
 
 import Support from "/components/support.mdx";
+import YAML from "/docs_versioned_docs/version-ros2humble/components/yaml/sensors/axis_camera.mdx";
 
 <center>
   <img