1 TIAGo Base handbook

2 Package content

2.1 Overview

This section includes a list of items and accessories that come with TIAGo Base . Make sure you can find all of them:

_images/package_base.png

Figure: Components inside transportation box



3 Specifications

3.1 Overview

TIAGo Base is provided with a differential drive mechanism and contains an onboard computer, batteries, power connector, laser-range finder, three rear sonars, a user panel, a service panel and two WiFi networks to ensure wireless connectivity. Furthermore, the version of TIAGo Base with a docking station has a charging plate on the front.

_images/Mobile_base_frontal.png

Figure: PMB2 Mobile base

_images/rear_base.png

Figure: Mobile base rear view

3.2 Overall dimensions

  • Height: ~300mm

  • Diameter: ~540mm

3.3 Weight

The total weight of TIAGo Base is about 40 kg, including batteries.

3.4 Payload

TIAGo Base has a payload of up to 100kg.

3.5 User panel

The TIAGo Base may come with a panel featuring an electric switch or a key lock.

_images/user_panel_without_key.png

Figure: User panel featuring an electric switch


_images/user_panel_with_key.png

Figure: User panel featuring a key lock


User Panel description

Number

Name / Short description

1

Emergency stop

2

Information display

3

On / Off button

4

Electric switch / key lock

3.5.1 Electric switch

The electric switch is the main power control switch. Note that this switch should not be turned OFF before using the On/Off button to turn OFF the onboard computer of the robot. Turning OFF this switch will cut instantaneously the power supply to all the robot components, including the onboard computer. Before turning TIAGo Base ON make sure first that this switch is ON.

3.5.2 Key lock

This is the main power control switch. When TIAGo Base is not going to be used for a long period of time, please turn off the power by selecting OFF position (Figure: Electric key positions).

_images/electric_key_positions.png

Figure: Electric key positions

3.5.3 Emergency stop

When pushed, motors are stopped and disconnected. Green indicator will blink fast in order to notify the emergency state.

To start the normal behaviour again, a two step validation must be executed: emergency button must be released rotating clockwise, and then On/On button must be pressed for 1 second. The green light will change to fixed state.

3.5.4 Information display

320x240 Color TFT display that shows battery level on the top-right corner.

3.5.5 On / Off button

Standby control button. It is a push button with a green light to indicate the current system status.

Green light indicator possible modes

Light

State

Name / Short description

Off

Fixed

Standby

On

Fixed

Running

On

Slow-Blink

System in process of shutdown

On

Fast-Blink

Emergency state

After main power is connected, i.e. electric switch is ON (Figure: User Panel), user must press this button during 1 second in order to start the TIAGo Base.

To set again the system in standby mode when is running, press again the button. The green light will blink slowly during shut down procedure and light-off when standby mode reached.

3.6 Expansion Panel

_images/expansion_panel_v2.png

Figure: Expansion panel (this may be subject of small variations depending on version)


Expansion panel description

Number

Name / Short description

1

USB 2.0

2

USB 2.0

3

USB 2.0

4

Speaker

5

Power expansion

6

Communications expansion

7

GPIOs

8

USB 3.0

9

USB 3.0

10

USB 3.0

11

GbE port

12

GbE port / External port

To access the expansion panel the front part of the top metal cover should be removed, as shown in the figure below.

_images/Acces_expansion.png

Figure: Accessing the expansion panel


3.6.1 Speaker connector

This expansion connector provides amplified audio output of RIGHT audio channel. Output power is 8 W max, output impedance is 8 Ohm. It is recommended to use external speaker of 8 Ohm impedance with rated power of 10 W minimum.

Connector type Molex 43020-0200, mating part is Molex 43025-0200.

_images/Ex2_Molex_43020-0200.png

Figure: Speaker connector pinout

Speaker connector pin description

Pin

Name / Short description

1

8 Ohm, 8 W audio output, negative pin

2

8 Ohm, 8 W audio output, positive pin

3.6.2 Power expansion connector

This expansion connector provides access to the battery and provide up to 360 W. Battery voltage can vary depending on actual State Of Charge in the range of 30V to 42V.

It is recommended to use the all 3 battery output pins in parallel to divide current between them. The maximum current that can be provided through these battery pins is 10 A in total, approximately.

Connector type Molex 39012101, mating part is Molex 39012100.

_images/Ex6_Molex_39012101.png

Figure: Power expansion connector pinout


Power expansion connector pin description

Pin

Name / Short description

1

2

+12V output (max 4.5A shared with SICK Laser if present)

3

Battery output (max 9A/pin)

4

Battery output (max 9A/pin)

5

Battery output (max 9A/pin)

6

7

GND of 12V output

8

Battery GND

9

Battery GND

10

Battery GND

3.6.3 Communications expansion connector

This expansion connector provides access to internal communication buses of the robot. There are 2 CAN buses for motors and actuators and a propietary bus for sensors. Only the CAN buses are available to the user. CAN bus speed is 1Mbit/s.

Connector type Molex 43020-1400, mating part is Molex 43025-1400.

_images/Ex7_Molex_43020-1400.png

Figure: Communication expansion connector pinout

Communication expansion pin description

Number

Name / Short description

1

CANL of LEFT bus

2

Shield of LEFT bus

3

CANH of LEFT bus

4

reserved

5

reserved

6

reserved

7

n.c.

8

CANL of RIGHT bus

9

Shield of RIGHT bus

10

CANH of RIGHT bus

11

n.c.

12

n.c.

13

n.c.

14

n.c.

3.6.4 GPIOs connector

This expansion connector provides access to General Purpose Input (GPI) and Output (GPO) pins.

Connector type Molex 43020-1600, mating part is Molex 43025-1600.

_images/Ex8_Molex_43020-1600.png

Figure: GPIOs connector pinout


GPIOs connector pin description

Number

Name / Short description

1

2

3

4

+5V

5

GPO 0 (5V TTL level)

6

GPO 1 (5V TTL level)

7

GPO 2 (5V TTL level)

8

GPO 3 (5V TTL level)

9

10

11

12

GND

13

GPI 0 (5V TTL level)

14

GPI 1 (5V TTL level)

15

GPI 2 (5V TTL level)

16

GPI 3 (5V TTL level)

General purpose outputs are referenced to pin 12 GND and by default are set to low level. On the other hand, general purpose inputs must be set using pin 4 +5V for high level and pin 12 GND for low level, and have an internal default pull-up.

3.7 Expansion Plate

The metal plate on the top of the TIAGo Base could be use for mounting additional componets. The thread distances are shown in Figure: Expansion plate for integration of upper body that will appear in the 3.9   Electrical parts and components section and the screws to use are M4 type.

3.8 Connectivity

TIAGo Base is equipped with a dual band Wireless 802.11b/g/n/ac interface plus Bluethooth 4.0. When theWifi interface is configured as access point it is a 802.11g interface.

There is a Gigabit Ethernet (port 13 in Figure: Expansion panel) that can be configured in order to be used with an external network.

For the internal network of the robot it has been reserved the IP address range 10.68.0.0/24.

The IP addresses used in the building network MUST not use this range because it can interferewith the services of the robot.

3.9 Electrical parts and components

Neither TIAGo Base nor any of its electrical components and mechanical parts are connected to an external ground. The chassis and all electromechanical components of the robot are physically isolated from the environment ground with the isolated rubber under its feet. To avoid any damage in the electromechanical part of TIAGo Base don’t touch any metallic parts directly to avoid discharges.

_images/Expansion_plate.png

Figure: Expansion plate for integration of upper body

Electrical power supply and connectors

The power source supplied with TIAGo Base is compliant with the directive on the restriction of the use of certain hazardous substances in electrical and electronic equipment 2002/95/EC (RoHS) and compliant with the requirements of the applicable EC directives, according to the manufacturer. The power source is connected to the environment ground, whenever the supplied wire is used (Phase-Neutral-Earth).

Battery

The specifications of the battery supplied with TIAGo Base are shown in the table:


Battery specifications

Type

Li-Ion

V_nominal

36.0 V

V_max

42.0 V

V_cutoff

30.0 V

Nominal capacity

20 Ah

Nominal energy

720 Wh

Max. continuous discharge current

20 A

Pulse discharge current

60 A

Max. charging current

15 A

Charging method

CC/CV

Weight

7.5 kg

3.10 Service panel

Removing the cover behind the laser it is possible to access the Service Panel (see figure below).

This service panel gives access to video, usb and on/off button of the computer inside the TIAGo Base. It can be used for reinstallation or debug propouses.

_images/Service_panel.png

Figure: Service panel


Service panel description

Number

Name / Short description

1

USB 3.0

2

On/Off button computer

3

HDMI

3.11 Power Connector

TIAGo Base must be charged only with suplied charger!! To insert the charger connector, open the lid located on the rear part.

_images/powercon_open.png

Figure: Charging connector entry


3.11.1 Connection

Insert charging connector with metal lock facing up, push it until you hear a ’click’.

_images/powercon_connect.png

Figure: Charger connector insertion procedure


3.11.2 Disconnection

Once charge is completed, connector can be removed. In order to do so, press metal lock and pull firmly the connector (see figure below).

_images/powercon_discon.png

Figure: Charger connector removal procedure



4 Transport and Storage

4.1 Overview

Information relating to transport, handling and storage of TIAGo Base will be explained in this section.

4.2 Unpacking

This section explains hoy to unbox TIAGo Base safely. TIAGo Base is shipped in the flightcase shown in the figure below.

_images/flightcase.png

Figure: TIAGo base flightcase

Open the box by removing the lid and superior foam cover. Then pull the robot by lifting from the bottom as shown in Figure: Unboxing of a TIAGo Base. Take care when lifting to grab the robot from underneath, holding it from the metal frame, not just by the plastic cover.

Once the robot has been placed on the ground press gently from the top to ensure that the shock absorbers compress and the robot is level with the ground before turning it on.

5 Storage cautions

  • Always store TIAGo Base in a place where it will not be exposed to weather conditions.

  • The storage temperature range for TIAGo Base is between 0ºC ∼ +60ºC.

  • The storage temperature range for the batteries is between +10ºC ∼ +35ºC.

  • It is recommended to turn completly off (red power button is off) the TIAGo Base when the storage period exceeds two weeks.

  • It is recommended to charge the battery to 50% when storing it for more than two weeks.

  • Avoid the use or presence of water near TIAGo Base.

  • Avoid any generation of dust close to TIAGo Base.

  • Avoid the use or presence of magnetic devices or electromagneticfields near TIAGo Base.

_images/unboxing.png

Figure: Unboxing of a TIAGo Base



6 Introduction to safety

6.1 Overview

Safety is important when working with TIAGo Base. This chapter provides an overview of safety issues, general usage guidelines to support safety, and describes some safety-related design features. Before operating the robot all users must read and understand this chapter!

6.2 Intended applications

It is important to clarify the intended usage of the robot before any kind of operation.

TIAGo Base is a robotics research and development platform meant to be operated in a controlled environment under supervision by trained staff at all time.

  • The hardware and software of TIAGo Base allows to research and develop activities in the following areas:

    • Navigation and SLAM

    • Speech recognition

    • Human-robot interaction

6.3 Working environment and usage guidelines

The working temperatures are:

  • Robot: +10ºC ~ +35ºC

The space where TIAGo Base operates should have a flat floor and be free of hazards. Specifically, stair-ways and other drop offs can pose an extreme danger. Avoid sharp objects (such as knives), sources of fire, hazardous chemicals, or furniture that could be knocked over.

