Many updates to the operation docs

docs/_data/bringup.csv

@@ -0,0 +1,37 @@
+Argument,Description,Default,Choices
+robot_model_leader,model type of the leader arms.,``aloha_wx250s``,
+robot_model_follower,model type of the follower arms.,``aloha_vx300s``,
+robot_name_leader_left,name of the left leader arm,``leader_left``,
+robot_name_leader_right,name of the right leader arm,``leader_right``,
+robot_name_follower_left,name of the left follower arm,``follower_left``,
+robot_name_follower_right,name of the right follower arm,``follower_right``,
+leader_modes_left,the file path to the 'mode config' YAML file for the left leader arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'leader_modes_left.yaml''),
+leader_modes_right,the file path to the 'mode config' YAML file for the right leader arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'leader_modes_right.yaml''),
+follower_modes_left,the file path to the 'mode config' YAML file for the left follower arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'follower_modes_left.yaml''),
+follower_modes_right,the file path to the 'mode config' YAML file for the right follower arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'follower_modes_right.yaml''),
+launch_leaders,"if ``true``, launches both the leader and follower arms; if ``false, just the followers are launched.",``true``,"``true``, ``false``"
+use_cameras,"if ``true``, launches the camera drivers.",``true``,"``true``, ``false``"
+cam_high_name,,``cam_high``,
+cam_low_name,,``cam_low``,
+cam_left_wrist_name,,``cam_left_wrist``,
+cam_right_wrist_name,,``cam_right_wrist``,
+is_mobile,,EnvVar\(``INTERBOTIX_ALOHA_IS_MOBILE``\),"``true``, ``false``"
+use_base,"if ``true``, launches the driver for the SLATE base.",LaunchConfig\(``is_mobile``\),"``true``, ``false``"
+use_joystick_teleop,"if ``true``, launches a joystick teleop node for the base.",LaunchConfig\(``use_base``\),"``true``, ``false``"
+use_aloha_rviz,"One of: ('true', 'false')",``false``,
+aloha_rvizconfig,,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'rviz' + 'aloha.rviz''),
+base_link_frame,"name of the 'root' link on the arm; typically ``base_link``, but can be changed if attaching the arm to a mobile base that already has a ``base_link`` frame.",``base_link``,
+use_gripper,"if ``true``, the default gripper is included in the ``robot_description``; if ``false``, it is left out; set to ``false`` if not using the default gripper.",``true``,"``true``, ``false``"
+show_ar_tag,"if ``true``, the AR tag mount is included in the ``robot_description``; if ``false``, it is left out; set to ``true`` if using the AR tag mount in your project.",``false``,"``true``, ``false``"
+show_gripper_bar,"if ``true``, the gripper_bar link is included in the ``robot_description``; if ``false``, the gripper_bar and finger links are not loaded. Set to ``false`` if you have a custom gripper attachment.",``true``,"``true``, ``false``"
+show_gripper_fingers,"if ``true``, the gripper fingers are included in the ``robot_description``; if ``false``, the gripper finger links are not loaded. Set to ``false`` if you have custom gripper fingers.",``true``,"``true``, ``false``"
+use_world_frame,"set this to ``true`` if you would like to load a 'world' frame to the ``robot_description`` which is located exactly at the 'base_link' frame of the robot; if using multiple robots or if you would like to attach the 'base_link' frame of the robot to a different frame, set this to ``false``.",``false``,"``true``, ``false``"
+external_urdf_loc,the file path to the custom urdf.xacro file that you would like to include in the Interbotix robot's urdf.xacro file.,'',
+hardware_type,"configures the ``robot_description`` to use the actual hardware, fake hardware, or hardware simulated in Gazebo.",``actual``,"``actual``, ``fake``, ``gz_classic``"
+robot_description_leader_left,URDF of the robot; this is typically generated by the xacro command.,Command(FindExec\(``xacro``\) + ' ' + LocalVar('FindPackageShare\(pkg= ``interbotix_xsarm_descriptions``\) + 'urdf' + LaunchConfig\(``robot_model_leader``\)') + '.urdf.xacro ' + 'robot_name:=' + LaunchConfig\(``robot_name_leader_left``\) + ' ' + 'base_link_frame:=' + LaunchConfig\(``base_link_frame``\) + ' ' + 'use_gripper:=' + LaunchConfig\(``use_gripper``\) + ' ' + 'show_ar_tag:=' + LaunchConfig\(``show_ar_tag``\) + ' ' + 'show_gripper_bar:=' + LaunchConfig\(``show_gripper_bar``\) + ' ' + 'show_gripper_fingers:=' + LaunchConfig\(``show_gripper_fingers``\) + ' ' + 'use_world_frame:=' + LaunchConfig\(``use_world_frame``\) + ' ' + 'external_urdf_loc:=' + LaunchConfig\(``external_urdf_loc``\) + ' ' + 'hardware_type:=' + LaunchConfig\(``hardware_type``\) + ' '),
+robot_description_leader_right,URDF of the robot; this is typically generated by the xacro command.,Command(FindExec\(``xacro``\) + ' ' + LocalVar('FindPackageShare\(pkg= ``interbotix_xsarm_descriptions``\) + 'urdf' + LaunchConfig\(``robot_model_leader``\)') + '.urdf.xacro ' + 'robot_name:=' + LaunchConfig\(``robot_name_leader_right``\) + ' ' + 'base_link_frame:=' + LaunchConfig\(``base_link_frame``\) + ' ' + 'use_gripper:=' + LaunchConfig\(``use_gripper``\) + ' ' + 'show_ar_tag:=' + LaunchConfig\(``show_ar_tag``\) + ' ' + 'show_gripper_bar:=' + LaunchConfig\(``show_gripper_bar``\) + ' ' + 'show_gripper_fingers:=' + LaunchConfig\(``show_gripper_fingers``\) + ' ' + 'use_world_frame:=' + LaunchConfig\(``use_world_frame``\) + ' ' + 'external_urdf_loc:=' + LaunchConfig\(``external_urdf_loc``\) + ' ' + 'hardware_type:=' + LaunchConfig\(``hardware_type``\) + ' '),
+robot_description_follower_left,URDF of the robot; this is typically generated by the xacro command.,Command(FindExec\(``xacro``\) + ' ' + LocalVar('FindPackageShare\(pkg= ``interbotix_xsarm_descriptions``\) + 'urdf' + LaunchConfig\(``robot_model_follower``\)') + '.urdf.xacro ' + 'robot_name:=' + LaunchConfig\(``robot_name_follower_left``\) + ' ' + 'base_link_frame:=' + LaunchConfig\(``base_link_frame``\) + ' ' + 'use_gripper:=' + LaunchConfig\(``use_gripper``\) + ' ' + 'show_ar_tag:=' + LaunchConfig\(``show_ar_tag``\) + ' ' + 'show_gripper_bar:=' + LaunchConfig\(``show_gripper_bar``\) + ' ' + 'show_gripper_fingers:=' + LaunchConfig\(``show_gripper_fingers``\) + ' ' + 'use_world_frame:=' + LaunchConfig\(``use_world_frame``\) + ' ' + 'external_urdf_loc:=' + LaunchConfig\(``external_urdf_loc``\) + ' ' + 'hardware_type:=' + LaunchConfig\(``hardware_type``\) + ' '),
+robot_description_follower_right,URDF of the robot; this is typically generated by the xacro command.,Command(FindExec\(``xacro``\) + ' ' + LocalVar('FindPackageShare\(pkg= ``interbotix_xsarm_descriptions``\) + 'urdf' + LaunchConfig\(``robot_model_follower``\)') + '.urdf.xacro ' + 'robot_name:=' + LaunchConfig\(``robot_name_follower_right``\) + ' ' + 'base_link_frame:=' + LaunchConfig\(``base_link_frame``\) + ' ' + 'use_gripper:=' + LaunchConfig\(``use_gripper``\) + ' ' + 'show_ar_tag:=' + LaunchConfig\(``show_ar_tag``\) + ' ' + 'show_gripper_bar:=' + LaunchConfig\(``show_gripper_bar``\) + ' ' + 'show_gripper_fingers:=' + LaunchConfig\(``show_gripper_fingers``\) + ' ' + 'use_world_frame:=' + LaunchConfig\(``use_world_frame``\) + ' ' + 'external_urdf_loc:=' + LaunchConfig\(``external_urdf_loc``\) + ' ' + 'hardware_type:=' + LaunchConfig\(``hardware_type``\) + ' '),
+use_gravity_compensation,"if ``true``, launches the gravity compensation node.",``true``,"``true``, ``false``"
+leader_motor_specs_left,the file path to the 'motor specs' YAML file for the left leader arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'leader_motor_specs_left.yaml''),
+leader_motor_specs_right,the file path to the 'motor specs' YAML file for the right leader arm.,LocalVar('FindPackageShare\(pkg= ``aloha``\) + 'config' + 'leader_motor_specs_right.yaml''),

