.. _auto_get_user_home:

get_user_home (Auto Mode)
------------------------------------------
This section explains how to use :ref:`get_user_home <get_user_home>`  
during **Auto (Run)** operations to retrieve the **user-defined home pose**  
stored in the robot controller.

The user home pose is typically configured beforehand using  
:ref:`set_user_home <auto_set_user_home>` and is often used as a safe return  
position during automated workflows.

**Typical usage**

- Retrieve the saved home position before executing a homing or return-to-base motion.  
- Log the home pose for debugging, calibration, or system validation.  
- Check the current stored home pose after an operator updates it on the teach pendant.  
- Use as a reference point for workspace initialization or task resets.  

.. Note::

   - Returns a pointer to :ref:`ROBOT_POSE <struct_ROBOT_POSE>`.  
   - Always validate the returned pointer before accessing pose values.  

**Example: Reading and Printing the User-Defined Home Position**

.. code-block:: cpp

   // 1) Retrieve the user-defined home pose
   LPROBOT_POSE home = drfl.get_user_home();

   if (!home) {
       printf("Failed to retrieve user home pose.\n");
       return -1;
   }

   // 2) Print the home joint angles [deg]
   printf("User Home Position:\n");
   printf("J1: %.1f\n", home->_fPosition[0]);
   printf("J2: %.1f\n", home->_fPosition[1]);
   printf("J3: %.1f\n", home->_fPosition[2]);
   printf("J4: %.1f\n", home->_fPosition[3]);
   printf("J5: %.1f\n", home->_fPosition[4]);
   printf("J6: %.1f\n", home->_fPosition[5]);

In this example, the program retrieves the saved user home pose  
and prints the joint position values [deg],  
allowing the automation system to confirm or log the reference position  
before moving the robot.

**Tips**

- Ideal for verifying the home pose before executing a return-to-home sequence.  
- Useful when operators frequently update home positions in the field.  
- Combine with motion functions such as ``movej`` or ``amovel`` to automate homing routines.  
- Log home pose values to ensure consistent setup across shifts or production cycles.