Maintain a safe environment:

  • The terrain for TIAGo Base usage must be capable of supporting the weight of the robot (see Specifications section). It must be horizontal and flat. Do not use any carpet, to avoid tripping over.

  • Make sure the robot has adequate space for any expected or unexpected operation.

  • Make sure the environment is free of objects that could pose a risk if knocked, hit, or otherwise affected by TIAGo Base.

  • Make sure there are no cables or ropes that could be caught in the covers or wheels; these could pull other objects over.

  • Make sure no animals are near the robot.

  • Be aware of the location of emergency exits and make sure the robot cannot block them.

  • Do not operate the robot outdoors.

  • Keep TIAGo Base away from flames and other heat sources.

  • Do not allow the robot to come in contact with liquids.

  • Avoid dust in the room.

  • Avoid the use or presence of magnetic devices near the robot.

  • Apply extreme caution with children.


6.4 Battery manipulation

The following guidelines must be respected when handling the robot in order to prevent damage to the robot’s internal batteries.

  • Do not expose to fire.

  • Do not expose the battery to water or salt water, or allow the battery to get wet.

  • Do not open or modify the battery case.

  • Do not expose to ambient temperatures above 49ºC for over 24 hours.

  • Do not store in temperatures below -5ºC over seven days.

  • For long term storage (more than 1 month) charge the battery to 50%.

  • Do not use the TIAGo Base’s batteries for other purposes.

  • Do not use other devices but the supplied charger to recharge the battery.

  • Do not drop the batteries.

  • If any damage or leakage is observed, stop using the battery.

7 Safety measures in practice

7.1 Emergency stop

The emergency stop button can be found on the back of the robot between the power button and the battery level display. As the name implies this button may be used only in exceptional cases where the immediate stop of the robot is required.

To activate the emergency stop the user has to push the button. To deactivate the emergency stop the buttonhas to be rotated clockwise according to the indications on the button until it pops out.

  • Pushing the Emergency button turns off the power of the robot. All electronic components of the robot, hardware controllers and computers included will be powered down. Be careful using this emergencystop action because the motors will be switched OFF.

    • After releasing the emergency stop button the user has to start the robot by using the power button.

7.2 Firefighting equipment

For correct use of TIAGo Base in a laboratory or location with safety conditions, it is recommended to have in place a C Class or ABC Class fire extinguisher (based on halogenated products), as these extinguishers are suitable for stifling an electrical fire.

If a fire occurs, please follow these instructions:

  1. Call the firefighters.

  2. Push the emergency stop button, as long as you can do so without any risk.

  3. Only tackle a fire in its very early stages.

  4. Always put your own and others’ safety first.

  5. Upon discovering the fire, immediately raise an alarm.

  6. Make sure the exit remains clear.

  7. Fire extinguishers are only suitable for fighting a fire in its very early stages. Never tackle a fire if it is starting to spread or has spread to other items in the room, or if the room is filling with smoke.

  8. If you cannot stop the fire or if the extinguisher runs out, get yourself and everyone else out of the building immediately, closing all doors behind you as you go. Then ensure the fire brigade are on their way.

7.3 Leakage

The battery is the only component of the robot that is able to leak. To avoid leakage of any substance from the battery, follow the instructions defined in section of 4   Transport and Storage, to ensure the battery is manipulated and used correctly

8 Robot Identification

The robot is identified by a physical label that can be found close to the power connector.

This label contains:

  • Business name and full address.

  • Designation of the machine.

  • Part Number (P.N.).

  • Year of construction.

  • Serial number (S.N.).

_images/LabelIdTiago.png

Figure: Identification label



9 Software recovery

9.1 Overview

This section explains the System and Software reinstall procedure for TIAGo Base.

9.2 Robot computer installation

To begin the installation process, plug a monitor and USB keyboard into the HDMI connector of the user panel.

BIOS configuration: Some options in the Control BIOS computer must be configured as follows:

  • Turn on the robot and press F2 repeatedly. Wait until the BIOS menu appears.

  • In System Performance, select ASUS Optimal.

  • Enter Advance Mode by pressing F7.

  • In the Advanced > CPU Configuration menu:

    • Set Intel Adaptive Thermal Monitor to Disabled

    • Set Intel Virtualization Technology to Disabled.

  • In the Advanced > CPU Configuration > CPU Power Management Configuration menu:

    • Set EIST to Disabled.

    • Set CPU C states to Disabled.

  • In the Boot menu:

    • Set Wait for F1 if error to Disabled.

  • Go to Exit and select Save Changes & Reset.

  • Shut down the robot.

Installation: The installation is performed using the Software USB drive provided with TIAGo Base.

  • Insert the Software USB drive.

  • Turn on the robot and press F2 repeatedly. Wait until the BIOS menu appears.

  • Enter the Boot Menu by pressing F8 and select the Software USB drive.

  • The Language menu will pop up. Select English.

The menu shown in figure below.

  • Select Install TIAGo Base.

  • Select the keyboard layout by following the instructions.

_images/installing.png

Figure: System installation menu


9.3 Development computer installation

Hardware installation: Connect the computer to the electric plug, the mouse and the keyboard. Internet access is not required as the installation is self-contained.

Software Installation: The installation is performed using the Software USB drive provided with TIAGo Base.

  • Insert the Software USB drive.

  • Turn on the computer, access the BIOS and boot the Software USB drive.

  • The Language menu will pop up. Select English.

The menu shown in next figure.

  • Choose Install Development (Advanced) if you wish to select a target partition in the development computer. Using the “Install Development” option will delete all partitions in the disk and automatically install the system in a new partition.

  • Select the keyboard layout by following the instructions.

_images/installing_2.png

Figure: System installation menu



10 Development Computer

10.1 Overview

The operating system used in the SDE Development Computer is based on a Linux Ubuntu distribution. Any documentation related to this specific Linux distribution applies to SDE. This document only points out how the PAL SDE differs from standard Ubuntu.

10.2 Computer requirements

A computer with 8 CPU cores is recommended. A powerful graphics card with resolution of at least 1920x1080 pixels is recommended in order to have a better user experience when using visualization tools like rviz andthe Gazebo simulator. The development computer ISO provides support for Nvidia cards. In case of upgrading the kernel of the development computer PAL Robotics cannot ensure proper support for other graphic cards.

10.3 Setting ROS environment

In order to use the ROS commands and packages provided in the development ISO the following command needs to be executed when opening a new console

# Pal distro environment variable
export PAL_DISTRO=gallium
export ROS_DISTRO=noetic
source /opt/pal/${PAL_DISTRO}/setup.bash

If you are using a ros2 distribution

# Pal distro environment variable
export PAL_DISTRO=alum
export ROS_DISTRO=humble
source /opt/pal/${PAL_DISTRO}/setup.bash

A good way to spare the execution of this command everytime is to append it at the /home/pal/.bashrc file.

10.4 ROS communication with the robot

When developing applications for robots based on ROS, it is typical to have the rosmaster running on the robot’s computer and the development computer running ROS nodes connected to the rosmaster of the robot. This is achieved by setting in each terminal of the development computer running ROS nodes the following environment variable:

export ROS_MASTER_URI=http://pmb2-1c:11311

Note that in order to successfully exchange ROS messages between different computers, each of them needs to be able to resolve the hostname of the others. This means that the robot computer needs to be able to resolve the hostname of any development computer and vice versa. Otherwise, ROS messages will not be properly exchanged and unexpected behavior will occur.

Do the following checks before starting to work with a development computer running ROS nodes that point to the rosmaster of the robot:

ping pmb2-1c

Make sure that the ping command reaches the robot’s computer.

Then do the same from the robot:

ssh pal@pmb2-1c
ping devel_computer_hostname

If ping does not reach the development computer then proceed to add the hostname to the local DNS of the robot, as explained in section 11.3   Internal DNS. Otherwise, you may export the environmental variable ROS_IP - the IP of the development computer that is visible from the robot. For example, if the robot is set as access point and the development computer is connected to it and it has been given IP 10.68.0.128 (use ifconfig to figure it out), use the following command in all terminals used to communicate with the robot:

export ROS_MASTER_URI=http://pmb2-1c:11311
export ROS_IP=10.68.0.128

All ROS commands sent will then use the computer’s IP rather than the hostname.

10.5 Compiling software

The development computer includes the ROS messages, system headers and our C++ open source headers necessary to compile and deploy software to the robot.

Some of the software APIs that we have developed are proprietary, and their headers are not included by default. If you require them you can contact us through our customer service portal and after signing a non disclosure agreement, they will be provided. These APIs are for accessing advanced features not available through a ROS API.

10.6 System Upgrade

In order to upgrade the software of the development computers, you have to use the pal_upgrade_chroot.sh command. Log in as a root and execute:

root@development:~# /opt/pal/${PAL_DISTRO}/lib/pal_debian_utils/pal_upgrade_chroot.sh

Notifications will appear whenever software upgrades are available.

10.7 NTP

Please follow the instructions on the section 11.4   NTP



11 TIAGo Base Robot’s Internal Computers

11.1 TIAGo Base LAN

The name of TIAGo Base’s computer is pmb2-1c, where 1 needs to be replaced by the serial number of your robot. For the sake of clarity, hereafter we will use pmb2-1c to refer to TIAGo Base’s computer name.

In order to connect ot the robot, use ssh as follows:

ssh pal@pmb2-1c

11.2 File system

The TIAGo Base robot’s computer has a protection against power failures that could corrupt the filesystem. These partitions are created:

  • /: This is an union partition, the disk is mounted in /ro directory as read-only and all the changes arestored in RAM. So, all the changes are not persistent between reboots.

  • /home: This partition is read-write. Changes are persistent between reboots.

  • /var/log: This partition is read-write. Changes are persistent between reboots.

In order to work with the filesystem as read-write do the following:

root@pmb2-1c:~# rw
Remounting as rw...
Mounting /ro as read-write
Binding system files...
root@pmb2-1c:~# chroot /ro

rw command remounts all the partitions as read-write. Then with a chroot to /ro we have the same system than the default but all writable. All the changes performed will be persistent.

In order to return to the previous state do the following:

root@pmb2-1c:~# exit
root@pmb2-1c:~# ro
Remount /ro as read only
Unbinding system files

First exit command returns from the chroot. Then the ro script remounts the partitions in the default way.

11.3 Internal DNS

The control computer has a DNS server that is used for the internal LAN of the TIAGo Base with the domain name reem-lan. This DNS server is used by all the computers connected to the LAN.

When a computer is added to the internal LAN (using the Ethernet connector, for example) it can be added to the internal DNS with the command addLocalDns:

root@pmb2-1c:~# addLocalDns -h
-h shows this help
-u DNSNAME dns name to add
-i IP ip address for this name

Example: addLocalDns -u terminal -i 10.68.0.220.

The same command can be used to modify the IP of a name: if the dnsname exists in the local DNS, the IP address is updated.

To remove names in the local DNS, exit the command delLocalDns:

root@pmb2-1c:~# addLocalDns -h
-h        shows this help
-u DNSNAME  dns name to remove

Example: addLocalDns -u terminal

These additions and removals in the local DNS are not persistent between reboots.

11.4 NTP

Since big jumps in the local time can have undesired effects on the robot applications, NTP is setup when the robot starts and before the ROS master is initiated. If no synchronization was possible, for example if the NTP servers are offline, the NTP daemon is stopped after a timeout.

To setup ntp as client edit the etc/ntp/.conf file and add your desired ntp servers. You can use your own local time servers or external ones, such as ntp.ubuntu.com. You can also try uncommenting the default servers already present. For example, if the local time server is in 192.168.1.6 add the following to the configuration file.

server 192.168.1.6 iburst

