Payload SDK for Python

Overview

The Gremsy Payload SDK provides a comprehensive Python interface for controlling and communicating with Gremsy payload systems. This SDK enables developers to integrate payload functionality into their applications with support for camera control, gimbal operations, GPS data transmission, and advanced features like object tracking.

Supported Hardware

• Computing Platforms:

  • Ubuntu PC (x86_64)

  • NVIDIA Jetson (aarch64)

  • Raspberry Pi

  • Qualcomm RB5165

Supported Payloads

Payload Model	Minimum Firmware Version	Status
VIO Payload	v2.0.0 or higher	✅ Fully Supported
ZIO Payload	v2.0.0 or higher	⚠️ Limited Support
GHardron Payload	v2.0.0 or higher	⚠️ Limited Support

Python Compatibility: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12

Installation

1. Clone the Repository

git clone -b payloadsdk_v3_python3 https://github.com/Gremsy/PayloadSdk.git
cd pymavlink

2. Setup Python Environment

Option A: Using Conda (Recommended)

conda create -n payloadsdk_env python=3.8
conda activate payloadsdk_env
pip install -r requirements.txt

Option B: Using Virtual Environment

python3 -m venv payloadsdk_env
source payloadsdk_env/bin/activate  # On Windows: payloadsdk_env\Scripts\activate
pip install -r requirements.txt

Project Structure

pymavlink/
├── examples/           # Example applications and use cases
├── libs/              # Core SDK libraries
│   ├── config.py      # Centralized configuration management
│   ├── payload_sdk.py # Main SDK interface
│   └── payload_define.py # Constants and enumerations
├── requirements.txt   # Python dependencies
├── PayloadSDK.md     # Detailed API documentation
└── README.md         # This file

Configuration

All configuration is centralized in libs/config.py. The SDK automatically sets up the environment when imported.

Connection Configuration

UDP Connection (Default)

class ConnectionConfig:
    CONTROL_METHOD = CONTROL_UDP
    UDP_IP_TARGET = "192.168.55.1"      # Change to your payload's IP
    UDP_PORT_TARGET = 14566             # Standard MAVLink port

UART/Serial Connection

class ConnectionConfig:
    CONTROL_METHOD = CONTROL_UART
    UART_PORT = "/dev/ttyUSB0"          # Linux: /dev/ttyUSB0, Windows: COM3
    UART_BAUDRATE = 115200              # Standard baudrate

MAVLink Protocol Configuration

The SDK uses MAVLink 2.0 by default for enhanced features and security:

class EnvironmentConfig:
    @staticmethod
    def setup_mavlink_environment():
        os.environ['MAVLINK20'] = '1'    # MAVLink 2.0 (recommended)
        os.environ['MAVLINK_DIALECT'] = 'ardupilotmega'

Advanced Configuration Options

• Camera Settings: Zoom/focus types, capture intervals, recording parameters

• Gimbal Settings: Angle limits, movement speeds, calibration parameters

• Communication: Timeouts, message rates, heartbeat intervals

• Debug Options: Logging levels, error reporting, diagnostic output

Quick Start

Basic Connection Test

python3 examples/check_connect.py

Example Usage in Your Code

#!/usr/bin/env python3
import sys
import os

# Add SDK to path
sys.path.append(os.path.join(os.path.dirname(__file__), 'libs'))
from config import config
from payload_sdk import PayloadSdkInterface

# Create and initialize payload interface
payload = PayloadSdkInterface()

# Establish connection
if not payload.sdkInitConnection():
    print("Failed to initialize connection")
    sys.exit(1)

# Check payload connectivity
if not payload.checkPayloadConnection():
    print("Failed to connect to payload")
    sys.exit(1)

print("✅ Successfully connected to payload!")

# Your application logic here...

# Clean shutdown
payload.sdkQuit()

Example Applications

Camera Control

# Basic camera settings
python3 examples/camera_change_settings.py

# Image capture
python3 examples/camera_eo_capture_image.py

# Video recording
python3 examples/camera_eo_record_video.py

# Zoom control
python3 examples/camera_do_setzoom_individual.py

# Time-lapse photography
python3 examples/camera_time_lapse_photography.py

# IR camera controls
python3 examples/camera_ir_set_palette.py
python3 examples/camera_ir_capture_image.py

Gimbal Operations

# Speed-based movement
python3 examples/gimbal_move_speed.py

# Angle-based positioning
python3 examples/gimbal_move_angle.py

# Gimbal calibration
python3 examples/gimbal_do_calib.py

# Settings management
python3 examples/gimbal_change_settings.py

Advanced Features

# Object detection
python3 examples/payload_do_object_detection.py

# Object tracking
python3 examples/payload_do_object_tracking.py

# GPS data transmission
python3 examples/payload_set_gps.py

# Media file management
python3 examples/payload_download_media_files.py

# System time synchronization
python3 examples/payload_set_system_time.py

Key Features

🔧 Centralized Configuration

• Single configuration file for all settings

• Automatic environment setup

• Parameter validation and error checking

• Easy IP/port changes without code modification

🔗 Robust Connection Management

• Automatic connection detection and validation

• Support for both UDP and UART connections

• Connection timeout and retry mechanisms

• Graceful error handling and recovery

📷 Comprehensive Camera Control

• Image capture and video recording

• Zoom and focus control (EO and IR cameras)

• Camera mode switching and settings management

• Storage management and media download

🎯 Advanced Gimbal Control

• Precise angle and speed-based movement

• Multiple control modes (lock, follow, mapping)

• Automatic calibration procedures

• Real-time attitude feedback

🤖 AI-Powered Features

• Object detection and tracking

• Smart tracking with bounding box control

• Real-time tracking status feedback

📡 Data Integration

• GPS position transmission

• System time synchronization

• Custom parameter streaming

• Real-time telemetry data

Troubleshooting

Connection Issues

UDP Connection Problems:

# Check network connectivity
ping 192.168.55.1

# Verify firewall settings
sudo ufw allow 14566/udp

# Test with different IP if needed
# Update libs/config.py -> ConnectionConfig.UDP_IP_TARGET

UART Connection Problems:

# Check port availability
ls /dev/tty*

# Fix permissions (Linux)
sudo chmod 666 /dev/ttyUSB0
# or add user to dialout group
sudo usermod -a -G dialout $USER

# Verify baudrate compatibility
# Update libs/config.py -> ConnectionConfig.UART_BAUDRATE

Common Error Solutions

Error	Solution
ModuleNotFoundError: No module named 'config'	Ensure you're running from correct directory and libs path is set
AttributeError: 'NoneType' object has no attribute 'recv_match'	Connection failed - check network/serial connection
No payload detected after X seconds	Verify payload is powered on and network is accessible
Permission denied: '/dev/ttyUSB0'	Add user to dialout group or use sudo

Debug Mode

Enable detailed logging by modifying libs/config.py:

class DebugConfig:
    ENABLE_DEBUG = True
    ENABLE_INFO = True

API Documentation

For detailed API documentation, function parameters, and advanced usage examples, see:

• PayloadSDK.md - Complete API reference

• examples/ - Working code examples

• libs/config.py - Configuration options

Support and Contact

• Technical Documentation: See PayloadSDK.md for detailed API reference

• Example Code: Check the examples/ directory for implementation patterns

• Configuration Help: Review libs/config.py for all available settings

• Issue Reporting: Contact Gremsy technical support team

Version Information

• SDK Version: 3.0.0_build.27052025

• MAVLink Protocol: 2.0 (with 1.0 compatibility)

• Supported Software: v2.0.0 and higher