From 4e33c3613d93ab1146946af16efe35d1c18997d8 Mon Sep 17 00:00:00 2001
From: m-guberina <gubi.guberina@gmail.com>
Date: Tue, 24 Sep 2024 12:18:46 +0200
Subject: [PATCH] more docs
---
TODOS_2024_09_19 | 6 +-
docs/bash_cli_basics.md | 10 +++
docs/collaborative_manipulators_general.md | 4 +-
docs/installing_ubuntu.md | 71 +++++++++++++++---
docs/python.md | 56 ++++++++++++++
{simulation => ur_simulator}/Dockerfile | 0
.../external_control.urscript | 0
.../externalcontrol-1.0.5.jar | Bin
.../externalcontrol-1.0.5.urcap | Bin
9 files changed, 135 insertions(+), 12 deletions(-)
create mode 100644 docs/bash_cli_basics.md
create mode 100644 docs/python.md
rename {simulation => ur_simulator}/Dockerfile (100%)
rename {simulation => ur_simulator}/external_control.urscript (100%)
rename {simulation => ur_simulator}/externalcontrol-1.0.5.jar (100%)
rename {simulation => ur_simulator}/externalcontrol-1.0.5.urcap (100%)
diff --git a/TODOS_2024_09_19 b/TODOS_2024_09_19
index fb31c5e..855cc50 100644
--- a/TODOS_2024_09_19
+++ b/TODOS_2024_09_19
@@ -6,7 +6,11 @@ goal 1: ease of use
make a docker image installing everything
1. get clik with visualization to work in a ubuntu22 docker
2. write down the installation process in a Dockerfile
-3. create a single loadable docker image however you can
+3. make the container more user friendly:
+ --> use build-user.sh from markus' ros-containers repo to create a user
+ --> folder with some basic goodies like a .bashrc or .zshrc
+ --> some text editor, preferably some bs gui thing
+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
diff --git a/docs/bash_cli_basics.md b/docs/bash_cli_basics.md
new file mode 100644
index 0000000..d45c95e
--- /dev/null
+++ b/docs/bash_cli_basics.md
@@ -0,0 +1,10 @@
+## 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]
diff --git a/docs/collaborative_manipulators_general.md b/docs/collaborative_manipulators_general.md
index 4e02c00..69148e0 100644
--- a/docs/collaborative_manipulators_general.md
+++ b/docs/collaborative_manipulators_general.md
@@ -1,4 +1,4 @@
## what is a robotic manipulator?
-TODO explain basic theory here
-also add a video explanation
+read bjorn's lectures and take the safety course
+
diff --git a/docs/installing_ubuntu.md b/docs/installing_ubuntu.md
index 2a0a264..bf06533 100644
--- a/docs/installing_ubuntu.md
+++ b/docs/installing_ubuntu.md
@@ -1,15 +1,68 @@
-## general ubuntu installation steps
-Install Ubuntu 22 LTS
+## 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
+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.
+After installing Docker, navigate to this project's directory in your CLI.
+Then:
+1. build the image with "docker build -t ur_simple_control ."
+TODO: add volume mounting (copy Marcus' approach with a user and /home/user/) and networking (put it to host)
+2. run the image with "docker run --rm -it --user root ur_simple_control"
+
+#### option 2) Native installation
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.
4. Enter BIOS to ensure you can boot from your USB. Ideally this step should just be to enable Boot menu, but this step is dependent to a specific computer. Any reasonable Ubuntu (or any Linux) installation guide should have detailed steps, but also consult your laptop manufacturer websites for BIOS steps if the steps won't be obvious/easy to follow.
5. Boot from the Ubuntu USB and install it to the partition/external disk from step 1. MAKE SURE you are installing to the right partition. To select the partition, select the "Advanced installation" option (selecting the partition is the only advanced thing you need). Otherwise just follow the installation instructions you get once you boot into the USB, they are quite well done.
-## 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
diff --git a/docs/python.md b/docs/python.md
new file mode 100644
index 0000000..081cee2
--- /dev/null
+++ b/docs/python.md
@@ -0,0 +1,56 @@
+## 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.
diff --git a/simulation/Dockerfile b/ur_simulator/Dockerfile
similarity index 100%
rename from simulation/Dockerfile
rename to ur_simulator/Dockerfile
diff --git a/simulation/external_control.urscript b/ur_simulator/external_control.urscript
similarity index 100%
rename from simulation/external_control.urscript
rename to ur_simulator/external_control.urscript
diff --git a/simulation/externalcontrol-1.0.5.jar b/ur_simulator/externalcontrol-1.0.5.jar
similarity index 100%
rename from simulation/externalcontrol-1.0.5.jar
rename to ur_simulator/externalcontrol-1.0.5.jar
diff --git a/simulation/externalcontrol-1.0.5.urcap b/ur_simulator/externalcontrol-1.0.5.urcap
similarity index 100%
rename from simulation/externalcontrol-1.0.5.urcap
rename to ur_simulator/externalcontrol-1.0.5.urcap
--
GitLab