Restart the ntp daemon to test your servers.

systemctl restart ntp.service

Run the ntpq -p command and check that at least one of the configured servers has a nonzero reach value and a nonzero offset value. The corrected date can be consulted with the date command. Once the desired configuration is working make sure to make the changes in /etc/ntp.conf persistant and reboot the robot.

If, on the contrary, you want the robot to act as the NTP server of your network, no changes are needed. The current ntp daemon already acts as server. You will only need to configure NTP for the clients.

To configure NTP on the rest of the clients, like the development PCs, run:

systemct1 status ntp.service

If the service is active follow the previous steps to configure the ntp daemon. Once again a private or public NTP server can be used. If, instead the robot is desired as server add this line to /etc/ntp.conf.

server tiago-Xc iburst

If the service is not found then that means ntp is not installed. Either install it with apt-get install ntp or make use of Ubuntu’s default ntp client called timesyncd.

To configure timesyncd simply edit the /etc/systemd/timesyncd.conf file and set the proper NTP server.

Restart the timesyncd daemon.

systemctl restart systemd-timesyncd.service

Check the corrected date with the date command. The time update can take a few seconds.

11.5 System upgrade

For performing system upgrades connect to the robot, make sure you have Internet access and run the pal_upgrade command as root user.

This will install the latest TIAGo Base software available from the PAL repositories.

Reboot after upgrade is complete.

11.6 Firmware update

To update firmware, use the application described in section 11.5   System upgrade. Check for updates for the pal-ferrum-firmware* packages and install them.

Run the update_firmware.sh script, as shown below. The update will take a few minutes.

pal@pmb2-1c:~# rosrun firmware_update_robot update_firmware.sh

Finally, shut it down completely, power off with the electric switch and then power up the robot, as described in 3.5.1   Electric switch section.

11.7 Meltdown and Spectre vulnerabilities

Meltdown and Spectre exploit critical vulnerabilities in modern processors.

Fortunately the linux Kernel has been patched to mitigate these vulnerabilities, this mitigation comes at a slight performance cost.

PAL Robotics configuration does not interfere with mitigation, whenever the installed kernel provides mitigation, it is not disable by our software configuration.

Below we provide some guidelines to disable the mitigation in order to recover the lost performance, this is not recommended by PAL Robotics and it is done on the customer’s own risk.

On this website the different tunables for disabling mitigation controls are displayed.

These kernel flags must be applied to the GRUB_CMDLINE_LINUX in /etc/default/grub. After changing them, update-grub must be executed, and the computer must be rebooted.

These changes need to be made in the persistent partition, as indicated in 11.2   File system

Be extremely careful when performing these changes, since they can prevent the system from booting properly.



12 Modifying Robot Startup

This section describes how the startup system of the robot is implemented and how to modify it, in order to add new applications, modify how they are launched, or prevent applications from being launched at all.

12.1 Introduction

TIAGo Base startup is configured via YAML files that are loaded as ROS Parameters upon robot startup.

There are two types of files: configuration files that describe how to start an application and files that determine which applications must be started for each computer in a robot.

All these files are in the pal_startup_base package within the config directory.

12.1.1 Application start configuration files

These files are placed inside the apps directory within config.

foo_bar.yaml contains a YAML description on how to start the application foo_bar.

roslaunch: "foo_bar_pkg foo_bar_node.launch"
dependencies: ["Functionality: Foo", "Functionality: Bar"]
timeout: 20

The required attributes are:

  • One of roslaunch, rosrun or bash: used to determine how to start the application. The value of roslaunch, rosrun or bash is the rest of the commands that you would use in a terminal (you can use bash magic inside such as ‘rospack find my_cfg_dir’). There are also some keywords that are replaced by the robot’s information in order to make scripts more usable. @robot@ is replaced by the robot name as used inour ROS packages (ie REEMH3 is reem, REEM-C is reemc, …)

  • dependencies: a list of dependencies that need to be running without error before starting the application. Dependencies can be seen in the Diagnostics Tab. If an application has no dependencies, it should be set to an empty list [].

Optional attributes:

  • timeout: applications whose dependencies are not satisfied after 10 seconds are reported as an error. This timeout can be changed with the timeout parameter.

  • auto_start: Determines whether this application must be launched as soon as its dependencies are satisfied, if not specified defaults to True.

Examples:

localization.yaml

roslaunch: "@robot@_2dnav localization_amcl.launch"
dependencies: ["Functionality: Mapper", "Functionality: Odometry"]

web_commander.yaml

rosrun: "pal_webcommander web_commander.sh"
dependencies: []

12.1.2 Computer start lists

The other type of YAML configuration files are the lists that determine what to start for each robot’s computer. They are placed within the config directory, inside a directory with the name of the computer that must start them, for instance control for the default computer in all of PAL Robotics’ robots, or multimedia for robots with a dedicated multimedia computer.

Each file contains a single YAML list with the name of the applications, which are the names of the YAML files for the application start configuration files.

Each file has a name that serves as a namespace for the applications contained within it. This allows the user to modify a subset of the applications to be launched.

Examples:

pal_startup_base/config/control/core.yaml

 # Core
- ros_bringup
- diagnostic_aggregator
- web_commander

 # Deployers
- deployer_xenomai

 # Navigation
- laser_ros_node
- map_server
- compressed_map_publisher
- map_configuration_server
- vo_server
- localizer
- move_base
- navigation_sm
- poi_navigation
- pal_waypoint

 # Utilities
- computer_monitor_control
- remote_shell_control
- rosbridge
- tablet_backend
- ros_topic_monitor
- embedded_networking_supervisor

12.1.3 Additional startup groups

Besides the control group, and the multimedia group for robots that have more than one computer, additional directories can be created in the config directory at the same level as the control directory.

These additional groups are typically used to group different applications in a separate tab in the WebCommander, such as the Startup Extras optional tab.

A startup_manager pal_startup_node.py instance is required to handle each startup group.

For instance if a group called grasping_demo is needed to a manage the nodes of a grasping demo started in the control computer, a directory will have to be created called grasping_demo containing at least one computer start list yaml file as described in the previous section.

Additionally it is recommended that we add to the control’s computer startup list a new application that will start the startup manager of the grasping_demo so it is available from the start.

rosrun: "pal_startup_manager pal_startup_node.py grasping_demo"
dependencies: []

12.2 Startup ROS API

Each startup node can be individually controlled using a ROS api that consists of the following services, where {startup_id} must be substituted for the name of the corresponding startup group (ie control, multimedia or grasping_demo).

/pal_startup_{startup_id}/start Arguments are app (name of the application as written YAML files for the application start configuration files) and args (optional command line arguments). Returns a string containing if the app was started successfully.

/pal_startup_{startup_id}/stop Arguments are app (name of the application as written YAML files for the application start configuration files). Returns a string containing if the app was stopped successfully.

/pal_startup_{startup_id}/get_log Arguments are app (name of the application as written YAML files for the application start configuration files) and nlines (number of lines of the log file to return). Returns up to the last nlines of logs generated by the specified app.

/pal_startup_{startup_id}/get_log_file Arguments are app (name of the application as written YAML files for the application start configuration files). Returns the path of the log file of the specified app.

12.3 Startup command line tools

pal-start This command will start an application in the background of the computer it is executed on, if it is stopped. Pressing TAB will list the applications that can be started.

pal-stop This command will stop an application launched via pal_startup in the computer it is executed on, if it is started. Pressing TAB will list the applications that can be stopped.

pal-log This command will print the name and path of the log file of the selected application. Pressing TAB will list the applications whose log can be seen.

12.4 ROS Workspaces

The startup system will look for packages in the following directories in order, if a package is found in one of the directories, it will not be looked for any further on directories lower in the list.

12.5 Modifying the robot’s startup

In order to enable the robot’s users to fully customize the startup of the robot, in addition to using the files located in the config directory of the pal_startup_base package, the startup procedure will also load all the parameters within /home/pal/.pal/pal_startup/ of the robot’s control computer, if it exists.

To modify the robot’s startup, this directory must be created and have the same structure as the config directory within the pal_startup_base package.

12.5.1 Adding a new application for automatic startup

To add a new application, “new_app”, to the startup, create a new_app.yaml file within the apps directory. Fill it with the information described in 12.1.1   Application start configuration files.

The file we created specifies how to start the application, in order to launch the application in the control computer, create a control directory and place it inside a new yaml file, which must consist of a list containing new_app.

For instance:

/home/pal/.pal/pal_startup/apps/new_app.yaml

roslaunch: "new_app_package new_app.launch"
dependencies: []

/home/pal/.pal/pal_startup/control/new_app_list.yaml

- new_app

12.5.2 Modifying how an application is launched

To modify how the application “foo_bar” is launched, copy the contents from the original foo_bar.yaml file in the pal_startup_base package and perform the desired modifications.

12.5.3 Adding a new workspace

In cases where the workspace resolution process needs to be changed, the file at /usr/bin/init_pal_env.sh can be modified to adapt the environment of the startup process.



13 Developer’s manual: WebCommander

The WebCommander is a web page hosted by TIAGo Base. It can be accessed from any modern web browser that is able to connect to TIAGo Base.

It is an entry point for several monitoring and configuration tasks that require a Graphical User Interface (GUI).

13.1 Accessing the WebCommander website

  1. Ensure that the device you want to use to access the website is in the same network and able to connect to TIAGo Base.

  2. Open a web browser and type in the address bar the host name or IP address of TIAGo Base’s control computer and try to access port 8080:

http://pmb2-1c:8080

  1. If you are connected directly to TIAGo Base, when the robot is acting as an access point, you can also use:

http://control:8080

13.2 Overview

The WebCommander website contains visualizations of the state of TIAGo Base’s hardware, applications and installed libraries, as well as tools to configure elements of its behaviour.

13.3 Default tabs

TIAGo Base comes with a set of preprogrammed tabs that are described in this section, these tabs can also be modified and extended, as explained in the 13.4   Tab configuration. Each tab is an instantiation of a web commander plugin.

For each tab a description and the plugin type used to create it is defined.

13.3.1 Startup tab

Plugin: Startup

Description: Displays the list of PAL software that is configured to be started in the robot, and whether it has been started or not.

Each application, or group of applications, that provides a functionality, can choose to specify a startup dependency on other applications or groups of applications. There are three possible states:

  • Green: All dependencies satisfied, application launched.

  • Yellow: One or more dependencies missing or in error state, but within reasonable time. Application not launched.

  • Red: One or more dependencies missing or in error state, and maximum wait time elapsed. Application not launched.

Additionally, there are two buttons on the right of each application. If the application is running, a “Stop” button is be displayed, which will stop the application when pressed. If the application is stopped or has crashed, the button “Start” is be displayed, which will start the application when pressed. The “Show Log” button, allows to display the log of the application.

_images/WebCommander.png

Figure: The Startup Tab displays the launched applications and their dependencies


13.3.2 Diagnostics Tab

Plugin: Diagnostics

Description: Displays the current status of TIAGo Base’s hardware and software.

The data is organized in an hierarchical tree. The first level contains the hardware and functionality categories.

The functionalities are the software elements that run in TIAGo Base, such as vision or text to speech applications.

Hardware diagnostics contain the hardware’s status, readings and possible errors.

Inside the hardware and functionality categories, there’s an entry for each individual functionality or device. Some devices are grouped together (motors, sonars), but each device can still be seen in detail.

