Skip to content
Snippets Groups Projects
Commit 91e13668 authored by m-guberina's avatar m-guberina
Browse files

documentation for just the library and its installation, and the tutorials... 

documentation for just the library and its installation, and the tutorials have been separated. it should be easy to use now
parent 0f692e2c
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
README.md
+ 65
− 57
View file @ 91e13668
# do this everytime you use this repo
# general info
-------------
[comment]: <> (- do git stash)
- and then git pull
This is a software library for robot manipulator control.
Its existance serves two main goals:
1. to speed up the development, testing and deployment
of new model-based control techniques
2. to provide the introductory robot control software stack for
engineers and engineering students
These goals are achieved through the following.
Its is designed to be as simple as possible, both in terms of logic
and the total amount of code. Its skeleton provides only a common
interface to both real and simulated robots,
and a wrapper around control loops to be written by the users.
It also provides basic control examples like inverse kinematics
point to point motion, which serve both as usage examples,
and as basic building blocks for higher level control.
# general info
-------------
Here is some basic technical information:
- code is developed on Arch Linux, also tested on Ubuntu 22, should work on any Linux
- code is written in Python, will be re-written in C++ with Python bindings in the future
- all of the library code is written in C++ with Python bindings
- all of the robotics-related libraries are written in C++ with Python bindings
- ur_rtde
- pinocchio
- crocoddyl in the future
- matrix operations are done with Eigen in C++, and NumPy in Python
- crocoddyl (will be added in the near future)
- if installing on own system install the latest python dependencies and it should work
- currently only support UR5e, porting to YuMi and Panda is ongoing work
- robot models are loaded via URDF
- porting to new robots requires providing an interface to the robot (socket with a protocol)
which contains functions for reading of the robot's state (joint positions, velocities, f/t sensor as vectors)
and functions to send control inputs (joint velocities)
- extensions for torque-controlled robots are ongoing
- RobotManager will be turned into a base class from each robot type will inherit,
overriding functions as necessary to accomodate different interfaces
while keeping code readable
# libraries used and their purpose
-----------------------------------
- ur_rtde for the client-side real-time interface for ur robots (we have a UR5e), will expand for other robots in the future
- pinocchio for robot dynamics calculations
- meshcat for visualization (has nice integration with pinocchio)
- crocoddyl for optimal control
- Dockerized ur simulator as a simulator (it's a bad simulator, but it uses the same robot-communication API
as the real robot, making coding and testing easier)
- Docker is used for shipping
# contents of this repository
---------------------------------
- basic documentation can be found in the docs directory: official UR documentation on the robot's capabilities
and its interface, short instructions on installing Ubuntu, ur_rtde, pinocchio, gepetto and the simulator
- basic closed-loop inverse kinematics control is implemented in both C++ and python. the C++ version
uses exponential coordinates and the Lie group formalism, while the Python version uses homogenious
transformations and basic matrix operations
- robot description files: urdf containing both the arm and the gripper, and other urdf-related files
## example usage
----------------
In the examples directory.
## the library
--------------------------------
- ur_simple_control package in python/ur_simple_control, core functionality in managers.py
- robot description files in python/ur_simple_control/robot_descriptions :
- UR5e with Robotiq Hand-e gripper: urdf containing both the arm and the gripper, and other urdf-related files
- some basic controllers in python/ur_simple_control/basics
- clik and extensions in python/ur_simple_control/clik
- dmp in python/ur_simple_control/dmp
- more algorithms will be added over time
- documentation will be expanded according to demand
- visualization in python/ur_simple_control/visualize
- some basic tests will be here as well, while full projects built on this repo will be in separate repos
# installation and operating instructions
------------------------------------------
For all of the listed items, consult their specific documentation in the docs folder, and do your own googling.
Note that for most items you can install through the ubuntu package manager apt, or through the python
package manager pip. Likewise, you can compile the libraries and install from local files. Both options
are OK, just make sure to select a stable release for local compilation (just in case).
All compilation is standard the standard cmake-make combo:
mkdir build && cd build && cmake .. && make , followed by sudo make install to install.
Most likely you can just copy-paste the commands given in the library docs to install. If not,
and you can't fix it yourself in a reasonable amount of time, send an email.
It's highly recommended that you download the source code of these libraries so that you have access to it,
and their examples. Looking around and running these examples is the best way to a) verify installation
and b) get to know the libraries. Of course also follow this up with reading on their documentation.
## documentation
------------------------
- tutorials on linux, python and the library are in [tutorials repository](https://gitlab.control.lth.se/marko-g/LPR-tutorials)
- basic documentation can be found in the docs directory
- links to and basic information about the external resources are listed in the docs directory:
- official UR documentation on the robot's capabilities and its interface
- ur_rtde
- pinocchio
- short instructions on installing Ubuntu and the project Docker image
- code is well documented and short and simple enough to be simple read to be understood
- documentation will be expanded according to demand
Here is a checklist of what to do together with the key remarks.
- install ubuntu either on metal, i.e. do a real install on your machine, or build the provided docker image (on windows use wsl),
or compile all the libraries on windows or something else, but in that case proceed at your own risk and with no support
if installing on metal:
- install ur_rtde https://gitlab.com/sdurobotics/ur_rtde
- install pinocchio: https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/index.html ,
https://stack-of-tasks.github.io/pinocchio/download.html , https://github.com/stack-of-tasks/pinocchio .
# libraries used and their purpose
-----------------------------------
- usual python libraries: numpy, matplotlib, tkinter (needed just for some of the visualization)
- ur_rtde for the client-side real-time interface for Universal Robots robots (only UR5e is tested atm)
- pinocchio for robot dynamics calculations
- meshcat for visualization (has nice integration with pinocchio)
- crocoddyl for optimal control
- qpsolvers and ecos for QP formulation of IK
- Dockerized ur simulator as a simulator -DOES NOT WORK ATM (it's a bad simulator, but it uses the same robot-communication API
as the real robot, making coding and testing easier)
- Docker is used for shipping
## simulation
--------------
- use the --pinocchio-only argument to integrate the dynamics. if you want to add external disturbances,
put them into the kinematics/dynamics equations
- alternatively build the docker image of the simulator (Dockerfile is in the ur_simulator directory).
use the --simulation argument. go to
the local website to see the teacher pendant emulation and put 127.0.0.1 as the ip,
and see whether the code works. the simulator accepts the same commands as the robot.
the only TODO is to add the gripper to the simulator somehow, but you can also just
skip using it when simulating.
## connecting to the real robot
-------------------------------
......@@ -83,7 +92,6 @@ if installing on metal:
- instead of using a debug argument and ifs for prints, use built-in python logging
- implement and test other inverse kinematics algorithms
- use pyproject.toml for python packaging. it actually brakes the current local install so it is avoided for now.
- write all code in c++, make python bindings with pybind. have common documentation
and examples
- write all code in c++, make python bindings with pybind. have common documentation and examples
- do the documentation with doxygen so that you get webpages from markdown as well
- create a DMP from multiple trajectories (actually learn a DMP from multiple examples)
TODOS_2024_09_19
+ 2
− 38
View file @ 91e13668
the primary goal is to make this as easy to use as possible,
and that means a docker image that just needs to be built.
goal 1: ease of use
-----------------------
make a docker image installing everything
1. get clik with visualization to work in a ubuntu22 docker - DONE
2. write down the installation process in a Dockerfile - DONE
3. make the container more user friendly: - DONE
--> use build-user.sh from markus' ros-containers repo to create a user - DONE
--> folder with some basic goodies like a .bashrc or .zshrc - DONE
--> some text editor, preferably some bs gui thing - will just use vim instead
4. create a single loadable docker image however you can
the secondary goal is to re-do the documentation and
add the tutorials going from basic linux to python to
to minimal robotics to the library itself.
to make this less painful clean up the code first.
then just do the pareto optimal code rewrite to make it cleaner
(actually call everything in the step function, maybe finish logging and that's it)
goal 2: clean up the code
---------------------------
1. do all reading and updating into the local class in the step() function --> remove the rest - DONE
1. test to see everything works
2. fix logging a bit (add a function which combines logs of different runs
of a 'session' or at least names all logs in a run)
3. stop doing minor bs asap
4. merge to main
then finish goal 2 by making the docs & tutorialss
goal 3: documentation and tutorials
-----------------------------------
1. documents in text (md/tex) which at least outline the minimal amount of knowledge
2. linux cli video tutorials
2. python essentials video tutorials + some tips on how to learn it quicker (use shell etc)
3. ur_simple_control_library video tutorials, ex. example write circle tracking
set yourself up for research success by using crocoddyl on the real robot,
i.e. get some experience with the basics with the bonus being you can trust
ik not to hit the table
3. use python's logging instead of printing
goal 4: more controllers
------------------------
......
docs/bash_cli_basics.md deleted 100644 → 0
+ 0
− 18
View file @ 0f692e2c
## most basic CLI commands
1. sudo - run the actual command after it as administrator
(need to ex. install stuff)
2. apt - this is Ubuntu's package manager.
It allows you to install nearly everything you'll ever need and manages (nearly)
all installed programs in general. Note: on Linux you go to your package manager
to install most things, you very rarely need to go to websites and download things
(apt does all of it for you from Ubuntu's servers)
3. apt update - update your machine to programs (also called packages) from Ubuntu's serves
4. apt install [package_name] - installs [package_name]
5. ls - list stuff in a folder (also known as directory)
6. cd - change directory (i.e. change folder).
Sometimes you need to run commands from specific folders
(you need to pass a file as input for example).
It's like clicking on folders' icons, but in the terminal
7. python [python_scripy.py] - run a python script
8. man [command] - open manual for command [command]
9. [command] --help - get the help text for command [command]
docs/installing_ubuntu.md → docs/installation.md
+ 39
− 0
View file @ 91e13668
## why do you need to be bothered by software?
The core of robotics is mathematics. However,
to get a robot to move, this math needs to be implemented
on a computer. Furthermore, it needs to be implemented
well because the computations need to done in real time.
Finally, a robot has many different parts, and all of them,
from low-level motor control to image processing have become
software to become real.
Depending on robotic system, the whole software stack can
get incredibly complex.
This means that anyone programming a robot
needs to have at least some knowledge of software engineering competence.
This library is designed for simple control stacks on robotic manipulators
and tries to expose the mathematics as much as possible while minimizing
the amount of software abstractions.
In other words, it is aimed at control engineers who want to
experiment and quickly prototype, and is of limited use otherwise.
Nevertheless, some knowledge of the remaining software stack is unavoidable.
## why gnu/linux?
It is the operating system made by programmers for programmers.
There is a rich history going back to early computers and UNIX, but
a better story is how the development of the Linux kernel started.
In the early 90s Linus Torvalds had issues using a printer.
He fixed them by writing a driver for the printer. Many drivers later,
he began developing software to manage all hardware resources,
memory allocation, process scheduling,... This software is called the kernel,
and it constitutes the most important part of an OS.
The project got too big for a single person. A world-wide
distributed team of volunteers soon started contributing to the project
and the rest is history.
Today, GNU/Linux is primary OS on servers, mobile phones, embedded devices
and in robotics.
The open-source nature of the OS makes it possible to know what
is going on "under the hood", and, as mentioned,
this is a necessity in robotics.
Additionally, it is incredibly extensible and customizable.
All this makes it the ideal choice for the particular needs of robotics.
NOTE: we will not even attempt to use software with real-time guarantees.
This makes all our programs inherently unpredictable due to the lack
of hard real-time execution guarantees.
However, this has not yet caused a problem for our purposes.
Furthermore, since we are only building experimental set-ups,
not fully autonomous solutions, unpredictable behavior caused by
programming mistakes is what we really need to worry about.
## ubuntu installation steps
#### option 1) Docker
## Docker
----------
In the interest of time, the library is shipped as a Docker image.
To oversimplify, Docker is virtualisation software which allows
one to programatically set up a Linux virtual machine.
A virtual machine is a emulation of a full computer, and it runs similarly to other
programs on the host machine (your computer and its OS).
By default, the virtual machine has no information about the host machine - it is as if
you had a different computer sitting on your desk. For our purposes, some sharing will be necessary.
This includes things like internet access and sharing of files and folders.
A docker image is specification of a virtual machine,
while a docker container is an instance of that machine (similar to classes and objects
in programming). You can have multiple containers running the same image.
A Dockerfile is a specific kind of file where a Docker image is defined.
The Dockerfile provided in this repository will create an image with all the software
needed to simulate and use the UR robot.
If you want to install additional software within your Docker, you will need to either update
the Dockerfile and re-build the image, or use a persistent container, otherwise
all of the installed software will be deleted when you close the container
(as it happens on university computers). More on that later.
Here are the steps to get to your container running:
Installing docker on windows:
1. install wsl with "wsl --install" in powershell administrator, more at https://learn.microsoft.com/en-us/windows/wsl/install
2. install docker on windows (with wsl option, should be default)
3. create the docker accout
4. open docker desktop, navigate to Settings (by user/account button) -> Resources -> Network -> click on enable host networking
5. open wsl (type wsl in powershell) and navigate to git folder (now in wsl) with "cd /mnt/Users/YOURUSERNAME/PATH_TO_GIT_FOLDER"
Here are the steps to get to your container running once Docker is installed
6. build the image with "docker build -t ur_simple_control ."
7. to run the image FIRST RUN "xhost +" EVERY TIME, THEN RUN "docker run --rm -it --net=host -e DISPLAY=$DISPLAY -v /tmp:/tmp ur_simple_control /bin/zsh"
8. verify installation by running an example with --visualize-manipulator and --real-time-plotting arguments
......@@ -84,7 +18,8 @@ Here are the steps to get to your container running:
in particular, use -v [path_to_folder_on_host]:[path_to_that_folder_in_docker_container]:rw .
notice the :rw at the end. this allows for both the host and the container to modify the files (otherwise they will be read-only).
##### Installing additional software on the image
### Installing additional software on the image
-------------------------------------------------
Install things as you would normally (using apt in the terminal etc).
To get this to be a part of the Docker image, just use
the RUN [...] command in the Dockerfile, where you replace [...] with the
......@@ -94,7 +29,8 @@ I highly recommend adding software this way, because
it will allow you to share the exact same set-up between your colleagues,
which will help you avoid headaches in the future.
#### option 2) Native installation
## Native installation (installing ubuntu)
----------------------------------------------
1. Either create a disk partition for Ubuntu on your hard drive, or use an external hard drive. In the first case, you might need to shrink your existing partition. Searching for "how to create a disk partition [your_OS]" or "install ubuntu on [your_OS]" will get you all the information you need. Ideally, back up your data before any of this (you should be doing this in general as it's good practice).
2. Download an Ubuntu 22 LTH iso (file which contains everything needed for installation), available at official Ubuntu websites
3. Create a bootable USB. In short, you can't just copy an iso file to a USB and boot from it. Just google how to do it on your OS (use rufus if on windows).
......
docs/pinocchio.md
+ 23
− 18
View file @ 91e13668
# general documentation
https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/index.html
# pinocchio
-------------
pinocchio has functions with some advanced math, like Lie groups. while it's
certainly a plus to learn them, you don't need to. you can just use the forward
kinematics and calculating jacobian functions, and do ther rest of the math
with eigen or numpy.
# installation procedure
just follow the steps (copy-paste commands into terminal) listed here
https://stack-of-tasks.github.io/pinocchio/download.html
## general documentation
-------------------------------
[pinocchio documentation](https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/index.html)
# nice exercises to get yourself familiarized
https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/md_doc_d-practical-exercises_intro.html
pinocchio has functions with some advanced math, like Lie groups.
while it's certainly a plus to learn them, you don't need to. you can just use the forward kinematics
and calculating jacobian functions, and do ther rest of the math with eigen or numpy.
## native installation procedure
-------------------------------
just follow the steps (copy-paste commands into terminal) listed
[here](https://stack-of-tasks.github.io/pinocchio/download.html) .
NOTE: if using own compilation of pinocchio, make sure you compile with mpi
and whatever else is needed to run algorithms in parallel.
you won't be able to run in 500Hz on a single core. also note that
the compilation required 13GB of RAM on my system.
## tutorials
-------------------------------
- [probably the best introduction to pinocchio](https://github.com/ymontmarin/_tps_robotique)
- [pinocchio with casadi](https://github.com/nmansard/jnrh2023) - use the provided Docker, very difficult to install the exact software version used in the tutorial
- [exercises offered on documentation webstite](https://gepettoweb.laas.fr/doc/stack-of-tasks/pinocchio/master/doxygen-html/md_doc_d-practical-exercises_intro.html)
# how to learn how to use pinocchio?
follow exercises and tutorials from the pinocchio documentation webiste, play around with it in ipython3 (a nicer
shell than plain python, install with sudo apt-get install ipython3)
## NOTE
--------
if using own compilation of pinocchio, make sure you compile with mpi
and whatever else is needed to run algorithms in parallel.
you won't be able to run in 500Hz otherwise
docs/python.md deleted 100644 → 0
+ 0
− 56
View file @ 0f692e2c
## python general
Easiest possible language to use. Trades off
execution speed for ease of use.
Indentation has programatic meaning.
### variables
Any variable in Python can store any type.
The comperhensive list of types can be found at [link_to_structs_in_standard_lib]
Here is a very short list of basic facts:
- all variables are variable/dynamic
- a variable ONLY POINTS TO A LIST, and assigning it to a different variable
DOES NOT COPY THE LIST by default
### data structures
There are a number of built-in data structures in Python.
The comperhensive list of built-in data structures can be found at [link_to_structs_in_standard_lib]
#### lists
- look like [item_1, item_2,...]
- all lists are mutable (changeable)
- you can put anything in a list, i.e. item_n can be of any type
in any list (including other lists)
#### dictionaries
- look like {key_1 : value_1, key_2: value_2, ...}
- all dictionaries are mutable (changeable)
- you can put anything in a dictionary
### loops
Repeat a block of code. They can be prematurely
stopped with break .
A chunk of code can be skipped with continue .
#### for loop
goes over an iterator. That could be
a sequence of numbers like range(n),
but also elements of list or dictionary etc.
[syntax]
#### while loop
runs as long as the logical requirement is met
while test_true:
[code]
### functions
A function is a chunk of code to be easily accessed in multiple different places.
To be used somewhere else, its inputs and the outputs need to be matched
by the calling code.
NOTE: this is not strictly enforced in Python. BE CAREFUL because
if you don't put in what you think you're putting in,
the code will run and you will get VERY WEIRD ERRORS.
def something(arguments):
[code]
return [any_variable]
### classes
Classes are collections of variables and functions
that help us organize our code.
docs/robotics_math.md
+ 6
− 3
View file @ 91e13668
# general notes
## general notes
---------------------
You do not need to know most topics in the books listed below, but it's good
to have them as references and to look up the specific topics you are
working with. We will rely on the Pinocchio library for robotics-related
......@@ -8,14 +9,16 @@ know homogenious transformations, and have a good idea of
what the used equations mean (what are you calculating
and from what).
# classic approach
## classic approach
-----------------------
probably the best reference textbook:
Bruno Siciliano, Lorenzo Sciavicco, Luigi Villani, Giuseppe Oriolo (auth.) - Robotics_ Modelling, Planning and Control.
the only prerequisites are linear algebra, calculus and basic control (up to SISO PID control).
If you took the Applied robotics course, this book builds on what has been laid out there.
While easy to get started with, this approach may result in some cumbersome expressions.
# Lie group approach
## Lie group approach
-----------------------------
The idea here is to treat rigid motions and transformations as (mathematical) groups.
While it is certainly not necessary to use this approach,
it sheds light on the expressions which appear in robotics, and results
......
docs/simulation.md
+ 13
− 7
View file @ 91e13668
## numerical simulation
-----------------------
- use the --pinocchio-only argument to numerically integrate the dynamics
without sending any commands
- if you want to simulate external disturbances, put them into the kinematics/dynamics equations (create a new control loop with this)
## using ur_sim (BROKEN ATM)
-----------------------------
1. install docker (sudo apt-get install docker)
2. have a look at docker documentation to have an idea of what it is and for any additional information
as it's very well made
3. navigate to the the simulation folder of this repo
4. run "docker build -t myursim -f Dockerfile ." to crete the image
5. to run the image, run "docker run --rm -it --net=host myursim" . the --rm flag removes the previous container,
-it attaches the terminal to the containter, and --net=host makes the image share the localhost
connection with your OS.
6. go to http://127.0.1.1:6080/vnc.html?host=127.0.1.1&port=6080, go to the installation tab and change
the settings (IP addresses) of the external_control urcap in the URCaps tab. change the Host IP to
127.0.0.1
5. to run the image, run "docker run --rm -it --net=host myursim" . the --rm flag removes the previous container, -it attaches the terminal to the containter, and --net=host makes the image share the localhost connection with your OS.
6. go to http://127.0.1.1:6080/vnc.html?host=127.0.1.1&port=6080, go to the installation tab and change the settings (IP addresses) of the external_control urcap in the URCaps tab. change the Host IP to 127.0.0.1
7. go to the program tab, and put external control as a part of the program (the only part after main)
8. now run your program as if it was running on real hardware with a TODO being that there is no gripper in the simulation as of yet
8. now run your program as if it was running on real hardware use the --simulation flag, but NOTE: that there is no gripper in the simulation
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment