toposens repository

Repository Summary

Checkout URI
VCS Type git
VCS Version master
Last Updated 2019-06-14




pipeline status


ROS packages for working with Toposens 3D ultrasonic sensors:

Developed and tested for ROS Melodic on Ubuntu 18.04 (Bionic) and ROS Kinetic on Ubuntu 16.04 (Xenial) using Toposens TS3 ultrasonic sensor.

1. Setup

For Ubuntu 18.04

For Ubuntu 16.04

2. Build Driver

  • Clone the toposens metapackage into your catkin workspace:

    cd ~/catkin_ws/src

    git clone

  • Use rosdep to install missing dependencies:

    rosdep update

    rosdep install --from-paths ~/catkin_ws/src/ros-packages/ --ignore-src --rosdistro <distro> -y

  • Build the package by using catkin build:

    catkin build toposens

3. Enable Serial Port Permissions

  • Add yourself to the “dialout” group:

    sudo adduser $USER dialout

  • Trigger updated group permissions to take effect:

    newgrp dialout

    Re-login or reboot for the updated group permissions to take effect permanently.

4. Connect TS3 Sensor

  • Connect your Toposens TS3 sensor via the provided FTDI cable to any available USB port on your computer.

  • Obtain the connected terminal ID for the device:

    dmesg | grep "FTDI USB Serial Device"

In this case the terminal ID would be ttyUSB0.

5. Visualize Data

There are three different ways of viewing the data processed by a TS3 sensor. They are explained in the following.

View Raw Stream

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

  • Launch the driver node and start accruing data from a TS3 sensor. Set the corresponding serial port as launch argument (here: /dev/ttyUSB0):

    roslaunch toposens_driver toposens_driver.launch port:=/dev/ttyUSB0

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

    rostopic echo /ts_scans

Visualize Data as Markers

The ts_markers_node translates the messages of type toposens_msgs/TsScan into messages of type visualization_msgs/MarkerArray.

  • The driver node as well as the markers node are launched from within one launch-file:

    roslaunch toposens_markers toposens_markers.launch port:=/dev/ttyUSB0

The markers are visualized in RViz:

View Pointcloud

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

  • The driver node as well as the pointcloud node are launched from within one launch-file:

    roslaunch toposens_pointcloud toposens_cloud.launch port:=/dev/ttyUSB0

The pointcloud is visualized in RViz:

6. Manipulate Parameters

  • To manipulate sensor parameters as well as visualization parameters live in realtime, run in an additional terminal window:

    rosrun rqt_reconfigure rqt_reconfigure

    The ts_driver_node respectively ts_markers_node need to be running for this to work.

Sensor Parameters

There are 6 different parameters that can be changed in the ts_driver_node.

Variable Name Effect
num_pulse Number of ultrasonic pulses emitted by the sensors piezo transducer in every transmission cycle. Increasing the value will detect objects that are further away, decreasing it will increase the precision in short range.
peak_detection_window Kernel size applied on ADC signals for peak detection. Decreasing it will separate multiple objects that are close to each other.
echo_rejection_threshold Minimum amplitude for an echo to be considered valid. Increasing it will ignore more points of smaller intensity.
use_external_temperature If checked uses external temperature value to calibrate speed-of-sound, otherwise use value provided by on-board temperature sensor.
external_temperature Temperature value used to calibrate speed-of-sound. Value is only used if use_external_temperature is checked.
noise_indicator_threshold Normalized noise level on ADC signals to mark processed points as noisy.

Marker Parameters

There are 2 parameters that can be changed in the ts_markers_node.

Variable Name Effect
lifetime Duration for which a marker should remain visible
scale Magnitude for resizing markers equally and simultaneously

7. Turtlebot Integration

Basic mapping of the environment with sensor_msgs/PointCloud2 can be done by orchestrating a TurtelBot3 Burger with a TS3 ultrasonic sensor.


It is assumed that the TurtleBot has already been setup, its onboard computer (Raspberry Pi) is running e.g. ROS Melodic on Ubuntu Mate 18.04 and its IP address is known (<turtlebot_ip>, e.g.

  • In order to access the TurtelBot's onboard computer, use SSH:

    ssh pi@<turtlebot_ip>

  • [TurtelBot] Clone the TurtleBot repositories into your catkin workspace:

    git clone

    git clone

    git clone

    (The latter repository is only needed if the TurtleBot's Laser Distance Sensor shall be used.)

  • [TurtelBot] Use rosdep to install missing dependencies

rosdep update

rosdep install --from-paths ~/catkin_ws/src/ros-packages/ --ignore-src --rosdistro <distro> -y

  • [TurtelBot] Build the packages by making use of catkin_make:

    cd ~/catkin_ws


    or catkin build:

    catkin build turtlebot3_msgs turtlebot3

  • [TurtelBot] Follow sections 2. to 4. of this guide to setup the Toposens TS3 ultrasonic 3D sensor on the TurtelBot. The sensor can be mounted on a TurtleBot3 Burger via the mounting device, as can be seen in the picture below.

  • [Remote PC] Get to know your own IP address (<master_ip>, e.g.

    ifconfig | grep inet

  • [Remote PC] Add necessary parameters to your machine's bashrc (~/.bashrc):

    export TURTLEBOT3_MODEL='burger'
    export ROS_MASTER_URI=http://<master_ip>:11311
    export ROS_HOSTNAME=<master_ip>

Source the bashrc:

`source ~/.bashrc`
  • [TurtelBot] Add necessary parameters in the TurtleBot's bashrc (~/.bashrc):
    export TURTLEBOT3_MODEL='burger'
    export ROS_MASTER_URI=http://<master_ip>:11311
    export ROS_HOSTNAME=<turtlebot_ip>

Source the bashrc:

`source ~/.bashrc`


  • [Remote PC] Launch the pointcloud node:

    roslaunch toposens_pointcloud turtlebot_cloud.launch

  • [TurtleBot] Launch the driver node:

    roslaunch toposens_driver toposens_turtlebot.launch

  • [Remote PC] The TurtleBot can be controlled via the keyboard. For an instruction see the TurtleBot Documentation. It is not required to launch the launchfile for teleoperation. This is already done by the command above.

  • When navigating through a room, the robot is accumulating the TS3 sensor data and mapping the environment via sensor_msgs/PointCloud2. Make sure to set the "Decay Time" of the pointcloud large enogh in RViz.