The color of the dots indicates the status of the application or component.

  • Green: No errors detected.

  • Yellow: One or more anomalies wait until you are able to ping the new robot IP in your own LAN. If it does not happen you might have tohe left of the name of the category. This will provide information specific to the device or functionality. If there’s an error, an error code will be shown.

  • Red: One or more errors were detected which can affect the behaviour of the robot

  • Black: Stale, no information about the status is being provided

An example of this display is shown in the figure below. The status of a particular category can be expanded by clicking on the “+” symbol to the left of the name of the category. This will provide information specific to the device or functionality. If there’s an error, an error code will be shown.

_images/diagnostics.png

Figure: The Diagnostics tab displays the status of the hardware and software components of TIAGo Base


13.3.3 Logs Tab

Plugin: Logs

Description: Displays the latest messages printed by the applications’ logging system.

The logs are grouped by severity levels, from high to low severity: Fatal, Error, Warn, Info and Debug.

The logs are updated in real time, but messages printed before opening the tab can’t be displayed.

The log tab has different check-boxes to filter the severity of the messages that are displayed. Disabling a priority level will also disable all the levels below it, but they can be manually enabled. For instance, unchecking Error will also uncheck the Warn,Info and Debug levels, but the user can click on any of them to reenable them.

_images/logsTab.png

Figure: The Log Tab displays the log messages as they are being published in the robot


13.3.4 General Info Tab

Plugin: General Info

Description: Displays the robot model, part number and serial number.

13.3.5 Settings Tab

Plugin: Settings

Description: The settings tab allows to change the behaviour of TIAGo Base.

Software Configuration The Settings tab allows the user to configure some software of the robot. For example, the user can change the Diagnostic Severity reporting level so that, depending on this value, the robot will report certain errors by means of its LED stripes, voice, etc.

_images/WebCommander-Settings-software-config.png

Figure: TIAGo Base Software Configuration


Remote Support The Settings tab is equipped with the remote support connection widget. A technician from PAL Robotics can give remote assistance to the robot by connecting through this widget. Using an issue in the support portal, the PAL technician will provide the IP Address and the Port, this information need to be filled in the respective fields of the widget and then pressing the Connect button will allow for the remote assitance. If the robot needs to be rebooted, the customer has to activate the remote support after each reboot because it is not persistent.

_images/WebCommander-Settings-support.png

Figure: Remote support widget for TIAGo Base


At any point of time after the connection had established, the remote connection can be terminated by clicking the Disconnect button.

Note

After clicking the Connect if the widget pops back to the normal, instead of showing the connection status, then it means that the robot is either not connected to internet (or) there should be some network issue.

13.3.6 Networking tab

Plugin: NetworkingEmbedded

Description: The figure below shows the networking tab. By default, the controls for changing the configuration are not visible in order to avoid access by multiple users.

_images/WebCommander-Networking.png

Figure: Networking configuration


If the Enter button is pressed, the tab connects to the network configuration system and the controls shown in Figure: Networking configuration controls.

When a user connects to the configuration system, all the current clients are disconnected and a message is shown in the status line.

_images/networkingConfigurationParameters.png

Figure: Networking configuration controls


Configurations are separated in different blocks:

  • Wifi:

    • Mode: Can be selected whether WiFi connection works as client or access point.

    • SSID: ID of the Wi-Fi to connect to client mode or to publish in access point mode.

    • Channel: When the robot is in access point mode, use this channel.

    • Mode Key: Encryption of the connection. For more specific configurations select manual. In this case it is used the file /etc/wpa_supplicant.conf.manual that can be manually created in the robot.

    • Password: Password for the WiFi connection

  • Ethernet:

    • Mode: Can be selected whether the ethernet connection works as an internal LAN or external connection (see Section Specifications -> Expansion Panel).

  • IPv4

    • Enable DHCP Wifi: Enables DHCP client in WiFi interface.

    • Enable DHCP Ethernet: Enables DHCP client in the external ethernet port.

    • Address, Network, Gateway: In client mode, the manual values of the building’s network are used by the Wi-Fi interface. This is the same for the external ethernet port.

  • DNS

    • Server: DNS server.

    • Domain: Domain to use in the robot.

    • Search: Domain to use in the search.

  • VPN

    • Enable VPN: If the customer has a PAL basestation, the robot can be connected to the customer’s VPN.

    • Enable Firewall: When activating the VPN, a firewall can be connected to avoid an incoming connection from outside the VPN.

    • Address: Building network IP address of the basestation.

    • Port: Port of the basestation where the VPN server is listening.

No changes are set until the Apply change button is pressed.

When the Save button is pressed (and confirmed), the current configuration is stored in the hard disk.

Be sure to have a correct networking configuration before saving it. A bad configuration can make it impossible to connect to the robot. If this happens, a general reinstallation is needed.

Changes to the WiFi between client and access point could require a reboot of the computer in order to be correctly applied.

Using the diagnostic tab, it is possible to see the current state of the WiFi connection.

Connecting TIAGo Base to a LAN In order to connect TIAGo Base to your own LAN follow the steps below.

First of all you need to access the WebCommander via the URL http://pmb2-1c:8080 and go to the Networking tab. Press Enter button and then follow the instructions shown in Figure: Configuring TIAGo Base to connect to a LAN.

Once you have filled in the right configuration and pressed the Apply change button it is very important to wait until you are able to ping the new robot IP in your own LAN. If it does not happen you might have to reboot the robot as the configuration changes have not been saved yet. The robot will reboot with its previous networking configuration, allowing you to repeat the process properly.

When the new configuration allows you to detect the robot in your own LAN then you may proceed to enter the WebCommander again and press the Save button and then the Confirm button.

Setting TIAGo Base as an Access Point In order to configure TIAGo Base as access point open the WebCommander via the URL http://pmb2-1c:8080 and go to the Networking tab. Press Enter button and then follow the instructions shown in Figure: Configuring TIAGo Base to connect to a LAN in the 13.4.1   Parameter format section.

Once you have filled in the right configuration and pressed the Apply change button it is very important to wait until the new Wi-Fi network is detected. A smartphone, a tablet or a computer provided with a WiFi card can be used for this purpose. If it does not happen you might have to reboot the robot as the configuration changes have not been saved yet. The robot will reboot with its previous networking configuration, allowing you to repeat the process properly.

When the new configuration allows you to detect the robot’s Wi-Fi then you may proceed to enter the WebCommander after connecting to the Wi-Fi of the robot and press the Save button and then the Confirm button.

13.4 Tab configuration

The WebCommander is a configurable container for different types of content, and the configuration is done through the /wt parameter in the ROS Parameter Server. On the robot’s startup, this parameter is loaded by reading all the configuration files in /home/pal/.pal/wt/. For a file to be loaded, it needs to have a .yaml extension containing valid YAML syntax describing ROS Parameters: within the /wt namespace.

_images/configuration.png

Figure: Configuring TIAGo Base to connect to a LAN


13.4.1 Parameter format

In the box below, an example of how a WebCommander configuration is displayed. It is a YAML file, where /wt is a dictionary and each key in the dictionary creates a tab in the website with the key as the title of the tab.

Each element of the dictionary must contain a type key, whose value indicates the type of plugin to load. Additionally, it can have a parameters key with the parameters that the selected plugin requires.

_images/parameter_WebCom.png

Figure: Configuring TIAGo Base to connect to a LAN


wt:
    "0. Startup":
        type: "Startup"
    "1. Diagnostics":
        type: "Diagnostics"
    "2. Logs":
        type: "Logs"
    "3. Behaviour":
        type: "Commands"
        Parameters::
            buttons:
              - name: "Say some text"
                say:
                      text: "This is the text that will be said"
                      lang: "en_GB"
              - name: "Unsafe Wave"
                motion:
                      name: "wave"
                      safe: False
                      plan: True

The Parameters: in the box of this section would create four tabs. Named “0. Startup”, “1. Diagnostics”, “2. Logs” and “3. Behaviour”, of the types Startup, Diagnostics, Logs and Commands respectively. The first three plugins do not require Parameters:, but the Command type does, as explained in the Command Plugin section.

13.4.2 Startup Plugin: Configuration

Description: Displays the list of PAL software that is configured to be started in the robot, and whether it has been started or not.

Parameters:

startup_ids A list of strings that contains the startup groups handled the instance of the plugin. See section 12.1.3   Additional startup groups

13.4.3 Diagnostics Plugin Configuration

Description: Displays the current status of TIAGo Base’s hardware and software.

Parameters: None required

13.4.4 Logs Plugin Configuration

Description: Displays the latest messages printed by the applications’ logging system.

Parameters: None required

13.4.5 General Info Plugin Configuration

Description: Displays the robot model, part number and serial number.

Parameters: None required

13.4.6 Installed Software Plugin Configuration

Description: Displays the list of all the software packages installed in both the robot’s computers.

Parameters: None required

13.4.7 NetworkingEmbedded Plugin Configuration

Description: This tab allows to change the network configuration.

Parameters: None required

13.4.8 Video Plugin Configuration

Description: Displays the images from a ROS topic in the WebCommander

Parameters:

topic Name of the topic to read images from, for instance: /xtion/rgb/image_raw/compressed

_images/WebCommander-Video.png

Figure: The Video Tab displays live video stream from the robot’s camera



14 Web User Interface

14.1 Overview

This section explains the use TIAGo Base’s Web User Interface and its different plugins. The Web User Interface is a tool designed to simplify the configuration of the robot as well as the user experience. The Web User Interface can be accessed via browser, at the address http://pmb2-Xc , where X is the serial number of the robot.

14.2 Technical considerations

At the moment the Web User Interface supports only the Chrome browser on a laptop or computer. Accessing the Web User Interface from a mobile phone or tablet, or from a different browser, will result in some of the functions not working properly or at all.

14.3 Login screen

When accessing the Web User Interface a user and password will be requested. The default user and password is pal / pal . Once the correct user and password are introduced the user will automatically be redirected to the page he was accessing.

Sessions are not time-constrained, which means that once a user has logged in he won’t be logged out until either he closes the browser or the robot is rebooted.

Login screen of the WebGUI.

Figure: Login screen of the WebGUI.

14.5 Home Web Plugin

The Home Web Plugin contains general information of interest about the robot, as well as the basic task queue interface.

_images/home_page.png

Figure: Example of the TIAGo Base Home Plugin


At the top of the screen three cards present relevant information on the state of the robot:

  • State of the emergency button: when the emergency button is pressed the icon will turn red.

  • Dock station state: when the robot is docked the charging icon will turn green.

  • Battery information: Both the current battery precentage as well as its current voltage are displayed. The color of the battery gauge changes from green to red according to the current battery level.

Below this line a status bar shows the current task state of the robot. If no task is being executed at the moment the message “No current task now” is displayed over a white background, as seen in Figure: Example of the TIAGo Base Home Plugin. Otherwise, if a task is being executed the status line changes to an orange background, and the name of the task is displayed as show in figure below.

_images/home_page_running.png

Figure: Example of the TIAGo Base Home Plugin while a task is running.


Pressing on the Abort button displayed on the right side of the status bar will abort the current task.

Below the status line two panels asre displayed:

  • Available Tasks: This panel shows a list of the tasks configured on the robot, with the confiured name and type of task. Clicking on the play icon next to the name of the task will add this task to the queue to be executed.

  • Queue: This panel shows the current queue of tasks of the robot, in order, as seen in figure below. If no tasks are waiting to be executed on the queue the icon shown in Figure: Example of the TIAGo Base Home Plugin will be shown.

_images/tasks_webGUI.png

Figure: Example of queued tasks


Tasks added to the queue are executed in a First In, First Out fashion. If the current task is aborted the next task on the queue will begin immediately.

14.6 Building Manager Web Plugin

