Cerulean Companion

Companion app to enable Cerulean Sonar devices to share their data with other hosts and services, such as QGroundControl or a BlueROV2.

Installing a Release

Head over to Releases and download the appropriate version for your OS.

For now, the app is CLI only. Use terminal on Linux/Mac and CMD on Windows to execute the program. Follow the help prompt to set the flags appropriately for your configuration.

For Linux, you’ll need to enable execution of the file with your file manager, or by running chmod +x cerulean-companion . In Windows 10, you may need to approve a SmartScreen dialog.

$ ./cerulean-companion
usage: cerulean-companion [-h] [-r /dev/ttyUSB#] [-g /dev/ttyXXX#] [-e localhost:port]
                  [-m host:port] [--log level]

Getting ROVL and GPS data into QGroundControl on a BlueROV2

Requirements

ROVL Receiver and Transmitter
USB GPS Such as this
QGroundControl >= 3.5.2
BlueROV2 with a recent version of Companion How to Update

Start and Configure QGroundControl

Because of the way QGroundControl handles USB devices, we’ll have to disable its auto-connect functionality for everything except UDP. If we don’t do this, the Cerulean Companion (or anything else) will be unable to interact with serial ports while QGroundControl is open. This won’t have any effect on the way a BlueROV2 operates.

We also want to switch the NMEA GPS Device to “UDP Port” and leave it on 14401.

You can find these settings in the Q Menu of QGroundControl, and your settings should look like this:

qgc_settings

Plug Everything In

ROVL Receiver
USB GPS
Power on ROV

Determine the Correct Ports

You’ll need to figure out the correct ports for the ROVL Receiver and GPS on your system. This can be accomplished a few ways:

Run cerulean-companion in a terminal with no settings, and it will attempt to help you find your ports
Use Device Manager on Windows

At this point, you may want to allow your GPS some time to acquire a lock, and pivot the ROVL Receiver around so it can initialize.

Sync the ROVL Receiver and Transmitter

This is a good time to sync the ROVL Receiver and Transmitter using the supplied software, or by sending it D0 when the devices are touching.

On Linux:

$ sudo -s
# echo 'D0' > /dev/ttyUSB0

Run the app

Run cerulean-companion in a terminal with the settings you determined in the previous step, it should look something like this:

$ ./cerulean-companion -r /dev/ttyUSB0 -g /dev/ttyACM0 -e localhost:14401 -m 192.168.2.2:27000

By default, the BlueROV2 listens for position information at 192.168.2.2:27000

QGroundControl listens for position information at localhost:14401 if enabled in settings

If all has gone well, you should see your location as well as your ROV in QGroundControl’s map display:

qgc_map

If you have issues, check the output of cerulean-companion in the terminal

Advanced Usage

Installing From PIP

With python3.6 or later, the following command will install all dependencies locally:

pip3 install --user --force-reinstall git+https://github.com/CeruleanSonar/Cerulean-Companion.git

Note the --force-reinstall flag. This is required if you already have pynmea2 installed to get our custom modified branch.

You should then be able to run the command:

$ cerulean-companion
usage: cerulean-companion [-h] [-r /dev/ttyUSB#] [-g /dev/ttyXXX#] [-e localhost:port]
                  [-m host:port] [--log level]
cerulean-companion: error: GPS and USBL devices must be specified

Serial devices detected:
  /dev/cu.Bluetooth-Incoming-Port - n/a
  /dev/cu.DansCans-SPPDev - n/a

Building for distribution:

To package it up for consumption on another machine:

git clone https://github.com/CeruleanSonar/Cerulean-Companion.git
cd Cerulean-Companion
pip3 install pyinstaller ./ -t build
env PYTHONPATH="build" python3 -m PyInstaller cerulean-companion.spec

You will find the executable file in the dist subfolder.