(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Getting Started with ECHO ONE

Description: Using the Toposens stack to connect to and display data from Toposens 3D ultrasonic sensors

Keywords: Toposens, ECHO ONE, TS3, ultrasound

Tutorial Level: BEGINNER

This tutorial assumes that either Ubuntu 18.04 with ROS Melodic or Ubuntu 20.04 with ROS Noetic is used.

Install Driver

We provide three different ways of installing the Toposens ROS Software Stack. In the following we provide the details of how to set up each of those.

Docker Image from DockerHub

For the purpose of conveniently running the Toposens application we provide Docker images. This allows execution of the toposens ROS-Stack without any ROS installation, package installation or compiling being necessary. (Tested with Ubuntu 20.04 focal)

As a requirement, you need to have Docker installed on your system: https://www.docker.com/.

The Docker runtime images can be pulled and run from https://hub.docker.com/u/toposens as follows: (Make sure to have your Toposens sensor connected to the given port)

# Headless mode ECHO ONE:
$ docker run -it --net=host --env DRIVER=ECHO_ONE --env COM_INTERFACE=CAN --env GUI_ENABLE=false --cap-add=NET_ADMIN --env USER=toposens toposens/noetic

# Headless mode TS3:
$ docker run --device=/dev/ttyUSB0 -it --env GUI_ENABLE=false --env DRIVER=TS3 --env COM_INTERFACE=UART --net=host --env USER=toposens toposens/noetic

# Execution with RViz GUI ECHO ONE:
$ xhost +local:root; docker run -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" --env GUI_ENABLE=true --cap-add=NET_ADMIN --env DRIVER=ECHO_ONE --env COM_INTERFACE=CAN --net=host --env USER=toposens --privileged toposens/noetic; xhost -local:root

# Execution with RViz GUI TS3:
$ xhost +local:root; docker run --device=/dev/ttyUSB0 -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" --env GUI_ENABLE=true --env DRIVER=TS3 --env COM_INTERFACE=UART --net=host --env USER=toposens --privileged toposens/noetic; xhost -local:root

Install Binaries from Ubuntu Repository

Depending on the ROS distribution that you are using, install the binaries of the Toposens ROS packages with the following command:

sudo apt install ros-<distro>-toposens

E.g. if you are using ROS Noetic, it would look like this:

sudo apt install ros-noetic-toposens

Build Driver from Source

As an alternative to installing the binaries, you could also compile the packages from source. In order to follow the steps below, you need to have a catkin workspace and catkin tools installed. Check these links if you need assistance in doing so:

Then you are ready to clone the toposens ROS repository into the src/ folder of your catkin workspace:

cd ~/catkin_ws/src
git clone https://gitlab.com/toposens/public/ros-packages.git

Use rosdep to install missing dependencies (this will also install the toposens-sensory-library package):

rosdep init
rosdep update
rosdep install -y --from-paths ~/catkin_ws/src/ros-packages/ --ignore-src

In your catkin workspace build the package by using catkin build:

cd ~/catkin_ws
catkin build toposens

Source your build space:

source ~/catkin_ws/devel/setup.bash

This needs to be done in every new terminal or you can add this command to your bashrc for it to be executed automatically when opening a new terminal window.

Connect ECHO ONE Sensor with CAN

The README of the toposens_echo_driver package provides instructions on how to enable the CAN interface for Ubuntu to be used with ROS.

Visualize Data

Point data from the ECHO ONE is published on two topics:

The utility of these topics is further explored in the following sections.

View Raw Stream

The toposens_echo_driver_node translates the sensor data into custom toposens_msgs/TsScan messages.

Launch the driver node to read data from ECHO ONE. If the interface obtained in the previous step is the default (can0 for ECHO ONE), then the launch argument can_device can be omitted:

roslaunch toposens_echo_driver driver.launch can_device:=can0

The sensor data is published to the the topic /ts_scans. View the incoming scans with:

rostopic echo /ts_scans

TsScan

View Pointcloud in RViz

The ts_cloud_node translates the messages of type toposens_msgs/TsScan into messages of type sensor_msgs/PointCloud2.

Due to the specular reflection behavior of ultrasound, the surface normal of the detected object can be represented by a vector pointing from the detected point towards the sensor’s position while the point was recorded. This normal vector is added to the PointCloud representation. For a more detailed explanation of the physics behind Toposens sensors see Physics of 3D Ultrasonic Sensors.

The driver node as well as the pointcloud node are launched from within one launch-file (as before, interface defaults to can0 and can be omitted in this case):

roslaunch toposens_bringup echo_one.launch can_device:=can0

For also launching rqt_reconfigure set the launch argument:

roslaunch toposens_bringup echo_one.launch <launch_args> launch_rqt_reconfigure:=true

The pointcloud is visualized in RViz:

RVizPointcloud

In order to visualize the surface normal vectors, run the launch-file with the corresponding argument:

roslaunch toposens_bringup echo_one.launch lifetime_normals_vis:=1.0

RVizPointcloudNormals

Be aware that in case of a static sensor (i.e. no tf information) the normal vectors are simply pointing towards the sensor at any time.

Reconfigure Parameters

To adjust sensor parameters at runtime, launch the dynamic reconfigure GUI:

rosrun rqt_reconfigure rqt_reconfigure

Make sure roscore and the toposens_echo_driver_node are running before launching the reconfigure gui (roscore is started when using one of the aforementioned roslaunch commands).

Sensor Parameters

There are several parameters that can be dynamically reconfigured in the toposens_echo_driver_node.

DynRecDriver

Variable Name

Description

interface_sensor_id

The ID of the sensor you want to configure. This should be automatically configured to the currently connected sensor. In case of multi sensor setup please specify the ID of the sensor you want to reconfigure first, before adjusting any of the other parameters.

volume

Percentage determining the amplitude of the transducer pulse. Should be set to 100. Reconfiguring requires re-calibration of the sensor!

num_pulses

Defines the number of electrical pulses that the piezo transmitter is stimulated with in every transmission cycle. The higher the number, the louder and longer the emitted signal will be. As a result, increasing the value will detect objects that are further away, decreasing it will increase the sensor's precision in short range. Typically a value of 5 should yield good results. Reconfiguring requires re-calibration of the sensor!

transducer_noise_threshold

Controls the noise filtering of the sensor, i.e. very quiet points are already filtered out in the sensor's processing pipeline. If the value is 0.0 all points from the sensor are passed to ROS, a reasonably good value is 1.0.

transducer_noise_ratio

Sensor signal processing parameter that controls filtering of points on sensor side. A value of 100 disables the filtering and should be used, as this deprecated parameter is replaced with the confidence value of the point clouds which can be used for filtering.

temperature

This parameter defines the temperature that is used for calculating the speed to sound. Its accuracy has an effect on the correct calculation of the distance of objects.

sleep_dur_pulses [experimental]

Adds extra sleep after each measurement.

enable_auto_gain

The sensor amplifies the signal based on distance. This feature dynamically adjusts the amplification given the current signal and tries to avoid clipping of the signal while also amplifying quiet echoes.

near_field_threshold_phase_deviations [experimental]

Parameter used for handling of near field. This is currently deactivated by default, as this will change in upcoming firmware iteration.

Wiki: toposens/Tutorials/Getting Started with ECHO ONE (last edited 2022-05-11 07:33:07 by DennisMaier)