The Building Manager Web Plugin covers the management operations related both to buildings and maps. This Plugin is divided in three different sections: The Building Manager tabs, which covers building management, The Map Manager tab, which covers map management and the Update Map tab, which allows modification and merging of existing maps and their updates.

14.6.1 Building Manager Tab

The Building Manager tab lists all existing buildings and allows operations such as Building Creation, edition and removal.

Manager Building Tab

Figure: Manager Building Tab

The menu at the top left side displays three buttons:

  • The Create Building button opens a popup that allows the creation of a new building. Two steps are required to create a new building: assign a building name and choosing a map for the first floor of the building. This map must contain the POIs for a dockstation (dockstation and docked_pose).

  • The Upload Building button opens a popup that allows the user to upload a building. Two steps are required: assign a name to the building that will be uploaded, and selecting a zip file on the user’s computer (which must have the same structure as that of the buildings downloaded through the Download button of a specific building).

  • The Save Current Config button stores the current WiFi configuration, as well as the current Task configuration on the building the robot is currently in (active building).

On the top right menu a Search field allows the user to filter the list of buildings by name.

The list of building shows the buildings configured on the robot. The currently active building is show with an orange icon next to it. In addition the currently active floor is shown as well. Clicking on any of the buildings will expand the information shown on that building.

A list is shown with all the floors of the building, with the first floor of the building in bold, and the currently active floor, if any, initialized. At the top of the list the Add Floor button opens a popup with a dropdown menu to select another map to be added as a new floor to the building. Click on the cross next to each floor wil remove that floor from the building.

On the lower left-hand side either the Set As Current button is shown (if the building is not active), which opens a popup that allows the user to choose a floor on that building and then set that floor and that building as the currently active one; or the Change Floor button is shown (if the building is the active one), to choose a floor on that building to set as the currently active one.

In addition two other buttons are always shown on the lower right-hand side:

  • Download, which downloads the building configuration in zip format.

  • Remove, which allows the user to remove the building from the robot after a confirmation dialog (this action can be undone).

14.6.2 Map Manager Tab

The Map Manager tab lists all existing maps and allows operations such as starting a new map, uploading a new map or changing the currently active map.

Map Manager Tab

Map Manager Tab

The menu at the top left side displays two buttons:

  • The Start Mapping button wil begin a new map, and change the screen to show a window around the robot with the map that is being created, as seen in Figure: Mapping screen. The Stop Mapping button shown on the top left menu stops the map and stores its information. After that a popup will appear to change the name of the newly generated map. Clicking on the minimap displayed at the top left corner of the mapping area will open a bigger version of the completed map. The eye icon on the top right side allows hiding or showing the minimap (which is shown by default). The joystick on the lower right side allows control of the robot.

  • The upload map button opens a popup that allows allows the user to select a zip file on his computer (which must have the same structure as that of the maps downloaded through the Download Map button), set up a name for the map and upload it on the robot.

On the top right menu a Search field allows the user to filter the list of maps by name.

The list of maps shows all existing maps on the robot. The currently active map is shown with an orange icon next to it. Clicking on any of the maps will expand the options on that map. If the map is not the active one the Set As Active button is shown in the lower left side, which will change the active map after a confirmation popup.

On the lower right side three buttons are shown:

Mapping screen

Figure: Mapping screen

  • The Download Map button downloads all the information of the map as a zip file.

  • The Rename Map button opens a popup to change the name of the map.

  • The Update button switches to the Update Map Tab with this map preselected as the Source Map.

14.6.3 Update Map Tab

The Update Map tab allows the user to visualize and apply updates to the maps loaded on the robot.

Example of the Map Updates Tab

Example of the Map Updates Tab

On the top left side of the screen the Source Map dropdown list allows the user to select which of the available maps to work with. On the top right side the Update dropdown list allows the user to select which update or other map will be used to update the source map. In between both dropdowns a slider allows changing the transparency to visualize the differences. When the slider is at the right side only the updated version is displayed. Moving the slider to the left makes the updated version of the map transparent so differences can be seen, when the slider is at its left side only the original map is displayed.

The main component of the page shows both the source map with its update. The view can be zoomed in and out using the mouse wheel, and the view can be panned by drag-and-drop with the mouse wheel button.

At the right side of the map three buttons are displayed:

  • The Move Map button (represented with four arrows) activates the move mode. In this mode the updated map can be moved by dragging and dropping it with the left mouse button. When activating this mode the updated map will be made transparent so both maps can be seen. While in this mode the button will change to a tick icon, click on that button to exit move mode.

  • The Rotate Map button (represented with a circular arrow) activates the rotate mode. In this mode the updated map can be rotated around its center by clicking on the map with the left mouse button and then dragging it. While in this mode the button will change to a tick icon, click on that button to exit rotate mode.

  • The Update Area button (represented with a dashed square) allows the user to select a region to update. The area is drawn by clicking with the left mouse button and then dragging, to create a basic rectangle shape of the desired dimensions. Once this is done, the vertexes can be dragged and dropped into position, and new vertexes can be added by clicking anywhere along the edges. While in this mode the button will change to a tick icon, click on that button to exit update area mode.

Clicking on any of the other buttons while in a particular mode (i.e. clicking on the Rotate Map while on move mode) will automatically change the mode.

Ath the bottom-right side of the page two buttons are shown:

  • The Undo Last Update button allows the user to undo the last update that was applied to the selected map (only the last update can be undone, additional clicks on the button won’t have any effect).

  • The Apply Update button will update either the selected area (if any), or apply all the Update to the Source Map, after a confirmation popup.

After a map update is performed it is possible that some of the existing POIs are now located inside, or too close, to an obstacle. In that event,a popup will appear warning the user about the fact, and the affected POIs will be displayed in colour red in both the Map and Map Manager tabs, until those POIs are edited. The robot will still try to navigate to those POIs even if they are not edited, it will simply try to get as close as safely possible to the location and orientation of the POI.

14.8 Task Manager Web Plugin

The Task Manager Plugin allows the user to define and manage automated tasks for the robot to perform. It is composed of three different tabs:

  • The Today’s Tasks tab, which allows the user to see which tasks are programmed for (or have been executed on) a given date, as well as enabling and disabling the execution of the scheduled tasks.

  • The Scheduled Tasks tab, which allow the user to manage scheduled tasks.

  • The Execute Task tab, which allows the user to define and execute a task on the fly.

14.8.1 Today’s Tasks tab

The Today’s Tasks tab allows the user to see a list of all the scheduled tasks for a given day, both those pending to be done as well as those that have already been completed and their state. By default this tab displays the list of tasks of the current day. If the execution of scheduled tasks is disabled an icon will be shown as seen in Figure Figure: Today’s Tasks Tab. Click the Enable Schedule button will start the execution of the schedule. If the execution of the scheduled tasks is enabled, and the robot has no pending tasks for the next 15 minutes, it will go back to the dockstation (assuming the dockstation POI have been created). The robot will remain charging until the next pending task needs to be executed.

Today’s Tasks Tab

Figure: Today’s Tasks Tab

If the execution of scheduled tasks is enabled, but the robot has no scheduled tasks for the date selected the icon shown in figure below will be displayed instead.

If the execution of scheduled tasks is enabled and there are tasks on the selected date then a list with the different tasks will be shown, as seen in figure below.

The Disable Schedule button on the top left allows the user to disable the automatic execution of scheduled tasks. On the top right a Search field allows the user to change the date of the scheduled tasks to be displayed.

Clicking on any of the tasks in the list will expand the information shown. In the expanded view the user can see (in read-only mode) all the parameters of each task, as explained on the Scheduled Tasks tab below.

No Tasks for the selected day icon.

Figure: No Tasks for the selected day icon.

Today Tasks Tab with tasks scheduled for the selected date.

Figure: Today Tasks Tab with tasks scheduled for the selected date.

14.8.2 Scheduled Tasks tab

The Scheduled Tasks tab allows the user to see all the tasks defined on the robot and manage them.

Example of the Scheduled Tasks Tab

Figure: Example of the Scheduled Tasks Tab

On the top left the Create New Task button is shown. This button opens a popup with a wizard for task creation. Task creation is performed in the following steps:

  1. Choose the task type.

  2. Assign a name to the task.

  3. Configure the task:

    1. Robot to execute the task (by default, name of the current robot).

    2. Priority

    3. Task is scheduled by default

    4. Start time

    5. Duration of the task (in minutes)

    6. Timeout for task cancellation

    7. Days in which the task should be executed (only used if the task is added to the schedule).

  4. Set Mandatory and Optional Parameters for the task. The optional parameters block is closed by default, it can be opened by clicking on the Optional Parameters title.

On the top right a Search field allows the user to filter the list of tasks by name.

The list of tasks show the name and type of all tasks configured on the robot. Tasks that are added to the schedule and will be automatically executed have an orange icon, and their start time is shown between parenthesis. Tasks that are not added to the schedule are shown with a grey icon.

Clicking on any of the tasks in the list will expand the information on this task. In the expanded task view all parameters of the task can be modified. The expanded view contains four buttons:

  • If the task is not scheduled the Add To Schedule button is shown, which allows the user to add a task to the schedule to be automatically executed. If the task is scheduled the Remove From Schedule button is shown to allow the user to remove it from the schedule, so the task will not be automatically executed.

  • The Execute button allows the user to immediately start this task, reardless of the time configuration. When a task is being executed the button changes to Stop Task, and will immediately abort the current task.

  • The Remove button allows the user to remove this task after a confirmation popup. This action can’t be undone.

  • The Save button stores any changes made on the task.

The time of all the tasks are shown in the local time of the browser.

14.8.3 Execute Task tab

The Execute Task tab allows the user to define and run a task on the fly.

Example of the Execute Tasks Tab

Figure: Example of the Execute Tasks Tab

In the first section, the Type combo box sets the type of task to be executed from those available on the robot.

Other optional fields can be set by clicking on the Optional Parameters menu, in case they are left blank, a default setting will be used. They allow different configurations of the the RFID reader.

The Execute/Stop Task button allows the user to execute or stop a task respectively. This button changes its state depending on the current state of the robot.

14.9 Visual Programming

14.9.1 What is a Visual Programming webapp?

Visual programming is a WebGUI application that allows you to create and execute robot programs. The main advantage of Visual Programming is the user friendly interface. So, you can create programs with minimal technical skills.

To access the Visual Programming select the puzzle icon in the left menu bar of webGUI.

_images/vp_sidebar_icon.png

14.9.2 Interface

Visual Programming webapp consists of a homepage with a list of previously created programs and a visual editor for creating and editing programs.

14.9.3 Homepage

The homepage serves to store a list of all created programs, to manage them and to create new ones.

The interface of homepage has:

  • a button to create a new program,

  • a list of programs created earlier,

  • search engine (loupe icon) for quick navigation through the list.

Each program on the list has:

  • icon to start program execution.

  • icon to edit the program.

  • icon to create a copy of choosed program.

  • icon to remove the program.

_images/vp_homepage.png

In case you clicked the Copy icon, the system will ask you to choose a new program name, because the program names should not be repeated. Be careful when choosing the name, as it cannot be changed later.

_images/vp_copy_program.png

If you click the New Program button or the Edit icon, you will be redirected to the visual editor.

14.9.4 Editor

The visual editor is the main tool of this application. The interface consists of three sections: two columns with interactive blocks on the sides and a Workspace in the center.

_images/vp_editor_interface.png

14.9.4.1 Blocks

Note: some blocks may be not available or can be different depending on the model of robot.

A program is a set of instructions that will be executed by the robot.

