Updating Docs for commit 3b0341b made on 2024-09-17T16:12:20+00:00 fr…

…om refs/heads/master by firephinx

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 21abeef3817ee902e2935c9f0ae82485
+tags: 645f666f9bcd5a90fca523b33c5a78b7

README.md

@@ -0,0 +1,10 @@
+# GitHub Pages Cache
+
+Nothing to see here. The contents of this branch are essentially a cache that's not intended to be viewed on github.com.
+
+
+If you're looking to update our documentation, check the relevant development branch's 'docs/' dir.
+
+For more information on how this documentation is built using Sphinx, Read the Docs, and GitHub Actions/Pages, see:
+
+ * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1

_sources/frankaarm.rst.txt

@@ -0,0 +1,8 @@
+Frankapy
+========
+
+FrankaArm
+---------
+
+.. autoclass:: frankapy.FrankaArm
+   :members:

_sources/index.rst.txt

@@ -0,0 +1,38 @@
+.. frankapy documentation master file, created by
+   sphinx-quickstart on Sat Jun  5 14:43:41 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to FrankaPy's Documentation!
+====================================
+
+This library was designed to be used on a Ubuntu 18.04 / Ubuntu 20.04 PC with either ROS Melodic or ROS Noetic. We are currently not supporting ROS2 at the moment.
+
+To join the Discord community, click the link `here <https://discord.gg/r6r7dttMwZ>`_. 
+
+If this library proves useful to your research, please cite the paper below::
+
+    @article{zhang2020modular,
+      title={A modular robotic arm control stack for research: Franka-interface and frankapy},
+      author={Zhang, Kevin and Sharma, Mohit and Liang, Jacky and Kroemer, Oliver},
+      journal={arXiv preprint arXiv:2011.02398},
+      year={2020}
+    }
+
+Note that this library has been released with the Apache v2.0 license.
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   network
+   running
+   frankaarm
+   support
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

_sources/install.rst.txt

@@ -0,0 +1,98 @@
+Installation
+============
+
+Requirements
+------------
+
+* A computer with Ubuntu 18.04 / 20.04
+* ROS Melodic / Noetic
+
+
+Steps
+-----
+
+1. Clone the Frankapy Repository and its Submodules::
+
+    git clone --recurse-submodules [email protected]:iamlab-cmu/frankapy.git
+
+2. To allow asynchronous gripper commands, we use the ``franka_ros`` package, so install libfranka and franka_ros using the following command (Change melodic to noetic if you are on Ubuntu 20.04)::
+
+    sudo apt install ros-melodic-libfranka ros-melodic-franka-ros
+
+3. Create and enter a virtual environment (:ref:`Virtual Environment`) and then run the following commands::
+
+    cd frankapy
+    pip install -e .
+
+4. Compile the catkin_ws using the following script::
+
+    ./bash_scripts/make_catkin.sh
+
+5. Afterwards source the ``catkin_ws`` using the following command::
+
+    source catkin_ws/devel/setup.bash
+
+6. It is a good idea to add the following line to the end of your ``~/.bashrc`` file::
+
+    source /path/to/frankapy/catkin_ws/devel/setup.bash --extend
+
+
+(Optional) Additional Steps
+---------------------------
+
+Protobuf
+~~~~~~~~
+
+If you plan on modifying the library and the protobuf messages, you will need to compile the `Google Protocol Buffer <https://developers.google.com/protocol-buffers>`_ library from scratch using the following instructions.
+
+1. First determine the number of cores on your computer using the command::
+
+    nproc
+
+2. Execute the following commands::
+
+    sudo apt-get install autoconf automake libtool curl make g++ unzip
+    wget https://github.com/protocolbuffers/protobuf/releases/download/v21.8/protobuf-all-21.8.zip
+    unzip protobuf-all-21.8.zip
+    cd protobuf-21.8
+    ./configure
+
+3. Use the number that was previously printed out using the ``nproc`` command above and substitute it as ``N`` below::
+
+    make -jN
+    sudo make install
+    sudo ldconfig
+
+4. Afterwards, you can make the protobuf messages using the following script::
+
+    ./bash_scripts/make_proto.sh
+
+
+Virtual Environment
+~~~~~~~~~~~~~~~~~~~
+
+Note that these instructions work on Ubuntu 18.04. They might be slightly different for Ubuntu 20.04.
+
+1. Install Python3.6::
+
+    sudo apt install -y python3-distutils
+
+2. Install Pip::
+
+    curl https://bootstrap.pypa.io/get-pip.py | sudo -H python3.6
+
+3. Install Virtual Environment and Other Useful Python Packages::
+
+    sudo -H pip3.6 install numpy matplotlib virtualenv
+
+4. Create a Virtual Environment for Frankapy::
+
+    virtualenv -p python3.6 franka
+
+5. Enter into the Virtual Environment::
+
+    source franka/bin/activate
+
+6. How to exit the Virtual Environment::
+
+    deactivate