docs/operation.rst

@@ -5,6 +5,7 @@ Operation
 .. toctree::
   :maxdepth: 2
 
+  ./operation/bringup_shutdown.rst
   ./operation/mobile.rst
   ./operation/stationary.rst
   ./operation/data_collection.rst

docs/operation/bringup_shutdown.rst

@@ -0,0 +1,69 @@
+==================
+Bringup & Shutdown
+==================
+
+Bringup
+=======
+
+To bring up a Mobile or Stationary ALOHA, you will need to run the following commands in a terminal:
+
+.. code-block:: bash
+
+  $ export INTERBOTIX_ALOHA_IS_MOBILE=true/false # true for Mobile, false for Stationary
+  $ source /opt/ros/humble/setup.bash # configure ROS system install environment
+  $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment
+  $ ros2 launch aloha aloha_bringup.launch.py # launch hardware drivers and control software
+
+.. warning::
+
+  Terminating bringup while the arms are not in their sleep configurations will cause them to collapse!
+  Be sure to run through the :ref:`operation/bringup_shutdown:shutdown` procedure before doing so.
+
+.. tip::
+
+  The ALOHA can be brought up with additional arguments to customize the behavior.
+  For a full list of arguments, refer to the :ref:`operation/bringup_shutdown:Arguments for ALOHA Bringup` section below.
+
+Shutdown
+========
+
+To shutdown the ALOHA, you will need to first send the arms to their sleep configurations.
+While the ALOHA bringup is running in another terminal, open a new one and run the following commands:
+
+.. code-block:: bash
+
+  $ export INTERBOTIX_ALOHA_IS_MOBILE=true/false # true for Mobile, false for Stationary
+  $ source /opt/ros/humble/setup.bash # configure ROS system install environment
+  $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment
+  $ cd ~/interbotix_ws/src/aloha/scripts/
+  $ python3 sleep.py
+
+The follower arms will move to their "staged" configurations and then place themselves into their sleep configurations.
+
+.. tip::
+
+  You can optionally append the ``-a|--all`` flag to the sleep script command to send all arms to their sleep configurations:
+
+  .. code-block:: bash
+
+    $ python3 sleep.py -a
+    # or
+    $ python3 sleep.py --all
+
+Now that the arms are in their sleep configurations, you can terminate the ALOHA bringup by pressing :kbd:`Ctrl` + :kbd:`C` in the terminal where the bringup was launched.
+
+What's Next?
+============
+
+Now that you know how to bringup and shutdown the ALOHA, teleoperation will be a good starting point to explore its features.
+
+-   :doc:`/operation/mobile`
+-   :doc:`/operation/stationary`
+
+Arguments for ALOHA Bringup
+===========================
+
+.. csv-table::
+  :file: ../_data/bringup.csv
+  :header-rows: 1
+  :widths: 20, 60, 20, 20