A block is an instruction in the program. There are four types of blocks used:

  • actions, which represent specific actions for the robot to do.

  • conditionals, which evaluate when a step should be executed.

  • controls, which allow modifications to the normal order of instructions and .

  • decorators, which modify how other instructions are performed, for example repeating them.

Blocks section is a menu of program blocks grouped by functions. By clicking on the group headers (with plus/minus icon), you can open or close the tab with the blocks in this group.

_images/vp_blocks.png

14.9.4.2 Workspace

The Workspace is an interactive area where you can create programs by adding blocks in the order of their execution. Programs are executed in sequential order, starting at the top.

Add a block to the Workspace

To add a block to the Workspace, drag it with the cursor or double-click on it. If you drag the block, the shadow on the Workspace will indicate where you can place it. In the case of double clicking on it, the block will be automatically added to the end of the queue.

_images/vp_add_block_to_ws.png

Move blocks inside the Workspace: Children blocks

To move blocks inside the Workspace drag it to the desired position.

Certain types of blocks may have children blocks, as indicated by the indentation. In the case of Conditionals and Controls children blocks will be executed or not according to the parent’s configuration. In the case of Decorators children blocks will see their behavior modified accordingly.

To find further information see the 14.9.7   Blocks library.

When you are dragging a block to the Workspace or inside it, look at the shadow that indicates you where you can move the block: under it, below it or as its child.

_images/vp_add_child_block.png

You can edit relations between parent and child blocks any moment during the editing process. To move the block, click an arrow icon on the left of it.

_images/vp_move_block_with_arrow.png

Delete blocks

To delete any block from the Workspace, drag it to the trash icon and drop it over the icon.

_images/vp_delete_block.png

Blocks with ports

Blocks may have ports. It allows adding variables or constants from the right menu. Those ports represent parameters that set up how the action works or return values.

Also near the block you can see a short message that indicates what you should do. Grey text means that it is “a recommendation”, red text - it is a critical error you must resolve. Click the block with the ‘plus’ icon to open it.

_images/vp_block_with_port.png

Ports are directional, that is a port is either read for Input ports, written to for output ports or both for in-out ports. Green arrows (or one arrow) between port name and port input indicate the direction of the port.

Ports also have a type, which means that they only accept certain types of data, for example text, or numbers. If you hover the cursor over the port you will see a tooltip with the port type.

_images/vp_directional_port.png

There are different ways to add a value to the port. First, is typing it manually.

_images/vp_manual_port_value.png

Second, by adding a variable from the right menu.

_images/vp_drag_port_value.png

To delete the added variable from the port, click the ‘X’ icon near ir.

_images/vp_delete_port_value.png

The third way to add value is by using constants. Drag and drop the constant you chose and it will convert to the text value of the port.

_images/vp_drag_port_const.png

The result:

_images/vp_drag_port_const_result.png

14.9.4.3 Variables

Variables are used to store information for the program. Usually they will be used first in an output port to store the result of an action and then used in input ports to be read. Variables are also typed.

To create a new variable, click the ‘Plus’ icon.

_images/vp_create_variable.png

You will open a popup window where you should fill the Name and Type fields.

_images/vp_new_var_popup.png

The name of the variable must start with a letter and can consist of only letters, numbers and ‘_’ symbol. Also it must not be repeated. In each case you will see an error message.

_images/vp_new_var_error_1.png
_images/vp_new_var_error_2.png

Click ‘Save’ to add a new variable to the list.

_images/vp_new_var_save.png

To delete a variable, active ‘Delete’ mode by clicking the ‘Trash’ icon.

_images/vp_variables_delete_mode.png

Choose the variable you want to delete.

_images/vp_variables_delete_mode_select.png

Confirm your choice.

_images/vp_variables_delete_mode_confirm.png

Confirm your choice.

_images/vp_variables_delete_mode_close.png

14.9.4.4 Constants

Constants are used to list values that may be of interest for the programmer, for example, existing POIs on the system.

Like the block menu, constants are grouped by type. In the example, we only have ‘string’ constants. If there is a lot, it is convenient to use opening and closing tabs.

_images/vp_constant_tab_close.png
_images/vp_constant_tab_open.png

14.9.5 How to create a program?

14.9.5.1 Programming process

As it mentioned above, the program is a set of instructions that will be executed by the robot. Programs are executed in sequential order, starting at the top. A block is an instruction in the program. Check the 14.9.7   Blocks library before starting to know more which functions each block has.

So you should add blocks to the Workspace in the desired order and assign corresponding value to the block ports using variables or constants. Pay attention to the prompts on the Workspace. They indicate next steps or important errors.

14.9.5.2 Save program

To leave the edition process without storing changes, click the ‘CANCEL’ button in the lower right corner of the page.

To store your progress, click the ‘SAVE’ button and choose a name for your program. The name cannot be changed afterwards.

_images/vp_save_program.png

14.9.6 How to execute a program?

To execute the program go to the Visual Programming homepage and click the ‘Play’ icon of the chosen program.

_images/vp_execute_program.png

14.9.7 Blocks library

Note: some blocks may be not available or can be different depending on the model of robot.

14.9.7.1 Actions

Actions are executed by the robot and can either Succeed or Fail.

_images/vp_block_action.png

Different actions available

_images/vp_block_action_dock.png

The dock action makes the robot connect to a dock station in front of it.

_images/vp_block_action_undock.png

The Undock action will disconnect the robot from a dock station.

_images/vp_block_action_go_to_poi.png

The Go To POI action instructs the robot to navigate to a POI in the current map. The action will SUCCEED when the robot reaches the target POI, if for any reason the robot is unable to reach the POI the action will FAIL.

  • target poi [String Input Port]: Name of the POI to navigate to.

_images/vp_block_action_led_stripes_blink.png

The Led Stripes Blink action instructs the robot to blink the leds in the configured pattern for some time, switching back and forth between two colors.

  • effect duration [float Input Port]: Total duration of the effect.

  • first color [string Input Port]: Color in format R,G,B,A 255 (i.e. white is 255,255,255,255).

  • first color duration [float Input Port]: Duration of the first color.

  • second color [string Input Port]: Color in format R,G,B,A 255 (i.e. white is 255,255,255,255).

  • second color duration [float Input Port]: Duration of the second color.

_images/vp_block_action_show_on_touchscreen.png

The Show On Touchscreen action shows a list of buttons on the small TFT screen on the back of the TIAGo base, and then waits for a user to press one of the buttons.

  • options [string Input Port]: Comma-separated list of buttons to show on the TFT.

  • selected option [string Output Port]: The option selected by the user will be stored in this port.

_images/vp_block_action_tts.png

The TTS action will make the robot speak a sentence.

  • text [string Input Port]: Text to be read by the robot.

  • lang [string Input Port]: Language code in which the robot should speak (i.e. en_GB for british english).

_images/vp_block_action_wait_n_sec.png

The Wait N Seconds action will halt the execution of the program for the configured amount of time.

  • time [unsigned int Input Port]: Number of seconds the robot should wait.

_images/vp_block_action_wait_for_continue.png

The Wait For Continue action will stop the robot until an external signal is sent.

  • look back [float Input Port]: if a signal was sent less than look back seconds ago the action will consider it valid and continue.

_images/vp_block_action_wait_for_path.png

The Wait For Path action will stop the robot in place and wait until a path is available to the configured POI.

  • target poi [string Input Port]: POI to which the robot will try to trace a path.

14.9.7.2 Conditionals

Conditionals are used to redirect the program flow according to different conditions. Conditionals must be used in chains that start with an IF, have zero or more ELSE IFs and may finish with an ELSE block.

_images/vp_block_conditionals.png
_images/vp_block_conditional_if.png

If the values of both ports match execute the children of this block.

  • value A [any Input Port]: A value to compare, it may be of any type, but both ports must have the same type.

  • value B [any Input Port]: B value to compare, it may be of any type, but both ports must have the same type.

_images/vp_block_conditional_else_if.png

If the values of both ports match execute the children of this block.

  • value A [any Input Port]: A value to compare, it may be of any type, but both ports must have the same type.

  • value B [any Input Port]: B value to compare, it may be of any type, but both ports must have the same type.

_images/vp_block_conditional_else.png

In case all the previous IF and ELSE IF blocks in the chain have failed, execute this block’s children.

14.9.7.3 Control

Controls modify the behavior of the program sequence.

_images/vp_block_control.png
_images/vp_block_control_fallback.png

Children of a Fallback block will be executed in order until one of them SUCCEEDS, and then it will SUCCEED. If no block SUCCEEDS then it will FAIL.

_images/vp_block_control_sequence.png

A Sequence block encapsulates a set of blocks, executing them in order until one of them FAILS, in which case it will FAIL. If all of them SUCCEED it will SUCCEED as well.

14.9.7.4 Decorator

Decorators modify how blocks behave on success and failure situations.

_images/vp_block_decorator.png
_images/vp_block_decorator_repeat.png

A Repeat block will repeat its children blocks in order a number of times, as long as they SUCCEED.

  • num cycles [integer Input Port]: Number of times to repeat the children blocks.

_images/vp_block_decorator_repeat_until_successful.png

A Retry Until Successful block will keep executing its children actions in order until all of them SUCCEED, up to the configured number of times.

  • num attempts [integer Input Port]: Maximum number of tries, can be set to 0 to retry indefinitely.

15 Deploying software on the robot

This section contains a brief introduction to the deploy script PAL Robotics provides with the development environment.

The deploy tool can be used to:

  • Install new software onto the robot

  • Modify the behaviour of existing software packages by installing a newer version and leaving the original installation untouched.

15.1 Introduction

When TIAGo Base boots up it always adds two sources of packages to its ROS environment. One is the ROS software distribution of PAL Robotics at /opt/pal/${PAL_DISTRO}/, the other is a fixed location at /home/pal/deployed_ws, which is where the deploy tool installs to. This location precedes the rest of the software installation, making it possible to overlay previously installed packages.

To maintain consistency with the ROS release pipeline, the deploy tool uses the install rules in the CMakeLists.txt of every catkin package. Make sure that everything you need on the robot is declared to be installed.

15.2 Usage

usage: deploy.py [-h] [--user USER] [--yes] [--package PKG]
                      [--install_prefix INSTALL_PREFIX]
                      [--cmake_args CMAKE_ARGS]
                      robot
Deploy built packages to a robot. The default behavior is to deploy *all*
packages from any found workspace. Use --package to only deploy a single package.
positional arguments:   robot
                hostname to deploy to (e.g. pmb2-1c)
optional arguments:
    -h, --help            show this help message and exit
    --user USER, -u USER  username (default: pal)
    --yes, -y             don't ask for confirmation, do it
    --package PKG, -p PKG deploy a single package
    --install_prefix INSTALL_PREFIX, -i INSTALL_PREFIX
                        Directory to deploy files
    --cmake_args CMAKE_ARGS, -c CMAKE_ARGS
                        Extra cmake args like
                        --cmake_args="-DCMAKE_BUILD_TYPE=Release"
e.g.: deploy.py pmb2-1c -u root -p pal_tts -c="-DCMAKE_BUILD_TYPE=Release"

15.3 Notes

  • The build type by default is not defined, meaning that the compiler will use the default C++ flags. This is likely to include -O2 optimization and -g debug information, meaning that, in this mode, executables and libraries will go through optimization during compilation and will therefore have no debugging symbols. This behaviour can be changed by manually specifying a different option such as: --cmake_args="-DCMAKE_BUILD_TYPE=Debug"

  • Different flags can also be set by chaining them: --cmake_args="-DCMAKE_BUILD_TYPE=Debug -DPCL_ONNURBS=1"

  • If an existing library is overlayed, executables and other libraries which depend on this library may break. This is caused by ABI / API incompatibility between the original and the overlaying library versions. To avoid this, is it recommended to simultaneously deploy the packages that depend on the changed library.

  • There is no tool to remove individual packages from the deployed workspace except to delete the /home/pal/deployed_ws folder altogether.

