GokHAS was developed as an undergraduate capstone project, featuring a custom two-axis turret integrated with an Airsoft system. A GUI-based centralized management interface provides a robust software architecture for target acquisition and engagement. On the embedded side, an STM32 microcontroller handles real-time control and telemetry over UART communication. This end-to-end design demonstrates seamless coordination between high-level command software and low-level embedded hardware.
The GokHAS system features a modern PyQt6-based interface with dual theme support:
| Light Theme | Dark Theme |
|---|---|
 |
 |
Advanced control interface with real-time camera feed, joint controls, and comprehensive system monitoring
The GokHAS system consists of three main ROS packages:
- gokhas_perception - Computer vision and perception stack for target detection and tracking using YOLOv8
- gokhas_communication - Bidirectional UART communication interface with STM32 microcontroller
- gokhas_interface - Advanced PyQt6-based GUI with real-time calibration and control system
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ GUI Interface │◄──►│ ROS Messages │◄──►│ Perception │
│ (gokhas_ │ │ (gokhas_commu- │ │ (gokhas_per- │
│ interface) │ │ nication) │ │ ception) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ │ │
v v v
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ PyQt6 │ │ STM32 MCU │ │ Camera/Sensors │
│ GUI │ │ (UART Comm) │ │ (ZED Camera) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
- Operating System: Ubuntu 20.04 LTS
- ROS Version: ROS Noetic (must be installed and sourced)
- Python: 3.8+ (included with Ubuntu 20.04)
- Hardware: NVIDIA GPU (recommended for ZED SDK)
- Camera: ZED Stereo Camera (optional - can run in simulation)
- Microcontroller: STM32 with UART communication (optional - can run in simulation)
- Actuators: Two-axis servo/stepper motor system
- Mechanism: Airsoft firing system
- Ensure ROS Noetic is installed and sourced:
# Check if ROS is sourced
echo $ROS_DISTRO # Should output: noetic
# If ROS is not installed, install it first:
# Follow: http://wiki.ros.org/noetic/Installation/Ubuntu
# Ensure ROS is sourced in your .bashrc
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc- Create your catkin workspace:
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src✅ Streamlined Setup: All other dependencies (system packages, Python libraries, ROS packages) will be automatically installed using the provided installation scripts. No manual dependency installation required!
The GokHAS project provides automated installation scripts that handle all dependencies and setup:
- Clone the repository:
cd ~/catkin_ws/src
git clone <repository-url> gokhas_project
cd gokhas_project- Run the main installation script:
# Install all dependencies (system packages, ROS packages, Python packages)
./install.sh- Install ZED SDK (if using ZED camera):
# Run ZED SDK installer
./install_zed_sdk.sh- Build the workspace:
cd ~/catkin_ws
catkin_make
# or if you prefer catkin build:
# catkin build- Source the workspace:
source ~/catkin_ws/devel/setup.bashIf you prefer manual installation or encounter issues with the automated scripts:
Click to expand manual installation steps
- Clone the repository:
cd ~/catkin_ws/src
git clone <repository-url> gokhas_project- Install system dependencies:
sudo apt-get update
sudo apt-get install -y python3-pip python3-dev build-essential cmake git pkg-config- Install Python dependencies:
# PyQt6 for interface
pip3 install PyQt6 pyserial
# Computer vision
pip3 install opencv-python
# Install perception requirements
cd ~/catkin_ws/src/gokhas_project/gokhas_perception
pip3 install -r requirements.txt
# Additional ROS Python packages
pip3 install rospkg pyyaml catkin_pkg empy defusedxml netifaces- Install ROS dependencies:
cd ~/catkin_ws
rosdep update
rosdep install --from-paths src --ignore-src -r -y- Install ZED SDK (optional for camera):
# Download from https://www.stereolabs.com/developers/release/
# Or use our automated installer:
cd ~/catkin_ws/src/gokhas_project
./install_zed_sdk.sh- Build and source:
cd ~/catkin_ws
catkin_make
source ~/catkin_ws/devel/setup.bash-
install.sh: Main installer that handles:- System package dependencies (build-essential, cmake, etc.)
- ROS package dependencies via rosdep
- Python packages (PyQt6, OpenCV, perception requirements)
- GPG key fixes for ROS repositories
- Installation verification
-
install_zed_sdk.sh: ZED SDK installer that:- Downloads ZED SDK from Google Drive
- Handles Ubuntu 20.04 compatibility
- Installs CUDA dependencies if needed
- Configures ZED ROS wrapper dependencies
Common Installation Issues
ROS GPG Key Errors:
# If you see GPG key errors during installation:
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys F42ED6FBAB17C654
sudo apt-get updatePyQt6 Installation Issues:
# If PyQt6 installation fails:
sudo apt-get install python3-pyqt6
# or
pip3 install --upgrade pip
pip3 install PyQt6Permission Errors:
# Never run the install scripts with sudo
# If you get permission errors, fix ownership:
sudo chown -R $USER:$USER ~/catkin_wsZED SDK Issues:
- Ensure NVIDIA drivers are installed:
nvidia-smi - Check CUDA compatibility with your GPU
- ZED SDK requires Ubuntu 20.04 or compatible
Build Errors:
# Clean and rebuild if you encounter build issues:
cd ~/catkin_ws
catkin clean # or rm -rf build/ devel/
catkin_makeThe GokHAS system uses a delayed launch sequence for proper component initialization:
# Start all components with proper timing
roslaunch gokhas_interface gokhas_interface.launchThis will launch:
- t=0s: PyQt6 Interface (immediate startup)
- t=1s: UART Communication system
- t=2s: ZED Camera wrapper
- t=3s: YOLOv8 Perception/Tracker
Interface only:
roslaunch gokhas_interface gokhas_interface.launchPerception only:
roslaunch gokhas_perception tracker.launchCommunication only:
roslaunch gokhas_communication communication.launchZED Camera only:
roslaunch zed_wrapper zedm.launchTo run without hardware (STM32, ZED camera):
# Edit config/params.yaml
# Set: stm32/simulation_mode: true
roslaunch gokhas_interface gokhas_interface.launchPurpose: Computer vision and perception stack for target detection and tracking
Key Features:
- YOLOv8-based object detection and segmentation
- Real-time 3D point cloud processing
- Advanced target tracking with multiple algorithms
- 2D/3D bounding box generation
- Custom message types for detection data
Nodes:
tracker_node- Real-time 2D object detection and trackingtracker_with_cloud_node- 3D object detection with LiDAR integration
Custom Messages:
Detection2D- 2D bounding box detectionDetection2DArray- Array of 2D detectionsYoloResult- YOLO detection results with segmentation masks
Dependencies:
- Ultralytics YOLO models
- OpenCV (cv_bridge)
- PCL (pcl_ros)
- Image processing (image_transport, image_geometry)
- Vision messages (vision_msgs)
Purpose: Bidirectional UART communication interface with STM32 microcontroller
Key Features:
- Real-time UART communication (100 Hz)
- Compact 8-byte packet protocol
- Trigger-based transmission system
- Joint position and speed control
- Airsoft system control and feedback
- Simulation mode for testing
- Fault-tolerant communication with error handling
Message Types:
ControlMessage- Communication and calibration control (2 bytes)JointMessage- Joint and airsoft control (6 bytes)
Topics:
/control_topic- Control and calibration commands/joint_command_topic- Joint movement commands
Dependencies:
- Python serial library
- ROS Python (rospy)
- Custom message generation
Purpose: Advanced PyQt6-based GUI with real-time calibration and control system
Key Features:
- Enhanced Calibration System:
- STM32 response-based calibration (no fixed timers)
- Visual feedback: Default → Processing (Yellow/Pulsing) → Completed (Green)
- Timeout handling (15s) for non-responsive hardware
- Prevention of simultaneous calibrations
- Real-time Control:
- Manual/autonomous mode switching
- Individual joint control with position (-135° to +135°) and power (0-100%)
- Live camera feed display with YOLOv8 detection overlay
- Advanced UI:
- Dynamic theme system (Light/Dark)
- Comprehensive logging panel with timestamps
- Configuration management via ROS parameters
- Responsive design with status-based color coding
- Communication:
- ROS Bridge for seamless topic integration
- Connection monitoring and status reporting
- Safe shutdown with resource cleanup
GUI Screenshots:
Light Theme Interface:
Dark Theme Interface:
The interface features a modern, responsive design with real-time camera feed, comprehensive control panels, and dynamic status indicators. The dual-theme system provides optimal visibility in different lighting conditions.
Configuration:
- Centralized parameter system in
config/params.yaml - Simulation/real hardware mode switching
- Configurable timeouts and delays
Interface Features:
- Real-time Camera Feed: Live video stream with YOLOv8 detection overlays
- Joint Control Panel: Precise position (-135° to +135°) and power (0-100%) control
- System Status: Visual indicators for communication, calibration, and operation modes
- Dual Theme Support: Light and dark themes for optimal visibility
- Comprehensive Logging: Timestamped system events and debug information
- Safety Features: Emergency stops, timeout handling, and state validation
Dependencies:
- PyQt6 framework
- ROS integration (rospy)
- OpenCV for image processing
- Image processing for display
- Custom message handling
roslaunch zed_wrapper zed2.launchroslaunch gokhas_perception perception.launchroslaunch gokhas_communication communication.launchroslaunch gokhas_interface interface.launchroslaunch gokhas_project full_system.launchEdit camera parameters in:
gokhas_perception/config/camera_params.yaml
Configure YOLO detection settings:
gokhas_perception/config/detection_params.yaml
Set UART and communication parameters:
gokhas_communication/config/comm_params.yaml
/gokhas/detections- Detection results/gokhas/target_position- Target coordinates/gokhas/system_status- System health status
/camera/image_raw- Camera feed/camera/depth/points- Point cloud data/gokhas/control_commands- Manual control inputs
/gokhas/set_mode- Switch between manual/auto modes/gokhas/calibrate- System calibration/gokhas/emergency_stop- Emergency shutdown
After adding new message files:
catkin build gokhas_perception
catkin build gokhas_communicationcatkin_make run_tests- Follow ROS coding standards
- Use meaningful variable names
- Document all public functions
- Add appropriate error handling
-
Camera not detected:
- Check USB connections
- Verify ZED SDK installation
- Check camera permissions
-
Communication timeout:
- Verify STM32 connection
- Check UART settings
- Ensure correct baud rate
-
GUI not responding:
- Check PyQt6 installation
- Verify ROS node connections
- Check message dependencies
# Check node status
rosnode list
rosnode info /gokhas_perception
# Monitor topics
rostopic echo /gokhas/detections
rostopic hz /camera/image_raw
# View system graph
rosrun rqt_graph rqt_graph- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- Ahmet Ceyhun Bilir - Lead Developer - ahmetceyhunbilir16@gmail.com
- Beyza Meltem Amanet - Communication Module - meltem.aman@gmail.com
- Bachelor's thesis project
- ROS community for excellent documentation
- OpenCV and PCL communities
- Stereolabs for ZED SDK support
This project is licensed under the MIT License - see the details below.
Copyright (c) 2025 Ahmet Ceyhun Bilir
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
This project is actively developed as part of a bachelor's thesis. Current focus areas:
- Improving detection accuracy
- Enhancing real-time performance
- Expanding GUI functionality
- Adding safety features
For questions or support, please contact the maintainers or create an issue in the repository.