docs/operation/data_collection.rst

@@ -32,24 +32,29 @@ Recording Episodes
 
 To record an episode, follow the steps below:
 
-#.  Bring up the ALOHA control stack according to your platform
-
-    * Stationary: :ref:`operation/stationary:Running ALOHA Bringup`
-    * Mobile: :ref:`operation/mobile:Running ALOHA Bringup`
+#.  :ref:`operation/bringup_shutdown:bringup` the ALOHA control stack according to your platform
 
 #.  Configure the environment and run the episode recording script as follows:
 
   .. code-block:: bash
 
     $ source /opt/ros/humble/setup.bash # configure ROS system install environment
     $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment
-    $ source /<path_to_aloha_venv>/bin/activate # configure ALOHA Python environment
     $ cd ~/interbotix_ws/src/aloha/scripts/
-    $ python3 record_episodes.py --task_name <task_name> --episode_idx <episode_idx>
+    $ python3 record_episodes.py \
+          --task_name <task_name> \
+          [--episode_idx <episode_idx>] \
+          [-b, --enable_base_torque] \
+          [-g, --gravity_compensation]
+
+  The ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section.
+
+  The ``episode_idx`` argument is optional and specifies the index of the episode to record reflected in the output filename ``<dataset_dir>/episode_<episode_idx>.hdf5``.
+  If not provided, the script will automatically calculate the next episode index based on the number of episodes already saved in the dataset directory.
 
-  .. note::
+  If the ``-b, --enable_base_torque`` argument is set, mobile base will be torqued on during episode recording, allowing the use of a joystick controller or some other manual method.
 
-    The ``task_name`` argument should match one of the task names in the ``TASK_CONFIGS``, as configured in the :ref:`operation/data_collection:Task Creation` section.
+  If the ``-g, --gravity_compensation`` argument is set, gravity compensation will be enabled for the leader robots when teleop starts.
 
   .. tip::
 