15.4 Deploy tips

  • You can use an alias ( you may want to add it to your .bashrc) to ease the deploy process:

alias deploy="rosrun pal_deploy deploy.py"

  • You can omit the --user palas it is the default argument

  • You may deploy a single specific package instead of the entire workspace:

deploy -p hello_world pmb2-1c

  • You can deploy multiple specific packages instead of the entire workspace:

deploy -p "hello_world other_local_package more_packages" pmb2-1c

  • Before deploying you may want to do a backup of your previous ~/deployed_ws in the robot to be able to return to your previous state, if required.

15.5 Use-case example

15.5.1 Adding a new ROS Package

In the development computer, load the ROS environment (you may add the following instruction to the ~.bashrc)

source /opt/pal/${PAL_DISTRO}/setup.bash

Create a workspace

mkdir -p ~/example_ws/src
cd ~/example_ws/src

Create a catkin package

catkin_create_pkg hello_world roscpp

Edit the CMakeLists.txt file with the contents in the figure below.

cmake_minimum_required(VERSION 2.8.3)
project(hello_world)

find_package(catkin REQUIRED COMPONENTS roscpp)

catkin_package()

include_directories(
    SYSTEM ${catkin_INCLUDE_DIRS}
)

## Declare a C++ executable
add_executable(hello_world_node src/hello_world_node.cpp)
target_link_libraries(hello_world_node ${catkin_LIBRARIES})

