Overview and software installation

Overview

pam robot

PAM robot (Pneumatic Artificial Muscle robot) is a four degrees of freedom robot. Most of the days, we have it learning how to play tennis table. But it could be used for other purposes, e.g. exploring the control of artificial muscles.

It is controlled via the value of pressures of its 8 artificial muscles. Each joint is connected to 2 artificial muscles, called agonist and antagonist. If the pressure of the agonist is higher than the pressure of the antagonist (i.e. the agonist is more contracted than the antagonist), the joint moves left. A control command consists of setting the pressure(s) of one (or more) muscle(s).

We developed some software allowing for the control of the robot (or a MuJoCo simulated version of it). The software allows to send commands related to the desired pressures to the robot, as well as accessing the current and past states of the robot. The software is written in C++ and has Python wrappers (and has been tested only on Ubuntu).

Once the software installed, the typical workflow starts with calling in a terminal:

For starting the real robot:

o80_pam

For starting a simulated robot:

pam_mujoco mujoco_id
# arbritrary_id is an arbitrary string used
# to distinguish between all the simulated robots
# that may run in parallel

The command above spawns a “backend” process which connects to the robot. This process reads continuously (i.e. at a frequency of 200Hz or more) the state of the robot and writes it in a shared memory. Also, it reads the shared memory for commands to apply to the robot.

User may then use a Python (or a C++) API for interacting with the shared memory, i.e. reading the state of the robot (written by the backend) or writing commands to it (which will then be read by the backend and applied to the robot).

There are quite a few types of commands that can be written in the shared memory. The system is based on o80, and it is advised to read o80’s documentation before going further.

Software installation

Installing the software will results in:

  • having some executables installed on your system (e.g. ‘o80_pam’ or ‘pam_mujoco’ already mentioned above)

  • having some Python packages installed

  • useful for advanced users: some C++ libraries installed

The executables will be used to start the backend connecting to the robot, while the Python packages can be used for developers to create control scripts that send commands to the backend (via the shared memory) and/or read states of the robot (also via the shared memory).

Using the installation script

Requirements

  • recommanded: activate a dedicated python virtual environment

  • install the development package of the python version you use, e.g. sudo apt install python3.9-dev

  • upgrade pip to latest version: pip install --upgrade pip

Steps

  • clone https://github.com/intelligent-soft-robots/hysr

  • pip install (cd hysr && pip install .)

  • run in a terminal hysr_pam_install. This will prompt you for your (sudo) password. Sudo rights are required by the script because it installs some dependencies using apt.

  • open a new terminal. Running for example o80_dummy should work. import pam_mujoco in python code should also work.

Via colcon workspace

This is the recommended way for developers of the PAM software (as opposed to the users of it).

Colcon is the built system of ROS2. The instructions below will result in the setup of a colcon workspace. Possibly, if you would like to use o80 in a ROS2 project, you may copy the cloned packages to an existing workspace.

Adding your SSH key to github

See: github documentation.

All the following instructions assume your SSH key has been activated, i.e.:

# replace id_rsa by your key file name
ssh-add ~/.ssh/id_rsa

  • You must first register your SSH key to Github. See instructions here

  • treep is likely to be already installed on your machine. If not:

pip install treep

Dependencies and configuration folder

in a terminal:

mkdir /tmp/pam && cd /tmp/pam
wget http://people.tuebingen.mpg.de/mpi-is-software/pam/resources/apt-dependencies
wget http://people.tuebingen.mpg.de/mpi-is-software/pam/resources/pip3-dependencies
chmod +x ./apt-dependencies
chmod +x ./pip3-dependencies
sudo ./apt-dependencies
./pip3-dependencies

Cloning the repositories

Creating a folder and cloning the treep configuration:

mkdir Software # you may use another folder name
cd Software
git clone git@github.com:intelligent-soft-robots/treep_isr.git

Cloning all the required repositories:

treep --clone PAM_MUJOCO

Compilation

cd /path/to/Software
cd workspace
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release -DPYBIND11_TEST=OFF --no-warn-unused-cli

This will result in a “install” folder containing the compiled binaries

Activating the workspace

In each new terminal, the workspace needs to be sourced:

source /path/to/Software/workspace/install/setup.bash

Note

Possibly, you may want to add the line above to the ~/.bashrc file (so that each new terminal source the workspace automatically).

Checking things are ok

In a python3 terminal:

import o80
import o80_pam
import pam_mujoco
import context

You may also try in a terminal:

pam_mujoco test