A comprehensive solution for underwater robotic teleoperation, sensor integration, and wireless communication using ROS2, Docker, Python sensor drivers, and acoustic modems.
Developed at the Research Center in Robotics and Underwater Technologies (CIRTESU), Universitat Jaume I (UJI), Castellón, Spain.
The Pez project enables seamless remote operation and control of an underwater robotic fish by integrating:
- ROS2 Humble for robust robotics control
- Docker for simplified deployment and reproducibility
- Bluerobotics Navigator for actuator control (servos, camera, electromagnet)
- Real-time visualization with RQT and PlotJuggler
- Integrated environmental sensing (temperature, pressure, depth)
- Custom acoustic communication protocols for remote command transmission
This project facilitates both simulation-based testing and real-world robotic fish teleoperation, designed for use in educational, research, or practical underwater inspection and monitoring scenarios.
- ROS2 Humble
- Docker and Docker Compose
- Bluerobotics Navigator
- RQT
- PlotJuggler
- tsys01-python
- ms5837-python
- smbus2
+---------------------------+ +---------------------------+ +---------------------------+
| Fish-side (Pi 4) | <---> | Acoustic Comms | <---> | Host-side |
|---------------------------| |---------------------------| |---------------------------|
| - ROS2 Humble (Docker) | | - Custom Packet Protocol | | - ROS2 Humble (Docker) |
| - Actuator Control | | (Packet A, B, future C) | | - Joystick Teleoperation |
| - Sensor Data Publishing | | | | - Real-time Visualization |
| • TSYS01 Temperature | | | | • Sensor Data Reception |
| • MS5837 Pressure/Depth | | | | |
+---------------------------+ +---------------------------+ +---------------------------+
Copy the compose file from
pez_docker/pez to the
Raspberry Pi and start one of the modes. The compose file pulls the tagged
image automatically:
# Clone and copy compose file
git clone https://github.com/mpuigsari/Pez
cp pez_ros/pez_docker/pez/docker-compose.yml .
# Interactive shell for maintenance
docker compose run pez-dev
# Tele‑op over umbilical cable
docker compose up pez-cable
# Tele‑op with acoustic comms
docker compose up pez-commsThe same container image is reused – the first word passed to the entrypoint
(dev, cable or comms) selects the launch behaviour.
Clone the repository, copy the compose file from
pez_docker/host and start the
host container (mapuigsari/pez:core-amd64) in the desired mode:
# Clone and copy compose file
git clone https://github.com/mpuigsari/Pez
cp Pez/pez_ros/pez_docker/host/docker-compose.yml .
# Short-lived dev shell
docker compose run pez-dev
# USB/serial tether
docker compose up pez-cable
# Radio/MAVLink comms
docker compose up pez-commsPlug in your joystick (and any serial adapters) before starting. See host Docker README for details.
git clone https://github.com/mpuigsari/Pez
cd Pez/pez_ros/pez_humble/pez_ws
colcon build
source install/setup.bashPez
├── pez_ros/
│ ├── pez_docker/ # Docker setups for fish, host and buoy
│ ├── pez_humble/ # ROS 2 packages shared across all platforms
│ └── pez_noetic(discarded)/
├── blueos_ros/ # ROS Noetic workspace for BlueROV2 teleop
└── README.md
ROS 2 Humble image for the onboard Raspberry Pi. It exposes Navigator-driven PWM control and publishes sensor data.
See pez_docker for all container images.
Provides ROS 2 Humble with joystick support, visualization tools and optional acoustic modem bridge. The container tag is mapuigsari/pez:core-amd64.
Provides ROS 2 Humble image for buoy to serve as a bridge between host and accoustic modem. The container tag is mapuigsari/pez:comms-arm64.
pez_core: Teleoperation, actuator control, and sensor nodes.pez_comms: YAML-driven serial communication with plugin extensibility.pez_joy: Joystick teleoperation package with snapshot logging and launch helpers.
Custom lightweight packets are defined in pez_comms/core/packet_def.py:
- Packet40 – 32‑bit velocity + service field packet for ROS 2 teleop.
- PacketB_Full – 32‑bit service command with CRC protection.
- PacketBlueRov – 32‑bit twist packet for BlueROV2 control.
These allow a Noetic vehicle and a Humble host to communicate seamlessly over the acoustic modem.
- Packet C Implementation – extended packet carrying 6‑DoF pose data
License: This project is licensed under the GNU General Public License v3.0.
See the LICENSE file for details.
👤 Author
Max Puig Bachelor in Robotics Intelligence – Universitat Jaume I (2021–2025)
This project forms part of my academic portfolio, demonstrating integration of ROS2, Docker, sensor fusion, and real-time communication for robotic teleoperation.