diff --git a/README.md b/README.md index b4b1495..2ffb857 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Since UDP is the only supported connection type and the connection object is not See the [examples](examples/). -# Quickstart +## Quickstart 1. Clone repository (make sure you include `--recursive`): ```shell @@ -56,13 +56,11 @@ See the [examples](examples/). > [!NOTE] > FRI client is fetched from [fri](https://github.com/lbr-stack/fri) and must be available as branch, refer [README](https://github.com/lbr-stack/fri?tab=readme-ov-file#contributing). -# Important notice +4. Setup the hardware, see [Hardware Setup](https://lbr-stack.readthedocs.io/en/latest/lbr_fri_ros2_stack/lbr_fri_ros2_stack/doc/hardware_setup.html). -**THIS IS NOT A KUKA PRODUCT.** +5. Checkout the [example applications](https://lbr-stack.readthedocs.io/en/latest/pyfri/doc/example_applications.html#example-applications). -[@cmower](https://github.com/cmower) and [@mhubii](https://github.com/mhubii) are not affiliated with KUKA. - -# Citation +## Citation If you enjoyed using this repository for your work, we would really appreciate ❤️ if you could leave a ⭐ and / or cite it, as it helps us to continue offering support. ``` diff --git a/doc/example_applications.rst b/doc/example_applications.rst new file mode 100644 index 0000000..7b273d1 --- /dev/null +++ b/doc/example_applications.rst @@ -0,0 +1,172 @@ +Usage +----- +.. contents:: Table of Contents + :depth: 3 + :local: + :backlinks: none + +Data Types +~~~~~~~~~~ + +You can pass NumPy arrays to the "set" methods (e.g. ``setJointPosition``) in order to command the robot. +However, you **must** ensure the format of the array is correct. + +Arrays that have a ``dtype`` of ``np.float32`` are the only ones that can be accepted. +See how the commands are set in the the examples. + +Collecting Data from the Robot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We provide additional functionality to the LBR client application class that enables data collection to a text file. +In Python, simply add the following + +```python +app = fri.ClientApplication(client) +app.collect_data(file_name) +``` + +The string ``file_name`` should contain the file name for the data file. +We use the comma-separated values format for the data file, and so the file name should end with the extension ``.csv`` - *note*, if this isn't the case then ``.csv`` is automatically appended to the given file name. + +The columns in the recorded csv file are as follows: +* ``index``: the index of the recorded data, starts at 0, and is incremented by 1 at each call to the ``step`` method. +* ``time``: the time of the command, starts at 0.0, then is incremented by the sample time at each call to the ``step`` method. +* ``record_time_nsec``: the epoch time collected when the data in the current time step is recorded. +* ``tsec``: controller time as specified by the FRI in seconds. See FRI documentation for ``getTimestampSec``. +* ``tnsec``: controller time as specified by the FRI in nanoseconds. See FRI documentation for ``getTimestampNanoSec``. +* ``mp1, ..., mp7``: The measured joint position for the robot. +* ``ip1, ..., ip7``: The ipo joint position for the robot. +* ``mt1, ..., mt7``: The measured torque for the robot. +* ``et1, ..., et7``: The external torque for the robot. +* ``dt``: The sample time specified on the KUKA controller. + +See the [examples/LBRJointSineOverlay.py](examples/LBRJointSineOverlay.py) example that demonstrates how to easily collect data from the robot. + +Example Applications +~~~~~~~~~~~~~~~~~~~~ +First, ensure the corresponding Java applications for each example are installed (these were supplied with KUKA Sunrise). +Then turn on the robot, connect your laptop via ethernet, and follow these steps on your laptop. + +1. Change directory: ``cd /path/to/FRI-Client-SDK_Python/examples`` +2. Run examples + +Hand-guiding +^^^^^^^^^^^^ +Source code: `hand_guide.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +#. Client side: + +Joint Teleoperation +^^^^^^^^^^^^^^^^^^^ +Source code: `joint_teleop.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +#. Client side: + +- ``$ python3 joint_teleop.py`` + + +Task Teleoperation +^^^^^^^^^^^^^^^^^^ +Source code: `task_teleop.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +- ``$ python3 task_teleop.py`` + +KUKA Default Demos +^^^^^^^^^^^^^^^^^^ +LBR Joint Sine Overlay +"""""""""""""""""""""" +Source code: `LBRJointSineOverlay.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +- ``$ python3 LBRJointSineOverlay.py # based on examples provided by KUKA`` + + +LBR Torque Sine Overlay +""""""""""""""""""""""" +Source code: `LBRTorqueSineOverlay.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +- ``$ python3 LBRTorqueSineOverlay.py # based on examples provided by KUKA`` + + +LBR Wrench Sine Overlay +""""""""""""""""""""""" +Source code: `LBRWrenchSineOverlay.py `_:octicon:`link-external` + +#. Remote side configurations: + + #. .. dropdown:: Launch the ``LBRServer`` application on the ``KUKA smartPAD`` + + .. thumbnail:: img/applications_lbr_server.png + + #. Select + + - ``FRI send period``: ``10 ms`` + - ``IP address``: ``your configuration`` + - ``FRI control mode``: ``POSITION_CONTROL`` + - ``FRI client command mode``: ``POSITION`` + +- ``$ python3 LBRWrenchSineOverlay.py # based on examples provided by KUKA`` diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index 037246a..0000000 --- a/doc/examples.rst +++ /dev/null @@ -1,51 +0,0 @@ - -# Usage - -## Data types - -You can pass NumPy arrays to the "set" methods (e.g. `setJointPosition`) in order to command the robot. -However, you **must** ensure the format of the array is correct. - -Arrays that have a `dtype` of `np.float32` are the only ones that can be accepted. -See how the commands are set in the the examples. - -## Collecting data from the robot - -We provide additional functionality to the LBR client application class that enables data collection to a text file. -In Python, simply add the following - -```python -app = fri.ClientApplication(client) -app.collect_data(file_name) -``` - -The string `file_name` should contain the file name for the data file. -We use the comma-separated values format for the data file, and so the file name should end with the extension `.csv` - *note*, if this isn't the case then `.csv` is automatically appended to the given file name. - -The columns in the recorded csv file are as follows: -* `index`: the index of the recorded data, starts at 0, and is incremented by 1 at each call to the `step` method. -* `time`: the time of the command, starts at 0.0, then is incremented by the sample time at each call to the `step` method. -* `record_time_nsec`: the epoch time collected when the data in the current time step is recorded. -* `tsec`: controller time as specified by the FRI in seconds. See FRI documentation for `getTimestampSec`. -* `tnsec`: controller time as specified by the FRI in nanoseconds. See FRI documentation for `getTimestampNanoSec`. -* `mp1, ..., mp7`: The measured joint position for the robot. -* `ip1, ..., ip7`: The ipo joint position for the robot. -* `mt1, ..., mt7`: The measured torque for the robot. -* `et1, ..., et7`: The external torque for the robot. -* `dt`: The sample time specified on the KUKA controller. - -See the [examples/LBRJointSineOverlay.py](examples/LBRJointSineOverlay.py) example that demonstrates how to easily collect data from the robot. - -# Examples - -First, ensure the corresponding Java applications for each example are installed (these were supplied with KUKA Sunrise). -Then turn on the robot, connect your laptop via ethernet, and follow these steps on your laptop. - -1. Change directory: `cd /path/to/FRI-Client-SDK_Python/examples` -2. Run examples - - `$ python3 LBRJointSineOverlay.py # based on examples provided by KUKA` - - `$ python3 LBRTorqueSineOverlay.py # based on examples provided by KUKA` - - `$ python3 LBRWrenchSineOverlay.py # based on examples provided by KUKA` - - `$ python3 joint_teleop.py` - - `$ python3 task_teleop.py` - diff --git a/doc/img/applications_lbr_server.png b/doc/img/applications_lbr_server.png new file mode 100644 index 0000000..6588f6a Binary files /dev/null and b/doc/img/applications_lbr_server.png differ diff --git a/doc/pyfri.rst b/doc/pyfri.rst index f8f3d6c..1df0d0f 100644 --- a/doc/pyfri.rst +++ b/doc/pyfri.rst @@ -1,6 +1,8 @@ -pyfri -===== +.. include:: ../README.md + :parser: myst_parser.sphinx_ -.. ## Upgrading/switching between FRI Versions +.. toctree:: + :hidden: -.. If you upgrade your FRI version or want to switch between them, you need to manually remove the `build/` directory before running `pip install`. + software_architecture + example_applications diff --git a/doc/software_architecture.rst b/doc/software_architecture.rst new file mode 100644 index 0000000..e69de29 diff --git a/examples/joint_teleop.py b/examples/joint_teleop.py index cc176ba..a762055 100644 --- a/examples/joint_teleop.py +++ b/examples/joint_teleop.py @@ -1,10 +1,10 @@ +import argparse import sys -# PyGame: https://www.pygame.org/news -import pygame - # FRI Client: https://github.com/cmower/FRI-Client-SDK_Python import pyfri as fri +# PyGame: https://www.pygame.org/news +import pygame pygame.init()