@@ -68,18 +73,14 @@ Episode Playback
 
 To play back a previously-recorded episode, follow the steps below:
 
-#.  Bring up the ALOHA control stack according to your platform
-
-    * Stationary: :ref:`operation/stationary:Running ALOHA Bringup`
-    * Mobile: :ref:`operation/mobile:Running ALOHA Bringup`
+#.  :ref:`operation/bringup_shutdown:bringup` the ALOHA control stack according to your platform
 
 #.  Configure the environment and run the episode playback script as follows:
 
   .. code-block:: bash
 
     $ source /opt/ros/humble/setup.bash # configure ROS system install environment
     $ source ~/interbotix_ws/install/setup.bash # configure ROS workspace environment
-    $ source /<path_to_aloha_venv>/bin/activate # configure ALOHA Python environment
     $ cd ~/interbotix_ws/src/aloha/scripts/
     $ python3 replay_episodes.py --dataset_dir </path/to/dataset> --episode_idx <episode_idx>
 
@@ -114,17 +115,6 @@ This value is used to set the path to the ``ROS_SETUP_PATH`` variable used later
 
   ROS_DISTRO=humble
 
-``VENV_ACTIVATE_PATH``
-^^^^^^^^^^^^^^^^^^^^^^
-
-Set the path to the virtual environment's activate file.
-This value is used when setting up the Python virtual environment.
-``VENV_ACTIVATE_PATH`` defaults to ``"$HOME/act/bin/activate"``.
-
-.. code-block:: bash
-
-  VENV_ACTIVATE_PATH="$HOME/act/bin/activate"
-
 ``ROS_SETUP_PATH``
 ^^^^^^^^^^^^^^^^^^
 
@@ -164,16 +154,13 @@ Usage
 
 Once configured, the auto_record script is now ready to use. To auto-record a specific amount of episodes, follow the steps below:
 
-#.  Bring up the ALOHA control stack according to your platform
-
-    * Stationary: :ref:`operation/stationary:Running ALOHA Bringup`
-    * Mobile: :ref:`operation/mobile:Running ALOHA Bringup`
+#.  :ref:`operation/bringup_shutdown:bringup` the ALOHA control stack according to your platform
 
 #.  In a new terminal, navigate to the directory storing the auto_record script and run the command below:
 
     .. code-block::
 
-      $ auto_record.sh <task_name> <num_episodes>
+      $ auto_record.sh <task_name> <num_episodes> [-b, --enable_base_torque] [-g, --gravity_compensation]
 
     .. tip::
 
@@ -208,3 +195,8 @@ ALOHA saves its episodes in the `hdf5 format`_ with the following format:
 
     action                  (14,)         'float64'
     base_action             (2,)          'float64' (on Mobile)
+
+What's Next?
+============
+
+With the data collected, we are ready to :doc:`train and evaluate </operation/training>` the machine learning models.

docs/operation/lerobot_guide.rst

@@ -60,7 +60,7 @@ Teleoperation
 To teleoperate your robot, follow these steps:
 
 #. Find the serial numbers of your robot's arms and cameras as described in the following documentation:
-   
+
    - Arm Symlink Setup: `Aloha Post Install Arm Setup <https://docs.trossenrobotics.com/aloha_docs/getting_started/stationary/software_setup.html#arm-symlink-setup>`_
    - Camera Setup: `Aloha Post Install Camera Setup <https://docs.trossenrobotics.com/aloha_docs/getting_started/stationary/software_setup.html#camera-setup>`_
 
@@ -136,7 +136,7 @@ The system supports episode-based data collection, where episodes are time-bound
 
    #. The :guilabel:`--num-episodes` defines the total number of episodes to be collected.
       Therefore it will check the existing output directories for any previously recorded episodes and will start recording from the last recorded episode.
-   
+
    #. The recorded data is pushed to hugging face hub by default you can set this false by using :guilabel:`--push-to-hub 0`.
 
 .. note::
@@ -203,7 +203,7 @@ To replay the first episode of your recorded dataset:
 
    Use different :guilabel:`--fps` values to adjust the frequency of the robot actions.
 
-Training 
+Training
 ========
 
 To train a policy for controlling your robot, use the following command:
@@ -393,9 +393,9 @@ Arrow Keys Not Working During Data Recording (Linux)
 
 Frequency drops during evaluation
 ---------------------------------
-  
+
    This happens on low-performance systems due to their inability to handle multi-threaded I/O operations.
-   Checkout the following version for a smoother operation. 
+   Checkout the following version for a smoother operation.
    Changes will be integrated soon in the newer version of the repository.
    `Low Frequency Fix <https://github.com/Interbotix/lerobot/pull/3>`_