.. _guided-insertion: ========================== Guided Insertion Operation ========================== .. admonition:: What you will learn :class: tip How to use several of pitasc's most common skills, including **linear movements**, a **guarded approach** and different ways of using the **slide** skill. The application focus is the **insertion of a T-piece into a fixture with guides**. .. rst-class:: tutorial-meta :bdg-primary:`Level: intermediate` :bdg-secondary:`insertion` :bdg-secondary:`force control` :bdg-info:`chamfer vs. no chamfer` .. contents:: On this page :local: :depth: 2 Requirements ============ Hardware -------- .. list-table:: :header-rows: 1 :widths: 30 70 * - Item - Details * - 3D printer - For the parts listed in :ref:`p1-models` * - Fasteners - Screws ISO 4762 – M3x35 and nuts ISO 4032 – M3 (or comparable), **7 pcs each** * - Robot - Any pitasc-compatible robot with a force/torque sensor. This example uses a **UR5e**. * - Table *(recommended)* - Welding table with 50 × 50 hole pattern, hole diameter 16 mm * - Positioning bolts - 16 mm, **4 – 6 pcs** Supported grippers ------------------ .. grid:: 1 2 2 4 :gutter: 2 .. grid-item-card:: Weiss WSG 50-110 :class-card: sd-shadow-sm Used in this example. Requires **either**: - ``F-WSG-FMF`` sensor fingers, **or** - 2 × custom fingers (model 05 below) .. grid-item-card:: Robotiq 2F-140 :class-card: sd-shadow-sm Supported out of the box. .. grid-item-card:: Robotiq 2F-85 :class-card: sd-shadow-sm Supported out of the box. .. grid-item-card:: Franka Hand :class-card: sd-shadow-sm Supported out of the box. .. important:: The T-piece exists in a **gripper-specific variant**. Download the version that matches your hardware from :ref:`p1-tpiece`. .. _p1-models: Provided 3D models ================== All models are hosted on GrabCAD and available as ``.step``, ``.stl`` and ``.sldprt``. Station and carrier ------------------- .. list-table:: :widths: 8 32 32 28 :header-rows: 1 :class: model-table * - # - Preview - Part - Downloads * - 01 - .. image:: /_images/real_world_tutorial/parkour_0/01_bottom.png :alt: Lower section of the station :width: 100% - **Lower section** .. note:: Print with the **chamfer facing up**. - | `.step `__ | `.stl `__ | `.sldprt `__ * - 02 - .. image:: /_images/real_world_tutorial/parkour_1/02_upper_with_guide.png :alt: Upper section carrying both guides :width: 100% - **Upper section with guides** Contains guide 1 (chamfered) and guide 2 (not chamfered). .. note:: Print with the **largest surface facing down**. - | `.step `__ | `.stl `__ | `.sldprt `__ * - 04 - .. image:: /_images/real_world_tutorial/parkour_1/04_workpiece_carrier.png :alt: Workpiece carrier :width: 100% - **Workpiece carrier** Defines the pick and place pose of the T-piece. .. note:: Print with the **chamfers facing up**. - | `.step `__ | `.stl `__ | `.sldprt `__ * - 05 - .. image:: /_images/real_world_tutorial/parkour_0/05_gripper_finger.png :alt: Custom prismatic gripper fingers :width: 100% - **Custom gripper fingers** For the Weiss WSG 50-110 only. .. note:: Print with the **largest surface facing down**. - | `.step `__ | `.stl `__ | `.sldprt `__ .. _p1-tpiece: T-piece - choose the variant for your gripper --------------------------------------------- .. figure:: /_images/real_world_tutorial/parkour_1/03_t_piece.png :alt: T-piece workpiece :width: 60% :align: center The T-piece (model 03). Print with the **text facing up**. .. list-table:: :widths: 40 60 :header-rows: 1 * - Gripper - Downloads * - **Weiss WSG 50-110** - custom gripper fingers - `.step `__ · `.stl `__ · `.sldprt `__ * - **Weiss WSG 50-110** - F-WSG-FMF sensor fingers - `.step `__ · `.stl `__ · `.sldprt `__ * - **Robotiq 2F-140** - `.step `__ · `.stl `__ · `.sldprt `__ * - **Robotiq 2F-85** - `.step `__ · `.stl `__ · `.sldprt `__ * - **Franka Hand** - `.step `__ · `.stl `__ · `.sldprt `__ .. note:: The first row reuses the *gripper finger* download links from the source document. If a dedicated T-piece variant for the custom fingers exists, replace those three links. Setup ===== Step 1 - Print the parts ------------------------ Print the lower and upper section, the workpiece carrier and the T-piece variant for your gripper (plus the custom gripper fingers if needed). .. warning:: Tolerances were tested on a **Bambu Lab X1** - adjust if needed. The fit between T-piece and guide should be between a **clearance and a transition fit**: it must be possible to insert the T-piece manually with little force. Step 2 - Assemble the station ----------------------------- Assemble the lower and upper section using the screws and nuts. .. figure:: /_images/real_world_tutorial/parkour_1/00_slide_assembly_font.png :alt: Assembled station with inserted T-piece :width: 90% :align: center Assembly of the 3D-printed parts with inserted T-piece. **Guide 1** has chamfers to simplify insertion, **guide 2** does not. Step 3 - Clamp everything to the table -------------------------------------- Clamp the assembled station and the workpiece carrier to your table. .. figure:: /_images/real_world_tutorial/parkour_1/p1_example_configuration.png :alt: Example table configuration :width: 90% :align: center Example configuration, allowing easy access to the T-piece and a minimal distance between the T-piece and both guides. Step 4 - Position the T-piece ----------------------------- Place the T-piece in the workpiece carrier as shown below. .. figure:: /_images/real_world_tutorial/parkour_1/t-piece_in_workpiece_carrier.png :alt: T-piece seated in the workpiece carrier :width: 90% :align: center T-piece in the workpiece carrier. Step 5 - Mount the gripper fingers ---------------------------------- If needed, screw the custom 3D-printed gripper fingers onto the Weiss WSG 50-110 gripper. How to solve this parkour task ============================== The task is to **insert and retrieve the T-piece into and out of both guides**, as shown in the videos below. .. tab-set:: .. tab-item:: Guide 1 - chamfered .. video:: /_videos/real_world_tutorial/parkour_1/pitasc_realworld_tutorial_p1.mp4 :width: 100% Insertion into and retrieval from guide 1 .. tab-item:: Guide 2 - not chamfered .. video:: /_videos/real_world_tutorial/parkour_1/pitasc_realworld_tutorial_p1_guide2.mp4 :width: 100% Insertion into and retrieval from guide 2 .. admonition:: Why the chamfer matters :class: note Guides 1 and 2 differ only in the presence or absence of a chamfer at their opening. Chamfers simplify automated assembly by allowing the workpiece to **self-centre**, which reduces the precision required during assembly. Try it yourself --------------- .. card:: Where to put your solution Add your solution to: .. code-block:: text .../pitasc_realworld_tutorial_p1/apps/parkour_1.xml Then start RViz and the frame editor with: .. code-block:: bash roslaunch pitasc_realworld_tutorial_p1 bringup_ur5_parkour_1.launch .. admonition:: Increasing levels of assistance :class: important The following sections progressively reveal more detail. Stop reading at whichever level still leaves you with an interesting challenge. #. :ref:`p1-rough-steps` - the six high-level actions #. :ref:`p1-example-steps` - every individual motion, no code #. :ref:`p1-tips` - which pitasc skills to reach for #. :ref:`p1-solution` - the full annotated XML .. _p1-rough-steps: Level 1 – Rough steps --------------------- The sample solution comprises the following rough steps. Each step is implemented as a skill sequence containing several skills: #. Pick up the workpiece from the workpiece carrier. #. Insert the workpiece into **guide 1**. #. Retrieve the workpiece from **guide 1**. #. Insert the workpiece into **guide 2**. #. Retrieve the workpiece from **guide 2**. #. Place the workpiece back on the workpiece carrier. .. _p1-example-steps: Level 2 – Example steps in detail --------------------------------- .. note:: For safety reasons, each step begins and ends with the robot moving to its home pose by linear movement. Step 1 - Pick up ~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the workpiece carrier *(position controlled)* #. Lower the end effector to the gripping position *(position controlled)* #. Grip the T-piece *(command to your specific gripper)* #. Push down on the T-piece to ensure a safe grip *(force controlled - only needed for flat gripper fingers)* #. Move upwards *(position controlled)* #. Move to home pose *(position controlled)* Step 2 - Insert into guide 1 *(chamfered)* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the contact position *(position controlled)* #. Move to a position close to the guide *(position controlled)* #. Establish contact between T-piece and station *(force controlled)* #. Slide the T-piece into the guide until it is fully inside *(force controlled)* #. Slide the T-piece until it hits the guide end *(force controlled)* #. Open the gripper *(command to your specific gripper)* #. Move to home pose *(position controlled)* Step 3 - Retrieve from guide 1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the workpiece *(position controlled)* #. Lower the end effector to the gripping position *(position controlled)* #. Grip the T-piece *(command to your specific gripper)* #. Push down on the T-piece to ensure a safe grip *(force controlled - only needed for flat gripper fingers)* #. Slide the T-piece out *(force controlled)* #. Move up *(position controlled)* #. Move to home pose *(position controlled)* Step 4 - Insert into guide 2 *(not chamfered)* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the contact position *(position controlled)* #. Move to a position close to the guide *(position controlled)* #. Tilt the T-piece so that the **bottom left corner is exposed** *(position controlled)* #. Establish contact between T-piece and station *(force controlled)* #. Apply force so that the bottom left corner of the T-piece is pushed into the bottom left corner of the guide *(force controlled)* #. Apply force in the direction of the guide and align the T-piece with the guide *(force and position controlled)* #. Slide the T-piece into the guide *(force controlled)* #. Open the gripper *(command to your specific gripper)* #. Move to home pose *(position controlled)* .. tip:: Steps 4.4 – 4.7 replace the self-centring that the chamfer provides in guide 1. Tilting and corner-seating creates a **known contact state** from which the insertion direction is unambiguous. Step 5 - Retrieve from guide 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the workpiece *(position controlled)* #. Lower the end effector to the gripping position *(position controlled)* #. Grip the T-piece *(command to your specific gripper)* #. Push down on the T-piece to ensure a safe grip *(force controlled - only needed for flat gripper fingers)* #. Slide the T-piece out *(force controlled)* #. Move up *(position controlled)* #. Move to home pose *(position controlled)* Step 6 - Place in the workpiece carrier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Move to home pose *(position controlled)* #. Move to a position above the workpiece carrier *(position controlled)* #. Establish contact between T-piece and workpiece carrier *(force controlled)* #. Open the gripper *(command to your specific gripper)* #. Move upwards *(position controlled)* .. _p1-tips: Level 3 – Tips on using skills ------------------------------ .. list-table:: :header-rows: 1 :widths: 35 65 * - Goal - Recommended approach * - Establish contact with the surroundings - Use a **guarded approach**. * - Predictable linear motion with minimal jerk - Use ``lin_time_optimal_ruckig``. * - Follow a wall or guide under constant force - Use the pitasc **slide** skill. * - End a skill on a condition - Attach **monitors** to react to a force threshold or travelled distance. .. danger:: **Tare the force/torque sensor before every force-controlled skill.** This is the single most important step for reliable real-world operation - an untared sensor makes the measured contact force meaningless and can damage the workpiece or the station. See the code snippets below for how taring is invoked in practice. .. tip:: Add **user confirms** between skills. This makes it much easier to spot problems and abort execution safely while developing. .. _p1-solution: Level 4 – Step-by-step sample solution -------------------------------------- Preamble ~~~~~~~~ The preamble handles all imports of relevant models and configures the application environment, in which every component (robots, sensors, actuators) must be specified in order to be controlled later on. It also defines a boolean parameter to activate or deactivate all user confirmations at once. .. dropdown:: ``0_preamble.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/0_preamble.xml :language: xml Homing sequence for the gripper ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This short skill sequence commands the WSG 50-110 gripper to run its homing sequence. .. dropdown:: ``0.1_home_gripper.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/0.1_home_gripper.xml :language: xml Step 1: Pick up the workpiece from the carrier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Picks up the T-piece and carries it to the robot's home pose. .. dropdown:: ``1_pick.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/1_pick.xml :language: xml Step 2: Insert into guide 1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because the opening of guide 1 is chamfered, the T-piece centres itself (within limits). The position of the T-piece relative to the opening is therefore far less critical than for guide 2. .. dropdown:: ``2_insert_guide_1.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/2_insert_guide_1.xml :language: xml Step 3: Retrieve from guide 1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The pose at which the gripper held the inserted workpiece was saved. The following code slides the T-piece out of the guide and carries it back to the home pose. .. dropdown:: ``3_retrieve_guide_1.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/3_retrieve_guide_1.xml :language: xml Step 4: Insert into guide 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ While inserting into guide 2 appears to be the same task as guide 1, the lack of a chamfer proves to be an obstacle. The T-piece is therefore **tilted and pushed into one corner** of the guide to achieve a form of mutual centring. .. dropdown:: ``4_insert_guide_2.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/4_insert_guide_2.xml :language: xml Step 5: Retrieve from guide 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Similar to the retrieval from guide 1. The main difference is the **change of direction** for sliding and for moving the T-piece away from the guide. .. dropdown:: ``5_retrieve_guide_2.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/5_retrieve_guide_2.xml :language: xml Step 6: Place in the workpiece carrier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The final step places the T-piece back in the carrier. To prevent an unwanted collision in case the workpiece slipped during retrieval, the robot first moves to a position just above the carrier, then gently establishes contact and pushes the workpiece into the recess. .. dropdown:: ``6_place.xml`` :icon: code :color: light .. literalinclude:: /_xml/real_world_tutorial/6_place.xml :language: xml Complete sample solution ------------------------ For completeness, the full application is shown below. It includes all previously described steps, from homing the gripper to placing the T-piece back in the workpiece carrier. .. dropdown:: ``7_complete_application.xml`` - full application :icon: file-code :color: primary .. literalinclude:: /_xml/real_world_tutorial/7_complete_application.xml :language: xml :linenos: