ROS 2 Node
==========

This node handles the communication of the Neobotix USBoard-USS5.

The USBoard-USS5 node has been tested with:

* ROS 2 Foxy on Ubuntu 20.04, Rolling and Humble on Ubuntu 22.04

Find the code of the ROS node at https://github.com/neobotix/neo_usboard_v2-2.

.. note:: We also have extended our support to Galactic and Humble. Please checkout to the corresponding branch as needed.


Installation
------------

#. Clone the ``neo_usboard_v2-2`` repository into your ros2 workspace source folder::

     cd your_ros2_workspace/src
     git clone https://github.com/neobotix/neo_usboard_v2-2.git

#. Clone ``neo_msgs`` into your catkin workspace source folder::

     git clone https://github.com/neobotix/neo_msgs2.git

#. Fetch the submodules ``vnx-base``, ``pilot-base`` and ``pilot-usboard``::

     cd neo_usboard_v2-2
     git submodule update --init

#. Install ``vnx-base`` onto your system.

   * ROS Foxy::

       sudo dpkg -i vnx-base/x86_64/vnx-base-1.9.3-x86_64-ubuntu-20.04.deb

   * ROS Humble::

       sudo dpkg -i vnx-base/x86_64/vnx-base-1.9.6-x86_64-ubuntu-22.04.deb

#. Compile your workspace::

     cd your_ros2_workspace
     colcon build --symlink-install
     . install/setup.bash


Launch
------

In case of using CAN, the bus needs to be configured first::

  sudo ip link set can0 down
  sudo ip link set can0 type can bitrate 1000000
  sudo ip link set can0 up

To launch the USBoard-USS5 ROS node use::

  ros2 launch neo_usboard_v2 neo_usboard_v2.launch.py


Parameters
----------

The following parameters can be changed according to your needs in ``neo_usboard_v2.yaml``:

============= =============== ==================
Parameter     Value           Note
============= =============== ==================
can_id        1024            Needs to be a multiple of 32.
can_device    None or can0
serial_port   /dev/ttyUSB0
can_baud_rate 1000000 (bit/s) Needs to match what is configured on the board.
update_rate   5 (Hz)          Relevant only in transmit mode "Request", see USBoardV2 GUI.
============= =============== ==================

.. note::
   If ``can_device`` is set, the CAN bus will be used for communication,
   otherwise the serial interface specified in ``serial_port`` is used.

The following parameters can be changed from the parameter server once the ros2 node is executed.

============================ ================ ==================
Parameter                    Value            Note
============================ ================ ==================
low_pass_gain                 1               low pass filter gain (1 = no filtering)
enable_analog_input           false           if to enable reading analog inputs
enable_legacy_format          false           if to use old message format (when transmitting automatically)
enable_can_termination        false           if to connect CAN bus termination resistance on the board
relay_warn_blocked_invert     false           if to invert warn relay output when a sensor is blocked
relay_alarm_blocked_invert    false           if to invert alarm relay output when a sensor is blocked
active_sensors(0 to 15)       true            Active sensors from 1-16
warn_distance(0 to 15)        100 cm          Warning distances of sensors 1-16
alarm_distance(0 to 15)       30 cm           Alarm distances
enable_transmission(0 to 4)   true            if the group transmits in continuous mode
fire_interval_ms              20 ms           time between pulses
sending_sensor                0               index of the sensor which will send the pulse (cross echo mode)
cross_echo_mode               false           if to enable cross echo mode
============================ ================ ==================

Topics
------

The following ROS topics are available:

======================== ======================
Name                     Type
======================== ======================
/usboard_v2/measurements neo_msgs/msg/USBoardV2
/usboard_v2/sensor1      sensor_msgs/msg/Range
/usboard_v2/sensor2      sensor_msgs/msg/Range
...
/usboard_v2/sensor16     sensor_msgs/msg/Range
======================== ======================


Help
----

If you receive the error ``unable to connect to port /dev/ttyUSB0``, run
the following command::

  sudo usermod -a -G dialout $USER

and restart your PC.