_sources/network.rst.txt

@@ -0,0 +1,114 @@
+Network Configuration
+=====================
+
+If you are running franka-interface and frankapy on the same computer, you can skip this page.
+
+Requirements
+------------
+
+* A Control PC computer running Ubuntu 18.04 with a Realtime Kernel. It should also have franka-interface installed with ROS Melodic.
+
+Terminology
+-----------
+
+Control PC - Realtime Kernel PC connected by Ethernet to the Robot
+
+FrankaPy PC - Computer running FrankaPy
+
+Ethernet
+--------
+
+1. Plug an ethernet cable directly between the Control PC and the FrankaPy PC.
+
+2. Go into the Ubuntu Network Connections Menu on the Control PC.
+
+3. Select the Wired connection that corresponds to the Ethernet port that is connected to the FrankaPy PC. Then click the settings gear icon to edit.
+
+4. Go to the IPv4 Settings Tab and switch from Automatic (DHCP) to Manual. Add a static ip address like 192.168.1.3 on the Control PC with netmask 24 and then click Apply.
+
+    .. image:: imgs/network_config.png
+      :width: 600
+      :alt: Network Config Photo
+
+5. Then do the same on the FrankaPy PC but instead set the static ip address to be 192.168.1.2 with netmask 24.
+
+Wifi
+----
+
+While FrankaPy will work over Wifi, it is not recommended due to additional latency in sending commands between computers.
+
+1. If you are only communicating with the Control PC over Wifi, use the command ``ifconfig`` in order to get the Wifi IP address of both the Control PC and FrankaPy PC and note them down.
+
+Editing the /etc/hosts file
+---------------------------
+
+1. Now that you have the IP addresses for both the Control PC and FrankaPy PC, you will need to edit the /etc/hosts files on both computers in order to allow communication between the 2 over ROS.
+
+2. On the Control PC, run the command::
+
+    sudo gedit /etc/hosts
+
+3. If you are using an Ethernet connection, then add the following above the line ``# The following lines are desirable for IPv6 capable hosts:`` ::
+
+    192.168.1.2     [frankapy-pc-name]
+
+\   
+    Otherwise substitute ``192.168.1.2`` with the IP address of the FrankaPy PC that you discovered using the command ``ifconfig``.
+
+4. Afterwards, on the FrankaPy PC, again run the command ``sudo gedit /etc/hosts`` and add the line::
+
+    192.168.1.3     [control-pc-name]
+
+\
+    Otherwise substitute ``192.168.1.3`` with the IP address of the Control PC that you discovered using the command ``ifconfig``.
+
+5. Now you should be able to ssh from the FrankaPy PC to the Control PC using the command::
+
+    ssh [control-pc-username]@[control-pc-name]
+    Input password to control-pc.
+
+Setting Up SSH Key to Control PC
+--------------------------------
+
+Generate a new SSH Key on the FrankaPy PC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Generate a SSH key by executing the following commands or reading these `instructions <https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_::
+
+    ssh-keygen -t rsa -b 4096 -C "[email protected]"
+    [Press enter]
+    [Press enter]
+    [Press enter]
+    eval "$(ssh-agent -s)"
+    ssh-add ~/.ssh/id_rsa
+
+Upload the public SSH key to the Control PC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. In a new terminal on your FrankaPy PC, use your favorite text editor to open your ``id_rsa.pub`` file::
+
+    gedit ~/.ssh/id_rsa.pub
+
+2. Copy the contents in your ``id_rsa.pub`` file.
+
+3. Next, SSH to the Control PC::
+
+    ssh [control-pc-username]@[control-pc-name]
+    Input password to control-pc.
+
+4. Use vim to open the authorized_keys file::
+
+    vim ~/.ssh/authorized_keys
+
+5. Press the following buttons to paste your copied public key into the ``authorized_keys`` file on the Control PC::
+
+    i
+    ctrl-shift-v
+    <esc>
+    :
+    w
+    q
+    <enter>
+
+6. Open a new terminal on the FrankaPy PC and try SSHing to the Control PC and it should no longer require a password.
+
+7. (Optional) Upload your SSH key to Github by following instructions `here <https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account>`_.

_sources/running.rst.txt

@@ -0,0 +1,51 @@
+Running the Robot
+=================
+
+Unlocking the Franka Robot
+--------------------------
+
+1. If you are running franka-interface and frankapy on the same computer, you can skip to step 2. If you have a FrankaPy PC and a Control PC, first ssh to the Control PC from the FrankaPy PC using SSH with option ``-X``::
+
+    ssh -X [control-pc-username]@[control-pc-name]
+
+2. Open a web browser, either firefox or google chrome using the command line::
+    
+    firefox
+
+3. Go to ``172.16.0.2`` in the web browser.
+
+4. Login to the Franka Desk GUI using the username and password that you used during the initial robot setup.
+
+5. Unlock the robot by clicking the unlock button on the bottom right of the web interface.
+
+6. If the robot has pink lights, press down on the e-stop and then release it and the robot should turn blue. If the robot is white, just release the e-stop and it should also turn blue.
+
+
+Starting the FrankaPy Interface
+-------------------------------
+
+1. Make sure that the Franka Robot has been unlocked in the Franka Desk GUI and has blue lights. 
+
+2. Open up a new terminal and go to the frankapy directory.
+
+3. If you are running franka-interface and frankapy on the same computer, run the following command::
+
+    bash ./bash_scripts/start_control_pc.sh -i localhost
+
+4. Otherwise run the following command::
+
+    bash ./bash_scripts/start_control_pc.sh -u [control-pc-username] -i [control-pc-name]
+
+5. Please see the ``bash_scripts/start_control_pc.sh`` bash script for additional arguments, including specifying a custom directory for where franka-interface is installed on the Control PC. 
+
+6. Open up a new terminal, enter into the same virtual environment that FrankaPy was installed in, go to the frankapy directory, then::
+
+    source catkin_ws/devel/setup.bash
+
+7. Place your hand on top of the e-stop and reset the robot with the following command::
+
+    python scripts/reset_arm.py
+
+8. See example scripts in the ``examples/`` and ``scripts/`` folders to learn how to use the FrankaPy python package.
+
+9. Please note that if you are using a custom gripper or no gripper, please set the ``with_gripper=True`` flag in ``frankapy/franka_arm.py`` to ``False`` as well as set the ``with_gripper=1`` flag in ``bash_scripts/start_control_pc.sh`` to ``0``.

_sources/support.rst.txt

@@ -0,0 +1,4 @@
+Support
+=======
+
+The easiest way to get help with the library is to join the FrankaPy and Franka-Interface Discord using this link `here <https://discord.gg/r6r7dttMwZ>`_.