## Mark executables and/or libraries for installation
install(TARGETS hello_world_node RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

Edit the src/hello_world_node.cpp file with the contents in the figure below

 // ROS headers
 #include <ros/ros.h>

 // C++ std headers
 #include <iostream>

 int main(int argc, char** argv)
 {
   ros::init(argc,argv,"hello_world");

   ros::NodeHandle nh("~");

   std::cout << "Hello world" << std::endl;

   return 0;
 }

Build the workspace

cd ~/example_ws
catkin build

The expected output is shown in the figure below.

_images/hello_world_build.png

Figure: Build output of hello world package


Deploy the package to the robot:

cd ~/example_ws
rosrun pal_deploy deploy.py --user pal pmb2-1c

The deploy tool will build the entire workspace in a separate path and, if successful, it will request confirmation in order to install the package on the robot, as shown in the figure below.

_images/Hello_world_deploy_1.png

Figure: Deployment of hello world package


Press Y so that the package files are installed on the robot computer. The figure below shows the files that are copied for the hello world package, according to the installation rules specified by the user in the CMakeLists.txt.

_images/Hello_world_deploy_2.png

Figure: Installation of the hello world package to the robot


Then connect to the robot:

ssh pal@pmb2-1c

And run the new node as follows:

rosrun hello_world hello_world_node

If everything goes well you should see ’Hello world’ printed on the screen.

15.5.2 Adding a new controller

One use-case for the tool is to add or modifiy controllers. Let’s take the ros_controllers_tutorials package, as it contains simple controllers, to demonstrate the power of deploying.

First, list the known controller types on the robot. Open a new terminal and execute the following:

export ROS_MASTER_URI=http://pmb2-1c:11311
rosservice call /controller_manager/list_controller_types | grep HelloController

As it is a genuine installation, the result should be empty.

Assuming a running robot and a workspace on the development computer called pmb2_ws that contains the sources of ros_controllers_tutorials, open a new terminal and execute the following commands:

cd pmb2_ws
catkin_make #-j5 #optional
source devel/setup.bash # to get this workspace into the development environment
rosrun pal_deploy deploy.py --package ros_controllers_tutorials pmb2-1c

The script will wait for confirmation before copying the package to the robot.

Once successfully copied, restart the robot and run the following commands again:

export ROS_MASTER_URI=http://pmb2-1c:11311
rosservice call /controller_manager/list_controller_types | grep HelloController

Now, a list of controller types should appear. If terminal highlighting is enabled, “HelloController” will appear in red.

_images/typesOfControllers.png

Figure: List of contoller types


15.5.3 Modifying an installed package

Now let’s suppose we found a bug on an installed controller inside the robot. In this case, we’ll change the joint_state_controller/JointStateController.

Go to https://github.com/ros-controls/ros_controllers, open a new terminal and execute the following commands:

cd pmb2_ws/src
git clone https://github.com/ros-controls/ros_controllers
# Fix bugs in controller
cd ..
catkin_make #-j5 #optional
source devel/setup.bash # to get this workspace into the development environment
rosrun pal_deploy deploy.py --package joint_state_controller pmb2-1c

After rebooting the robot, the controller with the fixed changes will be loaded instead of the one installed in /opt/



17 Dock Station

17.1 Overview

Depending on the version acquired, your TIAGo Base may include a dock station that allows the robot to recharge itself automatically. This section will describe the components of the dock station and how to use integrate it with your algorithms.

17.2 The Dock Station Hardware

The dock is composed by a metal structure containing basically a pattern to be detected by the TIAGo Base’s LIDAR sensor, a connector to the external charger and the power contacts that will transmit the energy to the robot, as shown in figure below. The dock also has tabs that can be screwed to the floor or wall to rigidly fix it, although this operation is not necesary. It is important to emphasize that, although the charger possesses several security protections, the user should not touch or meddle with the power contacts, for safety reasons.

_images/dockstation.png

Figure: The dock station


17.3 Installation

The dock station should be preferably mounted against a hard surface, to avoid the robot displacing it while doing a docking manoeuvre. The power charger must be plugged in the respective plug. The user must also assure that no objects are present in the dock surroundings, that could interfere with the docking manoeuvre.

17.4 Docking Algorithm

When the robot is asked to go to the dock station, it activates two services in parallel. The first is responsable for the pattern detection, while the second performs the servoing to reach the power contacts:

  • pattern detector: the robot is capable of detecting the pattern up to 1 meters from the LIDAR sensor and with an orientation angle of ± 10º.

  • servoing manoeuvre: it comprises two steps, where first the robot aligns itself with the power contacts and, secondly, advances until the contact is made or a timeout occurs (in the case the dock station is not powered, or the contact fails for example).

The figure below illustrates the requirements for the docking maneouvre.

Once the robot is docked, it will block most velocity commands sent to the base, in order to avoid manoeuvres that could possibly damage the robot or the dock station. There are only two ways of moving the robot after is it docked: by doing an undock manoeuvre, or using the gamepad, which can override all velocity commands.

Warning

It is the sole responsability of the user to operate safely the robot with the gamepad after the robot has reached the dock station.

_images/docking_manoeuvre.png

Figure: The docking specifications


17.5 Usage

The dock/undock manoeuvres are available through two different action servers that can be activated by using the provided rviz plugin or directly through the action server interface.

17.5.1 Dock/Undock using RViz plugins

A dock/undock panel is available as an RViz plugin, that can be added to any RViz configuration by going to the menu Panels -> Add New Panel and then chosing the DockUndockPanel. There is also a preconfigured rviz file that is shipped with the robot and can be loaded with the following command:

export ROS_MASTER_URI=http://pmb2-1c:11311
rosrun rviz rviz -d `rospack find pmb2_2dnav`/config/rviz/advanced_navigation.rviz

The figure below shows the layout of the panel.

_images/dock_panel.png

Figure: The docking specifications


Once the user has positioned the robot within the tolerances specified before, he/she can click the Dock button to perform a docking manoeuvre. At any moment it is possible to cancel the docking manoeuvre by clicking the Cancel button. In a similar way, the robot can be moved out from the dock by clicking the Undock button. A status message will be shown beside the Cancel button, informing the user about the status of the action requested. Note: the robot will only accept an undock order if it was previously docked, otherwise the action request will be rejected.

17.5.2 Dock/Undock using action client

ROS provides an action client interface that can be used to communicate with the action servers responsible for the dock and undock manoeuvres. To run the action client, the following command should be entered for the docking manoeuvre:

export ROS_MASTER_URI=http://pmb2-1c:11311
# For ROS Melodic
rosrun actionlib axclient.py /go_and_dock

# For ROS Noetic
rosrun actionlib_tools axclient.py /go_and_dock

and for the undocking manoeuvre:

export ROS_MASTER_URI=http://pmb2-1c:11311
# For ROS Melodic
rosrun actionlib axclient.py /undocker_server

# For ROS Noetic
rosrun actionlib_tools axclient.py /undocker_server

After any of the previous commands is executed, a panel will pop up. The Figure: The action client for the docking and undocking manoeuvres shows both the /go_and_dock and the /undocker_server panels.

Note

For the docking acti 33on client, the field use_current_pose should be set to True, otherwise the action will fail (this field is not needed for the /undocker_server). In this interface, the button SEND GOAL would start the docking (or undocking) manoeuvre. As before, the CANCEL GOAL button will abort the action, and the status of the server and of the goal are displayed in the bottom of the panel.

_images/dock_undock_axclient.png

Figure: The action client for the docking and undocking manoeuvres.


17.5.3 Dock/Undock code example

Finally, the user can interface with the action servers directly by code, in either Python or C++. There is plenty examples of the usage of action clients in ROS Wiki. Bellow there is a very simple example in Python code, that connects and sends a goal to the /go_and_dock server. Note that the field goal.use_current_pose (line 19) is set to False, as in the previous example.

1. #!  / usr/bin / env python
2. import rospy
3. import rospkg
4. import  actionlib
5.
6. from dock_charge_sm_msgs.msg import GoAndDockAction, GoAndDockGoal
7. from std_msgs.msg import Bool
8.
9. class  SimpleDock():
10.    def  __init__(self) :
11.
12.       rospy.init_node('simple_dock')
13.       self.dock_checker_sub = rospy.Subscriber("/power/is_docked", Bool, self.is_docked_cb)
14.       self.is_docked = False
15.
16.    def go_and_dock_client(self):
17.
18.       goal = GoAndDockGoal()
19.       goal.use_current_pose = True
20.       self.dock_client  =  actionlib.SimpleActionClient("go_and_dock", GoAndDockAction)
21.       self.dock_client.wait_for_server()
22.       self.dock_client.send_goal(goal)
23.       rospy.loginfo("goalsenttogoanddockserver")
24.
25.    def is_docked_cb(self, is_docked):
26.       if(is_docked.data):
27.          self.dock_checker_sub.unregister()
28.          rospy.loginfo("simpledocker:therobotisdocked!")
29.          quit()
30.
31. if  __name__ == '__main__':
32.     try:
33.        sd = SimpleDock()
34.        sd.go_and_dock_client()
35.        rospy.spin ()
36.     except rospy.ROSInterruptException:
37.        print ( "programinterruptedbeforecompletion")




18 Sensors

This section contains an overview of the sensors included in the TIAGo Base robot. After a brief description of the sensors themselves, their ROS and C++ API are presented.

18.1 Description of sensors

  1. LIDAR sensor

    Located at the front of the base. This sensor measures distances in an horizontal plane. It is a valuable asset for navigation and mapping. Bad measurements can be caused by reflective or transparent surfaces. The output of this sensor is filtered to remove outliers and noisy measurements.

  2. Inertial measurement unit (IMU)

    This sensor unit is mounted at the center of TIAGo Base and can be used to monitor inertial forces and it also provides the attitude.

  3. Ultrasound (sonar) sensors (optional)

    These sensors are capable of measuring from low to mid-range distances. In robotics, ultrasound sensors are commonly used for local collision avoidance. Ultrasound sensors work by emitting a sound signal and measuring the reflection of this signal that returns to the sensor. Bad measurements can be caused by either blocking the sensor (will report max range in this case) or by environments where the sound signals intersect with each other.

18.2 ROS API

Note

Every node that publishes sensor data is launched by default on startup.

18.2.1 Published topics

/scan (sensor_msgs/LaserScan)

/scan_raw (sensor_msgs/LaserScan)

Filtered and raw LIDAR measurements.

/base_imu (sensor_msgs/Imu)

Inertial data from the IMU.

/sonar_base (sensor_msgs/Range)

All measurements from sonars sensors are published in this topic as individual messages.



19 GPIOs

This section contains an overview of the general-purpose input/outputs (GPIOs) included in the TIAGo Base robot.

19.1 ROS API

Note

The node that publishes GPIO data and the services provided for controlling the GPIOs are launched by default on startup.

19.1.1 Published topic

/gpio

Current input states. The information is visualised as an array where the status of each input corresponds to its index in the array. For example, the input0 has its status mapped to the input_state[0]. A status equal to 1 means the input is enabled while 0 means it is disabled.

19.1.2 Available services

  • /mmll/gpio/get_input_state input

Returns the state of a specified input.

root@pmb2-1c:~# rosservice call /mm11/gpio/get_input_state 0
state: 1

  • /mm11/gpio/get_output_state output

Returns the state of a specified output.

root@pmb2-1c:~# rosservice call /mm11/gpio/get_output_state 0
state: 0

  • /mm11/gpio/set_output_state output state

Sets the state of a specified output.

root@pmb2-1c:~# rosservice call /mm11/gpio/set_output_state 0 1


20 LEDs

This section contains an overview of the LEDs included in the TIAGo Base robot.

20.1 ROS API

Note

The services provided for controlling the LEDs are launched by default on startup.

Keep in mind that there is an application running in the TIAGo Base robot that changes the LEDs strips according the robot’s speed. This application must be stopped if any operation with the LED strips is to be performed, using the following command:

~$ pal-stop velocity_led_flow

In order to resume the velocity controlled LED application, the following command should be used:

~$ pal-start velocity_led_flow

20.2 Available services

The following services are used for controlling the LED strips present in TIAGo Base robot. All of them require a port argument that specifies which strip the command will affect. A port of value 0 referes to the left strip and 1 to the right strip. LED strips are composed of pixel LEDs.

To execute these service calls, the user must either be logged on the robot or have pointed the master URI to the robot:

export ROS_MASTER_URI=http://pmb2-1c:11311

Note

Resulting color may be different or not visible at all due to the plastic that covers the LED strips.

20.2.1 /mm1/led/set_strip_color

sets all the pixels in the strip to a color.

arguments: port r g b

r, g and b: refers to the color to be set in RGB scale.

example: rosservice call /mm11/led/set_strip_color 0 255 255 255

20.2.2 /mm1/led/set_strip_pixel_color

Sets one pixel in the strip to a color. pixel is the position of the LED in the strip. r,g and b refers to the color to set in RGB scale.

arguments: port pixel r g b

example: rosservice call /mm11/led/set_strip_pixel_color 0 5 255 0 0

20.2.3 /mm1/led/set_strip_flash

Sets a flashing effect to the LED strip.

arguments: port time period r_1 g_1 b_1 r_2 g_2 b_2

time: the duration of the flash in milliseconds.

period: the time between flashes in milliseconds.

r_1, g_1 and b_1: refers to the color of the animation in RGB scale.

r_2, g_2 and b_2: refers to the background color of the animation in RGB scale.

example: rosservice call /mm11/led/set_strip_animation 0 1 100 5 250 0 0 0 0 255

20.2.4 /mm1/led/set_strip_animation

Sets an animation effect to the LED strip.

arguments: port animation_id param_1 param_2 r_1 g_1 b_1 r_2 g_2 b_2

animation_id: sets the type of animation, 1 for pixels running left, 2 for pixels running right,3 for pixels running forth and back starting from the left and 4 for pixels running forth and back starting from the right.

param_1: the time between effects in milliseconds.

param_2:the distance between animated pixels.

r_1, g_1 and b_1: refers to the color of the animation in RGB scale.

r_2, g_2 and b_2: refers to the background color of the animation in RGB scale.

example: rosservice call /mm11/led/set_strip_animation 0 1 100 5 250 0 0 0 0 255



21 Introspection controller

The introspection controller is a tool used at PAL to serialize and publish data on the real robot that could be recorded and used later for debugging.

21.1 Start the controller

The introspection controller doesn’t use any resource, and it could be activated in parallel with any other controller.

In order to start it run:

ssh pal@pmb2-1c
roslaunch introspection_controller introspection_controller.launch

Once the controller is started it will start publishing all the information on the topic: /introspection_data/full

21.2 Record and reproduce the data

If you want to record the information from your experiment, it can simply be done using rosbag.

ssh pal@pmb2-1c
rosbag record -O NAME_OF_THE_BAG /introspection_data/full

Once you are finished to record your experiment simply close it with Ctrl-C

Then copy this file in your development PC

ssh pal@pmb2-1c
scp -C NAME_OF_THE_BAG.bag pal@development:PATH_TO_SAVE_IT

Once in your development PC you can reproduce it using PlotJuggler.

rosrun plotjuggler PlotJuggler

Once PlotJuggler is open load the bag: File -> Load Data and select the recorded rosbag.

For more information about PlotJuggler please visit: http://wiki.ros.org/plotjuggler

_images/plotjuggler.png

PlotJuggler

21.3 Record new variables

In order to record new variables it will be necessary to register them inside your code as follows.

#include <pal_statistics/pal_statistics.h>
#include <pal_statistics/pal_statistics_macros.h>
#include <pal_statistics/registration_utils.h>

...

double aux = 0;
pal_statistics::RegistrationsRAII registered_variables_;
REGISTER_VARIABLE("/introspection_data", "example_aux", &aux, &registered_variables_);

Eigen::Vector3d vec(0,0,0);
REGISTER_VARIABLE("/introspection_data", "example_vec_x", &vec[0], &registered_variables_);
REGISTER_VARIABLE("/introspection_data", "example_vec_y", &vec[1], &registered_variables_);
REGISTER_VARIABLE("/introspection_data", "example_vec_z", &vec[2], &registered_variables_);
...

Take in account that the introspection controller only accepts one dimensional variables. For more information please check: https://github.com/pal-robotics/pal_statistics



22 Troubleshooting

22.1 Overview

This chapter presents typical issues that may appear when using TIAGo Base and possible solutions. Please check the tables below carefully before reporting an issue to the support platform in order to find solutions faster.

22.2 Startup issues

Table: Startup issues

#

Issue description

Possible solutions

1.1

The robot does not power up when pressing the On/Off button of the rear panel

Make sure that the electric switch is pressed, i.e. its red light is ON

1.2

After several days of not using the robot does not power up

Make sure that the battery is charged. Connect the charger and try to turn the robot on again after a couple of minutes

1.3

After several deays of not using the robot, the batteries, which were charged, are now empty

If the the electric switch was left pressed it is possible that the batteries have been completely discharged

22.4 Network issues

Table: Network issues

#

Issue description

Possible solutions

3.1

I have configured TIAGo Base’s network to connect to my LAN but it does not work and I have no longer access to the robot via WiFi

Connect a computer to one of the Ethernet ports of the expansion panel and open a web browser to connect to http://10.68.0.1:8080 to have access to the WebCommander. Check on the Network tab if the configuration is OK.

3.2

I have applied on TIAGo Base a new network configuration but after rebooting the robot the changes made have been reverted

To save permanently the new network configuration make sure to press ’Save’ and ’Confirm’ after pressing ’Apply change’. Otherwise the network configuration changes are not save permanently.

22.5 Gazebo issues

Table: Gazebo issues

#

Issue description

Possible solutions

4.1

If you are using a computer with a non-dedicated GPU and run into issues with the lasers in simulation

You would need to change this environment variable before launching the simulation: export LIBGL_ALWAYS_SOFTWARE=1


23 Customer service

23.1 Support portal

All communication between customers and PAL Robotics is made using tickets in a helpdesk software.

This web system can be found at http://support.pal-robotics.com. The next figure shows the initial page of the site.

New accounts will be created on request by PAL Robotics.

PAL Robotics support website

Figure: PAL Robotics support website

Once the customer has entered the system (Figure: Helpdesk), two tabs can be seen: Solutions and Tickets.

The Solution section contains FAQs and News from PAL Robotics.

The Tickets section contains the history of all tickets the customer has created.

fig:Helpdesk

Figure: Helpdesk

The next figure shows the ticket creation webpage.

Ticket creation

Figure: Ticket creation

23.2 Remote support

A technician from PAL Robotics can give remote support. This remote support is disabled by default, so the customer has to activate it manually. If the robot needs to be rebooted, the customer has to activate the remote support after each reboot because it is not persistent.

The robot connects to PAL’s remote support system using the command remoteAssitanceConnect:

root@pmb2-1c:~# remoteAssistanceConnect ipAddress port

Using an issue in the support portal, the PAL technician will provide the IP address and port the customer has to use.

24 Add-Ons

Additional information on how to use and communicate with the different add-ons available for TIAGo Base robot will be detailed in this section. This capabilities are dependent on the specific hardware configuration of the robot.

24.1 Actuated Conveyor

The actuated conveyor add-on adds an actuated conveyor belt to the TIAGo Base robot, which allows automatic load transfer. The conveyor belt height can be manually regulated to fit different structures, while the space below the belt can be used for additional manual load.

_images/actuated_conveyor.png

Figure: The TIAGo Base with actuated conveyor add-on.


This hardware add-on is controlled via the run_conveyor action. It can be accesed on:

/run_conveyor (conveyor_controller_msgs/RunConveyorActionGoal)

This action has 3 parameters:

  • duration - Time - time that the action will last. If set to 0 the conveyor will be running until the action iscanceled.

  • speed - uint8 - 0, 1 or 2 for slowest speed, medium speed, and high speed; respectively.

  • reverse - bool - Set to True to reverse the direction of the conveyor (the belt will move front to back), by default is set to False (belt moves back to front).

Cancelling the action stops the conveyor regardless of the remaining time.

Example: (Reverse motion at highest speed during 5 seconds)

rostopic pub /run_conveyor/goal conveyor_controller_msgs/RunConveyorActionGoal
    header:
        seq: 0
        stamp:
            secs: 0
            nsecs: 0
        frame id: ''
    goal_id:
        stamp:
            secs: 0
            nsecs: 0
        id: ''
    goal:
        duration:
            data:
                secs: 5
                nsecs: 0
        speed: 2
        reverse: true

24.2 Vision enabled Stackable boxes

The Vision enabled Stackable boxes add-on equips TIAGo Base with a space for manual stacking of European boxes (35.6 x 25.6 x 22.2 cm). It also adds 2 depth cameras to increase safety and improve obstacle avoidance, as well as an additional push button at the top of the add-on to improve the usuablity of the robot.

_images/stackable_boxes.png

Figure: The TIAGo Base with Vision enabled Stackable boxes add-on.


Pressing the button on the top changes the value of the Input PIN 0 of the robot’s board. The state of this PIN can be accessed by checking the /gpio topic. The value of the Input PINs is reported in the input_state field, which contains an array of ordered states (position 0 corresponds to Input 0). While the button is pressed the value will be 0, otherwise, it will be 1.